@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/knip-client.js

@@ -9,12 +9,18 @@
  * Docs: https://knip.dev/
  */
 import { createSubsystemLogger } from "./extension-log.js";
+import { incrementDegradationCount } from "./degradation-ledger.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "./file-utils.js";
 import { findNearestMarkerRoot } from "./path-utils.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
-import { createAvailabilityChecker, getManagedToolEnvironment, resolveAvailableOrInstall, } from "./dispatch/runners/utils/runner-helpers.js";
+import { createAvailabilityChecker, findManagedNodeToolBinary, getManagedToolEnvironment, resolveAvailableOrInstall, } from "./dispatch/runners/utils/runner-helpers.js";
+import { createAvailabilityLatch, describeUnavailability, } from "./dispatch/runners/utils/availability-policy.js";
+import { spawnFailedWithNoOutput } from "./dispatch/runners/utils/spawn-outcome.js";
+import { formatToolFailure } from "./dispatch/runners/utils/tool-failure.js";
+import { findLocalBinUpwards } from "./package-manager.js";
+import { logSessionStart } from "./sessionstart-logger.js";
 const EMPTY_RESULT = {
     success: false,
     issues: [],
@@ -56,13 +62,118 @@ export function readOverridePinnedPackageNames(targetDir) {
     collectKeys(pkg.pnpm?.overrides);
     return names;
 }
+/**
+ * knip's own config-file names, in knip's discovery order (knip 6
+ * `configFilesLookup`). Used for REPORTING which config a run resolved — the
+ * runner never passes `--config`, so knip still does its own discovery from the
+ * spawn cwd. Reading the same list here keeps the recorded answer honest
+ * instead of guessing "knip.json or nothing".
+ */
+const KNIP_CONFIG_FILENAMES = [
+    "knip.json",
+    "knip.jsonc",
+    "knip.ts",
+    "knip.js",
+    "knip.config.ts",
+    "knip.config.js",
+    ".knip.json",
+    ".knip.jsonc",
+    ".knip.ts",
+    ".knip.js",
+];
+/**
+ * The knip config this project ships, relative to `targetDir`, or null when the
+ * project ships none (knip then runs on its built-in defaults).
+ *
+ * `package.json` is reported last and only when it carries a `knip` field —
+ * knip reads that field as a config source, and a project that configures knip
+ * there is just as configured as one with a `knip.json`.
+ */
+export function resolveProjectKnipConfig(targetDir) {
+    for (const name of KNIP_CONFIG_FILENAMES) {
+        if (fs.existsSync(path.join(targetDir, name)))
+            return name;
+    }
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(targetDir, "package.json"), "utf-8"));
+        if (pkg && typeof pkg === "object" && pkg.knip !== undefined) {
+            return "package.json#knip";
+        }
+    }
+    catch {
+        // No/malformed package.json — "no project config" is the honest answer.
+    }
+    return null;
+}
+/**
+ * The knip the PROJECT itself would run: its own `node_modules/.bin/knip`,
+ * walking up so a workspace package finds the monorepo's hoisted copy. Null
+ * when the project installs no knip and pi-lens's managed shim is all there is.
+ *
+ * A project that installs knip pins the version its config is written against,
+ * and that version is what the project's `npx knip` / `npm run knip` runs.
+ * Preferring pi-lens's managed shim instead makes the lens report a DIFFERENT
+ * tool's verdict under the project's config (#1721): a managed knip 6.4.1
+ * flagged 62 unused type exports on a tree that knip 6.32.2 leaves clean, and
+ * every one of those flags is destructive advice.
+ *
+ * The walk is the shared `findLocalBinUpwards`, the same one behind jscpd's
+ * (`clients/jscpd-client.ts:269`) and madge's
+ * (`clients/dependency-checker.ts:420`) resolution, rather than a fourth copy.
+ * It stops at the filesystem half deliberately: the global-bin step those two
+ * add spawns a probe per package manager, and this runs on every analyze().
+ */
+export function resolveProjectKnipBinary(targetDir) {
+    return findLocalBinUpwards("knip", targetDir) ?? null;
+}
+/**
+ * Classify a resolved shim for the toolchain record: inside the project tree,
+ * elsewhere on the user's machine, or pi-lens's own managed/PATH fallback.
+ */
+export function classifyKnipBinary(binary, targetDir) {
+    if (binary === null)
+        return "managed-or-path";
+    const relative = path.relative(path.resolve(targetDir), path.resolve(binary));
+    return relative === "" || relative.startsWith("..") || path.isAbsolute(relative)
+        ? "global"
+        : "project";
+}
+/**
+ * The version of the knip package behind a resolved shim, read from disk (no
+ * spawn — a `--version` probe per project root would add a process to a hot
+ * path for a telemetry field). Returns null for a bare PATH command, whose
+ * package location is unknown.
+ */
+function readKnipShimVersion(binary) {
+    if (!path.isAbsolute(binary))
+        return null;
+    const binDir = path.dirname(binary);
+    if (path.basename(binDir) !== ".bin")
+        return null;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(path.dirname(binDir), "knip", "package.json"), "utf-8"));
+        const version = pkg.version;
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Distinct toolchain records kept per client instance (bounded telemetry). */
+const MAX_RECORDED_TOOLCHAINS = 32;
 // --- Client ---
 export class KnipClient {
     knipAvailability = createAvailabilityChecker("knip", ".cmd", ["--version"], {
         environment: (cwd) => getManagedToolEnvironment("knip", cwd),
         unclassifiedFailureOutcome: "missing",
+        fastPath: () => findManagedNodeToolBinary("knip"),
     });
-    knipAvailable = null;
+    /**
+     * Client-side memo. Only a DURABLE verdict is latched — a transient probe
+     * failure expires, so an installed knip becomes available again without a
+     * host restart (#1467).
+     */
+    availabilityLatch = createAvailabilityLatch();
     knipCommand = "knip";
     ensureInFlight = null;
     log;
@@ -80,11 +191,22 @@ export class KnipClient {
      * in-flight promise; completing clears the slot.
      */
     inFlight = new Map();
+    /** Last successful result per project and runtime content generation. */
+    completedByProject = new Map();
+    /**
+     * (project root, binary, config) triples already recorded, so the toolchain
+     * row is written once per distinct resolution instead of once per run.
+     */
+    recordedToolchains = new Set();
     constructor(verbose = false) {
         this.log = verbose
             ? createSubsystemLogger("knip")
             : () => { };
     }
+    /** Re-arm content-keyed reuse at the session boundary. */
+    resetSessionState() {
+        this.completedByProject.clear();
+    }
     /**
      * Find the nearest directory with a project/knip config marker.
      *
@@ -104,12 +226,17 @@ export class KnipClient {
         return findNearestMarkerRoot(startDir, ["package.json", "knip.json", "knip.ts", "knip.config.js", "knip.config.ts"], { boundaries: [".git", ".hg", ".svn"], homeDir: homeDirOverride });
     }
     /**
-     * Check if knip CLI is available, auto-install if not
+     * Check if knip CLI is available, auto-install if not.
+     *
+     * The memo returns `null` when the last verdict was transient and its
+     * cooldown has expired, which re-enters the probe. That is the difference
+     * between "knip is missing" (a fact worth caching) and "the probe timed out"
+     * (a moment worth retrying).
      */
     async ensureAvailable() {
-        // Fast path: already checked
-        if (this.knipAvailable !== null)
-            return this.knipAvailable;
+        const memo = this.availabilityLatch.read();
+        if (memo !== null)
+            return memo;
         if (this.ensureInFlight)
             return this.ensureInFlight;
         this.ensureInFlight = this.doEnsureAvailable();
@@ -121,11 +248,39 @@ export class KnipClient {
         }
     }
     async doEnsureAvailable() {
-        const resolved = await resolveAvailableOrInstall(this.knipAvailability, "knip", process.cwd());
-        this.knipAvailable = resolved !== null;
-        if (resolved)
+        const cwd = process.cwd();
+        const resolved = await resolveAvailableOrInstall(this.knipAvailability, "knip", cwd);
+        if (resolved !== null) {
             this.knipCommand = resolved;
-        return this.knipAvailable;
+            this.availabilityLatch.noteAvailable();
+            return true;
+        }
+        const verdict = this.knipAvailability.getVerdict(cwd);
+        this.availabilityLatch.noteUnavailable(verdict.outcome ?? "missing", verdict.cause ?? "not-found");
+        return false;
+    }
+    /**
+     * The single place a knip-unavailable result is worded. A transient probe
+     * failure must never be reported as "install knip" — knip is on disk.
+     */
+    unavailableResult() {
+        const verdict = this.knipAvailability.getVerdict(process.cwd());
+        const transient = verdict.outcome === "transient";
+        const retryAfterMs = verdict.retryAtMs
+            ? Math.max(0, verdict.retryAtMs - Date.now())
+            : undefined;
+        return {
+            ...EMPTY_RESULT,
+            failureKind: transient ? "unavailable-transient" : "unavailable-missing",
+            summary: describeUnavailability({
+                tool: "Knip",
+                installHint: "npm install -D knip",
+                outcome: verdict.outcome,
+                cause: verdict.cause,
+                elapsedMs: verdict.elapsedMs,
+                retryAfterMs,
+            }),
+        };
     }
     /**
      * Run knip analysis on the project.
@@ -137,8 +292,13 @@ export class KnipClient {
      *
      * Re-entrancy safe: concurrent calls resolving to the same project
      * root share a single knip process via `inFlight`.
+     *
+     * Successful memo hits validate package.json and the resolved Knip config
+     * with bounded metadata checks. The two statSync calls replace a 10-23
+     * second project scan. Source-only external edits remain undetected until
+     * pi observes a write or the session resets.
      */
-    async analyze(cwd, _ignore) {
+    async analyze(cwd, _ignore, options = {}) {
         const targetDir = this.resolveProjectRoot(cwd || process.cwd());
         if (!targetDir) {
             // No package.json / knip config anywhere up the tree. Running knip
@@ -151,33 +311,97 @@ export class KnipClient {
                 summary: "No project root found; knip skipped",
             };
         }
-        if (!(await this.ensureAvailable())) {
-            return {
-                ...EMPTY_RESULT,
-                summary: "Knip not available. Install with: npm install -D knip",
-            };
-        }
         const key = path.resolve(targetDir);
+        const completed = this.completedByProject.get(key);
+        if (options.projectSeq !== undefined &&
+            completed?.projectSeq === options.projectSeq &&
+            this.matchesMemoSignal(targetDir, completed.signal)) {
+            this.log(`Analysis cache hit for ${key} at projectSeq ${options.projectSeq}`);
+            return { ...completed.result, execution: "cache" };
+        }
+        // A project that ships its own knip needs no managed install and no
+        // managed probe — the shim is already on disk, and gating on
+        // `ensureAvailable()` would tell such a project to "npm install -D knip"
+        // whenever the MANAGED copy is missing (#1721).
+        if (resolveProjectKnipBinary(targetDir) === null &&
+            !(await this.ensureAvailable())) {
+            return this.unavailableResult();
+        }
         const existing = this.inFlight.get(key);
         if (existing) {
             this.log(`Analysis already in flight for ${key}; sharing result`);
             return existing;
         }
-        const promise = this.runAnalyze(key).finally(() => {
+        const promise = this.runAnalyze(key)
+            .then((result) => {
+            const executed = { ...result, execution: "executed" };
+            if (result.success && options.projectSeq !== undefined) {
+                this.completedByProject.set(key, {
+                    projectSeq: options.projectSeq,
+                    result: executed,
+                    signal: this.readMemoSignal(key),
+                });
+            }
+            return executed;
+        })
+            .finally(() => {
             this.inFlight.delete(key);
         });
         this.inFlight.set(key, promise);
         return promise;
     }
+    readMemoFileSignal(filePath) {
+        try {
+            const stat = fs.statSync(filePath);
+            return { path: filePath, mtimeMs: stat.mtimeMs, size: stat.size };
+        }
+        catch {
+            return null;
+        }
+    }
+    readMemoSignal(targetDir) {
+        const config = resolveProjectKnipConfig(targetDir);
+        return {
+            packageJson: this.readMemoFileSignal(path.join(targetDir, "package.json")),
+            config: config && config !== "package.json#knip"
+                ? this.readMemoFileSignal(path.join(targetDir, config))
+                : null,
+        };
+    }
+    matchesMemoSignal(targetDir, signal) {
+        const current = {
+            packageJson: this.readMemoFileSignal(path.join(targetDir, "package.json")),
+            config: signal.config ? this.readMemoFileSignal(signal.config.path) : null,
+        };
+        return (JSON.stringify(current.packageJson) === JSON.stringify(signal.packageJson) &&
+            JSON.stringify(current.config) === JSON.stringify(signal.config));
+    }
     async runAnalyze(targetDir) {
         // Cache dir is routed through pi-lens's project-data-dir convention (NOT
         // knip's own default `./node_modules/.cache/knip`) so it lives alongside
         // every other project cache (see cache-manager.ts, call-graph.ts) and is
         // covered by the existing `.pi-lens/` gitignore entry.
         //
-        // Caveat (per knip's docs): a cached run does NOT pick up newly-added
-        // `.gitignore` files automatically — the cache must be deleted to detect
-        // them. Not auto-handled here; this is a documented tradeoff, not a bug.
+        // Documented cache-invalidation gaps (both live in knip's own cache, not
+        // in pi-lens):
+        //
+        // 1. `.gitignore` (per knip's docs): a cached run does NOT pick up
+        //    newly-added `.gitignore` files automatically — the cache must be
+        //    deleted to detect them. Not auto-handled here; documented tradeoff.
+        // 2. Consumer-side imports (#1630): knip's glob cache records the mtime of
+        //    every directory that CONTRIBUTED a matched path, and revalidates
+        //    against those. A directory that matched nothing at cache time is not
+        //    recorded, so a file later added to it is invisible to the cached
+        //    glob. A new test that imports an export therefore never reaches the
+        //    graph, and knip keeps reporting that export as unused — a stale
+        //    verdict pi-lens then renders as fresh. Fixed upstream in knip 6.28.0
+        //    (glob cache now tracks every directory it reads), but the managed
+        //    install floats and older versions are common in the field, so
+        //    `pruneStaleGlobCache()` below drops the glob cache on every run
+        //    regardless of version. Measured on this repo with knip 6.4.1:
+        //    uncached 3.3s, fully cached 1.3s, glob-cache-dropped 1.4s. The glob
+        //    cache is worth ~0.1s of the ~2.0s the cache saves, so dropping it
+        //    buys correctness for almost nothing.
         const cacheLocation = path.join(getProjectDataDir(targetDir), "cache", "knip");
         // knip (verified against 6.26.0) silently fails to persist the cache when
         // `--cache-location` points at a directory that doesn't exist yet: its
@@ -193,6 +417,7 @@ export class KnipClient {
         catch (err) {
             this.log(`Failed to pre-create knip cache dir ${cacheLocation}: ${err}`);
         }
+        this.pruneStaleGlobCache(cacheLocation);
         const args = [
             "--reporter=json",
             "--include",
@@ -205,7 +430,14 @@ export class KnipClient {
             "--cache-location",
             cacheLocation,
         ];
-        const result = await safeSpawnAsync(this.knipCommand, args, {
+        // Project toolchain first. #1199 already put `<targetDir>/node_modules/.bin`
+        // at the front of the child PATH for exactly this preference, but the spawn
+        // command is an ABSOLUTE managed path, so PATH order never got a say
+        // (#1721). Resolving the command here is what makes that intent real.
+        const projectBinary = resolveProjectKnipBinary(targetDir);
+        const command = projectBinary ?? this.knipCommand;
+        this.recordToolchain(targetDir, command, classifyKnipBinary(projectBinary, targetDir));
+        const result = await safeSpawnAsync(command, args, {
             timeout: ANALYSIS_TIMEOUT_MS,
             cwd: targetDir,
             env: await getManagedToolEnvironment("knip", targetDir),
@@ -217,13 +449,55 @@ export class KnipClient {
                 summary: `Error: ${result.error.message}`,
             };
         }
-        // Knip exits 0 on success (even with issues), 1 on errors
+        // Empirical exit-code table (knip 6.4.1, verified live for #1736): 0 =
+        // clean run, JSON stdout `{"issues":[]}`; 1 = clean run WITH findings,
+        // JSON stdout `{"issues":[...]}`; 2 = config/load error, empty or
+        // non-JSON stdout with the error on stderr. A genuinely clean run's
+        // stdout is therefore NEVER empty — knip always prints at least
+        // `{"issues":[]}` on exit 0. Empty stdout only ever shows up paired
+        // with a NONZERO exit (a broken shim, a crash, or knip's own load
+        // error), so `status !== 0 && !output.trim()` is unambiguous evidence
+        // of a failed run, never a clean one.
         const output = result.stdout || "";
-        this.log(`Knip output length: ${output.length}`);
+        this.log(`Knip output length: ${output.length}, exit status: ${result.status}`);
         if (output.length < 500) {
             this.log(`Knip output sample: ${output}`);
         }
         if (!output.trim()) {
+            // Reuses the SAME discriminator every dispatch/runners linter uses
+            // (`spawnFailedWithNoOutput`, `clients/dispatch/runners/utils/
+            // spawn-outcome.ts`) rather than a parallel hand-rolled check — a
+            // nonzero exit with nothing to parse is never a clean run, here or
+            // there.
+            if (spawnFailedWithNoOutput(result, output)) {
+                // #1816: one shared wording, one truncation, signal named. The
+                // binary-source discriminator (#1721's whole point — WHICH knip
+                // ran) survives as a named field rather than as prose.
+                const reason = formatToolFailure({
+                    tool: "knip",
+                    status: result.status,
+                    signal: result.signal,
+                    stderr: result.stderr,
+                    fields: {
+                        command,
+                        source: classifyKnipBinary(projectBinary, targetDir),
+                    },
+                });
+                this.log(reason);
+                incrementDegradationCount({
+                    kind: "runner-empty-result",
+                    subject: "knip",
+                    reason,
+                });
+                return {
+                    ...EMPTY_RESULT,
+                    summary: `Knip exited ${result.status} with no output; run skipped`,
+                };
+            }
+            // status === 0 with empty stdout has never been observed against a
+            // real knip binary (a genuine clean run still prints
+            // `{"issues":[]}`), but a defensive fallback is cheap insurance
+            // against a future knip release that changes this.
             return {
                 ...EMPTY_RESULT,
                 success: true,
@@ -232,6 +506,69 @@ export class KnipClient {
         }
         return this.dropOverridePinnedDeps(this.parseOutput(output), targetDir);
     }
+    /**
+     * Record WHICH knip a run used and WHICH config it ran under (#1721).
+     *
+     * The dogfood failure this fixes was invisible from the outside: the lens
+     * reported 62 unused type exports and the project's own `npx knip` reported
+     * none, with nothing in any log to say the two ran different binaries. This
+     * row is that missing evidence — it names the shim, its version, the config
+     * knip will discover, and whether the shim came from the project or from
+     * pi-lens.
+     *
+     * Bounded twice over: one row per distinct (project root, binary, config)
+     * triple, and at most `MAX_RECORDED_TOOLCHAINS` distinct triples per client.
+     * Steady-state cost is therefore one line per project per session, not one
+     * per turn_end.
+     */
+    recordToolchain(targetDir, command, source) {
+        const config = resolveProjectKnipConfig(targetDir);
+        const key = `${targetDir} ${command} ${config ?? ""}`;
+        if (this.recordedToolchains.has(key))
+            return;
+        if (this.recordedToolchains.size >= MAX_RECORDED_TOOLCHAINS)
+            return;
+        this.recordedToolchains.add(key);
+        const version = readKnipShimVersion(command);
+        logSessionStart(`knip toolchain ${targetDir}: binary=${command}` +
+            `${version ? ` version=${version}` : ""}` +
+            ` source=${source}` +
+            ` config=${config ?? "none (knip defaults)"}`);
+    }
+    /**
+     * Delete knip's glob cache (`glob-<version>.cache`) before every run (#1630).
+     *
+     * knip revalidates a cached glob against the mtimes of the directories that
+     * contributed a matched path. Directories that matched nothing are never
+     * recorded, so files later added to them stay invisible and knip keeps
+     * reporting an export as unused after a new consumer imports it. Removing
+     * this one file forces a fresh file walk while the module and plugin caches —
+     * which carry nearly all of the cache's speed — survive.
+     *
+     * Failures are logged and ignored: a glob cache we could not delete degrades
+     * to the pre-#1630 behavior, which is stale but not fatal.
+     */
+    pruneStaleGlobCache(cacheLocation) {
+        let entries;
+        try {
+            entries = fs.readdirSync(cacheLocation);
+        }
+        catch (err) {
+            this.log(`Failed to read knip cache dir ${cacheLocation}: ${err}`);
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.startsWith("glob-") || !entry.endsWith(".cache"))
+                continue;
+            try {
+                fs.rmSync(path.join(cacheLocation, entry), { force: true });
+                this.log(`Pruned knip glob cache ${entry}`);
+            }
+            catch (err) {
+                this.log(`Failed to prune knip glob cache ${entry}: ${err}`);
+            }
+        }
+    }
     /**
      * Drop `dependency`/`devDependency` issues for a package that's also
      * referenced as an npm `overrides` (or Yarn `resolutions` / pnpm

package/node_modules/pi-lens/dist/clients/language-policy.js

@@ -61,6 +61,7 @@ export const LANGUAGE_POLICY = {
     gleam: { lspCapable: true },
     ocaml: { lspCapable: true },
     clojure: { lspCapable: true },
+    cue: { lspCapable: true },
     terraform: { lspCapable: true },
     terragrunt: { lspCapable: false },
     nix: { lspCapable: true },
@@ -119,7 +120,7 @@ const PRIMARY_DISPATCH_GROUPS = {
     },
     yaml: {
         mode: "all",
-        runnerIds: ["lsp", "yamllint", "trivy-config", "helm-lint"],
+        runnerIds: ["lsp", "yamllint", "trivy-config", "helm-lint", "helm-render"],
         filterKinds: ["yaml"],
     },
     sql: {
@@ -183,7 +184,9 @@ const PRIMARY_DISPATCH_GROUPS = {
     haskell: { mode: "fallback", runnerIds: ["lsp"], filterKinds: ["haskell"] },
     "helm-template": {
         mode: "all",
-        runnerIds: ["helm-lint"],
+        // helm-render is opt-in (`helm.renderValidation.enabled`) and skips itself
+        // when the switch is absent, so it costs nothing when unconfigured (#1283).
+        runnerIds: ["helm-lint", "helm-render"],
         filterKinds: ["helm-template"],
     },
     elixir: {
@@ -198,6 +201,9 @@ const PRIMARY_DISPATCH_GROUPS = {
     },
     ocaml: { mode: "fallback", runnerIds: ["lsp"], filterKinds: ["ocaml"] },
     clojure: { mode: "fallback", runnerIds: ["lsp"], filterKinds: ["clojure"] },
+    // #1522: cuelsp reports syntax/parse errors only; cue-vet covers the
+    // evaluation-error class the language server deliberately doesn't publish.
+    cue: { mode: "all", runnerIds: ["lsp", "cue-vet"], filterKinds: ["cue"] },
     terraform: {
         mode: "all",
         runnerIds: ["lsp", "tflint", "trivy-config"],

package/node_modules/pi-lens/dist/clients/language-profile.js

@@ -35,6 +35,7 @@ const PROJECT_MARKERS_BY_KIND = {
     swift: ["Package.swift"],
     dart: ["pubspec.yaml"],
     elixir: ["mix.exs"],
+    cue: ["cue.mod"],
     gleam: ["gleam.toml"],
     terraform: [".terraform.lock.hcl"],
     terragrunt: TERRAGRUNT_FILENAMES,
@@ -80,6 +81,7 @@ const ROOT_MARKERS_BY_KIND = {
     swift: ["Package.swift"],
     dart: ["pubspec.yaml"],
     elixir: ["mix.exs"],
+    cue: ["cue.mod", ".git"],
     gleam: ["gleam.toml"],
     terraform: [".terraform.lock.hcl"],
     terragrunt: TERRAGRUNT_FILENAMES,