@descryy/mcp 0.1.0

package/dist/tools/kit.js.map

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

package/dist/tools/link-workspace.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `link_workspace` — the agent-mediated door onto the same declaration
+ * `descry init` writes from the command line (§ session.ts's `writeConfig`,
+ * shared by both so there is one writer for one file).
+ *
+ * ## Why this exists as a tool and not a smarter `analyze`
+ *
+ * `analyze` already discloses "no workspace is configured" (DEC-054) and,
+ * until now, that disclosure was a dead end — true, and nowhere to go. This
+ * tool is where it goes: an agent that reads the disclosure can act on it in
+ * the same conversation, in plain English, rather than sending the developer
+ * to a terminal.
+ *
+ * ## The constraint that makes this legal
+ *
+ * `workspace.ts`'s header is explicit that a pairing between two directories
+ * is a name inference and this project does not make that inference. An
+ * agent that can see `sherpa-frontend` sitting next to `sherpa-backend` may
+ * **propose** it — that is a suggestion grounded in something real, a
+ * directory listing — but it must never **decide** the two belong together
+ * and call this tool unprompted. `repos` is not filled in by this tool from
+ * anything it can see; it is supplied by the caller, and the caller's own
+ * description is instructed to obtain that list from the user's explicit
+ * confirmation, not from its own inference. The tool has no way to verify
+ * that happened — the same trust boundary every write tool in this server
+ * already crosses when a client approves the call — so the discipline is
+ * enforced by what this tool refuses to do (guess) rather than by what it
+ * can check.
+ *
+ * ## The one tool in this server that writes outside its own session root
+ *
+ * Every other tool operates on `session.repoPath` alone. `repos` here names
+ * arbitrary paths on disk, because the whole point is writing into siblings
+ * the current session does not own. Each path is required to exist and be a
+ * directory before anything is written, and a path that fails that check is
+ * reported rather than silently skipped — a typo'd path here is exactly the
+ * kind of silent failure DEC-054 exists to prevent, one level up.
+ */
+import { type ToolDefinition } from "./kit.ts";
+/** A repository the workspace id was actually written into. */
+export interface LinkedRepo {
+    /** Resolved to absolute. */
+    readonly path: string;
+    readonly repo: string;
+    /** The `.descry/config.json` that was written. */
+    readonly configPath: string;
+}
+export interface LinkWorkspaceData {
+    readonly workspace: string;
+    /**
+     * Only the repositories actually written.
+     *
+     * A path that did not exist is **absent from this list and disclosed** — the
+     * workspace id is byte-identical only where it was written, and a partial
+     * link that looks complete is the failure this list exists to make visible.
+     */
+    readonly written: readonly LinkedRepo[];
+    /** How many were asked for. Compare against `written.length`. */
+    readonly requested: number;
+}
+export declare const linkWorkspaceTool: ToolDefinition;
+//# sourceMappingURL=link-workspace.d.ts.map

package/dist/tools/link-workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-workspace.d.ts","sourceRoot":"","sources":["../../src/tools/link-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAMH,OAAO,EAA4D,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAGzG,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AA6HD,eAAO,MAAM,iBAAiB,EAAE,cAe/B,CAAC"}

package/dist/tools/link-workspace.js

@@ -0,0 +1,156 @@
+/**
+ * `link_workspace` — the agent-mediated door onto the same declaration
+ * `descry init` writes from the command line (§ session.ts's `writeConfig`,
+ * shared by both so there is one writer for one file).
+ *
+ * ## Why this exists as a tool and not a smarter `analyze`
+ *
+ * `analyze` already discloses "no workspace is configured" (DEC-054) and,
+ * until now, that disclosure was a dead end — true, and nowhere to go. This
+ * tool is where it goes: an agent that reads the disclosure can act on it in
+ * the same conversation, in plain English, rather than sending the developer
+ * to a terminal.
+ *
+ * ## The constraint that makes this legal
+ *
+ * `workspace.ts`'s header is explicit that a pairing between two directories
+ * is a name inference and this project does not make that inference. An
+ * agent that can see `sherpa-frontend` sitting next to `sherpa-backend` may
+ * **propose** it — that is a suggestion grounded in something real, a
+ * directory listing — but it must never **decide** the two belong together
+ * and call this tool unprompted. `repos` is not filled in by this tool from
+ * anything it can see; it is supplied by the caller, and the caller's own
+ * description is instructed to obtain that list from the user's explicit
+ * confirmation, not from its own inference. The tool has no way to verify
+ * that happened — the same trust boundary every write tool in this server
+ * already crosses when a client approves the call — so the discipline is
+ * enforced by what this tool refuses to do (guess) rather than by what it
+ * can check.
+ *
+ * ## The one tool in this server that writes outside its own session root
+ *
+ * Every other tool operates on `session.repoPath` alone. `repos` here names
+ * arbitrary paths on disk, because the whole point is writing into siblings
+ * the current session does not own. Each path is required to exist and be a
+ * directory before anything is written, and a path that fails that check is
+ * reported rather than silently skipped — a typo'd path here is exactly the
+ * kind of silent failure DEC-054 exists to prevent, one level up.
+ */
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { writeConfig } from "../session.js";
+import { answer, requiredString, ToolInputError } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        workspace: {
+            type: "string",
+            description: "The workspace id to write into every repository listed in `repos`, byte-identical. " +
+                "Choose a short, stable name — it becomes part of every workspace-scoped node id.",
+        },
+        repos: {
+            type: "array",
+            minItems: 2,
+            items: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Absolute path to the repository on disk." },
+                    repo: {
+                        type: "string",
+                        description: "This repository's identity, written explicitly rather than defaulted.",
+                    },
+                },
+                required: ["path", "repo"],
+                additionalProperties: false,
+            },
+            description: "Every repository that should share this workspace, INCLUDING the current one if it should " +
+                "join. Only call this with repositories the user has explicitly confirmed belong together " +
+                "— a directory sitting next to another is a suggestion to put in front of the user, never " +
+                "a decision this tool or the caller makes on its own (workspace.ts's pairing rule, one " +
+                "level up: never infer, always declare).",
+        },
+    },
+    required: ["workspace", "repos"],
+    additionalProperties: false,
+};
+function parseRepos(value) {
+    if (!Array.isArray(value) || value.length < 2) {
+        throw new ToolInputError('"repos" must be an array of at least two {path, repo} entries — a workspace of one ' +
+            "repository joins nothing, so linking one is never the right call.");
+    }
+    return value.map((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            throw new ToolInputError(`repos[${index}] must be an object`);
+        }
+        const path = requiredString(entry, "path");
+        const repo = requiredString(entry, "repo");
+        return { path, repo };
+    });
+}
+async function run(args, ctx) {
+    const workspace = requiredString(args, "workspace");
+    const repos = parseRepos(args["repos"]);
+    const seen = new Set();
+    for (const entry of repos) {
+        const absolute = resolve(entry.path);
+        if (seen.has(absolute)) {
+            throw new ToolInputError(`"${entry.path}" is listed more than once`);
+        }
+        seen.add(absolute);
+    }
+    const written = [];
+    const notes = [];
+    for (const entry of repos) {
+        const absolute = resolve(entry.path);
+        if (!existsSync(absolute) || !statSync(absolute).isDirectory()) {
+            notes.push(`"${entry.path}" does not exist or is not a directory — nothing was written there.`);
+            continue;
+        }
+        ctx.progress(`Writing .descry/config.json in ${entry.repo}`, written.length, repos.length);
+        const result = await writeConfig(absolute, { repo: entry.repo, workspace });
+        written.push({ path: absolute, repo: entry.repo, configPath: result.path });
+        if (result.previousWorkspace !== undefined && result.previousWorkspace !== workspace) {
+            notes.push(`${entry.repo}: replaced previous workspace "${result.previousWorkspace}" with "${workspace}".`);
+        }
+    }
+    if (written.length < repos.length) {
+        notes.push(`${repos.length - written.length} of ${repos.length} repositories were skipped. The workspace ` +
+            "id is only byte-identical where it was actually written — re-run for the skipped paths " +
+            "once they are correct.");
+    }
+    notes.push(`Run "analyze" again in each linked repository so its graph is rebuilt under the "${workspace}" ` +
+        "workspace — writing the config here does not itself rebuild anything.");
+    return answer({
+        headline: written.length === 0
+            ? `No repository was linked — every path in "repos" failed to resolve.`
+            : `Linked ${written.length} of ${repos.length} repositor${repos.length === 1 ? "y" : "ies"} ` +
+                `to workspace "${workspace}".`,
+        state: written.length === 0 ? "refused" : "ok",
+        nameLevel: true,
+        // Writing a config file is not evidence about code, so there is no
+        // resolution to report — R0 rather than a cheerful default, the same
+        // choice `analyze` makes when no code-reading source ran.
+        resolutionFloor: 0,
+        commitSha: null,
+        graphBuiltAt: null,
+        irSchemaVersion: ctx.session.provider().baseStamp().irSchemaVersion,
+        notes,
+        data: { workspace, written, requested: repos.length },
+    });
+}
+export const linkWorkspaceTool = {
+    name: "link_workspace",
+    class: "stateful-read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Declare which repositories share a workspace",
+    description: "Write the workspace id that lets multiple repositories' graphs join (DEC-054) into each " +
+        "repository's .descry/config.json. Call this ONLY after the user has explicitly confirmed " +
+        "which repositories belong together — you may point out sibling directories you can see as a " +
+        "suggestion, but you must never decide on your own that they are related and call this " +
+        "unprompted. The same file `descry init` writes from the command line; this is the " +
+        "conversational door onto it.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=link-workspace.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"link-workspace.js","sourceRoot":"","sources":["../../src/tools/link-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,cAAc,EAAyC,MAAM,UAAU,CAAC;AA+BzG,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,SAAS,EAAE;YACT,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,qFAAqF;gBACrF,kFAAkF;SACrF;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,0CAA0C,EAAE;oBACjF,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,uEAAuE;qBACrF;iBACF;gBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;gBAC1B,oBAAoB,EAAE,KAAK;aAC5B;YACD,WAAW,EACT,4FAA4F;gBAC5F,2FAA2F;gBAC3F,2FAA2F;gBAC3F,wFAAwF;gBACxF,yCAAyC;SAC5C;KACF;IACD,QAAQ,EAAE,CAAC,WAAW,EAAE,OAAO,CAAC;IAChC,oBAAoB,EAAE,KAAK;CACnB,CAAC;AAEX,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,cAAc,CACtB,qFAAqF;YACnF,mEAAmE,CACtE,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,IAAI,cAAc,CAAC,SAAS,KAAK,qBAAqB,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,IAAI,GAAG,cAAc,CAAC,KAAgC,EAAE,MAAM,CAAC,CAAC;QACtE,MAAM,IAAI,GAAG,cAAc,CAAC,KAAgC,EAAE,MAAM,CAAC,CAAC;QACtE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,GAAG,CAAC,IAA6B,EAAE,GAAgB;IAChE,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAExC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,cAAc,CAAC,IAAI,KAAK,CAAC,IAAI,4BAA4B,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrB,CAAC;IAED,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YAC/D,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,qEAAqE,CAAC,CAAC;YAChG,SAAS;QACX,CAAC;QACD,GAAG,CAAC,QAAQ,CAAC,kCAAkC,KAAK,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAC5E,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5E,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;YACrF,KAAK,CAAC,IAAI,CACR,GAAG,KAAK,CAAC,IAAI,kCAAkC,MAAM,CAAC,iBAAiB,WAAW,SAAS,IAAI,CAChG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CACR,GAAG,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,KAAK,CAAC,MAAM,4CAA4C;YAC7F,yFAAyF;YACzF,wBAAwB,CAC3B,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI,CACR,oFAAoF,SAAS,IAAI;QAC/F,uEAAuE,CAC1E,CAAC;IAEF,OAAO,MAAM,CAAoB;QAC/B,QAAQ,EACN,OAAO,CAAC,MAAM,KAAK,CAAC;YAClB,CAAC,CAAC,qEAAqE;YACvE,CAAC,CAAC,UAAU,OAAO,CAAC,MAAM,OAAO,KAAK,CAAC,MAAM,aAAa,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG;gBAC3F,iBAAiB,SAAS,IAAI;QACpC,KAAK,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;QAC9C,SAAS,EAAE,IAAI;QACf,mEAAmE;QACnE,qEAAqE;QACrE,0DAA0D;QAC1D,eAAe,EAAE,CAAC;QAClB,SAAS,EAAE,IAAI;QACf,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,CAAC,eAAe;QACnE,KAAK;QACL,IAAI,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE;KACtD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAmB;IAC/C,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,eAAe;IACtB,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,8CAA8C;IACrD,WAAW,EACT,0FAA0F;QAC1F,2FAA2F;QAC3F,8FAA8F;QAC9F,wFAAwF;QACxF,oFAAoF;QACpF,8BAA8B;IAChC,WAAW,EAAE,MAA4C;IACzD,GAAG;CACJ,CAAC"}

package/dist/tools/lookup.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Turning what a developer typed into exactly one node — or refusing to.
+ *
+ * A developer says "the `charge` function"; the graph wants a node id. Two
+ * functions in one repository can legitimately be called `charge`, and the
+ * tempting move — take the first row, or the one with the most edges — is how a
+ * tool ends up answering confidently about the wrong symbol. There is no signal
+ * available here that distinguishes them; picking would be inventing one.
+ *
+ * So ambiguity is returned, with the candidates, and the caller is told how to
+ * narrow it. That is the same discipline the graph builder applies to an
+ * unresolvable edge (never stub a node) and the adapters apply to an unreadable
+ * receiver (ledger row, never a guess), arriving at the interaction layer.
+ */
+import type { IRNode } from "@descryy/ir";
+import type { Session } from "../session.ts";
+export interface Lookup {
+    /** Null when nothing matched, or when more than one thing did. */
+    readonly node: IRNode | null;
+    readonly candidates: readonly IRNode[];
+    readonly headline: string;
+    readonly notes: readonly string[];
+}
+export declare function resolveOneNode(session: Session, criteria: {
+    readonly nodeId?: string | undefined;
+    readonly symbol?: string | undefined;
+    readonly file?: string | undefined;
+}): Lookup;
+//# sourceMappingURL=lookup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../src/tools/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,MAAM,WAAW,MAAM;IACrB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE;IACR,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC,GACA,MAAM,CA+DR"}

package/dist/tools/lookup.js

@@ -0,0 +1,73 @@
+/**
+ * Turning what a developer typed into exactly one node — or refusing to.
+ *
+ * A developer says "the `charge` function"; the graph wants a node id. Two
+ * functions in one repository can legitimately be called `charge`, and the
+ * tempting move — take the first row, or the one with the most edges — is how a
+ * tool ends up answering confidently about the wrong symbol. There is no signal
+ * available here that distinguishes them; picking would be inventing one.
+ *
+ * So ambiguity is returned, with the candidates, and the caller is told how to
+ * narrow it. That is the same discipline the graph builder applies to an
+ * unresolvable edge (never stub a node) and the adapters apply to an unreadable
+ * receiver (ledger row, never a guess), arriving at the interaction layer.
+ */
+import { findNodes, getNode } from "@descryy/core";
+export function resolveOneNode(session, criteria) {
+    const driver = session.store().driver;
+    if (criteria.nodeId !== undefined) {
+        const node = getNode(driver, criteria.nodeId);
+        return node === undefined
+            ? {
+                node: null,
+                candidates: [],
+                headline: `No node with id ${criteria.nodeId} is in the graph.`,
+                notes: [
+                    "The id may be from an older graph. Node ids are hashes over the repository scope, " +
+                        "kind and qualified symbol path, so they survive file moves but not a change to the " +
+                        "configured repository name. Run analyze and use an id from its output.",
+                ],
+            }
+            : { node, candidates: [node], headline: node.name, notes: [] };
+    }
+    const matches = findNodes(driver, {
+        ...(criteria.symbol === undefined ? {} : { name: criteria.symbol }),
+        ...(criteria.file === undefined ? {} : { file: criteria.file }),
+    });
+    const named = criteria.symbol ?? criteria.file ?? "";
+    if (matches.length === 0) {
+        return {
+            node: null,
+            candidates: [],
+            headline: `Nothing named "${named}" is in the graph.`,
+            notes: [
+                "This does not mean it does not exist. It means no configured adapter read it, or the " +
+                    "graph predates it. Run analyze, and check its disclosures for languages that were not " +
+                    "analysable.",
+            ],
+        };
+    }
+    if (matches.length === 1) {
+        return { node: matches[0], candidates: matches, headline: matches[0].name, notes: [] };
+    }
+    // More than one. Only a file narrows it, and only if the caller did not already
+    // give one — in which case the file genuinely declares two things of that name.
+    const where = matches
+        .slice(0, 8)
+        .map((m) => `${m.type} ${m.name}${m.file === null ? "" : ` (${m.file})`}`)
+        .join(", ");
+    return {
+        node: null,
+        candidates: matches,
+        headline: `"${named}" is ambiguous — ${matches.length} nodes match.`,
+        notes: [
+            `Candidates: ${where}${matches.length > 8 ? ", …" : ""}. ` +
+                (criteria.file === undefined
+                    ? 'Narrow it with "file", or pass "nodeId" directly.'
+                    : "They are in the same file, so pass \"nodeId\" directly."),
+            "No answer was computed. Choosing one of these by a heuristic would produce a confident " +
+                "answer about a symbol you did not ask about.",
+        ],
+    };
+}
+//# sourceMappingURL=lookup.js.map

package/dist/tools/lookup.js.map

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

package/dist/tools/pr-analysis.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `pr-analysis` — "what should I test before I open this PR?"
+ *
+ * The blast radius of a diff, intersected with the tests that cover it. The
+ * useful half of the answer is the second list: **what is affected and has no
+ * covering test.** A green suite proves nothing about that set, and it is the
+ * only part of a PR review that a test run cannot supply.
+ *
+ * ## `base...head`, three dots
+ *
+ * `changedFiles` diffs against the merge base rather than the two tips. On a
+ * branch a week behind `main`, two dots would fold every change made on `main`
+ * since the branch point into "this PR", and the blast radius would belong to
+ * somebody else's work. This is stated here as well as at the git call because
+ * it is the kind of thing that gets "simplified" later.
+ *
+ * ## Absence of a test is not evidence of absence
+ *
+ * `TESTS` edges come from adapters, and every adapter's recall is below 100% by
+ * design — precision over recall, when in doubt omit the edge. So "no covering
+ * test" means "no test that this graph can link", and the difference is
+ * disclosed. Reporting the untested list without it would turn a measured recall
+ * gap into a confident accusation.
+ */
+import { type BriefNode, type ToolDefinition } from "./kit.ts";
+/** A node in the change's blast radius. */
+export interface AffectedNode extends BriefNode {
+    readonly score: number;
+    readonly depth: number;
+}
+/** Shared by every branch: what was diffed, and what came out of git. */
+export interface PrAnalysisRange {
+    readonly base: string;
+    readonly head: string;
+    /** Paths in `base...head` — three dots, so somebody else's work on base is not folded in. */
+    readonly files: readonly string[];
+}
+/**
+ * git rejected the range, so nothing downstream ran.
+ *
+ * The narrowest of the four shapes, and the tell is what is absent: no
+ * `missing`, because no path was ever looked up. Narrow on `!("affected" in data)`.
+ */
+export type PrAnalysisGitFailure = PrAnalysisRange;
+/**
+ * The diff is empty. A real answer: there is nothing to assess.
+ *
+ * The three lists are present and empty on purpose — the absence here **is**
+ * a fact about the change. No `missing`, because there was nothing to resolve.
+ */
+export interface PrAnalysisEmptyDiff extends PrAnalysisRange {
+    readonly affected: readonly AffectedNode[];
+    readonly untested: readonly BriefNode[];
+    readonly tests: readonly BriefNode[];
+}
+/**
+ * The diff resolved to no graph node at all, so no blast radius was computed.
+ *
+ * Distinguished from `PrAnalysisEmptyDiff` by `missing`, which names every
+ * path the graph has never heard of. The empty lists here mean *nothing was
+ * examined* rather than *nothing is affected*.
+ */
+export interface PrAnalysisUnresolved extends PrAnalysisEmptyDiff {
+    readonly missing: readonly string[];
+}
+/**
+ * The full answer.
+ *
+ * `untested` is the half a test run cannot supply, and it means *no test is
+ * linked to the node in this graph* — adapters omit an edge they cannot prove,
+ * so a genuinely covered symbol can appear here. A gap to check, never a
+ * proven hole. Narrow on `"changedSymbols" in data`.
+ */
+export interface PrAnalysisReport extends PrAnalysisRange {
+    readonly missing: readonly string[];
+    readonly changedSymbols: number;
+    readonly affectedTotal: number;
+    /** Capped by `limit`. */
+    readonly affected: readonly AffectedNode[];
+    readonly untestedTotal: number;
+    /** Capped by `limit`. */
+    readonly untested: readonly BriefNode[];
+    /** Capped by `limit`. */
+    readonly tests: readonly BriefNode[];
+    readonly testsTotal: number;
+}
+export type PrAnalysisData = PrAnalysisGitFailure | PrAnalysisEmptyDiff | PrAnalysisUnresolved | PrAnalysisReport;
+export declare const prAnalysisTool: ToolDefinition;
+//# sourceMappingURL=pr-analysis.d.ts.map

package/dist/tools/pr-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-analysis.d.ts","sourceRoot":"","sources":["../../src/tools/pr-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,EAOL,KAAK,SAAS,EAEd,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAGlB,2CAA2C;AAC3C,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,eAAe,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;IACxC,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,cAAc,GACtB,oBAAoB,GACpB,mBAAmB,GACnB,oBAAoB,GACpB,gBAAgB,CAAC;AA0JrB,eAAO,MAAM,cAAc,EAAE,cAa5B,CAAC"}

package/dist/tools/pr-analysis.js

@@ -0,0 +1,169 @@
+/**
+ * `pr-analysis` — "what should I test before I open this PR?"
+ *
+ * The blast radius of a diff, intersected with the tests that cover it. The
+ * useful half of the answer is the second list: **what is affected and has no
+ * covering test.** A green suite proves nothing about that set, and it is the
+ * only part of a PR review that a test run cannot supply.
+ *
+ * ## `base...head`, three dots
+ *
+ * `changedFiles` diffs against the merge base rather than the two tips. On a
+ * branch a week behind `main`, two dots would fold every change made on `main`
+ * since the branch point into "this PR", and the blast radius would belong to
+ * somebody else's work. This is stated here as well as at the git call because
+ * it is the kind of thing that gets "simplified" later.
+ *
+ * ## Absence of a test is not evidence of absence
+ *
+ * `TESTS` edges come from adapters, and every adapter's recall is below 100% by
+ * design — precision over recall, when in doubt omit the edge. So "no covering
+ * test" means "no test that this graph can link", and the difference is
+ * disclosed. Reporting the untested list without it would turn a measured recall
+ * gap into a confident accusation.
+ */
+import { changedFiles, changeRisk, NODE_BUDGETS, nodesInFiles } from "@descryy/core";
+import { answer, briefNode, optionalEnum, optionalInteger, optionalString, requiredString, } from "./kit.js";
+const TRIGGERS = ["pre-push", "pr", "nightly"];
+const SCHEMA = {
+    type: "object",
+    properties: {
+        base: {
+            type: "string",
+            description: "The branch or commit this change is measured against, e.g. \"main\" or \"origin/main\". " +
+                "Required — there is no defensible default, and guessing one silently changes the diff.",
+        },
+        head: { type: "string", description: "The tip being reviewed. Default HEAD." },
+        trigger: {
+            type: "string",
+            enum: [...TRIGGERS],
+            description: "Node budget to use. Default pr (1000).",
+        },
+        limit: { type: "integer", minimum: 1, description: "Cap on nodes per list. Default 50." },
+    },
+    required: ["base"],
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    // Required rather than defaulted: there is no defensible default base, and
+    // guessing one would silently change which diff the whole answer describes.
+    const base = requiredString(args, "base");
+    const head = optionalString(args, "head") ?? "HEAD";
+    const trigger = optionalEnum(args, "trigger", TRIGGERS) ?? "pr";
+    const limit = optionalInteger(args, "limit", 1) ?? 50;
+    const session = ctx.session;
+    const stamp = session.provider().baseStamp();
+    ctx.progress(`Diffing ${base}...${head}`);
+    let files;
+    try {
+        files = await changedFiles(session.repoPath, base, head);
+    }
+    catch (error) {
+        return answer({
+            headline: `Could not diff ${base}...${head}.`,
+            state: "refused",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: stamp.commitSha,
+            graphBuiltAt: stamp.graphBuiltAt,
+            irSchemaVersion: stamp.irSchemaVersion,
+            notes: [
+                `git rejected the range: ${error.message.trim()}. Check that "${base}" exists ` +
+                    "locally — a shallow clone or a missing fetch is the usual cause.",
+            ],
+            data: { base, head, files: [] },
+        });
+    }
+    const notes = [];
+    if (files.length === 0) {
+        return answer({
+            headline: `${base}...${head} changes no files.`,
+            nameLevel: true,
+            resolutionFloor: 4,
+            commitSha: stamp.commitSha,
+            graphBuiltAt: stamp.graphBuiltAt,
+            irSchemaVersion: stamp.irSchemaVersion,
+            notes: ["An empty diff is a real answer: there is nothing to assess."],
+            data: { base, head, files: [], affected: [], untested: [], tests: [] },
+        });
+    }
+    ctx.progress(`Resolving ${files.length} changed file(s)`, 1, 3);
+    const { nodes, missing } = nodesInFiles(session.store().driver, files);
+    if (missing.length > 0) {
+        notes.push(`${missing.length} of ${files.length} changed file(s) have no node in the graph ` +
+            `(${missing.slice(0, 5).join(", ")}${missing.length > 5 ? ", …" : ""}). They are outside ` +
+            "what any configured adapter reads, or the graph predates them. Their impact is absent " +
+            "from this analysis and they are not being reported as safe.");
+    }
+    if (nodes.length === 0) {
+        return answer({
+            headline: `None of the ${files.length} changed file(s) are in the graph.`,
+            state: "refused",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: stamp.commitSha,
+            graphBuiltAt: stamp.graphBuiltAt,
+            irSchemaVersion: stamp.irSchemaVersion,
+            notes: [
+                ...notes,
+                "No blast radius was computed. Run analyze first; if it has already run, its disclosures " +
+                    "name the languages and paths it could not read.",
+            ],
+            data: { base, head, files, missing, affected: [], untested: [], tests: [] },
+        });
+    }
+    ctx.progress(`Assessing ${nodes.length} changed symbol(s)`, 2, 3);
+    // `changeRisk` takes a raw node budget rather than a trigger: the trigger is a
+    // scoping concept and the query layer deliberately does not know about it.
+    // Translating here keeps the tool's vocabulary the developer's ("this is a
+    // PR") and the engine's its own.
+    const risk = changeRisk(session.provider(), nodes.map((n) => n.id), { budget: NODE_BUDGETS[trigger] });
+    notes.push("\"Untested\" means no test is linked to the node in this graph. Adapters omit an edge they " +
+        "cannot prove, so a genuinely covered symbol can appear here — treat it as a gap to check, " +
+        "not as a proven hole.");
+    const untested = risk.data.untested;
+    const affected = risk.data.affected.filter((entry) => entry.node.type !== "TEST_CASE");
+    ctx.progress("Done", 3, 3);
+    return {
+        result: {
+            ...risk,
+            data: {
+                base,
+                head,
+                files,
+                missing,
+                changedSymbols: nodes.length,
+                affectedTotal: affected.length,
+                affected: affected.slice(0, limit).map((entry) => ({
+                    ...briefNode(entry.node),
+                    score: Number(entry.score.toFixed(4)),
+                    depth: entry.depth,
+                })),
+                untestedTotal: untested.length,
+                untested: untested.slice(0, limit).map(briefNode),
+                tests: risk.data.tests.slice(0, limit).map(briefNode),
+                testsTotal: risk.data.tests.length,
+            },
+            notes: [...risk.notes, ...notes],
+        },
+        ...(affected.length === 0 ? { state: "empty" } : {}),
+        nameLevel: true,
+        headline: `${nodes.length} changed symbol(s) across ${files.length} file(s) affect ${affected.length} ` +
+            `other node(s). ${risk.data.tests.length} test(s) cover part of that; ${untested.length} ` +
+            "affected node(s) have no covering test in the graph.",
+    };
+}
+export const prAnalysisTool = {
+    name: "pr_analysis",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "What this change affects, and what is not covered",
+    description: "Diff a branch against its merge base, compute the blast radius of the change, and split it " +
+        "into what existing tests cover and what they do not. The uncovered list is the point: a " +
+        "passing suite says nothing about it. Files outside what the adapters read are named rather " +
+        "than counted as safe.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=pr-analysis.js.map

package/dist/tools/pr-analysis.js.map

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