Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
TypeScript antigravity-skillsbusiness-knowledgeclaude-codeclaude-skillscodebase-analysiscodexcodex-skillsdeveloper-tools-ai-agentgemini-cli-skillskarpathy-llm-wikiknowledge-baseknowledge-graphmemoryopencode-skillspi-agentunderstandcodevibe-coding
fix(incremental): verify ownership before accepting preserved IDs
Lum1104d0b3105df1f2
diff --git a/tests/skill/understand/test_incremental_symbols.test.mjs b/tests/skill/understand/test_incremental_symbols.test.mjsindex 5560f3e3..8d9583e2 100644--- a/tests/skill/understand/test_incremental_symbols.test.mjs+++ b/tests/skill/understand/test_incremental_symbols.test.mjs@@ -48,6 +48,29 @@ describe('incremental symbol matching', () => {expect(result.missing[0]).toMatchObject({ name: 'run', status: 'still-present' });});+ it('does not let an unchanged generic ID hide a changed or missing class owner', () => {+ const code = 'class A { run() {} }\nclass B { run() {} }';+ const classes = ['A', 'B'].map(name => node(name, { id: `class:src/a.ts:${name}`, type: 'class' }));+ const previous = graph([...classes, node('run')]);+ previous.edges = [{ source: classes[0].id, target: node('run').id, type: 'contains' }];+ for (const edges of [[], [{ source: classes[1].id, target: node('run').id, type: 'contains' }]]) {+ const current = { ...graph([...classes, node('run')]), edges };+ const result = compareFileSymbols(previous, current, parse(code), parse(code));+ expect(result.missing[0]).toMatchObject({ id: node('run').id, status: 'still-present' });+ expect(compareFileSymbols(previous, current, { status: 'unsupported' }, { status: 'unsupported' })+ .missing[0].status).toBe('unknown');+ }+ expect(compareFileSymbols(previous, previous).missing).toEqual([]);+ const ambiguous = graph([...classes, node('run')]);+ expect(compareFileSymbols(ambiguous, ambiguous, parse(code), parse(code)).missing[0].status).toBe('unknown');+ });++ it('accepts a top-level function sharing a name with a method when source locations establish ownership', () => {+ const code = 'function run() {}\nclass A { run() {} }';+ const nodes = [node('A', { type: 'class', id: 'class:src/a.ts:A' }), node('run', { lineRange: [1, 1] })];+ expect(compare(nodes, nodes, code, code).missing).toEqual([]);+ });+it('confirms genuine function, class, and method deletions without restoring them', () => {const result = compare([node('gone'), node('Old', { type: 'class' }), node('A.removed')], [],'function gone() {} class Old {} class A { removed() {} keep() {} }',diff --git a/tests/skill/understand/test_prepare_incremental.test.mjs b/tests/skill/understand/test_prepare_incremental.test.mjsindex 26a63f2a..709811f0 100644--- a/tests/skill/understand/test_prepare_incremental.test.mjs+++ b/tests/skill/understand/test_prepare_incremental.test.mjs@@ -232,6 +232,34 @@ afterEach(async () => {});describe('incremental symbol publication gate', { timeout: 30_000 }, () => {+ it('blocks owner substitution behind an unchanged generic method ID in merge and finalize', () => {+ const otherSource = 'export class Other { method0() { return 2; } }\n';+ const f = symbolFixture(2, {+ 'src/a.ts': 'export class Service { method0() { return 1; } method1() { return 1; } }\n' + otherSource,+ });+ const generic = { ...f.methodNodes[0], id: 'function:src/a.ts:method0', name: 'method0' };+ const otherClass = { ...f.classNode, id: 'class:src/a.ts:Other', name: 'Other' };+ const previous = JSON.parse(f.persisted()[0]);+ previous.nodes = previous.nodes.map(node => node.id === f.methodNodes[0].id ? generic : node);+ previous.nodes.push(otherClass);+ previous.edges = previous.edges.map(edge => edge.target === f.methodNodes[0].id ? { ...edge, target: generic.id } : edge);+ writeFileSync(join(f.dataDir, 'knowledge-graph.json'), JSON.stringify(previous));+ writeProjectFile(f.root, 'src/a.ts', f.source([...f.names, 'added']) + otherSource);+ commit(f.root, 'add method');+ const before = f.persisted();+ prepare(f.root, f.baseCommit);+ f.write('batch-1.json', {+ nodes: [f.fileNode, f.classNode, otherClass, generic, f.methodNodes[1]],+ edges: [{ source: otherClass.id, target: generic.id, type: 'contains', direction: 'forward', weight: 1 }],+ });+ expect(spawnSync(python, [mergeScript, f.root]).status).toBe(1);+ expect(f.read('incremental-symbol-report.json').files[0].missing).toContainEqual(expect.objectContaining({+ id: generic.id, name: generic.name, status: 'still-present',+ }));+ expect(spawnSync(process.execPath, [finalizeScript, f.root]).status).toBe(1);+ expect(f.persisted()).toEqual(before);+ });+it('reconciles accepted replacement IDs on the first pass without requiring a retry', () => {const f = symbolFixture(2, { 'src/b.ts': 'export function b() {}\n' });const oldSource = { ...f.methodNodes[0], id: 'func:src/b.ts:b', filePath: 'src/b.ts', name: 'b' };diff --git a/understand-anything-plugin/skills/understand/SKILL.md b/understand-anything-plugin/skills/understand/SKILL.mdindex 205b97ae..e7fbcf75 100644--- a/understand-anything-plugin/skills/understand/SKILL.md+++ b/understand-anything-plugin/skills/understand/SKILL.md@@ -424,7 +424,7 @@ This helper revalidates the candidate, records attempt 1/1 for the base/head comIf repair preparation, the repair dispatch, or the second merge fails, **STOP** and retain diagnostics. Do not publish or advance `knowledge-graph.json`, `fingerprints.json`, or `meta.json`. Never concatenate old nodes or old semantic edges into the candidate to satisfy the gate. Other merge failures without eligible unresolved files stop immediately. On success, continue to the applicable architecture/tour phases.-Parser limitation: languages without a deterministic structural parser (including `.sh`, `.ps1`, and `.bat`) cannot have missing symbols automatically confirmed as deleted. Such omissions remain `unknown`, even for genuine deletions, and stop publication pending manual investigation or parser support. Supplemental LLM source inspection and regex guesses are not deletion evidence. Preserved symbols with unchanged IDs/names do not require a parser.+Parser limitation: languages without a deterministic structural parser (including `.sh`, `.ps1`, and `.bat`) cannot have missing symbols automatically confirmed as deleted. Such omissions remain `unknown`, even for genuine deletions, and stop publication pending manual investigation or parser support. Supplemental LLM source inspection and regex guesses are not deletion evidence. Preserved symbols with unchanged IDs/names and unambiguous ownership do not require a parser. An unchanged generic method ID cannot stand in for a different class's method; changed or ambiguous containment requires source identity verification.---diff --git a/understand-anything-plugin/skills/understand/validate-incremental-symbols.mjs b/understand-anything-plugin/skills/understand/validate-incremental-symbols.mjsindex cb3020b4..e5efb60e 100644--- a/understand-anything-plugin/skills/understand/validate-incremental-symbols.mjs+++ b/understand-anything-plugin/skills/understand/validate-incremental-symbols.mjs@@ -76,8 +76,7 @@ function sourceSymbols(evidence) {return symbols;}-function resolveSymbol(node, graph, symbols) {- const kind = symbolKind(node);+function nodeNames(node) {const path = normalizePath(node.filePath);const names = new Set([qualifiedName(node.name)]);// Accept ID spelling changes, including func/function and class separators.@@ -86,6 +85,34 @@ function resolveSymbol(node, graph, symbols) {if (typeof node.id === 'string' && node.id.includes(marker)) {names.add(qualifiedName(node.id.slice(node.id.indexOf(marker) + marker.length)));}+ return names;+}++function classOwners(node, graph) {+ const parents = new Set(graph.edges.filter(edge => edge.type === 'contains' && edge.target === node.id)+ .map(edge => edge.source));+ return graph.nodes.filter(parent => parent.type === 'class' && parents.has(parent.id));+}++function hasPreservedIdentity(node, previous, current) {+ const candidate = current.nodes.find(candidate => candidate.id === node.id+ && symbolKind(candidate) === symbolKind(node) && candidate.name === node.name);+ if (!candidate) return false;+ const owners = (item, graph) => classOwners(item, graph)+ .map(owner => JSON.stringify([owner.id, owner.name])).sort();+ const oldOwners = owners(node, previous);+ if (JSON.stringify(oldOwners) !== JSON.stringify(owners(candidate, current))) return false;+ // Generic method IDs do not encode scope. Without a contains owner, class+ // context requires unique source mapping even if the ID/name stayed equal.+ if (symbolKind(node) === 'callable' && oldOwners.length === 0+ && ![...nodeNames(node)].some(name => name.includes('.'))+ && [...previous.nodes, ...current.nodes].some(item => item.type === 'class')) return false;+ return true;+}++function resolveSymbol(node, graph, symbols) {+ const kind = symbolKind(node);+ const names = nodeNames(node);let candidates = symbols.filter(symbol => symbol.kind === kind && (names.has(qualifiedName(symbol.name))|| (symbol.owner && names.has(qualifiedName(`${symbol.owner}.${symbol.name}`)))@@ -93,16 +120,13 @@ function resolveSymbol(node, graph, symbols) {const qualified = candidates.filter(symbol => symbol.owner&& names.has(qualifiedName(`${symbol.owner}.${symbol.name}`)));if (qualified.length) candidates = qualified;- const parentIds = new Set(graph.edges.filter(edge => edge.type === 'contains' && edge.target === node.id)- .map(edge => edge.source));- const owners = graph.nodes.filter(parent => parent.type === 'class' && parentIds.has(parent.id))- .map(parent => parent.name);+ const owners = classOwners(node, graph).map(parent => parent.name);if (owners.length) candidates = candidates.filter(symbol => owners.includes(symbol.owner));// Lines locate ownership within one revision only; they are never identity// across revisions. Do not use lines to guess among overloads/same-name classes.if (candidates.length > 1 && Array.isArray(node.lineRange)) {- const located = candidates.filter(symbol => symbol.owner- && node.lineRange[0] >= symbol.lineRange[0] && node.lineRange[1] <= symbol.lineRange[1]);+ const located = candidates.filter(symbol => node.lineRange[0] >= symbol.lineRange[0]+ && node.lineRange[1] <= symbol.lineRange[1]);if (located.length === 1) candidates = located;}return candidates.length === 1 ? candidates[0] : null;@@ -119,8 +143,7 @@ export function compareFileSymbols(previous, current, baseEvidence, headEvidenceconst replacements = [];for (let index = 0; index < oldSymbols.length; index++) {const node = oldSymbols[index];- if (newSymbols.some(candidate => candidate.id === node.id- && symbolKind(candidate) === symbolKind(node) && candidate.name === node.name)) continue;+ if (hasPreservedIdentity(node, previous, current)) continue;const entry = { id: node.id, name: node.name, type: node.type, status: 'unknown', reason: '' };const old = oldMappings[index];if (!old || baseEvidence?.status !== 'succeeded' || headEvidence?.status !== 'succeeded') {@@ -132,7 +155,9 @@ export function compareFileSymbols(previous, current, baseEvidence, headEvidenceconst graphMatches = newMappings.filter(symbol => symbol && symbolKey(symbol) === symbolKey(old));if (matches.length === 1 && graphMatches.length === 1) {const matchedIndex = newMappings.findIndex(symbol => symbol && symbolKey(symbol) === symbolKey(old));- replacements.push({ oldId: node.id, newId: newSymbols[matchedIndex].id });+ if (newSymbols[matchedIndex].id !== node.id) {+ replacements.push({ oldId: node.id, newId: newSymbols[matchedIndex].id });+ }continue;}if (matches.length === 1) {@@ -231,8 +256,7 @@ export async function validateIncrementalSymbols(projectRoot, { graph, intermediconst current = fileGraph(previous.filePath);let baseEvidence;let headEvidence;- if (previous.nodes.some(node => symbolKind(node) && !current.nodes.some(candidate => candidate.id === node.id- && candidate.name === node.name && symbolKind(candidate) === symbolKind(node)))) {+ if (previous.nodes.some(node => symbolKind(node) && !hasPreservedIdentity(node, previous, current))) {try {const evidence = await parseRevisions(previous.filePath);baseEvidence = evidence.base;