projscan 0.10.0 → 0.12.0

package/dist/core/prDiff.js

@@ -0,0 +1,298 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { scanRepository } from './repositoryScanner.js';
+import { buildCodeGraph } from './codeGraph.js';
+/**
+ * Compute a structural diff between two refs by building a CodeGraph for each
+ * side and comparing exports / imports / call sites / cyclomatic complexity /
+ * fan-in.
+ *
+ * Strategy: stand up a throwaway git worktree at the base ref, scan it like
+ * any other project, build its graph, then diff against the head graph
+ * (caller passes head graph in or the function builds one from `rootPath`).
+ *
+ * This is "structural diff", not text diff: agents reviewing PRs care about
+ * "what's the new export surface" and "which call sites disappeared", not
+ * "what whitespace changed on line 42."
+ */
+export async function computePrDiff(rootPath, options = {}) {
+    const isRepo = await isGitRepository(rootPath);
+    if (!isRepo) {
+        return {
+            available: false,
+            reason: 'Not a git repository - PR diff requires git history.',
+            base: { ref: '', resolvedSha: null },
+            head: { ref: '', resolvedSha: null },
+            filesAdded: [],
+            filesRemoved: [],
+            filesModified: [],
+            totalFilesChanged: 0,
+        };
+    }
+    const headRef = options.head ?? 'HEAD';
+    const baseRef = options.base ?? (await pickDefaultBase(rootPath));
+    const headSha = await resolveSha(rootPath, headRef);
+    const baseSha = await resolveSha(rootPath, baseRef);
+    if (!baseSha) {
+        return {
+            available: false,
+            reason: `Could not resolve base ref "${baseRef}".`,
+            base: { ref: baseRef, resolvedSha: null },
+            head: { ref: headRef, resolvedSha: headSha },
+            filesAdded: [],
+            filesRemoved: [],
+            filesModified: [],
+            totalFilesChanged: 0,
+        };
+    }
+    // Build the head graph from rootPath as-is (the working tree).
+    const headScan = await scanRepository(rootPath);
+    const headGraph = await buildCodeGraph(rootPath, headScan.files);
+    // Stand up a worktree at the base ref and scan it.
+    const worktreeDir = await mkTempWorktreeDir();
+    let baseGraph;
+    try {
+        await runGit(rootPath, ['worktree', 'add', '--detach', worktreeDir, baseSha]);
+        const baseScan = await scanRepository(worktreeDir);
+        baseGraph = await buildCodeGraph(worktreeDir, baseScan.files);
+    }
+    finally {
+        // Best-effort tear-down. `git worktree remove --force` handles the case
+        // where the worktree dir is somehow non-empty.
+        await runGit(rootPath, ['worktree', 'remove', '--force', worktreeDir]).catch(() => { });
+        await fs.rm(worktreeDir, { recursive: true, force: true }).catch(() => { });
+    }
+    return diffGraphs(baseRef, baseSha, headRef, headSha, baseGraph, headGraph);
+}
+/** Pure function - exported for unit testing without a real git repo. */
+export function diffGraphs(baseRef, baseSha, headRef, headSha, baseGraph, headGraph) {
+    const filesAdded = [];
+    const filesRemoved = [];
+    const filesModified = [];
+    const allFiles = new Set([...baseGraph.files.keys(), ...headGraph.files.keys()]);
+    for (const file of allFiles) {
+        const baseEntry = baseGraph.files.get(file);
+        const headEntry = headGraph.files.get(file);
+        if (!baseEntry && headEntry) {
+            filesAdded.push(file);
+            continue;
+        }
+        if (baseEntry && !headEntry) {
+            filesRemoved.push(file);
+            continue;
+        }
+        if (!baseEntry || !headEntry)
+            continue; // unreachable, satisfies TS
+        // Modified files: structural compare.
+        const exportsBase = new Set(baseEntry.exports.map((e) => e.name));
+        const exportsHead = new Set(headEntry.exports.map((e) => e.name));
+        const importsBase = new Set(baseEntry.imports.map((i) => i.source));
+        const importsHead = new Set(headEntry.imports.map((i) => i.source));
+        const callsBase = new Set(baseEntry.callSites);
+        const callsHead = new Set(headEntry.callSites);
+        const rawExportsAdded = [...exportsHead].filter((x) => !exportsBase.has(x));
+        const rawExportsRemoved = [...exportsBase].filter((x) => !exportsHead.has(x));
+        // Pull out renames first; whatever's left stays as +/-.
+        const { renames, addedAfter, removedAfter } = detectRenames(rawExportsRemoved, rawExportsAdded);
+        const exportsAdded = addedAfter;
+        const exportsRemoved = removedAfter;
+        const exportsRenamed = renames;
+        const importsAdded = [...importsHead].filter((x) => !importsBase.has(x));
+        const importsRemoved = [...importsBase].filter((x) => !importsHead.has(x));
+        const callsAdded = [...callsHead].filter((x) => !callsBase.has(x));
+        const callsRemoved = [...callsBase].filter((x) => !callsHead.has(x));
+        const ccDelta = baseEntry.parseOk && headEntry.parseOk
+            ? headEntry.cyclomaticComplexity - baseEntry.cyclomaticComplexity
+            : null;
+        const fanInBase = baseGraph.localImporters.get(file)?.size ?? 0;
+        const fanInHead = headGraph.localImporters.get(file)?.size ?? 0;
+        const fanInDelta = fanInHead - fanInBase;
+        const hasChange = exportsAdded.length +
+            exportsRemoved.length +
+            exportsRenamed.length +
+            importsAdded.length +
+            importsRemoved.length +
+            callsAdded.length +
+            callsRemoved.length >
+            0 ||
+            (ccDelta !== null && ccDelta !== 0) ||
+            fanInDelta !== 0;
+        if (!hasChange)
+            continue;
+        filesModified.push({
+            relativePath: file,
+            status: 'modified',
+            exportsAdded: exportsAdded.sort(),
+            exportsRemoved: exportsRemoved.sort(),
+            exportsRenamed,
+            importsAdded: importsAdded.sort(),
+            importsRemoved: importsRemoved.sort(),
+            callsAdded: callsAdded.sort(),
+            callsRemoved: callsRemoved.sort(),
+            cyclomaticDelta: ccDelta,
+            fanInDelta,
+        });
+    }
+    filesAdded.sort();
+    filesRemoved.sort();
+    filesModified.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return {
+        available: true,
+        base: { ref: baseRef, resolvedSha: baseSha },
+        head: { ref: headRef, resolvedSha: headSha },
+        filesAdded,
+        filesRemoved,
+        filesModified,
+        totalFilesChanged: filesAdded.length + filesRemoved.length + filesModified.length,
+    };
+}
+export function detectRenames(removed, added) {
+    if (removed.length === 0 || added.length === 0) {
+        return { renames: [], removedAfter: removed.sort(), addedAfter: added.sort() };
+    }
+    const candidates = [];
+    for (const from of removed) {
+        for (const to of added) {
+            const score = similarity(from, to);
+            if (score >= 0.5)
+                candidates.push({ from, to, score });
+        }
+    }
+    // Greedy: pick highest scores first; each name can only be paired once.
+    candidates.sort((a, b) => b.score - a.score);
+    const usedFrom = new Set();
+    const usedTo = new Set();
+    const renames = [];
+    for (const c of candidates) {
+        if (usedFrom.has(c.from) || usedTo.has(c.to))
+            continue;
+        usedFrom.add(c.from);
+        usedTo.add(c.to);
+        renames.push({ from: c.from, to: c.to });
+    }
+    renames.sort((a, b) => a.from.localeCompare(b.from));
+    return {
+        renames,
+        removedAfter: removed.filter((n) => !usedFrom.has(n)).sort(),
+        addedAfter: added.filter((n) => !usedTo.has(n)).sort(),
+    };
+}
+function similarity(a, b) {
+    if (a === b)
+        return 1;
+    const maxLen = Math.max(a.length, b.length);
+    if (maxLen === 0)
+        return 1;
+    const dist = levenshtein(a, b);
+    const editScore = 1 - dist / maxLen;
+    const prefix = sharedPrefix(a, b);
+    const suffix = sharedSuffix(a, b);
+    const affixScore = Math.max(prefix, suffix) / maxLen;
+    // Take the stronger signal. Either evidence alone is enough to suspect a
+    // rename: a name that's mostly the same characters (high edit score) OR a
+    // name that shares a long prefix/suffix (e.g. `fetch` -> `fetchUser`).
+    return Math.max(editScore, affixScore);
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    // Two-row DP - small allocations keep this cheap on the realistic name sizes.
+    let prev = new Array(n + 1);
+    let curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}
+function sharedPrefix(a, b) {
+    const cap = Math.min(a.length, b.length);
+    let i = 0;
+    while (i < cap && a.charCodeAt(i) === b.charCodeAt(i))
+        i++;
+    return i;
+}
+function sharedSuffix(a, b) {
+    const cap = Math.min(a.length, b.length);
+    let i = 0;
+    while (i < cap && a.charCodeAt(a.length - 1 - i) === b.charCodeAt(b.length - 1 - i))
+        i++;
+    return i;
+}
+// ── git helpers ───────────────────────────────────────────
+async function isGitRepository(rootPath) {
+    const { code } = await runGit(rootPath, ['rev-parse', '--is-inside-work-tree']).catch(() => ({
+        code: 1,
+        stdout: '',
+        stderr: '',
+    }));
+    return code === 0;
+}
+async function resolveSha(rootPath, ref) {
+    const { code, stdout } = await runGit(rootPath, ['rev-parse', '--verify', `${ref}^{commit}`]).catch(() => ({ code: 1, stdout: '', stderr: '' }));
+    if (code !== 0)
+        return null;
+    const sha = stdout.trim();
+    return sha || null;
+}
+/** origin/main if it exists, else main, else master. Mirrors what most tooling does. */
+async function pickDefaultBase(rootPath) {
+    for (const candidate of ['origin/main', 'main', 'origin/master', 'master']) {
+        if (await resolveSha(rootPath, candidate))
+            return candidate;
+    }
+    return 'HEAD~1';
+}
+async function mkTempWorktreeDir() {
+    return fs.mkdtemp(path.join(os.tmpdir(), 'projscan-pr-diff-'));
+}
+function runGit(cwd, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', args, { cwd, env: process.env });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const timeout = opts.timeoutMs
+            ? setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                child.kill('SIGKILL');
+                reject(new Error('git command timed out'));
+            }, opts.timeoutMs)
+            : null;
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        child.stderr.on('data', (d) => (stderr += d.toString()));
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout)
+                clearTimeout(timeout);
+            reject(err);
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout)
+                clearTimeout(timeout);
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}
+//# sourceMappingURL=prDiff.js.map

package/dist/core/prDiff.js.map

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

package/dist/core/telemetry.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Opt-in, privacy-preserving telemetry (0.14).
+ *
+ * What it records: tool name, duration, success/failure, projscan version,
+ * iso timestamp. That's it. NO source content, NO file paths, NO arguments,
+ * NO repository identifiers, NO machine identifiers.
+ *
+ * What it does NOT do: send anything off the machine. The MVP sink is a
+ * local JSONL file the user controls. A remote sink may follow in a later
+ * release once we have a server worth pointing at.
+ *
+ * Discoverability: off by default. Enable via .projscanrc telemetry block,
+ * or PROJSCAN_TELEMETRY=1 env var (env wins). PROJSCAN_TELEMETRY=0 disables
+ * even when the config opts in (per-machine kill switch).
+ */
+export interface TelemetryConfig {
+    enabled: boolean;
+    /**
+     * Where to write events. Default: `~/.projscan/telemetry.jsonl`.
+     * Either a path or the literal string "stderr" (test/diagnostic use).
+     */
+    sink: string;
+}
+export interface TelemetryEvent {
+    ts: string;
+    version: string;
+    tool: string;
+    durationMs: number;
+    ok: boolean;
+    errorCode?: string;
+}
+/**
+ * Resolve effective config. Env var takes precedence; .projscanrc supplies
+ * the sink and acts as the default. Non-throwing — bad config silently
+ * disables.
+ */
+export declare function resolveTelemetryConfig(rcConfig?: {
+    enabled?: boolean;
+    sink?: string;
+}): TelemetryConfig;
+/** Test-only: drop the cached config so tests can mutate env between cases. */
+export declare function _resetTelemetryConfigForTests(): void;
+/**
+ * Fire-and-forget event recorder. Catches every error path so an unwritable
+ * sink can never affect the calling tool. Does nothing when disabled.
+ */
+export declare function recordToolCall(tool: string, durationMs: number, ok: boolean, errorCode?: string, rcConfig?: {
+    enabled?: boolean;
+    sink?: string;
+}): Promise<void>;
+/** Returns the JSON used by `projscan_telemetry` to surface state to the user. */
+export declare function describeTelemetryConfig(rcConfig?: {
+    enabled?: boolean;
+    sink?: string;
+}): TelemetryConfig & {
+    defaultSink: string;
+    envOverride: string | null;
+};
+export interface ToolHistogram {
+    tool: string;
+    count: number;
+    errorCount: number;
+    errorRate: number;
+    /** Latency percentiles (ms). null when count is 0 (shouldn't happen post-filter). */
+    p50Ms: number | null;
+    p95Ms: number | null;
+    p99Ms: number | null;
+    meanMs: number;
+    minMs: number;
+    maxMs: number;
+}
+export interface TelemetryAggregate {
+    available: boolean;
+    reason?: string;
+    sink: string;
+    totalEvents: number;
+    windowFrom: string | null;
+    windowTo: string | null;
+    byTool: ToolHistogram[];
+}
+/**
+ * Read the JSONL sink and bucket events by tool, returning latency
+ * percentiles per tool. Returns available:false (with a reason) when the
+ * sink doesn't exist yet — typical case for users who haven't enabled
+ * telemetry or haven't run anything yet.
+ */
+export declare function aggregateTelemetry(rcConfig?: {
+    enabled?: boolean;
+    sink?: string;
+}): Promise<TelemetryAggregate>;

package/dist/core/telemetry.js

@@ -0,0 +1,199 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const DEFAULT_SINK_DIR = path.join(os.homedir(), '.projscan');
+const DEFAULT_SINK_FILE = path.join(DEFAULT_SINK_DIR, 'telemetry.jsonl');
+let cachedConfig;
+let cachedVersion;
+/**
+ * Resolve effective config. Env var takes precedence; .projscanrc supplies
+ * the sink and acts as the default. Non-throwing — bad config silently
+ * disables.
+ */
+export function resolveTelemetryConfig(rcConfig) {
+    if (cachedConfig)
+        return cachedConfig;
+    const envFlag = process.env.PROJSCAN_TELEMETRY;
+    let enabled = !!rcConfig?.enabled;
+    if (envFlag === '1' || envFlag?.toLowerCase() === 'true')
+        enabled = true;
+    if (envFlag === '0' || envFlag?.toLowerCase() === 'false')
+        enabled = false;
+    const sink = rcConfig?.sink || DEFAULT_SINK_FILE;
+    cachedConfig = { enabled, sink };
+    return cachedConfig;
+}
+/** Test-only: drop the cached config so tests can mutate env between cases. */
+export function _resetTelemetryConfigForTests() {
+    cachedConfig = undefined;
+    cachedVersion = undefined;
+}
+function readVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        const __dirname = path.dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '../../package.json'), 'utf-8'));
+        cachedVersion = String(pkg.version ?? '0.0.0');
+    }
+    catch {
+        cachedVersion = '0.0.0';
+    }
+    return cachedVersion;
+}
+/**
+ * Fire-and-forget event recorder. Catches every error path so an unwritable
+ * sink can never affect the calling tool. Does nothing when disabled.
+ */
+export async function recordToolCall(tool, durationMs, ok, errorCode, rcConfig) {
+    const config = resolveTelemetryConfig(rcConfig);
+    if (!config.enabled)
+        return;
+    const event = {
+        ts: new Date().toISOString(),
+        version: readVersion(),
+        tool,
+        durationMs: Math.round(durationMs),
+        ok,
+    };
+    if (errorCode)
+        event.errorCode = errorCode;
+    try {
+        if (config.sink === 'stderr') {
+            process.stderr.write(`[telemetry] ${JSON.stringify(event)}\n`);
+            return;
+        }
+        await fs.mkdir(path.dirname(config.sink), { recursive: true });
+        await fs.appendFile(config.sink, JSON.stringify(event) + '\n', 'utf-8');
+    }
+    catch {
+        // Sink failures are silent by design. Telemetry must never break a tool.
+    }
+}
+/** Returns the JSON used by `projscan_telemetry` to surface state to the user. */
+export function describeTelemetryConfig(rcConfig) {
+    const config = resolveTelemetryConfig(rcConfig);
+    const env = process.env.PROJSCAN_TELEMETRY ?? null;
+    return {
+        ...config,
+        defaultSink: DEFAULT_SINK_FILE,
+        envOverride: env,
+    };
+}
+/**
+ * Read the JSONL sink and bucket events by tool, returning latency
+ * percentiles per tool. Returns available:false (with a reason) when the
+ * sink doesn't exist yet — typical case for users who haven't enabled
+ * telemetry or haven't run anything yet.
+ */
+export async function aggregateTelemetry(rcConfig) {
+    const config = resolveTelemetryConfig(rcConfig);
+    const sinkPath = config.sink === 'stderr' ? '' : config.sink;
+    if (!sinkPath) {
+        return {
+            available: false,
+            reason: 'Sink is "stderr"; nothing to aggregate from disk.',
+            sink: config.sink,
+            totalEvents: 0,
+            windowFrom: null,
+            windowTo: null,
+            byTool: [],
+        };
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(sinkPath, 'utf-8');
+    }
+    catch {
+        return {
+            available: false,
+            reason: `No telemetry sink found at ${sinkPath}. Enable telemetry and run a few tools first.`,
+            sink: sinkPath,
+            totalEvents: 0,
+            windowFrom: null,
+            windowTo: null,
+            byTool: [],
+        };
+    }
+    const events = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const obj = JSON.parse(trimmed);
+            if (typeof obj?.tool === 'string' && typeof obj?.durationMs === 'number') {
+                events.push(obj);
+            }
+        }
+        catch {
+            // Skip malformed lines silently — JSONL files can be partially written
+            // when a process is killed mid-append.
+        }
+    }
+    if (events.length === 0) {
+        return {
+            available: true,
+            sink: sinkPath,
+            totalEvents: 0,
+            windowFrom: null,
+            windowTo: null,
+            byTool: [],
+        };
+    }
+    const byToolMap = new Map();
+    let windowFrom = events[0].ts;
+    let windowTo = events[0].ts;
+    for (const e of events) {
+        if (e.ts < windowFrom)
+            windowFrom = e.ts;
+        if (e.ts > windowTo)
+            windowTo = e.ts;
+        if (!byToolMap.has(e.tool))
+            byToolMap.set(e.tool, []);
+        byToolMap.get(e.tool).push(e);
+    }
+    const byTool = [];
+    for (const [tool, toolEvents] of byToolMap) {
+        const durations = toolEvents.map((e) => e.durationMs).sort((a, b) => a - b);
+        const errorCount = toolEvents.filter((e) => e.ok === false).length;
+        byTool.push({
+            tool,
+            count: toolEvents.length,
+            errorCount,
+            errorRate: Math.round((errorCount / toolEvents.length) * 1000) / 1000,
+            p50Ms: percentile(durations, 50),
+            p95Ms: percentile(durations, 95),
+            p99Ms: percentile(durations, 99),
+            meanMs: Math.round(durations.reduce((s, n) => s + n, 0) / durations.length),
+            minMs: durations[0],
+            maxMs: durations[durations.length - 1],
+        });
+    }
+    byTool.sort((a, b) => b.count - a.count);
+    return {
+        available: true,
+        sink: sinkPath,
+        totalEvents: events.length,
+        windowFrom,
+        windowTo,
+        byTool,
+    };
+}
+/** Linear-interpolation percentile over a pre-sorted ascending array. */
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return null;
+    if (sorted.length === 1)
+        return sorted[0];
+    const rank = (p / 100) * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    if (lo === hi)
+        return sorted[lo];
+    const frac = rank - lo;
+    return Math.round(sorted[lo] * (1 - frac) + sorted[hi] * frac);
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/core/telemetry.js.map

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

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

@@ -0,0 +1,24 @@
+import type { FileEntry, FileExplanation, McpToolDefinition, DirectoryNode } from '../../types.js';
+export interface McpToolHandler {
+    (args: Record<string, unknown>, rootPath: string): Promise<unknown>;
+}
+export interface McpTool extends McpToolDefinition {
+    handler: McpToolHandler;
+}
+/**
+ * A repo is "Python-dominated" if it has a pyproject.toml OR setup.py AND
+ * either no node_modules directory or no package.json.
+ */
+export declare function isPythonDominated(rootPath: string, files: FileEntry[]): Promise<boolean>;
+/**
+ * Resolve the `package` arg to a (file -> boolean) filter, or null when
+ * scoping wasn't requested.
+ */
+export declare function resolvePackageFilter(rootPath: string, args: Record<string, unknown>): Promise<((file: string) => boolean) | null>;
+export declare const PACKAGE_ARG_SCHEMA: {
+    readonly type: "string";
+    readonly description: "Optional. Workspace package name (from projscan_workspaces) to scope results to one package only.";
+};
+/** Walk a DirectoryNode tree to find the node whose `path` equals targetPath. */
+export declare function sliceTree(node: DirectoryNode, targetPath: string): DirectoryNode | null;
+export declare function explainFile(absolutePath: string, content: string, rootPath: string): FileExplanation;