Skip to content

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.

fix(understand): reconcile incremental inventory and import map

Lum1104cc20b4b2b939
diff --git a/tests/skill/understand/test_prepare_incremental.test.mjs b/tests/skill/understand/test_prepare_incremental.test.mjs
new file mode 100644
index 00000000..eafc04a2
--- /dev/null
+++ b/tests/skill/understand/test_prepare_incremental.test.mjs
@@ -0,0 +1,432 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ renameSync,
+ rmSync,
+ unlinkSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, '../../..');
+const skillDir = join(repoRoot, 'understand-anything-plugin', 'skills', 'understand');
+const scanScript = join(skillDir, 'scan-project.mjs');
+const importScript = join(skillDir, 'extract-import-map.mjs');
+const fingerprintScript = join(skillDir, 'build-fingerprints.mjs');
+const prepareScript = join(skillDir, 'prepare-incremental.mjs');
+const finalizeScript = join(skillDir, 'finalize-incremental.mjs');
+const mergeScript = join(skillDir, 'merge-batch-graphs.py');
+
+const python = (() => {
+ for (const command of ['python3', 'python']) {
+ const probe = spawnSync(command, ['--version'], { encoding: 'utf-8' });
+ if (probe.status === 0) return command;
+ }
+ throw new Error('Python 3 is required for incremental merge tests');
+})();
+
+const roots = [];
+
+function run(command, args, cwd) {
+ const result = spawnSync(command, args, { cwd, encoding: 'utf-8' });
+ if (result.status !== 0) {
+ throw new Error(
+ `${command} ${args.join(' ')} failed (${result.status})\n${result.stdout}\n${result.stderr}`,
+ );
+ }
+ return result;
+}
+
+function git(root, args) {
+ return run('git', args, root).stdout.trim();
+}
+
+function writeProjectFile(root, path, content) {
+ const absolute = join(root, path);
+ mkdirSync(dirname(absolute), { recursive: true });
+ writeFileSync(absolute, content, 'utf-8');
+}
+
+function commit(root, message, { forcePaths = [] } = {}) {
+ git(root, ['add', '-A']);
+ for (const path of forcePaths) git(root, ['add', '-f', '--', path]);
+ git(root, ['commit', '-m', message]);
+ return git(root, ['rev-parse', 'HEAD']);
+}
+
+function setupRepository(files) {
+ const root = mkdtempSync(join(tmpdir(), 'ua-incremental-test-'));
+ roots.push(root);
+ git(root, ['init', '-b', 'main']);
+ git(root, ['config', 'user.email', '[email protected]']);
+ git(root, ['config', 'user.name', 'Test User']);
+ writeProjectFile(root, '.gitignore', '.ua/\n.understand-anything/\n');
+ for (const [path, content] of Object.entries(files)) writeProjectFile(root, path, content);
+ const baseCommit = commit(root, 'baseline');
+ buildBaseline(root, baseCommit);
+ return { root, baseCommit };
+}
+
+function buildBaseline(root, baseCommit) {
+ const intermediate = join(root, '.ua', 'intermediate');
+ mkdirSync(intermediate, { recursive: true });
+ const rawScanPath = join(intermediate, 'baseline-scan.json');
+ run(process.execPath, [scanScript, root, rawScanPath, '--exclude-analysis-data'], root);
+ const rawScan = JSON.parse(readFileSync(rawScanPath, 'utf-8'));
+
+ const importInput = join(intermediate, 'baseline-import-input.json');
+ const importOutput = join(intermediate, 'baseline-import-output.json');
+ writeFileSync(
+ importInput,
+ JSON.stringify({ projectRoot: root, files: rawScan.files }),
+ 'utf-8',
+ );
+ run(process.execPath, [importScript, importInput, importOutput], root);
+ const importMap = JSON.parse(readFileSync(importOutput, 'utf-8')).importMap;
+ const scan = {
+ name: 'fixture',
+ description: 'fixture project',
+ languages: [...new Set(rawScan.files.map(file => file.language))].sort(),
+ frameworks: [],
+ contentDigest: rawScan.contentDigest,
+ files: rawScan.files,
+ totalFiles: rawScan.totalFiles,
+ filteredByIgnore: rawScan.filteredByIgnore,
+ estimatedComplexity: rawScan.estimatedComplexity,
+ importMap,
+ };
+ writeFileSync(join(intermediate, 'scan-result.json'), JSON.stringify(scan), 'utf-8');
+
+ const fingerprintInput = join(intermediate, 'fingerprint-input.json');
+ writeFileSync(
+ fingerprintInput,
+ JSON.stringify({
+ projectRoot: root,
+ filePaths: rawScan.files.map(file => file.path),
+ gitCommitHash: baseCommit,
+ }),
+ 'utf-8',
+ );
+ run(process.execPath, [fingerprintScript, fingerprintInput], root);
+
+ const nodes = rawScan.files.map(file => ({
+ id: `file:${file.path}`,
+ type: 'file',
+ name: file.path.split('/').at(-1),
+ filePath: file.path,
+ summary: file.path,
+ tags: ['fixture'],
+ complexity: 'simple',
+ }));
+ writeFileSync(
+ join(root, '.ua', 'knowledge-graph.json'),
+ JSON.stringify({
+ version: '1.0.0',
+ project: {
+ name: 'fixture',
+ languages: scan.languages,
+ frameworks: [],
+ description: 'fixture project',
+ analyzedAt: '2026-01-01T00:00:00.000Z',
+ gitCommitHash: baseCommit,
+ },
+ nodes,
+ edges: [],
+ layers: [{
+ id: 'layer:source',
+ name: 'Source',
+ description: 'Source files',
+ nodeIds: nodes.map(node => node.id),
+ }],
+ tour: [{
+ order: 1,
+ title: 'Overview',
+ description: 'Read the project',
+ nodeIds: nodes.map(node => node.id),
+ }],
+ }),
+ 'utf-8',
+ );
+ writeFileSync(
+ join(root, '.ua', 'meta.json'),
+ JSON.stringify({ gitCommitHash: baseCommit, analyzedFiles: nodes.length, version: '1.0.0' }),
+ 'utf-8',
+ );
+}
+
+function prepare(root, baseCommit) {
+ const result = run(process.execPath, [prepareScript, root, baseCommit], root);
+ const intermediate = join(root, '.ua', 'intermediate');
+ return {
+ result,
+ plan: JSON.parse(readFileSync(join(intermediate, 'incremental-plan.json'), 'utf-8')),
+ scan: JSON.parse(readFileSync(join(intermediate, 'scan-result.json'), 'utf-8')),
+ changedFiles: readFileSync(join(intermediate, 'changed-files.txt'), 'utf-8'),
+ };
+}
+
+afterEach(() => {
+ for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('prepare-incremental.mjs', { timeout: 30_000 }, () => {
+ it('refreshes imports in the same run and only schedules the structural source', () => {
+ const { root, baseCommit } = setupRepository({
+ 'src/a.ts': 'export const a = 1;\n',
+ 'src/b.ts': 'export const b = 2;\n',
+ 'src/c.ts': 'export const c = 3;\n',
+ 'src/d.ts': 'export const d = 4;\n',
+ });
+ writeProjectFile(root, 'src/a.ts', "import { b } from './b';\nexport const a = b;\n");
+ commit(root, 'add import');
+
+ const { plan, scan, changedFiles } = prepare(root, baseCommit);
+ expect(plan.action).toBe('PARTIAL_UPDATE');
+ expect(plan.filesToReanalyze).toEqual(['src/a.ts']);
+ expect(changedFiles).toBe('src/a.ts\n');
+ expect(scan.importMap['src/a.ts']).toEqual(['src/b.ts']);
+ expect(scan.importMap['src/c.ts']).toEqual([]);
+ });
+
+ it('turns a local deletion into cleanup with an empty analyzer list', () => {
+ const { root, baseCommit } = setupRepository({
+ 'src/a.ts': 'export const a = 1;\n',
+ 'src/b.ts': 'export const b = 2;\n',
+ 'src/c.ts': 'export const c = 3;\n',
+ 'src/d.ts': 'export const d = 4;\n',
+ });
+ unlinkSync(join(root, 'src/b.ts'));
+ commit(root, 'delete b');
+ writeFileSync(
+ join(root, '.ua', 'intermediate', 'batch-99.json'),
+ JSON.stringify({
+ nodes: [{ id: 'file:src/b.ts', type: 'file', filePath: 'src/b.ts' }],
+ edges: [],
+ }),
+ 'utf-8',
+ );
+
+ const { plan, scan, changedFiles } = prepare(root, baseCommit);
+ expect(plan.action).toBe('PARTIAL_UPDATE');
+ expect(plan.filesToReanalyze).toEqual([]);
+ expect(plan.deletedFiles).toEqual(['src/b.ts']);
+ expect(changedFiles).toBe('');
+ expect(scan.files.map(file => file.path)).not.toContain('src/b.ts');
+ expect(scan.importMap).not.toHaveProperty('src/b.ts');
+ expect(() => readFileSync(join(root, '.ua', 'intermediate', 'batch-99.json'))).toThrow();
+ const retained = JSON.parse(
+ readFileSync(join(root, '.ua', 'intermediate', 'batch-existing.json'), 'utf-8'),
+ );
+ expect(retained.nodes.map(node => node.filePath)).not.toContain('src/b.ts');
+
+ run(python, [mergeScript, root], root);
+ run(process.execPath, [finalizeScript, root], root);
+ const graph = JSON.parse(readFileSync(join(root, '.ua', 'knowledge-graph.json'), 'utf-8'));
+ const fingerprints = JSON.parse(
+ readFileSync(join(root, '.ua', 'fingerprints.json'), 'utf-8'),
+ );
+ expect(graph.nodes.map(node => node.filePath)).not.toContain('src/b.ts');
+ expect(graph.layers.flatMap(layer => layer.nodeIds)).not.toContain('file:src/b.ts');
+ expect(graph.tour.flatMap(step => step.nodeIds)).not.toContain('file:src/b.ts');
+ expect(fingerprints.files).not.toHaveProperty('src/b.ts');
+ });
+
+ it('does not recover an import removed during this incremental run', () => {
+ const { root, baseCommit } = setupRepository({
+ 'src/a.ts': "import { b } from './b';\nexport const a = b;\n",
+ 'src/b.ts': 'export const b = 2;\n',
+ 'src/c.ts': 'export const c = 3;\n',
+ 'src/d.ts': 'export const d = 4;\n',
+ });
+ writeProjectFile(root, 'src/a.ts', 'export const a = 1;\n');
+ commit(root, 'remove import');
+
+ const { plan, scan } = prepare(root, baseCommit);
+ expect(plan.filesToReanalyze).toEqual(['src/a.ts']);
+ expect(scan.importMap['src/a.ts']).toEqual([]);
+ const intermediate = join(root, '.ua', 'intermediate');
+ const retained = JSON.parse(readFileSync(join(intermediate, 'batch-existing.json'), 'utf-8'));
+ writeFileSync(
+ join(intermediate, 'batch-0.json'),
+ JSON.stringify({
+ nodes: [{
+ id: 'file:src/a.ts',
+ type: 'file',
+ name: 'a.ts',
+ filePath: 'src/a.ts',
+ summary: 'a',
+ tags: ['fixture'],
+ complexity: 'simple',
+ }],
+ edges: [],
+ }),
+ 'utf-8',
+ );
+ expect(retained.nodes.map(node => node.filePath)).not.toContain('src/a.ts');
+ run(python, [mergeScript, root], root);
+ const assembled = JSON.parse(
+ readFileSync(join(intermediate, 'assembled-graph.json'), 'utf-8'),
+ );
+ expect(assembled.edges.filter(edge => edge.type === 'imports')).toHaveLength(0);
+ });
+
+ it('classifies implementation-only edits as SKIP and advances fingerprints via finalize', () => {
+ const { root, baseCommit } = setupRepository({
+ 'src/a.ts': 'export function value() { return 1; }\n',
+ 'src/b.ts': 'export const b = 2;\n',
+ 'src/c.ts': 'export const c = 3;\n',
+ 'src/d.ts': 'export const d = 4;\n',
+ });
+ writeProjectFile(root, 'src/a.ts', 'export function value() { return 2; }\n');
+ const headCommit = commit(root, 'implementation only');
+
+ const { plan } = prepare(root, baseCommit);
+ expect(plan.action).toBe('SKIP');
+ expect(plan.cosmeticFiles).toEqual(['src/a.ts']);
+ run(process.execPath, [finalizeScript, root], root);
+
+ const meta = JSON.parse(readFileSync(join(root, '.ua', 'meta.json'), 'utf-8'));
+ const fingerprints = JSON.parse(
+ readFileSync(join(root, '.ua', 'fingerprints.json'), 'utf-8'),
+ );
+ expect(meta.gitCommitHash).toBe(headCommit);
+ expect(fingerprints.gitCommitHash).toBe(headCommit);
+ expect(Object.keys(fingerprints.files)).toHaveLength(4);
+ });
+
+ it('removes files newly covered by .understandignore without analyzing them', () => {
+ const { root, baseCommit } = setupRepository({
+ 'src/a.ts': 'export const a = 1;\n',
+ 'src/b.ts': 'export const b = 2;\n',
+ 'src/c.ts': 'export const c = 3;\n',
+ 'legacy/old.ts': 'export const old = true;\n',
+ });
+ writeProjectFile(root, '.understandignore', 'legacy/\n');
+ commit(root, 'ignore legacy');
+
+ const { plan } = prepare(root, baseCommit);
+ expect(plan.filesToReanalyze).toEqual([]);
+ expect(plan.deletedFiles).toEqual(['legacy/old.ts']);
+ expect(plan.ignoredFiles).toContain('.understandignore');
+ expect(plan.action).toBe('ARCHITECTURE_UPDATE');
+ });
+
+ it('handles renames and spaces as a delete plus add', () => {
+ const { root, baseCommit } = setupRepository({
+ 'src/old name.ts': 'export const value = 1;\n',
+ 'src/a.ts': 'export const a = 1;\n',
+ 'src/b.ts': 'export const b = 2;\n',
+ 'src/c.ts': 'export const c = 3;\n',
+ });
+ renameSync(join(root, 'src/old name.ts'), join(root, 'src/new name.ts'));
+ commit(root, 'rename spaced file');
+
+ const { plan } = prepare(root, baseCommit);
+ expect(plan.deletedFiles).toEqual(['src/old name.ts']);
+ expect(plan.filesToReanalyze).toEqual(['src/new name.ts']);
+ });
+
+ it('keeps the same new-directory decision when preparation is retried', () => {
+ const { root, baseCommit } = setupRepository({
+ 'src/a.ts': 'export const a = 1;\n',
+ 'src/b.ts': 'export const b = 2;\n',
+ 'src/c.ts': 'export const c = 3;\n',
+ 'src/d.ts': 'export const d = 4;\n',
+ });
+ writeProjectFile(root, 'new-package/index.ts', 'export const added = true;\n');
+ commit(root, 'add package');
+
+ const first = prepare(root, baseCommit).plan;
+ const second = prepare(root, baseCommit).plan;
+ expect(first.action).toBe('ARCHITECTURE_UPDATE');
+ expect(second.action).toBe(first.action);
+ expect(second.filesToReanalyze).toEqual(['new-package/index.ts']);
+ });
+
+ it('does not advance the baseline for generated-artifact-only commits', () => {
+ const { root, baseCommit } = setupRepository({
+ 'src/a.ts': 'export const a = 1;\n',
+ 'src/b.ts': 'export const b = 2;\n',
+ 'src/c.ts': 'export const c = 3;\n',
+ 'src/d.ts': 'export const d = 4;\n',
+ });
+ writeProjectFile(root, '.ua/tracked-generated.json', '{}\n');
+ commit(root, 'generated output', { forcePaths: ['.ua/tracked-generated.json'] });
+
+ const { plan } = prepare(root, baseCommit);
+ expect(plan.action).toBe('SKIP');
+ expect(plan.generatedArtifactFiles).toEqual(['.ua/tracked-generated.json']);
+ run(process.execPath, [finalizeScript, root], root);
+ const meta = JSON.parse(readFileSync(join(root, '.ua', 'meta.json'), 'utf-8'));
+ expect(meta.gitCommitHash).toBe(baseCommit);
+ });
+});
+
+describe('finalize-incremental.mjs', { timeout: 30_000 }, () => {
+ it('preserves local layer/tour text, removes dangling refs, and places new nodes by path', () => {
+ const { root, baseCommit } = setupRepository({
+ 'src/api/a.ts': 'export const a = 1;\n',
+ 'src/ui/view.ts': 'export const view = 1;\n',
+ 'src/other.ts': 'export const other = 1;\n',
+ 'docs/readme.md': '# Docs\n',
+ });
+ const graphPath = join(root, '.ua', 'knowledge-graph.json');
+ const previousGraph = JSON.parse(readFileSync(graphPath, 'utf-8'));
+ previousGraph.layers = [
+ {
+ id: 'layer:api',
+ name: 'API',
+ description: 'API files',
+ nodeIds: ['file:src/api/a.ts', 'file:missing.ts'],
+ },
+ {
+ id: 'layer:ui',
+ name: 'UI',
+ description: 'UI files',
+ nodeIds: ['file:src/ui/view.ts', 'file:src/other.ts', 'file:docs/readme.md'],
+ },
+ ];
+ previousGraph.tour[0].nodeIds.push('file:missing.ts');
+ writeFileSync(graphPath, JSON.stringify(previousGraph), 'utf-8');
+ writeProjectFile(root, 'src/api/new.ts', "import { a } from './a';\nexport const value = a;\n");
+ const headCommit = commit(root, 'add api file');
+ const { plan } = prepare(root, baseCommit);
+ expect(plan.action).toBe('PARTIAL_UPDATE');
+
+ const intermediate = join(root, '.ua', 'intermediate');
+ const retained = JSON.parse(readFileSync(join(intermediate, 'batch-existing.json'), 'utf-8'));
+ const newNode = {
+ id: 'file:src/api/new.ts',
+ type: 'file',
+ name: 'new.ts',
+ filePath: 'src/api/new.ts',
+ summary: 'new api',
+ tags: ['api'],
+ complexity: 'simple',
+ };
+ const aId = 'file:src/api/a.ts';
+ writeFileSync(
+ join(intermediate, 'assembled-graph.json'),
+ JSON.stringify({
+ nodes: [...retained.nodes, newNode],
+ edges: [{ source: newNode.id, target: aId, type: 'imports', direction: 'forward', weight: 0.7 }],
+ }),
+ 'utf-8',
+ );
+
+ run(process.execPath, [finalizeScript, root], root);
+ const graph = JSON.parse(readFileSync(join(root, '.ua', 'knowledge-graph.json'), 'utf-8'));
+ expect(graph.project.gitCommitHash).toBe(headCommit);
+ expect(graph.layers.find(layer => layer.id === 'layer:api').nodeIds).toContain(newNode.id);
+ expect(graph.layers.flatMap(layer => layer.nodeIds)).not.toContain('file:missing.ts');
+ expect(graph.tour[0].title).toBe('Overview');
+ expect(graph.tour[0].description).toBe('Read the project');
+ expect(graph.tour[0].nodeIds.every(id => graph.nodes.some(node => node.id === id))).toBe(true);
+ });
+});
diff --git a/understand-anything-plugin/packages/core/src/__tests__/ignore-filter.test.ts b/understand-anything-plugin/packages/core/src/__tests__/ignore-filter.test.ts
index 915c32cf..77a324a1 100644
--- a/understand-anything-plugin/packages/core/src/__tests__/ignore-filter.test.ts
+++ b/understand-anything-plugin/packages/core/src/__tests__/ignore-filter.test.ts
@@ -26,6 +26,10 @@ describe("IgnoreFilter", () => {
expect(DEFAULT_IGNORE_PATTERNS).toContain(".git/");
});
+ it("contains the .understandignore control file", () => {
+ expect(DEFAULT_IGNORE_PATTERNS).toContain(".understandignore");
+ });
+
it("contains obj for .NET", () => {
expect(DEFAULT_IGNORE_PATTERNS).toContain("obj/");
});
diff --git a/understand-anything-plugin/packages/core/src/ignore-filter.ts b/understand-anything-plugin/packages/core/src/ignore-filter.ts
index 7f12e362..9794f55a 100644
--- a/understand-anything-plugin/packages/core/src/ignore-filter.ts
+++ b/understand-anything-plugin/packages/core/src/ignore-filter.ts
@@ -64,6 +64,7 @@ export const DEFAULT_IGNORE_PATTERNS: string[] = [
// Misc
"LICENSE",
".gitignore",
+ ".understandignore",
".editorconfig",
".prettierrc",
".eslintrc*",
diff --git a/understand-anything-plugin/skills/understand/build-fingerprints.mjs b/understand-anything-plugin/skills/understand/build-fingerprints.mjs
index 61cbe8c3..75fb4063 100644
--- a/understand-anything-plugin/skills/understand/build-fingerprints.mjs
+++ b/understand-anything-plugin/skills/understand/build-fingerprints.mjs
@@ -17,7 +17,11 @@
* node build-fingerprints.mjs <input.json>
*
* Input JSON:
- * { projectRoot: string, sourceFilePaths: string[], gitCommitHash: string }
+ * { projectRoot: string, filePaths: string[], gitCommitHash: string }
+ *
+ * `sourceFilePaths` remains accepted as a backwards-compatible alias. Full
+ * baselines should pass every analyzed path; unsupported formats receive a
+ * conservative content-only fingerprint from buildFingerprintStore().
*
* Writes: <projectRoot>/.ua/fingerprints.json (or legacy
* <projectRoot>/.understand-anything/fingerprints.json when that dir exists)
@@ -62,13 +66,15 @@ async function main() {
process.exit(1);
}
- const { projectRoot, sourceFilePaths, gitCommitHash } = JSON.parse(
+ const input = JSON.parse(
readFileSync(inputPath, 'utf-8'),
);
+ const { projectRoot, gitCommitHash } = input;
+ const filePaths = input.filePaths ?? input.sourceFilePaths;
- if (!projectRoot || !Array.isArray(sourceFilePaths) || typeof gitCommitHash !== 'string') {
+ if (!projectRoot || !Array.isArray(filePaths) || typeof gitCommitHash !== 'string') {
throw new Error(
- 'Invalid input: requires { projectRoot: string, sourceFilePaths: string[], gitCommitHash: string }',
+ 'Invalid input: requires { projectRoot: string, filePaths: string[], gitCommitHash: string }',
);
}
@@ -83,7 +89,7 @@ async function main() {
registry.register(tsPlugin);
registerAllParsers(registry);
- const store = buildFingerprintStore(projectRoot, sourceFilePaths, registry, gitCommitHash);
+ const store = buildFingerprintStore(projectRoot, filePaths, registry, gitCommitHash);
saveFingerprints(projectRoot, store);
const fileCount = Object.keys(store.files).length;
diff --git a/understand-anything-plugin/skills/understand/finalize-incremental.mjs b/understand-anything-plugin/skills/understand/finalize-incremental.mjs
new file mode 100644
index 00000000..2794be55
--- /dev/null
+++ b/understand-anything-plugin/skills/understand/finalize-incremental.mjs
@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+/**
+ * Finalize a prepared incremental update without another LLM pass.
+ *
+ * Usage: node finalize-incremental.mjs <projectRoot>
+ *
+ * For PARTIAL_UPDATE / ARCHITECTURE_UPDATE, reads assembled-graph.json plus
+ * either the previous or regenerated layers/tour, performs deterministic
+ * dangling-reference cleanup and local layer placement, then atomically saves
+ * knowledge-graph.json. Only after that succeeds does it patch fingerprints
+ * and advance meta.json. SKIP applies the fingerprint/meta patch only; a
+ * generated-artifact-only SKIP deliberately advances nothing.
+ */
+
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+ existsSync,
+ readFileSync,
+ realpathSync,
+ renameSync,
+ writeFileSync,
+} from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = resolve(__dirname, '../..');
+const require = createRequire(resolve(pluginRoot, 'package.json'));
+
+let core;
+try {
+ core = await import(pathToFileURL(require.resolve('@understand-anything/core')).href);
+} catch {
+ core = await import(pathToFileURL(resolve(pluginRoot, 'packages/core/dist/index.js')).href);
+}
+
+const { resolveUaDir } = core;
+const LAYER_NODE_TYPES = new Set([
+ 'file',
+ 'config',
+ 'document',
+ 'service',
+ 'pipeline',
+ 'table',
+ 'schema',
+ 'resource',
+ 'endpoint',
+]);
+const WHOLE_FILE_TYPES = new Set([
+ 'file',
+ 'config',
+ 'document',
+ 'service',
+ 'pipeline',
+ 'schema',
+ 'resource',
+]);
+
+function readJson(path, fallback = null) {
+ if (!existsSync(path)) return fallback;
+ return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+function atomicWriteJson(path, value) {
+ const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+ writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+ renameSync(tempPath, path);
+ // Verify the durable target, not the temporary file.
+ JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+function normalizeRelativePath(value) {
+ if (typeof value !== 'string' || !value || isAbsolute(value)) return null;
+ const path = value.replaceAll('\\', '/').replace(/^\.\//, '');
+ if (!path || path.split('/').some(part => part === '..')) return null;
+ return path;
+}
+
+function unwrap(value, key) {
+ return Array.isArray(value) ? value : Array.isArray(value?.[key]) ? value[key] : [];
+}
+
+function slug(value) {
+ const result = String(value ?? '')
+ .trim()
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/^-|-$/g, '');
+ return result || 'other';
+}
+
+function buildPathIndex(nodes) {
+ const index = new Map();
+ const selectedTypes = new Map();
+ for (const node of nodes) {
+ if (!WHOLE_FILE_TYPES.has(node.type)) continue;
+ const path = normalizeRelativePath(node.filePath);
+ if (!path || node.id !== `${node.type}:${path}`) continue;
+ if (!index.has(path) || (node.type === 'file' && selectedTypes.get(path) !== 'file')) {
+ index.set(path, node.id);
+ selectedTypes.set(path, node.type);
+ }
+ }
+ return index;
+}
+
+function resolveNodeRef(value, nodeIds, pathIndex) {
+ if (typeof value === 'object' && value) value = value.id;
+ if (typeof value !== 'string' || !value) return null;
+ if (nodeIds.has(value)) return value;
+ const path = normalizeRelativePath(value);
+ return path ? pathIndex.get(path) ?? null : null;
+}
+
+function normalizeLayerShape(rawLayers, nodeIds, pathIndex) {
+ return unwrap(rawLayers, 'layers').map((layer, index) => {
+ const refs = Array.isArray(layer?.nodeIds)
+ ? layer.nodeIds
+ : Array.isArray(layer?.nodes)
+ ? layer.nodes
+ : [];
+ const name = typeof layer?.name === 'string' && layer.name ? layer.name : 'Other';
+ return {
+ id: typeof layer?.id === 'string' && layer.id ? layer.id : `layer:${slug(name)}`,
+ name,
+ description:
+ typeof layer?.description === 'string'
+ ? layer.description
+ : index === 0
+ ? 'Project files'
+ : '',
+ nodeIds: refs
+ .map(ref => resolveNodeRef(ref, nodeIds, pathIndex))
+ .filter(Boolean),
+ };
+ });
+}
+
+function directorySegments(filePath) {
+ const parts = normalizeRelativePath(filePath)?.split('/') ?? [];
+ return parts.slice(0, -1);
+}
+
+function commonParentDepth(leftPath, rightPath) {
+ const left = directorySegments(leftPath);
+ const right = directorySegments(rightPath);
+ let depth = 0;
+ while (depth < left.length && depth < right.length && left[depth] === right[depth]) depth++;
+ return depth;
+}
+
+function assignLayers(rawLayers, nodes, edges) {
+ const nodeIds = new Set(nodes.map(node => node.id));
+ const pathIndex = buildPathIndex(nodes);
+ const layerable = nodes.filter(node => LAYER_NODE_TYPES.has(node.type));
+ const nodeById = new Map(nodes.map(node => [node.id, node]));
+ const layers = normalizeLayerShape(rawLayers, nodeIds, pathIndex);
+ const assigned = new Set();
+
+ for (const layer of layers) {
+ layer.nodeIds = layer.nodeIds.filter(id => {
+ if (assigned.has(id)) return false;
+ assigned.add(id);
+ return true;
+ });
+ }
+
+ const adjacency = new Map();
+ for (const edge of edges) {
+ if (!nodeIds.has(edge.source) || !nodeIds.has(edge.target)) continue;
+ if (!adjacency.has(edge.source)) adjacency.set(edge.source, new Set());
+ if (!adjacency.has(edge.target)) adjacency.set(edge.target, new Set());
+ adjacency.get(edge.source).add(edge.target);
+ adjacency.get(edge.target).add(edge.source);
+ }
+
+ const candidates = layers.filter(layer => layer.nodeIds.length > 0);
+ for (const node of layerable) {
+ if (assigned.has(node.id)) continue;
+ if (candidates.length === 0) {
+ const fallback = {
+ id: 'layer:other',
+ name: 'Other',
+ description: 'Files not assigned to another architectural layer',
+ nodeIds: [],
+ };
+ layers.push(fallback);
+ candidates.push(fallback);
+ }
+
+ let bestLayer = candidates[0];
+ let bestDepth = -1;
+ let bestConnections = -1;
+ for (const layer of candidates) {
+ let depth = 0;
+ for (const memberId of layer.nodeIds) {
+ const member = nodeById.get(memberId);
+ if (member?.filePath && node.filePath) {
+ depth = Math.max(depth, commonParentDepth(node.filePath, member.filePath));
+ }
+ }
+ const neighborIds = adjacency.get(node.id) ?? new Set();
+ const connections = layer.nodeIds.reduce(
+ (count, memberId) => count + (neighborIds.has(memberId) ? 1 : 0),
+ 0,
+ );
+ // Strict comparisons preserve original layer order as the final tie-break.
+ if (depth > bestDepth || (depth === bestDepth && connections > bestConnections)) {
+ bestLayer = layer;
+ bestDepth = depth;
+ bestConnections = connections;
+ }
+ }
+ bestLayer.nodeIds.push(node.id);
+ assigned.add(node.id);
+ }
+
+ return layers.filter(layer => layer.nodeIds.length > 0);
+}
+
+function normalizeTour(rawTour, nodeIds, pathIndex) {
+ return unwrap(rawTour, 'steps')
+ .map((step, index) => {
+ const refs = Array.isArray(step?.nodeIds)
+ ? step.nodeIds
+ : Array.isArray(step?.nodesToInspect)
+ ? step.nodesToInspect
+ : [];
+ const normalized = {
+ order: Number.isFinite(step?.order) ? step.order : index + 1,
+ title: typeof step?.title === 'string' ? step.title : `Step ${index + 1}`,
+ description:
+ typeof step?.description === 'string'
+ ? step.description
+ : typeof step?.whyItMatters === 'string'
+ ? step.whyItMatters
+ : '',
+ nodeIds: [...new Set(
+ refs.map(ref => resolveNodeRef(ref, nodeIds, pathIndex)).filter(Boolean),
+ )],
+ };
+ if (typeof step?.languageLesson === 'string') {
+ normalized.languageLesson = step.languageLesson;
+ }
+ return normalized;
+ })
+ .sort((a, b) => a.order - b.order);
+}
+
+function normalizeAssembled(assembled) {
+ const nodesById = new Map();
+ for (const node of assembled?.nodes ?? []) {
+ if (node && typeof node.id === 'string' && node.id) nodesById.set(node.id, node);
+ }
+ const nodes = [...nodesById.values()];
+ const nodeIds = new Set(nodesById.keys());
+ const seenEdges = new Set();
+ const edges = [];
+ for (const edge of assembled?.edges ?? []) {
+ if (!nodeIds.has(edge?.source) || !nodeIds.has(edge?.target)) continue;
+ if (edge.source === edge.target) continue;
+ const key = `${edge.source}\0${edge.target}\0${edge.type}`;
+ if (seenEdges.has(key)) continue;
+ seenEdges.add(key);
+ edges.push(edge);
+ }
+ return { nodes, edges };
+}
+
+function normalizeFingerprintStore(raw, baseCommit) {
+ if (raw && raw.files && typeof raw.files === 'object' && !Array.isArray(raw.files)) {
+ return raw;
+ }
+ return {
+ version: '1.0.0',
+ gitCommitHash: baseCommit,
+ generatedAt: new Date(0).toISOString(),
+ files: raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {},
+ };
+}
+
+function isGeneratedOnly(plan) {
+ return plan.generatedArtifactFiles.length > 0
+ && plan.filesToReanalyze.length === 0
+ && plan.deletedFiles.length === 0
+ && plan.cosmeticFiles.length === 0
+ && plan.ignoredFiles.length === 0;
+}
+
+function patchFingerprints(uaDir, plan, patch) {
+ const fingerprintPath = join(uaDir, 'fingerprints.json');
+ const store = normalizeFingerprintStore(readJson(fingerprintPath, null), plan.baseCommit);
+ const files = { ...store.files };
+ for (const filePath of patch.deletedFiles ?? []) delete files[filePath];
+ for (const [filePath, fingerprint] of Object.entries(patch.files ?? {})) {
+ files[filePath] = fingerprint;
+ }
+ atomicWriteJson(fingerprintPath, {
+ version: '1.0.0',
+ gitCommitHash: plan.headCommit,
+ generatedAt: new Date().toISOString(),
+ files,
+ });
+}
+
+function advanceMeta(uaDir, plan, analyzedFiles) {
+ const metaPath = join(uaDir, 'meta.json');
+ const previous = readJson(metaPath, {});
+ atomicWriteJson(metaPath, {
+ ...previous,
+ lastAnalyzedAt: new Date().toISOString(),
+ gitCommitHash: plan.headCommit,
+ version: previous.version ?? '1.0.0',
+ analyzedFiles,
+ });
+}
+
+function main() {
+ const args = process.argv.slice(2);
+ if (args.length !== 1 || args[0].startsWith('--')) {
+ throw new Error('Usage: node finalize-incremental.mjs <projectRoot>');
+ }
+ const projectRoot = realpathSync(args[0]);
+ const uaDir = resolveUaDir(projectRoot);
+ const intermediateDir = join(uaDir, 'intermediate');
+ const plan = readJson(join(intermediateDir, 'incremental-plan.json'));
+ const patch = readJson(join(intermediateDir, 'fingerprint-patch.json'));
+ const scan = readJson(join(intermediateDir, 'scan-result.json'), { totalFiles: 0 });
+ if (!plan || !patch) throw new Error('Incremental plan or fingerprint patch is missing');
+ if (patch.baseCommit !== plan.baseCommit || patch.headCommit !== plan.headCommit) {
+ throw new Error('Fingerprint patch does not match the incremental plan commits');
+ }
+
+ if (plan.action === 'FULL_UPDATE') {
+ throw new Error('FULL_UPDATE must run the full /understand pipeline');
+ }
+ if (plan.action === 'SKIP' && isGeneratedOnly(plan)) {
+ process.stdout.write('Generated artifacts only: analysis baseline unchanged\n');
+ return;
+ }
+
+ if (plan.action !== 'SKIP') {
+ const previousGraph = readJson(join(uaDir, 'knowledge-graph.json'), {});
+ const assembledRaw = readJson(join(intermediateDir, 'assembled-graph.json'));
+ if (!assembledRaw || !Array.isArray(assembledRaw.nodes) || !Array.isArray(assembledRaw.edges)) {
+ throw new Error('assembled-graph.json is missing or invalid; baseline not advanced');
+ }
+ const assembled = normalizeAssembled(assembledRaw);
+ const nodeIds = new Set(assembled.nodes.map(node => node.id));
+ const pathIndex = buildPathIndex(assembled.nodes);
+ if (plan.rerunArchitecture && !existsSync(join(intermediateDir, 'layers.json'))) {
+ throw new Error('Architecture update requires layers.json; baseline not advanced');
+ }
+ if (plan.rerunTour && !existsSync(join(intermediateDir, 'tour.json'))) {
+ throw new Error('Architecture update requires tour.json; baseline not advanced');
+ }
+ const rawLayers = plan.rerunArchitecture
+ ? readJson(join(intermediateDir, 'layers.json'))
+ : previousGraph.layers ?? [];
+ const rawTour = plan.rerunTour
+ ? readJson(join(intermediateDir, 'tour.json'))
+ : previousGraph.tour ?? [];
+ const now = new Date().toISOString();
+ const graph = {
+ ...previousGraph,
+ version: previousGraph.version ?? '1.0.0',
+ project: {
+ ...(previousGraph.project ?? {}),
+ analyzedAt: now,
+ gitCommitHash: plan.headCommit,
+ },
+ nodes: assembled.nodes,
+ edges: assembled.edges,
+ layers: assignLayers(rawLayers, assembled.nodes, assembled.edges),
+ tour: normalizeTour(rawTour, nodeIds, pathIndex),
+ };
+
+ // Ordering is intentional: a failed graph save must never advance the
+ // structural baseline and hide the failed update from the next run.
+ atomicWriteJson(join(uaDir, 'knowledge-graph.json'), graph);
+ }
+
+ patchFingerprints(uaDir, plan, patch);
+ advanceMeta(uaDir, plan, scan.totalFiles);
+ process.stdout.write(
+ `Incremental update finalized: ${plan.action}; analyzedFiles=${scan.totalFiles}\n`,
+ );
+}
+
+function isCliEntry() {
+ if (!process.argv[1]) return false;
+ try {
+ return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+ } catch {
+ return false;
+ }
+}
+
+if (isCliEntry()) {
+ try {
+ main();
+ } catch (error) {
+ process.stderr.write(`finalize-incremental.mjs failed: ${error.message}\n${error.stack}\n`);
+ process.exit(1);
+ }
+}
+
+export { assignLayers, commonParentDepth, normalizeTour };
diff --git a/understand-anything-plugin/skills/understand/prepare-incremental.mjs b/understand-anything-plugin/skills/understand/prepare-incremental.mjs
new file mode 100644
index 00000000..9f23b5c5
--- /dev/null
+++ b/understand-anything-plugin/skills/understand/prepare-incremental.mjs
@@ -0,0 +1,585 @@
+#!/usr/bin/env node
+/**
+ * Prepare a deterministic incremental /understand update.
+ *
+ * Usage:
+ * node prepare-incremental.mjs <projectRoot> <baseCommit>
+ * [--exclude <comma-separated-patterns>]
+ *
+ * Writes under <UA_DIR>/intermediate:
+ * - incremental-plan.json
+ * - changed-files.txt
+ * - fingerprint-patch.json
+ * - incremental-baseline.json (retry-safe copy of the pre-update scan)
+ * - batch-existing.json (PARTIAL/ARCHITECTURE only)
+ *
+ * It also atomically refreshes scan-result.json (except for a commit whose
+ * only changes are generated analysis artifacts). All git subprocess
+ * arguments are parameterized and all path lists use Git's NUL-delimited
+ * format so spaces, renames, and non-ASCII filenames round-trip safely.
+ */
+
+import { createRequire } from 'node:module';
+import { dirname, basename, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ realpathSync,
+ renameSync,
+ unlinkSync,
+ writeFileSync,
+} from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = resolve(__dirname, '../..');
+const require = createRequire(resolve(pluginRoot, 'package.json'));
+
+let core;
+try {
+ core = await import(pathToFileURL(require.resolve('@understand-anything/core')).href);
+} catch {
+ core = await import(pathToFileURL(resolve(pluginRoot, 'packages/core/dist/index.js')).href);
+}
+
+const {
+ TreeSitterPlugin,
+ PluginRegistry,
+ builtinLanguageConfigs,
+ registerAllParsers,
+ buildFingerprintStore,
+ compareFingerprints,
+ classifyUpdate,
+ resolveUaDir,
+} = core;
+
+const SCAN_SCRIPT = join(__dirname, 'scan-project.mjs');
+const IMPORT_SCRIPT = join(__dirname, 'extract-import-map.mjs');
+const GENERATED_ROOTS = new Set(['.ua', '.understand-anything']);
+
+function comparePaths(a, b) {
+ if (a === b) return 0;
+ return a < b ? -1 : 1;
+}
+
+function sorted(values) {
+ return [...new Set(values)].sort(comparePaths);
+}
+
+function normalizeRelativePath(value) {
+ if (typeof value !== 'string' || value.length === 0 || isAbsolute(value)) return null;
+ const posix = value.replaceAll('\\', '/').replace(/^\.\//, '');
+ if (!posix || posix.split('/').some(part => part === '..')) return null;
+ return posix;
+}
+
+function isGeneratedArtifact(path) {
+ return GENERATED_ROOTS.has(path.split('/')[0]);
+}
+
+function readJson(path, fallback = null) {
+ if (!existsSync(path)) return fallback;
+ try {
+ return JSON.parse(readFileSync(path, 'utf-8'));
+ } catch (error) {
+ throw new Error(`Could not parse ${path}: ${error.message}`);
+ }
+}
+
+function atomicWriteJson(path, value) {
+ const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+ writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+ renameSync(tempPath, path);
+}
+
+function clearIncrementalScratch(intermediateDir) {
+ const exactNames = new Set([
+ 'assembled-graph.json',
+ 'batch-existing.json',
+ 'batches.json',
+ 'layers.json',
+ 'tour.json',
+ ]);
+ for (const name of readdirSync(intermediateDir)) {
+ if (exactNames.has(name) || /^batch-\d+(?:-part-\d+)?\.json$/.test(name)) {
+ unlinkSync(join(intermediateDir, name));
+ }
+ }
+}
+
+function run(command, args, options = {}) {
+ const result = spawnSync(command, args, {
+ cwd: options.cwd,
+ encoding: 'utf-8',
+ maxBuffer: 256 * 1024 * 1024,
+ });
+ if (result.status !== 0) {
+ const detail = result.stderr?.trim() || result.stdout?.trim() || `exit ${result.status}`;
+ throw new Error(`${command} failed: ${detail}`);
+ }
+ if (result.stderr) process.stderr.write(result.stderr);
+ return result.stdout;
+}
+
+function resolveCommit(projectRoot, value) {
+ return run(
+ 'git',
+ ['rev-parse', '--verify', '--end-of-options', `${value}^{commit}`],
+ { cwd: projectRoot },
+ ).trim();
+}
+
+function parseNameStatusZ(output) {
+ if (!output) return [];
+ const fields = output.split('\0');
+ if (fields.at(-1) === '') fields.pop();
+ const changes = [];
+ for (let i = 0; i < fields.length;) {
+ const status = fields[i++];
+ if (!status) continue;
+ const kind = status[0];
+ if (kind === 'R' || kind === 'C') {
+ const oldPath = normalizeRelativePath(fields[i++]);
+ const newPath = normalizeRelativePath(fields[i++]);
+ if (!oldPath || !newPath) throw new Error(`Invalid ${kind} path in git diff`);
+ changes.push({ status, oldPath, newPath });
+ } else {
+ const path = normalizeRelativePath(fields[i++]);
+ if (!path) throw new Error(`Invalid path in git diff for status ${status}`);
+ changes.push({ status, path });
+ }
+ }
+ return changes;
+}
+
+function pathsFromChanges(changes) {
+ const paths = [];
+ for (const change of changes) {
+ if (change.path) paths.push(change.path);
+ if (change.oldPath) paths.push(change.oldPath);
+ if (change.newPath) paths.push(change.newPath);
+ }
+ return sorted(paths);
+}
+
+function normalizeFingerprintStore(raw, baseCommit) {
+ if (raw && raw.files && typeof raw.files === 'object' && !Array.isArray(raw.files)) {
+ return raw;
+ }
+ // Compatibility with the early auto-update prompt, which wrote a bare
+ // path -> fingerprint dictionary instead of FingerprintStore.
+ if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+ return {
+ version: '1.0.0',
+ gitCommitHash: baseCommit,
+ generatedAt: new Date(0).toISOString(),
+ files: raw,
+ };
+ }
+ return {
+ version: '1.0.0',
+ gitCommitHash: baseCommit,
+ generatedAt: new Date(0).toISOString(),
+ files: {},
+ };
+}
+
+function inventoryFrom(scan, graph, fingerprints) {
+ const paths = [];
+ for (const file of scan?.files ?? []) paths.push(file?.path);
+ for (const node of graph?.nodes ?? []) paths.push(node?.filePath);
+ paths.push(...Object.keys(fingerprints.files ?? {}));
+ return sorted(
+ paths
+ .map(normalizeRelativePath)
+ .filter(path => path && !isGeneratedArtifact(path)),
+ );
+}
+
+function contentOnlyFingerprint(filePath) {
+ const content = readFileSync(filePath.absolutePath, 'utf-8');
+ const contentHash = require('node:crypto').createHash('sha256').update(content).digest('hex');
+ return {
+ filePath: filePath.relativePath,
+ contentHash,
+ functions: [],
+ classes: [],
+ imports: [],
+ exports: [],
+ totalLines: content.split('\n').length,
+ hasStructuralAnalysis: false,
+ };
+}
+
+async function buildCurrentFingerprints(projectRoot, paths, headCommit) {
+ if (paths.length === 0) {
+ return {
+ version: '1.0.0',
+ gitCommitHash: headCommit,
+ generatedAt: new Date().toISOString(),
+ files: {},
+ };
+ }
+
+ try {
+ const tsConfigs = builtinLanguageConfigs.filter(config => config.treeSitter);
+ const treeSitter = new TreeSitterPlugin(tsConfigs);
+ await treeSitter.init();
+ const registry = new PluginRegistry();
+ registry.register(treeSitter);
+ registerAllParsers(registry);
+ return buildFingerprintStore(projectRoot, paths, registry, headCommit);
+ } catch (error) {
+ process.stderr.write(
+ `Warning: prepare-incremental: structural parser initialization failed ` +
+ `(${error.message}); changed files will be classified conservatively\n`,
+ );
+ const files = {};
+ for (const relativePath of paths) {
+ files[relativePath] = contentOnlyFingerprint({
+ relativePath,
+ absolutePath: join(projectRoot, relativePath),
+ });
+ }
+ return {
+ version: '1.0.0',
+ gitCommitHash: headCommit,
+ generatedAt: new Date().toISOString(),
+ files,
+ };
+ }
+}
+
+function analyzeInventoryChanges({
+ currentChangedPaths,
+ currentFingerprints,
+ oldFingerprints,
+ oldInventory,
+ deletedFiles,
+}) {
+ const oldInventorySet = new Set(oldInventory);
+ const fileChanges = [];
+ const newFiles = [];
+ const structurallyChangedFiles = [];
+ const cosmeticOnlyFiles = [];
+ const unchangedFiles = [];
+
+ for (const filePath of currentChangedPaths) {
+ const current = currentFingerprints.files[filePath];
+ if (!current) {
+ throw new Error(`File disappeared while preparing incremental update: ${filePath}`);
+ }
+ const previous = oldFingerprints.files[filePath];
+ if (!oldInventorySet.has(filePath)) {
+ newFiles.push(filePath);
+ fileChanges.push({ filePath, changeLevel: 'STRUCTURAL', details: ['new file'] });
+ continue;
+ }
+ if (!previous) {
+ structurallyChangedFiles.push(filePath);
+ fileChanges.push({
+ filePath,
+ changeLevel: 'STRUCTURAL',
+ details: ['no fingerprint baseline — conservative classification'],
+ });
+ continue;
+ }
+ const result = compareFingerprints(previous, current);
+ fileChanges.push(result);
+ if (result.changeLevel === 'STRUCTURAL') structurallyChangedFiles.push(filePath);
+ else if (result.changeLevel === 'COSMETIC') cosmeticOnlyFiles.push(filePath);
+ else unchangedFiles.push(filePath);
+ }
+
+ for (const filePath of deletedFiles) {
+ fileChanges.push({ filePath, changeLevel: 'STRUCTURAL', details: ['file deleted or ignored'] });
+ }
+
+ return {
+ fileChanges,
+ newFiles: sorted(newFiles),
+ deletedFiles: sorted(deletedFiles),
+ structurallyChangedFiles: sorted(structurallyChangedFiles),
+ cosmeticOnlyFiles: sorted(cosmeticOnlyFiles),
+ unchangedFiles: sorted(unchangedFiles),
+ };
+}
+
+function runScan(projectRoot, outputPath, excludePatterns) {
+ const args = [SCAN_SCRIPT, projectRoot, outputPath, '--exclude-analysis-data'];
+ if (excludePatterns.length > 0) args.push('--exclude', excludePatterns.join(','));
+ run(process.execPath, args);
+ return readJson(outputPath);
+}
+
+function refreshImportMap({ projectRoot, intermediateDir, oldScan, currentScan, analysisPaths }) {
+ const inputPath = join(intermediateDir, 'incremental-import-input.json');
+ const outputPath = join(intermediateDir, 'incremental-import-output.json');
+ atomicWriteJson(inputPath, {
+ projectRoot,
+ files: currentScan.files,
+ analysisPaths,
+ });
+ run(process.execPath, [IMPORT_SCRIPT, inputPath, outputPath]);
+ const selective = readJson(outputPath)?.importMap ?? {};
+ const currentPaths = new Set(currentScan.files.map(file => file.path));
+ const importMap = {};
+ for (const file of currentScan.files) {
+ const path = file.path;
+ const candidate = Object.hasOwn(selective, path)
+ ? selective[path]
+ : oldScan?.importMap?.[path];
+ importMap[path] = Array.isArray(candidate)
+ ? sorted(candidate.filter(target => typeof target === 'string' && currentPaths.has(target)))
+ : [];
+ }
+ return importMap;
+}
+
+function pruneExistingGraph(graph, pathsToReplace) {
+ const removedNodeIds = new Set();
+ const nodes = [];
+ for (const node of graph?.nodes ?? []) {
+ const path = normalizeRelativePath(node?.filePath);
+ if (path && pathsToReplace.has(path)) removedNodeIds.add(node.id);
+ else nodes.push(node);
+ }
+ const retainedIds = new Set(nodes.map(node => node.id));
+ const edges = (graph?.edges ?? []).filter(
+ edge =>
+ !removedNodeIds.has(edge.source)
+ && !removedNodeIds.has(edge.target)
+ && retainedIds.has(edge.source)
+ && retainedIds.has(edge.target),
+ );
+ return { nodes, edges };
+}
+
+function parseArgs(argv) {
+ const positionals = [];
+ const excludePatterns = [];
+ for (let i = 0; i < argv.length; i++) {
+ const arg = argv[i];
+ if (arg === '--exclude') {
+ const value = argv[++i];
+ if (!value || value.startsWith('--')) throw new Error('--exclude requires patterns');
+ excludePatterns.push(...value.split(',').map(item => item.trim()).filter(Boolean));
+ } else if (arg.startsWith('--')) {
+ throw new Error(`Unknown option: ${arg}`);
+ } else {
+ positionals.push(arg);
+ }
+ }
+ if (positionals.length !== 2) {
+ throw new Error(
+ 'Usage: node prepare-incremental.mjs <projectRoot> <baseCommit> [--exclude <patterns>]',
+ );
+ }
+ return { projectRoot: positionals[0], baseCommit: positionals[1], excludePatterns };
+}
+
+async function main() {
+ const args = parseArgs(process.argv.slice(2));
+ const projectRoot = realpathSync(args.projectRoot);
+ const uaDir = resolveUaDir(projectRoot);
+ const intermediateDir = join(uaDir, 'intermediate');
+ mkdirSync(intermediateDir, { recursive: true });
+
+ const baseCommit = resolveCommit(projectRoot, args.baseCommit);
+ const headCommit = resolveCommit(projectRoot, 'HEAD');
+ const changes = parseNameStatusZ(
+ run(
+ 'git',
+ ['diff', '--name-status', '-z', '--relative', baseCommit, headCommit, '--', '.'],
+ { cwd: projectRoot },
+ ),
+ );
+ const diffPaths = pathsFromChanges(changes);
+
+ const scanPath = join(intermediateDir, 'scan-result.json');
+ const oldScan = readJson(scanPath, {});
+ const graph = readJson(join(uaDir, 'knowledge-graph.json'), {});
+ const oldFingerprints = normalizeFingerprintStore(
+ readJson(join(uaDir, 'fingerprints.json'), null),
+ baseCommit,
+ );
+ const baselineSnapshotPath = join(intermediateDir, 'incremental-baseline.json');
+ const existingSnapshot = readJson(baselineSnapshotPath, null);
+ const baselineScan = existingSnapshot?.baseCommit === baseCommit
+ ? existingSnapshot.scan
+ : oldScan;
+ if (existingSnapshot?.baseCommit !== baseCommit) {
+ atomicWriteJson(baselineSnapshotPath, { baseCommit, scan: oldScan });
+ }
+ // A failed prior attempt can leave complete or split analyzer batches behind.
+ // Remove only known internal scratch names before planning the retry so the
+ // merge cannot resurrect deleted nodes from stale output.
+ clearIncrementalScratch(intermediateDir);
+
+ const currentScanPath = join(intermediateDir, 'current-scan.json');
+ const currentScan = runScan(projectRoot, currentScanPath, args.excludePatterns);
+ const currentInventory = sorted(currentScan.files.map(file => file.path));
+ const currentInventorySet = new Set(currentInventory);
+ // If a previous attempt saved the graph but failed before fingerprints/meta,
+ // its project hash is already HEAD. Do not let that partially advanced graph
+ // redefine the previous inventory; the preserved scan + old fingerprints are
+ // the retry baseline. A graph still tied to baseCommit remains useful for
+ // recovering files omitted by an older scan/fingerprint format.
+ const graphMatchesUncommittedHead =
+ graph?.project?.gitCommitHash === headCommit && headCommit !== baseCommit;
+ const inventoryGraph = graphMatchesUncommittedHead ? {} : graph;
+ const oldInventory = inventoryFrom(baselineScan, inventoryGraph, oldFingerprints);
+ const oldInventorySet = new Set(oldInventory);
+
+ const generatedArtifactFiles = sorted(diffPaths.filter(isGeneratedArtifact));
+ const nonGeneratedDiffPaths = diffPaths.filter(path => !isGeneratedArtifact(path));
+ const deletedFiles = sorted(oldInventory.filter(path => !currentInventorySet.has(path)));
+ const ignoredFiles = sorted(
+ nonGeneratedDiffPaths.filter(
+ path => !currentInventorySet.has(path) && !oldInventorySet.has(path),
+ ),
+ );
+ const currentChangedPaths = sorted([
+ ...nonGeneratedDiffPaths.filter(path => currentInventorySet.has(path)),
+ ...currentInventory.filter(path => !oldInventorySet.has(path)),
+ ]);
+
+ const currentFingerprints = await buildCurrentFingerprints(
+ projectRoot,
+ currentChangedPaths,
+ headCommit,
+ );
+ const analysis = analyzeInventoryChanges({
+ currentChangedPaths,
+ currentFingerprints,
+ oldFingerprints,
+ oldInventory,
+ deletedFiles,
+ });
+ const decision = classifyUpdate(
+ analysis,
+ oldInventory.length,
+ oldInventory,
+ currentInventory,
+ );
+
+ const onlyGeneratedArtifacts =
+ generatedArtifactFiles.length > 0
+ && nonGeneratedDiffPaths.length === 0
+ && deletedFiles.length === 0
+ && currentChangedPaths.length === 0;
+ if (decision.action === 'SKIP') {
+ if (onlyGeneratedArtifacts) {
+ decision.reason = 'Only generated analysis artifacts changed; baseline not advanced';
+ } else if (ignoredFiles.length > 0 && analysis.cosmeticOnlyFiles.length === 0) {
+ decision.reason = `${ignoredFiles.length} changed file(s) are outside the current analysis inventory`;
+ }
+ }
+
+ const filesToReanalyze = sorted(
+ decision.filesToReanalyze.filter(path => currentInventorySet.has(path)),
+ );
+ const missingImportEntries = currentInventory.filter(
+ path => !Object.hasOwn(oldScan?.importMap ?? {}, path),
+ );
+ const importAnalysisPaths = sorted([...filesToReanalyze, ...missingImportEntries]);
+ const importMap = refreshImportMap({
+ projectRoot,
+ intermediateDir,
+ oldScan,
+ currentScan,
+ analysisPaths: importAnalysisPaths,
+ });
+
+ const refreshedScan = {
+ ...oldScan,
+ contentDigest: currentScan.contentDigest,
+ files: currentScan.files,
+ totalFiles: currentScan.totalFiles,
+ filteredByIgnore: currentScan.filteredByIgnore,
+ estimatedComplexity: currentScan.estimatedComplexity,
+ importMap,
+ };
+ delete refreshedScan.scriptCompleted;
+ delete refreshedScan.stats;
+ if (!Object.hasOwn(refreshedScan, 'name')) refreshedScan.name = basename(projectRoot);
+ if (!Object.hasOwn(refreshedScan, 'description')) refreshedScan.description = 'No description available';
+ if (!Array.isArray(refreshedScan.languages)) refreshedScan.languages = [];
+ if (!Array.isArray(refreshedScan.frameworks)) refreshedScan.frameworks = [];
+
+ // Generated-only commits intentionally keep every baseline artifact tied to
+ // the last analyzed source commit. Other zero-token paths still refresh the
+ // deterministic scan so cosmetic line counts and ignore changes are saved.
+ if (!onlyGeneratedArtifacts) atomicWriteJson(scanPath, refreshedScan);
+
+ const plan = {
+ baseCommit,
+ headCommit,
+ action: decision.action,
+ filesToReanalyze,
+ deletedFiles,
+ cosmeticFiles: analysis.cosmeticOnlyFiles,
+ ignoredFiles,
+ generatedArtifactFiles,
+ rerunArchitecture: decision.rerunArchitecture,
+ rerunTour: decision.rerunTour,
+ reason: decision.reason,
+ };
+
+ atomicWriteJson(join(intermediateDir, 'fingerprint-patch.json'), {
+ version: '1.0.0',
+ baseCommit,
+ headCommit,
+ generatedAt: currentFingerprints.generatedAt,
+ files: currentFingerprints.files,
+ deletedFiles,
+ });
+ writeFileSync(
+ join(intermediateDir, 'changed-files.txt'),
+ filesToReanalyze.length > 0 ? `${filesToReanalyze.join('\n')}\n` : '',
+ 'utf-8',
+ );
+
+ if (decision.action === 'PARTIAL_UPDATE' || decision.action === 'ARCHITECTURE_UPDATE') {
+ const pathsToReplace = new Set([...filesToReanalyze, ...deletedFiles]);
+ atomicWriteJson(
+ join(intermediateDir, 'batch-existing.json'),
+ pruneExistingGraph(graph, pathsToReplace),
+ );
+ }
+ atomicWriteJson(join(intermediateDir, 'incremental-plan.json'), plan);
+
+ process.stdout.write(
+ `Incremental plan: ${plan.action}; analyze=${filesToReanalyze.length}; ` +
+ `delete=${deletedFiles.length}; cosmetic=${plan.cosmeticFiles.length}; ` +
+ `ignored=${ignoredFiles.length}; generated=${generatedArtifactFiles.length}\n`,
+ );
+}
+
+function isCliEntry() {
+ if (!process.argv[1]) return false;
+ try {
+ return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+ } catch {
+ return false;
+ }
+}
+
+if (isCliEntry()) {
+ try {
+ await main();
+ } catch (error) {
+ process.stderr.write(`prepare-incremental.mjs failed: ${error.message}\n${error.stack}\n`);
+ process.exit(1);
+ }
+}
+
+export {
+ isGeneratedArtifact,
+ normalizeRelativePath,
+ parseNameStatusZ,
+ pruneExistingGraph,
+};