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(batching): use JSON changed-file handoff

Lum11042ddfa7326e2c
diff --git a/tests/skill/understand/test_compute_batches.test.mjs b/tests/skill/understand/test_compute_batches.test.mjs
index 768d5c0f..e366c2fe 100644
--- a/tests/skill/understand/test_compute_batches.test.mjs
+++ b/tests/skill/understand/test_compute_batches.test.mjs
@@ -749,7 +749,8 @@ describe('compute-batches.mjs — --changed-files', () => {
const changedPath = join(root, 'changed.txt');
// Only two files in the auth clique are changed. Use CRLF plus one
// backslash path to cover Windows git diff/path-list inputs.
- writeFileSync(changedPath, ['src\\auth\\login.ts', 'src/auth/tokens.ts'].join('\r\n'));
+ const loginPath = process.platform === 'win32' ? 'src\\auth\\login.ts' : 'src/auth/login.ts';
+ writeFileSync(changedPath, [loginPath, 'src/auth/tokens.ts'].join('\r\n'));
const result = runScript(root, [`--changed-files=${changedPath}`]);
expect(result.status).toBe(0);
@@ -794,6 +795,38 @@ describe('compute-batches.mjs — --changed-files', () => {
]);
});
+ it.skipIf(process.platform === 'win32')(
+ 'preserves a newline-containing path from a JSON changed-file list',
+ () => {
+ root = mkdtempSync(join(tmpdir(), 'ua-cb-newline-'));
+ const intermediate = join(root, '.understand-anything', 'intermediate');
+ const sourcePath = 'src/line\nbreak.ts';
+ mkdirSync(intermediate, { recursive: true });
+ mkdirSync(join(root, 'src'), { recursive: true });
+ writeFileSync(join(root, sourcePath), 'export const value = 1;\n');
+ writeFileSync(
+ join(intermediate, 'scan-result.json'),
+ JSON.stringify({
+ files: [{
+ path: sourcePath,
+ language: 'typescript',
+ sizeLines: 1,
+ fileCategory: 'code',
+ }],
+ importMap: { [sourcePath]: [] },
+ }),
+ );
+ const changedPath = join(root, 'changed-files.json');
+ writeFileSync(changedPath, JSON.stringify([sourcePath]));
+
+ const result = runScript(root, [`--changed-files=${changedPath}`]);
+ expect(result.status, result.stderr).toBe(0);
+ expect(readBatches(root).batches.flatMap(batch => batch.files)).toEqual([
+ expect.objectContaining({ path: sourcePath }),
+ ]);
+ },
+ );
+
it('emits only changed files inside retained batches while preserving unchanged neighbor context', () => {
root = mkdtempSync(join(tmpdir(), 'ua-cb-changed-nbr-'));
mkdirSync(join(root, '.understand-anything', 'intermediate'), { recursive: true });
diff --git a/tests/skill/understand/test_prepare_incremental.test.mjs b/tests/skill/understand/test_prepare_incremental.test.mjs
index b483e993..3875486f 100644
--- a/tests/skill/understand/test_prepare_incremental.test.mjs
+++ b/tests/skill/understand/test_prepare_incremental.test.mjs
@@ -183,7 +183,7 @@ function prepare(root, baseCommit, extraArgs = []) {
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'),
+ changedFiles: JSON.parse(readFileSync(join(intermediate, 'changed-files.json'), 'utf-8')),
};
}
@@ -209,7 +209,7 @@ describe('prepare-incremental.mjs', { timeout: 30_000 }, () => {
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(changedFiles).toEqual(['src/a.ts']);
expect(scan.importMap['src/a.ts']).toEqual(['src/b.ts']);
expect(scan.importMap['src/c.ts']).toEqual([]);
});
@@ -236,7 +236,7 @@ describe('prepare-incremental.mjs', { timeout: 30_000 }, () => {
expect(plan.action).toBe('PARTIAL_UPDATE');
expect(plan.filesToReanalyze).toEqual([]);
expect(plan.deletedFiles).toEqual(['src/b.ts']);
- expect(changedFiles).toBe('');
+ expect(changedFiles).toEqual([]);
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();
@@ -464,7 +464,7 @@ describe('prepare-incremental.mjs', { timeout: 30_000 }, () => {
expect(plan.action).toBe('SKIP');
expect(plan.cosmeticFiles).toEqual(['src/a.ts']);
expect(plan.filesToReanalyze).toEqual([]);
- expect(changedFiles).toBe('');
+ expect(changedFiles).toEqual([]);
});
it('applies a new explicit exclude against the current inventory at the same commit', () => {
@@ -599,6 +599,29 @@ describe('prepare-incremental.mjs', { timeout: 30_000 }, () => {
},
);
+ it.skipIf(process.platform === 'win32')(
+ 'preserves newline-containing paths in the JSON analyzer handoff',
+ () => {
+ const newlinePath = 'src/line\nbreak.js';
+ const { root, baseCommit } = setupRepository({
+ [newlinePath]: 'function before() { return 1; }\nmodule.exports = before;\n',
+ 'src/a.js': 'module.exports = 1;\n',
+ 'src/b.js': 'module.exports = 2;\n',
+ 'src/c.js': 'module.exports = 3;\n',
+ });
+ writeProjectFile(
+ root,
+ newlinePath,
+ 'function after() { return 1; }\nmodule.exports = after;\n',
+ );
+ commit(root, 'change newline path');
+
+ const { plan, changedFiles } = prepare(root, baseCommit);
+ expect(plan.filesToReanalyze).toEqual([newlinePath]);
+ expect(changedFiles).toEqual([newlinePath]);
+ },
+ );
+
it('keeps the same new-directory decision when preparation is retried', () => {
const { root, baseCommit } = setupRepository({
'src/a.ts': 'export const a = 1;\n',
diff --git a/understand-anything-plugin/hooks/auto-update-prompt.md b/understand-anything-plugin/hooks/auto-update-prompt.md
index 94a75f5c..aae89f73 100644
--- a/understand-anything-plugin/hooks/auto-update-prompt.md
+++ b/understand-anything-plugin/hooks/auto-update-prompt.md
@@ -48,7 +48,7 @@ Read `filesToReanalyze` from the plan. It never contains deleted, ignored, cosme
```bash
node "$PLUGIN_ROOT/skills/understand/compute-batches.mjs" "$PROJECT_ROOT" \
- --changed-files="$UA_DIR/intermediate/changed-files.txt"
+ --changed-files="$UA_DIR/intermediate/changed-files.json"
```
Dispatch file-analyzer for those batches only, using `agents/file-analyzer.md` and the batch prompt contract from the `/understand` skill. Preserve each original batch index in its output filename. Retry a failed dispatch once; if it still fails, **STOP** without running the finalizer or advancing the baseline.
diff --git a/understand-anything-plugin/skills/understand/SKILL.md b/understand-anything-plugin/skills/understand/SKILL.md
index 3d693700..319f6638 100644
--- a/understand-anything-plugin/skills/understand/SKILL.md
+++ b/understand-anything-plugin/skills/understand/SKILL.md
@@ -210,7 +210,7 @@ Determine whether to run a full analysis or incremental update.
The helper uses parameterized `git diff --name-status -z`, performs a fresh deterministic scan with the current `.understandignore` / `--exclude` rules, compares structural fingerprints, selectively refreshes imports, and atomically writes:
- `$UA_DIR/intermediate/incremental-plan.json`
- `$UA_DIR/intermediate/scan-result.json`
- - `$UA_DIR/intermediate/changed-files.txt`
+ - `$UA_DIR/intermediate/changed-files.json`
- `$UA_DIR/intermediate/batch-existing.json` for partial/architecture updates
Read `incremental-plan.json` and store its `action`, `filesToReanalyze`, `deletedFiles`, `rerunArchitecture`, and `rerunTour` values. Follow this gate:
@@ -318,7 +318,7 @@ For `PARTIAL_UPDATE` or `ARCHITECTURE_UPDATE`, inspect `filesToReanalyze` from t
```bash
node "<SKILL_DIR>/compute-batches.mjs" "$PROJECT_ROOT" \
- --changed-files="$UA_DIR/intermediate/changed-files.txt"
+ --changed-files="$UA_DIR/intermediate/changed-files.json"
```
Both forms read the freshly reconciled `$UA_DIR/intermediate/scan-result.json` and write `$UA_DIR/intermediate/batches.json`.
diff --git a/understand-anything-plugin/skills/understand/compute-batches.mjs b/understand-anything-plugin/skills/understand/compute-batches.mjs
index ed5d0933..101ffb34 100644
--- a/understand-anything-plugin/skills/understand/compute-batches.mjs
+++ b/understand-anything-plugin/skills/understand/compute-batches.mjs
@@ -256,13 +256,26 @@ function buildBatchOfMap(allBatches) {
}
function normalizeRelativePathForMatch(pathText) {
- return pathText
- .trim()
- .replace(/\\/g, '/')
+ if (typeof pathText !== 'string') return '';
+ const platformPath = process.platform === 'win32' ? pathText.replace(/\\/g, '/') : pathText;
+ return platformPath
.replace(/^\.\/+/, '')
.replace(/\/+/g, '/');
}
+function parseChangedFileList(content, filePath) {
+ if (filePath.toLowerCase().endsWith('.json') || content.trimStart().startsWith('[')) {
+ const parsed = JSON.parse(content);
+ if (!Array.isArray(parsed) || parsed.some(path => typeof path !== 'string')) {
+ throw new Error('JSON changed-file list must be an array of strings');
+ }
+ return parsed.map(normalizeRelativePathForMatch).filter(Boolean);
+ }
+ // Backwards compatibility for existing newline-delimited callers. New
+ // incremental handoffs use JSON so embedded newlines remain unambiguous.
+ return content.split(/\r?\n/).map(normalizeRelativePathForMatch).filter(Boolean);
+}
+
// ECMAScript string comparison uses a stable UTF-16 code-unit order and does
// not depend on the host locale or ICU version.
function comparePaths(a, b) {
@@ -417,11 +430,15 @@ async function main() {
);
process.exit(1);
}
- const lines = content
- .split('\n')
- .map(normalizeRelativePathForMatch)
- .filter(Boolean);
- changedFiles = new Set(lines);
+ try {
+ changedFiles = new Set(parseChangedFileList(content, changedFilesPath));
+ } catch (err) {
+ process.stderr.write(
+ `Error: compute-batches: --changed-files contents invalid: ${changedFilesPath} ` +
+ `(${err.message})\n`,
+ );
+ process.exit(1);
+ }
}
const scanResultValue = helperOptions.get('scan-result');
diff --git a/understand-anything-plugin/skills/understand/prepare-incremental.mjs b/understand-anything-plugin/skills/understand/prepare-incremental.mjs
index d3341df8..b2156475 100644
--- a/understand-anything-plugin/skills/understand/prepare-incremental.mjs
+++ b/understand-anything-plugin/skills/understand/prepare-incremental.mjs
@@ -8,7 +8,7 @@
*
* Writes under <UA_DIR>/intermediate:
* - incremental-plan.json
- * - changed-files.txt
+ * - changed-files.json
* - fingerprint-patch.json
* - incremental-baseline.json (retry-safe copy of the pre-update scan)
* - batch-existing.json (PARTIAL/ARCHITECTURE only)
@@ -673,11 +673,7 @@ async function main() {
files: currentFingerprints.files,
deletedFiles,
});
- writeFileSync(
- join(intermediateDir, 'changed-files.txt'),
- filesToReanalyze.length > 0 ? `${filesToReanalyze.join('\n')}\n` : '',
- 'utf-8',
- );
+ atomicWriteJson(join(intermediateDir, 'changed-files.json'), filesToReanalyze);
if (decision.action === 'PARTIAL_UPDATE' || decision.action === 'ARCHITECTURE_UPDATE') {
const pathsToReplace = new Set([...filesToReanalyze, ...deletedFiles]);