pi-lens 4.3.0 → 4.4.0

package/dist/clients/lens-engine.js

@@ -1,358 +0,0 @@
-/**
- * LensEngine — the single internal-facing seam for pi-lens host adapters.
- *
- * The maintainability rule: host adapters (the MCP server today; index.ts can
- * adopt incrementally) talk ONLY to this module, never reaching into pi-lens
- * internals directly. So when an internal API is refactored, the break surfaces
- * HERE (one file, TypeScript-loud), not scattered across the adapter. New
- * mirrored capabilities (cascade, call-graph, …) get a method here and the
- * adapter just routes to it — coupling stays capped at this interface instead of
- * growing per tool.
- *
- * It re-exports the per-concern facades (analyze / review / session / ipc) and
- * adds thin wrappers over the remaining internal reach-ins (latency, project
- * scan, LSP status, diagnostic stats, LSP config).
- */
-import * as path from "node:path";
-import { minimatch } from "./deps/minimatch.js";
-import { getDiagnosticTracker } from "./diagnostic-tracker.js";
-import { getLatencyReports, } from "./dispatch/integration.js";
-import { getResourceFootprint as getResourceFootprintSnapshot, } from "./instance-registry.js";
-import { extensionsForLanguageToken } from "./language-registry.js";
-import { initLSPConfig } from "./lsp/config.js";
-import { getLSPService } from "./lsp/index.js";
-import { acquireWarmWordIndex } from "./mcp/analyze.js";
-import { normalizeMapKey } from "./path-utils.js";
-import { scanProjectDiagnostics } from "./project-diagnostics/scanner.js";
-import { loadProjectSnapshotWithoutWordIndex } from "./project-snapshot.js";
-import { resolveLensToolName } from "./tool-config.js";
-import { getTreeSitterRuntimeStatus, } from "./tree-sitter-shared.js";
-import { centralityFromReverseDeps, getWordIndexBuildStatus, searchWordIndex, triggerBackgroundWordIndexBuild, } from "./word-index.js";
-// --- Facades (re-exported so adapters import only this module) ---------------
-export { analyzeFile } from "./mcp/analyze.js";
-export { createMcpHost } from "./mcp/host-shim.js";
-export { createWarmIpcLineReader, createWarmIpcRequestQueue, ipcPathForCwd, readTurnEndStatus, WARM_TURN_END_SCHEMA_VERSION, } from "./mcp/ipc.js";
-export { analyzeFileFresh, canRebuildPiLens, resolveRebuildScript, runRebuild, summarizeScan, } from "./mcp/review.js";
-export { acknowledgeTurnEnd, runSessionStart, runTurnEnd, runTurnEndForIpc, } from "./mcp/session.js";
-export { moduleReport, readEnclosing, readSymbol, renderCompactModuleReport, } from "./module-report.js";
-export { projectReport, renderCompactProjectReport, } from "./project-report.js";
-// Effective-config introspection (#2427). A facade rather than a wrapper for
-// the same reason the others are: the computation reaches into the config
-// resolution, the LSP registry and the dispatch plan at once, and putting that
-// composition here would make this file the fourth place that knows how a
-// server is selected. Adapters route to it; nobody re-derives it.
-export { effectiveConfig, isEffectiveFileViewError, } from "./effective-config.js";
-// --- Query wrappers (own the remaining internal reach-ins) -------------------
-/** Recent dispatch latency reports (latency.log schema), newest first. */
-export function recentLatency(limit = 5, fileFilter) {
-    let reports = getLatencyReports();
-    if (fileFilter) {
-        const needle = fileFilter.replace(/\\/g, "/");
-        reports = reports.filter((report) => report.filePath.replace(/\\/g, "/").endsWith(needle));
-    }
-    return reports.slice(-limit).reverse();
-}
-/**
- * Cheap project-wide scan (tree-sitter + fact rules).
- *
- * `includeGenerated` (#1107 phase 2 review): scan WITHOUT the generated/
- * artifact NAME-heuristic filter — the actionable opt-out
- * `generatedSkipNotice` below points a user at. Default `false` (existing
- * filtering behavior unchanged).
- */
-export function projectScan(cwd, maxFiles, includeGenerated) {
-    return scanProjectDiagnostics({
-        cwd,
-        tier: "cheap",
-        maxFiles,
-        includeGenerated,
-    });
-}
-/**
- * #784: `scanTruncated` (#760) reaches this seam intact but, until now, no
- * caller rendered it — a capped scan read as a complete clean sweep to the
- * agent/user. One shared, unit-testable line adapters can append to their
- * rendered summary, matching the #777 warm-skip notify's override-hint style.
- * Returns `undefined` when the scan was not truncated (no line to append).
- */
-export function scanTruncationNotice(snapshot) {
-    if (!snapshot.scanTruncated)
-        return undefined;
-    if (snapshot.treeSitterStatus === "wasm_aborted_restart_required") {
-        return (`⚠ Scan stopped after ${snapshot.filesScanned} complete file(s): the ` +
-            "tree-sitter WASM runtime aborted. Results are partial and were not cached; " +
-            "restart the pi-lens extension/MCP server to restore structural analysis.");
-    }
-    return (`⚠ Scan truncated at ${snapshot.filesScanned} file(s) — results are partial; ` +
-        "raise maxProjectFiles in .pi-lens.json to scan fully.");
-}
-/**
- * #1107 phase 2: `generatedNameOnlySkips`/`generatedDirSkips` reach this seam
- * via `ProjectDiagnosticsSnapshot` but need explicit rendering, same pattern
- * as `scanTruncationNotice` above — otherwise a user has no way to learn the
- * generated-name heuristic silently excluded files/directories short of
- * reading `latency.log`'s `source_walk_skip_summary` line directly.
- *
- * #1107 phase 2 review round 2 (P1, empirically proven): this deliberately
- * keys off `generatedNameOnlySkips`, NOT the raw `generatedFileSkips` total.
- * `generatedFileSkips` counts every file the generated/artifact heuristic
- * skipped, including STRONG evidence (lockfiles, declaration files, minified/
- * bundle/chunk output — expected on nearly every real repo) and
- * content-CONFIRMED WEAK matches (the escape hatch checked and a genuine
- * generated-code header was present). Keying the notice off that total meant
- * a repo with nothing more unusual than a `package-lock.json` and an ambient
- * `.d.ts` showed "2 file(s) excluded" on literally every scan forever — the
- * signal drowned itself on day one. `generatedNameOnlySkips` is the narrower,
- * genuinely at-risk residual: a WEAK name match trusted with NO corroborating
- * evidence check at all (only reachable when a caller opts out of the header
- * probe — source-filter.ts's default project-walk path always enables it).
- * Post-escape-hatch, this should be rare-to-zero on the default path, which
- * is exactly what makes the notice meaningful again when it DOES fire.
- * `generatedDirSkips` stays in the trigger condition unchanged: directory-
- * level pruning has no escape hatch at all (the walk never enumerates a
- * pruned directory's contents to check them), so it is always a genuine
- * "real files may be hiding in here, unverified" signal, not a
- * false-positive-prone one — see `generatedDirSkips`'s doc on
- * `SourceCollectionResult`.
- *
- * Returns `undefined` when neither counter is set (nothing to append).
- */
-export function generatedSkipNotice(snapshot, host = "pi") {
-    const files = snapshot.generatedNameOnlySkips ?? 0;
-    const dirs = snapshot.generatedDirSkips ?? 0;
-    if (files === 0 && dirs === 0)
-        return undefined;
-    const parts = [];
-    if (files > 0)
-        parts.push(`${files} file(s)`);
-    if (dirs > 0)
-        parts.push(`${dirs} director${dirs === 1 ? "y" : "ies"}`);
-    // #2535 F1: name the tools THIS host can call. pi has no project-scan
-    // surface, so it names only its diagnostics tool; MCP names both. A
-    // known-but-unmapped host resolves to undefined and is left out, never
-    // printed as a name the host cannot resolve.
-    const targets = [
-        resolveLensToolName("project_scan", host),
-        resolveLensToolName("lens_diagnostics", host),
-    ].filter((tool) => tool !== undefined);
-    const scanRef = targets.length > 0 ? ` to ${targets.join(" / ")}` : "";
-    return (`ℹ ${parts.join(" and ")} excluded by generated-name heuristics with no ` +
-        "confirming evidence — a real hand-written file/directory whose name " +
-        "looks generated (e.g. `gen.ts`, `generated/`) can be excluded too; " +
-        `pass includeGenerated: true${scanRef} to scan without this filter if you suspect a false skip.`);
-}
-/** Process-wide tree-sitter health for host status surfaces. */
-export function treeSitterRuntimeStatus() {
-    return getTreeSitterRuntimeStatus();
-}
-/** Alive LSP client count + per-server status. */
-export function lspStatus() {
-    const lsp = getLSPService();
-    return {
-        aliveClients: lsp.getAliveClientCount(),
-        servers: lsp.getStatus(),
-        brokenServers: lsp.getBrokenStatus(),
-    };
-}
-export function renderLspBrokenStatusLines(brokenServers) {
-    return brokenServers.map((server) => server.permanentlyBroken
-        ? `  ✗ ${server.serverId} — disabled after ${server.failures} failures (${server.root})`
-        : `  ✗ ${server.serverId} — cooling down after ${server.failures} failure(s) until ${new Date(server.cooldownUntil).toISOString()} (${server.root})`);
-}
-/** Session diagnostic counters (shown / auto-fixed / unresolved …). */
-export function diagnosticStats() {
-    return getDiagnosticTracker().getStats();
-}
-/** Initialise LSP config for a workspace (idempotent at the LSP layer). */
-export function ensureLspConfig(cwd) {
-    return initLSPConfig(cwd);
-}
-/**
- * #620: total CPU/RAM footprint attributable to pi-lens across every process
- * it owns — every registered instance's host, plus that instance's live LSP
- * children. Reads the machine-global `~/.pi-lens/instances.json` registry, so
- * this answers across ALL concurrent pi-lens sessions/worktrees on the box,
- * not just this one. Best-effort: reflects whatever heartbeats have landed so
- * far — a stale-heartbeat instance simply reports its last-sampled numbers.
- */
-export function resourceFootprint() {
-    return getResourceFootprintSnapshot();
-}
-/**
- * symbol_search's `lang` filter.
- *
- * The extension table this used to consult was a NINTH hand-written language ->
- * extensions map, kept here because `clients/` never reaches into `tools/`
- * (AGENTS.md's MCP-mirror layering note) — and it had drifted from every other
- * one (#2424 review, S2): `css` claimed `.scss`/`.less`, `json` claimed
- * `.jsonc`, `php` omitted its four alias extensions, `ruby` omitted `.ru`, and
- * `solidity` was not a language the registry (or any grammar, or the ast-grep
- * napi matrix) knows at all.
- *
- * The layering constraint was never a reason to duplicate the DATA, only a
- * reason not to import the tool's token list. `extensionsForLanguageToken`
- * resolves the token against the canonical registry instead.
- *
- * Exported so `tests/clients/language-registry-drift.test.ts` guards the SEAM
- * and not just the projection behind it: a future local table reintroduced
- * here would satisfy a registry-only assertion but fail this one.
- */
-export function symbolSearchFileMatchesLang(file, lang) {
-    const exts = extensionsForLanguageToken(lang);
-    if (exts.length === 0)
-        return false;
-    return exts.includes(path.extname(file).toLowerCase());
-}
-/** Same glob semantics as ast_grep_search's `paths`: a bare directory/file
- * entry scopes its whole subtree (via a `/**` suffix match), a full glob
- * pattern is matched as-is. Matched relative to `cwd` so absolute index paths
- * and repo-relative globs line up regardless of platform path separators. */
-function fileMatchesPathGlobs(file, cwd, globs) {
-    const rel = path.relative(cwd, file).split(path.sep).join("/");
-    const options = { dot: true, nocase: process.platform === "win32" };
-    return globs.some((raw) => {
-        const pattern = raw.split("\\").join("/");
-        return (minimatch(rel, pattern, options) ||
-            minimatch(rel, `${pattern}/**`, options));
-    });
-}
-function buildSymbolSearchFileFilter(cwd, options) {
-    const paths = options.paths?.filter((p) => p.trim().length > 0);
-    const lang = options.lang?.trim();
-    if (!paths?.length && !lang)
-        return undefined;
-    return (file) => {
-        if (paths?.length && !fileMatchesPathGlobs(file, cwd, paths))
-            return false;
-        if (lang && !symbolSearchFileMatchesLang(file, lang))
-            return false;
-        return true;
-    };
-}
-/**
- * Attaches read-only graph signals to already-ranked hits (#771) — mutates
- * each hit in place. `fanIn` reuses the SAME `centrality` map `symbolSearch`
- * already computed for its ranking boost (zero extra cost); `complexity` is
- * the highest per-symbol `cyclomaticComplexity` the (warm) review graph
- * recorded for that file. Caller only invokes this when `graph` is defined —
- * never builds one itself.
- */
-function annotateSymbolSearchHitsWithGraph(hits, centrality, graph) {
-    for (const hit of hits) {
-        const normalized = normalizeMapKey(path.resolve(hit.file));
-        const fanIn = centrality.get(hit.file) ?? 0;
-        let complexity;
-        for (const symbolId of graph.symbolNodesByFile.get(normalized) ?? []) {
-            const raw = graph.nodes.get(symbolId)?.metadata?.cyclomaticComplexity;
-            if (typeof raw === "number" &&
-                (complexity === undefined || raw > complexity)) {
-                complexity = raw;
-            }
-        }
-        hit.annotations = {
-            fanIn,
-            ...(complexity !== undefined ? { complexity } : {}),
-        };
-    }
-}
-function toSymbolSearchHit(result) {
-    const line = result.lines[0] ?? 1;
-    return {
-        file: result.file,
-        score: result.score,
-        hits: result.hits,
-        startLine: line,
-        endLine: line,
-    };
-}
-/**
- * Ranked identifier search over the persisted word index (#162). Mostly
- * stateless: loads the index from the project snapshot (built by the session
- * scan, in either the pi extension or the MCP session), so it works without a
- * warm runtime. Returns `available: false` when no index exists yet — and
- * kicks off a single bounded background build for this workspace (deduped per
- * cwd, never blocking this call) so a retry shortly after succeeds (#348
- * decision 3).
- *
- * #536 rider: prefers the warm in-memory index (`acquireWarmWordIndex`,
- * clients/mcp/analyze.ts) over a fresh disk read when one exists for this
- * cwd — a warm `pilens_analyze` call updates that live copy synchronously but
- * persists it to disk on a debounce (default 1500ms), so without this a query
- * immediately following an analyze in the SAME process would read stale
- * on-disk state until the debounce flushes. Falls back to the stateless disk
- * read exactly as before when no warm copy is cached (nothing has called
- * pilens_analyze yet this process, or #348 phase 2's forward-index isn't
- * available) — this function's public contract (available/hint/results shape)
- * is unchanged either way.
- *
- * `options.paths`/`options.lang` (#771) scope the word index BEFORE ranking
- * (`searchWordIndex`'s `fileFilter`), so a surviving file's score is identical
- * to an unfiltered run; omitting both reproduces prior output byte-for-byte.
- *
- * Every hit is additionally annotated (#771) with the graph signals already
- * available when the cached review graph happens to be warm —
- * `getCachedReviewGraph` (`clients/review-graph/builder.ts`) is a READ-ONLY
- * accessor: an in-memory miss falls through to a persisted-disk read, and
- * NOTHING here ever triggers a fresh build. A cold cache (no in-memory graph,
- * no persisted snapshot) simply omits `annotations` — this function's latency
- * profile is unchanged either way. The module is dynamic-imported (mirroring
- * module-report.ts's own lazy load of it) so an unused review graph costs
- * nothing on this hot path.
- */
-export async function symbolSearch(query, cwd, limit = 20, options = {}) {
-    const warmLease = acquireWarmWordIndex(cwd);
-    const snapshot = loadProjectSnapshotWithoutWordIndex(cwd);
-    const index = warmLease.index;
-    if (!index) {
-        warmLease.release();
-        const priorStatus = getWordIndexBuildStatus(cwd);
-        const status = priorStatus?.state === "refused"
-            ? priorStatus
-            : triggerBackgroundWordIndexBuild(cwd);
-        const unavailableReason = priorStatus?.state === "failed"
-            ? "last-build-failed"
-            : status.state === "refused"
-                ? "refused"
-                : "building";
-        const hint = unavailableReason === "refused"
-            ? `Word index build was refused for safety: ${status.state === "refused" ? status.reason : "unsafe workspace root"}. Run symbol_search from inside a project directory.`
-            : unavailableReason === "last-build-failed"
-                ? `The last word index build failed: ${priorStatus?.state === "failed" ? priorStatus.reason : "unknown error"}. A retry is now running in the background.`
-                : "Word index is building in the background for this workspace — retry this query shortly.";
-        return {
-            available: false,
-            query,
-            results: [],
-            unavailableReason,
-            hint,
-        };
-    }
-    // Boost well-connected files using the snapshot's reverse-dependency
-    // (importedBy) counts; snapshot keys are normalized, index keys are raw.
-    let centrality;
-    let results;
-    try {
-        centrality = centralityFromReverseDeps(index, snapshot?.reverseDeps, (file) => normalizeMapKey(path.resolve(file)));
-        const fileFilter = buildSymbolSearchFileFilter(cwd, options);
-        results = searchWordIndex(index, query, { limit, centrality, fileFilter });
-    }
-    finally {
-        warmLease.release();
-    }
-    const hits = results.map(toSymbolSearchHit);
-    const { getCachedReviewGraph } = await import("./review-graph/builder.js");
-    const graph = getCachedReviewGraph(cwd);
-    if (graph)
-        annotateSymbolSearchHitsWithGraph(hits, centrality, graph);
-    return {
-        available: true,
-        query,
-        results: hits,
-        coverage: { files: index.docCount, truncated: index.truncated === true },
-        snapshotGeneratedAt: snapshot?.generatedAt,
-    };
-}
-// symbolImpact was removed (#304 follow-up): the transitive blast radius is now
-// served by module_report's `blastRadius` option (clients/module-report.ts), which
-// calls computeTransitiveImpact (review-graph/query.ts) directly over the cached
-// graph. No engine wrapper is needed.

package/dist/clients/lens-events.js

@@ -1,125 +0,0 @@
-import { logExtension } from "./extension-log.js";
-import { logBusEvent } from "./bus-events-logger.js";
-import { normalizeFilePath } from "./path-utils.js";
-import { createLiveBusEmitter, recordStaleBusFailure, resolveLiveBusEmitter, } from "./live-bus-emitter.js";
-const LENS_EVENT_VERSION = 1;
-export const LENS_EVENT_NAMES = {
-    analysisComplete: "pi-lens/analysis-complete",
-    findings: "pi-lens/findings",
-    turnFindings: "pi-lens/turn-findings",
-};
-const liveEmitter = createLiveBusEmitter();
-/** Keep deferred deliveries on the live extension activation. */
-export function initLensEventsGetter(getter) {
-    liveEmitter.wireGetter(getter);
-}
-function truncateText(value, maxChars) {
-    if (value === undefined)
-        return undefined;
-    if (value.length <= maxChars)
-        return value;
-    return `${value.slice(0, maxChars)}…`;
-}
-function normalizeDiagnostic(diagnostic) {
-    return {
-        ...diagnostic,
-        message: truncateText(diagnostic.message, 1_000) ?? "",
-        matchedText: truncateText(diagnostic.matchedText, 500),
-        fixSuggestion: truncateText(diagnostic.fixSuggestion, 500),
-    };
-}
-function normalizeDiagnostics(diagnostics) {
-    return diagnostics.map(normalizeDiagnostic);
-}
-// Dropped-emit observability (#1128 review): drops are legitimate (no bus
-// during startup/replacement windows) but must not be invisible. One line per
-// process — enough to notice a permanently-missing bus without spamming.
-let _droppedEmitLogged = false;
-// Emit-failure gating (H1, #1415 review): occurrence-scoped, matching every
-// other producer's `hasLoggedFailure` guard (see clients/bus-publish.ts) and
-// AGENTS.md's "one bus-stale degradation per occurrence" invariant. A success
-// re-arms it, so a later failure records a fresh degradation rather than
-// being silently absorbed by an earlier one.
-let hasLoggedFailure = false;
-/** Test-only: reset module state between test files. */
-export function _resetForTests() {
-    liveEmitter.reset();
-    _droppedEmitLogged = false;
-    hasLoggedFailure = false;
-}
-function emitLensEvent(eventName, payload) {
-    setImmediate(() => {
-        const rawCwd = payload.cwd ?? process.cwd();
-        // M1: normalizeFilePath is a sync realpathSync.native on Windows, and on
-        // POSIX too since #3098 — build
-        // the resolveLiveBusEmitter log entry lazily so the ready-path (the
-        // common case) never pays it. Only the stale-session branch needs it.
-        const resolution = resolveLiveBusEmitter(liveEmitter, () => ({
-            event: eventName,
-            cwd: normalizeFilePath(rawCwd),
-        }));
-        if (resolution.outcome === "stale-session")
-            return;
-        if (resolution.outcome === "unwired") {
-            if (!_droppedEmitLogged) {
-                _droppedEmitLogged = true;
-                logExtension({
-                    subsystem: "lens-events",
-                    level: "warn",
-                    message: `lens event dropped (no live bus): ${eventName} — further drops logged once per process`,
-                    metadata: { eventName },
-                });
-            }
-            return;
-        }
-        const cwd = normalizeFilePath(rawCwd);
-        try {
-            resolution.emit(eventName, payload);
-            hasLoggedFailure = false;
-            logBusEvent({ event: eventName, outcome: "emitted", cwd });
-        }
-        catch (err) {
-            logBusEvent({
-                event: eventName,
-                outcome: "emit_failed",
-                cwd,
-                error: String(err),
-                ctxSource: resolution.ctxSource,
-            });
-            if (!hasLoggedFailure) {
-                hasLoggedFailure = true;
-                recordStaleBusFailure(eventName, err);
-            }
-            // Inter-extension events are observational. A listener must never break
-            // the pi-lens hook path or delay agent progress.
-        }
-    });
-}
-export function emitLensAnalysisComplete(payload) {
-    const normalized = {
-        version: LENS_EVENT_VERSION,
-        source: "pi-lens",
-        timestamp: new Date().toISOString(),
-        ...payload,
-        diagnostics: normalizeDiagnostics(payload.diagnostics),
-        blockers: normalizeDiagnostics(payload.blockers),
-        warnings: normalizeDiagnostics(payload.warnings),
-        fixed: normalizeDiagnostics(payload.fixed),
-    };
-    emitLensEvent(LENS_EVENT_NAMES.analysisComplete, normalized);
-    if (normalized.diagnostics.length > 0 ||
-        normalized.blockers.length > 0 ||
-        normalized.warnings.length > 0 ||
-        normalized.fixed.length > 0) {
-        emitLensEvent(LENS_EVENT_NAMES.findings, normalized);
-    }
-}
-export function emitLensTurnFindings(payload) {
-    emitLensEvent(LENS_EVENT_NAMES.turnFindings, {
-        version: LENS_EVENT_VERSION,
-        source: "pi-lens",
-        timestamp: new Date().toISOString(),
-        ...payload,
-        content: truncateText(payload.content, 8_000) ?? "",
-    });
-}