patchwork-os 0.2.0-alpha.0

package/dist/tools/enrichCommit.js

@@ -0,0 +1,201 @@
+import { runGitStdout } from "./git-utils.js";
+import { GH_NOT_AUTHED, isNotAuthed, isNotFound } from "./github/shared.js";
+import { classifyIssueLink, extractIssueRefs } from "./issueRefs.js";
+import { error, execSafe, optionalString, successStructured } from "./utils.js";
+/**
+ * Fetch a single issue via `gh issue view --json`. Returns `null` if the
+ * issue doesn't exist (not an auth error) — callers treat missing issues
+ * as unresolved, not fatal.
+ */
+async function fetchIssue(workspace, number, signal) {
+    const result = await execSafe("gh", [
+        "issue",
+        "view",
+        number,
+        "--json",
+        "number,title,state,url,labels,assignees",
+    ], { cwd: workspace, signal, timeout: 30_000 });
+    if (result.exitCode === 0) {
+        try {
+            return { ok: true, issue: JSON.parse(result.stdout.trim()) };
+        }
+        catch {
+            return {
+                ok: false,
+                reason: "error",
+                detail: `parse failed: ${result.stdout.trim().slice(0, 200)}`,
+            };
+        }
+    }
+    const msg = result.stderr.trim() || result.stdout.trim();
+    if (isNotAuthed(msg))
+        return { ok: false, reason: "not_authed", detail: msg };
+    if (isNotFound(msg) || /not found|could not resolve/i.test(msg)) {
+        return { ok: false, reason: "not_found", detail: msg };
+    }
+    return { ok: false, reason: "error", detail: msg };
+}
+export function createEnrichCommitTool(workspace, linkLog) {
+    return {
+        schema: {
+            name: "enrichCommit",
+            description: "Enrich commit w/ linked issues. Parses #N / GH-N refs from message, fetches issue state via gh, classifies close vs ref. Missing issues flagged unresolved — not errors.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    ref: {
+                        type: "string",
+                        description: "Commit SHA or ref. Defaults to HEAD. Passed through to `git show`.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    sha: { type: "string" },
+                    subject: { type: "string" },
+                    author: { type: "string" },
+                    date: { type: "string" },
+                    issueRefs: { type: "array", items: { type: "string" } },
+                    links: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                ref: { type: "string" },
+                                linkType: { type: "string", enum: ["closes", "references"] },
+                                resolved: { type: "boolean" },
+                                issue: { type: ["object", "null"] },
+                                reason: { type: ["string", "null"] },
+                            },
+                            required: ["ref", "linkType", "resolved"],
+                        },
+                    },
+                    unresolved: { type: "integer" },
+                    ghAvailable: { type: "boolean" },
+                },
+                required: [
+                    "sha",
+                    "subject",
+                    "issueRefs",
+                    "links",
+                    "unresolved",
+                    "ghAvailable",
+                ],
+            },
+        },
+        timeoutMs: 45_000,
+        async handler(args, signal) {
+            const ref = optionalString(args, "ref") ?? "HEAD";
+            // Verify git repo
+            const check = await execSafe("git", ["rev-parse", "--git-dir"], {
+                cwd: workspace,
+                signal,
+                timeout: 5_000,
+            });
+            if (check.exitCode !== 0)
+                return error("Not a git repository");
+            let showOut;
+            try {
+                showOut = await runGitStdout([
+                    "show",
+                    "--no-patch",
+                    "--format=%H%n%an <%ae>%n%aI%n%s%n---BODY---%n%B",
+                    ref,
+                ], workspace, { signal, timeout: 10_000 });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return error(`Failed to read commit '${ref}': ${msg}`);
+            }
+            const [metaPart, bodyPart = ""] = showOut.split("\n---BODY---\n", 2);
+            const metaLines = (metaPart ?? "").split("\n");
+            const sha = metaLines[0] ?? "";
+            const author = metaLines[1] ?? "";
+            const date = metaLines[2] ?? "";
+            const subject = metaLines[3] ?? "";
+            const fullMessage = bodyPart.trim() || subject;
+            const issueRefs = extractIssueRefs(fullMessage);
+            // Probe gh availability once — if the tool is missing, skip all fetches.
+            const probe = await execSafe("gh", ["--version"], {
+                cwd: workspace,
+                signal,
+                timeout: 5_000,
+            });
+            const ghAvailable = probe.exitCode === 0;
+            const links = [];
+            let unresolved = 0;
+            for (const r of issueRefs) {
+                const linkType = classifyIssueLink(fullMessage, r);
+                const recordLink = (resolved, issue, reason) => {
+                    if (!linkLog || !sha)
+                        return;
+                    linkLog.record({
+                        sha,
+                        ref: r,
+                        linkType,
+                        resolved,
+                        workspace,
+                        ...(subject && { subject }),
+                        ...(typeof issue?.state === "string" && {
+                            issueState: issue.state,
+                        }),
+                        ...(typeof issue?.title === "string" && {
+                            issueTitle: issue.title,
+                        }),
+                        ...(reason !== null && { reason }),
+                    });
+                };
+                if (!ghAvailable) {
+                    links.push({
+                        ref: r,
+                        linkType,
+                        resolved: false,
+                        issue: null,
+                        reason: "gh_unavailable",
+                    });
+                    unresolved += 1;
+                    recordLink(false, null, "gh_unavailable");
+                    continue;
+                }
+                const num = r.replace(/^#/, "");
+                const fetched = await fetchIssue(workspace, num, signal);
+                if (fetched.ok) {
+                    links.push({
+                        ref: r,
+                        linkType,
+                        resolved: true,
+                        issue: fetched.issue,
+                        reason: null,
+                    });
+                    recordLink(true, fetched.issue, null);
+                }
+                else {
+                    const reason = fetched.reason === "not_authed" ? GH_NOT_AUTHED : fetched.reason;
+                    links.push({
+                        ref: r,
+                        linkType,
+                        resolved: false,
+                        issue: null,
+                        reason,
+                    });
+                    unresolved += 1;
+                    recordLink(false, null, reason);
+                }
+            }
+            return successStructured({
+                sha,
+                subject,
+                author,
+                date,
+                issueRefs,
+                links,
+                unresolved,
+                ghAvailable,
+            });
+        },
+    };
+}
+//# sourceMappingURL=enrichCommit.js.map

package/dist/tools/enrichCommit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichCommit.js","sourceRoot":"","sources":["../../src/tools/enrichCommit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEhF;;;;GAIG;AACH,KAAK,UAAU,UAAU,CACvB,SAAiB,EACjB,MAAc,EACd,MAAoB;IAKpB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAC3B,IAAI,EACJ;QACE,OAAO;QACP,MAAM;QACN,MAAM;QACN,QAAQ;QACR,yCAAyC;KAC1C,EACD,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAC5C,CAAC;IACF,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,OAAO;gBACf,MAAM,EAAE,iBAAiB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;aAC9D,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACzD,IAAI,WAAW,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IAC9E,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,8BAA8B,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IACzD,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,SAAiB,EACjB,OAA4B;IAE5B,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,cAAc;YACpB,WAAW,EACT,0KAA0K;YAC5K,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;YACnC,WAAW,EAAE;gBACX,IAAI,EAAE,QAAiB;gBACvB,UAAU,EAAE;oBACV,GAAG,EAAE;wBACH,IAAI,EAAE,QAAQ;wBACd,WAAW,EACT,oEAAoE;qBACvE;iBACF;gBACD,oBAAoB,EAAE,KAAc;aACrC;YACD,YAAY,EAAE;gBACZ,IAAI,EAAE,QAAiB;gBACvB,UAAU,EAAE;oBACV,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACvB,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBAC3B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACxB,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;oBACvD,KAAK,EAAE;wBACL,IAAI,EAAE,OAAO;wBACb,KAAK,EAAE;4BACL,IAAI,EAAE,QAAQ;4BACd,UAAU,EAAE;gCACV,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gCACvB,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,EAAE;gCAC5D,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;gCAC7B,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE;gCACnC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE;6BACrC;4BACD,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,CAAC;yBAC1C;qBACF;oBACD,UAAU,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;oBAC/B,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;iBACjC;gBACD,QAAQ,EAAE;oBACR,KAAK;oBACL,SAAS;oBACT,WAAW;oBACX,OAAO;oBACP,YAAY;oBACZ,aAAa;iBACd;aACF;SACF;QACD,SAAS,EAAE,MAAM;QACjB,KAAK,CAAC,OAAO,CAAC,IAA6B,EAAE,MAAoB;YAC/D,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC;YAElD,kBAAkB;YAClB,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE;gBAC9D,GAAG,EAAE,SAAS;gBACd,MAAM;gBACN,OAAO,EAAE,KAAK;aACf,CAAC,CAAC;YACH,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC,sBAAsB,CAAC,CAAC;YAE/D,IAAI,OAAe,CAAC;YACpB,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,YAAY,CAC1B;oBACE,MAAM;oBACN,YAAY;oBACZ,iDAAiD;oBACjD,GAAG;iBACJ,EACD,SAAS,EACT,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAC5B,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC7D,OAAO,KAAK,CAAC,0BAA0B,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC;YACzD,CAAC;YAED,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;YACrE,MAAM,SAAS,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC/C,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAChC,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,OAAO,CAAC;YAE/C,MAAM,SAAS,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;YAEhD,yEAAyE;YACzE,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE;gBAChD,GAAG,EAAE,SAAS;gBACd,MAAM;gBACN,OAAO,EAAE,KAAK;aACf,CAAC,CAAC;YACH,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,KAAK,CAAC,CAAC;YAEzC,MAAM,KAAK,GAAmC,EAAE,CAAC;YACjD,IAAI,UAAU,GAAG,CAAC,CAAC;YAEnB,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;gBAC1B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;gBACnD,MAAM,UAAU,GAAG,CACjB,QAAiB,EACjB,KAAqC,EACrC,MAAqB,EACrB,EAAE;oBACF,IAAI,CAAC,OAAO,IAAI,CAAC,GAAG;wBAAE,OAAO;oBAC7B,OAAO,CAAC,MAAM,CAAC;wBACb,GAAG;wBACH,GAAG,EAAE,CAAC;wBACN,QAAQ;wBACR,QAAQ;wBACR,SAAS;wBACT,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;wBAC3B,GAAG,CAAC,OAAO,KAAK,EAAE,KAAK,KAAK,QAAQ,IAAI;4BACtC,UAAU,EAAE,KAAK,CAAC,KAAK;yBACxB,CAAC;wBACF,GAAG,CAAC,OAAO,KAAK,EAAE,KAAK,KAAK,QAAQ,IAAI;4BACtC,UAAU,EAAE,KAAK,CAAC,KAAK;yBACxB,CAAC;wBACF,GAAG,CAAC,MAAM,KAAK,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;qBACnC,CAAC,CAAC;gBACL,CAAC,CAAC;gBAEF,IAAI,CAAC,WAAW,EAAE,CAAC;oBACjB,KAAK,CAAC,IAAI,CAAC;wBACT,GAAG,EAAE,CAAC;wBACN,QAAQ;wBACR,QAAQ,EAAE,KAAK;wBACf,KAAK,EAAE,IAAI;wBACX,MAAM,EAAE,gBAAgB;qBACzB,CAAC,CAAC;oBACH,UAAU,IAAI,CAAC,CAAC;oBAChB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC;oBAC1C,SAAS;gBACX,CAAC;gBACD,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAChC,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;gBACzD,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC;oBACf,KAAK,CAAC,IAAI,CAAC;wBACT,GAAG,EAAE,CAAC;wBACN,QAAQ;wBACR,QAAQ,EAAE,IAAI;wBACd,KAAK,EAAE,OAAO,CAAC,KAAK;wBACpB,MAAM,EAAE,IAAI;qBACb,CAAC,CAAC;oBACH,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;gBACxC,CAAC;qBAAM,CAAC;oBACN,MAAM,MAAM,GACV,OAAO,CAAC,MAAM,KAAK,YAAY,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;oBACnE,KAAK,CAAC,IAAI,CAAC;wBACT,GAAG,EAAE,CAAC;wBACN,QAAQ;wBACR,QAAQ,EAAE,KAAK;wBACf,KAAK,EAAE,IAAI;wBACX,MAAM;qBACP,CAAC,CAAC;oBACH,UAAU,IAAI,CAAC,CAAC;oBAChB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;gBAClC,CAAC;YACH,CAAC;YAED,OAAO,iBAAiB,CAAC;gBACvB,GAAG;gBACH,OAAO;gBACP,MAAM;gBACN,IAAI;gBACJ,SAAS;gBACT,KAAK;gBACL,UAAU;gBACV,WAAW;aACZ,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/enrichStackTrace.d.ts

@@ -0,0 +1,121 @@
+export declare function createEnrichStackTraceTool(workspace: string): {
+    schema: {
+        name: string;
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+        };
+        inputSchema: {
+            type: "object";
+            required: string[];
+            properties: {
+                stackTrace: {
+                    type: string;
+                    description: string;
+                    maxLength: number;
+                };
+                maxFrames: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                };
+            };
+            additionalProperties: false;
+        };
+        outputSchema: {
+            type: "object";
+            properties: {
+                frames: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            file: {
+                                type: string;
+                            };
+                            line: {
+                                type: string;
+                            };
+                            column: {
+                                type: string[];
+                            };
+                            function: {
+                                type: string[];
+                            };
+                            language: {
+                                type: string;
+                            };
+                            inWorkspace: {
+                                type: string;
+                            };
+                            resolvedPath: {
+                                type: string[];
+                            };
+                            commit: {
+                                type: string[];
+                                properties: {
+                                    sha: {
+                                        type: string;
+                                    };
+                                    author: {
+                                        type: string;
+                                    };
+                                    date: {
+                                        type: string;
+                                    };
+                                    subject: {
+                                        type: string;
+                                    };
+                                };
+                            };
+                        };
+                        required: string[];
+                    };
+                };
+                topSuspect: {
+                    type: string[];
+                    properties: {
+                        sha: {
+                            type: string;
+                        };
+                        author: {
+                            type: string;
+                        };
+                        date: {
+                            type: string;
+                        };
+                        subject: {
+                            type: string;
+                        };
+                        frameCount: {
+                            type: string;
+                        };
+                    };
+                };
+                confidence: {
+                    type: string;
+                    enum: string[];
+                };
+                framesParsed: {
+                    type: string;
+                };
+                framesBlamed: {
+                    type: string;
+                };
+                gitAvailable: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    timeoutMs: number;
+    handler(args: Record<string, unknown>, signal?: AbortSignal): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        structuredContent: unknown;
+    }>;
+};

package/dist/tools/enrichStackTrace.js

@@ -0,0 +1,194 @@
+import { createBlameResolver } from "./blame-utils.js";
+import { runGitStdout } from "./git-utils.js";
+import { parseStackTrace, resolveFrameFile, } from "./stackTraceParser.js";
+import { execSafe, optionalInt, requireString, successStructured, } from "./utils.js";
+/**
+ * Fetch minimal commit metadata for display. Returns `null` if the commit
+ * can't be read (unknown sha, shallow clone, git missing).
+ */
+async function fetchCommitMeta(workspace, sha, signal) {
+    try {
+        const out = await runGitStdout(["show", "--no-patch", "--format=%H%n%an <%ae>%n%aI%n%s", sha], workspace, { signal, timeout: 5_000 });
+        const [fullSha, author, date, subject] = out.split("\n");
+        if (!fullSha)
+            return null;
+        return {
+            sha: fullSha,
+            author: author ?? "",
+            date: date ?? "",
+            subject: subject ?? "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Classify overall confidence in the top suspect:
+ *   high   — top frame blamed, >=2 frames agree on the same commit
+ *   medium — top frame blamed, other frames blamed to different commits
+ *   low    — top frame not blamed (outside workspace / uncommitted)
+ */
+function scoreConfidence(topShaResolved, uniqueShas, topSha) {
+    if (!topShaResolved || !topSha)
+        return "low";
+    const topAgreements = uniqueShas.filter((s) => s === topSha).length;
+    if (topAgreements >= 2)
+        return "high";
+    return "medium";
+}
+export function createEnrichStackTraceTool(workspace) {
+    return {
+        schema: {
+            name: "enrichStackTrace",
+            description: "Map stack-trace frames to introducing commits via git blame. Parses Node/Python/browser traces, filters to in-workspace files, returns per-frame commit + overall top suspect.",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                required: ["stackTrace"],
+                properties: {
+                    stackTrace: {
+                        type: "string",
+                        description: "Full stack trace text. Multi-line; any language.",
+                        maxLength: 64_000,
+                    },
+                    maxFrames: {
+                        type: "integer",
+                        minimum: 1,
+                        maximum: 50,
+                        description: "Max frames to blame. Default 10. Top-of-stack first.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    frames: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                file: { type: "string" },
+                                line: { type: "integer" },
+                                column: { type: ["integer", "null"] },
+                                function: { type: ["string", "null"] },
+                                language: { type: "string" },
+                                inWorkspace: { type: "boolean" },
+                                resolvedPath: { type: ["string", "null"] },
+                                commit: {
+                                    type: ["object", "null"],
+                                    properties: {
+                                        sha: { type: "string" },
+                                        author: { type: "string" },
+                                        date: { type: "string" },
+                                        subject: { type: "string" },
+                                    },
+                                },
+                            },
+                            required: ["file", "line", "language", "inWorkspace"],
+                        },
+                    },
+                    topSuspect: {
+                        type: ["object", "null"],
+                        properties: {
+                            sha: { type: "string" },
+                            author: { type: "string" },
+                            date: { type: "string" },
+                            subject: { type: "string" },
+                            frameCount: { type: "integer" },
+                        },
+                    },
+                    confidence: {
+                        type: "string",
+                        enum: ["high", "medium", "low"],
+                    },
+                    framesParsed: { type: "integer" },
+                    framesBlamed: { type: "integer" },
+                    gitAvailable: { type: "boolean" },
+                },
+                required: [
+                    "frames",
+                    "confidence",
+                    "framesParsed",
+                    "framesBlamed",
+                    "gitAvailable",
+                ],
+            },
+        },
+        timeoutMs: 30_000,
+        async handler(args, signal) {
+            const stackTrace = requireString(args, "stackTrace", 64_000);
+            const maxFrames = optionalInt(args, "maxFrames", 1, 50) ?? 10;
+            // Verify git repo up front so we return a meaningful `gitAvailable`.
+            const check = await execSafe("git", ["rev-parse", "--git-dir"], {
+                cwd: workspace,
+                signal,
+                timeout: 5_000,
+            });
+            const gitAvailable = check.exitCode === 0;
+            const parsed = parseStackTrace(stackTrace);
+            const framesParsed = parsed.length;
+            const toConsider = parsed.slice(0, maxFrames);
+            const resolver = createBlameResolver(workspace);
+            const blameShaByIndex = new Array(toConsider.length);
+            if (gitAvailable) {
+                // Blame sequentially — top-of-stack first. The cache inside
+                // createBlameResolver makes repeat frames on the same file+line
+                // free, so this is already cheap for the typical case.
+                for (let i = 0; i < toConsider.length; i += 1) {
+                    const frame = toConsider[i];
+                    const resolved = resolveFrameFile(workspace, frame.file);
+                    if (!resolved)
+                        continue;
+                    const sha = await resolver.getIntroducedByCommit(resolved, frame.line);
+                    if (sha)
+                        blameShaByIndex[i] = sha;
+                }
+            }
+            const uniqueShas = Array.from(new Set(blameShaByIndex.filter((s) => typeof s === "string")));
+            const commitMetaCache = new Map();
+            for (const sha of uniqueShas) {
+                commitMetaCache.set(sha, await fetchCommitMeta(workspace, sha, signal));
+            }
+            const frames = toConsider.map((frame, i) => {
+                const resolved = resolveFrameFile(workspace, frame.file);
+                const sha = blameShaByIndex[i];
+                const commit = sha ? (commitMetaCache.get(sha) ?? null) : null;
+                return {
+                    file: frame.file,
+                    line: frame.line,
+                    column: frame.column,
+                    function: frame.function,
+                    language: frame.language,
+                    inWorkspace: resolved !== null,
+                    resolvedPath: resolved,
+                    commit,
+                };
+            });
+            const allBlamedShas = blameShaByIndex.filter((s) => typeof s === "string");
+            const framesBlamed = allBlamedShas.length;
+            const topSha = blameShaByIndex[0] ?? null;
+            const confidence = scoreConfidence(Boolean(topSha), allBlamedShas, topSha);
+            let topSuspect = null;
+            if (topSha) {
+                const meta = commitMetaCache.get(topSha);
+                if (meta) {
+                    topSuspect = {
+                        ...meta,
+                        frameCount: allBlamedShas.filter((s) => s === topSha).length,
+                    };
+                }
+            }
+            return successStructured({
+                frames,
+                topSuspect,
+                confidence,
+                framesParsed,
+                framesBlamed,
+                gitAvailable,
+            });
+        },
+    };
+}
+//# sourceMappingURL=enrichStackTrace.js.map

package/dist/tools/enrichStackTrace.js.map

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

package/dist/tools/explainDiagnostic.d.ts

@@ -0,0 +1,137 @@
+import type { ExtensionClient } from "../extensionClient.js";
+export declare function createExplainDiagnosticTool(workspace: string, extensionClient: ExtensionClient): {
+    schema: {
+        name: string;
+        description: string;
+        extensionRequired: boolean;
+        annotations: {
+            readOnlyHint: boolean;
+        };
+        inputSchema: {
+            type: "object";
+            required: string[];
+            properties: {
+                filePath: {
+                    type: "string";
+                    description: string;
+                };
+                line: {
+                    type: "integer";
+                    description: string;
+                };
+                character: {
+                    type: "integer";
+                    description: string;
+                };
+            };
+            additionalProperties: false;
+        };
+        outputSchema: {
+            type: "object";
+            properties: {
+                diagnostic: {
+                    anyOf: ({
+                        type: "object";
+                        properties: {
+                            file: {
+                                type: "string";
+                            };
+                            line: {
+                                type: "integer";
+                            };
+                            column: {
+                                type: "integer";
+                            };
+                            severity: {
+                                type: "string";
+                            };
+                            message: {
+                                type: "string";
+                            };
+                            source: {
+                                type: "string";
+                            };
+                        };
+                        required: string[];
+                    } | {
+                        type: "null";
+                        properties?: undefined;
+                        required?: undefined;
+                    })[];
+                };
+                codeContext: {
+                    type: "array";
+                    items: {
+                        type: "string";
+                    };
+                };
+                symbol: {
+                    anyOf: ({
+                        type: "string";
+                    } | {
+                        type: "null";
+                    })[];
+                };
+                definition: {
+                    anyOf: ({
+                        type: "object";
+                        properties: {
+                            file: {
+                                type: "string";
+                            };
+                            line: {
+                                type: "integer";
+                            };
+                            column: {
+                                type: "integer";
+                            };
+                        };
+                        required: string[];
+                    } | {
+                        type: "null";
+                        properties?: undefined;
+                        required?: undefined;
+                    })[];
+                };
+                callers: {
+                    type: "array";
+                    items: {
+                        type: "object";
+                        properties: {
+                            name: {
+                                type: "string";
+                            };
+                            file: {
+                                type: "string";
+                            };
+                            line: {
+                                type: "integer";
+                            };
+                            column: {
+                                type: "integer";
+                            };
+                        };
+                        required: string[];
+                    };
+                };
+                explanation: {
+                    type: "string";
+                };
+            };
+            required: string[];
+        };
+    };
+    handler: (args: Record<string, unknown>, signal?: AbortSignal) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        structuredContent: unknown;
+    } | {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError: true;
+    }>;
+};