pi-lens 3.8.61 → 3.8.63

package/dist/clients/bootstrap.js

@@ -1,41 +1,107 @@
 let bootstrapPromise = null;
+/**
+ * A stand-in for an analysis client whose module failed to load (an unresolved
+ * runtime dependency under a package-manager layout the resolver can't traverse
+ * — #285/#335). Every method call no-ops to `undefined`, which every analyzer
+ * consumer already treats as "nothing to report", so a single failed analyzer
+ * degrades to silence instead of taking down the whole extension. This keeps the
+ * fail-soft in ONE seam (the bootstrap) so consumers never special-case it —
+ * the same single-seam principle as the clients/deps/* accessors.
+ */
+export function degradedClient() {
+    return new Proxy({}, {
+        get(_target, prop) {
+            // Not thenable (so `await stub` / Promise.resolve(stub) won't treat it
+            // as a promise), not iterable, no surprising coercion.
+            if (typeof prop === "symbol" || prop === "then")
+                return undefined;
+            return () => undefined;
+        },
+    });
+}
+/**
+ * One or more client modules failed to load — almost always an unresolved
+ * runtime dependency under a package-manager layout the runtime's resolver can't
+ * traverse (#285/#335). Name each disabled analyzer, then emit ONE paste-able
+ * environment fingerprint so a reporter can tell us exactly what failed and
+ * where. Best-effort: never let the diagnostic itself mask the failure.
+ */
+async function logBootstrapFailures(failures) {
+    for (const { name, err } of failures) {
+        console.error(`[pi-lens] analyzer "${name}" disabled (degraded mode): ${err?.message ?? String(err)}`);
+    }
+    try {
+        const { collectInstallDiagnostics, formatInstallDiagnostics } = await import("./install-diagnostics.js");
+        console.error(formatInstallDiagnostics(collectInstallDiagnostics(), failures[0]?.err));
+    }
+    catch {
+        // the per-analyzer lines above already named the failures
+    }
+}
 export function loadBootstrapClients() {
     bootstrapPromise ??= (async () => {
-        const [ruffMod, biomeMod, knipMod, todoMod, jscpdMod, typeCoverageMod, depCheckerMod, testRunnerMod, metricsMod, complexityMod, goMod, govulncheckMod, gitleaksMod, trivyMod, rustMod, agentBehaviorMod,] = await Promise.all([
-            import("./ruff-client.js"),
-            import("./biome-client.js"),
-            import("./knip-client.js"),
-            import("./todo-scanner.js"),
-            import("./jscpd-client.js"),
-            import("./type-coverage-client.js"),
-            import("./dependency-checker.js"),
-            import("./test-runner-client.js"),
-            import("./metrics-client.js"),
-            import("./complexity-client.js"),
-            import("./go-client.js"),
-            import("./govulncheck-client.js"),
-            import("./gitleaks-client.js"),
-            import("./trivy-client.js"),
-            import("./rust-client.js"),
-            import("./agent-behavior-client.js"),
+        const failures = [];
+        // Load + construct one client in isolation; on failure record it and
+        // substitute a degraded no-op stub so the others still load — single-seam
+        // fail-soft, consumers never special-case it.
+        async function load(name, make) {
+            try {
+                return await make();
+            }
+            catch (err) {
+                failures.push({ name, err });
+                return degradedClient();
+            }
+        }
+        // Lists degrade to empty (a stub Proxy isn't iterable), e.g. dead-code.
+        async function loadList(name, make) {
+            try {
+                return await make();
+            }
+            catch (err) {
+                failures.push({ name, err });
+                return [];
+            }
+        }
+        const [ruffClient, biomeClient, knipClient, todoScanner, jscpdClient, typeCoverageClient, depChecker, testRunnerClient, metricsClient, complexityClient, goClient, govulncheckClient, gitleaksClient, trivyClient, rustClient, agentBehaviorClient, deadCodeClients,] = await Promise.all([
+            load("ruff", async () => new (await import("./ruff-client.js")).RuffClient()),
+            load("biome", async () => new (await import("./biome-client.js")).BiomeClient()),
+            load("knip", async () => new (await import("./knip-client.js")).KnipClient()),
+            load("todo", async () => new (await import("./todo-scanner.js")).TodoScanner()),
+            load("jscpd", async () => new (await import("./jscpd-client.js")).JscpdClient()),
+            load("type-coverage", async () => new (await import("./type-coverage-client.js")).TypeCoverageClient()),
+            load("dependency-checker", async () => new (await import("./dependency-checker.js")).DependencyChecker()),
+            load("test-runner", async () => new (await import("./test-runner-client.js")).TestRunnerClient()),
+            load("metrics", async () => new (await import("./metrics-client.js")).MetricsClient()),
+            load("complexity", async () => new (await import("./complexity-client.js")).ComplexityClient()),
+            load("go", async () => new (await import("./go-client.js")).GoClient()),
+            load("govulncheck", async () => new (await import("./govulncheck-client.js")).GovulncheckClient()),
+            load("gitleaks", async () => new (await import("./gitleaks-client.js")).GitleaksClient()),
+            load("trivy", async () => new (await import("./trivy-client.js")).TrivyClient()),
+            load("rust", async () => new (await import("./rust-client.js")).RustClient()),
+            load("agent-behavior", async () => new (await import("./agent-behavior-client.js")).AgentBehaviorClient()),
+            loadList("dead-code", async () => (await import("./dead-code-client.js")).getDeadCodeClients()),
         ]);
+        if (failures.length > 0)
+            await logBootstrapFailures(failures);
         return {
-            ruffClient: new ruffMod.RuffClient(),
-            biomeClient: new biomeMod.BiomeClient(),
-            knipClient: new knipMod.KnipClient(),
-            todoScanner: new todoMod.TodoScanner(),
-            jscpdClient: new jscpdMod.JscpdClient(),
-            typeCoverageClient: new typeCoverageMod.TypeCoverageClient(),
-            depChecker: new depCheckerMod.DependencyChecker(),
-            testRunnerClient: new testRunnerMod.TestRunnerClient(),
-            metricsClient: new metricsMod.MetricsClient(),
-            complexityClient: new complexityMod.ComplexityClient(),
-            goClient: new goMod.GoClient(),
-            govulncheckClient: new govulncheckMod.GovulncheckClient(),
-            gitleaksClient: new gitleaksMod.GitleaksClient(),
-            trivyClient: new trivyMod.TrivyClient(),
-            rustClient: new rustMod.RustClient(),
-            agentBehaviorClient: new agentBehaviorMod.AgentBehaviorClient(),
+            ruffClient,
+            biomeClient,
+            knipClient,
+            todoScanner,
+            jscpdClient,
+            typeCoverageClient,
+            depChecker,
+            testRunnerClient,
+            metricsClient,
+            complexityClient,
+            goClient,
+            govulncheckClient,
+            gitleaksClient,
+            trivyClient,
+            rustClient,
+            agentBehaviorClient,
+            deadCodeClients,
         };
     })();
     return bootstrapPromise;

package/dist/clients/complexity-client.js

@@ -16,7 +16,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import * as ts from "typescript";
+import { ts } from "./deps/typescript.js";
 import { isFileKind } from "./file-kinds.js";
 // --- Constants ---
 // Nodes that increase cyclomatic complexity

package/dist/clients/dead-code-client.js

@@ -0,0 +1,304 @@
+/**
+ * Cross-file dead-code detection for non-JS/TS ecosystems (#127).
+ *
+ * Knip (clients/knip-client.ts) gives JS/TS projects project-wide unused
+ * exports/files/deps at session_start. Per-file dispatch linters can't do that
+ * for other languages — "this exported function is unused anywhere" needs a
+ * whole-project scan. This module is the per-language harness that closes the
+ * gap, paralleling KnipClient's lifecycle (detect → ensureAvailable → analyze,
+ * cached at session_start, surfaced as a turn_end advisory).
+ *
+ * Phase 1 ships Python via `vulture`. Future phases add Go/Rust/etc. by
+ * implementing DeadCodeClient and adding to getDeadCodeClients().
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isAtOrAboveHomeDir } from "./path-utils.js";
+import { safeSpawnAsync } from "./safe-spawn.js";
+function emptyResult(language) {
+    return {
+        success: false,
+        language,
+        unusedExports: [],
+        unusedFiles: [],
+        unusedDeps: [],
+        unlistedDeps: [],
+    };
+}
+const ANALYSIS_TIMEOUT_MS = 30_000;
+// Directories never worth scanning for the user's own dead code.
+const VULTURE_EXCLUDES = [
+    "*/.venv/*",
+    "*/venv/*",
+    "*/.tox/*",
+    "*/build/*",
+    "*/dist/*",
+    "*/node_modules/*",
+    "*/.git/*",
+    "*/site-packages/*",
+    "*/__pycache__/*",
+    "*/.eggs/*",
+];
+// vulture line: `path/to/file.py:12: unused function 'foo' (60% confidence)`
+const VULTURE_LINE = /^(.*?):(\d+): unused (\w[\w ]*?) '([^']+)' \((\d+)% confidence\)\s*$/;
+/**
+ * Parse vulture's text output into normalized issues. Pure (no spawn/fs) so the
+ * parser is unit-testable against captured output. Unrecognized lines (banner,
+ * `unreachable code` without a quoted name) are ignored. `root` makes file
+ * paths project-relative when possible.
+ */
+export function parseVultureOutput(output, root) {
+    const issues = [];
+    for (const raw of output.split(/\r?\n/)) {
+        const m = raw.match(VULTURE_LINE);
+        if (!m)
+            continue;
+        const [, file, line, kind, name, confidence] = m;
+        // All map to the "export" bucket (a defined symbol used nowhere); the
+        // `kind` preserves function/class/import/etc. for display.
+        let rel = file;
+        try {
+            rel = path.relative(root, file) || file;
+        }
+        catch {
+            rel = file;
+        }
+        issues.push({
+            category: "export",
+            kind: kind.trim(),
+            name,
+            file: rel,
+            line: Number.parseInt(line, 10),
+            confidence: Number.parseInt(confidence, 10),
+        });
+    }
+    return issues;
+}
+/**
+ * Python dead-code via vulture (https://github.com/jendrikseipp/vulture).
+ *
+ * vulture finds unused functions, classes, methods, imports, variables and
+ * attributes by static analysis of the whole tree. It has no JSON reporter, so
+ * we parse its stable one-line-per-finding text output. It exits 1 when it
+ * FINDS dead code (linter convention), so a non-zero exit with parseable
+ * output is success, not failure.
+ */
+export class PythonDeadCodeClient {
+    id = "python";
+    language = "Python";
+    available = null;
+    resolved = null;
+    ensureInFlight = null;
+    inFlight = new Map();
+    log;
+    constructor(verbose = false) {
+        this.log = verbose
+            ? (msg) => console.error(`[dead-code:python] ${msg}`)
+            : () => { };
+    }
+    get minConfidence() {
+        const raw = Number.parseInt(process.env.PI_LENS_VULTURE_MIN_CONFIDENCE ?? "60", 10);
+        return Number.isFinite(raw) ? Math.min(100, Math.max(0, raw)) : 60;
+    }
+    detect(cwd) {
+        return this.resolveProjectRoot(cwd) !== null;
+    }
+    /**
+     * Nearest dir with a Python project marker, never at/above $HOME and never
+     * escaping a VCS boundary — same containment rules as KnipClient so a scan
+     * launched from a bare cwd can't recurse the whole home tree (#250/#296).
+     */
+    resolveProjectRoot(startDir, homeDirOverride) {
+        const markers = [
+            "pyproject.toml",
+            "setup.py",
+            "setup.cfg",
+            "requirements.txt",
+            "Pipfile",
+            "tox.ini",
+        ];
+        const boundaries = [".git", ".hg", ".svn"];
+        const homeDir = path.resolve(homeDirOverride ?? os.homedir());
+        let current = path.resolve(startDir);
+        for (let depth = 0; depth < 64; depth++) {
+            if (isAtOrAboveHomeDir(current, homeDir))
+                return null;
+            if (markers.some((m) => fs.existsSync(path.join(current, m)))) {
+                return current;
+            }
+            if (boundaries.some((m) => fs.existsSync(path.join(current, m)))) {
+                return null;
+            }
+            const parent = path.dirname(current);
+            if (parent === current)
+                return null;
+            current = parent;
+        }
+        return null;
+    }
+    async ensureAvailable() {
+        if (this.available !== null)
+            return this.available;
+        if (this.ensureInFlight)
+            return this.ensureInFlight;
+        this.ensureInFlight = this.doEnsureAvailable();
+        try {
+            return await this.ensureInFlight;
+        }
+        finally {
+            this.ensureInFlight = null;
+        }
+    }
+    async doEnsureAvailable() {
+        // Presence-gated, NOT auto-installed. vulture is a pure-Python package
+        // with no standalone binary, so "auto-install" would mean `pip install`
+        // into whatever Python environment happens to be active — wrong and
+        // intrusive for uv / poetry / conda / pipx users. So we only use vulture
+        // when the user already has it, probing both the `vulture` console script
+        // and `python -m vulture` (the script dir is frequently not on PATH even
+        // when the package is installed). Mirrors govulncheck's no-install gating.
+        const candidates = [
+            { cmd: "vulture", prefix: [] },
+            { cmd: "python", prefix: ["-m", "vulture"] },
+            { cmd: "python3", prefix: ["-m", "vulture"] },
+        ];
+        for (const c of candidates) {
+            const probe = await safeSpawnAsync(c.cmd, [...c.prefix, "--version"], {
+                timeout: 5000,
+            });
+            if (!probe.error && probe.status === 0) {
+                this.resolved = c;
+                this.available = true;
+                this.log(`vulture found: ${[c.cmd, ...c.prefix].join(" ")}`);
+                return true;
+            }
+        }
+        this.available = false;
+        this.log("vulture not installed; skipping (no auto-install)");
+        return false;
+    }
+    async analyze(cwd) {
+        const root = this.resolveProjectRoot(cwd || process.cwd());
+        if (!root) {
+            return {
+                ...emptyResult(this.language),
+                success: true,
+                summary: "No Python project root found; vulture skipped",
+            };
+        }
+        if (!(await this.ensureAvailable())) {
+            return {
+                ...emptyResult(this.language),
+                success: true,
+                summary: "vulture not installed; skipped. Install vulture (pip/uv/pipx) to enable Python dead-code detection.",
+            };
+        }
+        const key = path.resolve(root);
+        const existing = this.inFlight.get(key);
+        if (existing)
+            return existing;
+        const promise = this.runAnalyze(key).finally(() => this.inFlight.delete(key));
+        this.inFlight.set(key, promise);
+        return promise;
+    }
+    async runAnalyze(root) {
+        const startMs = Date.now();
+        const invocation = this.resolved ?? { cmd: "vulture", prefix: [] };
+        const args = [
+            ...invocation.prefix,
+            ".",
+            `--min-confidence=${this.minConfidence}`,
+            `--exclude=${VULTURE_EXCLUDES.join(",")}`,
+        ];
+        const result = await safeSpawnAsync(invocation.cmd, args, {
+            timeout: ANALYSIS_TIMEOUT_MS,
+            cwd: root,
+        });
+        const durationMs = Date.now() - startMs;
+        // Spawn-level failure (ENOENT, timeout) — not a "found issues" exit.
+        if (result.error) {
+            this.log(`scan error: ${result.error.message}`);
+            return {
+                ...emptyResult(this.language),
+                summary: `Error: ${result.error.message}`,
+                durationMs,
+            };
+        }
+        // vulture writes parse/usage errors to stderr and exits 1 with no
+        // stdout findings; distinguish that from "found dead code" (exit 1 WITH
+        // findings on stdout).
+        const output = result.stdout || "";
+        if (!output.trim()) {
+            const stderr = (result.stderr || "").trim();
+            if (result.status !== 0 && stderr) {
+                return {
+                    ...emptyResult(this.language),
+                    summary: `vulture error: ${stderr.split("\n")[0]}`,
+                    durationMs,
+                };
+            }
+            return {
+                ...emptyResult(this.language),
+                success: true,
+                summary: "No dead code found",
+                durationMs,
+            };
+        }
+        return { ...this.parseOutput(output, root), durationMs };
+    }
+    parseOutput(output, root) {
+        const unusedExports = parseVultureOutput(output, root);
+        const total = unusedExports.length;
+        return {
+            ...emptyResult(this.language),
+            success: true,
+            unusedExports,
+            summary: total === 0
+                ? "No dead code found"
+                : `Found ${total} unused Python symbol(s)`,
+        };
+    }
+}
+/**
+ * The dead-code clients to run at session_start. Each is offered every project;
+ * the orchestrator calls detect() to decide which actually apply (polyglot
+ * repos may run several). Phase 1: Python only.
+ */
+export function getDeadCodeClients(verbose = false) {
+    return [new PythonDeadCodeClient(verbose)];
+}
+/** Total issue count across all buckets — convenience for advisories/telemetry. */
+export function deadCodeIssueCount(result) {
+    return (result.unusedExports.length +
+        result.unusedFiles.length +
+        result.unusedDeps.length +
+        result.unlistedDeps.length);
+}
+/**
+ * Format cached dead-code results into one turn_end advisory, or "" when there
+ * is nothing to report. Merges multiple languages (polyglot repos) under one
+ * `[Dead code]` heading so it reads consistently next to the Knip advisory.
+ * Advisory-only: these are project-wide signals, never blockers.
+ */
+export function formatDeadCodeAdvisory(results, maxPerLang = 10) {
+    const withFindings = results.filter((r) => r.success && deadCodeIssueCount(r) > 0);
+    if (withFindings.length === 0)
+        return "";
+    const lines = [];
+    for (const r of withFindings) {
+        const count = deadCodeIssueCount(r);
+        lines.push(`${r.language}: ${count} unused symbol(s)`);
+        for (const issue of r.unusedExports.slice(0, maxPerLang)) {
+            const loc = issue.file
+                ? ` (${issue.file}${issue.line ? `:${issue.line}` : ""})`
+                : "";
+            lines.push(`    - unused ${issue.kind} '${issue.name}'${loc}`);
+        }
+        if (r.unusedExports.length > maxPerLang) {
+            lines.push(`    … and ${r.unusedExports.length - maxPerLang} more`);
+        }
+    }
+    return ("💀 [Dead code] project-wide unused symbols — verify before removing:\n  " +
+        lines.join("\n  "));
+}

package/dist/clients/dead-code-logger.js

@@ -0,0 +1,46 @@
+/**
+ * NDJSON telemetry for cross-file dead-code scans (#127). One event per
+ * session_start scan per language, so we can answer: which languages get
+ * scanned, how many findings, and how long the whole-project scan takes (the
+ * input to phasing decisions in the issue). Mirrors `ast-grep-tool-logger.ts`
+ * for shape + size-based rotation.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isTestMode } from "./env-utils.js";
+import { getGlobalPiLensDir } from "./file-utils.js";
+const LOG_DIR = getGlobalPiLensDir();
+const LOG_FILE = path.join(LOG_DIR, "dead-code.log");
+const LOG_BACKUP_FILE = path.join(LOG_DIR, "dead-code.log.1");
+const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.PI_LENS_DEAD_CODE_LOG_MAX_BYTES ?? "1048576", 10) ||
+    1048576);
+function rotateIfNeeded() {
+    try {
+        const stat = fs.statSync(LOG_FILE);
+        if (stat.size >= MAX_LOG_BYTES) {
+            fs.renameSync(LOG_FILE, LOG_BACKUP_FILE);
+        }
+    }
+    catch {
+        // no file yet, or rename raced — nothing to rotate
+    }
+}
+/**
+ * Append one scan event. Fire-and-forget: telemetry must never break a scan, so
+ * every fs error is swallowed. Skipped under test mode to keep the suite from
+ * writing to the user's real ~/.pi-lens.
+ */
+export function logDeadCodeScan(event) {
+    if (isTestMode())
+        return;
+    try {
+        if (!fs.existsSync(LOG_DIR))
+            fs.mkdirSync(LOG_DIR, { recursive: true });
+        rotateIfNeeded();
+        const row = JSON.stringify({ ts: new Date().toISOString(), ...event });
+        fs.appendFileSync(LOG_FILE, row + "\n");
+    }
+    catch {
+        // telemetry is best-effort
+    }
+}

package/dist/clients/deadline-utils.js

@@ -0,0 +1,70 @@
+/**
+ * One implementation of the "race a promise against a timer" pattern that had
+ * drifted into three near-identical copies (#366): `withTimeout` (clients/lsp),
+ * `withBudget` (read-expansion), and `withinRemaining` (module-report-lsp).
+ *
+ * The differences between them were real — timeout can *reject* or *resolve
+ * undefined*, and the raced promise's own rejection can *propagate* or be
+ * *swallowed* — so they are kept as named adapters over one core. Consolidating
+ * fixes two latent bugs the copies had: `withBudget` did not suppress the loser
+ * promise's late rejection (an unhandled rejection if the timer won first), and
+ * `withinRemaining` never cleared its timer.
+ */
+export function withDeadline(promise, options) {
+    const onTimeout = options.onTimeout ?? "reject";
+    const onReject = options.onReject ?? "propagate";
+    const ms = options.ms ??
+        (options.deadlineAt !== undefined ? options.deadlineAt - Date.now() : 0);
+    // Past deadline / non-positive budget: settle immediately, no timer.
+    if (ms <= 0) {
+        return onTimeout === "undefined"
+            ? Promise.resolve(undefined)
+            : Promise.reject(new Error(`Timeout after ${Math.max(0, ms)}ms`));
+    }
+    // Base promise with rejection handled per `onReject`. In propagate mode we
+    // still attach a no-op catch so that if the timer wins the race, the loser
+    // promise's later rejection does not surface as an unhandled rejection.
+    const base = onReject === "undefined" ? promise.catch(() => undefined) : promise;
+    if (onReject === "propagate")
+        promise.catch(() => { });
+    let timer;
+    const timeoutPromise = new Promise((resolve, reject) => {
+        timer = setTimeout(() => {
+            if (onTimeout === "undefined")
+                resolve(undefined);
+            else
+                reject(new Error(`Timeout after ${ms}ms`));
+        }, ms);
+    });
+    return Promise.race([base, timeoutPromise]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+/**
+ * Resolve `promise`, or reject with `Error("Timeout after <ms>ms")` once
+ * `timeoutMs` elapses. The raced promise's own rejection propagates.
+ */
+export function withTimeout(promise, timeoutMs) {
+    return withDeadline(promise, { ms: timeoutMs });
+}
+/**
+ * Resolve `promise`, or `undefined` once `budgetMs` elapses (a non-positive
+ * budget resolves `undefined` immediately). The raced promise's own rejection
+ * propagates.
+ */
+export function withBudget(promise, budgetMs) {
+    return withDeadline(promise, { ms: budgetMs, onTimeout: "undefined" });
+}
+/**
+ * Resolve `promise`, or `undefined` once the shared `deadlineAt` passes (a past
+ * deadline resolves `undefined` immediately). The raced promise's own rejection
+ * is swallowed to `undefined`.
+ */
+export function withinRemaining(promise, deadlineAt) {
+    return withDeadline(promise, {
+        deadlineAt,
+        onTimeout: "undefined",
+        onReject: "undefined",
+    });
+}

package/dist/clients/dependency-checker.js

@@ -11,6 +11,54 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { safeSpawnAsync } from "./safe-spawn.js";
+/**
+ * Build madge's argv for a circular-dependency scan.
+ *
+ * Two correctness levers beyond the bare `--circular`:
+ *   - `mjs,cjs` extensions: without them madge ignores explicit ESM/CJS files,
+ *     dropping their edges from the graph.
+ *   - `--ts-config <tsconfig.json>`: madge can only resolve TypeScript `paths`
+ *     aliases (`@/foo`, `~/bar`) when pointed at the tsconfig. Without it those
+ *     imports are silently unresolved, so cycles that route through an alias are
+ *     MISSED (false negatives). Passed only when a tsconfig actually exists, so
+ *     non-TS / alias-free projects are unaffected.
+ */
+export function buildMadgeArgs(target, projectRoot) {
+    const args = ["--circular", "--extensions", "ts,tsx,js,jsx,mjs,cjs"];
+    const tsConfig = path.join(projectRoot, "tsconfig.json");
+    if (fs.existsSync(tsConfig)) {
+        args.push("--ts-config", tsConfig);
+    }
+    // --warning surfaces files madge couldn't resolve into the graph (to stderr;
+    // stdout JSON is unaffected). Without it those skips are SILENT — and a
+    // skipped *local* file could hide a real cycle. We log them (see
+    // parseMadgeSkips) instead of discarding stderr.
+    args.push("--warning", "--json", target);
+    return args;
+}
+/**
+ * Parse madge's `--warning` stderr for skipped (unresolvable) files. External
+ * package specifiers (bare names / subpaths like `web-tree-sitter`,
+ * `vitest/config`) are expected — madge doesn't traverse node_modules. We flag
+ * only **local** skips (relative/absolute paths), which are the ones that could
+ * silently drop an internal edge and hide a cycle.
+ *
+ * @returns total skip count and the subset that look local.
+ */
+export function parseMadgeSkips(stderr) {
+    const lines = (stderr || "").split(/\r?\n/);
+    const headerIdx = lines.findIndex((l) => /Skipped\s+\d+\s+file/i.test(l));
+    if (headerIdx === -1)
+        return { total: 0, local: [] };
+    const total = Number.parseInt(lines[headerIdx].match(/Skipped\s+(\d+)/i)?.[1] ?? "0", 10) ||
+        0;
+    const specifiers = lines
+        .slice(headerIdx + 1)
+        .map((l) => l.trim())
+        .filter(Boolean);
+    const local = specifiers.filter((s) => s.startsWith(".") || s.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(s));
+    return { total, local };
+}
 // --- Client ---
 export class DependencyChecker {
     available = null;
@@ -202,14 +250,7 @@ export class DependencyChecker {
         this.log(`Imports changed for ${path.basename(normalized)}, checking dependencies...`);
         // Run madge on the specific file (fast)
         try {
-            const result = await safeSpawnAsync("npx", [
-                "madge",
-                "--circular",
-                "--extensions",
-                "ts,tsx,js,jsx",
-                "--json",
-                normalized,
-            ], {
+            const result = await safeSpawnAsync("npx", ["madge", ...buildMadgeArgs(normalized, projectRoot)], {
                 timeout: 15000,
                 cwd: projectRoot,
             });
@@ -240,11 +281,16 @@ export class DependencyChecker {
             }
             this.lastCircular = circular;
             this.circularFiles = circularFiles;
+            const skips = parseMadgeSkips(result.stderr || "");
+            if (skips.local.length > 0) {
+                this.log(`madge skipped ${skips.local.length} local file(s) (possible silent cycle-miss): ${skips.local.slice(0, 5).join(", ")}`);
+            }
             return {
                 hasCircular: circular.length > 0,
                 circular: circular.filter((d) => d.file === normalized || d.path.includes(normalized)),
                 checked: true,
                 cacheHit: false,
+                localSkips: skips.local.length,
             };
         }
         catch (err) {
@@ -298,14 +344,7 @@ export class DependencyChecker {
     }
     async runScanProject(projectRoot) {
         try {
-            const result = await safeSpawnAsync("npx", [
-                "madge",
-                "--circular",
-                "--extensions",
-                "ts,tsx,js,jsx",
-                "--json",
-                projectRoot,
-            ], {
+            const result = await safeSpawnAsync("npx", ["madge", ...buildMadgeArgs(projectRoot, projectRoot)], {
                 timeout: 30000,
                 cwd: projectRoot,
             });

package/dist/clients/deps/ast-grep-napi.js

@@ -0,0 +1,3 @@
+export function loadAstGrepNapi() {
+    return import("@ast-grep/napi");
+}