@event4u/agent-config 9.7.0 → 9.8.0

package/src/scripts/check_secret_leak.ts

@@ -0,0 +1,290 @@
+#!/usr/bin/env tsx
+/**
+ * CI secret-leak gate — the non-bypassable second layer behind the
+ * `secret-vcs-guard` behavioral rule.
+ *
+ * Runs the shared `secret_detector` library (regex rule pack + Shannon entropy +
+ * keyword context) over the repository's tracked working tree (or a supplied
+ * path set), and FAILS (exit 1) on any `high`-confidence finding that is not
+ * suppressed. This is the deterministic enforcing net: a PR cannot merge red,
+ * unlike a client-side commit hook (which fires only on agent-initiated bash and
+ * is `--no-verify`/GUI/fresh-clone bypassable) — see
+ * `src/rules/secret-vcs-guard.md` and `skill:secrets-management` for the
+ * layering rationale.
+ *
+ * Suppression (audited, narrow — never a global mute):
+ *   - inline `# secret-allow` / `// secret-allow` / `<!-- secret-allow -->` on a
+ *     line (handled inside `secret_detector`);
+ *   - a repo-root `.secret-allow` file: one entry per line, `path` or
+ *     `path:line`, `#` comments allowed. Each entry SHOULD carry a one-line
+ *     justification comment so it is reviewable in the diff.
+ *
+ * Default excludes (fixtures/tests/examples legitimately hold fake secrets;
+ * generated + vendored trees are not source): node_modules, dist, dist-*,
+ * .git, .claude, **\/fixtures\/**, *.test.*, *.spec.*, *.example, *.sample,
+ * .env.example, lockfiles, *.min.*.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_secret_leak [paths...] [--all] [--base <ref>] [--json]
+ *   default → files changed vs origin/main + untracked (shift-left); --all →
+ *   whole tracked tree; paths → exactly those (excludes skipped).
+ *
+ * Exit codes: 0 clean · 1 high-confidence leak found · 2 usage/env error.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { scanText, type SecretFinding } from './_lib/secret_detector.js';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+// repo root: src/scripts/check_secret_leak.ts → parents[2].
+export const REPO_ROOT = path.resolve(_HERE, '..', '..');
+
+const DEFAULT_EXCLUDE: readonly RegExp[] = [
+    /(^|\/)node_modules(\/|$)/,
+    /(^|\/)dist(\/|$)/,
+    /(^|\/)dist-[^/]+(\/|$)/,
+    /(^|\/)\.git(\/|$)/,
+    /(^|\/)\.claude(\/|$)/,
+    /(^|\/)fixtures(\/|$)/,
+    /(^|\/)tests(\/|$)/, // test + golden + parity data legitimately holds secret-shaped strings
+    /(^|\/)__[a-z_]+__(\/|$)/, // snapshot dirs (e.g. __parity_snapshots__)
+    /\.test\.[a-z]+$/,
+    /\.spec\.[a-z]+$/,
+    /\.example$/,
+    /\.sample$/,
+    /(^|\/)\.env\.example$/,
+    /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|composer\.lock)$/,
+    /\.min\.[a-z]+$/,
+];
+
+export interface LeakHit extends SecretFinding {
+    file: string;
+}
+
+interface AllowEntry {
+    file: string;
+    line: number | null; // null = whole-file allow
+}
+
+/** Parse `.secret-allow` (repo-root) into path[:line] entries. */
+export function readAllowFile(root: string): AllowEntry[] {
+    const p = path.join(root, '.secret-allow');
+    if (!fs.existsSync(p)) {
+        return [];
+    }
+    const out: AllowEntry[] = [];
+    for (const raw of fs.readFileSync(p, 'utf-8').split(/\r?\n/)) {
+        const line = raw.replace(/#.*$/, '').trim();
+        if (line === '') {
+            continue;
+        }
+        const m = /^(.*?)(?::(\d+))?$/.exec(line);
+        if (m) {
+            out.push({ file: m[1] as string, line: m[2] ? parseInt(m[2], 10) : null });
+        }
+    }
+    return out;
+}
+
+function isAllowed(rel: string, lineno: number, allow: readonly AllowEntry[]): boolean {
+    return allow.some((a) => a.file === rel && (a.line === null || a.line === lineno));
+}
+
+function isExcluded(rel: string): boolean {
+    return DEFAULT_EXCLUDE.some((rx) => rx.test(rel));
+}
+
+/** Fast binary sniff — a NUL byte in the first 8 KiB means "not text". */
+function isBinary(abs: string): boolean {
+    try {
+        const fd = fs.openSync(abs, 'r');
+        const buf = Buffer.alloc(8192);
+        const n = fs.readSync(fd, buf, 0, 8192, 0);
+        fs.closeSync(fd);
+        return buf.subarray(0, n).includes(0);
+    } catch {
+        return true; // unreadable → skip
+    }
+}
+
+function gitLines(root: string, args: readonly string[]): string[] {
+    const res = spawnSync('git', args as string[], { cwd: root, encoding: 'utf-8' });
+    if (res.status !== 0) {
+        return [];
+    }
+    return res.stdout.split('\n').filter((l) => l.trim() !== '');
+}
+
+export type Mode = 'diff' | 'all' | 'explicit';
+
+/**
+ * Resolve the file set.
+ *   explicit → the named paths (intent — excludes skipped by the caller).
+ *   all      → every tracked file (`git ls-files`).
+ *   diff     → files this branch adds or changes vs `base` PLUS untracked files —
+ *              the shift-left surface: scan what the change introduces, never the
+ *              pre-existing corpus (which floods a mature repo with matches).
+ */
+export function resolveFiles(
+    root: string,
+    mode: Mode,
+    opts: { explicit?: readonly string[] | undefined; base?: string | undefined } = {},
+): string[] {
+    if (mode === 'explicit') {
+        return (opts.explicit ?? []).map((p) =>
+            path.isAbsolute(p) ? path.relative(root, p) : p,
+        );
+    }
+    if (mode === 'all') {
+        return gitLines(root, ['ls-files']);
+    }
+    const base = opts.base ?? 'origin/main';
+    // An unresolvable base is a scan of NOTHING, not a clean scan.
+    //
+    // `git diff <missing-ref>` yields no lines, so the changed-set silently
+    // became empty and the gate reported "no high-confidence secret found in the
+    // tracked tree" while examining zero files. That is the shape a shallow CI
+    // checkout produces by default — verified: with an unresolvable base this
+    // function returned 0 paths. A secret gate that passes green on an empty
+    // scan is worse than no gate, because it is believed.
+    const probe = spawnSync('git', ['-C', root, 'rev-parse', '--verify', '--quiet', `${base}^{commit}`], {
+        encoding: 'utf-8',
+    });
+    if ((probe.status ?? 1) !== 0) {
+        throw new Error(
+            `check_secret_leak: baseline ref '${base}' does not resolve, so the changed-set would be empty ` +
+                `and the scan would examine no files. Fetch the branch (CI: actions/checkout with fetch-depth: 0), ` +
+                `pass --base <ref>, or use --all to scan the whole tracked tree.`,
+        );
+    }
+    const changed = gitLines(root, ['diff', '--name-only', '--diff-filter=ACMR', base]);
+    const untracked = gitLines(root, ['ls-files', '--others', '--exclude-standard']);
+    return Array.from(new Set([...changed, ...untracked]));
+}
+
+export function scanRepo(
+    root: string,
+    mode: Mode = 'diff',
+    opts: { explicit?: readonly string[] | undefined; base?: string | undefined } = {},
+): LeakHit[] {
+    const allow = readAllowFile(root);
+    // Explicit paths express intent — the fixture/test/example excludes (which
+    // exist so an auto-discovered scan ignores intentional fake secrets) are
+    // skipped only when the caller names paths directly.
+    const applyExcludes = mode !== 'explicit';
+    const hits: LeakHit[] = [];
+    for (const rel of resolveFiles(root, mode, opts)) {
+        if (applyExcludes && isExcluded(rel)) {
+            continue;
+        }
+        const abs = path.join(root, rel);
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile() || isBinary(abs)) {
+            continue;
+        }
+        let text: string;
+        try {
+            text = fs.readFileSync(abs, 'utf-8');
+        } catch {
+            continue;
+        }
+        for (const f of scanText(text, { path: rel })) {
+            if (f.confidence !== 'high') {
+                continue;
+            }
+            if (isAllowed(rel, f.line, allow)) {
+                continue;
+            }
+            hits.push({ ...f, file: rel });
+        }
+    }
+    return hits;
+}
+
+interface Args {
+    json: boolean;
+    all: boolean;
+    base: string | undefined;
+    paths: string[];
+}
+
+function parseArgs(argv: readonly string[]): Args {
+    const paths: string[] = [];
+    let json = false;
+    let all = false;
+    let base: string | undefined;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--json') {
+            json = true;
+        } else if (a === '--all') {
+            all = true;
+        } else if (a === '--base') {
+            base = argv[++i];
+        } else if (a === '-h' || a === '--help') {
+            _stdout(
+                'usage: check_secret_leak [paths...] [--all] [--base <ref>] [--json]\n' +
+                    '  default → scans files changed vs origin/main + untracked (shift-left).\n' +
+                    '  --all   → scans the whole tracked tree.\n' +
+                    '  paths   → scans exactly those paths (excludes skipped).\n' +
+                    '  Exit 1 on a high-confidence leak.\n',
+            );
+            process.exit(0);
+        } else if (a.startsWith('--')) {
+            _stderr(`check_secret_leak: unknown flag ${a}\n`);
+            process.exit(2);
+        } else {
+            paths.push(a);
+        }
+    }
+    return { json, all, base, paths };
+}
+
+function _stdout(s: string): void {
+    process.stdout.write(s);
+}
+function _stderr(s: string): void {
+    process.stderr.write(s);
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = parseArgs(argv ?? process.argv.slice(2));
+    const mode: Mode = args.paths.length > 0 ? 'explicit' : args.all ? 'all' : 'diff';
+    const hits = scanRepo(REPO_ROOT, mode, { explicit: args.paths, base: args.base });
+
+    if (args.json) {
+        _stdout(JSON.stringify({ check: 'secret-leak', count: hits.length, hits }, null, 2) + '\n');
+    } else if (hits.length === 0) {
+        _stdout('✅  check_secret_leak: no high-confidence secret found in the tracked tree.\n');
+    } else {
+        _stderr(`❌  check_secret_leak: ${hits.length} high-confidence secret finding(s):\n`);
+        for (const h of hits) {
+            _stderr(`   ${h.file}:${h.line}  ${h.kind}  (${h.masked})\n`);
+        }
+        _stderr(
+            '\nRotate any real credential NOW (a commit does not un-leak it), move it to a\n' +
+                'secret store (see skill:secrets-management), or add an audited entry to\n' +
+                '.secret-allow / an inline `# secret-allow` marker if this is a false positive.\n',
+        );
+    }
+    return hits.length === 0 ? 0 : 1;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention).
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main());
+        }
+    } catch {
+        const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+        if (import.meta.url === argvUrl) {
+            process.exit(main());
+        }
+    }
+}

package/src/scripts/code_graph/cli.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env tsx
+/**
+ * Native code-graph engine CLI (Class-A, ADR-124).
+ *
+ *   build    [--root P] [--out P] [--force]   (re)build the deterministic graph
+ *   validate [--graph P]                       schema-gate a graph.json
+ *
+ * Query subcommands (query/path/explain/affected/detect) are added by the
+ * Phase-3 query tier. Deterministic, LLM-free, no network. Exit codes:
+ * 0 ok · 1 not-found / validation-failed · 2 usage · 3 internal.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
+import { buildFromRepo } from './build.js';
+import { detectSources, pickSource } from './detect.js';
+import { affected, explain, loadGraph, type LoadedGraph, path as graphPath, query, type QueryResult } from './query.js';
+import { validateGraph } from './validate.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
+export const DEFAULT_CACHE = path.join(REPO_ROOT, 'agents', 'runtime', 'state', 'code-graph-v1.json');
+
+function flag(argv: string[], name: string): string | null {
+    const i = argv.indexOf(name);
+    return i >= 0 && i + 1 < argv.length ? (argv[i + 1] as string) : null;
+}
+
+async function cmdBuild(argv: string[]): Promise<number> {
+    const root = flag(argv, '--root') ?? REPO_ROOT;
+    const out = argv.includes('--out') ? flag(argv, '--out') : DEFAULT_CACHE;
+    if (!fs.existsSync(root)) {
+        process.stderr.write(`code-graph: root not found: ${root}\n`);
+        return 1;
+    }
+    const update = argv.includes('--update');
+    const { graph, fileCount, reExtracted, reused } = await buildFromRepo(root, out, { update });
+    const c = graph.edge_confidence_counts;
+    process.stdout.write(
+        `✅  code-graph ${update ? 'updated' : 'built'} — ${fileCount} files · ${graph.nodes.length} nodes · ${graph.edges.length} edges\n` +
+            `    languages: ${graph.languages.join(', ') || '(none)'} · grammar ABI ${graph.grammar_abi}\n` +
+            `    edges: EXTRACTED ${c.EXTRACTED} · INFERRED ${c.INFERRED} · AMBIGUOUS ${c.AMBIGUOUS}\n` +
+            (update ? `    incremental: ${reExtracted} re-extracted · ${reused} reused\n` : '') +
+            (out ? `    cache: ${path.relative(REPO_ROOT, out)}\n` : ''),
+    );
+    return 0;
+}
+
+function cmdValidate(argv: string[]): number {
+    const p = flag(argv, '--graph') ?? DEFAULT_CACHE;
+    if (!fs.existsSync(p)) {
+        process.stderr.write(`code-graph: graph not found: ${p}\n`);
+        return 1;
+    }
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    } catch (e) {
+        process.stderr.write(`code-graph: graph is not valid JSON: ${(e as Error).message}\n`);
+        return 1;
+    }
+    const r = validateGraph(parsed);
+    if (r.ok) {
+        process.stdout.write(`✅  graph schema valid: ${path.relative(REPO_ROOT, p)}\n`);
+        return 0;
+    }
+    process.stderr.write(`❌  graph schema invalid (${r.errors.length}):\n`);
+    for (const e of r.errors) process.stderr.write(`  ${e}\n`);
+    return 1;
+}
+
+function resolveGraph(argv: string[]): { g: LoadedGraph; note: string } | { err: string } {
+    const explicit = flag(argv, '--graph');
+    const root = flag(argv, '--root') ?? REPO_ROOT;
+    if (explicit) {
+        if (!fs.existsSync(explicit)) return { err: `graph not found: ${explicit}` };
+        return { g: loadGraph(explicit, path.relative(REPO_ROOT, explicit)), note: '' };
+    }
+    const picked = pickSource(detectSources(root, DEFAULT_CACHE));
+    if (!picked) return { err: 'no code-graph source found — run `code_graph build` or ship a graph.json' };
+    if (picked.kind === 'scip') return { err: `${picked.note ?? 'SCIP detected'} — pass --graph <json> or install peer tooling` };
+    const staleNote = picked.stale ? ` ⚠ index is ${picked.commits_behind ?? 'N'} commit(s) behind — rebuild before trusting` : '';
+    return { g: loadGraph(picked.path, `${picked.kind}:${path.relative(REPO_ROOT, picked.path)}`), note: staleNote };
+}
+
+function render(r: QueryResult, staleNote: string): number {
+    process.stdout.write(`source: ${r.source}${staleNote}\n`);
+    if (r.seeds.length) process.stdout.write(`seeds: ${r.seeds.join(', ')}\n`);
+    for (const l of r.lines) process.stdout.write(`  ${l}\n`);
+    if (r.truncated) process.stdout.write('  … (budget reached — narrow the seed or raise --budget)\n');
+    if (!r.lines.length) process.stdout.write('  (no matching relations)\n');
+    return 0;
+}
+
+function budgetOf(argv: string[]): number {
+    const b = Number(flag(argv, '--budget'));
+    return Number.isFinite(b) && b > 0 ? b : 1500;
+}
+
+function changedNodeSeeds(g: LoadedGraph, root: string, ref: string): string[] {
+    let files: string[];
+    try {
+        files = execFileSync('git', ['-C', root, 'diff', '--name-only', `${ref}..HEAD`], {
+            env: hardenedSpawnEnv(),
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .split('\n')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    } catch {
+        return [];
+    }
+    const set = new Set(files);
+    return g.graph.nodes.filter((n) => set.has(n.source_file) && n.kind !== 'file').map((n) => n.id);
+}
+
+function cmdQuery(kind: 'query' | 'explain' | 'affected' | 'path', argv: string[]): number {
+    const r = resolveGraph(argv);
+    if ('err' in r) {
+        process.stderr.write(`code-graph: ${r.err}\n`);
+        return 1;
+    }
+    const positional = argv.filter((a) => !a.startsWith('--') && !isFlagValue(argv, a));
+    const budget = budgetOf(argv);
+    if (kind === 'affected' && flag(argv, '--since')) {
+        const root = flag(argv, '--root') ?? REPO_ROOT;
+        const seeds = changedNodeSeeds(r.g, root, flag(argv, '--since') as string);
+        const merged: QueryResult = { source: r.g.source, seeds: [], lines: [], truncated: false };
+        for (const s of seeds) {
+            const one = affected(r.g, s, 2, budget);
+            merged.seeds.push(...one.seeds);
+            merged.lines.push(...one.lines);
+        }
+        return render(merged, r.note);
+    }
+    const a = positional[0];
+    if (!a) {
+        process.stderr.write(`usage: code_graph/cli.ts ${kind} <symbol> [--graph P] [--budget N]\n`);
+        return 2;
+    }
+    if (kind === 'path') {
+        const b = positional[1];
+        if (!b) {
+            process.stderr.write('usage: code_graph/cli.ts path <a> <b>\n');
+            return 2;
+        }
+        return render(graphPath(r.g, a, b, budget), r.note);
+    }
+    const fn = kind === 'query' ? query : kind === 'explain' ? explain : affected;
+    return render(fn(r.g, a, budget), r.note);
+}
+
+function isFlagValue(argv: string[], token: string): boolean {
+    const i = argv.indexOf(token);
+    return i > 0 && (argv[i - 1] as string).startsWith('--');
+}
+
+function cmdDetect(argv: string[]): number {
+    const root = flag(argv, '--root') ?? REPO_ROOT;
+    const verdicts = detectSources(root, DEFAULT_CACHE);
+    if (!verdicts.length) {
+        process.stdout.write('no code-graph source detected\n');
+        return 1;
+    }
+    for (const v of verdicts) {
+        const fresh = v.stale === undefined ? '' : v.stale ? ` · STALE${v.commits_behind !== undefined ? ` (${v.commits_behind} behind)` : ''}` : ' · fresh';
+        process.stdout.write(`${v.kind.padEnd(9)} ${path.relative(REPO_ROOT, v.path)}${fresh}${v.note ? ` · ${v.note}` : ''}\n`);
+    }
+    const picked = pickSource(verdicts);
+    if (picked) process.stdout.write(`→ query would use: ${picked.kind}\n`);
+    return 0;
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+    const sub = argv[0];
+    try {
+        if (sub === 'build') return await cmdBuild(argv.slice(1));
+        if (sub === 'validate') return cmdValidate(argv.slice(1));
+        if (sub === 'detect') return cmdDetect(argv.slice(1));
+        if (sub === 'query' || sub === 'explain' || sub === 'affected' || sub === 'path')
+            return cmdQuery(sub, argv.slice(1));
+        process.stderr.write(
+            'usage: code_graph/cli.ts <build|validate|detect|query|explain|affected|path> [options]\n',
+        );
+        return 2;
+    } catch (e) {
+        process.stderr.write(`code-graph: internal error: ${(e as Error).message}\n`);
+        return 3;
+    }
+}
+
+const _invokedDirectly = (() => {
+    if (process.argv[1] === undefined) return false;
+    try {
+        return fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(_HERE);
+    } catch {
+        return import.meta.url === `file://${process.argv[1]}`;
+    }
+})();
+if (_invokedDirectly) {
+    main().then((rc) => process.exit(rc));
+}

package/src/scripts/code_graph/detect.ts

@@ -0,0 +1,134 @@
+/**
+ * Source detection + freshness. Answers "what code-graph source should a
+ * query use, and is it fresh?" across three sources:
+ *
+ *   consumer  — a `graph.json`-shaped artifact the consumer repo ships
+ *   scip      — an `index.scip` / `*.scip` (presence only; peer tooling
+ *               required — an owned SCIP reader is YAGNI-gated until a
+ *               consumer actually ships one)
+ *   native    — the suite's own gitignored cache
+ *
+ * Precedence (ADR-124 § 2): a fresh consumer index wins (interop courtesy);
+ * the native engine covers stale-or-absent. Freshness: `head_at_build` when
+ * the artifact embeds a SHA (→ commits_behind), else artifact mtime vs the
+ * repo's last commit time. No guessing.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
+import { validateGraph } from './validate.js';
+
+export type SourceKind = 'consumer' | 'scip' | 'native';
+
+export interface SourceVerdict {
+    kind: SourceKind;
+    path: string;
+    present: boolean;
+    stale?: boolean;
+    commits_behind?: number;
+    note?: string;
+}
+
+const CONSUMER_CANDIDATES = ['graph.json', 'code-graph.json', '.code-graph/graph.json'];
+
+function gitLastCommitEpoch(root: string): number | null {
+    try {
+        const out = execFileSync('git', ['-C', root, 'log', '-1', '--format=%ct'], {
+            env: hardenedSpawnEnv(),
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const n = Number(out);
+        return Number.isFinite(n) ? n : null;
+    } catch {
+        return null;
+    }
+}
+
+function commitsBehind(root: string, sha: string): number | null {
+    try {
+        const out = execFileSync('git', ['-C', root, 'rev-list', '--count', `${sha}..HEAD`], {
+            env: hardenedSpawnEnv(),
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const n = Number(out);
+        return Number.isFinite(n) ? n : null;
+    } catch {
+        return null;
+    }
+}
+
+function freshness(root: string, file: string, embeddedSha: string | null): { stale?: boolean; commits_behind?: number } {
+    if (embeddedSha) {
+        const behind = commitsBehind(root, embeddedSha);
+        if (behind !== null) return { stale: behind > 0, commits_behind: behind };
+    }
+    const last = gitLastCommitEpoch(root);
+    if (last === null) return {};
+    try {
+        const mtime = Math.floor(fs.statSync(file).mtimeMs / 1000);
+        return { stale: mtime < last };
+    } catch {
+        return {};
+    }
+}
+
+/** Shape-validate a candidate consumer graph.json (native or foreign shape). */
+function looksLikeGraph(p: string): { ok: boolean; sha: string | null } {
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, unknown>;
+        // native shape passes validateGraph; a foreign graph.json just needs
+        // nodes[] + edges|links[] with source/target/relation.
+        if (validateGraph(raw).ok) return { ok: true, sha: (raw['head_at_build'] as string) ?? null };
+        const nodes = raw['nodes'];
+        const edges = (raw['edges'] ?? raw['links']) as unknown;
+        const okShape =
+            Array.isArray(nodes) &&
+            Array.isArray(edges) &&
+            (edges.length === 0 ||
+                (typeof edges[0] === 'object' && edges[0] !== null && 'source' in (edges[0] as object) && 'target' in (edges[0] as object)));
+        return { ok: okShape, sha: (raw['head_at_build'] as string) ?? null };
+    } catch {
+        return { ok: false, sha: null };
+    }
+}
+
+export function detectSources(root: string, nativeCache: string): SourceVerdict[] {
+    const abs = path.resolve(root);
+    const out: SourceVerdict[] = [];
+
+    for (const rel of CONSUMER_CANDIDATES) {
+        const p = path.join(abs, rel);
+        if (fs.existsSync(p)) {
+            const { ok, sha } = looksLikeGraph(p);
+            if (ok) out.push({ kind: 'consumer', path: p, present: true, ...freshness(abs, p, sha) });
+        }
+    }
+
+    // SCIP — presence only
+    const scipCandidates = [path.join(abs, 'index.scip')];
+    try {
+        for (const e of fs.readdirSync(abs)) if (e.endsWith('.scip')) scipCandidates.push(path.join(abs, e));
+    } catch {
+        /* ignore */
+    }
+    const scip = scipCandidates.find((p) => fs.existsSync(p));
+    if (scip) out.push({ kind: 'scip', path: scip, present: true, note: 'SCIP detected — peer tooling required (no owned reader)' });
+
+    // native cache
+    if (fs.existsSync(nativeCache)) out.push({ kind: 'native', path: nativeCache, present: true, ...freshness(abs, nativeCache, null) });
+
+    return out;
+}
+
+/** Pick the source a query should use: fresh consumer > native > stale consumer. */
+export function pickSource(verdicts: SourceVerdict[]): SourceVerdict | null {
+    const consumer = verdicts.find((v) => v.kind === 'consumer' && v.stale !== true);
+    if (consumer) return consumer;
+    const native = verdicts.find((v) => v.kind === 'native');
+    if (native) return native;
+    return verdicts.find((v) => v.kind === 'consumer') ?? null;
+}