@lzehrung/codegraph 2.1.0

package/dist/cli/index.js

@@ -0,0 +1,112 @@
+import { performance } from "node:perf_hooks";
+import { buildProjectIndexFromFiles, buildProjectIndexIncremental } from "../indexer/build-index.js";
+import {} from "../indexer/types.js";
+import { summarizeAnalysis } from "../analysisSummary.js";
+import {} from "../graphs/types.js";
+import { parseCacheModeOption, parseNonNegativeIntegerOption } from "./options.js";
+import { writeCliOutput } from "./pretty.js";
+function formatIndexOutput(output) {
+    const lines = [`Indexed ${output.files} file(s) with ${output.edges} edge(s).`];
+    if (output.analysis.mode !== "semantic") {
+        lines.push(`Analysis: ${output.analysis.label}.`);
+    }
+    if (!output.modules) {
+        return lines.join("\n");
+    }
+    lines.push("Modules:");
+    for (const mod of output.modules) {
+        lines.push(`- ${mod.file}: ${mod.locals.length} locals, ${mod.exports.length} exports, ${mod.imports.length} imports`);
+    }
+    return lines.join("\n");
+}
+export async function handleIndexCommand(context) {
+    const verbose = context.hasFlag("--verbose");
+    const commandReport = context.reportEnabled
+        ? { command: "index", timings: {} }
+        : undefined;
+    const commandStart = performance.now();
+    const resolveStart = performance.now();
+    const files = await context.resolveFiles();
+    if (commandReport) {
+        commandReport.timings.resolveFilesMs = Math.round(performance.now() - resolveStart);
+    }
+    const threads = parseNonNegativeIntegerOption(context.getOpt("--threads"), "--threads", 0);
+    const cache = parseCacheModeOption(context.getOpt("--cache"));
+    const cacheStrict = context.hasFlag("--cache-strict");
+    const full = context.hasFlag("--json") || context.hasFlag("--full");
+    const cacheVerify = context.hasFlag("--cache-verify");
+    const shouldWriteManifest = !context.includeRootsAbs.length && !context.gitBase && !context.changedSince;
+    // Always populated (not gated behind --report/--verbose) so a plain `index`
+    // run can detect and surface reduced-accuracy analysis (native tree-sitter
+    // unavailable or per-file fallback) via both the stderr warning and the
+    // pretty/--json `analysis` field below, per finding #43.
+    const indexReport = { timings: {} };
+    if (commandReport) {
+        commandReport.index = indexReport;
+    }
+    // Defaults to the on-disk incremental cache, matching search/orient/inspect/review;
+    // pass --cache off to opt out for a single invocation.
+    const baseIndexOptions = {
+        onProgress: context.progressHandler,
+        threads,
+        discovery: context.discoveryOptions,
+        ...(context.nativeMode !== "auto" ? { native: context.nativeMode } : {}),
+        ...(context.languageExtensions ? { languageExtensions: context.languageExtensions } : {}),
+        ...context.workerOpts,
+        cache: cache ?? "disk",
+        cacheStrict,
+        cacheVerify,
+        ...(context.graphOptions ? { graph: context.graphOptions } : {}),
+        report: indexReport,
+    };
+    // Whole-project runs reuse the on-disk manifest and Git-backed incremental discovery
+    // instead of a full recursive scan; scoped include roots or an explicit git range keep
+    // using the already-resolved file list, since manifest-based reconciliation is scoped
+    // to the whole project root and cannot safely stand in for a root subset.
+    const index = shouldWriteManifest
+        ? await buildProjectIndexIncremental(context.projectRootFs, baseIndexOptions)
+        : await buildProjectIndexFromFiles(context.projectRootFs, files, baseIndexOptions);
+    context.maybeWriteNativeBackendStatus(indexReport, context.showProgress);
+    const analysis = summarizeAnalysis({ index, nativeMode: context.nativeMode, report: indexReport });
+    if (full) {
+        const modules = [...index.byFile.values()].map((m) => ({
+            file: m.file,
+            locals: m.locals.map((l) => ({
+                name: l.localName,
+                kind: l.kind,
+                start: l.range.start,
+            })),
+            exports: m.exports,
+            imports: m.imports,
+        }));
+        writeCliOutput(context, {
+            files: modules.length,
+            edges: index.graph.edges.length,
+            analysis,
+            modules,
+        }, formatIndexOutput);
+    }
+    else {
+        writeCliOutput(context, {
+            files: [...index.byFile.keys()].length,
+            edges: index.graph.edges.length,
+            analysis,
+        }, formatIndexOutput);
+    }
+    if (verbose) {
+        const cache = indexReport.cache;
+        const fileStats = indexReport.files;
+        if (cache) {
+            context.writeStderrLine(`Cache (${cache.mode}): ${cache.hits} hits, ${cache.misses} misses`);
+        }
+        if (fileStats) {
+            context.writeStderrLine(`Files: ${fileStats.parsed ?? 0} parsed, ${fileStats.cached ?? 0} cached, ${fileStats.total} total`);
+        }
+    }
+    if (commandReport) {
+        commandReport.timings.commandMs = Math.round(performance.now() - commandStart);
+        commandReport.timings.totalMs = commandReport.timings.commandMs;
+        await context.writeCommandReport(commandReport, context.reportFile);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,0BAA0B,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACrG,OAAO,EAAuC,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAwB,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAA0B,MAAM,oBAAoB,CAAC;AAI5D,OAAO,EAAE,oBAAoB,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA0B7C,SAAS,iBAAiB,CAAC,MAAyB;IAClD,MAAM,KAAK,GAAG,CAAC,WAAW,MAAM,CAAC,KAAK,iBAAiB,MAAM,CAAC,KAAK,WAAW,CAAC,CAAC;IAChF,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CACR,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAO,CAAC,MAAM,aAAa,GAAG,CAAC,OAAO,CAAC,MAAM,UAAU,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AA0BD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAA4B;IACnE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7C,MAAM,aAAa,GAAmC,OAAO,CAAC,aAAa;QACzE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE;QACnC,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACvC,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC;IAC3C,IAAI,aAAa,EAAE,CAAC;QAClB,aAAa,CAAC,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC,CAAC;IACtF,CAAC;IACD,MAAM,OAAO,GAAG,6BAA6B,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IAC3F,MAAM,KAAK,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9D,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpE,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtD,MAAM,mBAAmB,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC;IACzG,4EAA4E;IAC5E,2EAA2E;IAC3E,wEAAwE;IACxE,yDAAyD;IACzD,MAAM,WAAW,GAAgB,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACjD,IAAI,aAAa,EAAE,CAAC;QAClB,aAAa,CAAC,KAAK,GAAG,WAAW,CAAC;IACpC,CAAC;IACD,oFAAoF;IACpF,uDAAuD;IACvD,MAAM,gBAAgB,GAAiB;QACrC,UAAU,EAAE,OAAO,CAAC,eAAe;QACnC,OAAO;QACP,SAAS,EAAE,OAAO,CAAC,gBAAgB;QACnC,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzF,GAAG,OAAO,CAAC,UAAU;QACrB,KAAK,EAAE,KAAK,IAAI,MAAM;QACtB,WAAW;QACX,WAAW;QACX,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,MAAM,EAAE,WAAW;KACpB,CAAC;IACF,qFAAqF;IACrF,uFAAuF;IACvF,sFAAsF;IACtF,0EAA0E;IAC1E,MAAM,KAAK,GAAG,mBAAmB;QAC/B,CAAC,CAAC,MAAM,4BAA4B,CAAC,OAAO,CAAC,aAAa,EAAE,gBAAgB,CAAC;QAC7E,CAAC,CAAC,MAAM,0BAA0B,CAAC,OAAO,CAAC,aAAa,EAAE,KAAK,EAAE,gBAAgB,CAAC,CAAC;IACrF,OAAO,CAAC,6BAA6B,CAAC,WAAW,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAG,iBAAiB,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IACnG,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACrD,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3B,IAAI,EAAE,CAAC,CAAC,SAAS;gBACjB,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK;aACrB,CAAC,CAAC;YACH,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,OAAO,EAAE,CAAC,CAAC,OAAO;SACnB,CAAC,CAAC,CAAC;QACJ,cAAc,CACZ,OAAO,EACP;YACE,KAAK,EAAE,OAAO,CAAC,MAAM;YACrB,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM;YAC/B,QAAQ;YACR,OAAO;SACR,EACD,iBAAiB,CAClB,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,cAAc,CACZ,OAAO,EACP;YACE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM;YACtC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM;YAC/B,QAAQ;SACT,EACD,iBAAiB,CAClB,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC;QAChC,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC;QACpC,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,eAAe,CAAC,UAAU,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC,MAAM,SAAS,CAAC,CAAC;QAC/F,CAAC;QACD,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,CAAC,eAAe,CACrB,UAAU,SAAS,CAAC,MAAM,IAAI,CAAC,YAAY,SAAS,CAAC,MAAM,IAAI,CAAC,YAAY,SAAS,CAAC,KAAK,QAAQ,CACpG,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,aAAa,EAAE,CAAC;QAClB,aAAa,CAAC,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC,CAAC;QAC/E,aAAa,CAAC,OAAO,CAAC,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC;QAChE,MAAM,OAAO,CAAC,kBAAkB,CAAC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACtE,CAAC;AACH,CAAC"}

package/dist/cli/indexPolicy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How a CLI command obtains a project index.
+ *
+ * This is an architectural inventory, not runtime dispatch: it exists so a new command
+ * cannot ship without an explicit freshness decision, and so intentional non-automatic
+ * paths stay enumerated instead of inferred from a command family label.
+ */
+export type CliIndexBehavior = 
+/** Loads no index. */
+"none"
+/** Loads current repository state through `loadCurrentProjectIndex`. */
+ | "current-query"
+/** Uses `createAgentSession`, including its in-memory freshness contract. */
+ | "agent-session"
+/** Intentionally creates, refreshes, or materializes an index or artifact. */
+ | "explicit-build"
+/** Reconstructs or compares a requested revision or range. */
+ | "historical";
+/** Wiring family of a `current-query` command; each family owns a behavioral CLI test. */
+export type CliCurrentQueryFamily = "navigation" | "graph-query" | "structural-summary" | "duplicate-analysis" | "diff-aware" | "affected-tests";
+export type CliIndexPolicyEntry = {
+    command: string;
+    behaviors: readonly CliIndexBehavior[];
+    /** Required when `behaviors` includes `current-query`. */
+    family?: CliCurrentQueryFamily;
+    /** Why this command loads (or does not load) an index the way it does. */
+    reason: string;
+};
+export declare const CLI_INDEX_POLICY: readonly CliIndexPolicyEntry[];
+/** Resolve the index policy for a command name or alias. */
+export declare function indexPolicyForCommand(command: string): CliIndexPolicyEntry | undefined;
+/** Canonical command names that load current repository state, grouped by wiring family. */
+export declare function currentQueryCommandsByFamily(): Map<CliCurrentQueryFamily, string[]>;
+/** Canonical command names known to the catalog, for parity checks. */
+export declare function catalogCommandNames(): string[];
+//# sourceMappingURL=indexPolicy.d.ts.map

package/dist/cli/indexPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexPolicy.d.ts","sourceRoot":"","sources":["../../src/cli/indexPolicy.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB;AAC1B,sBAAsB;AACpB,MAAM;AACR,wEAAwE;GACtE,eAAe;AACjB,6EAA6E;GAC3E,eAAe;AACjB,8EAA8E;GAC5E,gBAAgB;AAClB,8DAA8D;GAC5D,YAAY,CAAC;AAEjB,0FAA0F;AAC1F,MAAM,MAAM,qBAAqB,GAC/B,YAAY,GAAG,aAAa,GAAG,oBAAoB,GAAG,oBAAoB,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAE/G,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACvC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SAAS,mBAAmB,EA6I1D,CAAC;AAIF,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAItF;AAED,4FAA4F;AAC5F,wBAAgB,4BAA4B,IAAI,GAAG,CAAC,qBAAqB,EAAE,MAAM,EAAE,CAAC,CASnF;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C"}

package/dist/cli/indexPolicy.js

@@ -0,0 +1,168 @@
+import { CLI_COMMAND_CATALOG, resolveCliCommand } from "./commandCatalog.js";
+export const CLI_INDEX_POLICY = [
+    { command: "orient", behaviors: ["agent-session"], reason: "Agent snapshot with manual freshness." },
+    { command: "explore", behaviors: ["agent-session"], reason: "Agent snapshot shared by search and packets." },
+    {
+        command: "file",
+        behaviors: ["none", "agent-session"],
+        reason: "Reads a file directly; only --graph-context opens an agent session.",
+    },
+    {
+        command: "review",
+        behaviors: ["current-query"],
+        family: "diff-aware",
+        reason: "Diff range selects what to review; the index is current repository state.",
+    },
+    { command: "packet", behaviors: ["agent-session"], reason: "Evidence packets read an agent snapshot." },
+    { command: "search", behaviors: ["agent-session"], reason: "Ranked search reads an agent snapshot." },
+    { command: "symbols", behaviors: ["agent-session"], reason: "Symbol identity lookup reads an agent snapshot." },
+    { command: "callers", behaviors: ["agent-session"], reason: "Call hierarchy needs the session symbol graph." },
+    { command: "callees", behaviors: ["agent-session"], reason: "Call hierarchy needs the session symbol graph." },
+    { command: "supertypes", behaviors: ["agent-session"], reason: "Type hierarchy needs the session symbol graph." },
+    { command: "subtypes", behaviors: ["agent-session"], reason: "Type hierarchy needs the session symbol graph." },
+    { command: "implementations", behaviors: ["agent-session"], reason: "Needs the session symbol graph." },
+    { command: "rename-preview", behaviors: ["agent-session"], reason: "Rename evidence needs the session snapshot." },
+    { command: "refactor-plan", behaviors: ["agent-session"], reason: "Refactor evidence needs the session snapshot." },
+    { command: "explain", behaviors: ["agent-session"], reason: "Explanations need the session snapshot." },
+    {
+        command: "impact",
+        behaviors: ["current-query"],
+        family: "diff-aware",
+        reason: "Diff range selects changed symbols; the index is current repository state.",
+    },
+    {
+        command: "inspect",
+        behaviors: ["current-query"],
+        family: "structural-summary",
+        reason: "Structural summary over resolved include-root scope.",
+    },
+    {
+        command: "affected",
+        behaviors: ["current-query"],
+        family: "affected-tests",
+        reason: "Reverse dependency walk over current repository state.",
+    },
+    {
+        command: "graph",
+        behaviors: ["explicit-build"],
+        reason: "Materializes graph output; changed-range mode keeps its own range semantics.",
+    },
+    {
+        command: "artifact",
+        behaviors: ["agent-session", "explicit-build"],
+        reason: "Loads an agent snapshot, then writes an artifact bundle.",
+    },
+    { command: "drift", behaviors: ["historical"], reason: "Builds revision-isolated snapshots for comparison." },
+    { command: "mcp", behaviors: ["agent-session"], reason: "Serves MCP tools over a long-lived agent session." },
+    { command: "viewer", behaviors: ["none"], reason: "Serves prebuilt viewer assets." },
+    { command: "index", behaviors: ["explicit-build"], reason: "Explicit index build, prewarm, or materialization." },
+    { command: "init", behaviors: ["explicit-build"], reason: "Lifecycle metadata build for project onboarding." },
+    { command: "status", behaviors: ["none"], reason: "Hashes config and lists files; never loads an index." },
+    { command: "sync", behaviors: ["explicit-build"], reason: "Lifecycle metadata refresh and repair." },
+    { command: "uninit", behaviors: ["none"], reason: "Removes lifecycle metadata." },
+    {
+        command: "goto",
+        behaviors: ["current-query"],
+        family: "navigation",
+        reason: "Definition lookup over current repository state.",
+    },
+    {
+        command: "refs",
+        behaviors: ["current-query"],
+        family: "navigation",
+        reason: "Reference lookup over current repository state.",
+    },
+    {
+        command: "deps",
+        behaviors: ["current-query"],
+        family: "graph-query",
+        reason: "File dependency query over current repository state.",
+    },
+    {
+        command: "rdeps",
+        behaviors: ["current-query"],
+        family: "graph-query",
+        reason: "Reverse dependency query over current repository state.",
+    },
+    {
+        command: "path",
+        behaviors: ["current-query"],
+        family: "graph-query",
+        reason: "Shortest dependency path over current repository state.",
+    },
+    {
+        command: "cycles",
+        behaviors: ["current-query", "none"],
+        family: "graph-query",
+        reason: "Whole-project mode queries the index; include-root mode uses a scoped graph collector.",
+    },
+    {
+        command: "hotspots",
+        behaviors: ["current-query"],
+        family: "structural-summary",
+        reason: "Fan-in/fan-out summary over resolved include-root scope.",
+    },
+    {
+        command: "duplicates",
+        behaviors: ["current-query"],
+        family: "duplicate-analysis",
+        reason: "Duplicate detection over resolved scope, reusing the duplicate unit cache.",
+    },
+    {
+        command: "unresolved",
+        behaviors: ["current-query"],
+        family: "graph-query",
+        reason: "Unresolved import query over current repository state.",
+    },
+    {
+        command: "apisurface",
+        behaviors: ["current-query"],
+        family: "graph-query",
+        reason: "Exported API summary over current repository state.",
+    },
+    { command: "grep", behaviors: ["none"], reason: "Text and Tree-sitter query search without an index." },
+    { command: "links", behaviors: ["none"], reason: "Validates Markdown files directly without an index." },
+    {
+        command: "graph-delta",
+        behaviors: ["historical"],
+        reason: "Compares a requested changed range, not current-state freshness.",
+    },
+    { command: "sql", behaviors: ["none"], reason: "Reads an existing SQLite export." },
+    { command: "chunk", behaviors: ["none"], reason: "Chunks a single file for embeddings." },
+    { command: "doctor", behaviors: ["none"], reason: "Inspects runtime and artifact state only." },
+    { command: "install", behaviors: ["none"], reason: "Writes client configuration only." },
+    { command: "uninstall", behaviors: ["none"], reason: "Removes client configuration only." },
+    { command: "skill", behaviors: ["none"], reason: "Installs or inspects the bundled skill." },
+    { command: "version", behaviors: ["none"], reason: "Prints version identity." },
+    {
+        command: "dumpmod",
+        behaviors: ["current-query"],
+        family: "navigation",
+        reason: "Dumps one indexed module from current repository state.",
+    },
+];
+const policyByCommand = new Map(CLI_INDEX_POLICY.map((entry) => [entry.command, entry]));
+/** Resolve the index policy for a command name or alias. */
+export function indexPolicyForCommand(command) {
+    const canonical = resolveCliCommand(command);
+    if (!canonical)
+        return undefined;
+    return policyByCommand.get(canonical);
+}
+/** Canonical command names that load current repository state, grouped by wiring family. */
+export function currentQueryCommandsByFamily() {
+    const byFamily = new Map();
+    for (const entry of CLI_INDEX_POLICY) {
+        if (!entry.behaviors.includes("current-query") || !entry.family)
+            continue;
+        const commands = byFamily.get(entry.family) ?? [];
+        commands.push(entry.command);
+        byFamily.set(entry.family, commands);
+    }
+    return byFamily;
+}
+/** Canonical command names known to the catalog, for parity checks. */
+export function catalogCommandNames() {
+    return CLI_COMMAND_CATALOG.map((command) => command.name);
+}
+//# sourceMappingURL=indexPolicy.js.map

package/dist/cli/indexPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexPolicy.js","sourceRoot":"","sources":["../../src/cli/indexPolicy.ts"],"names":[],"mappings":"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"}

package/dist/cli/inspect.d.ts

@@ -0,0 +1,30 @@
+import type { GraphBuildOptions } from "../graphs/types.js";
+import { type BuildOptions } from "../indexer/types.js";
+import type { NativeRuntimeMode } from "../native/treeSitterNative.js";
+import type { LanguageExtensionMap } from "../languages.js";
+import type { ProjectFileDiscoveryOptions } from "../util/projectFiles.js";
+import type { CommandReport } from "./context.js";
+export type InspectCommandContext = {
+    projectRootFs: string;
+    includeRootsAbs: string[];
+    discoveryOptions: ProjectFileDiscoveryOptions;
+    languageExtensions: LanguageExtensionMap | undefined;
+    graphOptions: GraphBuildOptions | undefined;
+    nativeMode: NativeRuntimeMode;
+    workerOpts: {
+        useNativeWorkers: true;
+    } | Record<string, never>;
+    progressHandler: BuildOptions["onProgress"];
+    getOpt: (name: string) => string | undefined;
+    hasFlag: (name: string) => boolean;
+    resolveFilesFromRoots: () => Promise<string[]>;
+    writeJSONLine: (value: unknown) => void;
+    writeStdoutLine: (message: string) => void;
+    writeStderrLine: (message: string) => void;
+    reportFile?: string | undefined;
+    commandReport?: CommandReport | undefined;
+    writeCommandReport?: (report: CommandReport, reportFile: string | undefined) => Promise<void>;
+};
+export declare function handleInspectCommand(context: InspectCommandContext): Promise<void>;
+export declare function handleHotspotsCommand(context: InspectCommandContext): Promise<void>;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/cli/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/cli/inspect.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,qBAAqB,CAAC;AAM1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAIvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAG3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA2ElD,MAAM,MAAM,qBAAqB,GAAG;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,EAAE,2BAA2B,CAAC;IAC9C,kBAAkB,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACrD,YAAY,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC5C,UAAU,EAAE,iBAAiB,CAAC;IAC9B,UAAU,EAAE;QAAE,gBAAgB,EAAE,IAAI,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC/D,eAAe,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;IAC5C,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC7C,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,qBAAqB,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACxC,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/F,CAAC;AA0UF,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BxF;AAED,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BzF"}