projscan 0.11.0 → 0.12.0

package/dist/mcp/tools/coverage.js

@@ -0,0 +1,53 @@
+import { scanRepository } from '../../core/repositoryScanner.js';
+import { collectIssues } from '../../core/issueEngine.js';
+import { analyzeHotspots } from '../../core/hotspotAnalyzer.js';
+import { parseCoverage, coverageMap } from '../../core/coverageParser.js';
+import { joinCoverageWithHotspots } from '../../core/coverageJoin.js';
+import { paginate, listChecksum, readPageParams } from '../pagination.js';
+import { PACKAGE_ARG_SCHEMA, resolvePackageFilter } from './_shared.js';
+export const coverageTool = {
+    name: 'projscan_coverage',
+    description: 'Join test coverage with hotspot risk. Returns files ranked by "risk × uncovered fraction" - the scariest untested files. Requires a coverage file at coverage/lcov.info, coverage/coverage-final.json, or coverage/coverage-summary.json.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: {
+                type: 'number',
+                description: 'How many entries to return (default: 30, max: 200).',
+            },
+            max_tokens: {
+                type: 'number',
+                description: 'Cap the response size to roughly this many tokens (~4 chars/token). Truncates the entries array to fit.',
+            },
+            package: PACKAGE_ARG_SCHEMA,
+        },
+    },
+    handler: async (args, rootPath) => {
+        const coverage = await parseCoverage(rootPath);
+        const scan = await scanRepository(rootPath);
+        const issues = await collectIssues(rootPath, scan.files);
+        const rawLimit = typeof args.limit === 'number' ? args.limit : 200;
+        const limit = Math.max(1, Math.min(500, rawLimit));
+        const hotspots = await analyzeHotspots(rootPath, scan.files, issues, {
+            limit,
+            coverage: coverage.available ? coverageMap(coverage) : undefined,
+        });
+        const joined = joinCoverageWithHotspots(hotspots, coverage);
+        if (!joined.available)
+            return joined;
+        const passes = await resolvePackageFilter(rootPath, args);
+        const filteredEntries = passes
+            ? joined.entries.filter((e) => passes(e.relativePath))
+            : joined.entries;
+        const page = paginate(filteredEntries, readPageParams(args), listChecksum(filteredEntries));
+        return {
+            available: true,
+            coverageSource: joined.coverageSource,
+            coverageSourceFile: joined.coverageSourceFile,
+            entries: page.items,
+            total: page.total,
+            nextCursor: page.nextCursor,
+        };
+    },
+};
+//# sourceMappingURL=coverage.js.map

package/dist/mcp/tools/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../../src/mcp/tools/coverage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAgB,MAAM,cAAc,CAAC;AAEtF,MAAM,CAAC,MAAM,YAAY,GAAY;IACnC,IAAI,EAAE,mBAAmB;IACzB,WAAW,EACT,2OAA2O;IAC7O,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,qDAAqD;aACnE;YACD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,yGAAyG;aACvH;YACD,OAAO,EAAE,kBAAkB;SAC5B;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAChC,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC5C,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACzD,MAAM,QAAQ,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;QACnE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;QACnD,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE;YACnE,KAAK;YACL,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;SACjE,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC5D,IAAI,CAAC,MAAM,CAAC,SAAS;YAAE,OAAO,MAAM,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1D,MAAM,eAAe,GAAG,MAAM;YAC5B,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;YACtD,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QACnB,MAAM,IAAI,GAAG,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC;QAC5F,OAAO;YACL,SAAS,EAAE,IAAI;YACf,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;YAC7C,OAAO,EAAE,IAAI,CAAC,KAAK;YACnB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/mcp/tools/dependencies.d.ts

@@ -0,0 +1,2 @@
+import type { McpTool } from './_shared.js';
+export declare const dependenciesTool: McpTool;

package/dist/mcp/tools/dependencies.js

@@ -0,0 +1,16 @@
+import { analyzeDependencies } from '../../core/dependencyAnalyzer.js';
+export const dependenciesTool = {
+    name: 'projscan_dependencies',
+    description: 'Analyze package.json dependencies and return counts and risks (deprecated packages, wildcard versions, etc.).',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+    handler: async (_args, rootPath) => {
+        const report = await analyzeDependencies(rootPath);
+        if (!report)
+            return { available: false, reason: 'No package.json found' };
+        return { available: true, ...report };
+    },
+};
+//# sourceMappingURL=dependencies.js.map

package/dist/mcp/tools/dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.js","sourceRoot":"","sources":["../../../src/mcp/tools/dependencies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAGvE,MAAM,CAAC,MAAM,gBAAgB,GAAY;IACvC,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EAAE,+GAA+G;IAC5H,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE;KACf;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;QACjC,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;QAC1E,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;IACxC,CAAC;CACF,CAAC"}

package/dist/mcp/tools/doctor.d.ts

@@ -0,0 +1,2 @@
+import { type McpTool } from './_shared.js';
+export declare const doctorTool: McpTool;

package/dist/mcp/tools/doctor.js

@@ -0,0 +1,30 @@
+import { scanRepository } from '../../core/repositoryScanner.js';
+import { collectIssues } from '../../core/issueEngine.js';
+import { calculateScore } from '../../utils/scoreCalculator.js';
+import { PACKAGE_ARG_SCHEMA, resolvePackageFilter } from './_shared.js';
+export const doctorTool = {
+    name: 'projscan_doctor',
+    description: 'Run a health check on the project. Returns a 0-100 score, letter grade, and the list of issues (linting, formatting, tests, security, architecture).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            package: PACKAGE_ARG_SCHEMA,
+        },
+    },
+    handler: async (args, rootPath) => {
+        const scan = await scanRepository(rootPath);
+        let issues = await collectIssues(rootPath, scan.files);
+        const passes = await resolvePackageFilter(rootPath, args);
+        if (passes) {
+            issues = issues.filter((i) => {
+                const locs = i.locations ?? [];
+                if (locs.length === 0)
+                    return false;
+                return locs.some((l) => l.file && passes(l.file));
+            });
+        }
+        const health = calculateScore(issues);
+        return { health, issues };
+    },
+};
+//# sourceMappingURL=doctor.js.map

package/dist/mcp/tools/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/mcp/tools/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAgB,MAAM,cAAc,CAAC;AAEtF,MAAM,CAAC,MAAM,UAAU,GAAY;IACjC,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,sJAAsJ;IACxJ,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,OAAO,EAAE,kBAAkB;SAC5B;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAChC,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,MAAM,GAAG,MAAM,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1D,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC3B,MAAM,IAAI,GAAG,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC;gBAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACpC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YACpD,CAAC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QACtC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;CACF,CAAC"}

package/dist/mcp/tools/explain.d.ts

@@ -0,0 +1,2 @@
+import { type McpTool } from './_shared.js';
+export declare const explainTool: McpTool;

package/dist/mcp/tools/explain.js

@@ -0,0 +1,30 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { explainFile } from './_shared.js';
+export const explainTool = {
+    name: 'projscan_explain',
+    description: 'Explain a single file: purpose, imports, exports, and potential issues. Useful for understanding unfamiliar code before editing.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file: {
+                type: 'string',
+                description: 'Path to the file relative to the project root.',
+            },
+        },
+        required: ['file'],
+    },
+    handler: async (args, rootPath) => {
+        const rel = typeof args.file === 'string' ? args.file : '';
+        if (!rel)
+            throw new Error('file argument is required');
+        const absolutePath = path.resolve(rootPath, rel);
+        const resolvedRoot = path.resolve(rootPath);
+        if (!absolutePath.startsWith(resolvedRoot + path.sep) && absolutePath !== resolvedRoot) {
+            throw new Error('file must be inside the project root');
+        }
+        const content = await fs.readFile(absolutePath, 'utf-8');
+        return explainFile(absolutePath, content, rootPath);
+    },
+};
+//# sourceMappingURL=explain.js.map

package/dist/mcp/tools/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/mcp/tools/explain.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,EAAE,WAAW,EAAgB,MAAM,cAAc,CAAC;AAEzD,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,IAAI,EAAE,kBAAkB;IACxB,WAAW,EACT,kIAAkI;IACpI,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,gDAAgD;aAC9D;SACF;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;KACnB;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAChC,MAAM,GAAG,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QACvD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACjD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,YAAY,KAAK,YAAY,EAAE,CAAC;YACvF,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC1D,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACzD,OAAO,WAAW,CAAC,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACtD,CAAC;CACF,CAAC"}

package/dist/mcp/tools/file.d.ts

@@ -0,0 +1,2 @@
+import type { McpTool } from './_shared.js';
+export declare const fileTool: McpTool;

package/dist/mcp/tools/file.js

@@ -0,0 +1,22 @@
+import { inspectFile } from '../../core/fileInspector.js';
+export const fileTool = {
+    name: 'projscan_file',
+    description: 'Drill into a single file: purpose, imports, exports, churn/risk/ownership, related health issues, AST cyclomatic complexity, and coupling (fan-in / fan-out). Use this after projscan_hotspots when deciding how to approach a specific risky file.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file: {
+                type: 'string',
+                description: 'Path to the file relative to the project root.',
+            },
+        },
+        required: ['file'],
+    },
+    handler: async (args, rootPath) => {
+        const rel = typeof args.file === 'string' ? args.file : '';
+        if (!rel)
+            throw new Error('file argument is required');
+        return await inspectFile(rootPath, rel);
+    },
+};
+//# sourceMappingURL=file.js.map

package/dist/mcp/tools/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../src/mcp/tools/file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAG1D,MAAM,CAAC,MAAM,QAAQ,GAAY;IAC/B,IAAI,EAAE,eAAe;IACrB,WAAW,EACT,qPAAqP;IACvP,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,gDAAgD;aAC9D;SACF;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;KACnB;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAChC,MAAM,GAAG,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QACvD,OAAO,MAAM,WAAW,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;CACF,CAAC"}

package/dist/mcp/tools/graph.d.ts

@@ -0,0 +1,2 @@
+import type { McpTool } from './_shared.js';
+export declare const graphTool: McpTool;

package/dist/mcp/tools/graph.js

@@ -0,0 +1,69 @@
+import { scanRepository } from '../../core/repositoryScanner.js';
+import { buildCodeGraph, filesImportingFile, filesImportingPackage, filesDefiningSymbol, exportsOf, importsOf, } from '../../core/codeGraph.js';
+import { loadCachedGraph, saveCachedGraph } from '../../core/indexCache.js';
+export const graphTool = {
+    name: 'projscan_graph',
+    description: 'Query the AST-based code graph directly. Returns imports, exports, importers, or symbol definitions for a file or symbol. Agents should prefer this over analyze/doctor/explain for targeted structural questions - it is much cheaper and more accurate.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file: {
+                type: 'string',
+                description: 'File path (relative to project root) to query.',
+            },
+            symbol: {
+                type: 'string',
+                description: 'Symbol name to query (e.g. a function or class). Use instead of `file` to find where a symbol is defined.',
+            },
+            direction: {
+                type: 'string',
+                description: 'What to return: "imports" (what the file imports), "exports" (what the file exports), "importers" (who imports the file), "symbol_defs" (files defining the symbol), "package_importers" (files importing a package by name).',
+                enum: ['imports', 'exports', 'importers', 'symbol_defs', 'package_importers'],
+            },
+            limit: { type: 'number', description: 'Max entries returned (default 50).' },
+            max_tokens: { type: 'number', description: 'Cap the response to roughly this many tokens.' },
+        },
+        required: ['direction'],
+    },
+    handler: async (args, rootPath) => {
+        const scan = await scanRepository(rootPath);
+        const cached = await loadCachedGraph(rootPath);
+        const graph = await buildCodeGraph(rootPath, scan.files, cached);
+        await saveCachedGraph(rootPath, graph);
+        const direction = String(args.direction);
+        const file = typeof args.file === 'string' ? args.file : undefined;
+        const symbol = typeof args.symbol === 'string' ? args.symbol : undefined;
+        const limit = Math.max(1, Math.min(500, typeof args.limit === 'number' ? args.limit : 50));
+        switch (direction) {
+            case 'imports': {
+                if (!file)
+                    throw new Error('file argument is required for direction=imports');
+                return { file, imports: importsOf(graph, file).slice(0, limit) };
+            }
+            case 'exports': {
+                if (!file)
+                    throw new Error('file argument is required for direction=exports');
+                return { file, exports: exportsOf(graph, file).slice(0, limit) };
+            }
+            case 'importers': {
+                if (!file)
+                    throw new Error('file argument is required for direction=importers');
+                return { file, importers: filesImportingFile(graph, file).slice(0, limit) };
+            }
+            case 'symbol_defs': {
+                if (!symbol)
+                    throw new Error('symbol argument is required for direction=symbol_defs');
+                return { symbol, definedIn: filesDefiningSymbol(graph, symbol).slice(0, limit) };
+            }
+            case 'package_importers': {
+                const pkg = symbol ?? file;
+                if (!pkg)
+                    throw new Error('symbol (or file) argument is required for direction=package_importers');
+                return { package: pkg, importers: filesImportingPackage(graph, pkg).slice(0, limit) };
+            }
+            default:
+                throw new Error(`unknown direction: ${direction}`);
+        }
+    },
+};
+//# sourceMappingURL=graph.js.map

package/dist/mcp/tools/graph.js.map

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

package/dist/mcp/tools/hotspots.d.ts

@@ -0,0 +1,2 @@
+import type { McpTool } from './_shared.js';
+export declare const hotspotsTool: McpTool;

package/dist/mcp/tools/hotspots.js

@@ -0,0 +1,64 @@
+import { scanRepository } from '../../core/repositoryScanner.js';
+import { collectIssues } from '../../core/issueEngine.js';
+import { analyzeHotspots } from '../../core/hotspotAnalyzer.js';
+import { buildCodeGraph } from '../../core/codeGraph.js';
+import { loadCachedGraph, saveCachedGraph } from '../../core/indexCache.js';
+import { detectWorkspaces, filterFilesByPackage } from '../../core/monorepo.js';
+import { paginate, listChecksum, readPageParams } from '../pagination.js';
+import { emitProgress } from '../progress.js';
+export const hotspotsTool = {
+    name: 'projscan_hotspots',
+    description: 'Rank files by risk using git churn × AST cyclomatic complexity × open issues. Returns the most dangerous files to touch. Each hotspot includes `cyclomaticComplexity` (null for non-AST languages, where line count is used as fallback). Supports cursor-based pagination: pass the `nextCursor` from a previous response back as `cursor` to fetch the next page.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: {
+                type: 'number',
+                description: 'Cap on total hotspots ranked (default 100). For paging the returned set, use `page_size` + `cursor` instead.',
+            },
+            since: {
+                type: 'string',
+                description: 'Git history window. Examples: "12 months ago", "2024-01-01". Default: "12 months ago".',
+            },
+            cursor: { type: 'string', description: 'Opaque cursor from a previous response. Omit for the first page.' },
+            page_size: { type: 'number', description: 'Items per page (default 50, max 500).' },
+            max_tokens: { type: 'number', description: 'Cap response to roughly this many tokens.' },
+            package: {
+                type: 'string',
+                description: 'Optional. Workspace package name (from projscan_workspaces) to scope hotspots to one package only.',
+            },
+        },
+    },
+    handler: async (args, rootPath) => {
+        emitProgress(0, 5, 'scanning repository');
+        const scan = await scanRepository(rootPath);
+        emitProgress(1, 5, 'collecting issues');
+        const issues = await collectIssues(rootPath, scan.files);
+        const limit = typeof args.limit === 'number' ? args.limit : 100;
+        const since = typeof args.since === 'string' ? args.since : undefined;
+        emitProgress(2, 5, 'building code graph');
+        const cached = await loadCachedGraph(rootPath);
+        const graph = await buildCodeGraph(rootPath, scan.files, cached);
+        await saveCachedGraph(rootPath, graph);
+        emitProgress(3, 5, 'analyzing git churn + risk');
+        const report = await analyzeHotspots(rootPath, scan.files, issues, { limit, since, graph });
+        if (typeof args.package === 'string' && args.package.length > 0) {
+            const ws = await detectWorkspaces(rootPath);
+            const allowed = new Set(filterFilesByPackage(ws, args.package, report.hotspots.map((h) => h.relativePath)));
+            report.hotspots = report.hotspots.filter((h) => allowed.has(h.relativePath));
+        }
+        emitProgress(4, 5, 'paginating');
+        const page = paginate(report.hotspots, readPageParams(args), listChecksum(report.hotspots));
+        emitProgress(5, 5, 'done');
+        return {
+            available: report.available,
+            reason: report.reason,
+            window: report.window,
+            hotspots: page.items,
+            totalFilesRanked: report.totalFilesRanked,
+            nextCursor: page.nextCursor,
+            total: page.total,
+        };
+    },
+};
+//# sourceMappingURL=hotspots.js.map

package/dist/mcp/tools/hotspots.js.map

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

package/dist/mcp/tools/outdated.d.ts

@@ -0,0 +1,2 @@
+import { type McpTool } from './_shared.js';
+export declare const outdatedTool: McpTool;

package/dist/mcp/tools/outdated.js

@@ -0,0 +1,36 @@
+import { detectOutdated } from '../../core/outdatedDetector.js';
+import { detectWorkspaces } from '../../core/monorepo.js';
+import { paginate, listChecksum, readPageParams } from '../pagination.js';
+import { PACKAGE_ARG_SCHEMA } from './_shared.js';
+export const outdatedTool = {
+    name: 'projscan_outdated',
+    description: 'Compare declared vs installed versions of every package. Reports drift (patch/minor/major). Workspace-aware in monorepos: each package.json is scanned, and each entry is tagged with the workspace it came from. Pass `package` to scope to a single workspace. Offline - does not hit the npm registry. Supports cursor pagination.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            package: PACKAGE_ARG_SCHEMA,
+            cursor: { type: 'string', description: 'Opaque cursor from a previous response.' },
+            page_size: { type: 'number', description: 'Items per page (default 50).' },
+            max_tokens: { type: 'number', description: 'Cap response size.' },
+        },
+    },
+    handler: async (args, rootPath) => {
+        const workspaces = await detectWorkspaces(rootPath);
+        const report = await detectOutdated(rootPath, {
+            workspaces,
+            ...(typeof args.package === 'string' ? { workspaceFilter: args.package } : {}),
+        });
+        if (!report.available)
+            return report;
+        const page = paginate(report.packages, readPageParams(args), listChecksum(report.packages));
+        return {
+            available: true,
+            totalPackages: report.totalPackages,
+            packages: page.items,
+            byWorkspace: report.byWorkspace,
+            total: page.total,
+            nextCursor: page.nextCursor,
+        };
+    },
+};
+//# sourceMappingURL=outdated.js.map

package/dist/mcp/tools/outdated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outdated.js","sourceRoot":"","sources":["../../../src/mcp/tools/outdated.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAgB,MAAM,cAAc,CAAC;AAEhE,MAAM,CAAC,MAAM,YAAY,GAAY;IACnC,IAAI,EAAE,mBAAmB;IACzB,WAAW,EACT,uUAAuU;IACzU,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,OAAO,EAAE,kBAAkB;YAC3B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,yCAAyC,EAAE;YAClF,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,8BAA8B,EAAE;YAC1E,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAE;SAClE;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAChC,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE;YAC5C,UAAU;YACV,GAAG,CAAC,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/E,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,SAAS;YAAE,OAAO,MAAM,CAAC;QACrC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC5F,OAAO;YACL,SAAS,EAAE,IAAI;YACf,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,QAAQ,EAAE,IAAI,CAAC,KAAK;YACpB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/mcp/tools/prDiff.d.ts

@@ -0,0 +1,2 @@
+import { type McpTool } from './_shared.js';
+export declare const prDiffTool: McpTool;

package/dist/mcp/tools/prDiff.js

@@ -0,0 +1,38 @@
+import { computePrDiff } from '../../core/prDiff.js';
+import { emitProgress } from '../progress.js';
+import { PACKAGE_ARG_SCHEMA, resolvePackageFilter } from './_shared.js';
+export const prDiffTool = {
+    name: 'projscan_pr_diff',
+    description: 'Structural (AST) diff between two refs - what changed in exports, imports, call sites, cyclomatic complexity, and fan-in. Not a text diff: this surfaces the symbols and edges that an agent reviewing a PR actually cares about. Defaults: base=origin/main (falls back to main/master/HEAD~1), head=HEAD. Spins up a throwaway git worktree at the base ref to get a clean second graph.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            base: {
+                type: 'string',
+                description: 'Base ref (branch, tag, sha). Default: origin/main, falling back to main/master/HEAD~1.',
+            },
+            head: { type: 'string', description: 'Head ref. Default: HEAD.' },
+            max_tokens: { type: 'number', description: 'Cap the response to roughly this many tokens.' },
+            package: PACKAGE_ARG_SCHEMA,
+        },
+    },
+    handler: async (args, rootPath) => {
+        emitProgress(0, 3, 'resolving refs');
+        const base = typeof args.base === 'string' ? args.base : undefined;
+        const head = typeof args.head === 'string' ? args.head : undefined;
+        emitProgress(1, 3, 'building base + head graphs');
+        const report = await computePrDiff(rootPath, { base, head });
+        emitProgress(2, 3, 'diffing');
+        const passes = await resolvePackageFilter(rootPath, args);
+        if (passes) {
+            report.filesAdded = report.filesAdded.filter(passes);
+            report.filesRemoved = report.filesRemoved.filter(passes);
+            report.filesModified = report.filesModified.filter((f) => passes(f.relativePath));
+            report.totalFilesChanged =
+                report.filesAdded.length + report.filesRemoved.length + report.filesModified.length;
+        }
+        emitProgress(3, 3, 'done');
+        return report;
+    },
+};
+//# sourceMappingURL=prDiff.js.map

package/dist/mcp/tools/prDiff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prDiff.js","sourceRoot":"","sources":["../../../src/mcp/tools/prDiff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAgB,MAAM,cAAc,CAAC;AAEtF,MAAM,CAAC,MAAM,UAAU,GAAY;IACjC,IAAI,EAAE,kBAAkB;IACxB,WAAW,EACT,4XAA4X;IAC9X,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,wFAAwF;aACtG;YACD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0BAA0B,EAAE;YACjE,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+CAA+C,EAAE;YAC5F,OAAO,EAAE,kBAAkB;SAC5B;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAChC,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QACnE,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QACnE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,6BAA6B,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1D,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACrD,MAAM,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACzD,MAAM,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;YAClF,MAAM,CAAC,iBAAiB;gBACtB,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC;QACxF,CAAC;QACD,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;QAC3B,OAAO,MAAM,CAAC;IAChB,CAAC;CACF,CAAC"}

package/dist/mcp/tools/search.d.ts

@@ -0,0 +1,2 @@
+import { type McpTool } from './_shared.js';
+export declare const searchTool: McpTool;

package/dist/mcp/tools/search.js

@@ -0,0 +1,167 @@
+import { scanRepository } from '../../core/repositoryScanner.js';
+import { buildCodeGraph } from '../../core/codeGraph.js';
+import { loadCachedGraph, saveCachedGraph } from '../../core/indexCache.js';
+import { buildSearchIndex, search as searchIndex, attachExcerpts, expandQuery, } from '../../core/searchIndex.js';
+import { buildSemanticIndex, semanticSearch, reciprocalRankFusion, } from '../../core/semanticSearch.js';
+import { isSemanticAvailable } from '../../core/embeddings.js';
+import { paginate, listChecksum, readPageParams } from '../pagination.js';
+import { PACKAGE_ARG_SCHEMA, resolvePackageFilter } from './_shared.js';
+export const searchTool = {
+    name: 'projscan_search',
+    description: 'Ranked search across the project. Lexical (BM25) by default; optional semantic (vector) and hybrid (RRF fusion) modes available when the @xenova/transformers peer dependency is installed. Scope controls what to search: "auto"/"content" (ranked content matches with excerpts), "symbols" (exported names), "files" (path substring).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Search string. Multi-word queries are treated as OR across BM25 terms; semantic mode embeds the full query.',
+            },
+            scope: {
+                type: 'string',
+                description: 'What to search over: "auto" (= content), "symbols", "files", "content".',
+                enum: ['auto', 'symbols', 'files', 'content'],
+            },
+            mode: {
+                type: 'string',
+                description: '"lexical" (default, BM25) | "semantic" (embeddings, requires peer dep) | "hybrid" (BM25 + semantic via reciprocal rank fusion). Ignored for "symbols" and "files" scopes.',
+                enum: ['lexical', 'semantic', 'hybrid'],
+            },
+            limit: { type: 'number', description: 'Max matches returned (default 30).' },
+            max_tokens: { type: 'number', description: 'Cap the response to roughly this many tokens.' },
+            package: PACKAGE_ARG_SCHEMA,
+        },
+        required: ['query'],
+    },
+    handler: async (args, rootPath) => {
+        const query = String(args.query ?? '').trim();
+        if (!query)
+            throw new Error('query argument is required and must be non-empty');
+        const scope = String(args.scope ?? 'auto');
+        const limit = Math.max(1, Math.min(500, typeof args.limit === 'number' ? args.limit : 30));
+        const scan = await scanRepository(rootPath);
+        const cached = await loadCachedGraph(rootPath);
+        const graph = await buildCodeGraph(rootPath, scan.files, cached);
+        await saveCachedGraph(rootPath, graph);
+        const passes = await resolvePackageFilter(rootPath, args);
+        if (scope === 'files') {
+            const q = query.toLowerCase();
+            const all = scan.files
+                .filter((f) => f.relativePath.toLowerCase().includes(q))
+                .filter((f) => !passes || passes(f.relativePath))
+                .map((f) => ({ file: f.relativePath, sizeBytes: f.sizeBytes }));
+            const page = paginate(all, readPageParams(args), listChecksum(all));
+            return { scope, query, matches: page.items, total: page.total, nextCursor: page.nextCursor };
+        }
+        if (scope === 'symbols') {
+            const q = query.toLowerCase();
+            const rawMatches = [];
+            for (const [file, entry] of graph.files) {
+                if (passes && !passes(file))
+                    continue;
+                for (const exp of entry.exports) {
+                    const name = exp.name.toLowerCase();
+                    if (!name.includes(q))
+                        continue;
+                    const rank = name === q ? 0 : name.startsWith(q) ? 1 : 2;
+                    rawMatches.push({ symbol: exp.name, kind: exp.kind, file, line: exp.line, rank });
+                }
+            }
+            rawMatches.sort((a, b) => a.rank - b.rank);
+            const cleaned = rawMatches.map((m) => ({
+                symbol: m.symbol,
+                kind: m.kind,
+                file: m.file,
+                line: m.line,
+            }));
+            const page = paginate(cleaned, readPageParams(args), listChecksum(cleaned));
+            return { scope, query, matches: page.items, total: page.total, nextCursor: page.nextCursor };
+        }
+        const mode = String(args.mode ?? 'lexical');
+        const index = await buildSearchIndex(rootPath, scan.files, graph);
+        const lexicalHitsAll = searchIndex(index, query, { limit });
+        const lexicalHits = passes ? lexicalHitsAll.filter((h) => passes(h.file)) : lexicalHitsAll;
+        const tokens = expandQuery(query);
+        if (mode === 'lexical') {
+            const withExcerpts = await attachExcerpts(rootPath, lexicalHits, tokens);
+            const page = paginate(withExcerpts, readPageParams(args), listChecksum(withExcerpts));
+            return {
+                scope: scope === 'auto' ? 'content' : scope,
+                mode: 'lexical',
+                query,
+                queryTokens: tokens,
+                matches: page.items,
+                total: page.total,
+                nextCursor: page.nextCursor,
+            };
+        }
+        const hasSemantic = await isSemanticAvailable();
+        if (!hasSemantic) {
+            return {
+                scope: scope === 'auto' ? 'content' : scope,
+                mode,
+                query,
+                error: 'Semantic search requires the optional peer dependency @xenova/transformers. Install it with: npm install @xenova/transformers',
+                available: false,
+                matches: [],
+                total: 0,
+            };
+        }
+        const semIndex = await buildSemanticIndex(rootPath, scan.files);
+        if (!semIndex) {
+            return {
+                scope: scope === 'auto' ? 'content' : scope,
+                mode,
+                query,
+                error: 'Semantic index build failed (peer loaded but model not usable).',
+                available: false,
+                matches: [],
+                total: 0,
+            };
+        }
+        const semHitsAll = await semanticSearch(semIndex, query, { limit });
+        const semHits = passes ? semHitsAll.filter((h) => passes(h.file)) : semHitsAll;
+        if (mode === 'semantic') {
+            const enriched = await attachExcerpts(rootPath, semHits.map((h) => ({
+                file: h.file,
+                score: h.score,
+                matched: [],
+                symbolMatch: false,
+                pathMatch: false,
+                excerpt: '',
+                line: 0,
+            })), tokens);
+            const page = paginate(enriched, readPageParams(args), listChecksum(enriched));
+            return {
+                scope: scope === 'auto' ? 'content' : scope,
+                mode: 'semantic',
+                query,
+                model: semIndex.model,
+                matches: page.items,
+                total: page.total,
+                nextCursor: page.nextCursor,
+            };
+        }
+        const fused = reciprocalRankFusion([lexicalHits, semHits]).slice(0, limit);
+        const enriched = await attachExcerpts(rootPath, fused.map((f) => ({
+            file: f.file,
+            score: f.score,
+            matched: [],
+            symbolMatch: false,
+            pathMatch: false,
+            excerpt: '',
+            line: 0,
+        })), tokens);
+        const page = paginate(enriched, readPageParams(args), listChecksum(enriched));
+        return {
+            scope: scope === 'auto' ? 'content' : scope,
+            mode: 'hybrid',
+            query,
+            queryTokens: tokens,
+            model: semIndex.model,
+            matches: page.items,
+            total: page.total,
+            nextCursor: page.nextCursor,
+        };
+    },
+};
+//# sourceMappingURL=search.js.map