@herbertgao/pi-extensions 2026.8.3 → 2026.8.5

package/node_modules/pi-lens/dist/clients/smells-rollup.js

@@ -0,0 +1,224 @@
+/**
+ * Automatic smells self-surfacing (#1123 item 3).
+ *
+ * `scripts/analyze-pi-lens-logs.mjs` (`npm run logs:smells`) already detects
+ * a wide catalogue of operational smells, but it is MANUAL — an operator has
+ * to think to run it. The #1123 investigation found 20 stale-ctx
+ * `emit_failed` rows (see `session-lifecycle.ts`'s stale-ctx guard) and 37
+ * opengrep respawns sitting in logs for days before an audit went looking.
+ * This module closes that gap with a small, ALWAYS-ON rollup that surfaces a
+ * subset of the analyzer's smells without anyone running the script.
+ *
+ * COST BOUND (the constraint that shapes the design): `~/.pi-lens/*.log`
+ * files are size-rotated at `PI_LENS_MAX_LOG_SIZE_MB` (default 10MB,
+ * `clients/log-cleanup.ts`). Re-scanning a whole rotated log on every
+ * `session_start` — the analyzer's own approach — is exactly the megabyte
+ * full-file read `session_start` (a hot, input-latency-sensitive path, see
+ * `runtime-session.ts`'s cold-start comment) cannot afford. So this module
+ * does a BOUNDED TAIL READ: at most `SMELLS_TAIL_BYTES_PER_FILE` bytes from
+ * the END of each source log, via a single `pread`-style `fs.readSync` at a
+ * computed offset — never a full-file read, by construction (see
+ * `tailReadText`). Two source files, ~64KB each: ~128KB total I/O, once per
+ * session_start plus one bounded re-check every `SMELLS_TURN_CHECK_INTERVAL`
+ * turns — negligible next to the multi-second full startup walk it rides
+ * alongside.
+ *
+ * The tail scan is bounded, but the tail can contain prior-session rows. The
+ * session-start caller supplies the session boundary, and rows are admitted
+ * only when their own UTC timestamp is at or after that boundary. This keeps
+ * the same bounded read without reporting historical failures as current, so
+ * this module does not additionally instrument the write call sites
+ * (`bus-publish.ts`, `clients/lsp/index.ts`'s respawn path) with parallel
+ * live counters. That keeps the change contained to one new module + three
+ * small call sites (session_start, `/lens-health`, `turn_end`) instead of
+ * touching every producer of the two source logs.
+ *
+ * Smells covered (deliberately a SUBSET — the two the issue named as having
+ * gone unnoticed; the full catalogue stays in the manual analyzer):
+ *   - stale-ctx `emit_failed`: `bus-events.log` rows where
+ *     `outcome === "emit_failed"` and `error` contains the SDK's
+ *     `"stale after session replacement"` fragment (the known-benign class
+ *     `session-lifecycle.ts` documents — still worth a glance if it recurs
+ *     often, since a HIGH count could mask a real regression).
+ *   - opengrep respawns: `latency.log` rows where
+ *     `phase === "lsp_server_respawn"` and `metadata.serverId === "opengrep"`
+ *     (`clients/lsp/index.ts`'s existing respawn log point — unmodified).
+ *
+ * Both counters are gated by trivial threshold constants (`SMELLS_THRESHOLDS`)
+ * so a single stray event never surfaces noise — only a repeating pattern
+ * does, matching the analyzer's own low/medium/high severity gating.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getGlobalPiLensDir } from "./file-utils.js";
+/** Bounded tail-read budget PER source log file — never a full-file scan. */
+export const SMELLS_TAIL_BYTES_PER_FILE = 64 * 1024;
+/** Re-check cadence at `turn_end`, mirroring `memory-sampler.ts`'s pattern —
+ *  cheap enough (bounded ~128KB I/O) not to need finer throttling, but a
+ *  fixed interval keeps it from running on every single turn. */
+export const SMELLS_TURN_CHECK_INTERVAL = 20;
+/** Trivial threshold constants (#1123 item 3's explicit design ask). Counts
+ *  strictly below these never surface anywhere. */
+export const SMELLS_THRESHOLDS = {
+    staleCtxEmitFailed: 5,
+    opengrepRespawn: 5,
+};
+const SMELL_LABELS = {
+    staleCtxEmitFailed: "stale-ctx emit_failed (bus-events.log)",
+    opengrepRespawn: "opengrep respawn (latency.log)",
+};
+const SMELL_KEYS = ["staleCtxEmitFailed", "opengrepRespawn"];
+/**
+ * Read at most `maxBytes` from the END of `filePath`. Never reads more than
+ * that regardless of the file's actual size — the cost bound is enforced by
+ * construction (a single sized `fs.readSync` at a computed offset), not by a
+ * convention callers have to remember. Missing file / unreadable → "".
+ *
+ * The leading (possibly partial) line is dropped whenever the read started
+ * mid-file, since we can't tell if it's a truncated JSON row.
+ */
+export function tailReadText(filePath, maxBytes) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, "r");
+    }
+    catch {
+        return "";
+    }
+    try {
+        const size = fs.fstatSync(fd).size;
+        const readBytes = Math.min(size, maxBytes);
+        if (readBytes <= 0)
+            return "";
+        const start = size - readBytes;
+        const buf = Buffer.alloc(readBytes);
+        fs.readSync(fd, buf, 0, readBytes, start);
+        const text = buf.toString("utf8");
+        if (start <= 0)
+            return text;
+        const firstNewline = text.indexOf("\n");
+        return firstNewline >= 0 ? text.slice(firstNewline + 1) : "";
+    }
+    catch {
+        return "";
+    }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            /* already closed / nothing to do */
+        }
+    }
+}
+function countMatchingLines(text, predicate, sessionStartMs) {
+    let count = 0;
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue; // partial/corrupt line at the tail boundary — skip, don't throw
+        }
+        if (entry &&
+            typeof entry === "object" &&
+            (sessionStartMs === undefined ||
+                isAtOrAfterSessionStart(entry, sessionStartMs)) &&
+            predicate(entry)) {
+            count++;
+        }
+    }
+    return count;
+}
+function isAtOrAfterSessionStart(entry, sessionStartMs) {
+    const timestamp = typeof entry.ts === "string" ? Date.parse(entry.ts) : NaN;
+    return Number.isFinite(timestamp) && timestamp >= sessionStartMs;
+}
+function isStaleCtxEmitFailed(entry) {
+    return (entry.outcome === "emit_failed" &&
+        typeof entry.error === "string" &&
+        entry.error.includes("stale after session replacement"));
+}
+function isOpengrepRespawn(entry) {
+    if (entry.phase !== "lsp_server_respawn")
+        return false;
+    const metadata = entry.metadata;
+    return metadata?.serverId === "opengrep";
+}
+/**
+ * Bounded tail-scan of the two source logs. Total I/O is capped at
+ * `2 * SMELLS_TAIL_BYTES_PER_FILE` regardless of how large the (size-rotated,
+ * up to ~10MB) source files are. `root` is injectable for tests.
+ */
+export function countRecentSmells(root = getGlobalPiLensDir(), sessionStartMs) {
+    const busTail = tailReadText(path.join(root, "bus-events.log"), SMELLS_TAIL_BYTES_PER_FILE);
+    const latencyTail = tailReadText(path.join(root, "latency.log"), SMELLS_TAIL_BYTES_PER_FILE);
+    return {
+        staleCtxEmitFailed: countMatchingLines(busTail, isStaleCtxEmitFailed, sessionStartMs),
+        opengrepRespawn: countMatchingLines(latencyTail, isOpengrepRespawn, sessionStartMs),
+    };
+}
+/**
+ * One `sessionstart.log` line, gated to fire only when at least one smell is
+ * AT/ABOVE its threshold — `null` (nothing logged) otherwise, so an ordinary
+ * session never gets a noise line. Pairs with `logSessionStart` the same way
+ * every other `session_start ...` line does (see `runtime-session.ts`).
+ */
+export function formatSmellsSessionStartLine(counts) {
+    const bits = [];
+    for (const key of SMELL_KEYS) {
+        if (counts[key] >= SMELLS_THRESHOLDS[key]) {
+            bits.push(`${SMELL_LABELS[key]} x${counts[key]}`);
+        }
+    }
+    if (bits.length === 0)
+        return null;
+    const tailKb = Math.round(SMELLS_TAIL_BYTES_PER_FILE / 1024);
+    return `session_start smells (last ${tailKb}KB tail): ${bits.join(", ")} — run \`npm run logs:smells\` for detail`;
+}
+/**
+ * Compact, ALWAYS-shown `/lens-health` line (unconditional, like
+ * `memory-sampler.ts`'s `formatMemoryHealthLine` — the health command is
+ * explicitly requested, so it always renders current counts even when
+ * everything is below threshold).
+ */
+export function formatSmellsHealthLine(counts) {
+    return (`Smells (recent tail-scan): stale-ctx emit_failed=${counts.staleCtxEmitFailed}` +
+        ` · opengrep respawn=${counts.opengrepRespawn}`);
+}
+/** `true` on turn 20, 40, 60, ... — never turn 0. Pure so the cadence is
+ *  unit-testable without driving a real turn loop (mirrors
+ *  `memory-sampler.ts`'s `shouldEmitMemorySample`). */
+export function shouldCheckSmellsThisTurn(turnIndex) {
+    return turnIndex > 0 && turnIndex % SMELLS_TURN_CHECK_INTERVAL === 0;
+}
+// Module-scope session state: which smells have already produced a turn-end
+// note THIS session. Bounded to once per session per smell by construction —
+// see `checkSmellsAndNoteOnce`.
+const notifiedThisSession = new Set();
+/**
+ * Given a fresh `counts` read, return zero or more turn-end note strings for
+ * smells crossing threshold for the FIRST time this session. A smell already
+ * notified this session never fires again, even if its count keeps growing —
+ * "once per session per smell" per #1123 item 3's design ask.
+ */
+export function checkSmellsAndNoteOnce(counts) {
+    const notes = [];
+    for (const key of SMELL_KEYS) {
+        if (notifiedThisSession.has(key))
+            continue;
+        if (counts[key] >= SMELLS_THRESHOLDS[key]) {
+            notifiedThisSession.add(key);
+            notes.push(`pi-lens smell: ${SMELL_LABELS[key]} x${counts[key]} (recent tail-scan) — run \`npm run logs:smells\` for detail`);
+        }
+    }
+    return notes;
+}
+/** Reset the "already notified this session" state — call at `session_start`
+ *  (a fresh session should be able to re-report) and from tests. */
+export function resetSmellsSessionState() {
+    notifiedThisSession.clear();
+}

package/node_modules/pi-lens/dist/clients/source-filter.js

@@ -19,8 +19,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectIgnoreMatcher } from "./file-utils.js";
-import { isDeclarationFile, isGeneratedOrArtifact, } from "./generated-artifacts.js";
+import { classifyGeneratedOrArtifactDetailed, isDeclarationFile, } from "./generated-artifacts.js";
 import { isCodeKindFile, KIND_EXTENSIONS } from "./file-kinds.js";
+import { logLatency } from "./latency-logger.js";
 import { normalizeEphemeralMapKey } from "./path-utils.js";
 import { isSlowFs, SLOW_FS_REDUCED_MAX_FILES } from "./slow-fs.js";
 import { shouldRecurseIntoDir, walkTreeRecursiveSync, walkTreeStackAsync, } from "./source-walker.js";
@@ -49,12 +50,50 @@ function probeExists(filePath, cache) {
  * Order matters: first entry has highest precedence.
  */
 export const SOURCE_PRECEDENCE = {
-    ".ts": [".js", ".mjs", ".cjs"],
+    ".ts": [".js", ".jsx", ".mjs", ".cjs"],
     ".tsx": [".jsx", ".js", ".mjs", ".cjs"],
+    ".mts": [".mjs", ".js", ".jsx", ".cjs"],
+    ".cts": [".cjs", ".js", ".jsx", ".mjs"],
     ".vue": [".js", ".mjs"],
     ".svelte": [".js", ".mjs"],
     ".coffee": [".js"],
 };
+/**
+ * Return source-twin candidates in the policy order for a compiled path.
+ * This is the pure counterpart to {@link findSourceSibling}: callers that
+ * already have a complete file identity set (the review graph and lens map)
+ * must not probe the filesystem or reimplement the extension matrix.
+ */
+export function sourceTwinCandidates(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const stem = filePath.slice(0, filePath.length - ext.length);
+    const sourceExts = ext === ".mjs"
+        ? [".mts", ".ts", ".tsx", ".cts"]
+        : ext === ".cjs"
+            ? [".cts", ".ts", ".tsx", ".mts"]
+            : ext === ".jsx"
+                // Deliberately retain the broad fallback: a .jsx next to a .ts
+                // is treated as a build artifact even without a .tsx sibling.
+                ? [".tsx", ".ts", ".mts", ".cts"]
+                : ext === ".js"
+                    ? [".ts", ".tsx", ".mts", ".cts"]
+                    : [];
+    return sourceExts.map((sourceExt) => `${stem}${sourceExt}`);
+}
+/**
+ * Resolve a compiled file to its canonical source identity within a known
+ * file set. The caller supplies normalized identities; this helper deliberately
+ * does not touch the filesystem, so complete source-set walks remain bounded
+ * and point-in-time consistent.
+ */
+export function canonicalSourceTwin(filePath, availableFiles, excludedFiles) {
+    for (const candidate of sourceTwinCandidates(filePath)) {
+        if (availableFiles.has(candidate) && !excludedFiles?.has(candidate)) {
+            return candidate;
+        }
+    }
+    return filePath;
+}
 /**
  * Every extension belonging to a supported file kind. KIND_EXTENSIONS is the
  * single language-extension authority; deriving here makes a newly registered
@@ -142,16 +181,78 @@ function createKeptFilesAccumulator(maxFiles, prioritizeCodeKinds) {
         list: () => [...codeFiles, ...otherFiles].slice(0, maxFiles),
     };
 }
-function shouldSkipGeneratedOrArtifact(filePath, options) {
+function createSourceWalkSkipCounters() {
+    return {
+        generatedOrArtifactSkips: 0,
+        buildArtifactSkips: 0,
+        generatedDirSkips: 0,
+        generatedNameOverrides: 0,
+        generatedNameOnlySkips: 0,
+    };
+}
+/**
+ * Log a one-line rollup for a walk's skip counters through the existing
+ * latency/scan logging channel (`logLatency`, ndjson `latency.log`) — mirrors
+ * how `getGraphSourceFiles` logs `review_graph_source_walk_entry_budget`.
+ * Silent (no log line) when both counters are zero, so a healthy walk with no
+ * name/artifact-probe skips produces no new log noise.
+ *
+ * Logged once per walk call, at the walk layer itself
+ * (`collectSourceFilesWithBudget`/`collectSourceFilesWithBudgetAsync`) rather
+ * than at each of its several consumers (review-graph builder, project-
+ * diagnostics scanner, word-index, …): every one of those consumers funnels
+ * through these two functions (directly or via the plain `collectSourceFiles`/
+ * `collectSourceFilesAsync` wrappers), so logging here is a single choke point
+ * that covers all of them — the smaller diff versus exporting the counters and
+ * wiring a log call into each consumer separately.
+ */
+function logSourceWalkSkipsIfAny(rootDir, counters) {
+    if (counters.generatedOrArtifactSkips === 0 &&
+        counters.buildArtifactSkips === 0 &&
+        counters.generatedDirSkips === 0 &&
+        counters.generatedNameOverrides === 0) {
+        return;
+    }
+    logLatency({
+        type: "phase",
+        phase: "source_walk_skip_summary",
+        filePath: rootDir,
+        durationMs: 0,
+        metadata: {
+            generatedOrArtifactSkips: counters.generatedOrArtifactSkips,
+            buildArtifactSkips: counters.buildArtifactSkips,
+            generatedDirSkips: counters.generatedDirSkips,
+            generatedNameOverrides: counters.generatedNameOverrides,
+            generatedNameOnlySkips: counters.generatedNameOnlySkips,
+        },
+    });
+}
+/**
+ * Full verdict+evidence form of {@link shouldSkipGeneratedOrArtifact} (#1107
+ * phase 2) — exposes `classifyGeneratedOrArtifactDetailed`'s `"override"`
+ * outcome (a WEAK name-only match the content-probe escape hatch rescued)
+ * AND, for a `"generated"` verdict, WHICH evidence tier decided it, so
+ * `classifyEntry` can count a genuine skip, a rescue, and the residual
+ * "unconfirmed name-only skip" bucket all distinctly. See
+ * `GeneratedArtifactEvidence`'s doc for why the tier split matters: a
+ * tool-facing notice keyed on the RAW skip count fires permanently on any
+ * repo with a lockfile, drowning the signal it exists to surface.
+ */
+function classifySkipGeneratedOrArtifact(filePath, options) {
     const includeDeclarations = options?.includeDeclarationFiles === true;
     if (options?.includeGenerated === true) {
-        return !includeDeclarations && isDeclarationFile(filePath);
+        return !includeDeclarations && isDeclarationFile(filePath)
+            ? { verdict: "generated", evidence: "strong" }
+            : { verdict: "clean" };
     }
-    return isGeneratedOrArtifact(filePath, {
+    return classifyGeneratedOrArtifactDetailed(filePath, {
         readContentHeader: options?.inspectGeneratedHeaders !== false,
         includeDeclarations: !includeDeclarations,
     });
 }
+function shouldSkipGeneratedOrArtifact(filePath, options) {
+    return classifySkipGeneratedOrArtifact(filePath, options).verdict === "generated";
+}
 /**
  * Extract the basename (filename without extension) from a path.
  */
@@ -170,17 +271,20 @@ function getDir(filePath) {
  * Returns the shadowing source file path if found, null otherwise.
  */
 export function findSourceSibling(filePath, probeCache) {
+    for (const candidate of sourceTwinCandidates(filePath)) {
+        if (probeExists(candidate, probeCache))
+            return candidate;
+    }
+    // Keep the legacy non-JS source policies (Vue/Svelte/CoffeeScript) on the
+    // same seam without making them part of the JS/TS twin matrix above.
     const ext = path.extname(filePath).toLowerCase();
     const dir = getDir(filePath);
     const base = getBasename(filePath);
-    // Find which precedence group this extension belongs to
     for (const [sourceExt, shadowedExts] of Object.entries(SOURCE_PRECEDENCE)) {
-        if (shadowedExts.includes(ext)) {
-            // This file could be shadowed by a source file with sourceExt
+        if (!sourceExtsForCompiledExt(sourceExt).length && shadowedExts.includes(ext)) {
             const siblingPath = path.join(dir, base + sourceExt);
-            if (probeExists(siblingPath, probeCache)) {
+            if (probeExists(siblingPath, probeCache))
                 return siblingPath;
-            }
         }
     }
     return null;
@@ -191,6 +295,11 @@ export function findSourceSibling(filePath, probeCache) {
  * @param probeCache - Optional per-walk memo (see {@link ArtifactProbeCache}).
  * Omit for the original, uncached behavior.
  */
+function sourceExtsForCompiledExt(sourceExt) {
+    return sourceExt === ".ts" || sourceExt === ".tsx" || sourceExt === ".mts" || sourceExt === ".cts"
+        ? [sourceExt]
+        : [];
+}
 export function isBuildArtifact(filePath, probeCache) {
     return findSourceSibling(filePath, probeCache) !== null;
 }
@@ -261,7 +370,7 @@ function resolveCollectionConfig(rootDir, options, config) {
  * produce identical results — the only difference between the two is that the
  * async variant yields to the event loop every N entries.
  */
-function classifyEntry(entry, fullPath, cfg, probeCache) {
+function classifyEntry(entry, fullPath, cfg, probeCache, skipCounters) {
     const { ignoreMatcher, extraExcludePatterns, extensions, options } = cfg;
     if (entry.isDirectory()) {
         const canRecurse = shouldRecurseIntoDir(entry, fullPath, {
@@ -269,7 +378,14 @@ function classifyEntry(entry, fullPath, cfg, probeCache) {
             extraExcludeDirs: extraExcludePatterns,
             skipGeneratedArtifactDirs: options?.includeGenerated !== true,
             followSymlinks: options?.followSymlinks === true,
-        });
+        }, 
+        // #1107 phase 2: counts one event per PRUNED DIRECTORY, not per file
+        // inside it — see `generatedDirSkips`'s doc on `SourceCollectionResult`.
+        skipCounters
+            ? () => {
+                skipCounters.generatedDirSkips += 1;
+            }
+            : undefined);
         if (!canRecurse)
             return {};
         return { recurseInto: fullPath };
@@ -281,10 +397,35 @@ function classifyEntry(entry, fullPath, cfg, probeCache) {
         if (!extensions.has(ext))
             return {};
         // Skip if this is a build artifact or generated/codegen output.
-        if (isBuildArtifact(fullPath, probeCache))
+        // #1107: counted separately (both are observability-only — neither
+        // changes what gets skipped) so an invisible coverage hole (a real
+        // `src/gen.ts` silently dropped by the name heuristic) is at least
+        // visible via `SourceCollectionResult` and the walk's rollup log line.
+        if (isBuildArtifact(fullPath, probeCache)) {
+            if (skipCounters)
+                skipCounters.buildArtifactSkips += 1;
             return {};
-        if (shouldSkipGeneratedOrArtifact(fullPath, options))
+        }
+        // #1107 phase 2: the content-probe escape hatch can rescue a WEAK
+        // name-only match ("override") instead of skipping it — see
+        // `classifyGeneratedOrArtifactDetailed`'s doc for the evidence
+        // order/tradeoff. `evidence` additionally distinguishes a STRONG/
+        // content-CONFIRMED skip (expected, not a coverage-hole signal) from
+        // the residual "name-only" skip (unconfirmed — the one bucket a
+        // tool-facing notice should actually key off).
+        const classification = classifySkipGeneratedOrArtifact(fullPath, options);
+        if (classification.verdict === "generated") {
+            if (skipCounters) {
+                skipCounters.generatedOrArtifactSkips += 1;
+                if (classification.evidence === "name-only") {
+                    skipCounters.generatedNameOnlySkips += 1;
+                }
+            }
             return {};
+        }
+        if (classification.verdict === "override" && skipCounters) {
+            skipCounters.generatedNameOverrides += 1;
+        }
         return { keepFile: fullPath };
     }
     return {};
@@ -320,6 +461,8 @@ export function collectSourceFilesWithBudget(dir, options) {
     // on return — never persisted across calls.
     const probeCache = createArtifactProbeCache();
     const budget = createEntryBudget(cfg.maxScanEntries);
+    // #1107: per-walk skip counters, discarded on return like the probe cache.
+    const skipCounters = createSourceWalkSkipCounters();
     // #761: immediate-descent recursion driver (result-array order preserved),
     // with both caps kept as this walker's own per-entry policy: the hard
     // `maxFiles` results cap (#250) is checked BEFORE charging the entry budget
@@ -330,14 +473,23 @@ export function collectSourceFilesWithBudget(dir, options) {
             return "stop"; // hard cap (#250)
         if (!chargeEntryBudget(budget))
             return "stop"; // entry budget (#760)
-        const { recurseInto, keepFile } = classifyEntry(entry, fullPath, cfg, probeCache);
+        const { recurseInto, keepFile } = classifyEntry(entry, fullPath, cfg, probeCache, skipCounters);
         if (recurseInto)
             return "recurse";
         if (keepFile)
             kept.push(keepFile);
         return "skip";
     });
-    return { files: kept.list(), entryBudgetExceeded: budget.exceeded };
+    logSourceWalkSkipsIfAny(rootDir, skipCounters);
+    return {
+        files: kept.list(),
+        entryBudgetExceeded: budget.exceeded,
+        generatedOrArtifactSkips: skipCounters.generatedOrArtifactSkips,
+        buildArtifactSkips: skipCounters.buildArtifactSkips,
+        generatedDirSkips: skipCounters.generatedDirSkips,
+        generatedNameOverrides: skipCounters.generatedNameOverrides,
+        generatedNameOnlySkips: skipCounters.generatedNameOnlySkips,
+    };
 }
 export function collectSourceFiles(dir, options) {
     return collectSourceFilesWithBudget(dir, options).files;
@@ -345,7 +497,7 @@ export function collectSourceFiles(dir, options) {
 /**
  * Async, chunked-yield twin of {@link collectSourceFiles}. Returns the exact
  * same file list (it shares `classifyEntry`), but yields to the event loop
- * every `yieldEvery` directory entries so a large tree never holds the loop in
+ * on a monotonic time budget so a large tree never holds the loop in
  * one synchronous burst.
  *
  * Why this exists: on a ~2k-file project the synchronous `collectSourceFiles`
@@ -372,15 +524,18 @@ export async function collectSourceFilesWithBudgetAsync(dir, options) {
     // caching across the whole call remains invalidation-free.
     const probeCache = createArtifactProbeCache();
     const budget = createEntryBudget(cfg.maxScanEntries);
+    // #1107: per-walk skip counters, discarded on return like the probe cache.
+    const skipCounters = createSourceWalkSkipCounters();
     // #761: shared depth-first stack driver (its reverse-push mirrors the sync
     // collector's left-to-right recursion). The async collector charges the
     // entry budget (#760) FIRST, then checks the `maxFiles` cap immediately
     // after keeping a file — subtly different from the sync collector's ordering
     // but preserved verbatim, so both stay byte-identical to their pre-#761 form.
     await walkTreeStackAsync(rootDir, (entry, fullPath) => {
+        options?.onEntryVisited?.();
         if (!chargeEntryBudget(budget))
             return "stop"; // entry budget (#760)
-        const { recurseInto, keepFile } = classifyEntry(entry, fullPath, cfg, probeCache);
+        const { recurseInto, keepFile } = classifyEntry(entry, fullPath, cfg, probeCache, skipCounters);
         if (recurseInto)
             return "recurse";
         if (keepFile) {
@@ -394,13 +549,22 @@ export async function collectSourceFilesWithBudgetAsync(dir, options) {
         // even on a cold scan where every kept file pays the 4 KB generated-
         // header read (measured on a 2k-file fixture). Larger values regress
         // past the ~50ms event-loop budget; see PERF-AUDIT.md.
-        yieldEvery: Math.max(1, options?.yieldEvery ?? 50),
+        budgetMs: Math.max(1, options?.budgetMs ?? 8),
         // #703: prime the tracked-files set once before the walk so a tracked
         // file matching a `.gitignore`/global pattern still surfaces. Fail-open
         // on no-git/spawn failure.
         beforeWalk: () => cfg.ignoreMatcher.ensureTrackedIndex(),
     });
-    return { files: kept.list(), entryBudgetExceeded: budget.exceeded };
+    logSourceWalkSkipsIfAny(rootDir, skipCounters);
+    return {
+        files: kept.list(),
+        entryBudgetExceeded: budget.exceeded,
+        generatedOrArtifactSkips: skipCounters.generatedOrArtifactSkips,
+        buildArtifactSkips: skipCounters.buildArtifactSkips,
+        generatedDirSkips: skipCounters.generatedDirSkips,
+        generatedNameOverrides: skipCounters.generatedNameOverrides,
+        generatedNameOnlySkips: skipCounters.generatedNameOnlySkips,
+    };
 }
 /**
  * Get statistics about source file filtering for debugging/monitoring.