pi-shazam 0.1.0

package/dist/tools/hotspots.js

@@ -0,0 +1,107 @@
+import { scanProject } from "../core/scanner.js";
+export function registerHotspots(pi) {
+    pi.registerTool({
+        name: "shazam_hotspots",
+        label: "Complexity Hotspots",
+        description: `\
+Call to find complexity hotspots: files ranked by (symbol density ×
+PageRank score). The top 5 results are the files where bugs are most
+expensive — these files have the highest incoming dependency weight,
+meaning changes here cascade into the largest blast radius.
+
+Use this to decide where to focus code review, where to write tests
+first, and which files a new developer should read to understand the
+project's core.
+
+Scenario: code review prioritization. Deciding which tests to write
+next. Understanding where a new team member should start reading.
+Triaging bug reports (is the affected file a hotspot?).`,
+        parameters: pi.typebox.Object({
+            topN: pi.typebox.Optional(pi.typebox.Number()),
+            json: pi.typebox.Optional(pi.typebox.Boolean()),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const json = params.json ?? false;
+            const graph = scanProject(".");
+            const topN = params.topN ?? 10;
+            const result = executeHotspots(graph, topN);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: json
+                            ? executeHotspotsJson(graph, topN)
+                            : result,
+                    },
+                ],
+            };
+        },
+    });
+}
+export function executeHotspots(graph, topN = 10) {
+    const hotspots = computeHotspots(graph, topN);
+    const lines = [];
+    lines.push(`## Complexity Hotspots (Top ${topN})`);
+    lines.push("");
+    lines.push("Ranked by symbol density × PageRank score.");
+    lines.push("");
+    for (let i = 0; i < hotspots.length; i++) {
+        const h = hotspots[i];
+        lines.push(`${i + 1}. \`${h.file}\` — score: ${h.hotspotScore.toFixed(2)}`);
+        lines.push(`   ${h.symbolCount} symbols | PageRank: ${h.totalPagerank.toFixed(2)} | in:${h.incomingRefs} out:${h.outgoingRefs}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export function executeHotspotsJson(graph, topN) {
+    const hotspots = computeHotspots(graph, topN);
+    return JSON.stringify({
+        schema_version: "1.0",
+        command: "hotspots",
+        status: "ok",
+        result: {
+            hotspots: hotspots.map((h) => ({
+                file: h.file,
+                symbolCount: h.symbolCount,
+                totalPagerank: Number(h.totalPagerank.toFixed(4)),
+                incomingRefs: h.incomingRefs,
+                outgoingRefs: h.outgoingRefs,
+                hotspotScore: Number(h.hotspotScore.toFixed(2)),
+            })),
+        },
+    });
+}
+function computeHotspots(graph, topN) {
+    const fileStats = new Map();
+    for (const [file, symIds] of graph.fileSymbols) {
+        let totalPR = 0;
+        let incoming = 0;
+        let outgoing = 0;
+        for (const id of symIds) {
+            const sym = graph.symbols.get(id);
+            if (sym) {
+                totalPR += sym.pagerank;
+            }
+            const inc = graph.incoming.get(id);
+            if (inc)
+                incoming += inc.length;
+            const out = graph.outgoing.get(id);
+            if (out)
+                outgoing += out.length;
+        }
+        // Hotspot score = symbolCount * totalPagerank (normalized)
+        const hotspotScore = symIds.length * totalPR;
+        fileStats.set(file, {
+            file,
+            symbolCount: symIds.length,
+            totalPagerank: totalPR,
+            incomingRefs: incoming,
+            outgoingRefs: outgoing,
+            hotspotScore,
+        });
+    }
+    return [...fileStats.values()]
+        .sort((a, b) => b.hotspotScore - a.hotspotScore)
+        .slice(0, topN);
+}
+//# sourceMappingURL=hotspots.js.map

package/dist/tools/hotspots.js.map

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

package/dist/tools/impact.d.ts

@@ -0,0 +1,14 @@
+/**
+ * pi-shazam tools/impact — Change blast radius analysis.
+ */
+import type { ExtensionAPI } from "../types/pi-extension.js";
+import type { RepoGraph } from "../core/graph.js";
+export declare function registerImpact(pi: ExtensionAPI): void;
+interface ImpactOptions {
+    withSymbols: boolean;
+    compact: boolean;
+}
+export declare function executeImpact(graph: RepoGraph, files: string[], opts?: ImpactOptions): string;
+export declare function executeImpactJson(graph: RepoGraph, files: string[]): string;
+export {};
+//# sourceMappingURL=impact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"impact.d.ts","sourceRoot":"","sources":["../../tools/impact.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAU,MAAM,kBAAkB,CAAC;AAG1D,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAyCrD;AAED,UAAU,aAAa;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,aAAa,CAC5B,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,GAAE,aAAsD,GAC1D,MAAM,CA4FR;AAED,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,MAAM,EAAE,GACb,MAAM,CAsCR"}

package/dist/tools/impact.js

@@ -0,0 +1,160 @@
+import { scanProject } from "../core/scanner.js";
+export function registerImpact(pi) {
+    pi.registerTool({
+        name: "shazam_impact",
+        label: "Change Impact Analysis",
+        description: `\
+MUST call before editing 2+ files or any shared/exported module.
+Returns: exact list of files affected by planned changes, symbols at
+risk, test files that need re-running. Also surfaces untested code
+paths in the blast zone. Skipping this = guessing which tests to run
+and which callers to update.
+
+Scenario: refactoring. Adding a parameter to a shared function.
+Changing a type definition. Before any PR that touches >1 file.
+
+Pass --with-symbols for per-symbol risk breakdown. Pass --compact for
+concise output (file names only). Supports multiple --files.`,
+        parameters: pi.typebox.Object({
+            files: pi.typebox.Array(pi.typebox.String()),
+            withSymbols: pi.typebox.Optional(pi.typebox.Boolean()),
+            compact: pi.typebox.Optional(pi.typebox.Boolean()),
+            json: pi.typebox.Optional(pi.typebox.Boolean()),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const json = params.json ?? false;
+            const graph = scanProject(".");
+            const result = executeImpact(graph, params.files, {
+                withSymbols: params.withSymbols ?? false,
+                compact: params.compact ?? false,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: json
+                            ? executeImpactJson(graph, params.files)
+                            : result,
+                    },
+                ],
+            };
+        },
+    });
+}
+export function executeImpact(graph, files, opts = { withSymbols: false, compact: false }) {
+    const affectedFiles = new Set();
+    const affectedSymbols = [];
+    // For each file, find its symbols and trace outgoing edges
+    for (const file of files) {
+        affectedFiles.add(file);
+        const symIds = graph.fileSymbols.get(file) || [];
+        // Trace one level outward: what calls/imports symbols from this file?
+        for (const id of symIds) {
+            const incoming = graph.incoming.get(id);
+            if (incoming) {
+                for (const edge of incoming) {
+                    const callerSym = graph.symbols.get(edge.source);
+                    if (callerSym && !files.includes(callerSym.file)) {
+                        affectedFiles.add(callerSym.file);
+                        if (opts.withSymbols) {
+                            affectedSymbols.push(callerSym);
+                        }
+                    }
+                }
+            }
+            // Also: what does this file's symbols depend on?
+            const outgoing = graph.outgoing.get(id);
+            if (outgoing) {
+                for (const edge of outgoing) {
+                    const calleeSym = graph.symbols.get(edge.target);
+                    if (calleeSym && !files.includes(calleeSym.file)) {
+                        affectedFiles.add(calleeSym.file);
+                        if (opts.withSymbols) {
+                            affectedSymbols.push(calleeSym);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (opts.compact) {
+        return [...affectedFiles]
+            .filter((f) => !files.includes(f))
+            .sort()
+            .join("\n");
+    }
+    const lines = [];
+    lines.push("## Impact Analysis");
+    lines.push("");
+    lines.push(`Target files: ${files.join(", ")}`);
+    lines.push(`Affected files: ${affectedFiles.size - files.length}`);
+    lines.push("");
+    if (affectedFiles.size > files.length) {
+        lines.push("### Affected Files");
+        for (const f of [...affectedFiles].sort()) {
+            if (files.includes(f))
+                continue;
+            lines.push(`- \`${f}\``);
+        }
+    }
+    if (opts.withSymbols && affectedSymbols.length > 0) {
+        lines.push("");
+        lines.push("### Affected Symbols");
+        for (const sym of affectedSymbols.slice(0, 30)) {
+            lines.push(`- ${sym.kind} \`${sym.name}\` — ${sym.file}:${sym.line}`);
+        }
+        if (affectedSymbols.length > 30) {
+            lines.push(`  ... and ${affectedSymbols.length - 30} more`);
+        }
+    }
+    // Identify test files in affected set
+    const testFiles = [...affectedFiles].filter((f) => f.includes(".test.") ||
+        f.includes(".spec.") ||
+        f.includes("__tests__") ||
+        f.startsWith("tests/"));
+    if (testFiles.length > 0) {
+        lines.push("");
+        lines.push("### Affected Test Files (must re-run)");
+        for (const f of testFiles) {
+            lines.push(`- \`${f}\``);
+        }
+    }
+    return lines.join("\n");
+}
+export function executeImpactJson(graph, files) {
+    const affectedFiles = new Set();
+    const affectedSymbols = [];
+    for (const file of files) {
+        const symIds = graph.fileSymbols.get(file) || [];
+        for (const id of symIds) {
+            const incoming = graph.incoming.get(id);
+            if (incoming) {
+                for (const edge of incoming) {
+                    const callerSym = graph.symbols.get(edge.source);
+                    if (callerSym && !files.includes(callerSym.file)) {
+                        affectedFiles.add(callerSym.file);
+                        affectedSymbols.push(callerSym);
+                    }
+                }
+            }
+        }
+    }
+    return JSON.stringify({
+        schema_version: "1.0",
+        command: "impact",
+        status: "ok",
+        result: {
+            targetFiles: files,
+            affectedFileCount: affectedFiles.size - files.length,
+            affectedFiles: [...affectedFiles].filter((f) => !files.includes(f)).sort(),
+            affectedSymbols: affectedSymbols.slice(0, 50).map((s) => ({
+                id: s.id,
+                name: s.name,
+                kind: s.kind,
+                file: s.file,
+                line: s.line,
+            })),
+        },
+    });
+}
+//# sourceMappingURL=impact.js.map

package/dist/tools/impact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact.js","sourceRoot":"","sources":["../../tools/impact.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,UAAU,cAAc,CAAC,EAAgB;IAC9C,EAAE,CAAC,YAAY,CAAC;QACf,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,wBAAwB;QAC/B,WAAW,EAAE;;;;;;;;;;;6DAW8C;QAC3D,UAAU,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;YAC7B,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAC5C,WAAW,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACtD,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAClD,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;SAC/C,CAAC;QACF,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI;YAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC;YAClC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YAC/B,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE;gBACjD,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,KAAK;gBACxC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,KAAK;aAChC,CAAC,CAAC;YACH,OAAO;gBACN,OAAO,EAAE;oBACR;wBACC,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,IAAI;4BACT,CAAC,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;4BACxC,CAAC,CAAC,MAAM;qBACT;iBACD;aACD,CAAC;QACH,CAAC;KACD,CAAC,CAAC;AACJ,CAAC;AAOD,MAAM,UAAU,aAAa,CAC5B,KAAgB,EAChB,KAAe,EACf,OAAsB,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE;IAE5D,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,MAAM,eAAe,GAAa,EAAE,CAAC;IAErC,2DAA2D;IAC3D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAEjD,sEAAsE;QACtE,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxC,IAAI,QAAQ,EAAE,CAAC;gBACd,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;oBAC7B,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBACjD,IAAI,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;wBAClD,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;wBAClC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;4BACtB,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;wBACjC,CAAC;oBACF,CAAC;gBACF,CAAC;YACF,CAAC;YAED,iDAAiD;YACjD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxC,IAAI,QAAQ,EAAE,CAAC;gBACd,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;oBAC7B,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBACjD,IAAI,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;wBAClD,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;wBAClC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;4BACtB,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;wBACjC,CAAC;oBACF,CAAC;gBACF,CAAC;YACF,CAAC;QACF,CAAC;IACF,CAAC;IAED,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,CAAC,GAAG,aAAa,CAAC;aACvB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;aACjC,IAAI,EAAE;aACN,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,iBAAiB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChD,KAAK,CAAC,IAAI,CAAC,mBAAmB,aAAa,CAAC,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACnE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,aAAa,CAAC,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACjC,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,SAAS;YAChC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;IACF,CAAC;IAED,IAAI,IAAI,CAAC,WAAW,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACnC,KAAK,MAAM,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;YAChD,KAAK,CAAC,IAAI,CACT,KAAK,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,QAAQ,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,EAAE,CACzD,CAAC;QACH,CAAC;QACD,IAAI,eAAe,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,aAAa,eAAe,CAAC,MAAM,GAAG,EAAE,OAAO,CAAC,CAAC;QAC7D,CAAC;IACF,CAAC;IAED,sCAAsC;IACtC,MAAM,SAAS,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,MAAM,CAC1C,CAAC,CAAC,EAAE,EAAE,CACL,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACpB,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACpB,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;QACvB,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CACvB,CAAC;IACF,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;QACpD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAChC,KAAgB,EAChB,KAAe;IAGf,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,MAAM,eAAe,GAAa,EAAE,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACjD,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxC,IAAI,QAAQ,EAAE,CAAC;gBACd,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;oBAC7B,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBACjD,IAAI,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;wBAClD,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;wBAClC,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;oBACjC,CAAC;gBACF,CAAC;YACF,CAAC;QACF,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,CAAC;QACrB,cAAc,EAAE,KAAK;QACrB,OAAO,EAAE,QAAQ;QACjB,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE;YACP,WAAW,EAAE,KAAK;YAClB,iBAAiB,EAAE,aAAa,CAAC,IAAI,GAAG,KAAK,CAAC,MAAM;YACpD,aAAa,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;YAC1E,eAAe,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACzD,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;aACZ,CAAC,CAAC;SACH;KACD,CAAC,CAAC;AACJ,CAAC"}

package/dist/tools/orphan.d.ts

@@ -0,0 +1,9 @@
+/**
+ * pi-shazam tools/orphan — Dead code detection.
+ */
+import type { ExtensionAPI } from "../types/pi-extension.js";
+import type { RepoGraph } from "../core/graph.js";
+export declare function registerOrphan(pi: ExtensionAPI): void;
+export declare function executeOrphan(graph: RepoGraph, file?: string, minConfidence?: number): string;
+export declare function executeOrphanJson(graph: RepoGraph, file?: string, minConfidence?: number): string;
+//# sourceMappingURL=orphan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orphan.d.ts","sourceRoot":"","sources":["../../tools/orphan.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAU,MAAM,kBAAkB,CAAC;AAG1D,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA2CrD;AAQD,wBAAgB,aAAa,CAC5B,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE,MAAM,EACb,aAAa,GAAE,MAAW,GACxB,MAAM,CAqCR;AAED,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE,MAAM,EACb,aAAa,GAAE,MAAW,GACxB,MAAM,CAmBR"}

package/dist/tools/orphan.js

@@ -0,0 +1,124 @@
+import { scanProject } from "../core/scanner.js";
+export function registerOrphan(pi) {
+    pi.registerTool({
+        name: "shazam_orphan",
+        label: "Dead Code Detection",
+        description: `\
+Call to find dead code: symbols with zero incoming references across
+the entire project. Confidence ≥ 70 means LIKELY safe to delete.
+Confidence < 70 means check for dynamic references (string dispatch,
+reflection, macros, event listeners, test-only usage).
+
+MUST call shazam_refs on each candidate before actual deletion to
+confirm zero references. A "dead" function that's called via
+getattr/dlsym/Reflect is still live — orphan detection cannot see
+dynamic dispatch.
+
+Scenario: cleaning up unused code. Finding abandoned modules. Before a
+major refactor to identify removable surface area. After removing a
+feature to find orphaned helpers.`,
+        parameters: pi.typebox.Object({
+            file: pi.typebox.Optional(pi.typebox.String()),
+            minConfidence: pi.typebox.Optional(pi.typebox.Number()),
+            json: pi.typebox.Optional(pi.typebox.Boolean()),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const json = params.json ?? false;
+            const graph = scanProject(".");
+            const result = executeOrphan(graph, params.file, params.minConfidence ?? 50);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: json
+                            ? executeOrphanJson(graph, params.file, params.minConfidence ?? 50)
+                            : result,
+                    },
+                ],
+            };
+        },
+    });
+}
+export function executeOrphan(graph, file, minConfidence = 50) {
+    const candidates = findOrphans(graph, file, minConfidence);
+    if (candidates.length === 0) {
+        return "No orphan symbols detected.";
+    }
+    const lines = [];
+    lines.push(`## Orphan Symbols (${candidates.length} candidates, min confidence ${minConfidence}%)`);
+    lines.push("");
+    lines.push("Symbols with zero incoming references. Confidence ≥ 70 = likely safe to delete.");
+    lines.push("ALWAYS verify with shazam_refs before actual deletion.");
+    lines.push("");
+    // Group by file
+    const byFile = new Map();
+    for (const c of candidates) {
+        const arr = byFile.get(c.symbol.file) || [];
+        arr.push(c);
+        byFile.set(c.symbol.file, arr);
+    }
+    for (const [f, cands] of [...byFile.entries()].sort()) {
+        lines.push(`### ${f}`);
+        for (const c of cands) {
+            lines.push(`- ${c.symbol.kind} \`${c.symbol.name}\` L${c.symbol.line} — confidence ${c.confidence}% (${c.reason})`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trim();
+}
+export function executeOrphanJson(graph, file, minConfidence = 50) {
+    const candidates = findOrphans(graph, file, minConfidence);
+    return JSON.stringify({
+        schema_version: "1.0",
+        command: "orphan",
+        status: "ok",
+        result: {
+            count: candidates.length,
+            candidates: candidates.map((c) => ({
+                id: c.symbol.id,
+                name: c.symbol.name,
+                kind: c.symbol.kind,
+                file: c.symbol.file,
+                line: c.symbol.line,
+                confidence: c.confidence,
+                reason: c.reason,
+            })),
+        },
+    });
+}
+function findOrphans(graph, file, minConfidence = 50) {
+    const candidates = [];
+    for (const sym of graph.symbols.values()) {
+        if (file && sym.file !== file)
+            continue;
+        const incoming = graph.incoming.get(sym.id);
+        const outgoing = graph.outgoing.get(sym.id);
+        const incCount = incoming ? incoming.length : 0;
+        if (incCount > 0)
+            continue; // Has references, not orphan
+        // Determine confidence based on visibility and outgoing edges
+        let confidence = 0;
+        let reason = "";
+        if (sym.visibility === "private") {
+            confidence = 90;
+            reason = "private symbol with no incoming references";
+        }
+        else if (sym.name.startsWith("_")) {
+            confidence = 85;
+            reason = "underscore-prefixed with no incoming references";
+        }
+        else if (!outgoing || outgoing.length === 0) {
+            confidence = 70;
+            reason = "no incoming or outgoing references; possibly dead";
+        }
+        else {
+            confidence = 50;
+            reason = "has outgoing refs but no incoming; may be test-only or entry point";
+        }
+        if (confidence >= minConfidence) {
+            candidates.push({ symbol: sym, confidence, reason });
+        }
+    }
+    return candidates.sort((a, b) => b.confidence - a.confidence);
+}
+//# sourceMappingURL=orphan.js.map

package/dist/tools/orphan.js.map

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

package/dist/tools/overview.d.ts

@@ -0,0 +1,9 @@
+/**
+ * pi-shazam tools/overview — Project structure summary.
+ */
+import type { ExtensionAPI } from "../types/pi-extension.js";
+import type { RepoGraph } from "../core/graph.js";
+export declare function registerOverview(pi: ExtensionAPI): void;
+export declare function executeOverview(graph: RepoGraph, _projectRoot: string): string;
+export declare function executeOverviewJson(graph: RepoGraph, projectRoot: string): string;
+//# sourceMappingURL=overview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../../tools/overview.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAkCvD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CA2F9E;AAED,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,GACjB,MAAM,CA6BR"}

package/dist/tools/overview.js

@@ -0,0 +1,137 @@
+import { scanProject } from "../core/scanner.js";
+export function registerOverview(pi) {
+    pi.registerTool({
+        name: "shazam_overview",
+        label: "Project Overview",
+        description: `\
+MUST call before touching ANY code in an unfamiliar project or repo.
+Returns: module dependency map, top-10 highest-PageRank files (the
+"spine" of the codebase), entry points, and suggested reading order.
+Skipping this = navigating blind — you WILL miss cross-module ripple
+effects and waste turns on dead-end reads.
+
+Scenario: first turn in a new repo. After git clone. After switching
+to an unfamiliar project directory.
+
+Output: plain text summary by default. Pass { json: true } for
+structured output with file lists and PageRank scores.`,
+        parameters: pi.typebox.Object({
+            json: pi.typebox.Optional(pi.typebox.Boolean()),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const json = params.json ?? false;
+            const graph = scanProject(".");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: json
+                            ? executeOverviewJson(graph, ".")
+                            : executeOverview(graph, "."),
+                    },
+                ],
+            };
+        },
+    });
+}
+export function executeOverview(graph, _projectRoot) {
+    const lines = [];
+    // Summary stats
+    lines.push("## Project Overview");
+    lines.push("");
+    lines.push(`${graph.symbols.size} symbols across ${graph.fileSymbols.size} files`);
+    // Calculate per-file symbol counts and aggregate PageRank
+    const fileStats = new Map();
+    for (const [file, symIds] of graph.fileSymbols) {
+        let totalPR = 0;
+        let topPR = 0;
+        let topName = "";
+        for (const id of symIds) {
+            const sym = graph.symbols.get(id);
+            if (sym) {
+                totalPR += sym.pagerank;
+                if (sym.pagerank > topPR) {
+                    topPR = sym.pagerank;
+                    topName = sym.name;
+                }
+            }
+        }
+        fileStats.set(file, { count: symIds.length, pagerank: totalPR, topSym: topName });
+    }
+    // Top files by PageRank
+    const topFiles = [...fileStats.entries()]
+        .sort((a, b) => b[1].pagerank - a[1].pagerank)
+        .slice(0, 10);
+    lines.push("");
+    lines.push("### Top 10 Files by PageRank");
+    lines.push("");
+    for (let i = 0; i < topFiles.length; i++) {
+        const [file, stats] = topFiles[i];
+        lines.push(`${i + 1}. \`${file}\` — ${stats.count} symbols, PageRank ${stats.pagerank.toFixed(2)}, top symbol: ${stats.topSym}`);
+    }
+    // Entry points (files with high PageRank and export visibility)
+    const entryPoints = [...graph.symbols.values()]
+        .filter((s) => s.visibility === "exported" && s.pagerank > 0.01)
+        .sort((a, b) => b.pagerank - a.pagerank)
+        .slice(0, 10);
+    if (entryPoints.length > 0) {
+        lines.push("");
+        lines.push("### Entry Points");
+        lines.push("");
+        for (const sym of entryPoints) {
+            lines.push(`- ${sym.kind} \`${sym.name}\` — ${sym.file}:${sym.line} (PR ${sym.pagerank.toFixed(3)})`);
+        }
+    }
+    // Module dependency summary
+    lines.push("");
+    lines.push("### Module Structure");
+    lines.push("");
+    const dirs = new Set();
+    for (const file of graph.fileSymbols.keys()) {
+        const dir = file.includes("/") ? file.split("/")[0] : "(root)";
+        dirs.add(dir);
+    }
+    const sortedDirs = [...dirs].sort();
+    for (const dir of sortedDirs) {
+        const dirFiles = [...graph.fileSymbols.keys()].filter((f) => f.startsWith(dir + "/") || (dir === "(root)" && !f.includes("/")));
+        lines.push(`- \`${dir}/\` — ${dirFiles.length} files`);
+    }
+    lines.push("");
+    lines.push("### Suggested Reading Order");
+    lines.push("");
+    if (topFiles.length > 0) {
+        for (let i = 0; i < Math.min(5, topFiles.length); i++) {
+            lines.push(`${i + 1}. Start with \`${topFiles[i][0]}\``);
+        }
+    }
+    return lines.join("\n");
+}
+export function executeOverviewJson(graph, projectRoot) {
+    const fileStats = new Map();
+    for (const [file, symIds] of graph.fileSymbols) {
+        let totalPR = 0;
+        for (const id of symIds) {
+            totalPR += graph.symbols.get(id)?.pagerank ?? 0;
+        }
+        fileStats.set(file, { count: symIds.length, pagerank: totalPR });
+    }
+    const topFiles = [...fileStats.entries()]
+        .sort((a, b) => b[1].pagerank - a[1].pagerank)
+        .slice(0, 10);
+    return JSON.stringify({
+        schema_version: "1.0",
+        command: "overview",
+        project: projectRoot,
+        status: "ok",
+        result: {
+            totalSymbols: graph.symbols.size,
+            totalFiles: graph.fileSymbols.size,
+            topFiles: topFiles.map(([file, stats]) => ({
+                file,
+                symbolCount: stats.count,
+                pagerank: Number(stats.pagerank.toFixed(4)),
+            })),
+        },
+    });
+}
+//# sourceMappingURL=overview.js.map

package/dist/tools/overview.js.map

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

package/dist/tools/ready.d.ts

@@ -0,0 +1,18 @@
+/**
+ * pi-shazam tools/ready — Pre-commit readiness check.
+ *
+ * Composes verify + check into a single pre-commit gate.
+ * This is the FINAL GATE before shipping code.
+ */
+import type { ExtensionAPI } from "../types/pi-extension.js";
+import type { RepoGraph } from "../core/graph.js";
+export declare function registerReady(pi: ExtensionAPI): void;
+/**
+ * Run pre-commit readiness check, composing verify + check results.
+ */
+export declare function executeReady(graph: RepoGraph, projectRoot: string): string;
+/**
+ * Run readiness check and return structured JSON.
+ */
+export declare function executeReadyJson(graph: RepoGraph, projectRoot: string): string;
+//# sourceMappingURL=ready.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../../tools/ready.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAuBlD,wBAAgB,aAAa,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAwCpD;AAID;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAgE1E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,GACjB,MAAM,CAwCR"}