projscan 0.10.0 → 0.11.0

package/README.md

@@ -20,7 +20,7 @@
 
 AI coding agents are becoming the primary interface to code. Today, when you ask your agent *"which files implement auth?"* or *"what breaks if I bump React from 18 to 19?"* - it either guesses from names, or it shells out to grep and reads raw output not built for it.
 
-**projscan is the first code-intelligence tool built for agents, not for humans.** Your agent gets a fast, AST-accurate, context-budget-aware view of your codebase through 13 structured MCP tools. It can query the import graph, find symbol definitions, preview upgrades, rank hotspots - without loading the file tree into its context.
+**projscan is the first code-intelligence tool built for agents, not for humans.** Your agent gets a fast, AST-accurate, context-budget-aware view of your codebase through 17 structured MCP tools. It can query the import graph, find symbol definitions, preview upgrades, rank hotspots, diff structural changes between refs, and surface coupling/cycle hotspots - without loading the file tree into its context.
 
 Humans get the same thing through the CLI.
 
@@ -190,7 +190,7 @@ This outputs a [shields.io](https://shields.io) badge URL and markdown snippet y
 
 ## What It Detects
 
-**Languages**: TypeScript, JavaScript, Python (full AST analysis for all three), plus file-level detection for Go, Rust, Java, Ruby, C/C++, PHP, Swift, Kotlin, and 20+ more.
+**Languages**: TypeScript, JavaScript, Python, and Go (full AST analysis for all four), plus file-level detection for Rust, Java, Ruby, C/C++, PHP, Swift, Kotlin, and 20+ more.
 
 **Frameworks**: React, Next.js, Vue, Nuxt, Svelte, Angular, Express, Fastify, NestJS, Vite, Tailwind CSS, Prisma, and more
 
@@ -206,6 +206,18 @@ Python repos now get the same treatment JS/TS has had since 0.6:
 
 `projscan_upgrade` remains Node-only for now - a Python equivalent (reading pip / poetry metadata) is on the roadmap.
 
+### Bundle (0.11)
+
+0.11.0 is a multi-theme bundle. Five releases of work shipped under one version:
+
+- **Signal Quality (was 0.11)** - the hotspot risk score now uses AST-derived **cyclomatic complexity** instead of a line-count proxy. Per-file CC is exposed via `projscan_file` and the new `projscan_coupling` tool. Coupling metrics (fan-in / fan-out / instability) and **circular-import detection** (Tarjan SCC) ship as a first-class `projscan coupling` command and MCP tool.
+- **PR Native (was 0.12)** - new `projscan_pr_diff` tool returns the **structural** diff between two refs: exports added/removed, imports added/removed, call sites added/removed, ΔCC, Δfan-in. Stands up a temporary git worktree at the base ref to get a clean second graph. What an agent reviewing a PR actually wants to know.
+- **Monorepo (was 0.13)** - workspace detection for npm/yarn workspaces, pnpm-workspace.yaml, and Nx/Turbo/Lerna fallback. New `projscan workspaces` command lists every package; `--package <name>` (and the `package` MCP arg) scope `hotspots` and `coupling` to a single workspace.
+- **Observability (was 0.14)** - **opt-in**, privacy-preserving telemetry. Records only tool name, duration, success, version, timestamp; never source content, paths, or arguments. Off by default; enable via `.projscanrc` `telemetry.enabled` or `PROJSCAN_TELEMETRY=1`. Sink is a local JSONL file you control. New `projscan_telemetry` tool surfaces effective state.
+- **Second Language (was 0.15)** - **Go** via tree-sitter-go. Go files now flow through the same graph / hotspot / coupling / pr-diff pipeline as JS/TS and Python. `go.mod` parsed for module-path resolution; capitalization rule applied for export visibility.
+
+Cache version bumped 2 → 3 (CC stored per file). Existing v2 caches are discarded on first 0.11 run and rebuilt automatically.
+
 **Issues**:
 - Missing linting (ESLint) and formatting (Prettier) configuration
 - Missing test framework
@@ -222,7 +234,7 @@ Python repos now get the same treatment JS/TS has had since 0.6:
 - **5,000 files** analyzed in under 1.5 seconds
 - **20,000 files** analyzed in under 3 seconds
 - **Zero network requests** - everything runs locally
-- **6 runtime dependencies** - still minimal footprint (the two tree-sitter packages add ~640 KB of vendored wasm)
+- **9 runtime dependencies** - still minimal (the three tree-sitter packages bring ~850 KB of vendored wasm: web-tree-sitter ~190 KB, tree-sitter-python ~450 KB, tree-sitter-go ~210 KB)
 
 ## CI/CD Integration
 
@@ -429,17 +441,19 @@ claude mcp add projscan -- npx projscan mcp
 - *"What breaks if I bump chalk to 6?"* → `projscan_upgrade { package: "chalk" }`
 - *"Where should I refactor first?"* → `projscan_hotspots`
 
-### The 13 MCP tools
+### The 17 MCP tools
 
-**Structural (0.6.0 - new, agent-native):**
+**Structural (0.6.0 / 0.11 — agent-native):**
 - **`projscan_graph`** - query the AST-based code graph. Directions: `imports`, `exports`, `importers`, `symbol_defs`, `package_importers`. Millisecond responses on a warm cache.
 - **`projscan_search`** - fast search across `symbols` (exported names), `files` (path substring), or `content` (source substring with line + excerpt). Replaces the temptation to shell out to grep.
+- **`projscan_coupling`** *(0.11)* - per-file fan-in / fan-out / instability + circular-import cycles (Tarjan SCC). Filter by `direction: cycles_only | high_fan_in | high_fan_out`.
+- **`projscan_pr_diff`** *(0.11)* - structural diff between two git refs. Returns added/removed/modified files with explicit lists of exports, imports, and call sites that changed, plus ΔCC and Δfan-in.
 
 **Analysis:**
 - `projscan_analyze` - full project report
 - `projscan_doctor` - health score + issues
-- `projscan_hotspots` - risk-ranked files (churn × complexity × issues × ownership × coverage)
-- `projscan_file` - per-file risk + ownership + related issues
+- `projscan_hotspots` - risk-ranked files (churn × **AST cyclomatic complexity** × issues × ownership × coverage; falls back to LOC for non-AST languages)
+- `projscan_file` - per-file risk + ownership + related issues + CC + fan-in/fan-out
 - `projscan_explain` - per-file purpose, imports, exports, smells
 - `projscan_structure` - directory tree
 - `projscan_coverage` - scariest untested files (coverage × hotspots)
@@ -450,6 +464,10 @@ claude mcp add projscan -- npx projscan mcp
 - `projscan_audit` - normalized `npm audit`
 - `projscan_upgrade` - upgrade preview (CHANGELOG + importers, offline)
 
+**Workspace + observability (0.11):**
+- `projscan_workspaces` - list monorepo packages (npm/yarn/pnpm/Nx/Turbo/Lerna). Use the `name` as the `package` arg on `projscan_hotspots` / `projscan_coupling` to scope.
+- `projscan_telemetry` - inspect opt-in telemetry state (enabled?, sink path, env override).
+
 ### Context-window budgeting
 
 **Every MCP tool accepts an optional `max_tokens` argument.** Set it and projscan serializes the result, and - if over budget - truncates the largest array field record-by-record until it fits. Responses include a `_budget` sidecar when truncated so your agent knows it got a partial view.

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) {