@descryy/mcp 0.9.1 → 0.11.0

package/dist/tools/analyze-workspace.js

@@ -0,0 +1,207 @@
+/**
+ * `analyze_workspace` — Gap 1 of
+ * `documents/plans/site-claims-closure-production-plan.md`: the cross-repo
+ * counterpart of `analyze`. Resolves the repository list from
+ * `session.config.workspaceRepos` (written by `link_workspace`, never
+ * inferred — same rule `link_workspace`'s own header states), migrates any
+ * existing per-repository graph aside per `migrateToWorkspaceGraph`
+ * (`@descryy/core`), and calls `indexWorkspace` to read every repository into
+ * one shared store.
+ *
+ * Deliberately a **new** tool rather than a mode on `analyze` — `analyze`'s
+ * contract is "read this one repository" and every one of its callers reads
+ * its reply as describing `session.repoPath` alone; overloading it would
+ * change that contract for all of them. `analyze_workspace` instead composes
+ * `analyze`'s own building blocks (via `indexWorkspace`) without touching
+ * `analyze.ts` at all.
+ *
+ * The shared graph's location is a disclosed design choice, not an inferred
+ * one — see `workspaceGraphPath`'s own doc in `@descryy/core` for why it
+ * lives under the *invoking* repository's `.descry/` directory rather than
+ * some central, app-wide location this package (unlike `descry-desktop`) has
+ * no concept of.
+ */
+import { join, resolve } from "node:path";
+import { isGitRepository, migrateToWorkspaceGraph, workspaceGraphPath, } from "@descryy/core";
+import { indexWorkspace } from "../workspace-index.js";
+import { loadConfig } from "../session.js";
+import { answer, optionalBoolean, optionalInteger } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        includeHistory: {
+            type: "boolean",
+            description: "Read each repository's git history for co-change coupling. Default true.",
+        },
+        maxCommits: {
+            type: "integer",
+            minimum: 1,
+            description: "Cap on commits read from each repository's history. Default 2000.",
+        },
+    },
+    additionalProperties: false,
+};
+/** Where `repository`'s own pre-workspace graph lives today, per its own config — `null` when that cannot be determined (config unreadable), which `migrateToWorkspaceGraph` treats as nothing to move for it. */
+async function ownGraphPath(repository) {
+    try {
+        const config = await loadConfig(repository.path);
+        const graphPath = config.graph.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(config.graph)
+            ? config.graph
+            : join(repository.path, config.graph);
+        return { repo: repository.repo, graphPath };
+    }
+    catch {
+        return null;
+    }
+}
+async function run(args, ctx) {
+    const { session } = ctx;
+    const includeHistory = optionalBoolean(args, "includeHistory") ?? true;
+    const maxCommits = optionalInteger(args, "maxCommits", 1);
+    const workspace = session.config.workspace;
+    if (workspace === undefined) {
+        return answer({
+            headline: "No workspace is configured for this repository.",
+            state: "refused",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: null,
+            graphBuiltAt: null,
+            irSchemaVersion: session.provider().baseStamp().irSchemaVersion,
+            commitSpread: session.provider().baseStamp().commitSpread,
+            repoCount: session.provider().baseStamp().repoCount,
+            notes: [
+                'Call "link_workspace" first, with the repositories the user has explicitly confirmed ' +
+                    "belong together, then run analyze_workspace again.",
+            ],
+            data: {
+                workspace: "",
+                graphPath: "",
+                repos: [],
+                stored: { nodes: 0, edges: 0, unresolvedRefs: 0 },
+                merge: { mergedNodes: 0, mergedEdges: 0, collisions: 0, droppedEdges: 0, rejections: 0 },
+                migration: { migrated: false, movedDatabases: [] },
+            },
+        });
+    }
+    const declaredRepos = session.config.workspaceRepos ?? [];
+    if (declaredRepos.length < 2) {
+        return answer({
+            headline: `Workspace "${workspace}" has fewer than two declared repositories — nothing to join.`,
+            state: "refused",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: null,
+            graphBuiltAt: null,
+            irSchemaVersion: session.provider().baseStamp().irSchemaVersion,
+            commitSpread: session.provider().baseStamp().commitSpread,
+            repoCount: session.provider().baseStamp().repoCount,
+            notes: [
+                `session.config.workspaceRepos has ${declaredRepos.length} entr${declaredRepos.length === 1 ? "y" : "ies"}. ` +
+                    'Re-run "link_workspace" naming every repository that belongs to this workspace, including ' +
+                    "this one, then run analyze_workspace again.",
+            ],
+            data: {
+                workspace,
+                graphPath: "",
+                repos: [],
+                stored: { nodes: 0, edges: 0, unresolvedRefs: 0 },
+                merge: { mergedNodes: 0, mergedEdges: 0, collisions: 0, droppedEdges: 0, rejections: 0 },
+                migration: { migrated: false, movedDatabases: [] },
+            },
+        });
+    }
+    // The shared graph lives under the *invoking* repository's own `.descry/`
+    // directory — a disclosed design choice, not an inferred one; see this
+    // module's own header and `workspaceGraphPath`'s doc in `@descryy/core`.
+    const rootDir = join(session.repoPath, ".descry");
+    const graphDbPath = workspaceGraphPath(rootDir, workspace);
+    const notes = [];
+    const locations = (await Promise.all(declaredRepos.map(ownGraphPath))).filter((location) => location !== null && location.graphPath !== graphDbPath);
+    const migration = migrateToWorkspaceGraph({ rootDir, workspaceId: workspace, repositories: locations });
+    if (migration.disclosure !== null)
+        notes.push(migration.disclosure);
+    const missingRepos = [];
+    const repoInputs = [];
+    for (const declared of declaredRepos) {
+        const absolute = resolve(declared.path);
+        if (!(await isGitRepository(absolute).catch(() => false))) {
+            // `indexWorkspace` itself would also refuse this repository and say so
+            // in its own per-repo notes — checked here too only so a repository
+            // that cannot even be reached at all is named before the run starts,
+            // not discovered only in a per-repo note buried in the reply.
+            missingRepos.push(declared.path);
+        }
+        repoInputs.push({ repoPath: absolute, repo: declared.repo });
+    }
+    if (missingRepos.length > 0) {
+        notes.push(`${missingRepos.length} declared repositor${missingRepos.length === 1 ? "y is" : "ies are"} not a ` +
+            `git repository at the declared path (${missingRepos.join(", ")}) — each will be reported as not ` +
+            "indexed rather than skipped silently.");
+    }
+    const result = await indexWorkspace({
+        workspaceId: workspace,
+        repos: repoInputs,
+        graphDbPath,
+        includeHistory,
+        ...(maxCommits === undefined ? {} : { maxCommits }),
+        onProgress: (progress) => ctx.progress(`${progress.repo}: ${progress.phase}`, progress.completed, progress.total),
+        signal: ctx.signal,
+    });
+    for (const note of result.notes)
+        notes.push(note);
+    for (const repo of result.repos)
+        for (const note of repo.notes)
+            notes.push(`${repo.repo}: ${note}`);
+    const readRepos = result.repos.filter((r) => r.commitSha !== null).length;
+    const headline = readRepos === 0
+        ? `Nothing was read for workspace "${workspace}" — none of its ${result.repos.length} declared ` +
+            "repositories could be indexed."
+        : `Analysed workspace "${workspace}": ${readRepos} of ${result.repos.length} repositories indexed ` +
+            `into one shared graph, which now holds ${result.stored.nodes} nodes, ${result.stored.edges} edges.`;
+    return answer({
+        headline,
+        state: readRepos === 0 ? "refused" : "ok",
+        nameLevel: true,
+        resolutionFloor: result.stamp.resolutionFloor,
+        // No single commit describes a workspace spanning several repositories —
+        // each repository's own commit is in `data.repos[].commitSha` instead.
+        commitSha: null,
+        graphBuiltAt: Date.now(),
+        irSchemaVersion: result.stamp.irSchemaVersion,
+        commitSpread: result.stamp.commitSpread,
+        repoCount: result.stamp.repoCount,
+        notes,
+        data: {
+            workspace,
+            graphPath: graphDbPath,
+            repos: result.repos,
+            stored: {
+                nodes: result.stored.nodes,
+                edges: result.stored.edges,
+                unresolvedRefs: result.stored.unresolvedRefs,
+            },
+            merge: result.merge,
+            migration: {
+                migrated: migration.migrated,
+                movedDatabases: migration.movedDatabases.map((m) => ({ repo: m.repo, from: m.from, to: m.to })),
+            },
+        },
+    });
+}
+export const analyzeWorkspaceTool = {
+    name: "analyze_workspace",
+    class: "stateful-read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Analyse every repository in a workspace into one shared code graph",
+    description: 'Read every repository declared by "link_workspace" with its own configured adapters, and ' +
+        "store the merged result as one shared code graph — so a frontend's USES_API and a backend's " +
+        "SERVES_API can join on the same API_ENDPOINT id (DEC-054). Requires a workspace to already be " +
+        'linked; call "link_workspace" first if it is not. Moves any existing per-repository graph ' +
+        "aside (never deletes it) the first time a repository joins a shared graph, and re-indexes it " +
+        "into the shared store in the same call.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=analyze-workspace.js.map

package/dist/tools/analyze-workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-workspace.js","sourceRoot":"","sources":["../../src/tools/analyze-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,kBAAkB,GAEnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,cAAc,EAAiC,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,UAAU,EAAsB,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,EAAyC,MAAM,UAAU,CAAC;AAyB3G,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,cAAc,EAAE;YACd,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,0EAA0E;SACxF;QACD,UAAU,EAAE;YACV,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,WAAW,EAAE,mEAAmE;SACjF;KACF;IACD,oBAAoB,EAAE,KAAK;CACnB,CAAC;AAEX,kNAAkN;AAClN,KAAK,UAAU,YAAY,CAAC,UAAyB;IACnD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;YACpF,CAAC,CAAC,MAAM,CAAC,KAAK;YACd,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACxC,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,GAAG,CAAC,IAA6B,EAAE,GAAgB;IAChE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;IACxB,MAAM,cAAc,GAAG,eAAe,CAAC,IAAI,EAAE,gBAAgB,CAAC,IAAI,IAAI,CAAC;IACvE,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;IAE1D,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC;IAC3C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAuB;YAClC,QAAQ,EAAE,iDAAiD;YAC3D,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,IAAI;YACf,eAAe,EAAE,CAAC;YAClB,SAAS,EAAE,IAAI;YACf,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,eAAe;YAC/D,YAAY,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,YAAY;YACzD,SAAS,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,SAAS;YACnD,KAAK,EAAE;gBACL,uFAAuF;oBACrF,oDAAoD;aACvD;YACD,IAAI,EAAE;gBACJ,SAAS,EAAE,EAAE;gBACb,SAAS,EAAE,EAAE;gBACb,KAAK,EAAE,EAAE;gBACT,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE;gBACjD,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;gBACxF,SAAS,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE;aACnD;SACF,CAAC,CAAC;IACL,CAAC;IAED,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;IAC1D,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAuB;YAClC,QAAQ,EAAE,cAAc,SAAS,+DAA+D;YAChG,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,IAAI;YACf,eAAe,EAAE,CAAC;YAClB,SAAS,EAAE,IAAI;YACf,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,eAAe;YAC/D,YAAY,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,YAAY;YACzD,SAAS,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,SAAS;YACnD,KAAK,EAAE;gBACL,qCAAqC,aAAa,CAAC,MAAM,QAAQ,aAAa,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;oBAC3G,4FAA4F;oBAC5F,6CAA6C;aAChD;YACD,IAAI,EAAE;gBACJ,SAAS;gBACT,SAAS,EAAE,EAAE;gBACb,KAAK,EAAE,EAAE;gBACT,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE;gBACjD,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;gBACxF,SAAS,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE;aACnD;SACF,CAAC,CAAC;IACL,CAAC;IAED,0EAA0E;IAC1E,uEAAuE;IACvE,yEAAyE;IACzE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAE3D,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,SAAS,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAC3E,CAAC,QAAQ,EAAiC,EAAE,CAAC,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,SAAS,KAAK,WAAW,CACrG,CAAC;IACF,MAAM,SAAS,GAAG,uBAAuB,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC,CAAC;IACxG,IAAI,SAAS,CAAC,UAAU,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAEpE,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,UAAU,GAAyC,EAAE,CAAC;IAC5D,KAAK,MAAM,QAAQ,IAAI,aAAa,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,CAAC,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAC1D,uEAAuE;YACvE,oEAAoE;YACpE,qEAAqE;YACrE,8DAA8D;YAC9D,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CACR,GAAG,YAAY,CAAC,MAAM,sBAAsB,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,SAAS;YACjG,wCAAwC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,mCAAmC;YAClG,uCAAuC,CAC1C,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC;QAClC,WAAW,EAAE,SAAS;QACtB,KAAK,EAAE,UAAU;QACjB,WAAW;QACX,cAAc;QACd,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;QACnD,UAAU,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,KAAK,EAAE,EAAE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC;QACjH,MAAM,EAAE,GAAG,CAAC,MAAM;KACnB,CAAC,CAAC;IAEH,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK;QAAE,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC;IAEpG,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;IAC1E,MAAM,QAAQ,GACZ,SAAS,KAAK,CAAC;QACb,CAAC,CAAC,mCAAmC,SAAS,mBAAmB,MAAM,CAAC,KAAK,CAAC,MAAM,YAAY;YAC9F,gCAAgC;QAClC,CAAC,CAAC,uBAAuB,SAAS,MAAM,SAAS,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,wBAAwB;YACjG,0CAA0C,MAAM,CAAC,MAAM,CAAC,KAAK,WAAW,MAAM,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC;IAE3G,OAAO,MAAM,CAAuB;QAClC,QAAQ;QACR,KAAK,EAAE,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;QACzC,SAAS,EAAE,IAAI;QACf,eAAe,EAAE,MAAM,CAAC,KAAK,CAAC,eAAe;QAC7C,yEAAyE;QACzE,uEAAuE;QACvE,SAAS,EAAE,IAAI;QACf,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE;QACxB,eAAe,EAAE,MAAM,CAAC,KAAK,CAAC,eAAe;QAC7C,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY;QACvC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS;QACjC,KAAK;QACL,IAAI,EAAE;YACJ,SAAS;YACT,SAAS,EAAE,WAAW;YACtB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE;gBACN,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK;gBAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK;gBAC1B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc;aAC7C;YACD,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,SAAS,EAAE;gBACT,QAAQ,EAAE,SAAS,CAAC,QAAQ;gBAC5B,cAAc,EAAE,SAAS,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;aAChG;SACF;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAmB;IAClD,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,eAAe;IACtB,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,oEAAoE;IAC3E,WAAW,EACT,2FAA2F;QAC3F,8FAA8F;QAC9F,gGAAgG;QAChG,4FAA4F;QAC5F,+FAA+F;QAC/F,yCAAyC;IAC3C,WAAW,EAAE,MAA4C;IACzD,GAAG;CACJ,CAAC"}

package/dist/tools/analyze.d.ts

@@ -4,9 +4,10 @@
  *  reached (caps reliability, rule 3), id collisions (DEC-024), evicted files, and the
  *  cross-repo join count. No config → `repo` defaults to dir name, hashed into every id (DEC-004). */
 import type { IRBatch, UnresolvedRef } from "@descryy/ir";
+import { getCachedFiles } from "@descryy/core";
 import type { BuildResult, JoinMetric, StoreCounts } from "@descryy/core";
 import { type ToolDefinition } from "./kit.ts";
-import { type LoadedSource } from "../registry.ts";
+import { type DetectionEvidence, type LoadedSource } from "../registry.ts";
 export { configDriftNote } from "../session.ts";
 /** What one source read, and how well. `reachedResolution` is what rule 3 caps everything
  *  above it by — a run degraded to R0 looks identical to a healthy one until this is read. */
@@ -101,9 +102,48 @@ export interface AnalyzeData {
         readonly evictedFiles: number;
     };
 }
-/** §5.4's `refusals` field for this run only, not the graph's whole ledger
- *  (`refusal_fetch`'s job) — a fresh population per call, honestly scoped to what
- *  this run found. `undefined` on zero rows so `refusals` stays `null`, not an empty summary. */
+/**
+ * P6-B1 — the run stopped at the heap fence, before the phase that would have
+ * aborted the process.
+ *
+ * A distinct shape rather than a zeroed `AnalyzeData`, for the same reason
+ * `scope` has `ScopeNotSeeded`: a halted run has no source table, no merge
+ * counts and no stored totals, and reporting zeros for them would say the
+ * repository is empty rather than that Descry stopped looking. Narrow on
+ * `"halted" in data`.
+ */
+export interface AnalyzeHalted {
+    readonly halted: "heap";
+    /** The phase that was refused — what would have run next, not what failed. */
+    readonly phase: string;
+    readonly heapUsedMib: number;
+    readonly heapLimitMib: number;
+    /** Sources that had already emitted when the fence tripped. Read, then discarded unwritten. */
+    readonly sourcesRead: readonly SourceRun[];
+}
+export type AnalyzeResult = AnalyzeData | AnalyzeHalted;
+/** Gap 6 step 3: attempts whole-producer cache reuse for one `LanguageAdapter`
+ *  source, so a repeat `analyze` run can skip `emit()` (and the re-parse inside
+ *  it) entirely when nothing this producer read has changed. Every failure path
+ *  here returns `{ reused: false }` rather than throwing — declining to reuse is
+ *  always safe, and the caller's normal `emit()` path is the fallback. See
+ *  `planIncrementalReuse`'s doc (`@descryy/core`) for why this is whole-producer,
+ *  never per-file. */
+export declare function attemptIncrementalReuse(params: {
+    readonly driver: Parameters<typeof getCachedFiles>[0];
+    readonly producedBy: string;
+    readonly repo: string;
+    readonly repoPath: string;
+    readonly repoFileListing: readonly string[] | null;
+    readonly commitSha: string;
+    readonly workspace: string | undefined;
+}): Promise<{
+    readonly reused: true;
+    readonly batch: IRBatch;
+} | {
+    readonly reused: false;
+    readonly reason: string;
+}>;
 export declare function refusalSummaryField(unresolved: readonly UnresolvedRef[]): {
     readonly count: number;
     readonly exemplar: string;
@@ -113,5 +153,11 @@ export declare function refusalSummaryField(unresolved: readonly UnresolvedRef[]
  *  every join metric's `suppliedByTwoOrMoreRepos: 0` looks like `NO_CROSS_REPO_JOIN`'s
  *  failure case; this states outright it's just scope, not a failed join. */
 export declare function crossRepoJoinNote(joins: readonly JoinMetric[]): string | undefined;
+/** Turns one adapter's `DetectionResult.evidence` into the same kind of disclosed note the
+ *  `skippedFiles` rollup below builds — grouped by `reason` where an entry is a
+ *  `StructuredSkipEntry`, left under an "other" bucket, verbatim, where it is still the
+ *  legacy plain-string shape (`isStructuredSkipEntry`, `@descryy/ir`). `null` on an empty
+ *  list — nothing to disclose, not a note saying so. */
+export declare function summariseDetectionEvidence(evidence: DetectionEvidence): string | null;
 export declare const analyzeTool: ToolDefinition;
 //# sourceMappingURL=analyze.d.ts.map

package/dist/tools/analyze.d.ts.map

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

package/dist/tools/analyze.js

@@ -3,8 +3,14 @@
  *  didn't claim the repo (§20.2 — not-analysable ≠ clean), each source's resolution
  *  reached (caps reliability, rule 3), id collisions (DEC-024), evicted files, and the
  *  cross-repo join count. No config → `repo` defaults to dir name, hashed into every id (DEC-004). */
-import { applyConfirmedFacts, buildGraph, CONFIRMED_INCIDENT_SOURCE_ID, CONFIRMED_INCIDENT_SOURCE_VERSION, counts, createConfirmedIncidentSource, createGitSource, evictStaleConfirmedIncidentNodes, mintEdgesFromConfirmedFacts, MINT_PRODUCED_BY, persistGraph, summariseRefusals, } from "@descryy/core";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isStructuredSkipEntry } from "@descryy/ir";
+import { applyConfirmedFacts, buildGraph, CONFIRMED_INCIDENT_SOURCE_ID, CONFIRMED_INCIDENT_SOURCE_VERSION, counts, createConfirmedIncidentSource, createGitSource, evictStaleConfirmedIncidentNodes, FILELESS_CACHE_KEY, getCachedFiles, listWorkingTreeFiles, mintEdgesFromConfirmedFacts, MINT_PRODUCED_BY, partitionBatchByFile, persistGraph, planIncrementalReuse, replaceCachedFiles, summariseRefusals, } from "@descryy/core";
 import { answer, optionalBoolean, ToolInputError } from "./kit.js";
+import { heapGuard, readHeap } from "../heap.js";
+import { withHeartbeat } from "../heartbeat.js";
 import { detectSources, loadSources } from "../registry.js";
 // Re-exported for `analyze.test.ts`, which covers this pure helper in isolation.
 // The check itself now runs centrally in `server.ts` (13.3.16 / N2 steps 2-3) —
@@ -90,6 +96,63 @@ const SCHEMA = {
 /** §5.4's `refusals` field for this run only, not the graph's whole ledger
  *  (`refusal_fetch`'s job) — a fresh population per call, honestly scoped to what
  *  this run found. `undefined` on zero rows so `refusals` stays `null`, not an empty summary. */
+async function hashFileContent(absolutePath) {
+    try {
+        return createHash("sha256").update(await readFile(absolutePath)).digest("hex");
+    }
+    catch {
+        // Deleted, unreadable, or otherwise gone — left absent so the caller's
+        // hash lookup mismatches the cached value and correctly reports "changed".
+        return null;
+    }
+}
+/** Gap 6 step 3: attempts whole-producer cache reuse for one `LanguageAdapter`
+ *  source, so a repeat `analyze` run can skip `emit()` (and the re-parse inside
+ *  it) entirely when nothing this producer read has changed. Every failure path
+ *  here returns `{ reused: false }` rather than throwing — declining to reuse is
+ *  always safe, and the caller's normal `emit()` path is the fallback. See
+ *  `planIncrementalReuse`'s doc (`@descryy/core`) for why this is whole-producer,
+ *  never per-file. */
+export async function attemptIncrementalReuse(params) {
+    const cache = getCachedFiles(params.driver, params.producedBy, params.repo);
+    const cachedPaths = [...cache.files.keys()].filter((path) => path !== FILELESS_CACHE_KEY);
+    const cachedHashes = new Map(cachedPaths.map((path) => [path, cache.files.get(path).contentHash]));
+    const currentHashes = new Map();
+    for (const path of cachedPaths) {
+        const hash = await hashFileContent(join(params.repoPath, path));
+        if (hash !== null)
+            currentHashes.set(path, hash);
+    }
+    const decision = planIncrementalReuse({
+        cachedPaths,
+        repoPaths: params.repoFileListing,
+        currentHashes,
+        cachedHashes,
+    });
+    if (!decision.canReuse)
+        return { reused: false, reason: decision.reason };
+    const nodes = [];
+    const edges = [];
+    const unresolved = [];
+    for (const entry of cache.files.values()) {
+        nodes.push(...entry.nodes);
+        edges.push(...entry.edges);
+        unresolved.push(...entry.unresolved);
+    }
+    const batch = {
+        repo: params.repo,
+        ...(params.workspace === undefined ? {} : { workspace: params.workspace }),
+        commitSha: params.commitSha,
+        producedBy: params.producedBy,
+        sourceFiles: cachedPaths,
+        skippedFiles: cache.skippedFiles,
+        reachedResolution: (cache.reachedResolution ?? 0),
+        nodes,
+        edges,
+        unresolved,
+    };
+    return { reused: true, batch };
+}
 export function refusalSummaryField(unresolved) {
     const summary = summariseRefusals(unresolved);
     if (summary.count === 0 || summary.exemplar === null || summary.handle === null)
@@ -109,6 +172,30 @@ export function crossRepoJoinNote(joins) {
         "take for them; this is not the NO_CROSS_REPO_JOIN warning, which is for two or more " +
         "repositories that failed to join.");
 }
+/** Turns one adapter's `DetectionResult.evidence` into the same kind of disclosed note the
+ *  `skippedFiles` rollup below builds — grouped by `reason` where an entry is a
+ *  `StructuredSkipEntry`, left under an "other" bucket, verbatim, where it is still the
+ *  legacy plain-string shape (`isStructuredSkipEntry`, `@descryy/ir`). `null` on an empty
+ *  list — nothing to disclose, not a note saying so. */
+export function summariseDetectionEvidence(evidence) {
+    if (evidence.entries.length === 0)
+        return null;
+    const byReason = new Map();
+    const legacy = [];
+    for (const entry of evidence.entries) {
+        if (isStructuredSkipEntry(entry)) {
+            byReason.set(entry.reason, (byReason.get(entry.reason) ?? 0) + 1);
+        }
+        else {
+            legacy.push(entry);
+        }
+    }
+    const parts = [...byReason.entries()].map(([reason, count]) => `${count} ${reason}`);
+    if (legacy.length > 0)
+        parts.push(`${legacy.length} other (${legacy.join("; ")})`);
+    return (`${evidence.source} reported ${evidence.entries.length} detection note(s) for this ` +
+        `repository (${parts.join(", ")}).`);
+}
 async function run(args, ctx) {
     const { session } = ctx;
     const includeHistory = args["includeHistory"] !== false;
@@ -169,11 +256,16 @@ async function run(args, ctx) {
             "specifiers. This engine does not know the name of any adapter: the IR boundary is a " +
             "dependency direction, so the list has to come from configuration.");
     }
-    const { applicable, skipped } = await detectSources(registry.loaded, root);
+    const { applicable, skipped, evidence } = await detectSources(registry.loaded, root);
     for (const entry of skipped) {
         notes.push(`${entry.source.source.id} did not run: it ${entry.reason}. Any code only that adapter ` +
             "could read is not analysable.");
     }
+    for (const item of evidence) {
+        const note = summariseDetectionEvidence(item);
+        if (note !== null)
+            notes.push(note);
+    }
     // --- emit ----------------------------------------------------------------
     const context = {
         root,
@@ -188,14 +280,111 @@ async function run(args, ctx) {
     const codeResolutions = [];
     const total = applicable.length + (includeHistory ? 1 : 0);
     let done = 0;
+    const driver = session.store().driver;
+    // Computed once for the whole run, not per source: every `LanguageAdapter`
+    // source's Gap 6 reuse check needs the same "what does the working tree have
+    // right now" answer, and it is meaningless to ask git for it twice. `null`
+    // when it cannot be determined at all (no git, or git unavailable) — every
+    // incremental check below then conservatively declines to reuse anything.
+    const repoFileListing = await listWorkingTreeFiles(session.repoPath).catch(() => null);
+    /**
+     * P6-B1. The fence, at the two points where this tool's memory actually
+     * peaks: before an adapter is asked to read the repository (its batch is
+     * retained for the whole run), and before the merge, which holds every
+     * batch and the built graph live at once. A V8 heap abort cannot be caught
+     * — this is the only place the failure can be turned into a reply.
+     *
+     * `sourcesRead` reports what had already emitted, because those batches are
+     * discarded unwritten: without it the reply would be silent about work that
+     * did happen and produced nothing.
+     */
+    const halted = (phase) => {
+        const reading = readHeap();
+        const note = heapGuard(reading, phase);
+        if (note === null)
+            return null;
+        const base = session.provider().baseStamp();
+        return answer({
+            headline: `Analysis of ${session.config.repo} stopped at the heap ceiling before "${phase}". ` +
+                "Nothing was written to the graph.",
+            state: "failed",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: root.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            commitSpread: base.commitSpread,
+            repoCount: base.repoCount,
+            notes: [...notes, note],
+            data: {
+                halted: "heap",
+                phase,
+                heapUsedMib: Math.round(reading.usedBytes / (1024 * 1024)),
+                heapLimitMib: Math.round(reading.limitBytes / (1024 * 1024)),
+                sourcesRead: perSource,
+            },
+        });
+    };
     for (const entry of applicable) {
+        const fence = halted(`Reading ${entry.source.id}`);
+        if (fence !== null)
+            return fence;
         ctx.progress(`Reading ${entry.source.id}`, done, total);
         const started = Date.now();
+        // Gap 6: only `LanguageAdapter` sources pay the re-parse cost this exists
+        // to avoid — the git-history/confirmed-incidents/mint sources below are
+        // already cheap and deterministic and are out of scope for this cache.
+        if (entry.adapter !== null) {
+            const expectedProducedBy = `${entry.source.id}@${entry.source.version}`;
+            const reuse = await attemptIncrementalReuse({
+                driver,
+                producedBy: expectedProducedBy,
+                repo: session.config.repo,
+                repoPath: session.repoPath,
+                repoFileListing,
+                commitSha: root.commitSha,
+                workspace: session.config.workspace,
+            });
+            if (reuse.reused) {
+                const batch = reuse.batch;
+                batches.push(batch);
+                perSource.push({
+                    source: batch.producedBy,
+                    installedVersion: entry.packageVersion,
+                    files: batch.sourceFiles.length,
+                    nodes: batch.nodes.length,
+                    edges: batch.edges.length,
+                    unresolved: batch.unresolved.length,
+                    skippedFiles: batch.skippedFiles.length,
+                    reachedResolution: batch.reachedResolution,
+                    ms: 0,
+                });
+                const ceiling = entry.adapter.capabilities().maxResolution;
+                codeResolutions.push(batch.reachedResolution);
+                notes.push(`${entry.source.id}: reused ${String(batch.sourceFiles.length)} cached file(s) from the ` +
+                    "previous run, unchanged since — not re-parsed this run (Gap 6 incremental indexing). " +
+                    "Cross-file effects (a change in one file altering another file's resolved edges) are " +
+                    "not re-checked by this cache; see documents/plans/site-claims-closure-production-plan.md Gap 6.");
+                if (batch.reachedResolution < ceiling) {
+                    notes.push(`${entry.source.id} reached R${String(batch.reachedResolution)} where it is capable of ` +
+                        `R${String(ceiling)} (cached from its last real run). Findings resting on its edges are ` +
+                        "capped accordingly, and shape-level checks (contract matching, field propagation) need R3.");
+                }
+                done += 1;
+                continue;
+            }
+        }
         // Adapter's own work and Descry's handling of its output are separate phases with
         // separate blame — folding them into one `try` let a `TypeError` here be blamed on the adapter.
         let batch;
         try {
-            batch = await entry.source.emit(context);
+            // P6-B2. An adapter reading a large repository can hold this await for
+            // minutes, and until now that was the whole gap between two progress
+            // frames — long enough for the client's timeout to fire on a run that
+            // was working. The beat keeps the request visibly alive; it does not
+            // claim to know how far through the adapter is, because this side
+            // cannot see that and will not invent it.
+            batch = await withHeartbeat(`Reading ${entry.source.id}`, (message) => ctx.progress(message, done, total), () => entry.source.emit(context));
         }
         catch (error) {
             notes.push(sourceFailureNote(entry.source.id, error, "emit"));
@@ -217,6 +406,29 @@ async function run(args, ctx) {
                 reachedResolution: batch.reachedResolution,
                 ms: Date.now() - started,
             });
+            // Gap 6 step 3: this was a real parse (reuse would have `continue`d above),
+            // so refresh the per-file cache from its output — the only place the
+            // cache is ever written. A producer whose declared `id@version` drifted
+            // from its self-declared `producedBy` (see `sourceProvenanceNote`) simply
+            // caches under the real `producedBy`; the next run's reuse check looks
+            // for `${id}@${version}` and will not find a mismatched entry, which is
+            // the safe direction for this to fail (always falls back to full reparse).
+            try {
+                const partitioned = partitionBatchByFile(batch);
+                const cacheEntries = [];
+                for (const [filePath, contribution] of partitioned) {
+                    const contentHash = filePath === FILELESS_CACHE_KEY
+                        ? "fileless"
+                        : (await hashFileContent(join(session.repoPath, filePath))) ?? "unreadable";
+                    cacheEntries.push({ filePath, contentHash, ...contribution });
+                }
+                replaceCachedFiles(driver, batch.producedBy, session.config.repo, cacheEntries, batch.reachedResolution, skippedFiles, Date.now());
+            }
+            catch {
+                // Caching is an optimisation, never a correctness requirement — a
+                // failure here must not fail the run or lose the batch already pushed
+                // above. Worst case: the next run finds no cache and reparses fully.
+            }
             // Declared ceiling vs what this run reached — a gap is honest degradation (rule 7):
             // the adapter can do better but something in this repo stopped it.
             const ceiling = entry.adapter?.capabilities().maxResolution;
@@ -252,11 +464,14 @@ async function run(args, ctx) {
         ctx.progress("Reading git history", done, total);
         const historyStarted = Date.now();
         try {
-            const history = await createGitSource({
+            // P6-B2, same reason as the adapter read above: `maxCommits` defaults to
+            // 2000, and walking that much history on a large repository is its own
+            // multi-minute silence.
+            const history = await withHeartbeat("Reading git history", (message) => ctx.progress(message, done, total), () => createGitSource({
                 repo: root.repo,
                 cwd: session.repoPath,
                 ...(typeof maxCommits === "number" ? { maxCommits } : {}),
-            }).emit(context);
+            }).emit(context));
             batches.push(history);
             perSource.push({
                 source: history.producedBy,
@@ -310,6 +525,11 @@ async function run(args, ctx) {
             "an edge resting on one is capped at reliability class B (DEC-223).");
     }
     // --- build and store -----------------------------------------------------
+    // The real peak: every batch is live here and `buildGraph` allocates the
+    // merged graph beside them. This is the checkpoint the field report needed.
+    const mergeFence = halted("Merging into the graph");
+    if (mergeFence !== null)
+        return mergeFence;
     ctx.progress("Merging into the graph", done, total);
     const built = buildGraph(batches, {
         nodeExists: (id) => session.provider().node(id) !== undefined,