You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2026/07/03 22:31:04 UTC
(tinkerpop) branch master updated (020d0d061d -> 92c0d51291)
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
from 020d0d061d Fix flaky test shouldEnableWebSocketSsl CTR.
new 3cefc5c343 tinker-review: edge confidence tags + resilient graph population
new 01790f6b06 tinker-review: agent tools for confidence, removal impact, and callee origin
new e24bd427c6 tinker-review: document evidence.json schema and simplify playbooks
new 62baef164c skills: add DESIGN.md for tinker-review, tinker-dev, tinker-doc
new 4bf44b7802 tinker-review: move removal-ref discovery into Phase 1
new c011cb4024 tinker-review: harmonize SKILL.md phase terminology with DESIGN.md
new 92c0d51291 tinker-review: clarify playbook selection and section roles
The 7 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.skills/tinker-dev/DESIGN.md | 38 +++++
.skills/tinker-doc/DESIGN.md | 33 +++++
.skills/tinker-review/DESIGN.md | 85 ++++++++++++
.skills/tinker-review/SKILL.md | 83 ++++++++---
.skills/tinker-review/playbooks/bug-fix.md | 39 +++---
.skills/tinker-review/playbooks/driver-server.md | 24 ++--
.skills/tinker-review/playbooks/general.md | 16 ++-
.skills/tinker-review/playbooks/glv.md | 28 ++--
.skills/tinker-review/playbooks/grammar.md | 13 +-
.skills/tinker-review/playbooks/new-step.md | 29 ++--
.skills/tinker-review/playbooks/removal.md | 60 ++++++++
.skills/tinker-review/references/interfaces.md | 79 +++++++----
.skills/tinker-review/references/schema.md | 42 +++++-
.skills/tinker-review/scripts/enrichment/api.js | 141 ++++++++++++++++++-
.skills/tinker-review/scripts/enrichment/cli.js | 65 ++++++++-
.../scripts/extraction/tree-sitter.js | 10 +-
.skills/tinker-review/scripts/graph/confidence.js | 85 ++++++++++++
.skills/tinker-review/scripts/graph/externals.js | 87 ++++++++++++
.../scripts/graph/populate-discussions.js | 34 +++--
.skills/tinker-review/scripts/graph/populate.js | 94 ++++++++++++-
.skills/tinker-review/scripts/graph/references.js | 85 ++++++++++++
.../tinker-review/scripts/patterns/architecture.js | 14 +-
.../tinker-review/scripts/patterns/blast-radius.js | 19 +++
.../tinker-review/scripts/patterns/centrality.js | 35 ++++-
.../scripts/patterns/classify-externals.js | 83 +++++++++++
.../scripts/patterns/cluster-analysis.js | 13 ++
.../tinker-review/scripts/patterns/completeness.js | 8 ++
.../scripts/patterns/confidence-audit.js | 154 +++++++++++++++++++++
.../scripts/patterns/coverage-gaps.js | 14 ++
.skills/tinker-review/scripts/patterns/orphans.js | 13 ++
.../tinker-review/scripts/patterns/removal-refs.js | 106 ++++++++++++++
.skills/tinker-review/scripts/renderer/render.js | 46 +++++-
.skills/tinker-review/scripts/review.js | 35 ++++-
33 files changed, 1568 insertions(+), 142 deletions(-)
create mode 100644 .skills/tinker-dev/DESIGN.md
create mode 100644 .skills/tinker-doc/DESIGN.md
create mode 100644 .skills/tinker-review/DESIGN.md
create mode 100644 .skills/tinker-review/playbooks/removal.md
create mode 100644 .skills/tinker-review/scripts/graph/confidence.js
create mode 100644 .skills/tinker-review/scripts/graph/externals.js
create mode 100644 .skills/tinker-review/scripts/graph/references.js
create mode 100644 .skills/tinker-review/scripts/patterns/classify-externals.js
create mode 100644 .skills/tinker-review/scripts/patterns/confidence-audit.js
create mode 100644 .skills/tinker-review/scripts/patterns/removal-refs.js
(tinkerpop) 02/07: tinker-review: agent tools for confidence, removal impact, and callee origin
Posted by sp...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 01790f6b0694adabb90b211263a9b75a582e284c
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Fri Jul 3 11:39:45 2026 -0400
tinker-review: agent tools for confidence, removal impact, and callee origin
listInferred + setEdgeConfidence let the agent verify name-resolved / mapped
edges and re-grade them (promote a confirmed edge to EXTRACTED, downgrade a wrong
one to AMBIGUOUS). listDeleted, listExternalRefs, addReference and a removal.md
playbook surface lingering references to removed code. classifyExternals tags
external-callee stubs library/project/unresolved so centrality drops library
noise. Playbooks now point at these real commands.
Assisted-by: Claude Code:claude-opus-4-8
---
.skills/tinker-review/SKILL.md | 11 ++
.skills/tinker-review/playbooks/driver-server.md | 5 +-
.skills/tinker-review/playbooks/general.md | 9 ++
.skills/tinker-review/playbooks/glv.md | 10 ++
.skills/tinker-review/playbooks/removal.md | 61 ++++++++
.skills/tinker-review/references/schema.md | 11 +-
.skills/tinker-review/scripts/enrichment/api.js | 155 ++++++++++++++++++++-
.skills/tinker-review/scripts/enrichment/cli.js | 49 ++++++-
.skills/tinker-review/scripts/graph/externals.js | 87 ++++++++++++
.../tinker-review/scripts/patterns/centrality.js | 14 +-
.../scripts/patterns/classify-externals.js | 75 ++++++++++
.../scripts/patterns/confidence-audit.js | 57 +++++++-
.skills/tinker-review/scripts/review.js | 6 +
13 files changed, 537 insertions(+), 13 deletions(-)
diff --git a/.skills/tinker-review/SKILL.md b/.skills/tinker-review/SKILL.md
index 30f028258c..b29d148251 100644
--- a/.skills/tinker-review/SKILL.md
+++ b/.skills/tinker-review/SKILL.md
@@ -60,6 +60,7 @@ Then determine which domain-specific playbooks apply from changed file paths:
- `gremlin-driver/`, `gremlin-server/`, `gremlin-util/` → `playbooks/driver-server.md`
- Small change set with linked issue → `playbooks/bug-fix.md`
- `gremlin-language/` or `*.g4` → `playbooks/grammar.md`
+- Deletion-heavy change set (removes a feature/module/dependency; `listDeleted` returns entries) → `playbooks/removal.md`
Load ALL matching playbooks. Execute enrichment for each in sequence.
@@ -81,17 +82,27 @@ node scripts/enrichment/cli.js listTypes --workDir /tmp/pr-review-<pr> --kind cl
node scripts/enrichment/cli.js getCallsFrom --workDir /tmp/pr-review-<pr> --function <name> --file <path>
node scripts/enrichment/cli.js getCanonicalSteps --workDir /tmp/pr-review-<pr>
node scripts/enrichment/cli.js auditConfidence --workDir /tmp/pr-review-<pr>
+node scripts/enrichment/cli.js listInferred --workDir /tmp/pr-review-<pr> --relation implements_step
+node scripts/enrichment/cli.js listDeleted --workDir /tmp/pr-review-<pr> # removal PRs: files the PR deleted + their symbols
+node scripts/enrichment/cli.js listExternalRefs --workDir /tmp/pr-review-<pr> # unresolved callees; flags any matching a deleted symbol
```
`auditConfidence` returns the edge confidence distribution and the list of
AMBIGUOUS edges. Re-run it after enrichment to refresh the audit with the edges
you added, then reflect any remaining AMBIGUOUS links in `openQuestions`.
+`listInferred` is your **verification worklist** — the name-resolved / agent-mapped
+edges worth a source check (optionally narrowed with `--relation`). After reading
+the source, use `setEdgeConfidence` (below) to promote a confirmed edge to
+`EXTRACTED` or downgrade a wrong resolution to `AMBIGUOUS`.
+
**Write commands** (edges you create default to `INFERRED`; pass
`--confidence AMBIGUOUS` for a guess you want flagged, or `EXTRACTED` when the
source states it directly):
```bash
node scripts/enrichment/cli.js mapStep --workDir /tmp/pr-review-<pr> --function <name> --file <path> --step <canonicalName> [--confidence INFERRED|AMBIGUOUS|EXTRACTED]
+node scripts/enrichment/cli.js setEdgeConfidence --workDir /tmp/pr-review-<pr> --relation <label> --fromName <name> [--fromFile <path>] [--toName <name>] --confidence <EXTRACTED|INFERRED|AMBIGUOUS>
+node scripts/enrichment/cli.js addReference --workDir /tmp/pr-review-<pr> --fromPath <survivingFile> --toPath <deletedFile> --symbol <name> [--location <where>] [--confidence ...]
node scripts/enrichment/cli.js linkDiscussion --workDir /tmp/pr-review-<pr> --url <url> --source jira --title <title> [--confidence ...]
node scripts/enrichment/cli.js linkDoc --workDir /tmp/pr-review-<pr> --entity Step --name <name> --doc <path> [--confidence ...]
node scripts/enrichment/cli.js addGrammarRule --workDir /tmp/pr-review-<pr> --name <name>
diff --git a/.skills/tinker-review/playbooks/driver-server.md b/.skills/tinker-review/playbooks/driver-server.md
index 177fbfdf5e..5f1d2d1018 100644
--- a/.skills/tinker-review/playbooks/driver-server.md
+++ b/.skills/tinker-review/playbooks/driver-server.md
@@ -49,7 +49,10 @@ For each layer, look for:
## Interpret
Driver/server changes have inherently high blast radius — they're shared
infrastructure. Don't flag blast radius as surprising, but DO highlight
-which specific callers are most affected.
+which specific callers are most affected. Use `listExternalRefs` to separate
+real project coupling (`origin: project`/`unresolved`) from library noise
+(`origin: library`) when judging a changed function's reach — centrality already
+drops the library calls, so a function still ranking high is genuinely central.
Connection pooling and concurrency code should have explicit test coverage.
If coverage gaps exist in connection lifecycle code, flag prominently —
diff --git a/.skills/tinker-review/playbooks/general.md b/.skills/tinker-review/playbooks/general.md
index 91ea97253c..3cee125cd5 100644
--- a/.skills/tinker-review/playbooks/general.md
+++ b/.skills/tinker-review/playbooks/general.md
@@ -31,6 +31,15 @@ Look for these patterns in the changed code and annotate them:
- Data structures with concurrency implications (note if CopyOnWriteArraySet,
synchronized collections, etc. are introduced without profiling justification)
+## Verify confidence
+Before writing the report, run `auditConfidence`. Then pull the verification
+worklist with `listInferred` (start with `--relation implements_step`, then any
+`calls` edges that matter to your findings) and spot-check the ones your
+conclusions lean on against the source in the worktree. Re-grade what you
+verify with `setEdgeConfidence`: promote a confirmed edge to `EXTRACTED`, or
+downgrade a wrong name-resolution to `AMBIGUOUS`. Anything left `AMBIGUOUS`
+after this pass belongs in `openQuestions` — don't assert it as fact.
+
## Checks
- coverage_gaps(pr.tests(), pr.modified())
- orphans("Function", "tests", { changedOnly: true })
diff --git a/.skills/tinker-review/playbooks/glv.md b/.skills/tinker-review/playbooks/glv.md
index 8c862a7ddc..4937150a58 100644
--- a/.skills/tinker-review/playbooks/glv.md
+++ b/.skills/tinker-review/playbooks/glv.md
@@ -24,6 +24,16 @@ methods — only the method on GraphTraversal/GraphTraversalSource that users
call (e.g., `tree()`) should map to the step. In a GLV, the equivalent is
the method on the traversal DSL class.
+Record your confidence in each mapping via `mapStep --confidence`: use the
+default `INFERRED` for a solid match, and `AMBIGUOUS` when you can't reliably
+tell whether a method is a real step implementation (this is the graph form of
+the `step_mapping_confidence < 0.7` escape below — AMBIGUOUS mappings surface in
+the report's review list instead of being asserted as fact). Once you've mapped
+methods, run `listInferred --relation implements_step` and, for any mapping you
+then confirm against the reference GLV or grammar, promote it with
+`setEdgeConfidence --relation implements_step --fromName <method> --toName <step>
+--confidence EXTRACTED`.
+
If the PR references a JIRA ticket (TINKERPOP-XXXX), link it as a discussion.
For the driver layer, identify connection acquisition and release points.
diff --git a/.skills/tinker-review/playbooks/removal.md b/.skills/tinker-review/playbooks/removal.md
new file mode 100644
index 0000000000..19e45c2d73
--- /dev/null
+++ b/.skills/tinker-review/playbooks/removal.md
@@ -0,0 +1,61 @@
+# Playbook: Removal / Deprecation
+
+## Context
+The PR deletes code — a feature, a module, a dependency, or a deprecated API.
+The change set is deletion-heavy (many removed files, net-negative diff). The
+central review question is not "is the new code correct?" but **"does anything
+left behind still depend on what was removed?"** A removal that leaves dangling
+references, stale config, or orphaned docs is worse than no removal — it breaks
+the build or misleads users.
+
+Load this playbook when `listDeleted` returns entries (or the PR is dominated by
+deletions). It runs in addition to `general.md` and any module playbook.
+
+## Enrich
+1. Run `listDeleted` to get the removed files and the symbol each likely defined
+ (e.g. `Krb5Authenticator.java` -> `Krb5Authenticator`). Deleted files are
+ already in the graph as `File { deleted: true }` markers.
+
+2. Run `listExternalRefs`. Any external callee whose `matchesDeletedSymbol` is
+ true is a dangling reference the changed code itself still makes — a
+ smoking gun visible in the graph with no grep needed. Record each with
+ `addReference` and treat as a finding.
+
+3. **Grep the surviving worktree** (`/tmp/pr-review-<pr>/src`) for every removed
+ symbol, excluding the deleted files themselves. Search code *and* the
+ supporting cast that removals commonly miss:
+ - source (`*.java`, GLV sources) and build files (`pom.xml`, `*.gradle`)
+ - config/resources (`*.yaml`, `*.conf`, `*.properties`)
+ - docs (`docs/src/**/*.asciidoc`) and `CHANGELOG.asciidoc`
+ - Docker/CI setup (compose files, `*.sh`)
+
+ For each surviving hit, record it with `addReference --fromPath <file>
+ --toPath <deletedFile> --symbol <name> --location <where>`.
+
+4. Confirm the removal is complete on the *other* side too: was the dependency
+ dropped from `pom.xml`? Were the config keys, ports, and doc sections that
+ described the feature removed, not just the classes?
+
+## Checks
+- coverage_gaps(pr.tests(), pr.modified())
+- (references edges created above are the primary structural output)
+
+## Interpret
+Not every surviving reference is a defect — classify each:
+- **Active code / build / config / live docs** referencing a removed symbol is a
+ **blocking finding**: the build breaks or the feature is half-removed.
+- **Historical release notes** (e.g. `docs/src/upgrade/release-3.x.asciidoc`)
+ mentioning the removed symbol are **expected and correct** — they record when
+ the feature existed. Note them as verified-benign, not as a problem.
+- A **current** upgrade/CHANGELOG entry should *gain* a line announcing the
+ removal. Its absence is a finding (users need to know the feature is gone).
+
+Weight findings by where the reference lives, and say so explicitly in the
+report so the reviewer isn't left guessing whether a hit matters.
+
+## Escape
+- if a removed symbol is still referenced by active source or build files —
+ "Removal is incomplete: <symbol> still referenced in <file>; the build or
+ feature is broken until this is resolved."
+- if the removal drops a dependency or public API without an upgrade-doc entry —
+ "User-facing removal needs an upgrade/CHANGELOG note."
diff --git a/.skills/tinker-review/references/schema.md b/.skills/tinker-review/references/schema.md
index 22facca8d1..38564f8aa9 100644
--- a/.skills/tinker-review/references/schema.md
+++ b/.skills/tinker-review/references/schema.md
@@ -18,7 +18,7 @@ select materialized files with `.hasNot("parsed")` and markers with
**Function** `{ name, signature, visibility, filePath, lines_start, lines_end, changed }`
A function or method. The primary unit of analysis.
-*External stub Functions* `{ name, external: true, resolved: false, changed: false }`
+*External stub Functions* `{ name, external: true, resolved: false, changed: false, origin?, definedIn? }`
are markers created when a `calls`/`tests` edge targets a function by name that
wasn't extracted (a library/JDK call, or a function in a file this PR didn't
change). They keep the edge from vanishing and let blast-radius/centrality see
@@ -26,6 +26,12 @@ the call; they lack `filePath`/`signature`/`visibility`. Filter them out with
`.has("external", false)` — or, since real Functions have no `external` property,
`.hasNot("external")` — when you only want materialized code.
+`classifyExternals` tags each stub with `origin`: `library` (a known JDK/accessor
+name — noise), `project` (a repo source declares a type with this name;
+`definedIn` records the file), or `unresolved` (unknown). Centrality drops
+`origin: library` calls from out-degree so ubiquitous accessor calls don't
+inflate hotspots.
+
**Type** `{ name, kind, visibility, filePath }`
A class, interface, struct, or enum. `kind` is one of: class, interface, struct, enum.
@@ -57,7 +63,7 @@ The PR itself is a Discussion with `source: "pr"`.
**Comment** `{ author, body, timestamp }`
A comment on a Discussion.
-## Edges (14 labels)
+## Edges (15 labels)
### Edge confidence (every edge)
@@ -84,6 +90,7 @@ renders this as the **Signal Confidence** panel.
| `defines` | File | Function or Type | File contains this definition |
| `implements` | Function | Type | Function implements an interface |
| `depends_on` | File | File | File imports/requires another file |
+| `references` | File | File (deleted) | A surviving file still mentions a symbol from a file the PR deleted. Added during a removal review via `addReference`; carries `symbol` and `location` properties. |
### Domain relationships
diff --git a/.skills/tinker-review/scripts/enrichment/api.js b/.skills/tinker-review/scripts/enrichment/api.js
index 5508ed563b..9915c1c088 100644
--- a/.skills/tinker-review/scripts/enrichment/api.js
+++ b/.skills/tinker-review/scripts/enrichment/api.js
@@ -20,7 +20,7 @@
import { readFile } from "node:fs/promises";
import { join } from "node:path";
import gremlin from "gremlin";
-import { CONFIDENCE, normalizeConfidence } from "../graph/confidence.js";
+import { CONFIDENCE, normalizeConfidence, isValidConfidence } from "../graph/confidence.js";
const { process: { statics: __ } } = gremlin;
@@ -80,6 +80,66 @@ export async function getCanonicalSteps(repoPath) {
return cachedSteps;
}
+// The likely symbol name a source file defined — its basename without extension
+// (Krb5Authenticator.java -> Krb5Authenticator). Used to turn deleted-file paths
+// into names the agent can grep the rest of the repo for.
+function symbolFromPath(path) {
+ const base = path.split("/").pop() || path;
+ const dot = base.indexOf(".");
+ return dot > 0 ? base.slice(0, dot) : base;
+}
+
+function extOf(path) {
+ return path.includes(".") ? path.split(".").pop() : "";
+}
+
+// === Removal-impact reads ===
+
+/**
+ * Files the PR deleted (stub Files marked deleted). Each entry pairs the path
+ * with the symbol name it likely defined, so the agent can grep the surviving
+ * tree for lingering references to removed code.
+ *
+ * @param {object} g - gremlin-js GraphTraversalSource (already connected)
+ * @returns {Promise<{path: string, symbol: string}[]>}
+ */
+export async function listDeleted(g) {
+ const paths = await g.V().hasLabel("File").has("deleted", true).values("path").toList();
+ return paths.map((path) => ({ path, symbol: symbolFromPath(path) }));
+}
+
+/**
+ * Unresolved external callees (external Function stubs) — names the changed code
+ * calls that weren't defined in the changed set. Includes each stub's `origin`
+ * (library/project/unresolved, once classifyExternals has run) and flags any
+ * whose name matches a deleted file's symbol: a changed file still calling a
+ * just-removed name is a dangling reference visible in the graph alone.
+ *
+ * @param {object} g - gremlin-js GraphTraversalSource (already connected)
+ * @returns {Promise<{name: string, origin: string, matchesDeletedSymbol: boolean}[]>}
+ */
+export async function listExternalRefs(g) {
+ const rows = await g.V().hasLabel("Function").has("external", true)
+ .project("name", "origin")
+ .by("name")
+ .by(__.coalesce(__.values("origin"), __.constant("unclassified")))
+ .toList();
+ const deletedPaths = await g.V().hasLabel("File").has("deleted", true).values("path").toList();
+ const deletedSymbols = new Set(deletedPaths.map(symbolFromPath));
+
+ const rank = { project: 0, unresolved: 1, unclassified: 2, library: 3 };
+ return rows
+ .map((r) => ({
+ name: r.get("name"),
+ origin: r.get("origin"),
+ matchesDeletedSymbol: deletedSymbols.has(r.get("name")),
+ }))
+ .sort((a, b) => {
+ if (a.matchesDeletedSymbol !== b.matchesDeletedSymbol) return a.matchesDeletedSymbol ? -1 : 1;
+ return (rank[a.origin] ?? 9) - (rank[b.origin] ?? 9);
+ });
+}
+
// === Write operations ===
export async function mapStep(g, functionName, filePath, canonicalStepName, confidence) {
@@ -103,6 +163,99 @@ export async function mapStep(g, functionName, filePath, canonicalStepName, conf
return { mapped: `${functionName} -> ${canonicalStepName}`, confidence: conf };
}
+/**
+ * Re-grade the confidence of existing edge(s) after the agent verifies them
+ * against source. Identifies edges by their source vertex (name, optionally
+ * pinned to a file) and relation, optionally narrowed to a named target —
+ * covering the edges agents actually verify (`calls`, `implements_step`).
+ * Promote a confirmed edge to EXTRACTED, or downgrade a wrong resolution to
+ * AMBIGUOUS so it surfaces in the report's review list.
+ *
+ * @param {object} g - gremlin-js GraphTraversalSource (already connected)
+ * @param {object} params
+ * @param {string} params.relation - Edge label (e.g. calls, implements_step)
+ * @param {string} params.fromName - Source vertex name
+ * @param {string} [params.fromFile] - Pin the source to this filePath
+ * @param {string} [params.toName] - Narrow to edges whose target has this name
+ * @param {string} [params.fromLabel] - Source vertex label (default Function)
+ * @param {string} params.confidence - EXTRACTED | INFERRED | AMBIGUOUS
+ * @returns {Promise<object>}
+ */
+export async function setEdgeConfidence(g, params = {}) {
+ const { relation, fromName, fromFile, toName, fromLabel = "Function", confidence } = params;
+ if (!isValidConfidence(confidence)) {
+ return { error: `invalid confidence "${confidence}" — use EXTRACTED, INFERRED, or AMBIGUOUS` };
+ }
+ if (!relation || !fromName) {
+ return { error: "relation and fromName are required" };
+ }
+
+ let t = g.V().hasLabel(fromLabel).has("name", fromName);
+ if (fromFile) t = t.has("filePath", fromFile);
+ t = t.outE(relation);
+ if (toName) t = t.where(__.inV().has("name", toName));
+
+ const updated = await t.property("confidence", confidence).toList();
+ return {
+ relation,
+ from: fromName,
+ to: toName || "*",
+ confidence,
+ updated: updated.length,
+ };
+}
+
+/**
+ * Record a lingering reference to removed code: a surviving file (fromPath) that
+ * still mentions a symbol defined by a deleted file (toPath). Creates a
+ * `references` edge File -> File(deleted), carrying the matched symbol and
+ * location. The source file is often outside the changed set and has no vertex
+ * yet, so it's find-or-created as an unparsed marker. This is the payoff of a
+ * removal review — "the PR deleted X, but these places still use it."
+ *
+ * @param {object} g - gremlin-js GraphTraversalSource (already connected)
+ * @param {object} params
+ * @param {string} params.fromPath - Surviving file that references the removed symbol
+ * @param {string} params.toPath - Deleted file path (must be an existing deleted File)
+ * @param {string} [params.symbol] - The removed symbol found in fromPath
+ * @param {string} [params.location] - Where (e.g. "L42" or a line snippet)
+ * @param {string} [params.confidence] - default INFERRED (a textual grep match)
+ * @returns {Promise<object>}
+ */
+export async function addReference(g, params = {}) {
+ const { fromPath, toPath, symbol, location, confidence } = params;
+ const conf = normalizeConfidence(confidence, CONFIDENCE.INFERRED);
+ if (!fromPath || !toPath) {
+ return { error: "fromPath and toPath are required" };
+ }
+
+ const targetExists = await g.V().hasLabel("File").has("path", toPath).hasNext();
+ if (!targetExists) {
+ return { error: `no deleted File vertex for toPath "${toPath}" (use listDeleted for valid targets)` };
+ }
+
+ const srcExists = await g.V().hasLabel("File").has("path", fromPath).hasNext();
+ if (!srcExists) {
+ await g.addV("File")
+ .property("path", fromPath)
+ .property("language", extOf(fromPath))
+ .property("changed", false)
+ .property("parsed", false)
+ .property("deleted", false)
+ .next();
+ }
+
+ await g.V().hasLabel("File").has("path", fromPath)
+ .addE("references")
+ .property("confidence", conf)
+ .property("symbol", symbol || "")
+ .property("location", location || "")
+ .to(__.V().hasLabel("File").has("path", toPath))
+ .next();
+
+ return { referenced: `${fromPath} -> ${toPath}`, symbol: symbol || "", confidence: conf };
+}
+
export async function linkDiscussion(g, url, source, title, body, confidence) {
const conf = normalizeConfidence(confidence, CONFIDENCE.INFERRED);
await g.addV("Discussion")
diff --git a/.skills/tinker-review/scripts/enrichment/cli.js b/.skills/tinker-review/scripts/enrichment/cli.js
index c5f5099c22..49d078e853 100644
--- a/.skills/tinker-review/scripts/enrichment/cli.js
+++ b/.skills/tinker-review/scripts/enrichment/cli.js
@@ -22,10 +22,12 @@ import { join } from "node:path";
import gremlin from "gremlin";
import {
listFunctions, listTypes, getCallsFrom, getCanonicalSteps,
- mapStep, linkDiscussion, linkDoc, addGrammarRule, annotate,
+ listDeleted, listExternalRefs, addReference,
+ mapStep, setEdgeConfidence, linkDiscussion, linkDoc, addGrammarRule, annotate,
createPrDiscussion,
} from "./api.js";
-import { confidenceAudit } from "../patterns/confidence-audit.js";
+import { confidenceAudit, listInferred } from "../patterns/confidence-audit.js";
+import { classifyExternals } from "../patterns/classify-externals.js";
const COMMANDS = {
listFunctions: { fn: listFunctions, needsG: true },
@@ -33,7 +35,13 @@ const COMMANDS = {
getCallsFrom: { fn: getCallsFrom, needsG: true },
getCanonicalSteps: { fn: getCanonicalSteps, needsG: false },
auditConfidence: { fn: confidenceAudit, needsG: true },
+ listInferred: { fn: listInferred, needsG: true },
+ listDeleted: { fn: listDeleted, needsG: true },
+ listExternalRefs: { fn: listExternalRefs, needsG: true },
+ classifyExternals: { fn: classifyExternals, needsG: true },
+ addReference: { fn: addReference, needsG: true },
mapStep: { fn: mapStep, needsG: true },
+ setEdgeConfidence: { fn: setEdgeConfidence, needsG: true },
linkDiscussion: { fn: linkDiscussion, needsG: true },
linkDoc: { fn: linkDoc, needsG: true },
addGrammarRule: { fn: addGrammarRule, needsG: true },
@@ -76,7 +84,13 @@ async function main() {
console.log(" getCallsFrom --function <name> --file <path>");
console.log(" getCanonicalSteps");
console.log(" auditConfidence [--maxAmbiguous 50]");
+ console.log(" listInferred [--relation implements_step|calls|...] [--limit 100]");
+ console.log(" listDeleted");
+ console.log(" listExternalRefs");
+ console.log(" classifyExternals (tags external stubs origin=library|project|unresolved)");
+ console.log(" addReference --fromPath <path> --toPath <deletedPath> [--symbol <name>] [--location <L42>] [--confidence ...]");
console.log(" mapStep --function <name> --file <path> --step <canonicalName> [--confidence INFERRED|AMBIGUOUS|EXTRACTED]");
+ console.log(" setEdgeConfidence --relation <label> --fromName <name> [--fromFile <path>] [--toName <name>] --confidence <EXTRACTED|INFERRED|AMBIGUOUS>");
console.log(" linkDiscussion --url <url> --source <jira|devlist|proposal> --title <title> [--body <body>] [--confidence ...]");
console.log(" linkDoc --entity <label> --name <name> --doc <path> [--section <section>] [--confidence ...]");
console.log(" addGrammarRule --name <name> [--production <production>]");
@@ -130,9 +144,40 @@ async function main() {
case "auditConfidence":
result = await fn(g, { maxAmbiguous: args.maxAmbiguous });
break;
+ case "listInferred":
+ result = await fn(g, { relation: args.relation, limit: args.limit });
+ break;
+ case "listDeleted":
+ result = await fn(g);
+ break;
+ case "listExternalRefs":
+ result = await fn(g);
+ break;
+ case "classifyExternals":
+ result = await fn(g, session.worktreePath || session.repoPath);
+ break;
+ case "addReference":
+ result = await fn(g, {
+ fromPath: args.fromPath,
+ toPath: args.toPath,
+ symbol: args.symbol,
+ location: args.location,
+ confidence: args.confidence,
+ });
+ break;
case "mapStep":
result = await fn(g, args.function, args.file, args.step, args.confidence);
break;
+ case "setEdgeConfidence":
+ result = await fn(g, {
+ relation: args.relation,
+ fromName: args.fromName,
+ fromFile: args.fromFile,
+ toName: args.toName,
+ fromLabel: args.fromLabel,
+ confidence: args.confidence,
+ });
+ break;
case "linkDiscussion":
result = await fn(g, args.url, args.source, args.title, args.body, args.confidence);
break;
diff --git a/.skills/tinker-review/scripts/graph/externals.js b/.skills/tinker-review/scripts/graph/externals.js
new file mode 100644
index 0000000000..01c6080e7c
--- /dev/null
+++ b/.skills/tinker-review/scripts/graph/externals.js
@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Names that, when they show up as unresolved callees (external Function stubs),
+ * are almost certainly JDK / standard-library / ubiquitous-accessor calls rather
+ * than project functions. Classifying these as `library` lets structural checks
+ * (centrality, blast radius) drop the noise they'd otherwise inflate.
+ *
+ * Deliberately conservative: it lists object/collection/string/IO/logging/stream
+ * staples and common getX/isX accessors, and avoids ambiguous verbs (build,
+ * create, start, run, call…) that are just as likely to name a real project
+ * method. A false "library" on a genuinely ubiquitous name like `get` is
+ * acceptable; a false "library" on a distinctive project method is not.
+ */
+export const COMMON_LIBRARY_NAMES = new Set([
+ // java.lang.Object
+ "equals", "hashCode", "toString", "clone", "finalize", "getClass",
+ "wait", "notify", "notifyAll",
+ // Comparable / iterator
+ "compareTo", "iterator", "hasNext", "next", "remove",
+ // Collection / Map / List
+ "size", "isEmpty", "contains", "containsKey", "containsValue",
+ "add", "addAll", "get", "set", "put", "putAll", "clear", "remove",
+ "keySet", "values", "entrySet", "toArray", "stream", "getKey", "getValue",
+ // String / CharSequence
+ "length", "charAt", "substring", "trim", "split", "replace", "indexOf",
+ "startsWith", "endsWith", "matches", "toLowerCase", "toUpperCase",
+ "getBytes", "valueOf", "format",
+ // common accessors
+ "getName", "getId", "getType", "getMessage", "getValue", "getStatusCode",
+ "getCause", "getClassName", "name", "ordinal",
+ // IO / lifecycle
+ "close", "flush", "read", "write", "open",
+ // logging
+ "log", "info", "debug", "warn", "error", "trace", "printStackTrace",
+ "print", "println",
+ // Optional / functional / stream
+ "of", "empty", "orElse", "orElseGet", "orElseThrow", "ifPresent", "isPresent",
+ "forEach", "map", "filter", "collect", "count", "findFirst", "anyMatch",
+ "allMatch", "noneMatch", "apply", "accept", "test",
+]);
+
+/**
+ * @param {string} name
+ * @returns {boolean} true if the name is a well-known library/JDK/accessor call
+ */
+export function isLibraryName(name) {
+ return COMMON_LIBRARY_NAMES.has(name);
+}
+
+/**
+ * Origin classification for an external stub, given whether a project type with
+ * this name was found in the repo.
+ *
+ * library — a known JDK/standard-library/accessor name (noise)
+ * project — a project source file declares a type with this name (signal)
+ * unresolved — neither; unknown, treat with caution
+ *
+ * Method-name project detection isn't attempted (name-only grep can't tell a
+ * definition from a use reliably); that's the domain of precise resolution.
+ *
+ * @param {string} name
+ * @param {boolean} definedAsProjectType
+ * @returns {"library"|"project"|"unresolved"}
+ */
+export function classifyExternalName(name, definedAsProjectType) {
+ if (isLibraryName(name)) return "library";
+ if (definedAsProjectType) return "project";
+ return "unresolved";
+}
diff --git a/.skills/tinker-review/scripts/patterns/centrality.js b/.skills/tinker-review/scripts/patterns/centrality.js
index 11aa0ca259..d891533270 100644
--- a/.skills/tinker-review/scripts/patterns/centrality.js
+++ b/.skills/tinker-review/scripts/patterns/centrality.js
@@ -19,6 +19,8 @@
import gremlin from "gremlin";
+const { process: { statics: __ } } = gremlin;
+
const INHERENTLY_CENTRAL = new Set([
"equals", "hashCode", "toString", "clone", "close", "compareTo",
"iterator", "hasNext", "next", "get", "set", "size", "isEmpty",
@@ -39,12 +41,16 @@ const INHERENTLY_CENTRAL = new Set([
* @param {boolean} [params.changedOnly] - Only check changed functions (default: true)
* @param {number} [params.topN] - Return top N results (default: 10)
* @param {number} [params.minDegree] - Minimum combined in+out degree to include (default: 3)
+ * @param {boolean} [params.excludeLibrary] - Drop calls to library-origin external
+ * stubs from out-degree so JDK/accessor noise doesn't inflate hotspots (default: true).
+ * Only takes effect once classifyExternals has tagged `origin`.
* @returns {Promise<CentralityResult>}
*/
export async function highCentrality(g, params = {}) {
const changedOnly = params.changedOnly !== false;
const topN = params.topN || 10;
const minDegree = params.minDegree || 3;
+ const excludeLibrary = params.excludeLibrary !== false;
let traversal = g.V().hasLabel("Function");
if (changedOnly) {
@@ -61,7 +67,13 @@ export async function highCentrality(g, params = {}) {
const changed = fnMap.get("changed");
const inDegree = await g.V(vertexId).inE("calls").count().next();
- const outDegree = await g.V(vertexId).outE("calls").count().next();
+ // Out-degree optionally skips calls to library-origin externals (getName,
+ // toString, …) so ubiquitous JDK/accessor calls don't inflate the hotspot.
+ let outTraversal = g.V(vertexId).outE("calls");
+ if (excludeLibrary) {
+ outTraversal = outTraversal.where(__.inV().not(__.has("origin", "library")));
+ }
+ const outDegree = await outTraversal.count().next();
const inCount = inDegree.value;
const outCount = outDegree.value;
diff --git a/.skills/tinker-review/scripts/patterns/classify-externals.js b/.skills/tinker-review/scripts/patterns/classify-externals.js
new file mode 100644
index 0000000000..20562362f1
--- /dev/null
+++ b/.skills/tinker-review/scripts/patterns/classify-externals.js
@@ -0,0 +1,75 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { classifyExternalName } from "../graph/externals.js";
+
+const exec = promisify(execFile);
+
+// A precise, low-false-positive check: does a Java type declaration with this
+// exact name exist anywhere in the repo? Uses `git grep` in the worktree (fast,
+// respects the tree). Returns the first defining file, or null.
+async function definedAsProjectType(name, repoPath) {
+ if (!repoPath || !/^\w+$/.test(name)) return null;
+ try {
+ const { stdout } = await exec(
+ "git",
+ ["grep", "-lE", `(class|interface|enum|@interface)[[:space:]]+${name}\\b`],
+ { cwd: repoPath },
+ );
+ const files = stdout.split("\n").filter(Boolean);
+ return files[0] || null;
+ } catch {
+ // git grep exits non-zero when there is no match — treat as "not found".
+ return null;
+ }
+}
+
+/**
+ * Classify every external Function stub as library / project / unresolved and
+ * annotate the vertex with `origin` (and `definedIn` for project types). This
+ * lets structural checks drop library noise. Run it after populate and BEFORE
+ * centrality so the metric can exclude `origin: library`.
+ *
+ * @param {object} g - gremlin-js GraphTraversalSource (already connected)
+ * @param {string} repoPath - a git worktree to grep for project type definitions
+ * @returns {Promise<{total: number, library: string[], project: object[], unresolved: string[]}>}
+ */
+export async function classifyExternals(g, repoPath) {
+ const names = await g.V().hasLabel("Function").has("external", true).values("name").toList();
+
+ const classified = await Promise.all(names.map(async (name) => {
+ const definedIn = await definedAsProjectType(name, repoPath);
+ return { name, origin: classifyExternalName(name, Boolean(definedIn)), definedIn };
+ }));
+
+ const summary = { total: names.length, library: [], project: [], unresolved: [] };
+ for (const { name, origin, definedIn } of classified) {
+ let t = g.V().hasLabel("Function").has("external", true).has("name", name)
+ .property("origin", origin);
+ if (origin === "project" && definedIn) t = t.property("definedIn", definedIn);
+ await t.iterate();
+
+ if (origin === "project") summary.project.push({ name, definedIn });
+ else summary[origin].push(name);
+ }
+
+ return summary;
+}
diff --git a/.skills/tinker-review/scripts/patterns/confidence-audit.js b/.skills/tinker-review/scripts/patterns/confidence-audit.js
index ddb5c6e30d..db8442694f 100644
--- a/.skills/tinker-review/scripts/patterns/confidence-audit.js
+++ b/.skills/tinker-review/scripts/patterns/confidence-audit.js
@@ -71,24 +71,69 @@ export async function confidenceAudit(g, params = {}) {
}
}
- const ambiguousRows = await g.E()
- .has("confidence", CONFIDENCE.AMBIGUOUS)
- .project("relation", "found_in", "found_via", "from", "to")
+ const ambiguous = await listEdgesByConfidence(g, {
+ confidence: CONFIDENCE.AMBIGUOUS,
+ limit: maxAmbiguous,
+ });
+
+ return { distribution, total, ambiguous };
+}
+
+/**
+ * List edges at a given confidence, optionally narrowed to one relation, with
+ * both endpoints described. The building block behind confidenceAudit's
+ * AMBIGUOUS list and the agent-facing listInferred worklist.
+ *
+ * @param {object} g - gremlin-js GraphTraversalSource (already connected)
+ * @param {object} [opts]
+ * @param {string} [opts.confidence] - Filter to this confidence value
+ * @param {string} [opts.relation] - Filter to this edge label (e.g. implements_step)
+ * @param {number} [opts.limit] - Cap the result count (default 100)
+ * @returns {Promise<object[]>} rows of { relation, confidence, from, to, foundIn, foundVia }
+ */
+export async function listEdgesByConfidence(g, opts = {}) {
+ const { confidence, relation, limit = 100 } = opts;
+ let t = g.E();
+ if (relation) t = t.hasLabel(relation);
+ if (confidence) t = t.has("confidence", confidence);
+
+ const rows = await t
+ .limit(limit)
+ .project("relation", "confidence", "found_in", "found_via", "from", "to")
.by(__.label())
+ .by(__.coalesce(__.values("confidence"), __.constant("")))
.by(__.coalesce(__.values("found_in"), __.constant("")))
.by(__.coalesce(__.values("found_via"), __.constant("")))
.by(__.outV().elementMap())
.by(__.inV().elementMap())
- .limit(maxAmbiguous)
.toList();
- const ambiguous = ambiguousRows.map((row) => ({
+ return rows.map((row) => ({
relation: row.get("relation"),
+ confidence: row.get("confidence") || undefined,
from: describeVertex(row.get("from")),
to: describeVertex(row.get("to")),
foundIn: row.get("found_in") || undefined,
foundVia: row.get("found_via") || undefined,
}));
+}
- return { distribution, total, ambiguous };
+/**
+ * Agent verification worklist: the INFERRED edges (name-resolved calls, agent
+ * step/doc mappings) that warrant a source check. After verifying, the agent
+ * uses setEdgeConfidence to promote a confirmed edge to EXTRACTED or downgrade a
+ * wrong one to AMBIGUOUS.
+ *
+ * @param {object} g - gremlin-js GraphTraversalSource (already connected)
+ * @param {object} [params]
+ * @param {string} [params.relation] - Narrow to one relation (e.g. implements_step)
+ * @param {number} [params.limit] - Cap results (default 100)
+ * @returns {Promise<object[]>}
+ */
+export async function listInferred(g, params = {}) {
+ return listEdgesByConfidence(g, {
+ confidence: CONFIDENCE.INFERRED,
+ relation: params.relation,
+ limit: params.limit || 100,
+ });
}
diff --git a/.skills/tinker-review/scripts/review.js b/.skills/tinker-review/scripts/review.js
index bda97cd7b8..65863f08e5 100644
--- a/.skills/tinker-review/scripts/review.js
+++ b/.skills/tinker-review/scripts/review.js
@@ -35,6 +35,7 @@ import { blastRadius } from "./patterns/blast-radius.js";
import { clusterAnalysis } from "./patterns/cluster-analysis.js";
import { architecture } from "./patterns/architecture.js";
import { confidenceAudit } from "./patterns/confidence-audit.js";
+import { classifyExternals } from "./patterns/classify-externals.js";
import { createPrDiscussion } from "./enrichment/api.js";
import { discoverDiscussions } from "./discovery/discussions.js";
@@ -295,6 +296,10 @@ export async function phase1(session) {
log(`Loading discussions into graph...`);
await populateDiscussions(g, discussions, { pr, prTitle: prTitle.trim(), changedFiles });
+ log(`Classifying external callees...`);
+ const externalsResult = await classifyExternals(g, worktreePath);
+ log(` externals: ${externalsResult.library.length} library / ${externalsResult.project.length} project / ${externalsResult.unresolved.length} unresolved`);
+
log(`Running checks...`);
const completenessResults = await completeness(g, {
vertexLabel: "File",
@@ -335,6 +340,7 @@ export async function phase1(session) {
blastRadius: blastResult,
clusters: clusterResult,
confidence: confidenceResult,
+ externals: externalsResult,
},
discussions,
changedFiles,
(tinkerpop) 06/07: tinker-review: harmonize SKILL.md phase terminology with DESIGN.md
Posted by sp...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit c011cb4024cefb2c4f827cd0457526eabac07a14
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Fri Jul 3 17:23:09 2026 -0400
tinker-review: harmonize SKILL.md phase terminology with DESIGN.md
Phase 2 now spans the agent-driven steps (enrichment, the optional functional
test, and the report), matching DESIGN.md's two-phase model. Steps 3-5 are
labelled Phase 2; a lead-in frames Phase 1 as step 1 and step 2 as playbook prep.
Previously only enrichment carried the Phase 2 label, leaving the functional test
and report as unlabelled peers.
Assisted-by: Claude Code:claude-opus-4-8
---
.skills/tinker-review/SKILL.md | 11 ++++++++---
1 file changed, 8 insertions(+), 3 deletions(-)
diff --git a/.skills/tinker-review/SKILL.md b/.skills/tinker-review/SKILL.md
index 8e0e808af1..c11faa41b1 100644
--- a/.skills/tinker-review/SKILL.md
+++ b/.skills/tinker-review/SKILL.md
@@ -30,6 +30,11 @@ metadata:
When invoked with `/review <pr-number>`:
+The run has two phases (see [DESIGN.md](DESIGN.md)). **Phase 1** (step 1) is
+deterministic and builds the graph. **Phase 2** (steps 3–5) is agent-driven —
+enrichment, an optional functional test, then the report. Step 2 loads the
+playbooks that guide Phase 2; step 6 tears down.
+
### 1. Setup + Phase 1 (deterministic)
Run the review script. This handles everything mechanical:
@@ -82,7 +87,7 @@ meaning of every field is documented in
[references/interfaces.md](references/interfaces.md) (`Evidence`), which points
to the per-check `@typedef`s in `scripts/patterns/*.js`.
-### 3. Phase 2 — Enrichment (agent-driven)
+### 3. Phase 2 — Enrichment
The Gremlin Server is still running. Use `scripts/enrichment/cli.js` to
read from and write to the knowledge graph. Do NOT write your own connection
@@ -134,7 +139,7 @@ The connection info is read from `/tmp/pr-review-<pr>/session.json` automaticall
Follow the playbook's Enrich section. Check Escape conditions.
-### 4. Functional Testing (subagent)
+### 4. Phase 2 — Functional Testing (optional, subagent)
**IMPORTANT: Functional testing is NOT running the project's unit tests.**
DO NOT use `mvn test`. DO NOT run TreeTest, DO NOT run any existing test class.
@@ -175,7 +180,7 @@ and attempts adversarial edge cases.
The subagent returns: test plan, results, adversarial findings, exact test code.
-### 5. Produce Report
+### 5. Phase 2 — Produce Report
Write the narrative JSON, then render.
(tinkerpop) 03/07: tinker-review: document evidence.json schema and simplify playbooks
Posted by sp...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit e24bd427c63a2456150ffe747abfa6ef3b8e2fc1
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Fri Jul 3 15:18:28 2026 -0400
tinker-review: document evidence.json schema and simplify playbooks
Each check's result type is now a @typedef with per-field meaning in the pattern
file that produces it (fixing four @returns that referenced types defined
nowhere); interfaces.md keeps only the composite Evidence/ReportPackage shape and
points at those typedefs. Wire orphans into Phase 1 so checks.orphans is real.
Delete the pseudo-code Checks section from every playbook and fold its emphasis
into Interpret, which now cites real evidence.json fields. SKILL.md states the
section-to-phase contract so the agent knows what to do with each section.
Assisted-by: Claude Code:claude-opus-4-8
---
.skills/tinker-review/SKILL.md | 18 +++++
.skills/tinker-review/playbooks/bug-fix.md | 39 ++++++-----
.skills/tinker-review/playbooks/driver-server.md | 27 ++++----
.skills/tinker-review/playbooks/general.md | 9 +--
.skills/tinker-review/playbooks/glv.md | 18 +++--
.skills/tinker-review/playbooks/grammar.md | 13 ++--
.skills/tinker-review/playbooks/new-step.md | 29 ++++----
.skills/tinker-review/playbooks/removal.md | 9 +--
.skills/tinker-review/references/interfaces.md | 79 ++++++++++++++--------
.../tinker-review/scripts/patterns/architecture.js | 14 +++-
.../tinker-review/scripts/patterns/blast-radius.js | 19 ++++++
.../tinker-review/scripts/patterns/centrality.js | 21 ++++++
.../scripts/patterns/classify-externals.js | 10 ++-
.../scripts/patterns/cluster-analysis.js | 13 ++++
.../tinker-review/scripts/patterns/completeness.js | 8 +++
.../scripts/patterns/confidence-audit.js | 21 +++++-
.../scripts/patterns/coverage-gaps.js | 14 ++++
.skills/tinker-review/scripts/patterns/orphans.js | 13 ++++
.skills/tinker-review/scripts/review.js | 4 ++
19 files changed, 275 insertions(+), 103 deletions(-)
diff --git a/.skills/tinker-review/SKILL.md b/.skills/tinker-review/SKILL.md
index b29d148251..b4291613d8 100644
--- a/.skills/tinker-review/SKILL.md
+++ b/.skills/tinker-review/SKILL.md
@@ -64,6 +64,24 @@ Then determine which domain-specific playbooks apply from changed file paths:
Load ALL matching playbooks. Execute enrichment for each in sequence.
+**How a playbook is applied.** Each playbook has four sections, and each maps to
+a phase of this run — this is the contract for what to do with the content:
+
+| Section | When | What you do with it |
+|---------|------|---------------------|
+| **Context** | framing | Orient to the change type and its risks; not actioned directly. |
+| **Enrich** | Phase 2 | Execute the listed steps using the enrichment CLI commands. |
+| **Interpret** | Phase 5 | When writing the report, weigh the named `evidence.json` fields into `findings` / `openQuestions`. |
+| **Escape** | any phase | Check the stop/escalate conditions; halt or flag when one holds. |
+
+Phase 1 already computes every structural check — completeness, coverageGaps,
+centrality, blastRadius, clusters, confidence, externals, orphans — into
+`evidence.json`. Playbooks' Interpret sections reference those results **by field
+name** (e.g. `checks.blastRadius`); they do not re-run checks. The shape and
+meaning of every field is documented in
+[references/interfaces.md](references/interfaces.md) (`Evidence`), which points
+to the per-check `@typedef`s in `scripts/patterns/*.js`.
+
### 3. Phase 2 — Enrichment (agent-driven)
The Gremlin Server is still running. Use `scripts/enrichment/cli.js` to
diff --git a/.skills/tinker-review/playbooks/bug-fix.md b/.skills/tinker-review/playbooks/bug-fix.md
index 20be16eb98..fce7496a07 100644
--- a/.skills/tinker-review/playbooks/bug-fix.md
+++ b/.skills/tinker-review/playbooks/bug-fix.md
@@ -22,25 +22,28 @@ Look for:
If the PR references a JIRA ticket (TINKERPOP-XXXX), link it as a discussion.
-## Checks
-- completeness(pr, ["addresses"])
-- coverage_gaps(pr.tests(), pr.modified())
-- blast_radius(pr.modified(), 3)
-- high_centrality(pr.modified())
-
## Interpret
-High blast radius on a bug fix is a warning signal — the fix touches
-something many callers depend on. This doesn't mean it's wrong, but it
-means the reviewer should verify the fix doesn't subtly change behavior
-for existing callers.
-
-Changes outside the issue scope aren't automatically bad — sometimes
-fixing a bug requires touching adjacent code. But they should be
-explainable. Flag them with "necessary for fix?" not "wrong."
-
-If high-centrality functions are modified, emphasize that the reviewer
-should check all callers for behavioral changes. A fix in a hot function
-can silently break things far from the fix site.
+Read the structural signals from evidence.json (schema in
+[references/interfaces.md](../references/interfaces.md)).
+
+High blast radius (checks.blastRadius) on a bug fix is a warning signal — the
+fix touches something many callers depend on. It isn't wrong, but verify it
+doesn't subtly change behavior for existing callers. If high-centrality
+functions (checks.centrality) are modified, say explicitly that every caller
+needs a behavioral-change check — a fix in a hot function breaks things far
+from the fix site.
+
+A bug fix with no new or modified test is the biggest red flag: an untested fix
+(checks.coverageGaps, checks.orphans) can't be shown to prevent regression.
+Call it out prominently.
+
+Confirm the fix is tied to its issue — the PR should have an `addresses` edge to
+the JIRA/discussion (checks.completeness on `addresses`). No linked issue means
+correctness can't be assessed.
+
+Changes outside the issue scope aren't automatically bad — sometimes a fix needs
+adjacent code. But they should be explainable. Flag them "necessary for fix?"
+not "wrong."
## Escape
- if no linked issue — "Cannot assess whether fix is correct without knowing the bug"
diff --git a/.skills/tinker-review/playbooks/driver-server.md b/.skills/tinker-review/playbooks/driver-server.md
index 5f1d2d1018..38d4cf8705 100644
--- a/.skills/tinker-review/playbooks/driver-server.md
+++ b/.skills/tinker-review/playbooks/driver-server.md
@@ -40,23 +40,22 @@ For each layer, look for:
- Server configuration: gremlin-lang expressions, not Groovy scripts
- Don't leave commented-out old code — remove it cleanly
-## Checks
-- blast_radius(pr.modified(), 3)
-- high_centrality(pr.modified())
-- coverage_gaps(pr.tests(), pr.modified())
-- orphans("Function", "tests", { changedOnly: true })
-
## Interpret
-Driver/server changes have inherently high blast radius — they're shared
-infrastructure. Don't flag blast radius as surprising, but DO highlight
-which specific callers are most affected. Use `listExternalRefs` to separate
-real project coupling (`origin: project`/`unresolved`) from library noise
-(`origin: library`) when judging a changed function's reach — centrality already
-drops the library calls, so a function still ranking high is genuinely central.
+Read the structural signals from evidence.json (schema in
+[references/interfaces.md](../references/interfaces.md)).
+
+Driver/server changes have inherently high blast radius (checks.blastRadius) —
+they're shared infrastructure. Don't flag the reach as surprising, but DO
+highlight which specific callers are most affected (checks.centrality). Use
+`listExternalRefs` to separate real project coupling (`origin: project`/
+`unresolved`) from library noise (`origin: library`) when judging a changed
+function's reach — centrality already drops the library calls, so a function
+still ranking high is genuinely central.
Connection pooling and concurrency code should have explicit test coverage.
-If coverage gaps exist in connection lifecycle code, flag prominently —
-these are the hardest bugs to reproduce and the most impactful in production.
+If coverage gaps exist in connection lifecycle code (checks.coverageGaps,
+checks.orphans), flag prominently — these are the hardest bugs to reproduce
+and the most impactful in production.
Serialization changes that add/remove type codes need upgrade documentation.
Check if the PR includes corresponding upgrade doc entries.
diff --git a/.skills/tinker-review/playbooks/general.md b/.skills/tinker-review/playbooks/general.md
index 3cee125cd5..c13eba4ffc 100644
--- a/.skills/tinker-review/playbooks/general.md
+++ b/.skills/tinker-review/playbooks/general.md
@@ -40,11 +40,12 @@ verify with `setEdgeConfidence`: promote a confirmed edge to `EXTRACTED`, or
downgrade a wrong name-resolution to `AMBIGUOUS`. Anything left `AMBIGUOUS`
after this pass belongs in `openQuestions` — don't assert it as fact.
-## Checks
-- coverage_gaps(pr.tests(), pr.modified())
-- orphans("Function", "tests", { changedOnly: true })
-
## Interpret
+Read the structural signals from evidence.json (schema in
+[references/interfaces.md](../references/interfaces.md)). Missing tests on
+changed code (checks.coverageGaps, checks.orphans) are a test-quality concern —
+weigh them alongside the code smells below.
+
Style nits and unused variables are low severity — note them but don't
make them the focus of the report. Prioritize safety concerns (resource
leaks, concurrency risks, missing error handling) and test quality issues.
diff --git a/.skills/tinker-review/playbooks/glv.md b/.skills/tinker-review/playbooks/glv.md
index 4937150a58..ba9ce3308e 100644
--- a/.skills/tinker-review/playbooks/glv.md
+++ b/.skills/tinker-review/playbooks/glv.md
@@ -40,23 +40,21 @@ For the driver layer, identify connection acquisition and release points.
Trace resource lifecycle through error paths — the common GLV bug is
leaking connections when a traversal fails mid-execution.
-## Checks
-- completeness(glv, canonical_step_list())
-- coverage_gaps(pr.tests(), pr.modified())
-- high_centrality(pr.modified())
-
## Interpret
-When reporting completeness gaps, distinguish between missing steps and
-steps that exist but use a language-specific name (e.g., Python uses
-`addV` but Go uses `AddV` — same step, different convention).
+Read the structural signals from evidence.json (schema in
+[references/interfaces.md](../references/interfaces.md)).
+
+When reporting completeness gaps (checks.completeness), distinguish between
+missing steps and steps that exist but use a language-specific name (e.g.,
+Python uses `addV` but Go uses `AddV` — same step, different convention).
When reporting divergence from the reference GLV, the question isn't
"is it different?" — it's "is the difference justified by the host
language?" A Go GLV using goroutines where Python uses asyncio is fine.
A Go GLV using a different serialization format is a concern.
-Coverage gaps in a GLV are expected for driver internals (connection
-management, serialization) — but traversal step methods should have
+Coverage gaps in a GLV (checks.coverageGaps) are expected for driver internals
+(connection management, serialization) — but traversal step methods should have
corresponding test coverage.
## Escape
diff --git a/.skills/tinker-review/playbooks/grammar.md b/.skills/tinker-review/playbooks/grammar.md
index dd8bb704b0..9a796e33a2 100644
--- a/.skills/tinker-review/playbooks/grammar.md
+++ b/.skills/tinker-review/playbooks/grammar.md
@@ -15,14 +15,13 @@ Identify which grammar rules were added or modified. Check:
Link the proposal/discussion — grammar changes should always have prior
community discussion.
-## Checks
-- completeness(grammarRule, ["in:has_rule"])
-- blast_radius(pr.modified(), 2)
-- high_centrality(pr.modified())
-
## Interpret
-Grammar changes have outsized blast radius by nature — the grammar
-touches everything. Focus on whether the change is backwards compatible.
+Read the structural signals from evidence.json (schema in
+[references/interfaces.md](../references/interfaces.md)). Grammar changes have
+outsized blast radius by nature (checks.blastRadius, checks.centrality) — the
+grammar touches everything, so don't flag the reach itself; focus on backwards
+compatibility. Completeness (checks.completeness on has_rule) shows whether new
+rules are wired to a step.
A new rule that adds syntax (existing queries still work) is low risk.
A modified rule that changes parsing of existing syntax is high risk and
diff --git a/.skills/tinker-review/playbooks/new-step.md b/.skills/tinker-review/playbooks/new-step.md
index eb66769fb9..3cd04e5aca 100644
--- a/.skills/tinker-review/playbooks/new-step.md
+++ b/.skills/tinker-review/playbooks/new-step.md
@@ -24,24 +24,29 @@ For API design concerns (mined from TinkerPop reviewer patterns):
- Class design: wrapping + extending the same parent is suspicious
- Type restrictions should not be too narrow (provider implementations vary)
-## Checks
-- completeness(step, ["in:implements_step", "out:has_rule", "in:covers", "in:documents", "out:proposed_in"])
-- coverage_gaps(pr.tests(), pr.modified())
-- high_centrality(pr.modified())
-- blast_radius(pr.modified(), 3)
-
## Interpret
-A step missing from some GLVs is acceptable if tracked in a follow-up
-issue — check if the PR or linked JIRA mentions phased rollout. Missing
-documentation is not acceptable — a step without docs is undiscoverable.
+Read the structural signals from evidence.json (schema in
+[references/interfaces.md](../references/interfaces.md)).
+
+A new step's completeness (checks.completeness over implements_step / has_rule /
+covers / documents / proposed_in) tells you what's missing. Missing from some
+GLVs is acceptable if a follow-up issue tracks it — check the PR or linked JIRA
+for phased rollout. Missing docs (no `documents` edge) is not acceptable — an
+undocumented step is undiscoverable. Missing tests (checks.coverageGaps, no
+`covers` edge) is a blocking gap — a new step must be exercised.
+
+A new step usually has low blast radius (checks.blastRadius) since nothing calls
+it yet; a high value means it hooks into shared infrastructure — verify those
+integration points.
When comparing signatures across GLVs, parameter count should match but
parameter types will differ by language. Focus on semantic equivalence,
not syntactic identity.
-High centrality in step infrastructure (TraversalStrategy, Step interface
-implementations) is expected — these are shared abstractions. Flag it
-for attention but don't treat it as a problem.
+High centrality (checks.centrality) in step infrastructure (TraversalStrategy,
+Step interface implementations) is expected — these are shared abstractions.
+Flag it for attention but don't treat it as a problem. Ignore out-degree that's
+just library calls (checks.externals, origin=library).
## Escape
- if missing: proposal — "Cannot assess intent — need human to confirm expected semantics"
diff --git a/.skills/tinker-review/playbooks/removal.md b/.skills/tinker-review/playbooks/removal.md
index 19e45c2d73..a40dcd0d63 100644
--- a/.skills/tinker-review/playbooks/removal.md
+++ b/.skills/tinker-review/playbooks/removal.md
@@ -36,11 +36,12 @@ deletions). It runs in addition to `general.md` and any module playbook.
dropped from `pom.xml`? Were the config keys, ports, and doc sections that
described the feature removed, not just the classes?
-## Checks
-- coverage_gaps(pr.tests(), pr.modified())
-- (references edges created above are the primary structural output)
-
## Interpret
+Read the structural signals from evidence.json (schema in
+[references/interfaces.md](../references/interfaces.md)); the `references` edges
+you added above and checks.coverageGaps on any surviving code are the primary
+structural outputs here.
+
Not every surviving reference is a defect — classify each:
- **Active code / build / config / live docs** referencing a removed symbol is a
**blocking finding**: the build breaks or the feature is half-removed.
diff --git a/.skills/tinker-review/references/interfaces.md b/.skills/tinker-review/references/interfaces.md
index 33df7fd202..8d0fa4239d 100644
--- a/.skills/tinker-review/references/interfaces.md
+++ b/.skills/tinker-review/references/interfaces.md
@@ -68,54 +68,75 @@ interface ServerHandle {
// === Graph Population ===
interface PopulationSummary {
- vertices: number;
- edges: number;
- breakdown: {
+ vertices: number; // true count, queried from the graph after population
+ edges: number; // true count, queried from the graph after population
+ breakdown: { // per-type ATTEMPTED inserts (may exceed the real totals above)
files: number;
functions: number;
types: number;
+ tests: number;
calls: number;
defines: number;
- dependsOn: number;
+ testsEdges: number;
+ externalFunctions: number; // stub Functions minted for unresolved callees
+ stubFiles: number; // stub Files minted for changed files that weren't parsed
};
}
// === Pattern Results ===
-
-interface CompletenessResult {
- node: string; // vertex id or identifier checked
- present: string[]; // edge labels that exist
- missing: string[]; // edge labels that are absent
- score: number; // present.length / (present.length + missing.length)
-}
-
-interface CoverageGapResult {
- uncovered: {
- name: string;
- signature: string;
- filePath: string;
- linesStart: number;
- linesEnd: number;
- }[];
- totalChanged: number;
- totalCovered: number;
-}
-
-// === Evidence Package (renderer input) ===
-
-interface EvidencePackage {
+//
+// Each check's result type is defined — WITH per-field meaning — as a @typedef
+// in the pattern file that produces it. Those typedefs are canonical; read them
+// when interpreting a field. Do not re-declare them here (that is what drifts).
+//
+// CompletenessResult scripts/patterns/completeness.js
+// CoverageGapResult scripts/patterns/coverage-gaps.js
+// CentralityResult scripts/patterns/centrality.js
+// BlastRadiusResult scripts/patterns/blast-radius.js
+// ClusterResult scripts/patterns/cluster-analysis.js
+// ConfidenceResult scripts/patterns/confidence-audit.js
+// ExternalsResult scripts/patterns/classify-externals.js
+// OrphanResult scripts/patterns/orphans.js
+// ArchitectureResult scripts/patterns/architecture.js
+
+// === Evidence (evidence.json — what Phase 1 writes; the fields Interpret cites) ===
+
+interface Evidence {
meta: {
pr: number;
title: string;
- domain: string;
+ domains: string[]; // e.g. ["general", "glv", "driver-server"]
+ language: string;
+ changedFileCount: number;
timestamp: string;
};
- summary: string;
graphStats: PopulationSummary;
+ architecture: ArchitectureResult;
checks: {
completeness: CompletenessResult[];
coverageGaps: CoverageGapResult;
+ centrality: CentralityResult;
+ blastRadius: BlastRadiusResult;
+ clusters: ClusterResult;
+ confidence: ConfidenceResult;
+ externals: ExternalsResult;
+ orphans: OrphanResult;
};
+ discussions: DiscussionsResult; // jiras[], devList[], secondary[], proposals[], prComments{}
+ changedFiles: string[];
+}
+
+// === ReportPackage (report.json — renderer input; Evidence + agent narrative) ===
+// The agent adds these fields in Phase 5; render.js consumes the whole thing.
+
+interface ReportPackage extends Evidence {
+ summary: string; // HTML
+ clusters: { assessment: string }; // narrative prose — distinct from checks.clusters
+ guidedWalk: { title; badge; badgeText; body }[];
+ findings: { title; snippet; body }[];
+ openQuestions: { title; body; meta }[];
+ functionalTest?: { plan; results: { name; pass; output }[]; observations };
+ appendixFunctional?: { environment; testCode; fullOutput };
}
```
diff --git a/.skills/tinker-review/scripts/patterns/architecture.js b/.skills/tinker-review/scripts/patterns/architecture.js
index 1a510ad414..9c772d881d 100644
--- a/.skills/tinker-review/scripts/patterns/architecture.js
+++ b/.skills/tinker-review/scripts/patterns/architecture.js
@@ -33,7 +33,19 @@ const { process: { t } } = gremlin;
* @param {object} [params.clusterResult] - Output from clusterAnalysis() (connectedComponent clusters)
* @param {boolean} [params.changedOnly] - Only include changed files (default: false)
* @param {number} [params.maxNodes] - Cap on nodes to render (default: 40)
- * @returns {Promise<{nodes: Array, edges: Array}>}
+ * @returns {Promise<ArchitectureResult>}
+ */
+
+/**
+ * @typedef {Object} ArchitectureNode
+ * @property {string} id
+ * @property {string} label
+ * @property {string} cluster the cluster/community the node belongs to
+ * @property {boolean} changed whether the PR modified it
+ *
+ * @typedef {Object} ArchitectureResult
+ * @property {ArchitectureNode[]} nodes
+ * @property {{from: string, to: string}[]} edges directed dependency edges between nodes
*/
export async function architecture(g, params = {}) {
const { clusterResult, changedOnly = false, maxNodes = 40 } = params;
diff --git a/.skills/tinker-review/scripts/patterns/blast-radius.js b/.skills/tinker-review/scripts/patterns/blast-radius.js
index be96bda19e..9e823e56bd 100644
--- a/.skills/tinker-review/scripts/patterns/blast-radius.js
+++ b/.skills/tinker-review/scripts/patterns/blast-radius.js
@@ -40,6 +40,25 @@ const INHERENTLY_CENTRAL = new Set([
* @param {boolean} [params.changedOnly] - Start from changed functions only (default: true)
* @returns {Promise<BlastRadiusResult>}
*/
+
+/**
+ * @typedef {Object} BlastRadiusFn
+ * @property {string} name
+ * @property {string} filePath
+ * @property {string} signature
+ * @property {number} linesStart
+ * @property {number} linesEnd
+ * @property {boolean} changed whether the PR modified this function
+ * @property {number} reachableCount callers reachable within `depth` hops upstream; high = the
+ * change ripples widely (for driver/server this is expected)
+ * @property {number} depth hop limit used for this row
+ *
+ * @typedef {Object} BlastRadiusResult
+ * @property {BlastRadiusFn[]} functions changed functions and how far each one's change reaches
+ * @property {number} maxReachable largest reachableCount across changed functions
+ * @property {number} totalWithCallers changed functions that have any upstream callers
+ * @property {number} depth hop limit applied
+ */
export async function blastRadius(g, params = {}) {
const depth = params.depth || 3;
const changedOnly = params.changedOnly !== false;
diff --git a/.skills/tinker-review/scripts/patterns/centrality.js b/.skills/tinker-review/scripts/patterns/centrality.js
index d891533270..2e67be304c 100644
--- a/.skills/tinker-review/scripts/patterns/centrality.js
+++ b/.skills/tinker-review/scripts/patterns/centrality.js
@@ -46,6 +46,27 @@ const INHERENTLY_CENTRAL = new Set([
* Only takes effect once classifyExternals has tagged `origin`.
* @returns {Promise<CentralityResult>}
*/
+
+/**
+ * @typedef {Object} Hotspot
+ * @property {string} name
+ * @property {string} filePath
+ * @property {string} signature
+ * @property {number} linesStart
+ * @property {number} linesEnd
+ * @property {boolean} changed whether the PR modified this function
+ * @property {number} inDegree incoming call edges (how many functions call it)
+ * @property {number} outDegree outgoing call edges, excluding origin:library targets
+ * @property {number} totalDegree inDegree + outDegree — the centrality score
+ * @property {boolean} inherentlyCentral a boilerplate method (equals/toString/…) central by
+ * nature; surfaced only when the PR modified it
+ *
+ * @typedef {Object} CentralityResult
+ * @property {Hotspot[]} hotspots top functions by totalDegree (>= minDegree)
+ * @property {number} totalAnalyzed functions considered
+ * @property {number} aboveThreshold how many cleared minDegree
+ * @property {number} filteredAsBoilerplate inherently-central, unchanged functions dropped
+ */
export async function highCentrality(g, params = {}) {
const changedOnly = params.changedOnly !== false;
const topN = params.topN || 10;
diff --git a/.skills/tinker-review/scripts/patterns/classify-externals.js b/.skills/tinker-review/scripts/patterns/classify-externals.js
index 20562362f1..e242d3f753 100644
--- a/.skills/tinker-review/scripts/patterns/classify-externals.js
+++ b/.skills/tinker-review/scripts/patterns/classify-externals.js
@@ -50,7 +50,15 @@ async function definedAsProjectType(name, repoPath) {
*
* @param {object} g - gremlin-js GraphTraversalSource (already connected)
* @param {string} repoPath - a git worktree to grep for project type definitions
- * @returns {Promise<{total: number, library: string[], project: object[], unresolved: string[]}>}
+ * @returns {Promise<ExternalsResult>}
+ */
+
+/**
+ * @typedef {Object} ExternalsResult
+ * @property {number} total external-callee stubs classified
+ * @property {string[]} library names judged JDK/accessor noise (dropped from centrality out-degree)
+ * @property {{name: string, definedIn: string}[]} project names a repo type declares, with the file
+ * @property {string[]} unresolved neither a known library name nor a project type — unknown
*/
export async function classifyExternals(g, repoPath) {
const names = await g.V().hasLabel("Function").has("external", true).values("name").toList();
diff --git a/.skills/tinker-review/scripts/patterns/cluster-analysis.js b/.skills/tinker-review/scripts/patterns/cluster-analysis.js
index f446dc754e..2017e3d69a 100644
--- a/.skills/tinker-review/scripts/patterns/cluster-analysis.js
+++ b/.skills/tinker-review/scripts/patterns/cluster-analysis.js
@@ -29,6 +29,19 @@
* @param {boolean} [params.changedOnly] - Only analyze changed files (default: true)
* @returns {Promise<ClusterResult>}
*/
+
+/**
+ * @typedef {Object} Cluster
+ * @property {number} id 1-based cluster index (largest first)
+ * @property {string[]} files file paths in this connected component
+ * @property {number} size files.length
+ *
+ * @typedef {Object} ClusterResult
+ * @property {number} clusterCount disconnected components among changed files
+ * @property {boolean} coherent true when the change is one logical unit (<= 1 cluster)
+ * @property {Cluster[]} clusters components, largest first
+ * @property {number} totalFiles changed files placed into clusters
+ */
export async function clusterAnalysis(a, params = {}) {
const changedOnly = params.changedOnly !== false;
diff --git a/.skills/tinker-review/scripts/patterns/completeness.js b/.skills/tinker-review/scripts/patterns/completeness.js
index 788d6faf7c..a4630edaed 100644
--- a/.skills/tinker-review/scripts/patterns/completeness.js
+++ b/.skills/tinker-review/scripts/patterns/completeness.js
@@ -31,6 +31,14 @@ import gremlin from "gremlin";
* e.g., ["out:has_rule", "in:implements_step", "in:covers", "in:documents"]
* @returns {Promise<CompletenessResult[]>}
*/
+
+/**
+ * @typedef {Object} CompletenessResult
+ * @property {string} node the vertex checked (name or identifier)
+ * @property {string[]} present expected edge specs that exist (e.g. "out:defines")
+ * @property {string[]} missing expected edge specs that are absent — the gaps to weigh
+ * @property {number} score present / (present + missing), 0..1
+ */
export async function completeness(g, params) {
const { vertexLabel, vertexName, expectedEdges } = params;
diff --git a/.skills/tinker-review/scripts/patterns/confidence-audit.js b/.skills/tinker-review/scripts/patterns/confidence-audit.js
index db8442694f..29d6cb326f 100644
--- a/.skills/tinker-review/scripts/patterns/confidence-audit.js
+++ b/.skills/tinker-review/scripts/patterns/confidence-audit.js
@@ -47,7 +47,22 @@ function describeVertex(elementMap) {
* @param {object} g - gremlin-js GraphTraversalSource (already connected)
* @param {object} [params]
* @param {number} [params.maxAmbiguous] - Cap the AMBIGUOUS edge list (default 50)
- * @returns {Promise<{distribution: object, total: number, ambiguous: object[]}>}
+ * @returns {Promise<ConfidenceResult>}
+ */
+
+/**
+ * @typedef {Object} EdgeConfidenceRow
+ * @property {string} relation edge label (calls, implements_step, addresses, …)
+ * @property {string} [confidence] the edge's confidence value
+ * @property {string} from described source vertex, e.g. "Function(foo)"
+ * @property {string} to described target vertex
+ * @property {string} [foundIn] provenance for discussion links (pr, search, …)
+ * @property {string} [foundVia]
+ *
+ * @typedef {Object} ConfidenceResult
+ * @property {{EXTRACTED:number, INFERRED:number, AMBIGUOUS:number, UNTAGGED:number}} distribution edge counts by confidence
+ * @property {number} total count of all edges
+ * @property {EdgeConfidenceRow[]} ambiguous AMBIGUOUS edges — flagged for human review
*/
export async function confidenceAudit(g, params = {}) {
const maxAmbiguous = params.maxAmbiguous || 50;
@@ -89,7 +104,7 @@ export async function confidenceAudit(g, params = {}) {
* @param {string} [opts.confidence] - Filter to this confidence value
* @param {string} [opts.relation] - Filter to this edge label (e.g. implements_step)
* @param {number} [opts.limit] - Cap the result count (default 100)
- * @returns {Promise<object[]>} rows of { relation, confidence, from, to, foundIn, foundVia }
+ * @returns {Promise<EdgeConfidenceRow[]>}
*/
export async function listEdgesByConfidence(g, opts = {}) {
const { confidence, relation, limit = 100 } = opts;
@@ -128,7 +143,7 @@ export async function listEdgesByConfidence(g, opts = {}) {
* @param {object} [params]
* @param {string} [params.relation] - Narrow to one relation (e.g. implements_step)
* @param {number} [params.limit] - Cap results (default 100)
- * @returns {Promise<object[]>}
+ * @returns {Promise<EdgeConfidenceRow[]>}
*/
export async function listInferred(g, params = {}) {
return listEdgesByConfidence(g, {
diff --git a/.skills/tinker-review/scripts/patterns/coverage-gaps.js b/.skills/tinker-review/scripts/patterns/coverage-gaps.js
index b570fea2e7..20cee1b7de 100644
--- a/.skills/tinker-review/scripts/patterns/coverage-gaps.js
+++ b/.skills/tinker-review/scripts/patterns/coverage-gaps.js
@@ -27,6 +27,20 @@ import gremlin from "gremlin";
* @param {boolean} [params.changedOnly] - Only check functions with changed=true (default: true)
* @returns {Promise<CoverageGapResult>}
*/
+
+/**
+ * @typedef {Object} UncoveredFunction
+ * @property {string} name
+ * @property {string} signature
+ * @property {string} filePath
+ * @property {number} linesStart
+ * @property {number} linesEnd
+ *
+ * @typedef {Object} CoverageGapResult
+ * @property {UncoveredFunction[]} uncovered changed functions with no incoming `tests` edge
+ * @property {number} totalChanged changed functions considered
+ * @property {number} totalCovered changed functions that do have a test
+ */
export async function coverageGaps(g, params = {}) {
const changedOnly = params.changedOnly !== false;
diff --git a/.skills/tinker-review/scripts/patterns/orphans.js b/.skills/tinker-review/scripts/patterns/orphans.js
index 2cafaa7021..b9ef966dd1 100644
--- a/.skills/tinker-review/scripts/patterns/orphans.js
+++ b/.skills/tinker-review/scripts/patterns/orphans.js
@@ -32,6 +32,19 @@ import gremlin from "gremlin";
* @param {boolean} [params.changedOnly] - Only check changed vertices (default: false)
* @returns {Promise<OrphanResult>}
*/
+
+/**
+ * @typedef {Object} Orphan
+ * @property {string} name
+ * @property {string} label vertex label checked (Function, Step, …)
+ * @property {string} filePath
+ * @property {string} missingEdge the expected relationship that is absent (e.g. "in:tests")
+ *
+ * @typedef {Object} OrphanResult
+ * @property {Orphan[]} orphaned vertices missing the expected relationship
+ * @property {number} totalChecked vertices examined
+ * @property {number} totalOrphaned orphaned.length
+ */
export async function orphans(g, params) {
const { vertexLabel, expectedEdge } = params;
const direction = params.direction || "in";
diff --git a/.skills/tinker-review/scripts/review.js b/.skills/tinker-review/scripts/review.js
index 65863f08e5..09c42c491b 100644
--- a/.skills/tinker-review/scripts/review.js
+++ b/.skills/tinker-review/scripts/review.js
@@ -36,6 +36,7 @@ import { clusterAnalysis } from "./patterns/cluster-analysis.js";
import { architecture } from "./patterns/architecture.js";
import { confidenceAudit } from "./patterns/confidence-audit.js";
import { classifyExternals } from "./patterns/classify-externals.js";
+import { orphans } from "./patterns/orphans.js";
import { createPrDiscussion } from "./enrichment/api.js";
import { discoverDiscussions } from "./discovery/discussions.js";
@@ -311,12 +312,14 @@ export async function phase1(session) {
const blastResult = await blastRadius(g, { depth: 3, changedOnly: true });
const clusterResult = await clusterAnalysis(a, { changedOnly: true });
const confidenceResult = await confidenceAudit(g);
+ const orphansResult = await orphans(g, { vertexLabel: "Function", expectedEdge: "tests", direction: "in", changedOnly: true });
log(` completeness: ${completenessResults.filter(r => r.missing.length > 0).length} gaps found`);
log(` coverage_gaps: ${coverageResult.uncovered.length} functions without tests`);
log(` centrality: ${centralityResult.aboveThreshold} hotspots`);
log(` blast_radius: max ${blastResult.maxReachable} reachable`);
log(` clusters: ${clusterResult.clusterCount} (${clusterResult.coherent ? "coherent" : "fragmented"})`);
log(` confidence: ${confidenceResult.distribution.EXTRACTED} extracted / ${confidenceResult.distribution.INFERRED} inferred / ${confidenceResult.distribution.AMBIGUOUS} ambiguous`);
+ log(` orphans: ${orphansResult.totalOrphaned} functions with no test`);
log(`Generating architecture map...`);
const architectureResult = await architecture(g, { clusterResult, changedOnly: true });
@@ -341,6 +344,7 @@ export async function phase1(session) {
clusters: clusterResult,
confidence: confidenceResult,
externals: externalsResult,
+ orphans: orphansResult,
},
discussions,
changedFiles,
(tinkerpop) 04/07: skills: add DESIGN.md for tinker-review, tinker-dev, tinker-doc
Posted by sp...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 62baef164c89ecdd0009a459d05018c72845d120
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Fri Jul 3 16:35:43 2026 -0400
skills: add DESIGN.md for tinker-review, tinker-dev, tinker-doc
Document how each skill is built and how to change it — distinct from the
operational guidance in SKILL.md. tinker-review carries real machinery (module
map, evidence.json -> report.json data flow, extension points); the guidance
skills document their information architecture and where new content goes. Also
model tinker-review as two phases (deterministic / agent-driven) and drop an
invented "Phase 5" reference.
Assisted-by: Claude Code:claude-opus-4-8
---
.skills/tinker-dev/DESIGN.md | 38 ++++++++++++++++++++
.skills/tinker-doc/DESIGN.md | 33 +++++++++++++++++
.skills/tinker-review/DESIGN.md | 78 +++++++++++++++++++++++++++++++++++++++++
.skills/tinker-review/SKILL.md | 2 +-
4 files changed, 150 insertions(+), 1 deletion(-)
diff --git a/.skills/tinker-dev/DESIGN.md b/.skills/tinker-dev/DESIGN.md
new file mode 100644
index 0000000000..4ad70ab7e3
--- /dev/null
+++ b/.skills/tinker-dev/DESIGN.md
@@ -0,0 +1,38 @@
+# tinker-dev — Design
+
+How this skill is structured and how to change it. The development guidance
+itself — build recipes, the validation matrix, conventions, beads rules — is the
+skill's *content* and lives in `SKILL.md` and `references/`. This document is only
+the shape of the artifact and where new content goes.
+
+## Structure
+
+A guidance skill, not a program:
+
+| Path | Role |
+|------|------|
+| `SKILL.md` | the operational index — the guidance a reader needs up front |
+| `references/*.md` | deep, task-specific material, loaded on demand |
+| `scripts/check-env.sh` | environment preflight |
+
+It carries no logic of its own; its effect is what a reader does after reading it.
+
+## How to change it — where content goes
+
+Two rules govern the shape, so every change is a routing decision:
+
+- **Single source of truth — defer, don't duplicate.** General agent rules live
+ in the root `AGENTS.md`; canonical facts live in the repo (`CONTRIBUTING.md`,
+ `docs/src/`, `bin/asf-license-header.txt`). New guidance points at its source
+ and repeats only the TinkerPop-specific thing that is easy to miss. A fact
+ copied here drifts from its source — so it isn't.
+- **Progressive disclosure.** `SKILL.md` stays a lean index; anything deep or
+ task-specific becomes a `references/` file linked from it, never inlined.
+
+Applying them:
+
+- A **general** agent rule → root `AGENTS.md`, not here.
+- A **TinkerPop-specific, easy-to-miss** convention → a bullet in `SKILL.md`,
+ deferring to the canonical file.
+- A **new validation rule** → the Definition-of-Done matrix in `SKILL.md`.
+- A **new deep topic** → a `references/` file, linked from `SKILL.md`.
diff --git a/.skills/tinker-doc/DESIGN.md b/.skills/tinker-doc/DESIGN.md
new file mode 100644
index 0000000000..b7fd2d679c
--- /dev/null
+++ b/.skills/tinker-doc/DESIGN.md
@@ -0,0 +1,33 @@
+# tinker-doc — Design
+
+How this skill is structured and how to change it. The documentation guidance
+itself — per-book voice, house style, the executable-block rules — is the skill's
+*content* and lives in `SKILL.md` and `references/`. This document is only the
+shape of the artifact and where new content goes.
+
+## Structure
+
+A guidance skill, not a program:
+
+| Path | Role |
+|------|------|
+| `SKILL.md` | the book map, house style, and the load-bearing rules up front |
+| `references/*.md` | the voice guide and authoring mechanics, loaded on demand |
+
+## How to change it — where content goes
+
+Two rules govern the shape, so every change is a routing decision:
+
+- **Single source of truth — defer, don't duplicate.** Guidance that overlaps
+ development (build/validation, changelog discipline) defers to **tinker-dev**
+ rather than being restated. Canonical documentation lives under `docs/src/`.
+- **Progressive disclosure.** `SKILL.md` holds the rule; the details live in a
+ `references/` file linked from it.
+
+Applying them:
+
+- A **new book or audience** → a row in the book map in `SKILL.md`, plus a voice
+ entry in `references/books-and-voice.md`.
+- A **new authoring mechanic** → `references/executable-blocks.md` or
+ `references/asciidoc-and-wiring.md`; keep `SKILL.md` to the rule, not the how.
+- A **new house-style rule** → the House style list in `SKILL.md`.
diff --git a/.skills/tinker-review/DESIGN.md b/.skills/tinker-review/DESIGN.md
new file mode 100644
index 0000000000..de4cde0700
--- /dev/null
+++ b/.skills/tinker-review/DESIGN.md
@@ -0,0 +1,78 @@
+# tinker-review — Design
+
+How the skill is built and how to change it. What a review *does* and the
+guidance it applies live in `SKILL.md`, the playbooks, and `references/`. This
+document is only the machinery and its extension points.
+
+## How it works
+
+The pipeline is two phases, split by what is mechanical and what needs judgment.
+
+**Phase 1 — deterministic** (`scripts/review.js`) builds the graph and writes
+`evidence.json`: fetch PR → worktree → start Gremlin Server → tree-sitter
+extract → populate → discover discussions → run the structural checks. It exits
+cleanly (a `PHASE1_COMPLETE` sentinel) so a caller can detect completion; the
+Gremlin Server container stays up.
+
+**Phase 2 — agent-driven** does everything that needs judgment: enrich the graph
+via the enrichment CLI, an optional functional test, then the report. It ends by
+tearing down the container and worktree.
+
+Data flows one direction through three artifacts:
+
+```
+source → [Phase 1] → evidence.json → [agent adds narrative] → report.json → [renderer] → HTML
+```
+
+The knowledge graph is a live **Gremlin Server (TinkerGraph)** — the skill
+dogfoods TinkerPop. Phase 1 talks to it directly; Phase 2 opens a fresh
+connection per enrichment CLI call, because the process that populated the graph
+has already exited.
+
+### Module map
+
+| Path | Role |
+|------|------|
+| `scripts/review.js` | Phase 1 orchestrator — `setup` / `phase1` / `teardown` |
+| `scripts/extraction/tree-sitter.js` | source → structural extraction |
+| `scripts/graph/*.js` | populate the graph; `confidence.js` / `externals.js` hold the data-model vocabularies |
+| `scripts/patterns/*.js` | one structural check per file; each defines its own result `@typedef` |
+| `scripts/enrichment/{api,cli}.js` | Phase 2 read/write commands over the live graph |
+| `scripts/renderer/{render.js,template.html}` | `report.json` → HTML |
+| `playbooks/*.md` | domain review guidance — prompt scaffolds, not code |
+| `references/{schema,interfaces}.md` | the graph schema and the evidence composite |
+
+## Constraints that bound a change
+
+- **One source of truth per fact.** Each check's result shape is a `@typedef` in
+ the pattern file that produces it; `references/interfaces.md` holds only the
+ composite `Evidence` / `ReportPackage` and points at those typedefs. The graph
+ schema lives once in `references/schema.md`. Never re-declare a shape in a
+ second place.
+- **Type docs carry meaning.** A `@typedef` field gets a prose line saying what
+ it means and how to weigh it, not just its type — that is what the Interpret
+ sections and the reviewer consume.
+- **Plain JS + JSDoc, no build step.** The skill runs under `node` directly.
+ Don't add TypeScript, a bundler, or a compile step.
+- **Edges obey the data model.** Every edge carries a `confidence`
+ (`EXTRACTED | INFERRED | AMBIGUOUS`); an edge whose endpoint may fall outside
+ the changed set is created find-or-create against a marker vertex so it can't
+ silently vanish. A new edge must follow both.
+- **Mechanical vs judgment decides where code goes.** Anything reproducible is a
+ Phase-1 module; anything needing judgment is a Phase-2 command the agent drives
+ from a playbook. That boundary tells you where a new capability belongs.
+
+## How to change it
+
+- **Add a structural check** — new `scripts/patterns/<name>.js` exporting the
+ function and its result `@typedef`; call it in `review.js` Phase 1 and add it
+ to `evidence.checks`; add the type to `Evidence` in `interfaces.md`; reference
+ it from the relevant playbook's Interpret.
+- **Add an enrichment command** — a function in `scripts/enrichment/api.js` (or a
+ pattern module), wired into `cli.js` (COMMANDS + help + switch), documented in
+ `SKILL.md`. Edge-creating commands take a `confidence`, default `INFERRED`.
+- **Add a playbook** — four sections (Context / Enrich / Interpret / Escape);
+ Enrich uses real commands, Interpret cites `evidence.json` fields; add a
+ routing rule in `SKILL.md`.
+- **Add an edge or vertex type** — document it in `references/schema.md`; tag new
+ edges with `confidence`; use find-or-create for cross-boundary endpoints.
diff --git a/.skills/tinker-review/SKILL.md b/.skills/tinker-review/SKILL.md
index b4291613d8..8e0e808af1 100644
--- a/.skills/tinker-review/SKILL.md
+++ b/.skills/tinker-review/SKILL.md
@@ -71,7 +71,7 @@ a phase of this run — this is the contract for what to do with the content:
|---------|------|---------------------|
| **Context** | framing | Orient to the change type and its risks; not actioned directly. |
| **Enrich** | Phase 2 | Execute the listed steps using the enrichment CLI commands. |
-| **Interpret** | Phase 5 | When writing the report, weigh the named `evidence.json` fields into `findings` / `openQuestions`. |
+| **Interpret** | Phase 2 (report) | When writing the report, weigh the named `evidence.json` fields into `findings` / `openQuestions`. |
| **Escape** | any phase | Check the stop/escalate conditions; halt or flag when one holds. |
Phase 1 already computes every structural check — completeness, coverageGaps,
(tinkerpop) 07/07: tinker-review: clarify playbook selection and section roles
Posted by sp...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 92c0d512919926a6be2f44ee6e64deb5adfd68f4
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Fri Jul 3 17:40:39 2026 -0400
tinker-review: clarify playbook selection and section roles
Section 2 now selects domain playbooks in two passes — orient from file paths to
candidates, then confirm each via its Context section. Context becomes an
applicability gate (a path can match a playbook that doesn't fit) rather than
unactioned framing, giving every section a real job. The section contract lists
an activity-based "used when" (choosing playbooks / improving the graph / writing
the report / any time) instead of opaque phase labels. DESIGN.md's add-a-playbook
note matches.
Assisted-by: Claude Code:claude-opus-4-8
---
.skills/tinker-review/DESIGN.md | 7 +++---
.skills/tinker-review/SKILL.md | 50 +++++++++++++++++++++--------------------
2 files changed, 30 insertions(+), 27 deletions(-)
diff --git a/.skills/tinker-review/DESIGN.md b/.skills/tinker-review/DESIGN.md
index 4adda0eb51..07c493485f 100644
--- a/.skills/tinker-review/DESIGN.md
+++ b/.skills/tinker-review/DESIGN.md
@@ -77,8 +77,9 @@ has already exited.
- **Add an enrichment command** — a function in `scripts/enrichment/api.js` (or a
pattern module), wired into `cli.js` (COMMANDS + help + switch), documented in
`SKILL.md`. Edge-creating commands take a `confidence`, default `INFERRED`.
-- **Add a playbook** — four sections (Context / Enrich / Interpret / Escape);
- Enrich uses real commands, Interpret cites `evidence.json` fields; add a
- routing rule in `SKILL.md`.
+- **Add a playbook** — four sections, each with a job: **Context** states when
+ the playbook applies (an applicability gate, read while choosing playbooks),
+ **Enrich** uses real enrichment commands, **Interpret** cites `evidence.json`
+ fields, **Escape** sets stop/escalate gates. Add an orient rule in `SKILL.md`.
- **Add an edge or vertex type** — document it in `references/schema.md`; tag new
edges with `confidence`; use find-or-create for cross-boundary endpoints.
diff --git a/.skills/tinker-review/SKILL.md b/.skills/tinker-review/SKILL.md
index c11faa41b1..9926c22e90 100644
--- a/.skills/tinker-review/SKILL.md
+++ b/.skills/tinker-review/SKILL.md
@@ -32,7 +32,7 @@ When invoked with `/review <pr-number>`:
The run has two phases (see [DESIGN.md](DESIGN.md)). **Phase 1** (step 1) is
deterministic and builds the graph. **Phase 2** (steps 3–5) is agent-driven —
-enrichment, an optional functional test, then the report. Step 2 loads the
+enrichment, an optional functional test, then the report. Step 2 chooses the
playbooks that guide Phase 2; step 6 tears down.
### 1. Setup + Phase 1 (deterministic)
@@ -55,29 +55,31 @@ coverage gaps, centrality, blast radius, cluster analysis) → write evidence JS
If re-running, the script cleans up stale worktrees/branches automatically.
-### 2. Classify and Load Playbooks
-
-**Always load** `playbooks/general.md` — it applies to every PR.
-
-Then determine which domain-specific playbooks apply from changed file paths:
-- `gremlin-dart/`, `gremlin-go/`, `gremlin-python/`, `gremlin-dotnet/`, `gremlin-js/` → `playbooks/glv.md`
-- `gremlin-core/` with new step patterns → `playbooks/new-step.md`
-- `gremlin-driver/`, `gremlin-server/`, `gremlin-util/` → `playbooks/driver-server.md`
-- Small change set with linked issue → `playbooks/bug-fix.md`
-- `gremlin-language/` or `*.g4` → `playbooks/grammar.md`
-- Deletion-heavy change set (removes a feature/module/dependency; `listDeleted` returns entries) → `playbooks/removal.md`
-
-Load ALL matching playbooks. Execute enrichment for each in sequence.
-
-**How a playbook is applied.** Each playbook has four sections, and each maps to
-a phase of this run — this is the contract for what to do with the content:
-
-| Section | When | What you do with it |
-|---------|------|---------------------|
-| **Context** | framing | Orient to the change type and its risks; not actioned directly. |
-| **Enrich** | Phase 2 | Execute the listed steps using the enrichment CLI commands. |
-| **Interpret** | Phase 2 (report) | When writing the report, weigh the named `evidence.json` fields into `findings` / `openQuestions`. |
-| **Escape** | any phase | Check the stop/escalate conditions; halt or flag when one holds. |
+### 2. Choose the playbooks
+
+Playbooks carry the domain judgment for Phase 2. `general.md` always applies;
+select the domain playbooks in two passes:
+
+1. **Orient** — from the changed file paths, gather the candidates:
+ - `gremlin-dart/`, `gremlin-go/`, `gremlin-python/`, `gremlin-dotnet/`, `gremlin-js/` → `playbooks/glv.md`
+ - `gremlin-core/` with new step patterns → `playbooks/new-step.md`
+ - `gremlin-driver/`, `gremlin-server/`, `gremlin-util/` → `playbooks/driver-server.md`
+ - Small change set with linked issue → `playbooks/bug-fix.md`
+ - `gremlin-language/` or `*.g4` → `playbooks/grammar.md`
+ - Deletion-heavy change set (removes a feature/module/dependency; `listDeleted` returns entries) → `playbooks/removal.md`
+2. **Confirm** — read each candidate's **Context** and keep only the ones that
+ truly fit this PR. A path can match a playbook that doesn't apply: a
+ `gremlin-core/` change that adds no step, or a `gremlin-driver/` fix that's
+ really a bug-fix.
+
+Then apply each kept playbook's sections at the point each is used:
+
+| Section | Used when | What you do |
+|---------|-----------|-------------|
+| **Context** | choosing playbooks (above) | Confirm the path-matched playbook fits this PR; set aside the ones that don't. |
+| **Enrich** | improving the graph (step 3) | Run its enrichment CLI commands to add semantic edges. |
+| **Interpret** | writing the report (step 5) | Weigh the named `evidence.json` fields into `findings` / `openQuestions`. |
+| **Escape** | any time | Honor its stop/escalate gates; halt or flag when one holds. |
Phase 1 already computes every structural check — completeness, coverageGaps,
centrality, blastRadius, clusters, confidence, externals, orphans — into
(tinkerpop) 01/07: tinker-review: edge confidence tags + resilient graph population
Posted by sp...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 3cefc5c3431efe0e7117f976fe387b2bc032344a
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Fri Jul 3 11:03:12 2026 -0400
tinker-review: edge confidence tags + resilient graph population
Tag every graph edge EXTRACTED/INFERRED/AMBIGUOUS, with an auditConfidence
command and a Signal Confidence report panel so inferred/guessed links are
visible to the reviewer.
Stop dropping graph context: materialize external-callee and deleted/unparsed
File stubs so calls/tests/modifies edges no longer silently vanish, and report
the true vertex/edge totals. Fix a duplicate PR-discussion vertex that doubled
every PR-sourced edge, skip PR-deleted files during extraction (was crashing),
and exit Phase 1 cleanly so completion is detectable.
Assisted-by: Claude Code:claude-opus-4-8
---
.skills/tinker-review/SKILL.md | 15 +++-
.skills/tinker-review/references/schema.md | 33 ++++++++
.skills/tinker-review/scripts/enrichment/api.js | 19 +++--
.skills/tinker-review/scripts/enrichment/cli.js | 18 +++--
.../scripts/extraction/tree-sitter.js | 10 ++-
.skills/tinker-review/scripts/graph/confidence.js | 85 +++++++++++++++++++
.../scripts/graph/populate-discussions.js | 34 +++++---
.skills/tinker-review/scripts/graph/populate.js | 94 +++++++++++++++++++++-
.../scripts/patterns/confidence-audit.js | 94 ++++++++++++++++++++++
.skills/tinker-review/scripts/renderer/render.js | 46 ++++++++++-
.skills/tinker-review/scripts/review.js | 19 ++++-
11 files changed, 435 insertions(+), 32 deletions(-)
diff --git a/.skills/tinker-review/SKILL.md b/.skills/tinker-review/SKILL.md
index 084785509d..30f028258c 100644
--- a/.skills/tinker-review/SKILL.md
+++ b/.skills/tinker-review/SKILL.md
@@ -80,13 +80,20 @@ node scripts/enrichment/cli.js listFunctions --workDir /tmp/pr-review-<pr> --cha
node scripts/enrichment/cli.js listTypes --workDir /tmp/pr-review-<pr> --kind class
node scripts/enrichment/cli.js getCallsFrom --workDir /tmp/pr-review-<pr> --function <name> --file <path>
node scripts/enrichment/cli.js getCanonicalSteps --workDir /tmp/pr-review-<pr>
+node scripts/enrichment/cli.js auditConfidence --workDir /tmp/pr-review-<pr>
```
-**Write commands:**
+`auditConfidence` returns the edge confidence distribution and the list of
+AMBIGUOUS edges. Re-run it after enrichment to refresh the audit with the edges
+you added, then reflect any remaining AMBIGUOUS links in `openQuestions`.
+
+**Write commands** (edges you create default to `INFERRED`; pass
+`--confidence AMBIGUOUS` for a guess you want flagged, or `EXTRACTED` when the
+source states it directly):
```bash
-node scripts/enrichment/cli.js mapStep --workDir /tmp/pr-review-<pr> --function <name> --file <path> --step <canonicalName>
-node scripts/enrichment/cli.js linkDiscussion --workDir /tmp/pr-review-<pr> --url <url> --source jira --title <title>
-node scripts/enrichment/cli.js linkDoc --workDir /tmp/pr-review-<pr> --entity Step --name <name> --doc <path>
+node scripts/enrichment/cli.js mapStep --workDir /tmp/pr-review-<pr> --function <name> --file <path> --step <canonicalName> [--confidence INFERRED|AMBIGUOUS|EXTRACTED]
+node scripts/enrichment/cli.js linkDiscussion --workDir /tmp/pr-review-<pr> --url <url> --source jira --title <title> [--confidence ...]
+node scripts/enrichment/cli.js linkDoc --workDir /tmp/pr-review-<pr> --entity Step --name <name> --doc <path> [--confidence ...]
node scripts/enrichment/cli.js addGrammarRule --workDir /tmp/pr-review-<pr> --name <name>
node scripts/enrichment/cli.js annotate --workDir /tmp/pr-review-<pr> --label Function --name <name> --key <key> --value <value>
```
diff --git a/.skills/tinker-review/references/schema.md b/.skills/tinker-review/references/schema.md
index 03b833c3fb..22facca8d1 100644
--- a/.skills/tinker-review/references/schema.md
+++ b/.skills/tinker-review/references/schema.md
@@ -7,9 +7,25 @@
**File** `{ path, language, changed }`
A source file in the PR. `changed: true` if modified in this PR.
+*Stub Files* `{ path, language, changed: true, parsed: false, deleted }` are
+markers for changed files the extractor didn't parse, so the PR's `modifies`
+edge still lands. `deleted: true` means the PR removed the file (absent from the
+PR-head worktree); `deleted: false` means it's present but an unparsed type
+(non-code, or a non-primary language). Real Files have no `parsed` property, so
+select materialized files with `.hasNot("parsed")` and markers with
+`.has("parsed", false)`.
+
**Function** `{ name, signature, visibility, filePath, lines_start, lines_end, changed }`
A function or method. The primary unit of analysis.
+*External stub Functions* `{ name, external: true, resolved: false, changed: false }`
+are markers created when a `calls`/`tests` edge targets a function by name that
+wasn't extracted (a library/JDK call, or a function in a file this PR didn't
+change). They keep the edge from vanishing and let blast-radius/centrality see
+the call; they lack `filePath`/`signature`/`visibility`. Filter them out with
+`.has("external", false)` — or, since real Functions have no `external` property,
+`.hasNot("external")` — when you only want materialized code.
+
**Type** `{ name, kind, visibility, filePath }`
A class, interface, struct, or enum. `kind` is one of: class, interface, struct, enum.
@@ -43,6 +59,23 @@ A comment on a Discussion.
## Edges (14 labels)
+### Edge confidence (every edge)
+
+Every edge carries a `confidence` property recording how the relationship was
+established, so downstream analysis and the reviewer can separate observed fact
+from deduction:
+
+| Value | Meaning | Examples |
+|-------|---------|----------|
+| `EXTRACTED` | Explicitly present in source or the git diff | `defines`, `modifies`, `has_comment`, an `addresses` link stated in the PR body/diff (`found_in: pr`/`diff`) |
+| `INFERRED` | Reasonable deduction | `calls`/`tests` (resolved by name match), `proposed_in`, a cross-referenced `addresses` (`found_in: jira_body`/`devlist_body`), agent `implements_step`/`documents` mappings |
+| `AMBIGUOUS` | Uncertain; flagged for human review | keyword-search `addresses` (`found_in: search`), low-confidence agent guesses |
+
+Enrichment write commands (`mapStep`, `linkDiscussion`, `linkDoc`) accept an
+optional `--confidence` flag (default `INFERRED`). `auditConfidence` reports the
+distribution and lists every `AMBIGUOUS` edge; the review's structural appendix
+renders this as the **Signal Confidence** panel.
+
### Code relationships
| Edge | From | To | Meaning |
diff --git a/.skills/tinker-review/scripts/enrichment/api.js b/.skills/tinker-review/scripts/enrichment/api.js
index 5e6b370429..5508ed563b 100644
--- a/.skills/tinker-review/scripts/enrichment/api.js
+++ b/.skills/tinker-review/scripts/enrichment/api.js
@@ -20,6 +20,7 @@
import { readFile } from "node:fs/promises";
import { join } from "node:path";
import gremlin from "gremlin";
+import { CONFIDENCE, normalizeConfidence } from "../graph/confidence.js";
const { process: { statics: __ } } = gremlin;
@@ -81,7 +82,8 @@ export async function getCanonicalSteps(repoPath) {
// === Write operations ===
-export async function mapStep(g, functionName, filePath, canonicalStepName) {
+export async function mapStep(g, functionName, filePath, canonicalStepName, confidence) {
+ const conf = normalizeConfidence(confidence, CONFIDENCE.INFERRED);
const stepExists = await g.V().hasLabel("Step").has("name", canonicalStepName).hasNext();
if (!stepExists) {
await g.addV("Step")
@@ -94,13 +96,15 @@ export async function mapStep(g, functionName, filePath, canonicalStepName) {
.has("name", functionName)
.has("filePath", filePath)
.addE("implements_step")
+ .property("confidence", conf)
.to(__.V().hasLabel("Step").has("name", canonicalStepName))
.next();
- return { mapped: `${functionName} -> ${canonicalStepName}` };
+ return { mapped: `${functionName} -> ${canonicalStepName}`, confidence: conf };
}
-export async function linkDiscussion(g, url, source, title, body) {
+export async function linkDiscussion(g, url, source, title, body, confidence) {
+ const conf = normalizeConfidence(confidence, CONFIDENCE.INFERRED);
await g.addV("Discussion")
.property("url", url)
.property("source", source)
@@ -112,11 +116,12 @@ export async function linkDiscussion(g, url, source, title, body) {
if (prDiscussion) {
await g.V().hasLabel("Discussion").has("source", "pr")
.addE("addresses")
+ .property("confidence", conf)
.to(__.V().hasLabel("Discussion").has("url", url))
.next();
}
- return { linked: `${source}: ${title}` };
+ return { linked: `${source}: ${title}`, confidence: conf };
}
export async function annotate(g, label, name, key, value) {
@@ -127,7 +132,8 @@ export async function annotate(g, label, name, key, value) {
return { annotated: `${label}:${name}.${key} = ${value}` };
}
-export async function linkDoc(g, entityLabel, entityName, docPath, section) {
+export async function linkDoc(g, entityLabel, entityName, docPath, section, confidence) {
+ const conf = normalizeConfidence(confidence, CONFIDENCE.INFERRED);
const docExists = await g.V().hasLabel("Doc").has("path", docPath).hasNext();
if (!docExists) {
await g.addV("Doc")
@@ -138,10 +144,11 @@ export async function linkDoc(g, entityLabel, entityName, docPath, section) {
await g.V().hasLabel("Doc").has("path", docPath)
.addE("documents")
+ .property("confidence", conf)
.to(__.V().hasLabel(entityLabel).has("name", entityName))
.next();
- return { linked: `${docPath} documents ${entityLabel}:${entityName}` };
+ return { linked: `${docPath} documents ${entityLabel}:${entityName}`, confidence: conf };
}
export async function addGrammarRule(g, name, production) {
diff --git a/.skills/tinker-review/scripts/enrichment/cli.js b/.skills/tinker-review/scripts/enrichment/cli.js
index 4cf70ec498..c5f5099c22 100644
--- a/.skills/tinker-review/scripts/enrichment/cli.js
+++ b/.skills/tinker-review/scripts/enrichment/cli.js
@@ -25,12 +25,14 @@ import {
mapStep, linkDiscussion, linkDoc, addGrammarRule, annotate,
createPrDiscussion,
} from "./api.js";
+import { confidenceAudit } from "../patterns/confidence-audit.js";
const COMMANDS = {
listFunctions: { fn: listFunctions, needsG: true },
listTypes: { fn: listTypes, needsG: true },
getCallsFrom: { fn: getCallsFrom, needsG: true },
getCanonicalSteps: { fn: getCanonicalSteps, needsG: false },
+ auditConfidence: { fn: confidenceAudit, needsG: true },
mapStep: { fn: mapStep, needsG: true },
linkDiscussion: { fn: linkDiscussion, needsG: true },
linkDoc: { fn: linkDoc, needsG: true },
@@ -73,9 +75,10 @@ async function main() {
console.log(" listTypes [--kind class]");
console.log(" getCallsFrom --function <name> --file <path>");
console.log(" getCanonicalSteps");
- console.log(" mapStep --function <name> --file <path> --step <canonicalName>");
- console.log(" linkDiscussion --url <url> --source <jira|devlist|proposal> --title <title> [--body <body>]");
- console.log(" linkDoc --entity <label> --name <name> --doc <path> [--section <section>]");
+ console.log(" auditConfidence [--maxAmbiguous 50]");
+ console.log(" mapStep --function <name> --file <path> --step <canonicalName> [--confidence INFERRED|AMBIGUOUS|EXTRACTED]");
+ console.log(" linkDiscussion --url <url> --source <jira|devlist|proposal> --title <title> [--body <body>] [--confidence ...]");
+ console.log(" linkDoc --entity <label> --name <name> --doc <path> [--section <section>] [--confidence ...]");
console.log(" addGrammarRule --name <name> [--production <production>]");
console.log(" annotate --label <label> --name <name> --key <key> --value <value>");
console.log("");
@@ -124,14 +127,17 @@ async function main() {
case "getCanonicalSteps":
result = await fn(session.worktreePath || session.repoPath);
break;
+ case "auditConfidence":
+ result = await fn(g, { maxAmbiguous: args.maxAmbiguous });
+ break;
case "mapStep":
- result = await fn(g, args.function, args.file, args.step);
+ result = await fn(g, args.function, args.file, args.step, args.confidence);
break;
case "linkDiscussion":
- result = await fn(g, args.url, args.source, args.title, args.body);
+ result = await fn(g, args.url, args.source, args.title, args.body, args.confidence);
break;
case "linkDoc":
- result = await fn(g, args.entity, args.name, args.doc, args.section);
+ result = await fn(g, args.entity, args.name, args.doc, args.section, args.confidence);
break;
case "addGrammarRule":
result = await fn(g, args.name, args.production);
diff --git a/.skills/tinker-review/scripts/extraction/tree-sitter.js b/.skills/tinker-review/scripts/extraction/tree-sitter.js
index 6b9a89833a..661a67ccc6 100644
--- a/.skills/tinker-review/scripts/extraction/tree-sitter.js
+++ b/.skills/tinker-review/scripts/extraction/tree-sitter.js
@@ -549,7 +549,15 @@ export async function extract(directory, language, options = {}) {
};
for (const file of sourceFiles) {
- const content = await readFile(file.fullPath, "utf-8");
+ let content;
+ try {
+ content = await readFile(file.fullPath, "utf-8");
+ } catch (err) {
+ // A file in the PR's changed set that isn't on disk was deleted by the
+ // PR — there's no source to extract, so skip it rather than crash.
+ if (err.code === "ENOENT") continue;
+ throw err;
+ }
const tree = parser.parse(content);
if (!tree) continue;
diff --git a/.skills/tinker-review/scripts/graph/confidence.js b/.skills/tinker-review/scripts/graph/confidence.js
new file mode 100644
index 0000000000..bb3076ceac
--- /dev/null
+++ b/.skills/tinker-review/scripts/graph/confidence.js
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Edge confidence vocabulary. Every edge written into the knowledge graph
+ * carries a `confidence` property so downstream analysis (and the human
+ * reviewer) can tell what was observed directly from source versus what was
+ * deduced or guessed.
+ *
+ * EXTRACTED — explicitly present in the source: an AST definition, a git
+ * diff fact, a discussion link stated in the PR body/diff, a
+ * comment returned by the issue API for its parent thread.
+ * INFERRED — a reasonable deduction: a call/test edge resolved by name
+ * match, a cross-referenced discussion, an agent's step or doc
+ * mapping backed by evidence.
+ * AMBIGUOUS — uncertain; surfaced for human review. Keyword-search matches
+ * and low-confidence agent guesses land here.
+ */
+export const CONFIDENCE = Object.freeze({
+ EXTRACTED: "EXTRACTED",
+ INFERRED: "INFERRED",
+ AMBIGUOUS: "AMBIGUOUS",
+});
+
+const VALID = new Set(Object.values(CONFIDENCE));
+
+export function isValidConfidence(value) {
+ return VALID.has(value);
+}
+
+/**
+ * Normalize a caller-supplied confidence value, falling back to a default when
+ * missing or invalid. Enrichment write commands use this so a bad `--confidence`
+ * flag degrades to a sane default rather than poisoning the graph.
+ *
+ * @param {string|undefined} value
+ * @param {string} [fallback=CONFIDENCE.INFERRED]
+ * @returns {string}
+ */
+export function normalizeConfidence(value, fallback = CONFIDENCE.INFERRED) {
+ if (typeof value === "string") {
+ const upper = value.toUpperCase();
+ if (VALID.has(upper)) return upper;
+ }
+ return fallback;
+}
+
+/**
+ * Map a discussion-link `found_in` provenance to a confidence level.
+ * A link stated in the PR body or diff is EXTRACTED; a cross-reference found in
+ * another discussion's body is INFERRED; a keyword-search hit is AMBIGUOUS.
+ *
+ * @param {string|undefined} foundIn
+ * @returns {string}
+ */
+export function confidenceForFoundIn(foundIn) {
+ switch (foundIn) {
+ case "pr":
+ case "diff":
+ return CONFIDENCE.EXTRACTED;
+ case "search":
+ return CONFIDENCE.AMBIGUOUS;
+ case "jira_body":
+ case "devlist_body":
+ return CONFIDENCE.INFERRED;
+ default:
+ return CONFIDENCE.INFERRED;
+ }
+}
diff --git a/.skills/tinker-review/scripts/graph/populate-discussions.js b/.skills/tinker-review/scripts/graph/populate-discussions.js
index 996a3d5364..ea95c57f9d 100644
--- a/.skills/tinker-review/scripts/graph/populate-discussions.js
+++ b/.skills/tinker-review/scripts/graph/populate-discussions.js
@@ -18,6 +18,7 @@
*/
import gremlin from "gremlin";
+import { CONFIDENCE, confidenceForFoundIn } from "./confidence.js";
const { process: { statics: __ } } = gremlin;
@@ -49,15 +50,21 @@ export async function populateDiscussions(g, discussions, context) {
const prUrl = `https://github.com/apache/tinkerpop/pull/${context.pr}`;
- // Create the PR itself as a Discussion vertex
- await g.addV("Discussion")
- .property("url", prUrl)
- .property("source", "pr")
- .property("title", context.prTitle || `PR #${context.pr}`)
- .property("body", "")
- .next();
- counts.vertices++;
- counts.breakdown.discussions++;
+ // Create the PR itself as a Discussion vertex. Idempotent: review.js may have
+ // already created it via createPrDiscussion(). A duplicate PR vertex would make
+ // `.V().has("url", prUrl)` match two start vertices and double every PR-sourced
+ // edge (modifies, addresses, has_comment).
+ const prExists = await g.V().hasLabel("Discussion").has("url", prUrl).hasNext();
+ if (!prExists) {
+ await g.addV("Discussion")
+ .property("url", prUrl)
+ .property("source", "pr")
+ .property("title", context.prTitle || `PR #${context.pr}`)
+ .property("body", "")
+ .next();
+ counts.vertices++;
+ counts.breakdown.discussions++;
+ }
// Create Discussion vertices for JIRAs
for (const jira of discussions.jiras) {
@@ -158,6 +165,7 @@ export async function populateDiscussions(g, discussions, context) {
batch.push(
g.V().hasLabel("Discussion").has("url", prUrl)
.addE("has_comment")
+ .property("confidence", CONFIDENCE.EXTRACTED)
.to(__.V().hasLabel("Comment").has("author", comment.author).has("timestamp", comment.timestamp || ""))
);
counts.edges++;
@@ -169,6 +177,7 @@ export async function populateDiscussions(g, discussions, context) {
batch.push(
g.V().hasLabel("Discussion").has("url", prUrl)
.addE("has_comment")
+ .property("confidence", CONFIDENCE.EXTRACTED)
.to(__.V().hasLabel("Comment").has("author", comment.author).has("timestamp", comment.timestamp || ""))
);
counts.edges++;
@@ -182,6 +191,7 @@ export async function populateDiscussions(g, discussions, context) {
batch.push(
g.V().hasLabel("Discussion").has("url", jira.url)
.addE("has_comment")
+ .property("confidence", CONFIDENCE.EXTRACTED)
.to(__.V().hasLabel("Comment").has("author", comment.author).has("timestamp", comment.timestamp || ""))
);
counts.edges++;
@@ -196,6 +206,7 @@ export async function populateDiscussions(g, discussions, context) {
batch.push(
g.V().hasLabel("Discussion").has("url", sec.url)
.addE("has_comment")
+ .property("confidence", CONFIDENCE.EXTRACTED)
.to(__.V().hasLabel("Comment").has("author", comment.author).has("timestamp", comment.timestamp || ""))
);
counts.edges++;
@@ -210,6 +221,7 @@ export async function populateDiscussions(g, discussions, context) {
g.V().hasLabel("Discussion").has("url", prUrl)
.addE("addresses")
.property("found_in", jira.found_in || "pr")
+ .property("confidence", confidenceForFoundIn(jira.found_in || "pr"))
.to(__.V().hasLabel("Discussion").has("url", jira.url))
);
counts.edges++;
@@ -223,6 +235,7 @@ export async function populateDiscussions(g, discussions, context) {
g.V().hasLabel("Discussion").has("url", prUrl)
.addE("addresses")
.property("found_in", thread.found_in || "pr")
+ .property("confidence", confidenceForFoundIn(thread.found_in || "pr"))
.to(__.V().hasLabel("Discussion").has("url", thread.url))
);
counts.edges++;
@@ -240,6 +253,7 @@ export async function populateDiscussions(g, discussions, context) {
.addE("addresses")
.property("found_in", sec.found_in || "")
.property("found_via", sec.found_via || "")
+ .property("confidence", confidenceForFoundIn(sec.found_in))
.to(__.V().hasLabel("Discussion").has("url", sec.url))
);
counts.edges++;
@@ -252,6 +266,7 @@ export async function populateDiscussions(g, discussions, context) {
batch.push(
g.V().hasLabel("Discussion").has("source", "proposal").has("title", proposal.title)
.addE("proposed_in")
+ .property("confidence", CONFIDENCE.INFERRED)
.to(__.V().hasLabel("Discussion").has("url", prUrl))
);
counts.edges++;
@@ -264,6 +279,7 @@ export async function populateDiscussions(g, discussions, context) {
batch.push(
g.V().hasLabel("Discussion").has("url", prUrl)
.addE("modifies")
+ .property("confidence", CONFIDENCE.EXTRACTED)
.to(__.V().hasLabel("File").has("path", filePath))
);
counts.edges++;
diff --git a/.skills/tinker-review/scripts/graph/populate.js b/.skills/tinker-review/scripts/graph/populate.js
index 748dda561f..bc06379fbe 100644
--- a/.skills/tinker-review/scripts/graph/populate.js
+++ b/.skills/tinker-review/scripts/graph/populate.js
@@ -17,7 +17,10 @@
* under the License.
*/
+import { existsSync } from "node:fs";
+import { join } from "node:path";
import gremlin from "gremlin";
+import { CONFIDENCE } from "./confidence.js";
const { process: { statics: __ } } = gremlin;
@@ -34,13 +37,19 @@ async function submitBatch(batch) {
*
* @param {object} g - gremlin-js GraphTraversalSource (already connected)
* @param {ExtractionResult} extraction - Output from tree-sitter module
+ * @param {object} [options]
+ * @param {string[]} [options.changedFiles] - Full changed-file list for the PR
+ * (used to mark files the PR touched but the extractor didn't parse)
+ * @param {string} [options.worktreePath] - PR-head worktree, to tell a deleted
+ * file (absent on disk) from an unparsed one (present but not a parsed language)
* @returns {Promise<PopulationSummary>}
*/
-export async function populate(g, extraction) {
+export async function populate(g, extraction, options = {}) {
+ const { changedFiles = [], worktreePath = "" } = options;
const counts = {
vertices: 0,
edges: 0,
- breakdown: { files: 0, functions: 0, types: 0, tests: 0, calls: 0, defines: 0, testsEdges: 0 },
+ breakdown: { files: 0, functions: 0, types: 0, tests: 0, calls: 0, defines: 0, testsEdges: 0, externalFunctions: 0, stubFiles: 0 },
};
for (const file of extraction.files) {
@@ -53,6 +62,30 @@ export async function populate(g, extraction) {
counts.breakdown.files++;
}
+ // Mark changed files the extractor didn't parse. The PR's `modifies` edges
+ // target every changed file by path, but only parsed files (right language,
+ // present on disk) get a File vertex above — so a deleted or non-code file
+ // would have no vertex to land on and its `modifies` edge would vanish. Create
+ // a stub File as a marker (keyed by unique path, so it's race-free). A file
+ // absent from the PR-head worktree was deleted by the PR; one still on disk was
+ // simply not parsed (unsupported language). These markers are especially
+ // meaningful on removal PRs — they record exactly what the PR took out.
+ const extractedPaths = new Set(extraction.files.map((f) => f.path));
+ for (const filePath of changedFiles) {
+ if (extractedPaths.has(filePath)) continue;
+ const onDisk = worktreePath ? existsSync(join(worktreePath, filePath)) : true;
+ const ext = filePath.includes(".") ? filePath.split(".").pop() : "";
+ await g.addV("File")
+ .property("path", filePath)
+ .property("language", ext)
+ .property("changed", true)
+ .property("parsed", false)
+ .property("deleted", !onDisk)
+ .next();
+ counts.vertices++;
+ counts.breakdown.stubFiles++;
+ }
+
for (const fn of extraction.functions) {
await g.addV("Function")
.property("name", fn.name)
@@ -91,10 +124,51 @@ export async function populate(g, extraction) {
let batch = [];
+ // Resolve-or-mark callee vertices. Call/test edges target a function by name;
+ // when the callee isn't among the extracted functions (a library/JDK call, or
+ // a function in a file this PR didn't change) there is no vertex to land on
+ // and the edge would silently vanish. Materialize a lightweight "external"
+ // stub as a marker so the edge survives and downstream analysis (blast radius,
+ // centrality) can see the call. Stubs are keyed by unique name and created
+ // up front, so this is idempotent and race-free even under batched inserts.
+ // These MUST be flushed before the calls/tests edges below reference them.
+ const extractedFunctionNames = new Set(extraction.functions.map((f) => f.name));
+ const unresolvedCallees = new Set();
+ for (const call of extraction.calls) {
+ if (!extractedFunctionNames.has(call.calleeName)) unresolvedCallees.add(call.calleeName);
+ }
+ for (const test of tests) {
+ for (const calledFn of (test.calledFunctions || [])) {
+ if (!extractedFunctionNames.has(calledFn)) unresolvedCallees.add(calledFn);
+ }
+ }
+
+ for (const name of unresolvedCallees) {
+ batch.push(
+ g.addV("Function")
+ .property("name", name)
+ .property("external", true)
+ .property("resolved", false)
+ .property("changed", false)
+ );
+ counts.vertices++;
+ counts.breakdown.externalFunctions++;
+
+ if (batch.length >= BATCH_SIZE) {
+ await submitBatch(batch);
+ batch = [];
+ }
+ }
+ if (batch.length > 0) {
+ await submitBatch(batch);
+ batch = [];
+ }
+
for (const fn of extraction.functions) {
batch.push(
g.V().hasLabel("File").has("path", fn.filePath)
.addE("defines")
+ .property("confidence", CONFIDENCE.EXTRACTED)
.to(__.V().hasLabel("Function").has("name", fn.name).has("filePath", fn.filePath))
);
counts.edges++;
@@ -110,6 +184,7 @@ export async function populate(g, extraction) {
batch.push(
g.V().hasLabel("File").has("path", type.filePath)
.addE("defines")
+ .property("confidence", CONFIDENCE.EXTRACTED)
.to(__.V().hasLabel("Type").has("name", type.name).has("filePath", type.filePath))
);
counts.edges++;
@@ -122,11 +197,15 @@ export async function populate(g, extraction) {
}
for (const call of extraction.calls) {
+ // INFERRED: the call site is real, but the callee is resolved by name alone
+ // (it matches any Function with that name, across files/overloads), so the
+ // edge target is a deduction rather than a directly observed fact.
batch.push(
g.V().hasLabel("Function")
.has("name", call.callerName)
.has("filePath", call.callerFile)
.addE("calls")
+ .property("confidence", CONFIDENCE.INFERRED)
.to(__.V().hasLabel("Function").has("name", call.calleeName))
);
counts.edges++;
@@ -140,9 +219,11 @@ export async function populate(g, extraction) {
for (const test of tests) {
for (const calledFn of test.calledFunctions) {
+ // INFERRED: a test is linked to a function by name match on the callee.
batch.push(
g.V().hasLabel("Test").has("name", test.name).has("filePath", test.filePath)
.addE("tests")
+ .property("confidence", CONFIDENCE.INFERRED)
.to(__.V().hasLabel("Function").has("name", calledFn))
);
counts.edges++;
@@ -166,5 +247,14 @@ export async function populate(g, extraction) {
await submitBatch(batch);
}
+ // Report the true graph size. The per-type breakdown above counts attempted
+ // inserts; query the graph itself for the authoritative vertex/edge totals so
+ // the summary can't drift from reality (e.g. an edge whose endpoints matched
+ // multiple vertices, or a vertex insert that failed).
+ const realV = await g.V().count().next();
+ const realE = await g.E().count().next();
+ counts.vertices = Number(realV.value);
+ counts.edges = Number(realE.value);
+
return counts;
}
diff --git a/.skills/tinker-review/scripts/patterns/confidence-audit.js b/.skills/tinker-review/scripts/patterns/confidence-audit.js
new file mode 100644
index 0000000000..ddb5c6e30d
--- /dev/null
+++ b/.skills/tinker-review/scripts/patterns/confidence-audit.js
@@ -0,0 +1,94 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import gremlin from "gremlin";
+import { CONFIDENCE } from "../graph/confidence.js";
+
+const { process: { statics: __ } } = gremlin;
+
+// Pick a human-readable label for a vertex from whichever identifying property
+// it carries. Different labels key on different properties (Function/Type/Step
+// use name, File uses path, Discussion uses url/title).
+function describeVertex(elementMap) {
+ if (!elementMap) return "?";
+ const get = (k) => {
+ const v = elementMap.get ? elementMap.get(k) : elementMap[k];
+ return v == null ? undefined : String(v);
+ };
+ const labelKey = gremlin.process.t.label;
+ const label = (elementMap.get ? elementMap.get(labelKey) : elementMap["label"]) || "";
+ const name = get("name") || get("title") || get("path") || get("url") || "?";
+ return label ? `${label}(${name})` : name;
+}
+
+/**
+ * Audit the knowledge graph by edge confidence. Returns the distribution across
+ * EXTRACTED / INFERRED / AMBIGUOUS (plus UNTAGGED for any edge missing the
+ * property) and the full list of AMBIGUOUS edges — the ones flagged for human
+ * review. Since it reads the live graph it reflects enrichment edges too when
+ * run after Phase 2.
+ *
+ * @param {object} g - gremlin-js GraphTraversalSource (already connected)
+ * @param {object} [params]
+ * @param {number} [params.maxAmbiguous] - Cap the AMBIGUOUS edge list (default 50)
+ * @returns {Promise<{distribution: object, total: number, ambiguous: object[]}>}
+ */
+export async function confidenceAudit(g, params = {}) {
+ const maxAmbiguous = params.maxAmbiguous || 50;
+
+ // Distribution over every edge; edges predating this feature (or any we missed)
+ // fall into UNTAGGED so the audit stays honest about coverage.
+ const grouped = await g.E()
+ .groupCount()
+ .by(__.coalesce(__.values("confidence"), __.constant("UNTAGGED")))
+ .next();
+
+ const distribution = { EXTRACTED: 0, INFERRED: 0, AMBIGUOUS: 0, UNTAGGED: 0 };
+ let total = 0;
+ const gm = grouped.value;
+ if (gm) {
+ const entries = gm instanceof Map ? gm.entries() : Object.entries(gm);
+ for (const [key, count] of entries) {
+ const n = Number(count);
+ distribution[key] = (distribution[key] || 0) + n;
+ total += n;
+ }
+ }
+
+ const ambiguousRows = await g.E()
+ .has("confidence", CONFIDENCE.AMBIGUOUS)
+ .project("relation", "found_in", "found_via", "from", "to")
+ .by(__.label())
+ .by(__.coalesce(__.values("found_in"), __.constant("")))
+ .by(__.coalesce(__.values("found_via"), __.constant("")))
+ .by(__.outV().elementMap())
+ .by(__.inV().elementMap())
+ .limit(maxAmbiguous)
+ .toList();
+
+ const ambiguous = ambiguousRows.map((row) => ({
+ relation: row.get("relation"),
+ from: describeVertex(row.get("from")),
+ to: describeVertex(row.get("to")),
+ foundIn: row.get("found_in") || undefined,
+ foundVia: row.get("found_via") || undefined,
+ }));
+
+ return { distribution, total, ambiguous };
+}
diff --git a/.skills/tinker-review/scripts/renderer/render.js b/.skills/tinker-review/scripts/renderer/render.js
index ae18e32829..dbd71adbdb 100644
--- a/.skills/tinker-review/scripts/renderer/render.js
+++ b/.skills/tinker-review/scripts/renderer/render.js
@@ -39,7 +39,7 @@ function esc(str) {
* Input contract — data fields (from review.js):
* meta: { pr, title, domains: [], language, changedFileCount, timestamp }
* graphStats: { vertices, edges, breakdown: { files, functions, types, tests, calls } }
- * checks: { completeness, coverageGaps, centrality, blastRadius, clusters }
+ * checks: { completeness, coverageGaps, centrality, blastRadius, clusters, confidence }
* discussions: { jiras, devList, secondary, prComments, devListSearchKeywords, ... }
* changedFiles: []
*
@@ -345,11 +345,53 @@ function renderOpenQuestions(questions) {
return `<section id="open-questions">\n <h2>Open Questions</h2>\n ${cards}\n</section>`;
}
+function renderConfidence(confidence) {
+ if (!confidence || !confidence.distribution) return "";
+ const d = confidence.distribution;
+ const ambiguous = confidence.ambiguous || [];
+
+ const chip = (label, value, cls) =>
+ `<div class="stat-box"><div class="value">${value || 0}</div><div class="label">${label}</div></div>`;
+
+ let ambiguousHtml;
+ if (ambiguous.length === 0) {
+ ambiguousHtml = `<p class="section-intro">No AMBIGUOUS edges — nothing was linked purely by keyword search or low-confidence guess.</p>`;
+ } else {
+ const rows = ambiguous.map(a => {
+ const via = a.foundVia ? ` <span class="discovery-meta">via ${esc(a.foundVia)}</span>` : "";
+ const found = a.foundIn ? esc(a.foundIn) : "—";
+ return `<tr><td><code>${esc(a.relation)}</code></td><td class="fn-name">${esc(a.from)}</td><td class="fn-name">${esc(a.to)}${via}</td><td>${found}</td></tr>`;
+ }).join("\n ");
+ ambiguousHtml = `<table class="gap-table">
+ <thead><tr><th>Relation</th><th>From</th><th>To</th><th>Found in</th></tr></thead>
+ <tbody>\n ${rows}\n </tbody>
+ </table>`;
+ }
+
+ const untagged = d.UNTAGGED
+ ? `<div class="stat-box"><div class="value">${d.UNTAGGED}</div><div class="label">Untagged</div></div>`
+ : "";
+
+ return `
+ <h3>Signal Confidence</h3>
+ <p class="section-intro">Every graph edge is tagged by how it was established. <strong>EXTRACTED</strong> edges are observed directly in source or the git diff; <strong>INFERRED</strong> edges are name-resolved or evidence-backed deductions; <strong>AMBIGUOUS</strong> edges are keyword-search or low-confidence guesses and are listed below for human review.</p>
+ <div class="stats-grid">
+ ${chip("Extracted", d.EXTRACTED)}
+ ${chip("Inferred", d.INFERRED)}
+ ${chip("Ambiguous", d.AMBIGUOUS)}
+ ${untagged}
+ </div>
+ <h4 style="margin-top: 1rem;">Ambiguous edges (${ambiguous.length}) — verify before relying on</h4>
+ ${ambiguousHtml}
+`;
+}
+
function renderAppendixStructural(checks, graphStats) {
const hotspots = checks?.centrality?.hotspots || [];
const blast = checks?.blastRadius?.functions || [];
const stats = graphStats || {};
const bd = stats.breakdown || {};
+ const confidenceHtml = renderConfidence(checks?.confidence);
const hotspotRows = hotspots.slice(0, 10).map(h => {
const badge = (h.inherentlyCentral && h.changed) ? `<span class="badge badge-modified">modified</span>` : "";
@@ -377,7 +419,7 @@ function renderAppendixStructural(checks, graphStats) {
<thead><tr><th>Function</th><th>File</th><th>Reachable</th><th></th></tr></thead>
<tbody>\n ${blastRows}\n </tbody>
</table>
-
+${confidenceHtml}
<h3>Graph Statistics</h3>
<div class="stats-grid">
<div class="stat-box"><div class="value">${stats.vertices || 0}</div><div class="label">Vertices</div></div>
diff --git a/.skills/tinker-review/scripts/review.js b/.skills/tinker-review/scripts/review.js
index ebe50ffe99..bda97cd7b8 100644
--- a/.skills/tinker-review/scripts/review.js
+++ b/.skills/tinker-review/scripts/review.js
@@ -34,6 +34,7 @@ import { highCentrality } from "./patterns/centrality.js";
import { blastRadius } from "./patterns/blast-radius.js";
import { clusterAnalysis } from "./patterns/cluster-analysis.js";
import { architecture } from "./patterns/architecture.js";
+import { confidenceAudit } from "./patterns/confidence-audit.js";
import { createPrDiscussion } from "./enrichment/api.js";
import { discoverDiscussions } from "./discovery/discussions.js";
@@ -234,7 +235,8 @@ export async function setup(params) {
// ============================================================
// PHASE 1 — extract, populate, discover, run checks
-// Writes evidence JSON to workDir. Server stays alive.
+// Writes evidence JSON to workDir. The Gremlin Server container stays alive for
+// enrichment; the CLI process itself exits once Phase 1 completes (see main()).
// ============================================================
export async function phase1(session) {
@@ -245,7 +247,7 @@ export async function phase1(session) {
log(`Phase 1 complete: ${extraction.files.length} files, ${extraction.functions.length} functions, ${extraction.types.length} types`);
log(`Populating graph...`);
- const graphStats = await populate(g, extraction);
+ const graphStats = await populate(g, extraction, { changedFiles, worktreePath });
log(`Graph populated: ${graphStats.vertices} vertices, ${graphStats.edges} edges`);
let prTitle = `PR #${pr}`;
@@ -303,11 +305,13 @@ export async function phase1(session) {
const centralityResult = await highCentrality(g, { changedOnly: true, topN: 10, minDegree: 3 });
const blastResult = await blastRadius(g, { depth: 3, changedOnly: true });
const clusterResult = await clusterAnalysis(a, { changedOnly: true });
+ const confidenceResult = await confidenceAudit(g);
log(` completeness: ${completenessResults.filter(r => r.missing.length > 0).length} gaps found`);
log(` coverage_gaps: ${coverageResult.uncovered.length} functions without tests`);
log(` centrality: ${centralityResult.aboveThreshold} hotspots`);
log(` blast_radius: max ${blastResult.maxReachable} reachable`);
log(` clusters: ${clusterResult.clusterCount} (${clusterResult.coherent ? "coherent" : "fragmented"})`);
+ log(` confidence: ${confidenceResult.distribution.EXTRACTED} extracted / ${confidenceResult.distribution.INFERRED} inferred / ${confidenceResult.distribution.AMBIGUOUS} ambiguous`);
log(`Generating architecture map...`);
const architectureResult = await architecture(g, { clusterResult, changedOnly: true });
@@ -330,6 +334,7 @@ export async function phase1(session) {
centrality: centralityResult,
blastRadius: blastResult,
clusters: clusterResult,
+ confidence: confidenceResult,
},
discussions,
changedFiles,
@@ -399,6 +404,16 @@ if (process.argv[1] && basename(process.argv[1]) === "review.js") {
log(`Work directory: ${session.workDir}`);
log(`Worktree: ${session.worktreePath}`);
log(`To teardown: call teardown(session) or stop container ${session.handle.containerId}`);
+
+ // Phase 1 is done. Close OUR Gremlin connections so this process exits
+ // cleanly and completion is detectable (exit code 0 + the sentinel line
+ // below). The Gremlin Server container stays up independently — enrichment
+ // (scripts/enrichment/cli.js) opens its own connection per command from
+ // session.json, so nothing depends on this process lingering.
+ await session.connection.close().catch(() => {});
+ await session.aConnection.close().catch(() => {});
+ log(`PHASE1_COMPLETE pr=${pr} evidence=${jsonPath} port=${session.handle.port} container=${session.handle.containerId}`);
+ process.exit(0);
} catch (err) {
await teardown(session).catch(() => {});
throw err;
(tinkerpop) 05/07: tinker-review: move removal-ref discovery into Phase 1
Posted by sp...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 4bf44b7802cd14410479e4dd05fd04c59de897fa
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Fri Jul 3 17:19:22 2026 -0400
tinker-review: move removal-ref discovery into Phase 1
Finding references to removed code is mechanical — grep the worktree for each
deleted code symbol — so it belongs in the deterministic phase, mirroring
classifyExternals. A new removal-refs pass auto-creates `references` edges
(checks.removalRefs); addReference becomes the manual escape hatch for the
non-code cases (config strings, ports) the pass can't see. Shared symbol/edge
helpers move to graph/references.js so both paths write the edge one way.
The boundary audit that prompted this also found mapStep and grammar-rule
population do NOT qualify: step-name matching is a weak signal that needs the
judgment the GLV playbook describes, so those stay Phase-2 commands. DESIGN.md
records the distinction.
Assisted-by: Claude Code:claude-opus-4-8
---
.skills/tinker-review/DESIGN.md | 10 +-
.skills/tinker-review/playbooks/removal.md | 34 ++++---
.skills/tinker-review/scripts/enrichment/api.js | 47 ++-------
.skills/tinker-review/scripts/graph/references.js | 85 +++++++++++++++++
.../tinker-review/scripts/patterns/removal-refs.js | 106 +++++++++++++++++++++
.skills/tinker-review/scripts/review.js | 6 ++
6 files changed, 229 insertions(+), 59 deletions(-)
diff --git a/.skills/tinker-review/DESIGN.md b/.skills/tinker-review/DESIGN.md
index de4cde0700..4adda0eb51 100644
--- a/.skills/tinker-review/DESIGN.md
+++ b/.skills/tinker-review/DESIGN.md
@@ -35,7 +35,7 @@ has already exited.
|------|------|
| `scripts/review.js` | Phase 1 orchestrator — `setup` / `phase1` / `teardown` |
| `scripts/extraction/tree-sitter.js` | source → structural extraction |
-| `scripts/graph/*.js` | populate the graph; `confidence.js` / `externals.js` hold the data-model vocabularies |
+| `scripts/graph/*.js` | populate the graph; `confidence.js` / `externals.js` / `references.js` hold the data-model vocabularies and shared edge helpers |
| `scripts/patterns/*.js` | one structural check per file; each defines its own result `@typedef` |
| `scripts/enrichment/{api,cli}.js` | Phase 2 read/write commands over the live graph |
| `scripts/renderer/{render.js,template.html}` | `report.json` → HTML |
@@ -60,7 +60,13 @@ has already exited.
silently vanish. A new edge must follow both.
- **Mechanical vs judgment decides where code goes.** Anything reproducible is a
Phase-1 module; anything needing judgment is a Phase-2 command the agent drives
- from a playbook. That boundary tells you where a new capability belongs.
+ from a playbook. "Reproducible" means the signal is strong enough to act on
+ without judgment — not merely that a script *could* run. Finding references to
+ removed code is mechanical (grep a known symbol), so it is a Phase-1 pass
+ (`removal-refs.js`); `addReference` stays as the manual escape hatch for the
+ non-code cases the pass can't see. Mapping a method to a Gremlin step is *not*
+ mechanical — step names collide with ordinary method names, so it needs the
+ judgment the GLV playbook describes, and stays a Phase-2 command.
## How to change it
diff --git a/.skills/tinker-review/playbooks/removal.md b/.skills/tinker-review/playbooks/removal.md
index a40dcd0d63..b68574cf9c 100644
--- a/.skills/tinker-review/playbooks/removal.md
+++ b/.skills/tinker-review/playbooks/removal.md
@@ -16,31 +16,29 @@ deletions). It runs in addition to `general.md` and any module playbook.
(e.g. `Krb5Authenticator.java` -> `Krb5Authenticator`). Deleted files are
already in the graph as `File { deleted: true }` markers.
-2. Run `listExternalRefs`. Any external callee whose `matchesDeletedSymbol` is
- true is a dangling reference the changed code itself still makes — a
- smoking gun visible in the graph with no grep needed. Record each with
- `addReference` and treat as a finding.
-
-3. **Grep the surviving worktree** (`/tmp/pr-review-<pr>/src`) for every removed
- symbol, excluding the deleted files themselves. Search code *and* the
- supporting cast that removals commonly miss:
- - source (`*.java`, GLV sources) and build files (`pom.xml`, `*.gradle`)
- - config/resources (`*.yaml`, `*.conf`, `*.properties`)
+2. **Phase 1 already found the code-symbol references.** For every deleted *code*
+ file it grepped the surviving worktree for that class/method name and wrote a
+ `references` edge per hit — read them from `checks.removalRefs` (and
+ `checks.removalRefs.externalCallers` for changed code still calling a removed
+ name). Your job on these is judgment, not discovery: classify each (see
+ Interpret). They are `INFERRED`; confirm or downgrade with `setEdgeConfidence`.
+
+3. **Grep for what the automatic pass skips** — the non-code supporting cast that
+ removals commonly leave behind, keyed off `listDeleted`:
+ - config/resources (`*.yaml`, `*.conf`, `*.properties`), ports, feature flags
+ - build files (`pom.xml`, `*.gradle`) — was the dependency actually dropped?
- docs (`docs/src/**/*.asciidoc`) and `CHANGELOG.asciidoc`
- Docker/CI setup (compose files, `*.sh`)
- For each surviving hit, record it with `addReference --fromPath <file>
- --toPath <deletedFile> --symbol <name> --location <where>`.
-
-4. Confirm the removal is complete on the *other* side too: was the dependency
- dropped from `pom.xml`? Were the config keys, ports, and doc sections that
- described the feature removed, not just the classes?
+ Record any surviving hit with `addReference --fromPath <file> --toPath
+ <deletedFile> --symbol <name> --location <where>` — the escape hatch for the
+ cases the code-symbol pass cannot see.
## Interpret
Read the structural signals from evidence.json (schema in
[references/interfaces.md](../references/interfaces.md)); the `references` edges
-you added above and checks.coverageGaps on any surviving code are the primary
-structural outputs here.
+in checks.removalRefs (plus any you added by hand) and checks.coverageGaps on
+any surviving code are the primary structural outputs here.
Not every surviving reference is a defect — classify each:
- **Active code / build / config / live docs** referencing a removed symbol is a
diff --git a/.skills/tinker-review/scripts/enrichment/api.js b/.skills/tinker-review/scripts/enrichment/api.js
index 9915c1c088..b90b78757c 100644
--- a/.skills/tinker-review/scripts/enrichment/api.js
+++ b/.skills/tinker-review/scripts/enrichment/api.js
@@ -21,6 +21,7 @@ import { readFile } from "node:fs/promises";
import { join } from "node:path";
import gremlin from "gremlin";
import { CONFIDENCE, normalizeConfidence, isValidConfidence } from "../graph/confidence.js";
+import { symbolFromPath, createReferenceEdge } from "../graph/references.js";
const { process: { statics: __ } } = gremlin;
@@ -80,19 +81,6 @@ export async function getCanonicalSteps(repoPath) {
return cachedSteps;
}
-// The likely symbol name a source file defined — its basename without extension
-// (Krb5Authenticator.java -> Krb5Authenticator). Used to turn deleted-file paths
-// into names the agent can grep the rest of the repo for.
-function symbolFromPath(path) {
- const base = path.split("/").pop() || path;
- const dot = base.indexOf(".");
- return dot > 0 ? base.slice(0, dot) : base;
-}
-
-function extOf(path) {
- return path.includes(".") ? path.split(".").pop() : "";
-}
-
// === Removal-impact reads ===
/**
@@ -206,12 +194,11 @@ export async function setEdgeConfidence(g, params = {}) {
}
/**
- * Record a lingering reference to removed code: a surviving file (fromPath) that
- * still mentions a symbol defined by a deleted file (toPath). Creates a
- * `references` edge File -> File(deleted), carrying the matched symbol and
- * location. The source file is often outside the changed set and has no vertex
- * yet, so it's find-or-created as an unparsed marker. This is the payoff of a
- * removal review — "the PR deleted X, but these places still use it."
+ * Manual escape hatch for recording a lingering reference to removed code that
+ * the Phase-1 removal-refs pass didn't catch — e.g. a config-string or
+ * non-code-symbol reference, which that pass deliberately skips. The automatic
+ * pass (patterns/removal-refs.js) handles code symbols; use this for the cases
+ * that need a human/agent to spot. Creates the same `references` edge.
*
* @param {object} g - gremlin-js GraphTraversalSource (already connected)
* @param {object} params
@@ -219,7 +206,7 @@ export async function setEdgeConfidence(g, params = {}) {
* @param {string} params.toPath - Deleted file path (must be an existing deleted File)
* @param {string} [params.symbol] - The removed symbol found in fromPath
* @param {string} [params.location] - Where (e.g. "L42" or a line snippet)
- * @param {string} [params.confidence] - default INFERRED (a textual grep match)
+ * @param {string} [params.confidence] - default INFERRED (a textual match)
* @returns {Promise<object>}
*/
export async function addReference(g, params = {}) {
@@ -234,25 +221,7 @@ export async function addReference(g, params = {}) {
return { error: `no deleted File vertex for toPath "${toPath}" (use listDeleted for valid targets)` };
}
- const srcExists = await g.V().hasLabel("File").has("path", fromPath).hasNext();
- if (!srcExists) {
- await g.addV("File")
- .property("path", fromPath)
- .property("language", extOf(fromPath))
- .property("changed", false)
- .property("parsed", false)
- .property("deleted", false)
- .next();
- }
-
- await g.V().hasLabel("File").has("path", fromPath)
- .addE("references")
- .property("confidence", conf)
- .property("symbol", symbol || "")
- .property("location", location || "")
- .to(__.V().hasLabel("File").has("path", toPath))
- .next();
-
+ await createReferenceEdge(g, { fromPath, toPath, symbol, location, confidence: conf });
return { referenced: `${fromPath} -> ${toPath}`, symbol: symbol || "", confidence: conf };
}
diff --git a/.skills/tinker-review/scripts/graph/references.js b/.skills/tinker-review/scripts/graph/references.js
new file mode 100644
index 0000000000..21f84793bf
--- /dev/null
+++ b/.skills/tinker-review/scripts/graph/references.js
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// Shared helpers for symbols and `references` edges. Used by both the Phase-1
+// removal-refs pass (patterns/removal-refs.js) and the manual addReference
+// escape hatch (enrichment/api.js), so the edge shape lives in one place.
+
+import gremlin from "gremlin";
+import { CONFIDENCE } from "./confidence.js";
+
+const { process: { statics: __ } } = gremlin;
+
+const CODE_EXTENSIONS = new Set([
+ "java", "py", "js", "ts", "jsx", "tsx", "mjs", "go", "cs", "groovy",
+ "kt", "scala", "rb", "rs", "c", "cpp", "h", "hpp",
+]);
+
+// The likely symbol a source file defined — its basename without extension
+// (Krb5Authenticator.java -> Krb5Authenticator).
+export function symbolFromPath(path) {
+ const base = path.split("/").pop() || path;
+ const dot = base.indexOf(".");
+ return dot > 0 ? base.slice(0, dot) : base;
+}
+
+export function extOf(path) {
+ return path.includes(".") ? path.split(".").pop() : "";
+}
+
+export function isCodeFile(path) {
+ return CODE_EXTENSIONS.has(extOf(path));
+}
+
+/**
+ * Create a `references` edge: a surviving file (fromPath) still mentions a symbol
+ * from a deleted file (toPath). The source file is often outside the changed set
+ * and has no vertex yet, so it is find-or-created as an unparsed marker. Assumes
+ * the target (deleted) File vertex already exists.
+ *
+ * @param {object} g - gremlin-js GraphTraversalSource (already connected)
+ * @param {object} params
+ * @param {string} params.fromPath
+ * @param {string} params.toPath
+ * @param {string} [params.symbol]
+ * @param {string} [params.location]
+ * @param {string} [params.confidence] - default INFERRED
+ */
+export async function createReferenceEdge(g, params) {
+ const { fromPath, toPath, symbol, location, confidence = CONFIDENCE.INFERRED } = params;
+
+ const srcExists = await g.V().hasLabel("File").has("path", fromPath).hasNext();
+ if (!srcExists) {
+ await g.addV("File")
+ .property("path", fromPath)
+ .property("language", extOf(fromPath))
+ .property("changed", false)
+ .property("parsed", false)
+ .property("deleted", false)
+ .next();
+ }
+
+ await g.V().hasLabel("File").has("path", fromPath)
+ .addE("references")
+ .property("confidence", confidence)
+ .property("symbol", symbol || "")
+ .property("location", location || "")
+ .to(__.V().hasLabel("File").has("path", toPath))
+ .next();
+}
diff --git a/.skills/tinker-review/scripts/patterns/removal-refs.js b/.skills/tinker-review/scripts/patterns/removal-refs.js
new file mode 100644
index 0000000000..9d4792ccbe
--- /dev/null
+++ b/.skills/tinker-review/scripts/patterns/removal-refs.js
@@ -0,0 +1,106 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { CONFIDENCE } from "../graph/confidence.js";
+import { symbolFromPath, isCodeFile, createReferenceEdge } from "../graph/references.js";
+
+const exec = promisify(execFile);
+
+// Whole-word search for a symbol across the PR-head worktree. Returns one hit
+// per file (first line), since deleted files no longer exist in the worktree the
+// results are surviving references only. `git grep` exits non-zero on no match.
+async function gitGrepWord(symbol, repoPath) {
+ try {
+ const { stdout } = await exec("git", ["grep", "-nw", symbol], {
+ cwd: repoPath,
+ maxBuffer: 16 * 1024 * 1024,
+ });
+ const firstLineByFile = new Map();
+ for (const line of stdout.split("\n")) {
+ const m = line.match(/^([^:]+):(\d+):/);
+ if (m && !firstLineByFile.has(m[1])) firstLineByFile.set(m[1], m[2]);
+ }
+ return [...firstLineByFile.entries()].map(([file, ln]) => ({ file, line: `L${ln}` }));
+ } catch {
+ return [];
+ }
+}
+
+/**
+ * Phase-1 removal-impact pass. Mechanical mirror of classifyExternals: for every
+ * deleted *code* file, grep the surviving worktree for its symbol and auto-create
+ * a `references` edge (INFERRED) for each hit. Finding the references is
+ * reproducible; classifying them (blocking vs. benign historical note) is the
+ * agent's judgment in the report. Config/non-code symbols are skipped here and
+ * left to the addReference escape hatch.
+ *
+ * @param {object} g - gremlin-js GraphTraversalSource (already connected)
+ * @param {string} repoPath - a git worktree (PR-head) to grep
+ * @returns {Promise<RemovalRefsResult>}
+ */
+
+/**
+ * @typedef {Object} RemovalReference
+ * @property {string} from surviving file that still names the removed symbol
+ * @property {string} to the deleted file path
+ * @property {string} symbol the removed symbol matched
+ * @property {string} location first line in `from` (e.g. "L42")
+ *
+ * @typedef {Object} RemovalRefsResult
+ * @property {string[]} deletedCodeSymbols symbols of deleted code files that were searched
+ * @property {RemovalReference[]} references surviving references found (also written as edges)
+ * @property {string[]} externalCallers external-callee stubs whose name matches a deleted
+ * symbol — changed code still calling removed code
+ * @property {number} total references.length
+ */
+export async function findRemovalRefs(g, repoPath) {
+ const deletedPaths = await g.V().hasLabel("File").has("deleted", true).values("path").toList();
+ const result = { deletedCodeSymbols: [], references: [], externalCallers: [], total: 0 };
+ if (deletedPaths.length === 0) return result;
+
+ const deletedSymbolSet = new Set(deletedPaths.map(symbolFromPath));
+
+ for (const path of deletedPaths) {
+ if (!isCodeFile(path)) continue;
+ const symbol = symbolFromPath(path);
+ if (!/^\w+$/.test(symbol)) continue;
+ result.deletedCodeSymbols.push(symbol);
+
+ for (const { file, line } of await gitGrepWord(symbol, repoPath)) {
+ await createReferenceEdge(g, {
+ fromPath: file,
+ toPath: path,
+ symbol,
+ location: line,
+ confidence: CONFIDENCE.INFERRED,
+ });
+ result.references.push({ from: file, to: path, symbol, location: line });
+ }
+ }
+
+ // In-graph dangling references: a changed function still calls a name that a
+ // deleted file defined (surfaced from the external-callee stubs, no grep).
+ const externalStubs = await g.V().hasLabel("Function").has("external", true).values("name").toList();
+ result.externalCallers = externalStubs.filter((n) => deletedSymbolSet.has(n));
+
+ result.total = result.references.length;
+ return result;
+}
diff --git a/.skills/tinker-review/scripts/review.js b/.skills/tinker-review/scripts/review.js
index 09c42c491b..848bbd4fde 100644
--- a/.skills/tinker-review/scripts/review.js
+++ b/.skills/tinker-review/scripts/review.js
@@ -36,6 +36,7 @@ import { clusterAnalysis } from "./patterns/cluster-analysis.js";
import { architecture } from "./patterns/architecture.js";
import { confidenceAudit } from "./patterns/confidence-audit.js";
import { classifyExternals } from "./patterns/classify-externals.js";
+import { findRemovalRefs } from "./patterns/removal-refs.js";
import { orphans } from "./patterns/orphans.js";
import { createPrDiscussion } from "./enrichment/api.js";
import { discoverDiscussions } from "./discovery/discussions.js";
@@ -301,6 +302,10 @@ export async function phase1(session) {
const externalsResult = await classifyExternals(g, worktreePath);
log(` externals: ${externalsResult.library.length} library / ${externalsResult.project.length} project / ${externalsResult.unresolved.length} unresolved`);
+ log(`Finding references to removed code...`);
+ const removalRefsResult = await findRemovalRefs(g, worktreePath);
+ log(` removal_refs: ${removalRefsResult.total} surviving references to ${removalRefsResult.deletedCodeSymbols.length} removed symbols`);
+
log(`Running checks...`);
const completenessResults = await completeness(g, {
vertexLabel: "File",
@@ -344,6 +349,7 @@ export async function phase1(session) {
clusters: clusterResult,
confidence: confidenceResult,
externals: externalsResult,
+ removalRefs: removalRefsResult,
orphans: orphansResult,
},
discussions,