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(bench): isolate reproducible benchmark inputs
KumamuKumac4bdcf26b9a2
diff --git a/tests/skill/understand/test_scan_project.test.mjs b/tests/skill/understand/test_scan_project.test.mjsindex 1409daac..ace61e94 100644--- a/tests/skill/understand/test_scan_project.test.mjs+++ b/tests/skill/understand/test_scan_project.test.mjs@@ -7,6 +7,7 @@ import {rmSync,chmodSync,existsSync,+ symlinkSync,} from 'node:fs';import { tmpdir } from 'node:os';import { join, dirname, resolve } from 'node:path';@@ -60,12 +61,13 @@ const _runScriptOutputDirs = [];* { status, stdout, stderr, output } where `output` is the parsed JSON* written by the script (or null on failure).*/-function runScript(projectRoot) {+function runScript(projectRoot, extraArgs = [], envOverrides = {}) {const outputDir = mkdtempSync(join(tmpdir(), 'ua-scan-out-'));_runScriptOutputDirs.push(outputDir);const outputPath = join(outputDir, 'scan-output.json');- const result = spawnSync('node', [SCRIPT, projectRoot, outputPath], {+ const result = spawnSync('node', [SCRIPT, projectRoot, outputPath, ...extraArgs], {encoding: 'utf-8',+ env: { ...process.env, ...envOverrides },});let output = null;try {@@ -517,6 +519,19 @@ describe('scan-project.mjs — data-dir resolution (.ua vs legacy)', () => {expect(byPath(r.output, 'fixtures/snap2.json')).toBeUndefined();expect(r.output.filteredByIgnore).toBe(2);});++ it('can exclude persistent analysis data for isolated benchmark scans', () => {+ projectRoot = setupTree({+ '.ua/knowledge-graph.json': '{ "nodes": [] }\n',+ '.understand-anything/meta.json': '{ "version": 1 }\n',+ 'src/index.ts': 'export const x = 1;\n',+ });++ const r = runScript(projectRoot, ['--exclude-analysis-data']);++ expect(r.status).toBe(0);+ expect(r.output.files.map(file => file.path)).toEqual(['src/index.ts']);+ });});describe('scan-project.mjs — special-file recognition', () => {@@ -567,6 +582,105 @@ describe('scan-project.mjs — determinism', () => {expect(r2.status).toBe(0);expect(JSON.stringify(r1.output)).toBe(JSON.stringify(r2.output));});++ it('keeps Unicode and space-containing paths stable across process locales', () => {+ projectRoot = setupTree({+ '!bang.ts': 'export const bang = true;\n',+ '_under.ts': 'export const under = true;\n',+ 'space dir/å.ts': 'export const nested = true;\n',+ 'ä.ts': 'export const umlaut = true;\n',+ '中.ts': 'export const cjk = true;\n',+ });++ const cLocale = runScript(projectRoot, [], { LANG: 'C', LC_ALL: 'C' });+ const swedishLocale = runScript(projectRoot, [], {+ LANG: 'sv_SE.UTF-8',+ LC_ALL: 'sv_SE.UTF-8',+ });+ const expectedPaths = [+ '!bang.ts',+ '_under.ts',+ 'space dir/å.ts',+ 'ä.ts',+ '中.ts',+ ];++ expect(cLocale.status).toBe(0);+ expect(swedishLocale.status).toBe(0);+ expect(cLocale.output.files.map(file => file.path)).toEqual(expectedPaths);+ expect(swedishLocale.output.files.map(file => file.path)).toEqual(expectedPaths);+ expect(JSON.stringify(cLocale.output)).toBe(JSON.stringify(swedishLocale.output));+ });++ it('emits a top-level lowercase SHA-256 content fingerprint as contentDigest', () => {+ projectRoot = setupTree({+ 'src/value.ts': 'export const value = 1;\n',+ });++ const result = runScript(projectRoot);++ expect(result.status).toBe(0);+ expect(result.output.contentDigest).toMatch(/^[0-9a-f]{64}$/);+ });++ it('changes the content fingerprint when bytes change but metadata does not', () => {+ projectRoot = setupTree({+ 'src/value.ts': 'export const value = "aa";\n',+ });+ const before = runScript(projectRoot);++ writeFileSync(+ join(projectRoot, 'src/value.ts'),+ 'export const value = "bb";\n',+ 'utf-8',+ );+ const after = runScript(projectRoot);++ expect(before.status).toBe(0);+ expect(after.status).toBe(0);+ expect(byPath(before.output, 'src/value.ts').sizeLines).toBe(1);+ expect(byPath(after.output, 'src/value.ts').sizeLines).toBe(1);+ expect(after.output.files).toEqual(before.output.files);+ expect(after.output.contentDigest).not.toBe(before.output.contentDigest);+ });++ it('omits a Git-tracked outbound symlink and never fingerprints its target bytes', () => {+ projectRoot = setupTree({+ 'src/inside.ts': 'export const inside = true;\n',+ });+ const externalRoot = mkdtempSync(join(tmpdir(), 'ua-scan-external-'));+ const externalFile = join(externalRoot, 'secret.ts');++ try {+ writeFileSync(externalFile, 'export const secret = "first";\n', 'utf-8');+ try {+ symlinkSync(externalFile, join(projectRoot, 'outbound-link.ts'), 'file');+ } catch (error) {+ if (process.platform === 'win32') return;+ throw error;+ }+ const add = spawnSync('git', ['add', '--', 'outbound-link.ts'], {+ cwd: projectRoot,+ encoding: 'utf-8',+ });+ expect(add.status).toBe(0);++ const before = runScript(projectRoot);+ writeFileSync(externalFile, 'export const secret = "second";\n', 'utf-8');+ const after = runScript(projectRoot);++ expect(before.status).toBe(0);+ expect(after.status).toBe(0);+ expect(byPath(before.output, 'src/inside.ts')).toBeDefined();+ expect(byPath(before.output, 'outbound-link.ts')).toBeUndefined();+ expect(before.stderr).toMatch(+ /Warning: scan-project: outbound-link\.ts — symbolic link skipped — file skipped from output/,+ );+ expect(after.output.contentDigest).toBe(before.output.contentDigest);+ } finally {+ rmSync(externalRoot, { recursive: true, force: true });+ }+ });});describe('scan-project.mjs — empty repo', () => {@@ -767,6 +881,7 @@ describe('scan-project.mjs — output schema invariants', () => {expect(typeof out.totalFiles).toBe('number');expect(out.totalFiles).toBe(out.files.length);expect(typeof out.filteredByIgnore).toBe('number');+ expect(out.contentDigest).toMatch(/^[0-9a-f]{64}$/);expect(['small', 'moderate', 'large', 'very-large']).toContain(out.estimatedComplexity,);@@ -776,6 +891,9 @@ describe('scan-project.mjs — output schema invariants', () => {expect(typeof out.stats.byLanguage).toBe('object');// Per-file shapefor (const f of out.files) {+ expect(Object.keys(f).sort()).toEqual([+ 'fileCategory', 'language', 'path', 'sizeLines',+ ]);expect(typeof f.path).toBe('string');expect(typeof f.language).toBe('string');expect(typeof f.sizeLines).toBe('number');@@ -785,17 +903,17 @@ describe('scan-project.mjs — output schema invariants', () => {}});- it('files[] is sorted by path.localeCompare', () => {+ it('files[] is sorted by a locale-independent code-unit order', () => {projectRoot = setupTree({- 'zzz.ts': '\n',- 'aaa.ts': '\n',- 'mmm.ts': '\n',- 'subdir/file.ts': '\n',+ '!bang.ts': '\n',+ '0.ts': '\n',+ '_under.ts': '\n',+ 'a.ts': '\n',+ 'ä.ts': '\n',});const r = runScript(projectRoot);expect(r.status).toBe(0);const paths = r.output.files.map(f => f.path);- const sortedPaths = [...paths].sort((a, b) => a.localeCompare(b));- expect(paths).toEqual(sortedPaths);+ expect(paths).toEqual(['!bang.ts', '0.ts', '_under.ts', 'a.ts', 'ä.ts']);});});diff --git a/understand-anything-plugin/skills/understand/scan-project.mjs b/understand-anything-plugin/skills/understand/scan-project.mjsindex 20f299f2..1a59ca01 100644--- a/understand-anything-plugin/skills/understand/scan-project.mjs+++ b/understand-anything-plugin/skills/understand/scan-project.mjs@@ -26,13 +26,14 @@* - Complexity estimation (project-scanner.md Step 7 thresholds)** Usage:- * node scan-project.mjs <projectRoot> <outputPath>+ * node scan-project.mjs <projectRoot> <outputPath> [--exclude-analysis-data]** Output JSON (subset of what project-scanner.md Phase 1 expects — the LLM* agent merges this with Step A's narrative fields and Step C's importMap to* produce the final scan-result.json):* {* "scriptCompleted": true,+ * "contentDigest": "<sha256 lowercase hex>",* "files": [{ "path": "...", "language": "...", "sizeLines": N, "fileCategory": "..." }, ...],* "totalFiles": N,* "filteredByIgnore": M,@@ -45,16 +46,18 @@* `Warning: scan-project: <path> — <reason> — file skipped from output`* to stderr and the file is dropped; the rest of the scan completes.*- * Determinism: files are sorted by `path.localeCompare` before emission, and- * the underlying enumeration is deterministic (git ls-files returns a stable- * order; the fallback walker sorts each directory's entries).+ * Determinism: files are sorted by a locale-independent UTF-16 code-unit+ * comparison before emission. The content digest uses that same order and+ * length-frames each UTF-8 relative path plus its raw file bytes.*/import { createRequire } from 'node:module';+import { createHash } from 'node:crypto';import { dirname, resolve, join, basename, extname, relative, sep } from 'node:path';import { fileURLToPath, pathToFileURL } from 'node:url';import {existsSync,+ lstatSync,readFileSync,readdirSync,realpathSync,@@ -458,6 +461,17 @@ function toPosix(p) {return p.split(sep).join('/');}+/**+ * Locale-independent string order. ECMAScript relational string comparison+ * is lexicographic over UTF-16 code units, so the result cannot vary with ICU,+ * process locale, or operating system settings.+ */+function compareStableStrings(a, b) {+ if (a < b) return -1;+ if (a > b) return 1;+ return 0;+}+/*** Enumerate all files in `projectRoot` via `git ls-files`. Returns an* array of project-relative POSIX paths, or null if the directory is not@@ -531,7 +545,7 @@ function enumerateViaWalk(projectRoot) {// Sort deterministically by name; mix files and dirs together so the// final output (after the path sort) is identical regardless of// OS-specific readdir order.- entries.sort((a, b) => a.name.localeCompare(b.name));+ entries.sort((a, b) => compareStableStrings(a.name, b.name));for (const ent of entries) {if (ent.isDirectory()) {if (HARD_SKIP_DIRS.has(ent.name)) continue;@@ -621,15 +635,15 @@ function hasUserIgnoreFile(projectRoot) {// ---------------------------------------------------------------------------/**- * Count newline-delimited lines in a file. Returns the number of `\n`- * characters; this matches `wc -l` semantics (which counts newlines, not- * "lines of content"). Files without a trailing newline therefore report- * one fewer than the visible line count — same behavior as wc.+ * Read a file once and count its newline-delimited lines. Returns both the raw+ * bytes and the number of `\n` characters; the caller feeds those same bytes+ * directly into the content digest without a second read or a whole-repo+ * content concatenation. The count matches `wc -l` semantics.** Per-file failure: emits a Warning: and returns null. Caller decides* whether to drop the file or keep it with sizeLines=0.*/-function countLines(absPath, posixPath) {+function readAndCountLines(absPath, posixPath) {try {const buf = readFileSync(absPath);// Manual newline count beats split('\n').length on large files — no@@ -638,7 +652,7 @@ function countLines(absPath, posixPath) {for (let i = 0; i < buf.length; i++) {if (buf[i] === 0x0a) count++;}- return count;+ return { bytes: buf, sizeLines: count };} catch (err) {process.stderr.write(`Warning: scan-project: ${posixPath} — line count failed ` +@@ -648,18 +662,44 @@ function countLines(absPath, posixPath) {}}+const CONTENT_DIGEST_DOMAIN = Buffer.from('understand-anything:scan-content:v1\0', 'utf-8');++/**+ * Add one scanned regular file to the aggregate fingerprint. Entries arrive+ * in compareStableStrings path order. Each frame is:+ * uint32be(path UTF-8 byte length) || uint64be(content byte length) ||+ * UTF-8 path bytes || raw content bytes+ * Length prefixes make path/content and adjacent-entry boundaries unambiguous.+ */+function updateContentDigest(hash, posixPath, contentBytes) {+ const pathBytes = Buffer.from(posixPath, 'utf-8');+ const lengths = Buffer.allocUnsafe(12);+ lengths.writeUInt32BE(pathBytes.length, 0);+ lengths.writeBigUInt64BE(BigInt(contentBytes.length), 4);+ hash.update(lengths);+ hash.update(pathBytes);+ hash.update(contentBytes);+}+// ---------------------------------------------------------------------------// Main// ---------------------------------------------------------------------------async function main() {- const [, , projectRoot, outputPath] = process.argv;+ const [, , projectRoot, outputPath, ...options] = process.argv;if (!projectRoot || !outputPath) {process.stderr.write(- 'Usage: node scan-project.mjs <projectRoot> <outputPath>\n',+ 'Usage: node scan-project.mjs <projectRoot> <outputPath> ' ++ '[--exclude-analysis-data]\n',);process.exit(1);}+ const unknownOption = options.find(option => option !== '--exclude-analysis-data');+ if (unknownOption) {+ process.stderr.write(`scan-project.mjs failed: unknown option: ${unknownOption}\n`);+ process.exit(1);+ }+ const excludeAnalysisData = options.includes('--exclude-analysis-data');if (!existsSync(projectRoot)) {process.stderr.write(@@ -676,7 +716,11 @@ async function main() {}// 1. Enumerate. Either git ls-files or recursive walk.- const candidates = enumerateFiles(projectRoot);+ const candidates = enumerateFiles(projectRoot).filter(+ rel =>+ !excludeAnalysisData ||+ (!rel.startsWith('.ua/') && !rel.startsWith('.understand-anything/')),+ );// 2. Filter via createIgnoreFilter (defaults + user .understandignore).// Build a defaults-only filter in parallel to count user-driven drops.@@ -701,42 +745,56 @@ async function main() {}}+ // The per-file pass, output, stats key insertion, and content fingerprint+ // all consume this one locale-independent path order.+ kept.sort(compareStableStrings);+// 3. Per-file: language + category + line count.// Drop files that fail line counting (per-file resilience).const fileEntries = [];+ const contentHash = createHash('sha256');+ contentHash.update(CONTENT_DIGEST_DOMAIN);for (const rel of kept) {const absPath = join(projectRoot, rel);- // Stat first — git ls-files could include paths that vanished between- // listing and processing; the walker shouldn't but defensive anyway.+ // lstat first so Git-enumerated symlinks are rejected before any operation+ // can follow them to a repository-external target.try {- const st = statSync(absPath);+ const st = lstatSync(absPath);+ if (st.isSymbolicLink()) {+ process.stderr.write(+ `Warning: scan-project: ${rel} — symbolic link skipped ` ++ `— file skipped from output\n`,+ );+ continue;+ }if (!st.isFile()) {- // Symlinks-to-dir, special files, etc. — skip silently. Not a- // warning condition because git wouldn't have tracked it as a file.+ // Directories and special files are not scanned as regular-file input.continue;}} catch (err) {process.stderr.write(- `Warning: scan-project: ${rel} — stat failed (${err.message}) ` ++ `Warning: scan-project: ${rel} — lstat failed (${err.message}) ` +`— file skipped from output\n`,);continue;}- const sizeLines = countLines(absPath, rel);- if (sizeLines === null) {- // countLines already emitted the Warning: line.+ const scanned = readAndCountLines(absPath, rel);+ if (scanned === null) {+ // readAndCountLines already emitted the Warning: line.continue;}+ updateContentDigest(contentHash, rel, scanned.bytes);fileEntries.push({path: rel,language: detectLanguage(rel),- sizeLines,+ sizeLines: scanned.sizeLines,fileCategory: detectCategory(rel),});}- // 4. Determinism: sort by path.localeCompare.- fileEntries.sort((a, b) => a.path.localeCompare(b.path));+ // 4. Determinism: preserve the documented locale-independent path order.+ fileEntries.sort((a, b) => compareStableStrings(a.path, b.path));+ const contentDigest = contentHash.digest('hex');// 5. Stats.const byCategory = {};@@ -750,6 +808,7 @@ async function main() {const output = {scriptCompleted: true,+ contentDigest,files: fileEntries,totalFiles: fileEntries.length,filteredByIgnore,