projscan 3.8.0 → 4.1.0

package/scripts/capture-readme-assets.mjs

@@ -0,0 +1,60 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const demoPath = path.join(repoRoot, 'docs', 'demos', 'projscan-4-1-demo.html');
+
+if (!existsSync(demoPath)) {
+  console.error(`Missing capture source: ${path.relative(repoRoot, demoPath)}`);
+  process.exit(1);
+}
+
+const captures = [
+  {
+    name: 'Mission Control hero',
+    url: pathToFileURL(demoPath).href,
+    output: path.join(repoRoot, 'docs', 'projscan-mission-control.png'),
+    viewport: '1440,960',
+  },
+  {
+    name: 'Intent and proof workflow',
+    url: `${pathToFileURL(demoPath).href}#proof`,
+    output: path.join(repoRoot, 'docs', 'projscan-proof-router.png'),
+    viewport: '1440,760',
+  },
+];
+
+for (const capture of captures) {
+  console.log(`Capturing ${capture.name} -> ${path.relative(repoRoot, capture.output)}`);
+  const result = spawnSync(
+    'npx',
+    [
+      '--yes',
+      'playwright',
+      'screenshot',
+      '--browser',
+      'chromium',
+      '--viewport-size',
+      capture.viewport,
+      '--wait-for-selector',
+      '[data-ready="true"]',
+      capture.url,
+      capture.output,
+    ],
+    {
+      cwd: repoRoot,
+      stdio: 'inherit',
+    },
+  );
+
+  if (result.status !== 0) {
+    console.error(
+      'Playwright screenshot capture failed. If Chromium is missing locally, run: npx --yes playwright install chromium',
+    );
+    process.exit(result.status ?? 1);
+  }
+}
+
+console.log('README screenshots captured.');

package/dist/cli/commands/explain.d.ts

@@ -1 +0,0 @@
-export declare function registerExplain(): void;

package/dist/cli/commands/explain.js

@@ -1,48 +0,0 @@
-import chalk from 'chalk';
-import path from 'node:path';
-import { program, setupLogLevel, maybeCompactBanner, analyzeFile, assertFormatSupported } from '../_shared.js';
-import { reportExplanation } from '../../reporters/consoleReporter.js';
-import { reportExplanationJson } from '../../reporters/jsonReporter.js';
-import { reportExplanationMarkdown } from '../../reporters/markdownReporter.js';
-import { formatCliDeprecationNotice } from '../../core/deprecations.js';
-export function registerExplain() {
-    program
-        .command('explain <file>')
-        .description('Explain a file - its purpose, dependencies, and exports')
-        .action(async (filePath) => {
-        setupLogLevel();
-        maybeCompactBanner();
-        console.error(chalk.yellow(formatCliDeprecationNotice('explain', {
-            since: '3.8.0',
-            replacedBy: 'projscan file',
-            note: 'projscan file is a strict superset (adds churn, risk, ownership, and related health).',
-        })));
-        const format = assertFormatSupported('explain');
-        const absolutePath = path.resolve(filePath);
-        try {
-            const explanation = await analyzeFile(absolutePath);
-            switch (format) {
-                case 'json':
-                    reportExplanationJson(explanation);
-                    break;
-                case 'markdown':
-                    reportExplanationMarkdown(explanation);
-                    break;
-                default:
-                    reportExplanation(explanation);
-            }
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (error.code === 'ENOENT' || /not found/i.test(message)) {
-                console.error(chalk.red(`File not found: ${filePath}`));
-                console.error(chalk.dim(`  Tip: paths are repo-relative. Run \`projscan structure\` to see the file tree.`));
-            }
-            else {
-                console.error(chalk.red(message));
-            }
-            process.exit(1);
-        }
-    });
-}
-//# sourceMappingURL=explain.js.map

package/dist/cli/commands/explain.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/cli/commands/explain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC/G,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAChF,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAExE,MAAM,UAAU,eAAe;IAC7B,OAAO;SACJ,OAAO,CAAC,gBAAgB,CAAC;SACzB,WAAW,CAAC,yDAAyD,CAAC;SACtE,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,EAAE;QACjC,aAAa,EAAE,CAAC;QAChB,kBAAkB,EAAE,CAAC;QACrB,OAAO,CAAC,KAAK,CACX,KAAK,CAAC,MAAM,CACV,0BAA0B,CAAC,SAAS,EAAE;YACpC,KAAK,EAAE,OAAO;YACd,UAAU,EAAE,eAAe;YAC3B,IAAI,EAAE,uFAAuF;SAC9F,CAAC,CACH,CACF,CAAC;QACF,MAAM,MAAM,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;QAChD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAE5C,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,MAAM,WAAW,CAAC,YAAY,CAAC,CAAC;YAEpD,QAAQ,MAAM,EAAE,CAAC;gBACf,KAAK,MAAM;oBACT,qBAAqB,CAAC,WAAW,CAAC,CAAC;oBACnC,MAAM;gBACR,KAAK,UAAU;oBACb,yBAAyB,CAAC,WAAW,CAAC,CAAC;oBACvC,MAAM;gBACR;oBACE,iBAAiB,CAAC,WAAW,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrF,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC,CAAC;gBACxD,OAAO,CAAC,KAAK,CACX,KAAK,CAAC,GAAG,CAAC,kFAAkF,CAAC,CAC9F,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

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

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

package/dist/mcp/tools/explain.js

@@ -1,34 +0,0 @@
-import path from 'node:path';
-import { explainFile } from './_shared.js';
-export const explainTool = {
-    name: 'projscan_explain',
-    deprecated: {
-        since: '3.8.0',
-        replacedBy: 'projscan_file',
-        note: 'projscan_file is a strict superset (same purpose/imports/exports plus churn, risk, ownership, and related health).',
-    },
-    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: pass a repo-relative path (e.g. "src/auth.ts").');
-        }
-        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 (got "${rel}"; absolute or "../" paths are rejected for security).`);
-        }
-        return await explainFile(absolutePath, rootPath);
-    },
-};
-//# sourceMappingURL=explain.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/mcp/tools/explain.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAgB,MAAM,cAAc,CAAC;AAEzD,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,IAAI,EAAE,kBAAkB;IACxB,UAAU,EAAE;QACV,KAAK,EAAE,OAAO;QACd,UAAU,EAAE,eAAe;QAC3B,IAAI,EAAE,oHAAoH;KAC3H;IACD,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,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CACb,4EAA4E,CAC7E,CAAC;QACJ,CAAC;QACD,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,CACb,8CAA8C,GAAG,wDAAwD,CAC1G,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,WAAW,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;CACF,CAAC"}

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

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

package/dist/mcp/tools/graph.js

@@ -1,79 +0,0 @@
-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',
-    deprecated: {
-        since: '3.8.0',
-        replacedBy: 'projscan_semantic_graph',
-        note: 'projscan_semantic_graph is the stable v3 successor (same nodes/edges with a versioned, supported contract).',
-    },
-    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('direction=imports requires a `file` argument (repo-relative path, e.g. "src/auth.ts").');
-                }
-                return { file, imports: importsOf(graph, file).slice(0, limit) };
-            }
-            case 'exports': {
-                if (!file) {
-                    throw new Error('direction=exports requires a `file` argument (repo-relative path).');
-                }
-                return { file, exports: exportsOf(graph, file).slice(0, limit) };
-            }
-            case 'importers': {
-                if (!file) {
-                    throw new Error('direction=importers requires a `file` argument (repo-relative path).');
-                }
-                return { file, importers: filesImportingFile(graph, file).slice(0, limit) };
-            }
-            case 'symbol_defs': {
-                if (!symbol) {
-                    throw new Error('direction=symbol_defs requires a `symbol` argument (the exported name to look up, e.g. "authenticate").');
-                }
-                return { symbol, definedIn: filesDefiningSymbol(graph, symbol).slice(0, limit) };
-            }
-            case 'package_importers': {
-                const pkg = symbol ?? file;
-                if (!pkg) {
-                    throw new Error('direction=package_importers requires either `symbol` or `file` arg (the npm package name, e.g. "chalk").');
-                }
-                return { package: pkg, importers: filesImportingPackage(graph, pkg).slice(0, limit) };
-            }
-            default:
-                throw new Error(`unknown direction "${direction}". Valid: imports, exports, importers, symbol_defs, package_importers.`);
-        }
-    },
-};
-//# sourceMappingURL=graph.js.map

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

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