projscan 0.9.2 → 0.11.0

package/dist/analyzers/pythonTestCheck.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const TEST_FRAMEWORKS = ['pytest', 'unittest', 'nose', 'nose2', 'ward'];
+function isPythonTestFile(rel) {
+    const base = path.basename(rel);
+    if (/^test_.+\.py$/.test(base))
+        return true;
+    if (/^.+_test\.py$/.test(base))
+        return true;
+    if (rel.startsWith('tests/') || rel.includes('/tests/'))
+        return base.endsWith('.py');
+    return false;
+}
+async function tryRead(absolutePath) {
+    try {
+        return await fs.readFile(absolutePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+export async function check(rootPath, files) {
+    const hasPython = files.some((f) => f.extension === '.py' || f.extension === '.pyw');
+    if (!hasPython)
+        return [];
+    const pyproject = await tryRead(path.join(rootPath, 'pyproject.toml'));
+    const setupCfg = await tryRead(path.join(rootPath, 'setup.cfg'));
+    const pytestIni = await tryRead(path.join(rootPath, 'pytest.ini'));
+    const toxIni = await tryRead(path.join(rootPath, 'tox.ini'));
+    // Collect all requirements*.txt contents into one searchable blob.
+    const reqRels = files
+        .filter((f) => (!f.directory || f.directory === '.') &&
+        /^requirements(-.*)?\.txt$/i.test(path.basename(f.relativePath)))
+        .map((f) => f.relativePath);
+    let requirementsBlob = '';
+    for (const rel of reqRels) {
+        const content = await tryRead(path.join(rootPath, rel));
+        if (content)
+            requirementsBlob += content + '\n';
+    }
+    let hasFramework = false;
+    const manifestHaystack = [pyproject ?? '', setupCfg ?? '', requirementsBlob].join('\n');
+    for (const fw of TEST_FRAMEWORKS) {
+        // Use a word-boundary-ish match so "pytest" doesn't spuriously match "pytest-cov"
+        // for purposes of "is pytest the framework?" - but we also accept pytest-*, so
+        // a simple case-insensitive containment is fine in practice.
+        const re = new RegExp(`(^|[\\s"'\`\\[\\],={}><~^!;])${fw}(\\b|[^a-zA-Z0-9_.-])`, 'im');
+        if (re.test(manifestHaystack)) {
+            hasFramework = true;
+            break;
+        }
+    }
+    if (!hasFramework && pytestIni !== null)
+        hasFramework = true;
+    if (!hasFramework && toxIni !== null && /\[pytest\]|\[tool:pytest\]|pytest/i.test(toxIni)) {
+        hasFramework = true;
+    }
+    if (!hasFramework && pyproject !== null && /\[tool\.pytest\.ini_options\]/.test(pyproject)) {
+        hasFramework = true;
+    }
+    // Last-resort detection: `import unittest` (or `from unittest ...`) inside a
+    // pytest-conventional test file. Some projects rely on stdlib unittest and
+    // never declare a framework in manifests.
+    const testFiles = files.filter((f) => isPythonTestFile(f.relativePath));
+    if (!hasFramework) {
+        for (const f of testFiles) {
+            const content = await tryRead(f.absolutePath);
+            if (content && /^\s*(import\s+unittest|from\s+unittest\s+import)/m.test(content)) {
+                hasFramework = true;
+                break;
+            }
+        }
+    }
+    const issues = [];
+    if (!hasFramework) {
+        issues.push({
+            id: 'missing-python-test-framework',
+            title: 'No Python test framework detected',
+            description: 'No pytest/unittest configuration or dependency found. Testing is essential for code quality and reliability.',
+            severity: 'warning',
+            category: 'testing',
+            fixAvailable: false,
+        });
+    }
+    else if (testFiles.length === 0) {
+        issues.push({
+            id: 'no-python-test-files',
+            title: 'No Python test files found',
+            description: 'A Python test framework is configured but no test files were found (expected test_*.py, *_test.py, or under tests/).',
+            severity: 'info',
+            category: 'testing',
+            fixAvailable: false,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=pythonTestCheck.js.map

package/dist/analyzers/pythonTestCheck.js.map

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

package/dist/analyzers/pythonUnusedDependencyCheck.d.ts

@@ -0,0 +1,2 @@
+import type { FileEntry, Issue } from '../types.js';
+export declare function check(rootPath: string, files: FileEntry[]): Promise<Issue[]>;

package/dist/analyzers/pythonUnusedDependencyCheck.js

@@ -0,0 +1,76 @@
+import { detectPythonProject } from '../core/languages/pythonManifests.js';
+import { buildCodeGraph } from '../core/codeGraph.js';
+// Packages whose presence in manifests is implicit (build-time, test-time,
+// or tooling) and which typically won't appear in `import` statements.
+const IMPLICIT_USE = new Set([
+    'pytest',
+    'pytest-cov',
+    'pytest-mock',
+    'pytest-asyncio',
+    'pytest-xdist',
+    'ruff',
+    'black',
+    'mypy',
+    'coverage',
+    'wheel',
+    'build',
+    'setuptools',
+    'setuptools-scm',
+    'pip',
+    'pip-tools',
+    'twine',
+    'flake8',
+    'pylint',
+    'pyflakes',
+    'isort',
+    'bandit',
+    'tox',
+    'pre-commit',
+    'hatch',
+    'hatchling',
+    'poetry-core',
+    'maturin',
+]);
+/**
+ * Normalize a package name for comparison. PyPI names are case-insensitive
+ * and `_` / `-` / `.` are interchangeable per PEP 503.
+ */
+function normalize(name) {
+    return name.toLowerCase().replace(/[_.]/g, '-');
+}
+export async function check(rootPath, files) {
+    const info = await detectPythonProject(rootPath, files);
+    if (!info || info.declared.length === 0)
+        return [];
+    const pythonFiles = files.filter((f) => f.extension === '.py' || f.extension === '.pyw');
+    if (pythonFiles.length === 0)
+        return [];
+    const graph = await buildCodeGraph(rootPath, pythonFiles);
+    const usedPackages = new Set();
+    for (const pkg of graph.packageImporters.keys()) {
+        usedPackages.add(normalize(pkg));
+    }
+    const issues = [];
+    const seen = new Set();
+    for (const dep of info.declared) {
+        const norm = normalize(dep.name);
+        if (seen.has(norm))
+            continue;
+        if (IMPLICIT_USE.has(norm))
+            continue;
+        if (usedPackages.has(norm))
+            continue;
+        seen.add(norm);
+        issues.push({
+            id: `unused-python-dependency-${dep.name}`,
+            title: `Unused Python dependency: ${dep.name}`,
+            description: `\`${dep.name}\` is declared in ${dep.source} but no source file imports it. Either remove it or add it to the implicit-use allowlist.`,
+            severity: dep.scope === 'dev' ? 'info' : 'warning',
+            category: 'dependencies',
+            fixAvailable: false,
+            locations: [{ file: dep.source, line: dep.line }],
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=pythonUnusedDependencyCheck.js.map

package/dist/analyzers/pythonUnusedDependencyCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pythonUnusedDependencyCheck.js","sourceRoot":"","sources":["../../src/analyzers/pythonUnusedDependencyCheck.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,2EAA2E;AAC3E,uEAAuE;AACvE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC;IAC3B,QAAQ;IACR,YAAY;IACZ,aAAa;IACb,gBAAgB;IAChB,cAAc;IACd,MAAM;IACN,OAAO;IACP,MAAM;IACN,UAAU;IACV,OAAO;IACP,OAAO;IACP,YAAY;IACZ,gBAAgB;IAChB,KAAK;IACL,WAAW;IACX,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,OAAO;IACP,QAAQ;IACR,KAAK;IACL,YAAY;IACZ,OAAO;IACP,WAAW;IACX,aAAa;IACb,SAAS;CACV,CAAC,CAAC;AAEH;;;GAGG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,QAAgB,EAAE,KAAkB;IAC9D,MAAM,IAAI,GAAG,MAAM,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACxD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnD,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,KAAK,IAAI,CAAC,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC;IACzF,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAExC,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC;QAChD,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC7B,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACrC,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAErC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,4BAA4B,GAAG,CAAC,IAAI,EAAE;YAC1C,KAAK,EAAE,6BAA6B,GAAG,CAAC,IAAI,EAAE;YAC9C,WAAW,EAAE,KAAK,GAAG,CAAC,IAAI,qBAAqB,GAAG,CAAC,MAAM,2FAA2F;YACpJ,QAAQ,EAAE,GAAG,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;YAClD,QAAQ,EAAE,cAAc;YACxB,YAAY,EAAE,KAAK;YACnB,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;SAClD,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cli/index.js

@@ -22,6 +22,10 @@ import { parseCoverage, coverageMap } from '../core/coverageParser.js';
 import { joinCoverageWithHotspots } from '../core/coverageJoin.js';
 import { buildCodeGraph } from '../core/codeGraph.js';
 import { loadCachedGraph, saveCachedGraph } from '../core/indexCache.js';
+import { computeCoupling, filterCoupling } from '../core/couplingAnalyzer.js';
+import { computePrDiff } from '../core/prDiff.js';
+import { detectWorkspaces, filterFilesByPackage } from '../core/monorepo.js';
+import { describeTelemetryConfig, aggregateTelemetry } from '../core/telemetry.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';
@@ -34,9 +38,9 @@ import { saveBaseline, loadBaseline, computeDiff } from '../utils/baseline.js';
 import { loadConfig, applyConfigToIssues } from '../utils/config.js';
 import { getChangedFiles } from '../utils/changedFiles.js';
 import { runMcpServer } from '../mcp/server.js';
-import { reportAnalysis, reportHealth, reportCi, reportDiff, reportDetectedIssues, reportExplanation, reportDiagram, reportStructure, reportDependencies, reportHotspots, reportFileInspection, reportOutdated, reportAudit, reportUpgrade, reportCoverage, } from '../reporters/consoleReporter.js';
-import { reportAnalysisJson, reportHealthJson, reportCiJson, reportDiffJson, reportExplanationJson, reportDiagramJson, reportStructureJson, reportDependenciesJson, reportHotspotsJson, reportFileJson, reportOutdatedJson, reportAuditJson, reportUpgradeJson, reportCoverageJson, } from '../reporters/jsonReporter.js';
-import { reportAnalysisMarkdown, reportHealthMarkdown, reportCiMarkdown, reportDiffMarkdown, reportExplanationMarkdown, reportDiagramMarkdown, reportStructureMarkdown, reportDependenciesMarkdown, reportHotspotsMarkdown, reportFileMarkdown, reportOutdatedMarkdown, reportAuditMarkdown, reportUpgradeMarkdown, reportCoverageMarkdown, } from '../reporters/markdownReporter.js';
+import { reportAnalysis, reportHealth, reportCi, reportDiff, reportDetectedIssues, reportExplanation, reportDiagram, reportStructure, reportDependencies, reportHotspots, reportFileInspection, reportOutdated, reportAudit, reportUpgrade, reportCoverage, reportCoupling, reportPrDiff, reportWorkspaces, } from '../reporters/consoleReporter.js';
+import { reportAnalysisJson, reportHealthJson, reportCiJson, reportDiffJson, reportExplanationJson, reportDiagramJson, reportStructureJson, reportDependenciesJson, reportHotspotsJson, reportFileJson, reportOutdatedJson, reportAuditJson, reportUpgradeJson, reportCoverageJson, reportCouplingJson, reportPrDiffJson, reportWorkspacesJson, } from '../reporters/jsonReporter.js';
+import { reportAnalysisMarkdown, reportHealthMarkdown, reportCiMarkdown, reportDiffMarkdown, reportExplanationMarkdown, reportDiagramMarkdown, reportStructureMarkdown, reportDependenciesMarkdown, reportHotspotsMarkdown, reportFileMarkdown, reportOutdatedMarkdown, reportAuditMarkdown, reportUpgradeMarkdown, reportCoverageMarkdown, reportCouplingMarkdown, reportPrDiffMarkdown, reportWorkspacesMarkdown, } from '../reporters/markdownReporter.js';
 import { reportAnalysisSarif, reportHealthSarif, reportCiSarif, issuesToSarif, } from '../reporters/sarifReporter.js';
 // ── CLI Setup ─────────────────────────────────────────────
 const program = new Command();
@@ -137,12 +141,24 @@ function maybeCompactBanner() {
         }
     }
 }
+/** Walk a DirectoryNode to find the node whose `path` matches targetPath. */
+function sliceCliTree(node, targetPath) {
+    if (node.path === targetPath)
+        return node;
+    for (const child of node.children) {
+        const hit = sliceCliTree(child, targetPath);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
 // ── Command: analyze (default) ────────────────────────────
 program
     .command('analyze', { isDefault: true })
     .description('Analyze repository and show project report')
     .option('--changed-only', 'only report issues on files changed vs base ref')
     .option('--base-ref <ref>', 'git base ref for --changed-only (default: origin/main)')
+    .option('--package <name>', 'monorepo: scope issues to a single workspace package')
     .action(async (cmdOpts) => {
     setupLogLevel();
     maybeBanner();
@@ -168,6 +184,11 @@ program
         if (cmdOpts.changedOnly) {
             issues = await filterIssuesByChangedFiles(issues, rootPath, cmdOpts.baseRef ?? config.baseRef);
         }
+        if (cmdOpts.package) {
+            const ws = await detectWorkspaces(rootPath);
+            const allowed = new Set(filterFilesByPackage(ws, cmdOpts.package, scan.files.map((f) => f.relativePath)));
+            issues = issues.filter((i) => (i.locations ?? []).some((l) => l.file && allowed.has(l.file)));
+        }
         if (spinner)
             spinner.stop();
         const report = {
@@ -207,6 +228,7 @@ program
     .description('Evaluate project health and detect issues')
     .option('--changed-only', 'only report issues on files changed vs base ref')
     .option('--base-ref <ref>', 'git base ref for --changed-only (default: origin/main)')
+    .option('--package <name>', 'monorepo: scope issues to a single workspace package')
     .action(async (cmdOpts) => {
     setupLogLevel();
     maybeCompactBanner();
@@ -221,6 +243,11 @@ program
         if (cmdOpts.changedOnly) {
             issues = await filterIssuesByChangedFiles(issues, rootPath, cmdOpts.baseRef ?? config.baseRef);
         }
+        if (cmdOpts.package) {
+            const ws = await detectWorkspaces(rootPath);
+            const allowed = new Set(filterFilesByPackage(ws, cmdOpts.package, scan.files.map((f) => f.relativePath)));
+            issues = issues.filter((i) => (i.locations ?? []).some((l) => l.file && allowed.has(l.file)));
+        }
         if (spinner)
             spinner.stop();
         switch (format) {
@@ -516,7 +543,8 @@ program
 program
     .command('structure')
     .description('Show project directory structure')
-    .action(async () => {
+    .option('--package <name>', 'monorepo: scope tree to a single workspace package')
+    .action(async (cmdOpts) => {
     setupLogLevel();
     maybeCompactBanner();
     const rootPath = getRootPath();
@@ -525,17 +553,30 @@ program
     const spinner = format === 'console' ? ora('Scanning...').start() : null;
     try {
         const scan = await scanRepository(rootPath, { ignore: config.ignore });
+        let tree = scan.directoryTree;
+        let title = path.basename(rootPath);
+        if (cmdOpts.package) {
+            const ws = await detectWorkspaces(rootPath);
+            const pkg = ws.packages.find((p) => p.name === cmdOpts.package);
+            if (pkg && !pkg.isRoot && pkg.relativePath) {
+                const sliced = sliceCliTree(tree, pkg.relativePath);
+                if (sliced) {
+                    tree = sliced;
+                    title = pkg.name;
+                }
+            }
+        }
         if (spinner)
             spinner.stop();
         switch (format) {
             case 'json':
-                reportStructureJson(scan.directoryTree);
+                reportStructureJson(tree);
                 break;
             case 'markdown':
-                reportStructureMarkdown(scan.directoryTree);
+                reportStructureMarkdown(tree);
                 break;
             default:
-                reportStructure(scan.directoryTree, path.basename(rootPath));
+                reportStructure(tree, title);
         }
     }
     catch (error) {
@@ -584,9 +625,10 @@ program
 // ── Command: hotspots ─────────────────────────────────────
 program
     .command('hotspots')
-    .description('Rank files by risk (git churn × complexity × open issues)')
+    .description('Rank files by risk (git churn × AST cyclomatic complexity × open issues)')
     .option('--limit <n>', 'number of hotspots to show')
     .option('--since <when>', 'git history window (e.g. "6 months ago", "2024-01-01")')
+    .option('--package <name>', 'monorepo: scope to a single workspace package')
     .action(async (cmdOpts) => {
     setupLogLevel();
     maybeCompactBanner();
@@ -602,11 +644,22 @@ program
         const limit = Math.max(1, Math.min(100, typeof limitRaw === 'string' ? parseInt(limitRaw, 10) || 10 : limitRaw));
         const since = cmdOpts.since ?? config.hotspots?.since ?? '12 months ago';
         const coverageReport = await parseCoverage(rootPath);
+        // Build the code graph so the risk score uses AST cyclomatic complexity
+        // instead of LOC. Cache hit makes this nearly free on repeat runs.
+        const cached = await loadCachedGraph(rootPath);
+        const graph = await buildCodeGraph(rootPath, scan.files, cached);
+        await saveCachedGraph(rootPath, graph);
         const report = await analyzeHotspots(rootPath, scan.files, issues, {
             since,
             limit,
             coverage: coverageReport.available ? coverageMap(coverageReport) : undefined,
+            graph,
         });
+        if (cmdOpts.package) {
+            const ws = await detectWorkspaces(rootPath);
+            const allowed = new Set(filterFilesByPackage(ws, cmdOpts.package, report.hotspots.map((h) => h.relativePath)));
+            report.hotspots = report.hotspots.filter((h) => allowed.has(h.relativePath));
+        }
         if (spinner)
             spinner.stop();
         switch (format) {
@@ -627,6 +680,209 @@ program
         process.exit(1);
     }
 });
+// ── Command: coupling ─────────────────────────────────────
+program
+    .command('coupling')
+    .description('Per-file fan-in / fan-out / instability and circular-import cycles (AST-derived)')
+    .option('--limit <n>', 'number of files to show (default 25)')
+    .option('--cycles-only', 'only show files participating in import cycles')
+    .option('--high-fan-in', 'sort by fan-in (most-depended-on first)')
+    .option('--high-fan-out', 'sort by fan-out (most-coupled first)')
+    .option('--file <path>', 'restrict output to a single file')
+    .option('--package <name>', 'monorepo: scope to a single workspace package')
+    .action(async (cmdOpts) => {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    const config = await loadProjectConfig();
+    const spinner = format === 'console' ? ora('Computing coupling + cycles...').start() : null;
+    try {
+        const scan = await scanRepository(rootPath, { ignore: config.ignore });
+        const cached = await loadCachedGraph(rootPath);
+        const graph = await buildCodeGraph(rootPath, scan.files, cached);
+        await saveCachedGraph(rootPath, graph);
+        const ws = await detectWorkspaces(rootPath);
+        const report = computeCoupling(graph, ws);
+        const direction = cmdOpts.cyclesOnly
+            ? 'cycles_only'
+            : cmdOpts.highFanIn
+                ? 'high_fan_in'
+                : cmdOpts.highFanOut
+                    ? 'high_fan_out'
+                    : 'all';
+        const limitRaw = cmdOpts.limit ?? 25;
+        const limit = Math.max(1, Math.min(500, typeof limitRaw === 'string' ? parseInt(limitRaw, 10) || 25 : limitRaw));
+        let files = filterCoupling(report, direction);
+        if (cmdOpts.file)
+            files = files.filter((f) => f.relativePath === cmdOpts.file);
+        if (cmdOpts.package) {
+            const ws = await detectWorkspaces(rootPath);
+            const allowed = new Set(filterFilesByPackage(ws, cmdOpts.package, files.map((f) => f.relativePath)));
+            files = files.filter((f) => allowed.has(f.relativePath));
+        }
+        files = files.slice(0, limit);
+        const filtered = {
+            files,
+            cycles: report.cycles,
+            crossPackageEdges: report.crossPackageEdges,
+            totalFiles: report.totalFiles,
+            totalCycles: report.totalCycles,
+            totalCrossPackageEdges: report.totalCrossPackageEdges,
+        };
+        if (spinner)
+            spinner.stop();
+        switch (format) {
+            case 'json':
+                reportCouplingJson(filtered);
+                break;
+            case 'markdown':
+                reportCouplingMarkdown(filtered);
+                break;
+            default:
+                reportCoupling(filtered);
+        }
+    }
+    catch (error) {
+        if (spinner)
+            spinner.fail('Coupling analysis failed');
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});
+// ── Command: pr-diff ──────────────────────────────────────
+program
+    .command('pr-diff')
+    .description('Structural (AST) diff between two refs - what changed in exports, imports, calls, CC, fan-in')
+    .option('--base <ref>', 'base ref (default: origin/main, falling back to main/master/HEAD~1)')
+    .option('--head <ref>', 'head ref (default: HEAD)')
+    .option('--package <name>', 'monorepo: scope diff to a single workspace package')
+    .action(async (cmdOpts) => {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    const spinner = format === 'console' ? ora('Computing structural PR diff...').start() : null;
+    try {
+        const report = await computePrDiff(rootPath, { base: cmdOpts.base, head: cmdOpts.head });
+        if (cmdOpts.package) {
+            const ws = await detectWorkspaces(rootPath);
+            const collected = [
+                ...report.filesAdded,
+                ...report.filesRemoved,
+                ...report.filesModified.map((f) => f.relativePath),
+            ];
+            const allowed = new Set(filterFilesByPackage(ws, cmdOpts.package, collected));
+            report.filesAdded = report.filesAdded.filter((f) => allowed.has(f));
+            report.filesRemoved = report.filesRemoved.filter((f) => allowed.has(f));
+            report.filesModified = report.filesModified.filter((f) => allowed.has(f.relativePath));
+            report.totalFilesChanged =
+                report.filesAdded.length + report.filesRemoved.length + report.filesModified.length;
+        }
+        if (spinner)
+            spinner.stop();
+        switch (format) {
+            case 'json':
+                reportPrDiffJson(report);
+                break;
+            case 'markdown':
+                reportPrDiffMarkdown(report);
+                break;
+            default:
+                reportPrDiff(report);
+        }
+    }
+    catch (error) {
+        if (spinner)
+            spinner.fail('PR diff failed');
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});
+// ── Command: workspaces ───────────────────────────────────
+program
+    .command('workspaces')
+    .description('List monorepo workspace packages (npm/yarn workspaces, pnpm-workspace.yaml, Nx/Turbo/Lerna fallback)')
+    .action(async () => {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const info = await detectWorkspaces(rootPath);
+        switch (format) {
+            case 'json':
+                reportWorkspacesJson(info);
+                break;
+            case 'markdown':
+                reportWorkspacesMarkdown(info);
+                break;
+            default:
+                reportWorkspaces(info);
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});
+// ── Command: telemetry ────────────────────────────────────
+program
+    .command('telemetry')
+    .description('Inspect projscan opt-in telemetry: config state, or per-tool histograms with --aggregate')
+    .option('--aggregate', 'read the local sink and print per-tool latency histograms (count, p50/p95/p99, error rate)')
+    .action(async (cmdOpts) => {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const { config } = await loadConfig(rootPath);
+        const out = cmdOpts.aggregate
+            ? await aggregateTelemetry(config.telemetry)
+            : describeTelemetryConfig(config.telemetry);
+        if (format === 'json') {
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        // Console: hand-formatted summary so users don't have to read raw JSON.
+        if (cmdOpts.aggregate) {
+            const agg = out;
+            if (!agg.available) {
+                console.log(chalk.yellow(`\n  ${agg.reason ?? 'No telemetry available.'}\n`));
+                return;
+            }
+            console.log(chalk.bold('\n  Telemetry histograms'));
+            console.log(chalk.dim(`  sink: ${agg.sink}`));
+            console.log(chalk.dim(`  ${agg.totalEvents} event(s) · ${agg.windowFrom ?? '?'} → ${agg.windowTo ?? '?'}\n`));
+            if (agg.byTool.length === 0) {
+                console.log(chalk.dim('  (no events recorded yet)\n'));
+                return;
+            }
+            const colHead = `    ${'count'.padStart(6)}  ${'err%'.padStart(5)}  ${'p50'.padStart(6)}  ${'p95'.padStart(6)}  ${'p99'.padStart(6)}  tool`;
+            console.log(chalk.dim(colHead));
+            for (const t of agg.byTool) {
+                const errPct = (t.errorRate * 100).toFixed(1) + '%';
+                console.log(`    ${String(t.count).padStart(6)}  ${errPct.padStart(5)}  ${(t.p50Ms ?? 0).toString().padStart(6)}  ${(t.p95Ms ?? 0).toString().padStart(6)}  ${(t.p99Ms ?? 0).toString().padStart(6)}  ${chalk.cyan(t.tool)}`);
+            }
+            console.log('');
+        }
+        else {
+            const cfg = out;
+            console.log(chalk.bold('\n  Telemetry'));
+            console.log(`    enabled: ${cfg.enabled ? chalk.green('yes') : chalk.dim('no (default)')}`);
+            console.log(`    sink:    ${cfg.sink}`);
+            console.log(`    default: ${cfg.defaultSink}`);
+            console.log(`    PROJSCAN_TELEMETRY env: ${cfg.envOverride ?? chalk.dim('(unset)')}`);
+            console.log(chalk.dim('\n    Records: tool, durationMs, ok, version, ts. Never source/paths/args.'));
+            console.log(chalk.dim('    Re-run with --aggregate to see histograms over the recorded events.\n'));
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});
 // ── Command: outdated ─────────────────────────────────────
 program
     .command('outdated')
@@ -741,6 +997,7 @@ program
     .option('--mode <mode>', 'lexical | semantic | hybrid (content/auto scope only)', 'lexical')
     .option('--semantic', 'shortcut for --mode semantic')
     .option('--limit <n>', 'max results', '15')
+    .option('--package <name>', 'monorepo: scope to a single workspace package')
     .action(async (queryParts, cmdOpts) => {
     setupLogLevel();
     maybeCompactBanner();
@@ -761,6 +1018,22 @@ program
         const cached = await loadCachedGraph(rootPath);
         const graph = await buildCodeGraph(rootPath, scan.files, cached);
         await saveCachedGraph(rootPath, graph);
+        // Build a (file -> bool) filter once if --package is set; reused below.
+        let passes = null;
+        if (cmdOpts.package) {
+            const ws = await detectWorkspaces(rootPath);
+            const pkg = ws.packages.find((p) => p.name === cmdOpts.package);
+            if (!pkg) {
+                passes = () => false;
+            }
+            else if (pkg.isRoot) {
+                passes = () => true;
+            }
+            else {
+                const prefix = pkg.relativePath + '/';
+                passes = (f) => f === pkg.relativePath || f.startsWith(prefix);
+            }
+        }
         if (spinner)
             spinner.text = 'Searching...';
         let results;
@@ -768,6 +1041,8 @@ program
             const q = query.toLowerCase();
             const matches = [];
             for (const [file, entry] of graph.files) {
+                if (passes && !passes(file))
+                    continue;
                 for (const exp of entry.exports) {
                     if (exp.name.toLowerCase().includes(q)) {
                         matches.push({ symbol: exp.name, kind: exp.kind, file, line: exp.line });
@@ -785,6 +1060,7 @@ program
             const q = query.toLowerCase();
             const matches = scan.files
                 .filter((f) => f.relativePath.toLowerCase().includes(q))
+                .filter((f) => !passes || passes(f.relativePath))
                 .slice(0, limit)
                 .map((f) => ({ file: f.relativePath, sizeBytes: f.sizeBytes }));
             results = { scope, query, matches, total: matches.length };
@@ -792,7 +1068,8 @@ program
         else {
             const mode = cmdOpts.semantic ? 'semantic' : String(cmdOpts.mode ?? 'lexical');
             const index = await buildSearchIndex(rootPath, scan.files, graph);
-            const lexicalHits = searchIndex(index, query, { limit });
+            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);
@@ -829,7 +1106,8 @@ program
                 }
                 if (spinner)
                     spinner.text = 'Searching...';
-                const semHits = await semanticSearch(semIndex, query, { limit });
+                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,
@@ -934,6 +1212,7 @@ program
     .command('coverage')
     .description('Join test coverage with hotspots - surface the scariest untested files')
     .option('--limit <n>', 'limit number of entries shown', '30')
+    .option('--package <name>', 'monorepo: scope to a single workspace package')
     .action(async (cmdOpts) => {
     setupLogLevel();
     maybeCompactBanner();
@@ -952,6 +1231,11 @@ program
             coverage: coverage.available ? coverageMap(coverage) : undefined,
         });
         const joined = joinCoverageWithHotspots(hotspots, coverage);
+        if (cmdOpts.package && joined.available) {
+            const ws = await detectWorkspaces(rootPath);
+            const allowed = new Set(filterFilesByPackage(ws, cmdOpts.package, joined.entries.map((e) => e.relativePath)));
+            joined.entries = joined.entries.filter((e) => allowed.has(e.relativePath));
+        }
         if (spinner)
             spinner.stop();
         switch (format) {