@descryy/mcp 0.11.5 → 0.11.7

package/dist/tools/workspace.js

@@ -0,0 +1,94 @@
+/**
+ * `workspace` — merges `analyze`, `analyze_workspace` and `link_workspace`
+ * behind one `verb` (documents/plans/mcp-surface-consolidation.md §2, group 1).
+ * All three are `stateful-read`/`evidence`, so the merge crosses neither
+ * boundary.
+ *
+ * Dispatch only. Each verb's own `run()` body is untouched and stays in its
+ * own module (`analyze.ts` / `analyze-workspace.ts` / `link-workspace.ts`) —
+ * this file never holds a second copy of that logic, it only routes to it
+ * after `selectVerb` has re-established, per verb, the argument strength a
+ * flat union schema loses (`verb.ts`'s own header explains why that is
+ * mandatory once a schema covers more than one verb).
+ */
+import { selectVerb } from "./verb.js";
+import { analyzeTool } from "./analyze.js";
+import { analyzeWorkspaceTool } from "./analyze-workspace.js";
+import { linkWorkspaceTool } from "./link-workspace.js";
+const VERBS = ["analyze", "index", "link"];
+const VERB_SPECS = [
+    { verb: "analyze", accepts: ["includeHistory", "maxCommits", "reload"] },
+    { verb: "index", accepts: ["includeHistory", "maxCommits"] },
+    { verb: "link", accepts: ["workspace", "repos"] },
+];
+const SCHEMA = {
+    type: "object",
+    properties: {
+        verb: {
+            type: "string",
+            enum: [...VERBS],
+            description: "analyze: this repository. index: every linked repository. link: declare a shared workspace.",
+        },
+        includeHistory: {
+            type: "boolean",
+            description: "analyze/index. Read git history for co-change. Default true.",
+        },
+        maxCommits: {
+            type: "integer",
+            minimum: 1,
+            description: "analyze/index. Cap on commits read. Default 2000.",
+        },
+        reload: {
+            type: "boolean",
+            description: "analyze only. Re-read config from disk first.",
+        },
+        workspace: {
+            type: "string",
+            description: "link only. Workspace id to write into every repo in \"repos\".",
+        },
+        repos: {
+            type: "array",
+            minItems: 2,
+            items: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Absolute path on disk." },
+                    repo: { type: "string" },
+                },
+                required: ["path", "repo"],
+                additionalProperties: false,
+            },
+            description: "link only. Repositories that share this workspace. Only ones the user confirmed — never inferred.",
+        },
+    },
+    required: ["verb"],
+    additionalProperties: false,
+};
+const DISPATCH = {
+    analyze: analyzeTool,
+    index: analyzeWorkspaceTool,
+    link: linkWorkspaceTool,
+};
+async function run(args, ctx) {
+    const verb = selectVerb(args, "verb", VERB_SPECS);
+    // `ToolDefinition` erases its answer's type parameter — it has to, the
+    // registry is one array of many shapes — so the delegated call comes back as
+    // an erased answer type. The verb table is what makes the union true: every
+    // entry's own `run` is declared against one of WorkspaceData's members, and a verb
+    // added without its shape stops compiling at the union. The assertion
+    // re-applies what the table already guarantees rather than asserting
+    // something unchecked.
+    return (await DISPATCH[verb].run(args, ctx));
+}
+export const workspaceTool = {
+    name: "workspace",
+    class: "stateful-read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Analyse a repository or workspace into the code graph",
+    description: "analyze: read this repository. index: read linked repositories into one graph. link: " +
+        "declare a shared workspace. Most tools build the graph automatically; call to control timing.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=workspace.js.map

package/dist/tools/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/tools/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAiB,MAAM,WAAW,CAAC;AAItD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAkBxD,MAAM,KAAK,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAGpD,MAAM,UAAU,GAA8B;IAC5C,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,gBAAgB,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE;IACxE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,gBAAgB,EAAE,YAAY,CAAC,EAAE;IAC5D,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE;CAClD,CAAC;AAEF,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC;YAChB,WAAW,EAAE,6FAA6F;SAC3G;QACD,cAAc,EAAE;YACd,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,8DAA8D;SAC5E;QACD,UAAU,EAAE;YACV,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC;YACV,WAAW,EAAE,mDAAmD;SACjE;QACD,MAAM,EAAE;YACN,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,+CAA+C;SAC7D;QACD,SAAS,EAAE;YACT,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,gEAAgE;SAC9E;QACD,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,QAAQ,EAAE,CAAC;YACX,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wBAAwB,EAAE;oBAC/D,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iBACzB;gBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;gBAC1B,oBAAoB,EAAE,KAAK;aAC5B;YACD,WAAW,EAAE,mGAAmG;SACjH;KACF;IACD,QAAQ,EAAE,CAAC,MAAM,CAAC;IAClB,oBAAoB,EAAE,KAAK;CACnB,CAAC;AAEX,MAAM,QAAQ,GAA2C;IACvD,OAAO,EAAE,WAAW;IACpB,KAAK,EAAE,oBAAoB;IAC3B,IAAI,EAAE,iBAAiB;CACxB,CAAC;AAEF,KAAK,UAAU,GAAG,CAAC,IAA6B,EAAE,GAAgB;IAChE,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAClD,uEAAuE;IACvE,6EAA6E;IAC7E,4EAA4E;IAC5E,mFAAmF;IACnF,sEAAsE;IACtE,qEAAqE;IACrE,uBAAuB;IACvB,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAA8B,CAAC;AAC5E,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,eAAe;IACtB,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,uDAAuD;IAC9D,WAAW,EACT,uFAAuF;QACvF,+FAA+F;IACjG,WAAW,EAAE,MAA4C;IACzD,GAAG;CACJ,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,32 @@
+/** stdio transport: newline-delimited JSON over stdin/stdout. Stdout is the protocol
+ *  channel and nothing else may write to it — a stray `console.log` anywhere (engine,
+ *  adapter, dependency) corrupts a frame and kills the session with a misleading error;
+ *  `guardStdout()` redirects console.* to stderr instead. Framing: one JSON object per
+ *  line, UTF-8, no embedded newlines; reads use `StringDecoder` since a chunk boundary can split a multibyte character. */
+import type { Readable, Writable } from "node:stream";
+export interface Transport {
+    /** Write one frame. Must never be called with anything but a JSON-RPC message. */
+    send(frame: unknown): void;
+}
+/** Redirects every console channel to stderr and returns the real stdout writer. Called
+ *  once, before any handler runs — the returned function is the only sanctioned path to stdout. */
+export declare function guardStdout(stdout: Writable, stderr: Writable): (line: string) => void;
+/** Splits a byte stream into lines, decoding correctly across chunk boundaries. Returned as
+ *  a function, not a class — the buffer is the entire state, nothing else to hang on an object. */
+export declare function createLineReader(onLine: (line: string) => void): (chunk: Buffer) => void;
+export interface StdioOptions {
+    readonly stdin: Readable;
+    readonly stdout: Writable;
+    readonly stderr: Writable;
+}
+/** Runs a dispatcher over stdio until stdin closes. Resolves on end-of-input — how an MCP
+ *  host asks a stdio server to shut down. Anything the server holds open (DB handle, worker
+ *  pool) is disposed by the caller after, not here — this function knows only about bytes. */
+export interface ServeOptions {
+    /** Frames that must not wait behind an in-flight call. Supplied by the caller — which
+     *  methods mean what is the server's knowledge; `server.ts`'s `isOutOfBand` answers true
+     *  only for `notifications/cancelled`. */
+    readonly isOutOfBand?: (line: string) => boolean;
+}
+export declare function serveStdio(options: StdioOptions, dispatch: (line: string, transport: Transport) => Promise<void>, serveOptions?: ServeOptions): Promise<void>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;2HAI2H;AAG3H,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5B;AAED;mGACmG;AACnG,wBAAgB,WAAW,CACzB,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,QAAQ,GACf,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAiBxB;AAWD;mGACmG;AACnG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAcxF;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC3B;AAED;;8FAE8F;AAC9F,MAAM,WAAW,YAAY;IAC3B;;8CAE0C;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAClD;AAED,wBAAgB,UAAU,CACxB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,EAC/D,YAAY,GAAE,YAAiB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAqCf"}

package/dist/transport.js

@@ -0,0 +1,85 @@
+/** stdio transport: newline-delimited JSON over stdin/stdout. Stdout is the protocol
+ *  channel and nothing else may write to it — a stray `console.log` anywhere (engine,
+ *  adapter, dependency) corrupts a frame and kills the session with a misleading error;
+ *  `guardStdout()` redirects console.* to stderr instead. Framing: one JSON object per
+ *  line, UTF-8, no embedded newlines; reads use `StringDecoder` since a chunk boundary can split a multibyte character. */
+import { StringDecoder } from "node:string_decoder";
+/** Redirects every console channel to stderr and returns the real stdout writer. Called
+ *  once, before any handler runs — the returned function is the only sanctioned path to stdout. */
+export function guardStdout(stdout, stderr) {
+    const toStderr = (...args) => {
+        stderr.write(`${args
+            .map((a) => (typeof a === "string" ? a : inspectish(a)))
+            .join(" ")}\n`);
+    };
+    console.log = toStderr;
+    console.info = toStderr;
+    console.warn = toStderr;
+    console.debug = toStderr;
+    console.error = toStderr;
+    return (line) => {
+        stdout.write(line);
+    };
+}
+function inspectish(value) {
+    if (value instanceof Error)
+        return `${value.name}: ${value.message}`;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Splits a byte stream into lines, decoding correctly across chunk boundaries. Returned as
+ *  a function, not a class — the buffer is the entire state, nothing else to hang on an object. */
+export function createLineReader(onLine) {
+    const decoder = new StringDecoder("utf8");
+    let buffer = "";
+    return (chunk) => {
+        buffer += decoder.write(chunk);
+        let index = buffer.indexOf("\n");
+        while (index !== -1) {
+            const line = buffer.slice(0, index).replace(/\r$/, "");
+            buffer = buffer.slice(index + 1);
+            if (line.trim() !== "")
+                onLine(line);
+            index = buffer.indexOf("\n");
+        }
+    };
+}
+export function serveStdio(options, dispatch, serveOptions = {}) {
+    const write = guardStdout(options.stdout, options.stderr);
+    const transport = {
+        send: (frame) => {
+            write(`${JSON.stringify(frame)}\n`);
+        },
+    };
+    // Frames handled strictly in order — concurrency would let a fast `tools/list` overtake a
+    // slow `analyze` and read a half-built graph. Exempt: `notifications/cancelled` alone (useless
+    // if queued, does no graph work) — narrowly scoped so a future notification doesn't inherit this silently.
+    const isOutOfBand = serveOptions.isOutOfBand ?? (() => false);
+    let chain = Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            // A dispatcher that throws is a bug here — `dispatch` should turn every failure into
+            // an error frame. Report on stderr and keep the session alive rather than killing the editor integration.
+            options.stderr.write(`descry-mcp: dispatch failed: ${inspectish(error)}\n`);
+        };
+        const feed = createLineReader((line) => {
+            if (isOutOfBand(line)) {
+                // Deliberately not joined to `chain` or awaited — an out-of-band frame must not
+                // delay ordered work; its rejection is still handled so it can't surface as unhandled and crash the process.
+                void dispatch(line, transport).catch(onError);
+                return;
+            }
+            chain = chain.then(() => dispatch(line, transport)).catch(onError);
+        });
+        options.stdin.on("data", feed);
+        options.stdin.on("error", reject);
+        options.stdin.on("end", () => {
+            chain.then(resolve, resolve);
+        });
+    });
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;2HAI2H;AAE3H,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAQpD;mGACmG;AACnG,MAAM,UAAU,WAAW,CACzB,MAAgB,EAChB,MAAgB;IAEhB,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAe,EAAQ,EAAE;QAC5C,MAAM,CAAC,KAAK,CACV,GAAG,IAAI;aACJ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;aACvD,IAAI,CAAC,GAAG,CAAC,IAAI,CACjB,CAAC;IACJ,CAAC,CAAC;IACF,OAAO,CAAC,GAAG,GAAG,QAAQ,CAAC;IACvB,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC;IACxB,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC;IACxB,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC;IACzB,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC;IAEzB,OAAO,CAAC,IAAY,EAAQ,EAAE;QAC5B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACrE,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED;mGACmG;AACnG,MAAM,UAAU,gBAAgB,CAAC,MAA8B;IAC7D,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,MAAM,GAAG,EAAE,CAAC;IAEhB,OAAO,CAAC,KAAa,EAAQ,EAAE;QAC7B,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACvD,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YACjC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;gBAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YACrC,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAkBD,MAAM,UAAU,UAAU,CACxB,OAAqB,EACrB,QAA+D,EAC/D,eAA6B,EAAE;IAE/B,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1D,MAAM,SAAS,GAAc;QAC3B,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;YACd,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;KACF,CAAC;IAEF,0FAA0F;IAC1F,+FAA+F;IAC/F,2GAA2G;IAC3G,MAAM,WAAW,GAAG,YAAY,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;IAC9D,IAAI,KAAK,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAE7C,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,MAAM,OAAO,GAAG,CAAC,KAAc,EAAQ,EAAE;YACvC,qFAAqF;YACrF,0GAA0G;YAC1G,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9E,CAAC,CAAC;QAEF,MAAM,IAAI,GAAG,gBAAgB,CAAC,CAAC,IAAI,EAAE,EAAE;YACrC,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtB,gFAAgF;gBAChF,6GAA6G;gBAC7G,KAAK,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC9C,OAAO;YACT,CAAC;YACD,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;YAC3B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/workspace-index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * `indexWorkspace` — the cross-repo counterpart of `analyze`'s single-repo run.
+ *
+ * Gap 1 of `documents/plans/site-claims-closure-production-plan.md`. A
+ * standalone function, **not** a second constructor on `Session` — see that
+ * plan section for why: `session.ts`'s own header states "one repo, one
+ * graph, one process", `DescryConfig` is singular throughout, and well over a
+ * dozen other tool files read `session.config`/`session.repoPath` as singular
+ * values. Widening `Session` itself would mean widening all of them. This
+ * function instead does, once per repository in a loop, exactly what
+ * `analyze.ts`'s `run()` already does once per source — load a repository's
+ * own configured sources, detect, emit, read its git history — and then
+ * merges and persists every repository's batches together in **one**
+ * `buildGraph`/`persistGraph` pass, into one shared store.
+ *
+ * Ported in spirit from `descry-desktop`'s `packages/session/src/indexing
+ * /index.ts` (`indexRepository`), which solved the same "index N
+ * repositories into one store" problem for the desktop app's engine. The
+ * adaptation reuses `descry-core`'s own existing per-repo pieces —
+ * `loadConfig`, `registry.ts`'s `loadSources`/`detectSources`, `analyze.ts`'s
+ * `optionalBatchLists`/`sourceFailureNote`/`sourceProvenanceNote` — instead of
+ * re-discovering adapters or re-deriving batch handling, because those
+ * already live in this package (`@descryy/mcp`) beside `analyze.ts`; there
+ * was nothing to extract into `@descryy/core`.
+ *
+ * ## Why every repository's batches are merged in one `buildGraph` call,
+ * ## not one call per repository
+ *
+ * `buildGraph`'s `JoinMetric`/`crossRepoJoins` (`packages/core/src/graph
+ * /build.ts`) is computed from the batches handed to *that one call*: it
+ * counts, per workspace-scoped node type, how many of the repositories
+ * represented **in that call** supplied a node with the same id. A
+ * `buildGraph` call given only one repository's batches at a time can never
+ * see two repositories agreeing on an id — `crossRepoJoinPossible` would be
+ * false for every type on every call, and the workspace join `analyze_workspace`
+ * exists to prove would be invisible in its own reply. So every repository in
+ * this call is read first, and their batches are combined into one list
+ * before `buildGraph` runs once — the same shape `analyze.ts` already uses
+ * for merging one repository's several *sources*, extended one level up to
+ * merging several *repositories*. `persistGraph` still writes each batch's
+ * rows under its own `producedBy` (DEC-014's per-adapter invalidation rule is
+ * unaffected — a batch is still a batch, whichever repository it came from).
+ *
+ * ## What this deliberately does not do
+ *
+ * Unlike `analyze.ts`'s `run()`, this does not mint edges from confirmed
+ * facts or re-project confirmed incidents — both are per-repository testimony
+ * recorded in that repository's own `.descry/config.json`, and folding them
+ * into a cross-repo indexing pass is a separate, unscoped question. A
+ * repository indexed through `indexWorkspace` gets the code-reading half of
+ * what `analyze` gives it; the two are not currently unified, and that is
+ * disclosed by the caller (`analyze_workspace`), not silently assumed away
+ * here.
+ */
+import { type AmbiguousApiJoin, type AmbiguousTableJoin, type BuildResult, type GraphStamp, type ResolvedApiJoin, type ResolvedTableJoin, type StoreCounts } from "@descryy/core";
+import { type SourceRun } from "./tools/analyze.ts";
+export interface IndexWorkspaceRepoInput {
+    /** Absolute path to the repository on disk. */
+    readonly repoPath: string;
+    /**
+     * The repository's identity as `link_workspace` recorded it
+     * (`WorkspaceRepo.repo`). Used only when the repository's own
+     * `.descry/config.json` cannot be read at all — whenever it can, its own
+     * `repo` field wins instead, because that is the value its adapters
+     * actually hash node ids under; a mismatch between the two is disclosed,
+     * never silently resolved one way (`repoIdentityNote`).
+     */
+    readonly repo: string;
+}
+export interface IndexWorkspaceRepoResult {
+    readonly repo: string;
+    readonly repoPath: string;
+    /** `null` when this repository could not be read at all — not a git repository, or its config would not load. */
+    readonly commitSha: string | null;
+    readonly sources: readonly SourceRun[];
+    readonly sourcesFailed: readonly {
+        readonly module: string;
+        readonly reason: string;
+    }[];
+    readonly sourcesSkipped: readonly {
+        readonly source: string;
+        readonly reason: string;
+    }[];
+    readonly notes: readonly string[];
+    /** This repository's share of the one shared-store write this call made. */
+    readonly written: {
+        readonly nodes: number;
+        readonly edges: number;
+        readonly unresolved: number;
+        readonly evictedFiles: number;
+    };
+    /** Lowest resolution reached by a code-reading source in this repository, or 0 if none ran. */
+    readonly reachedResolution: number;
+}
+export interface IndexWorkspaceProgress {
+    readonly repo: string;
+    readonly phase: "detecting" | "emitting" | "history" | "merging" | "writing" | "done";
+    readonly completed: number;
+    readonly total: number;
+}
+export interface IndexWorkspaceOptions {
+    readonly workspaceId: string;
+    readonly repos: readonly IndexWorkspaceRepoInput[];
+    /** Where to open/create the shared store. Passed straight to `openStore`. */
+    readonly graphDbPath: string;
+    /** Default true, matching `analyze`'s own default. */
+    readonly includeHistory?: boolean;
+    readonly maxCommits?: number;
+    readonly onProgress?: (progress: IndexWorkspaceProgress) => void;
+    readonly signal?: AbortSignal;
+}
+export interface IndexWorkspaceResult {
+    readonly workspaceId: string;
+    readonly graphDbPath: string;
+    /** One entry per repository requested, in the order given — including one for a repository that could not be read at all. */
+    readonly repos: readonly IndexWorkspaceRepoResult[];
+    /** Row counts in the shared store after every repository has been indexed. */
+    readonly stored: StoreCounts;
+    /** The shared store's own stamp — `repoCount` here is the fact that this graph now spans more than one repository, not a staleness signal (`GraphStamp`'s own doc). `resolutionFloor` is this call's own, mirroring `analyze`'s (the minimum across every repository's code-reading sources; 0 if none ran anywhere). */
+    readonly stamp: GraphStamp;
+    readonly merge: {
+        readonly mergedNodes: number;
+        readonly mergedEdges: number;
+        readonly collisions: number;
+        readonly droppedEdges: number;
+        readonly rejections: number;
+    };
+    /** Per workspace-scoped node type: whether this call actually saw the join happen (DEC-054).
+     *  API_ENDPOINT is no longer one of these types (DEC-NEXT-endpoint-identity-repo-scoping) —
+     *  see `apiJoins` for its own, separate join accounting. */
+    readonly crossRepoJoins: BuildResult["crossRepoJoins"];
+    /** The staged frontend-to-backend API_ENDPOINT join (Gap 10,
+     *  `packages/core/src/contracts/workspace-join.ts`) — run once, after `buildGraph`, over the
+     *  whole merged workspace graph. */
+    readonly apiJoins: {
+        readonly resolved: readonly ResolvedApiJoin[];
+        readonly ambiguous: readonly AmbiguousApiJoin[];
+        readonly unmatched: number;
+        readonly unkeyed: number;
+    };
+    /** The staged cross-repo DATABASE_TABLE/DATABASE_COLUMN join (Gap 10's table
+     *  half, `packages/core/src/contracts/workspace-table-join.ts`) — run once,
+     *  after `buildGraph` and the API_ENDPOINT join, over the whole merged
+     *  workspace graph. */
+    readonly tableJoins: {
+        readonly resolved: readonly ResolvedTableJoin[];
+        readonly ambiguous: readonly AmbiguousTableJoin[];
+        readonly unkeyed: number;
+        readonly singletons: number;
+    };
+    readonly notes: readonly string[];
+}
+/**
+ * Index every repository in `options.repos` into one shared graph store at
+ * `options.graphDbPath`, creating it if absent.
+ *
+ * One repository failing to read — not a git repository, an unreadable
+ * config, every adapter refusing it — costs only its own rows; the others
+ * are still read, merged and persisted, the same "one adapter's failure
+ * costs its own rows and nothing else" posture `analyze.ts` already takes one
+ * level down.
+ */
+export declare function indexWorkspace(options: IndexWorkspaceOptions): Promise<IndexWorkspaceResult>;
+//# sourceMappingURL=workspace-index.d.ts.map

package/dist/workspace-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-index.d.ts","sourceRoot":"","sources":["../src/workspace-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAMH,OAAO,EAgBL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAA+D,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEjH,MAAM,WAAW,uBAAuB;IACtC,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iHAAiH;IACjH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxF,QAAQ,CAAC,cAAc,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzF,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF,+FAA+F;IAC/F,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IACtF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACnD,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6HAA6H;IAC7H,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACpD,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,yTAAyT;IACzT,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF;;gEAE4D;IAC5D,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC;IACvD;;wCAEoC;IACpC,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;QAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;QAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF;;;2BAGuB;IACvB,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;QAChD,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;QAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAiND;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA0JlG"}