@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/reverse/cluster.js

@@ -0,0 +1,187 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COHESION_MIN = exports.MAX_FILES = exports.MIN_FILES = void 0;
+exports.clusterFiles = clusterFiles;
+// @implements A-SPEC-126
+const path = __importStar(require("node:path"));
+/**
+ * Partition a scanned brownfield tree into A-SPEC-sized candidate slices.
+ *
+ * Directory locality does the first cut; call cohesion decides whether a directory is ONE slice or a
+ * bag of independent modules. Pure and deterministic: same input files -> byte-identical output, so a
+ * proposed partition can be diffed and re-checked rather than taken on trust.
+ */
+/** Directory names that make a cluster a T-SPEC's business rather than an A-SPEC candidate. */
+const TEST_DIR_RE = /(^|\/)(tests?|__tests__|specs?|e2e|fixtures)(\/|$)/;
+/** A directory with fewer files than this is folded into its nearest ancestor before classification. */
+exports.MIN_FILES = 3;
+/** Above this a cohesive cluster is flagged `oversized` — reported, never split (H-SPEC-126). */
+exports.MAX_FILES = 25;
+/**
+ * Cohesion threshold: ANY resolved internal call makes a directory cohesive.
+ *
+ * Derived, not chosen. Re-measured from the graph's own `calls` edges across a Python target and this
+ * repository, independent directories measure 0.00 and every cohesive one at least 0.17 — the classes
+ * separate at exactly zero. Zero is safe as a cutoff precisely because edge resolution is
+ * precision-first: an ambiguous callee resolves to nothing, so a single internal edge is evidence
+ * rather than a guess. Exported and named so a target with an unusual layout can raise it.
+ */
+exports.COHESION_MIN = 1;
+/**
+ * Extensions whose call edges the scanner can actually extract (`extractEdgesFromTree` implements
+ * TS/JS and Python only).
+ *
+ * This distinction is load-bearing. For Go/Java/Rust/C#/C++ a scan yields zero edges because the
+ * analyzer cannot see calls — not because the files are independent. Reading that zero as
+ * independence would split every such package per file and make each slice's blast radius wrong by
+ * construction, which is the exact error the split rule exists to prevent. Absence of evidence is
+ * reported as `unmeasured`, and an unmeasured cluster is left whole for a human to judge.
+ */
+const EDGE_CAPABLE_RE = /\.(ts|mts|cts|tsx|jsx|js|mjs|cjs|py)$/;
+/** Byte-stable comparator. `localeCompare` is locale-dependent and would break determinism. */
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * Resolve a callee name to the file that defines it, exactly as rtm-builder does, so cohesion
+ * measures the SAME edges the graph holds: an own-file definition wins, a uniquely-owned name
+ * resolves, and an ambiguous one resolves to nothing rather than to a guess.
+ */
+function makeResolver(files) {
+    const owner = new Map();
+    for (const f of files) {
+        for (const s of f.symbols) {
+            if (!owner.has(s.qualifiedName))
+                owner.set(s.qualifiedName, new Set());
+            owner.get(s.qualifiedName).add(f.sourcePath);
+        }
+    }
+    // A bare callee (`save`) can only be matched against the LAST segment of a qualified name
+    // (`Store.save`). A last segment owned by more than one name is ambiguous and resolves to nothing.
+    const byLast = new Map();
+    for (const [qn, paths] of owner) {
+        const last = qn.includes('.') ? qn.slice(qn.lastIndexOf('.') + 1) : qn;
+        if (byLast.has(last))
+            byLast.set(last, null);
+        else
+            byLast.set(last, paths);
+    }
+    return (fromPath, to) => {
+        const paths = owner.get(to) ?? byLast.get(to) ?? null;
+        if (!paths)
+            return null;
+        if (paths.has(fromPath))
+            return fromPath;
+        return paths.size === 1 ? [...paths][0] : null;
+    };
+}
+function clusterFiles(files, opts = {}) {
+    const { minFiles = exports.MIN_FILES, maxFiles = exports.MAX_FILES, cohesionMin = exports.COHESION_MIN } = opts;
+    const resolve = makeResolver(files);
+    const byDir = new Map();
+    for (const f of files) {
+        const d = path.posix.dirname(f.sourcePath);
+        if (!byDir.has(d))
+            byDir.set(d, []);
+        byDir.get(d).push(f);
+    }
+    // Fold undersized directories into the nearest ancestor that holds files. Deepest first, so a
+    // chain of thin directories collapses upward in one pass. The tie-break keeps the traversal order
+    // independent of the order files arrived in.
+    const dirs = [...byDir.keys()].sort((a, b) => b.length - a.length || cmp(a, b));
+    for (const d of dirs) {
+        const group = byDir.get(d);
+        if (!group || group.length >= minFiles || d === '.')
+            continue;
+        let parent = path.posix.dirname(d);
+        while (parent !== '.' && !byDir.has(parent))
+            parent = path.posix.dirname(parent);
+        const target = byDir.has(parent) ? parent : '.';
+        if (target === d)
+            continue;
+        // Folding is a SIZE rule and must never override the KIND rule. A two-file `fixtures/` beside a
+        // cohesive module would otherwise be absorbed into it and drafted as production code — and the
+        // scanner's own test-file filter does not catch `fixtures/`. An undersized test directory simply
+        // stays its own (test) cluster, which is where it gets reported separately anyway.
+        if (TEST_DIR_RE.test(d) !== TEST_DIR_RE.test(target))
+            continue;
+        if (!byDir.has(target))
+            byDir.set(target, []);
+        byDir.get(target).push(...group);
+        byDir.delete(d);
+    }
+    const out = [];
+    for (const [dir, group] of byDir) {
+        const inDir = new Set(group.map((f) => f.sourcePath));
+        let internalCalls = 0;
+        for (const f of group) {
+            for (const e of f.edges ?? []) {
+                if (e.rel !== 'calls')
+                    continue;
+                const target = resolve(f.sourcePath, e.to);
+                // A call that lands back in its own file says nothing about whether the file belongs with
+                // its neighbours, so only cross-file, same-directory calls count.
+                if (target && target !== f.sourcePath && inDir.has(target))
+                    internalCalls++;
+            }
+        }
+        const measurable = group.some((f) => EDGE_CAPABLE_RE.test(f.sourcePath));
+        const density = internalCalls / group.length;
+        const cohesion = !measurable ? 'unmeasured' : internalCalls >= cohesionMin ? 'cohesive' : 'independent';
+        const isTest = TEST_DIR_RE.test(dir);
+        if (cohesion === 'independent') {
+            // A bag of independent modules: each file is its own candidate. Folding N unrelated modules
+            // into one slice makes every blast-radius answer wrong by roughly N — and N does not have to be
+            // large for that to be wrong, which is why this is NOT gated on size. Directories too small to
+            // deserve a slice were already folded into a parent above.
+            for (const f of [...group].sort((a, b) => cmp(a.sourcePath, b.sourcePath))) {
+                out.push({
+                    dir, files: [f.sourcePath], symbols: f.symbols.length,
+                    internalCalls: 0, density, cohesion, split: 'per-file', isTest, oversized: false, testFiles: [],
+                });
+            }
+        }
+        else {
+            out.push({
+                dir,
+                files: group.map((f) => f.sourcePath).sort(cmp),
+                symbols: group.reduce((n, f) => n + f.symbols.length, 0),
+                internalCalls, density, cohesion, split: 'whole', isTest,
+                oversized: group.length > maxFiles, testFiles: [],
+            });
+        }
+    }
+    // Total deterministic order: repeated runs on an unchanged tree must be byte-identical.
+    return out.sort((a, b) => cmp(`${a.dir} ${a.files[0]}`, `${b.dir} ${b.files[0]}`));
+}

package/dist/holmes/reverse/draft.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INFERRED = void 0;
+exports.clusterKeyOf = clusterKeyOf;
+exports.nextIdBase = nextIdBase;
+exports.draftSpecs = draftSpecs;
+const surface_1 = require("./surface");
+/**
+ * Draft the H-SPEC/A-SPEC/T-SPEC documents for one recovered cluster.
+ *
+ * Pure, deterministic, and deliberately INCOMPLETE. Structural sections are filled from scan
+ * evidence; every prose section is left as an explicit `TODO` for a human, because the only thing a
+ * scan can testify to is what the code does — never why it exists. `status: 'draft'` is hard-coded
+ * rather than defaulted, so no argument can promote a description into a normative spec.
+ *
+ * NO CODE PATH HERE CREATES A REQ. A requirement is business intent, which is not in the code;
+ * `parentReqId` is mandatory and a missing one is a refusal, not a prompt to invent one.
+ */
+const DESCRIPTIVE_NOTE = 'NOTE: this spec was REVERSE-ENGINEERED from existing code. It describes what the code does today, ' +
+    'not what it should do. Every prose section below is a TODO for a human; approving this document ' +
+    'is the point at which a description becomes a normative specification.';
+const STRUCTURAL = '<!-- structural: derived from scan evidence -->';
+/**
+ * Exported so the approval-blocker judge can recognise an untouched draft by the marker this file
+ * plants, rather than re-typing the literal. A copy would drift silently the first time this string
+ * changes — and a silent divergence is the very class of defect REQ-182 exists to close.
+ */
+exports.INFERRED = '<!-- inferred: not recoverable from code — a human writes this -->';
+const structural = (body) => `${body}\n\n${STRUCTURAL}`;
+const todo = (prompt) => `TODO — ${prompt}\n\n${exports.INFERRED}`;
+/**
+ * Scan evidence followed by a TODO — the section is FILLED but still BLOCKS approval.
+ *
+ * This is the whole point of A-SPEC-181's split. Stating what the scanner saw turns the human's job
+ * from writing a blank section into editing a draft, which is where the cost actually was. It does
+ * not turn evidence into a decision, so the `TODO`/`INFERRED` pair REQ-182 judges on stays planted:
+ * a symbol dump must never acquire a seal by looking full.
+ */
+const evidenceThenTodo = (body, prompt) => `${body}\n\n${STRUCTURAL}\n\n${todo(prompt)}`;
+/** The identity of a cluster: its directory, or the file itself when the directory split per file. */
+function clusterKeyOf(cluster) {
+    return cluster.split === 'per-file' ? cluster.files[0] : cluster.dir;
+}
+/**
+ * The first id number above every number already in use, across all spec kinds.
+ *
+ * Kind-agnostic on purpose: the three drafted documents share one number (H-SPEC-N / A-SPEC-N /
+ * T-SPEC-N), so the base must be free for every kind at once. Deterministic given the same spec set.
+ */
+function nextIdBase(existingIds) {
+    let max = 99;
+    for (const id of existingIds) {
+        const m = /-(\d{3,})(?:\.\d+)?$/.exec(id);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return max + 1;
+}
+function draftSpecs(cluster, parentReqId, idBase, evidence) {
+    if (typeof parentReqId !== 'string' || parentReqId.trim() === '') {
+        return {
+            ok: false,
+            reason: 'parentReqId is required. A REQ states business intent, which does not exist in the code and ' +
+                'cannot be recovered from it — write the REQ first, then re-run with its id.',
+        };
+    }
+    if (cluster.isTest) {
+        return { ok: false, reason: `cluster "${cluster.dir}" is rooted in a test directory — tests implement nothing, so no A-SPEC is drafted for them` };
+    }
+    const base = String(idBase);
+    if (!/^\d{3,}$/.test(base)) {
+        return { ok: false, reason: `id base "${base}" must be at least three digits to form valid spec ids` };
+    }
+    const req = parentReqId.trim();
+    const hspecId = `H-SPEC-${base}`;
+    const aspecId = `A-SPEC-${base}`;
+    const tspecId = `T-SPEC-${base}`;
+    const key = clusterKeyOf(cluster);
+    const testFiles = cluster.testFiles ?? [];
+    // Test paths belong in Files to Touch as much as production ones do: they are anchored to this
+    // A-SPEC (that anchor is what makes per-A-SPEC test evidence exist), and the gate's scope check
+    // would otherwise refuse the very edits the anchor invites.
+    const fileList = [
+        ...cluster.files.map((f) => `- \`${f}\``),
+        ...(testFiles.length ? ['', 'Tests attached to this slice by name evidence:', ...testFiles.map((f) => `- \`${f}\``)] : []),
+    ].join('\n');
+    const testsLine = testFiles.length
+        ? `${testFiles.length} existing test file(s) cover this slice and are anchored to it:\n\n${testFiles.map((f) => `- \`${f}\``).join('\n')}`
+        : 'No existing test file could be attached to this slice by name evidence — either it has none, or their names do not identify their subject. Until one is anchored here, this slice has no per-A-SPEC test evidence.';
+    const cohesionLine = `Cohesion: ${cluster.internalCalls} resolved internal call(s) across ${cluster.files.length} file(s) ` +
+        `(density ${cluster.density.toFixed(2)}) → ${cluster.cohesion}, kept as "${cluster.split}".` +
+        (cluster.cohesion === 'unmeasured'
+            ? ' The scanner cannot extract call edges for this language, so the absence of calls is NOT evidence of independence — a human must confirm the boundary.'
+            : '');
+    // Recorded on every emitted document: `reverse_cluster` is the identity a re-run matches against so
+    // it never drafts the same cluster twice, and `reverse_engineered` marks the document as descriptive.
+    const provenance = { reverse_engineered: true, reverse_cluster: key, reverse_parent_req: req };
+    const specs = [
+        {
+            id: hspecId, type: 'H-SPEC', title: `Recovered slice: ${key}`, status: 'draft', dependsOn: [req],
+            frontmatter: { req_type: 'functional', owner: 'TODO', ...provenance },
+            sections: {
+                Intent: `${DESCRIPTIVE_NOTE}\n\nTODO — state what this slice is FOR. Reverse engineering recovers what the code DOES; intent lives with people, not in the source.\n\n${exports.INFERRED}`,
+                'Scope (In / Out)': structural(`In: ${cluster.files.length} file(s) under \`${cluster.dir}\`.\n\n${fileList}\n\nOut: everything not listed above.`),
+                'Design Overview': structural(cohesionLine),
+                'Interfaces / Contracts': evidence
+                    ? evidenceThenTodo((0, surface_1.renderSurface)(evidence.surface), '위 목록에서 공개 표면이 아닌 것을 지우고, 남은 것이 무엇을 약속하는지 적어라. ' +
+                        '중첩 함수와 밑줄로 시작하는 이름은 이미 제외돼 있다.')
+                    : todo("name the contracts this slice exposes. The scan counts symbols; it cannot tell which are a public surface."),
+                'Acceptance Criteria': todo('state what "correct" means for this slice. Existing behavior is evidence, not a criterion.'),
+                'Non-Functional': todo('state the latency/throughput/availability obligations this slice actually carries.'),
+                Assumptions: structural(cohesionLine),
+                'Open Questions': todo('list what the code could not answer — dynamic wiring, config-driven behavior, external contracts.'),
+            },
+        },
+        {
+            id: aspecId, type: 'A-SPEC', title: `Recovered slice implementation: ${key}`, status: 'draft', dependsOn: [hspecId],
+            frontmatter: { slice: key, priority: 'TODO', independent_test: false, ...provenance },
+            sections: {
+                Objective: `${DESCRIPTIVE_NOTE}\n\nTODO — describe the objective this code serves.\n\n${exports.INFERRED}`,
+                'Inputs / Outputs': todo('describe the inputs and outputs. The scan sees symbols, not data contracts.'),
+                Behavior: todo('describe the behavior this code implements today, then decide whether it is the behavior you want.'),
+                'Test Points': evidence
+                    ? evidenceThenTodo((0, surface_1.renderTestPoints)(evidence), '위 테스트가 이미 고정하는 성질과, 아직 아무도 고정하지 않은 성질을 갈라 적어라. ' +
+                        '테스트 파일의 존재는 그 성질이 무엇인지 말해주지 않는다.')
+                    : todo('list the properties worth pinning. Existing tests, if any, are listed in the scan report.'),
+                'Files to Touch': structural(fileList),
+                // Filled unconditionally: it needs only the cluster's own files and attached tests, and its
+                // three clauses are checkable as written — so this section does NOT keep a TODO and does not
+                // block approval. Clause 3 survives even at zero tests; see renderDoneWhen.
+                'Done When': structural((0, surface_1.renderDoneWhen)(cluster.files, testFiles)),
+            },
+        },
+        {
+            id: tspecId, type: 'T-SPEC', title: `Recovered slice tests: ${key}`, status: 'draft', dependsOn: [aspecId],
+            frontmatter: { coverage: { normal: false, corner: false, negative: false, boundary: false }, ...provenance },
+            sections: {
+                'Normal Cases': `${DESCRIPTIVE_NOTE}\n\n${testsLine}\n\nTODO — write the Given/When/Then cases. Approving a T-SPEC requires all four quadrants to carry a real scenario.\n\n${exports.INFERRED}`,
+                'Corner Cases': todo('write the corner-case scenarios.'),
+                'Negative Cases': todo('write the negative-case scenarios.'),
+                'Boundary Cases': todo('write the boundary-case scenarios.'),
+            },
+        },
+    ];
+    return {
+        ok: true,
+        specs,
+        anchorPlan: [...cluster.files, ...testFiles].map((file) => ({ file, aspec: aspecId })),
+        clusterKey: key,
+    };
+}

package/dist/holmes/reverse/dynamic-wiring.js

@@ -0,0 +1,47 @@
+"use strict";
+// @implements A-SPEC-126
+/**
+ * Detect the wiring forms a syntactic scan cannot follow — DI decorators, dynamic `require`/`import`,
+ * string-key dispatch, `eval`-like execution, config-driven wiring.
+ *
+ * REPORTED, NEVER RESOLVED. An indicator says "there is a relationship here that static evidence
+ * cannot recover"; it never becomes an edge or a cluster membership. The correct outcome for such a
+ * file is that it stays visibly unresolved, not that it gets attached to a guessed slice.
+ *
+ * The pattern sets are LANGUAGE-SCOPED and only exist for languages that were calibrated. Applying
+ * one language's regexes to another put nearly half of one subject's files under two indicators
+ * during calibration — and an indicator firing on most of a codebase teaches the reader to ignore it,
+ * which is worse than not shipping it. Languages with no calibrated set report nothing, and
+ * `dynamicWiringSupported` makes that gap visible instead of letting a silent zero read as "clean".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dynamicWiringSupported = dynamicWiringSupported;
+exports.detectDynamicWiring = detectDynamicWiring;
+const PY = [
+    ['dynamic-import', /\b(?:importlib\.import_module|__import__)\s*\(/m],
+    ['di-decorator', /(?:^|\n)\s*@(?:inject|provide|singleton|component|service|app\.(?:route|get|post|put|delete)|router\.(?:get|post|put|delete))\b/mi],
+    ['string-key-dispatch', /\b(?:getattr|setattr)\s*\(|globals\(\)\[|locals\(\)\[/m],
+    ['eval-like', /(?:^|[^.\w])(?:eval|exec)\s*\(/m],
+    ['config-driven', /\b(?:yaml\.(?:safe_)?load|json\.load|toml\.load|configparser|load_dotenv|ConfigParser)\s*\(?/m],
+];
+const JS = [
+    // A `require`/`import` whose argument is not a literal — the literal case is exactly what the
+    // scanner CAN follow, so flagging it would be noise.
+    ['dynamic-import', /(?:^|[^.\w])(?:require|import)\s*\(\s*(?!['"`)])/m],
+    ['di-decorator', /(?:^|\n)\s*@(?:Injectable|Component|Autowired|Inject|Service|Controller|Module|NgModule)\b/m],
+    ['string-key-dispatch', /\[\s*[a-zA-Z_$][\w$]*\s*\]\s*\(/m],
+    ['eval-like', /(?:^|[^.\w])eval\s*\(|new\s+Function\s*\(/m],
+    ['config-driven', /\b(?:readFileSync|readFile|loadConfig|dotenv\.config|cosmiconfig)\s*\(/m],
+];
+const PY_RE = /\.py$/;
+const JS_RE = /\.(ts|mts|cts|tsx|jsx|js|mjs|cjs)$/;
+/** True when this file's language has a calibrated indicator set. */
+function dynamicWiringSupported(file) {
+    return PY_RE.test(file) || JS_RE.test(file);
+}
+function detectDynamicWiring(code, file) {
+    const set = PY_RE.test(file) ? PY : JS_RE.test(file) ? JS : null;
+    if (!set)
+        return []; // uncalibrated language — see dynamicWiringSupported
+    return set.filter(([, re]) => re.test(code)).map(([k]) => k).sort();
+}

package/dist/holmes/reverse/scan.js

@@ -0,0 +1,194 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.candidates = candidates;
+exports.reverseScan = reverseScan;
+// @implements A-SPEC-126
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const test_files_1 = require("../cpg/test-files");
+const cluster_1 = require("./cluster");
+const dynamic_wiring_1 = require("./dynamic-wiring");
+const test_map_1 = require("./test-map");
+const surface_1 = require("./surface");
+// @implements A-SPEC-128
+const ignore_1 = require("../project/ignore");
+const draft_1 = require("./draft");
+const SCANNABLE_RE = new RegExp(`(${cpg_scanner_1.SCANNABLE_EXTENSIONS.map((e) => e.replace('.', '\\.')).join('|')})$`);
+/** Walk a non-git tree for test files, mirroring the scanner's own vendor-directory skips. */
+function walkTestFiles(root) {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (cpg_scanner_1.SKIP.has(e.name))
+                continue;
+            const abs = path.join(dir, e.name);
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if (e.isDirectory())
+                walk(abs);
+            else if (SCANNABLE_RE.test(e.name) && (0, test_files_1.isTestFile)(rel))
+                out.push(rel);
+        }
+    };
+    walk(root);
+    return out;
+}
+/**
+ * Only git-tracked files are candidates.
+ *
+ * Ignored code is by definition not part of the shipped system, and treating it as governable
+ * produces specs for scratch work, build output and local experiments. A non-git tree accepts
+ * everything and reports `isGit: false`, which is honest rather than silently wrong.
+ */
+function candidates(root, scan) {
+    let tracked = null;
+    try {
+        tracked = new Set(
+        // stderr is silenced: on a non-git tree git's "not a repository" complaint is an expected
+        // branch of this function, not a fault worth printing over the caller's output.
+        (0, node_child_process_1.execFileSync)('git', ['-C', root, 'ls-files', '-z'], { encoding: 'utf8', maxBuffer: 1 << 28, stdio: ['ignore', 'pipe', 'ignore'] })
+            .split('\0')
+            .filter(Boolean));
+    }
+    catch {
+        /* not a git repository — no filter applies */
+    }
+    const all = scan(root);
+    // @implements A-SPEC-128
+    // With git, tracked-ness already encodes the ignore rules. Without it, the SAME `.gitignore` is
+    // interpreted here — one ignore file, whoever is available to read it. A scan that ingested
+    // everything would put build output and vendored trees into the graph and into clustering.
+    const ignore = tracked ? null : (0, ignore_1.loadIgnore)(root);
+    const files = tracked
+        ? all.filter((f) => tracked.has(f.sourcePath))
+        : all.filter((f) => !ignore.isIgnored(f.sourcePath));
+    // Tests come from the tracked list rather than from the scan, which excludes them by design. An
+    // untracked test is dropped for the same reason untracked code is: it is not part of the system.
+    const testFiles = (tracked ? [...tracked].filter((p) => SCANNABLE_RE.test(p)) : walkTestFiles(root))
+        .filter((p) => (0, test_files_1.isTestFile)(p) && !ignore?.isIgnored(p))
+        .sort(cmp);
+    return {
+        files, testFiles, scanned: all.length, droppedUntracked: all.length - files.length,
+        isGit: tracked !== null,
+        ignoreUnsupportedPatterns: ignore?.unsupportedPatterns() ?? [],
+    };
+}
+const DEFAULT_MAX_FLAGGED = 50;
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function reverseScan(root, opts = {}) {
+    // An unreadable root must fail loudly: an empty inventory over a tree that was never read looks
+    // exactly like an empty repository, and the caller would act on "nothing to govern here".
+    const stat = fs.statSync(root);
+    if (!stat.isDirectory())
+        throw new Error(`reverse_scan: ${root} is not a directory`);
+    const scan = opts.scan ?? ((r) => new cpg_scanner_1.CpgScanner().scan(r, r));
+    const { files, testFiles, scanned, droppedUntracked, isGit, ignoreUnsupportedPatterns } = candidates(root, scan);
+    const clusters = (0, cluster_1.clusterFiles)(files);
+    const production = clusters.filter((c) => !c.isTest);
+    const testClusters = clusters.filter((c) => c.isTest);
+    // Attach existing tests to the slice each covers, by name evidence only. An unattachable test is
+    // reported, never attached on proximity — the anchor it would produce is an authorship claim.
+    const tests = (0, test_map_1.mapTestsToClusters)(testFiles, production);
+    const byKey = new Map(production.map((c) => [(0, draft_1.clusterKeyOf)(c), c]));
+    for (const m of tests.matched)
+        byKey.get(m.clusterKey)?.testFiles.push(m.file);
+    // Public-surface candidates, computed ONCE from the files this scan already holds. `reverse_draft`
+    // can draft every cluster in a single call, so deriving this per cluster would re-walk the same
+    // tree once per slice. Carried on the report but stripped from the `reverse_scan` TOOL response —
+    // it is evidence for drafting, not something a reader should pay context for on every scan.
+    const byPath = new Map(files.map((f) => [f.sourcePath, f]));
+    const surfaceByCluster = {};
+    for (const c of production) {
+        surfaceByCluster[(0, draft_1.clusterKeyOf)(c)] = (0, surface_1.surfaceOf)(c.files.map((p) => byPath.get(p)).filter((f) => f !== undefined));
+    }
+    const indicators = {};
+    const flagged = [];
+    const uncalibrated = new Set();
+    for (const f of files) {
+        if (!(0, dynamic_wiring_1.dynamicWiringSupported)(f.sourcePath)) {
+            uncalibrated.add(path.extname(f.sourcePath));
+            continue;
+        }
+        let code;
+        try {
+            code = fs.readFileSync(f.path, 'utf8');
+        }
+        catch {
+            continue; // a file that vanished between scan and read is not evidence of anything
+        }
+        const hits = (0, dynamic_wiring_1.detectDynamicWiring)(code, f.sourcePath);
+        for (const h of hits)
+            indicators[h] = (indicators[h] ?? 0) + 1;
+        if (hits.length)
+            flagged.push({ file: f.sourcePath, indicators: hits });
+    }
+    flagged.sort((a, b) => cmp(a.file, b.file));
+    const anchored = files.filter((f) => f.implementsSpecs.length > 0).length;
+    const countFiles = (cs) => cs.reduce((n, c) => n + c.files.length, 0);
+    return {
+        root,
+        isGit,
+        scanned,
+        droppedUntracked,
+        candidates: files.length,
+        anchored,
+        unanchored: files.length - anchored,
+        clusters: production,
+        testClusters,
+        surfaceByCluster,
+        coverage: {
+            structurallyResolved: countFiles(production),
+            inTestClusters: countFiles(testClusters),
+            cohesionUnmeasured: countFiles(clusters.filter((c) => c.cohesion === 'unmeasured')),
+            testsMatched: tests.matched.length,
+            testsUnmatched: tests.unmatched.length,
+            withDynamicIndicators: flagged.length,
+            indicators,
+            uncalibratedIndicatorLanguages: [...uncalibrated].sort(cmp),
+            ignoreUnsupportedPatterns,
+        },
+        needsHumanConfirmation: flagged.slice(0, opts.maxFlagged ?? DEFAULT_MAX_FLAGGED),
+        tests,
+    };
+}