pi-lens 4.2.1 → 4.4.0

package/dist/clients/code-quality-warnings.js

@@ -1,286 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
-import { displayProjectDataPath, getProjectDataDir } from "./file-utils.js";
-import { normalizeMessage, stableFindingId } from "./finding-identity.js";
-import { normalizeMapKey } from "./path-utils.js";
-import { resolveLensToolName } from "./tool-config.js";
-/**
- * Report-budget precedence (#1777). A hint is an opinion; a warning is a
- * finding. When the report is capped, warnings must be spent first, or an
- * alphabetically-early file's hints can push every real warning out of the
- * agent's view — the exact "hints dominate the stream" failure the hint tier
- * exists to prevent.
- */
-const TIER_BUDGET_ORDER = [
-    "warning",
-    "info",
-    "hint",
-];
-/** #1816: was a local `relativeFile|tool|rule|code|normalizedMessage|line`
- * hash (raw, non-canonicalized `relativeFile`, 10-char hash), independently
- * hand-rolled from `actionable-warnings.ts`'s twin and
- * `diagnostic-dispositions.ts`'s canonicalizing original. Now the shared
- * `finding-identity.js` builder (canonicalizes `cwd`/`filePath` through
- * `normalizeMapKey`, hashes to 12 chars). No back-compat migration needed
- * here: `cq:` ids are never a keyed lookup — `buildCodeQualityWarningsReport`
- * regenerates the whole report fresh every turn, callers only ever cache and
- * replay the report wholesale (`tools/lens-diagnostics.ts` reads it via
- * `cacheManager.readCache<CodeQualityWarningsReport>`, never by `id`), and
- * `appendCodeQualityWarningsHistory` just append-only-logs the id for
- * observability, never look it back up. Contrast `actionable-warnings.ts`,
- * whose `actionable-warning-state.json` DOES key a persisted suppression
- * store on `aw:` — that one migrates. */
-function createCodeQualityWarningId(args) {
-    return stableFindingId("cq:", {
-        cwd: args.cwd,
-        filePath: args.filePath,
-        parts: [
-            args.tool,
-            args.rule,
-            args.code,
-            normalizeMessage(args.message),
-            args.line,
-        ],
-    });
-}
-function categorize(diagnostic) {
-    const haystack = `${diagnostic.tool} ${diagnostic.rule ?? ""} ${diagnostic.code ?? ""} ${diagnostic.message}`.toLowerCase();
-    if (haystack.includes("type") || haystack.includes("any"))
-        return "type-safety";
-    if (haystack.includes("complex") ||
-        haystack.includes("fan-out") ||
-        haystack.includes("fanout"))
-        return "maintainability";
-    if (haystack.includes("duplicate") || haystack.includes("similar"))
-        return "duplication";
-    if (haystack.includes("style") || haystack.includes("format"))
-        return "style";
-    return "other";
-}
-function lineInModifiedRanges(line, ranges) {
-    if (line === undefined)
-        return true;
-    if (ranges.length === 0)
-        return true;
-    return ranges.some((range) => line >= range.start - 2 && line <= range.end + 2);
-}
-export function recordFromCodeQualityDiagnostic(diagnostic, cwd) {
-    if (diagnostic.semantic !== "warning" && diagnostic.semantic !== "none")
-        return undefined;
-    if (diagnostic.severity === "error")
-        return undefined;
-    if (diagnostic.fixable ||
-        diagnostic.fixSuggestion ||
-        diagnostic.autoFixAvailable)
-        return undefined;
-    const filePath = path.resolve(cwd, diagnostic.filePath);
-    return {
-        id: createCodeQualityWarningId({
-            cwd,
-            filePath,
-            tool: diagnostic.tool,
-            rule: diagnostic.rule,
-            code: diagnostic.code,
-            message: diagnostic.message,
-            line: diagnostic.line,
-        }),
-        filePath,
-        displayPath: toRunnerDisplayPath(cwd, filePath),
-        line: diagnostic.line,
-        column: diagnostic.column,
-        severity: diagnostic.severity === "hint"
-            ? "hint"
-            : diagnostic.severity === "info"
-                ? "info"
-                : "warning",
-        tool: diagnostic.tool,
-        rule: diagnostic.rule,
-        code: diagnostic.code,
-        message: diagnostic.message,
-        category: categorize(diagnostic),
-        origin: "dispatch",
-    };
-}
-export function buildCodeQualityWarningsReport(args) {
-    const cwd = path.resolve(args.cwd);
-    const maxWarnings = Math.max(1, args.maxWarnings ?? 50);
-    const byId = new Map();
-    for (const warning of args.warnings) {
-        const ranges = args.modifiedRangesByFile.get(normalizeMapKey(warning.filePath)) ?? [];
-        if (!lineInModifiedRanges(warning.line, ranges))
-            continue;
-        byId.set(warning.id, warning);
-    }
-    const byDisplayOrder = (a, b) => a.displayPath.localeCompare(b.displayPath) ||
-        (a.line ?? 0) - (b.line ?? 0) ||
-        a.message.localeCompare(b.message);
-    // Spend the budget tier by tier (see TIER_BUDGET_ORDER), then restore
-    // display order so the report still reads file by file, line by line.
-    const candidates = [...byId.values()].sort(byDisplayOrder);
-    const merged = [];
-    for (const tier of TIER_BUDGET_ORDER) {
-        for (const warning of candidates) {
-            if (merged.length >= maxWarnings)
-                break;
-            if (warning.severity === tier)
-                merged.push(warning);
-        }
-    }
-    merged.sort(byDisplayOrder);
-    const byFile = new Map();
-    for (const warning of merged) {
-        const arr = byFile.get(warning.filePath) ?? [];
-        arr.push(warning);
-        byFile.set(warning.filePath, arr);
-    }
-    const files = [...byFile.entries()].map(([filePath, warnings]) => ({
-        filePath,
-        displayPath: toRunnerDisplayPath(cwd, filePath),
-        fileSeq: args.fileSeqByPath?.get(normalizeMapKey(filePath)),
-        warnings,
-    }));
-    const ruleCounts = new Map();
-    for (const warning of merged) {
-        const rule = warning.rule ?? warning.tool;
-        ruleCounts.set(rule, (ruleCounts.get(rule) ?? 0) + 1);
-    }
-    const topRules = [...ruleCounts.entries()]
-        .map(([rule, count]) => ({ rule, count }))
-        .sort((a, b) => b.count - a.count || a.rule.localeCompare(b.rule))
-        .slice(0, 8);
-    return {
-        generatedAt: new Date().toISOString(),
-        scope: "turn_delta",
-        sessionId: args.sessionId,
-        turnIndex: args.turnIndex,
-        projectSeqStart: args.projectSeqStart,
-        projectSeqEnd: args.projectSeqEnd,
-        deltaOnly: true,
-        files,
-        summary: {
-            warnings: merged.length,
-            files: files.length,
-            byTier: {
-                warning: merged.filter((w) => w.severity === "warning").length,
-                info: merged.filter((w) => w.severity === "info").length,
-                hint: merged.filter((w) => w.severity === "hint").length,
-            },
-            topRules,
-        },
-    };
-}
-/**
- * #557 audit (same race class as #555's LSP client fix and #560's
- * `widget-state.ts` `recordDiagnostics` fix): pi-lens deliberately allows
- * concurrent pipeline runs for the SAME file across DIFFERENT same-turn
- * edits (dedupe key is `filePath + contentHash`, not just `filePath` — see
- * `clients/runtime-tool-result.ts`), so a per-key cache fed directly from
- * those concurrent pipeline runs needs an ordering guard (`WriteOrderingGuard`
- * from `clients/write-ordering-guard.ts`) or an older edit's slower pipeline
- * can silently overwrite a newer edit's fresher write.
- *
- * This call site is NOT exposed to that race. Unlike `widget-state.ts`'s
- * `recordDiagnostics` (called directly from `clients/pipeline.ts`, once per
- * pipeline run — i.e. potentially several times per turn, out of completion
- * order), `writeCodeQualityWarningsReport` has exactly one caller:
- * `handleTurnEnd` in `clients/runtime-turn.ts`, which per-edit pipeline runs
- * never call directly — they only feed `runtime.recordCodeQualityWarnings`
- * (an accumulating, order-independent Map). `handleTurnEnd` itself reads that
- * accumulator once via `runtime.peekCodeQualityWarnings()` and writes the
- * aggregate report exactly once per turn-end invocation — the same single
- * sequential turn-end-only shape already confirmed safe for
- * `writeActionableWarningsReport` in `clients/actionable-warnings.ts`, right
- * next to this call site in `handleTurnEnd`. No second writer, so no
- * ordering token to guard against — see
- * `tests/clients/code-quality-warnings.test.ts`'s
- * "single sequential caller" test, which pins this invariant so a future
- * change that adds a second call site has a better chance of being caught.
- */
-export function writeCodeQualityWarningsReport(cacheManager, cwd, report) {
-    cacheManager.writeCache("code-quality-warnings", report, cwd);
-}
-export function getCodeQualityWarningsHistoryPath(cwd) {
-    return path.join(getProjectDataDir(cwd), "code-quality-warnings.jsonl");
-}
-export function appendCodeQualityWarningsHistory(cwd, report) {
-    const warnings = report.files.flatMap((file) => file.warnings.map((warning) => ({
-        timestamp: report.generatedAt,
-        sessionId: report.sessionId,
-        turnIndex: report.turnIndex,
-        projectSeq: report.projectSeqEnd,
-        filePath: warning.filePath,
-        displayPath: warning.displayPath,
-        fileSeq: file.fileSeq,
-        line: warning.line,
-        column: warning.column,
-        severity: warning.severity,
-        tool: warning.tool,
-        rule: warning.rule,
-        code: warning.code,
-        message: warning.message,
-        category: warning.category,
-        warningId: warning.id,
-    })));
-    if (warnings.length === 0)
-        return;
-    const historyPath = getCodeQualityWarningsHistoryPath(cwd);
-    try {
-        fs.mkdirSync(path.dirname(historyPath), { recursive: true });
-        fs.appendFileSync(historyPath, `${warnings.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf8");
-    }
-    catch {
-        // Non-fatal — history write failure should never surface to the agent.
-    }
-}
-/**
- * The turn-end advisory for this report.
- *
- * `cwd` is REQUIRED for the same reason as
- * {@link formatActionableWarningsAdvisory} (#2521): this advisory carried the
- * identical hardcoded-legacy-path defect, one cache key over.
- */
-export function formatCodeQualityWarningsAdvisory(report, cwd, host = "pi") {
-    if (report.summary.warnings === 0)
-        return undefined;
-    const topRules = report.summary.topRules
-        .slice(0, 3)
-        .map((entry) => `${entry.rule}×${entry.count}`)
-        .join(", ");
-    // #1777: name the tiers, in the same descending-loudness order the on-demand
-    // ast-grep surface uses (`formatDiagnostics`, clients/ast-grep-client.ts).
-    // A tier with no findings is omitted rather than printed as zero.
-    const byTier = report.summary.byTier ?? { warning: 0, info: 0, hint: 0 };
-    // The line is worth its space only when a quiet tier is present; an
-    // all-warning turn already says everything in the count above.
-    const tiers = byTier.hint || byTier.info
-        ? [
-            byTier.warning ? `${byTier.warning} warning` : undefined,
-            byTier.info ? `${byTier.info} info` : undefined,
-            byTier.hint ? `${byTier.hint} hint` : undefined,
-        ]
-            .filter(Boolean)
-            .join(", ")
-        : "";
-    // #2535 F3: a known tool with no mapping on this host resolves to
-    // undefined — omit the instruction rather than naming a dead tool.
-    const diagnosticsTool = resolveLensToolName("lens_diagnostics", host);
-    return [
-        `Code-quality warnings introduced/touched this turn: ${report.summary.warnings} across ${report.summary.files} file(s).`,
-        tiers
-            ? `By tier: ${tiers}. Hint and info are style opinions, not defects.`
-            : undefined,
-        topRules ? `Top rules: ${topRules}` : undefined,
-        // #2521: tool route first (`mode=delta` covers the code-quality cache
-        // as well as the actionable one), resolved path second.
-        // #2535 F3: omit when unmapped on this host, never name a dead tool
-        // (pinned available on both hosts; defensive only).
-        diagnosticsTool
-            ? `Use ${diagnosticsTool} with mode=delta to inspect these warnings.`
-            : undefined,
-        "No action required unless you are already refactoring these areas.",
-        `Raw report (only if you need the JSON): ${displayProjectDataPath(cwd, "cache", "code-quality-warnings.json")}`,
-    ]
-        .filter(Boolean)
-        .join("\n");
-}

package/dist/clients/codebase-model.js

@@ -1,173 +0,0 @@
-/**
- * Codebase mental model — issue #155.
- *
- * Builds a compact structural summary of the codebase from the call graph:
- * top-N symbols by in-degree centrality, each with signature, calls, and
- * calledBy lists. Persisted to cache; never injected into agent context
- * until validated across several real sessions.
- *
- * This is intentionally internal-only. The one agent-facing surface is a
- * single dbg log line at session-start so quality can be assessed via
- * ~/.pi-lens/sessionstart.log before any agent exposure.
- */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { getProjectDataDir } from "./file-utils.js";
-import { writeFileAtomic } from "./atomic-write.js";
-import { parseSymbolKey } from "./call-graph.js";
-import { detectFileRole } from "./file-role.js";
-import { isExternalOrVendorFile } from "./path-utils.js";
-import { isBuildArtifact } from "./source-filter.js";
-// ── Constants ─────────────────────────────────────────────────────────────────
-export const DEFAULT_CODEBASE_MODEL_TOKEN_BUDGET = 1500;
-const MAX_CALLS_PER_SYMBOL = 10;
-const MIN_IN_DEGREE = 0.5; // skip symbols with low centrality (avoids noise)
-/** Persisted model schema version. Bump when the persisted shape changes. */
-export const CODEBASE_MODEL_VERSION = 1;
-// ── Builder ───────────────────────────────────────────────────────────────────
-function inferKind(symbolKey) {
-    const parsed = parseSymbolKey(symbolKey);
-    if (parsed.kind === "class")
-        return "class";
-    if (parsed.kind === "method" || parsed.symbolName?.includes("."))
-        return "method";
-    return /^[A-Z]/.test(parsed.symbolName ?? "") ? "class" : "function";
-}
-function estimateTokens(entry) {
-    const text = [
-        entry.name,
-        entry.file,
-        entry.calls.join(","),
-        entry.calledBy.join(","),
-    ].join(" ");
-    return Math.ceil(text.length / 4) + 5; // +5 for structural overhead
-}
-/**
- * Build a codebase mental model from a function-level call graph.
- *
- * Selection: rank all symbols by weighted in-degree, then fill a token budget
- * from the top. Symbols below MIN_IN_DEGREE are skipped to avoid noise.
- *
- * @param graph   The session's FunctionCallGraph (must have inDegree populated).
- * @param cwd     Project root — used to compute relative file paths.
- * @param budget  Maximum total token budget (default 1500).
- */
-export function buildCodebaseModel(graph, cwd, budget = DEFAULT_CODEBASE_MODEL_TOKEN_BUDGET, identity) {
-    // Standalone callers may build an unpersisted projection without the
-    // review-graph coordinator. Persisted/session models pass the canonical
-    // review-graph identity explicitly; this fallback is only a local call-graph
-    // identity for builder-only use.
-    const modelIdentity = identity ?? {
-        reviewGraphVersion: graph.builtAt || "call-graph-unknown",
-        reviewGraphSignature: graph.builtAt || "call-graph-unknown",
-    };
-    // Sort all callee keys by in-degree descending
-    const ranked = [...graph.inDegree.entries()]
-        .filter(([, score]) => score >= MIN_IN_DEGREE)
-        .sort(([, a], [, b]) => b - a);
-    const entries = [];
-    let totalTokens = 0;
-    const seenNames = new Set();
-    for (const [calleeKey, inDegree] of ranked) {
-        if (totalTokens >= budget)
-            break;
-        const parsedCallee = parseSymbolKey(calleeKey);
-        const name = parsedCallee.symbolName ?? calleeKey;
-        const filePath = parsedCallee.filePath;
-        // Keep this projection aligned with the shared file-role policy. The
-        // call graph is derived from the canonical review graph, so the model
-        // carries that graph's identity rather than inventing a second freshness
-        // policy.
-        const fileRole = detectFileRole(filePath);
-        if (fileRole === "test" ||
-            fileRole === "generated" ||
-            isExternalOrVendorFile(filePath, cwd) ||
-            isBuildArtifact(filePath)) {
-            continue;
-        }
-        // Deduplicate by name when the same function appears in multiple files
-        if (seenNames.has(name))
-            continue;
-        seenNames.add(name);
-        const calls = [...(graph.callees.get(calleeKey) ?? new Set())]
-            .map((k) => parseSymbolKey(k).symbolName ?? k)
-            .filter(Boolean)
-            .slice(0, MAX_CALLS_PER_SYMBOL);
-        const calledBy = [...(graph.callers.get(calleeKey) ?? new Set())]
-            .map((k) => parseSymbolKey(k).symbolName ?? k)
-            .filter((n) => !n.startsWith("file:"))
-            .slice(0, MAX_CALLS_PER_SYMBOL);
-        const file = filePath
-            ? path.relative(cwd, filePath).replace(/\\/g, "/")
-            : "unknown";
-        const draft = {
-            file,
-            name,
-            kind: inferKind(calleeKey),
-            calls,
-            calledBy,
-            inDegree,
-        };
-        const tokens = estimateTokens(draft);
-        if (totalTokens + tokens > budget)
-            continue;
-        entries.push({ ...draft, tokens });
-        totalTokens += tokens;
-    }
-    const allFiles = new Set([...graph.callers.keys(), ...graph.callees.keys()]
-        .map((k) => parseSymbolKey(k).filePath)
-        .filter(Boolean));
-    return {
-        version: CODEBASE_MODEL_VERSION,
-        reviewGraphVersion: modelIdentity.reviewGraphVersion,
-        reviewGraphSignature: modelIdentity.reviewGraphSignature,
-        generatedAt: new Date().toISOString(),
-        totalSymbols: graph.inDegree.size,
-        totalFiles: allFiles.size,
-        entries,
-        totalTokens,
-    };
-}
-// ── Persistence ───────────────────────────────────────────────────────────────
-function cacheFilePath(cwd) {
-    return path.join(getProjectDataDir(cwd), "cache", "codebase-model.json");
-}
-function metaFilePath(cwd) {
-    return path.join(getProjectDataDir(cwd), "cache", "codebase-model.meta.json");
-}
-export function saveCodebaseModel(cwd, model) {
-    const cacheFile = cacheFilePath(cwd);
-    try {
-        fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
-        writeFileAtomic(cacheFile, JSON.stringify(model));
-        writeFileAtomic(metaFilePath(cwd), JSON.stringify({
-            savedAt: new Date().toISOString(),
-            entryCount: model.entries.length,
-            totalTokens: model.totalTokens,
-        }));
-    }
-    catch {
-        // Non-fatal — next session rebuilds.
-    }
-}
-/** Load only a model matching the canonical identity it was derived from. */
-export function loadCodebaseModel(cwd, expectedIdentity) {
-    try {
-        const raw = JSON.parse(fs.readFileSync(cacheFilePath(cwd), "utf-8"));
-        if (raw.version !== CODEBASE_MODEL_VERSION ||
-            typeof raw.reviewGraphVersion !== "string" ||
-            raw.reviewGraphVersion.length === 0 ||
-            typeof raw.reviewGraphSignature !== "string" ||
-            raw.reviewGraphSignature.length === 0 ||
-            typeof raw.generatedAt !== "string" ||
-            !Array.isArray(raw.entries))
-            return undefined;
-        if (raw.reviewGraphVersion !== expectedIdentity.reviewGraphVersion ||
-            raw.reviewGraphSignature !== expectedIdentity.reviewGraphSignature)
-            return undefined;
-        return raw;
-    }
-    catch {
-        return undefined;
-    }
-}

package/dist/clients/collateral-test-role.js

@@ -1,40 +0,0 @@
-/**
- * Shared test-role predicate for COLLATERAL cascade/impact surfaces (#1080).
- *
- * The review graph is already tests-free (`review-graph/builder.ts` applies
- * `detectFileRole(file) !== "test"` at its walk/incremental chokepoints), but
- * several collateral surfaces re-derive neighbors from OTHER sources that never
- * saw that filter — LSP reference expansion, module-level downstream expansion,
- * the reverse-dependency index, and the passive-diagnostics fallback — so an
- * unignored `*.test.*` / `tests/` file can still leak into cascade neighbor
- * output, the formatted impact header/counts, the turn-end call-graph advisory,
- * and the persisted call-graph-impact diagnostics.
- *
- * This composes the SINGLE existing structural classifier (`detectFileRole`) —
- * no second matcher, no private test-filename list, no duplicated patterns. The
- * project ignore matcher (`getProjectIgnoreMatcher`) is applied separately and
- * unchanged at each surface; this predicate only adds the test-ROLE half of the
- * display policy the review graph already enforces.
- *
- * Honesty (#1080 acceptance criteria):
- *  - A KNOWN `"test"` role is filtered from the collateral surface.
- *  - If role classification cannot be obtained (an unexpected throw), the
- *    candidate is RETAINED (`false`) rather than dropped — filtering must never
- *    invent a heuristic or silently drop a potentially actionable file, and must
- *    never convert an incomplete/indeterminate computation into a clean result.
- */
-import { detectFileRole } from "./file-role.js";
-/**
- * True when `filePath` is a KNOWN test-role file that must not surface as a
- * collateral cascade/impact neighbor. Path-based only (no content needed for
- * the test-role branch of `detectFileRole`). Fail-open: any classifier error
- * returns `false` (retain the candidate).
- */
-export function isTestRoleCollateral(filePath) {
-    try {
-        return detectFileRole(filePath) === "test";
-    }
-    catch {
-        return false;
-    }
-}