pi-lens 3.8.73 → 4.0.0

package/dist/clients/path-keyed-map.js

@@ -0,0 +1,76 @@
+/**
+ * A `Map` for file-path keys that folds every key through a caller-supplied
+ * normalizer INTERNALLY, so keying on a raw (non-normalized) path is
+ * structurally impossible — the whole path-key divergence class (#1025,
+ * follow-up to #1020/#210) collapses to "pick the right normalizer once, at
+ * construction," instead of every call site having to remember to normalize on
+ * write AND read AND delete (the exact discipline #210 declared and #1020
+ * proved is easy to miss).
+ *
+ * The normalizer runs on EVERY `get`/`set`/`has`/`delete`, so two
+ * differently-formed keys for the same path (`SUB\a.ts` vs `sub/a.ts`, on a
+ * case-insensitive FS) collapse to a single entry — no silent duplicate, no
+ * `has()` miss, no orphaned stale entry.
+ *
+ * Values retain their ORIGINAL display path. Consumers that render paths
+ * (symbol_search results, footer widgets) must not see a lowercased /
+ * slash-folded key, so the entry stores the display path alongside the value
+ * and every iteration surface (`keys`/`values`/`entries`/`forEach`/the default
+ * iterator) yields that display path — the exact form last written, never the
+ * folded internal key. `set` refreshes the display path to the most recent
+ * write (last-writer-wins), matching a plain `Map`'s "the key you set is the
+ * key you see" intuition while still de-duplicating by normalized identity.
+ *
+ * Choose the normalizer to match how the keyed state is used:
+ *  - `normalizeEphemeralMapKey` (path-utils.ts) — cheap slash-fold +
+ *    win32-lowercase, NO filesystem I/O — for hot, single-process, in-memory
+ *    indexes whose keys this process produced itself (e.g. the word index).
+ *  - `normalizeMapKey` — realpath-canonicalizing — for long-lived state shared
+ *    across call sites where symlink/real-casing resolution matters.
+ */
+export class PathKeyedMap {
+    normalize;
+    store = new Map();
+    constructor(normalize) {
+        this.normalize = normalize;
+    }
+    get size() {
+        return this.store.size;
+    }
+    get(path) {
+        return this.store.get(this.normalize(path))?.value;
+    }
+    has(path) {
+        return this.store.has(this.normalize(path));
+    }
+    set(path, value) {
+        this.store.set(this.normalize(path), { displayPath: path, value });
+        return this;
+    }
+    delete(path) {
+        return this.store.delete(this.normalize(path));
+    }
+    clear() {
+        this.store.clear();
+    }
+    *keys() {
+        for (const entry of this.store.values())
+            yield entry.displayPath;
+    }
+    *values() {
+        for (const entry of this.store.values())
+            yield entry.value;
+    }
+    *entries() {
+        for (const entry of this.store.values())
+            yield [entry.displayPath, entry.value];
+    }
+    forEach(callback) {
+        for (const entry of this.store.values()) {
+            callback(entry.value, entry.displayPath, this);
+        }
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+}

package/dist/clients/path-utils.js

@@ -13,13 +13,63 @@
 import { existsSync, realpathSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { dirname, win32 } from "node:path";
+import { win32 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { minimatch } from "./deps/minimatch.js";
 /**
- * Detect if a path is a Windows path (has drive letter or UNC prefix).
+ * Detect a positively Windows-shaped path, regardless of the host OS.
+ *
+ * A backslash anywhere in a path is not enough: it is a legal character in a
+ * POSIX filename. Only a drive-letter prefix (`X:`), a UNC root (`\\`), or a
+ * rooted backslash at position zero (`\`) selects Windows parsing.
+ */
+export function isWindowsPath(filePath) {
+    return /^[A-Za-z]:/.test(filePath) || filePath.startsWith("\\");
+}
+/**
+ * Canonical backslash→forward-slash fold — the single sanctioned form of the
+ * `p.replace(/\\/g, "/")` idiom otherwise hand-rolled across the codebase
+ * (~138 sites, #1193). PURE separator normalization: it does NOT resolve,
+ * canonicalize, lowercase, or collapse repeated slashes — reach for
+ * `normalizeFilePath`/`normalizeMapKey`/`normalizeEphemeralMapKey` when a
+ * canonical map *key* (case-fold / realpath) is what you need. Consolidating on
+ * this funnels the scattered transform and makes a shape-2 lint/ast-grep rule
+ * possible for the first time: today a bare inline `.replace(/\\/g, "/")` is
+ * byte-identical to the sanctioned use so it can't be ruled (#1158); once
+ * everything routes through `toPosix`, an *un-migrated* inline `.replace`
+ * becomes detectable.
+ */
+export function toPosix(filePath) {
+    return filePath.replace(/\\/g, "/");
+}
+/** Return whether `filePath` is fully qualified under Windows semantics. */
+export function isFullyQualifiedWin32(filePath) {
+    return win32.isAbsolute(filePath) && win32.parse(filePath).root.length > 1;
+}
+/** Return whether `filePath` is fully qualified under POSIX semantics. */
+export function isFullyQualifiedPosix(filePath) {
+    return path.posix.isAbsolute(filePath) && !isWindowsPath(filePath);
+}
+/**
+ * Return whether `filePath` is fully qualified under the host's semantics.
+ *
+ * In particular, `/foo` is rooted-relative under Win32 (ambient-drive
+ * dependent) but fully qualified under POSIX.
+ */
+export function isFullyQualified(filePath) {
+    return process.platform === "win32"
+        ? isFullyQualifiedWin32(filePath)
+        : isFullyQualifiedPosix(filePath);
+}
+/**
+ * Split a path into its non-empty segments on EITHER separator (`\` or `/`),
+ * regardless of the running OS — the shape-safe form of `p.split(path.sep)` /
+ * an inline `p.split(/[\\/]+/)`, which #1161/#1163 showed must not assume the
+ * host separator for a possibly-cross-shaped path. Drops empty segments
+ * (leading slash, drive-root, doubled separators).
  */
-function isWindowsPath(filePath) {
-    return /^[A-Za-z]:/.test(filePath) || filePath.startsWith("\\\\");
+export function splitPathSegments(filePath) {
+    return filePath.split(/[\\/]+/).filter(Boolean);
 }
 /**
  * Normalize a file path for consistent Map key usage.
@@ -86,7 +136,15 @@ function resolveNonExisting(filePath) {
             const base = canonical.replace(/\\/g, "/");
             return base.endsWith("/") ? base + tail : `${base}/${tail}`;
         }
-        const parent = dirname(current);
+        // Use win32.dirname (not the platform-default dirname) so a
+        // Windows-shaped path is parsed with win32 semantics regardless of the
+        // running OS — consistent with the win32.resolve/win32.normalize this
+        // branch already commits to. The platform-default POSIX dirname would
+        // find no separator in a win32-resolved "C:\repo\..." path (its only
+        // separators are backslashes), collapse to ".", stop the upward walk at
+        // cwd, and mangle the key on Linux CI (refs #1150, the #1024
+        // OS-divergence class).
+        const parent = win32.dirname(current);
         if (parent === current) {
             // Reached filesystem root without finding existing dir
             // Fall back to full lowercase
@@ -110,6 +168,29 @@ export function uriToPath(uri) {
         return normalizeFilePath(uri);
     }
 }
+/**
+ * Decode a file:// URI to an on-disk path WITHOUT map-key normalization.
+ *
+ * `uriToPath` runs its result through `normalizeFilePath`, which on win32
+ * lowercases the nonexistent tail of a path (see `resolveNonExisting`) and
+ * canonicalizes an existing path to its real casing. That is correct for Map
+ * keys, but DESTRUCTIVE for a real create/rename target: creating `NewFile.txt`
+ * would write `newfile.txt`, and a legitimate case-only rename would collapse
+ * to a no-op ("source and destination must differ"). Disk mutations must honor
+ * the caller's intended casing, so they resolve their target through this
+ * decode-only path while confinement/validation keep using the normalized
+ * `uriToPath`. Non-win32 is unaffected either way (normalizeFilePath is a
+ * near-identity there).
+ */
+export function uriToDiskPath(uri) {
+    try {
+        return fileURLToPath(uri);
+    }
+    catch {
+        // Not a valid file:// URI — treat as a plain path (matches uriToPath).
+        return uri;
+    }
+}
 /**
  * Convert a path to a file:// URI.
  * Does NOT normalize the path - URIs preserve original casing.
@@ -124,6 +205,31 @@ export function pathToUri(filePath) {
 export function normalizeMapKey(filePath) {
     return normalizeFilePath(filePath);
 }
+/**
+ * Human-facing path relative to a project root when the file is inside it.
+ *
+ * Parses by path SHAPE, not host OS (refs #1150/#1152, shape-2 class #1163):
+ * a Windows-shaped `filePath` (drive-letter/UNC — e.g. a persisted call-graph
+ * symbol-key path `C:\repo\src\x.ts` rehydrated on a Linux CI run) is split
+ * with `win32.*` regardless of `process.platform`. The host-default
+ * `isAbsolute`/`relative` find no drive-letter anchor in a win32 path on POSIX:
+ * `path.isAbsolute("C:\\repo\\x.ts")` returns FALSE on Linux, short-circuiting
+ * to the raw absolute path instead of ever relativizing it — so a file that IS
+ * under the project root renders as a full absolute path on Linux but the
+ * expected `src/x.ts` on Windows (green-locally / wrong-on-CI, the #1024
+ * divergence class). `win32.*` on a native POSIX path (Windows never sees one;
+ * Linux native paths aren't Windows-shaped) is never selected, so same-OS
+ * native paths are unchanged either way.
+ */
+export function toProjectRelativePath(filePath, projectRoot) {
+    const p = isWindowsPath(filePath) ? win32 : path;
+    if (!p.isAbsolute(filePath))
+        return filePath.replace(/\\/g, "/");
+    const relative = p.relative(p.resolve(projectRoot), filePath);
+    return relative && !relative.startsWith("..") && !p.isAbsolute(relative)
+        ? relative.replace(/\\/g, "/")
+        : filePath.replace(/\\/g, "/");
+}
 /**
  * Cheap, syntactic-only Map key normalization: slash-fold + (on Windows)
  * lowercase. No `realpathSync` / filesystem I/O.
@@ -146,6 +252,11 @@ export function normalizeMapKey(filePath) {
  * real-casing resolution actually matters.
  */
 export function normalizeEphemeralMapKey(filePath) {
+    // Most hot-path keys on POSIX are already canonical slash-separated strings.
+    // Preserve that identity instead of allocating a replacement string for each
+    // file in a large diagnostics reconciliation.
+    if (process.platform !== "win32" && !filePath.includes("\\"))
+        return filePath;
     const slashed = filePath.replace(/\\/g, "/");
     return process.platform === "win32" ? slashed.toLowerCase() : slashed;
 }
@@ -316,3 +427,28 @@ export function isExternalOrVendorFile(filePath, projectRoot) {
         : normalized;
     return rel.split("/").some((seg) => VENDOR_DIR_NAMES.has(seg));
 }
+/**
+ * Shared marker-glob semantics for every "does this directory contain a file
+ * matching this glob" probe (#895 review): match against the entry NAME only,
+ * `dot: true` so dotfile markers match, `nocase` on win32 to match the
+ * filesystem (and the project ignore matcher). The three marker probes —
+ * language-profile.ts `hasProjectMarker`, workspace-topology.ts
+ * `hasBasenameMarker`, lsp/server.ts `markerExists` — must all route their
+ * glob matching through here rather than call minimatch with hand-copied
+ * options.
+ */
+export function nameMatchesMarkerGlob(name, pattern) {
+    return minimatch(name, pattern, {
+        dot: true,
+        nocase: process.platform === "win32",
+    });
+}
+/**
+ * Files/symlinks-only marker-glob probe over a directory listing — a
+ * *directory* named like a marker (e.g. a `Foo.csproj/` dir) is not a project
+ * file (#201).
+ */
+export function direntsHaveMarkerGlobMatch(entries, pattern) {
+    return entries.some((entry) => (entry.isFile() || entry.isSymbolicLink()) &&
+        nameMatchesMarkerGlob(entry.name, pattern));
+}

package/dist/clients/performance-report.js

@@ -0,0 +1,327 @@
+import * as fs from "node:fs";
+import * as readline from "node:readline";
+import { flushLatencyLog, getLatencyLogPath, } from "./latency-logger.js";
+import { getMaxLogSizeMB } from "./log-cleanup.js";
+export const DEFAULT_PERF_TOP_N = 5;
+export const MAX_PERF_TOP_N = 50;
+export const MAX_PERF_PHASE_SAMPLES = 20_000;
+const PARSE_YIELD_EVERY = 500;
+// The window follows the same threshold that rotates the log out from under it.
+// Exported so a test can size a fixture to the window it means to saturate
+// rather than to a second copy of the default that can drift out of agreement.
+export function resolveLogByteBudget() {
+    return getMaxLogSizeMB() * 1024 * 1024;
+}
+function boundedPositiveInteger(value, maximum, fallback = maximum) {
+    return Number.isFinite(value) && value > 0
+        ? Math.min(maximum, Math.max(1, Math.floor(value)))
+        : fallback;
+}
+function percentile(sorted, quantile) {
+    const position = (sorted.length - 1) * quantile;
+    const lower = Math.floor(position);
+    const upper = Math.ceil(position);
+    return lower === upper
+        ? sorted[lower]
+        : sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
+}
+function roundedMs(value) {
+    return Math.round(value * 10) / 10;
+}
+function isEntryObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isPhaseRecord(value) {
+    if (!isEntryObject(value))
+        return false;
+    return (value.type === "phase" &&
+        typeof value.phase === "string" &&
+        value.phase.trim().length > 0 &&
+        typeof value.durationMs === "number" &&
+        Number.isFinite(value.durationMs) &&
+        value.durationMs >= 0 &&
+        (value.toolName === undefined || typeof value.toolName === "string") &&
+        (value.ts === undefined || typeof value.ts === "string") &&
+        (value.startedAt === undefined || typeof value.startedAt === "string") &&
+        (value.pid === undefined ||
+            (typeof value.pid === "number" && Number.isFinite(value.pid))));
+}
+function isPhaseSample(value) {
+    return isPhaseRecord(value) && value.durationMs > 0;
+}
+function phaseKey(entry) {
+    const phase = entry.phase?.trim() ?? "";
+    const toolName = entry.toolName?.trim();
+    return toolName ? `${toolName}/${phase}` : phase;
+}
+function isCurrentSessionSample(entry, processId, sessionStartedAt) {
+    if (entry.pid !== processId || typeof entry.ts !== "string")
+        return false;
+    const finishedAt = Date.parse(entry.ts);
+    if (!Number.isFinite(finishedAt) || finishedAt < sessionStartedAt)
+        return false;
+    if (entry.startedAt === undefined)
+        return true;
+    const startedAt = Date.parse(entry.startedAt);
+    return Number.isFinite(startedAt) && startedAt >= sessionStartedAt;
+}
+function createPhaseBuffer(limit) {
+    return { values: [], nextIndex: 0, total: 0, limit };
+}
+function retainEntry(buffer, entry) {
+    buffer.total += 1;
+    if (buffer.values.length < buffer.limit) {
+        buffer.values.push(entry);
+        return;
+    }
+    buffer.values[buffer.nextIndex] = entry;
+    buffer.nextIndex = (buffer.nextIndex + 1) % buffer.limit;
+}
+function orderedEntries(buffer) {
+    return buffer.total > buffer.values.length
+        ? [
+            ...buffer.values.slice(buffer.nextIndex),
+            ...buffer.values.slice(0, buffer.nextIndex),
+        ]
+        : buffer.values;
+}
+export function summarizePhaseLatency(entries, topN = DEFAULT_PERF_TOP_N) {
+    const durationsByPhase = new Map();
+    let oldestTimestamp;
+    let newestTimestamp;
+    let sampleCount = 0;
+    for (const entry of entries) {
+        if (!isPhaseSample(entry))
+            continue;
+        const phase = phaseKey(entry);
+        const durations = durationsByPhase.get(phase) ?? [];
+        durations.push(entry.durationMs);
+        durationsByPhase.set(phase, durations);
+        sampleCount += 1;
+        if (typeof entry.ts === "string") {
+            const ms = Date.parse(entry.ts);
+            if (Number.isFinite(ms)) {
+                if (!oldestTimestamp || ms < oldestTimestamp.ms) {
+                    oldestTimestamp = { ms, iso: entry.ts };
+                }
+                if (!newestTimestamp || ms > newestTimestamp.ms) {
+                    newestTimestamp = { ms, iso: entry.ts };
+                }
+            }
+        }
+    }
+    const summaries = Array.from(durationsByPhase, ([phase, durations]) => {
+        const sorted = [...durations].sort((a, b) => a - b);
+        const p50RawMs = percentile(sorted, 0.5);
+        const p99RawMs = percentile(sorted, 0.99);
+        return {
+            phase,
+            samples: sorted.length,
+            p50Ms: roundedMs(p50RawMs),
+            p99Ms: roundedMs(p99RawMs),
+            p50RawMs,
+            p99RawMs,
+        };
+    });
+    const limit = boundedPositiveInteger(topN, MAX_PERF_TOP_N, DEFAULT_PERF_TOP_N);
+    const tieBreak = (a, b) => b.samples - a.samples || a.phase.localeCompare(b.phase);
+    const toPublic = ({ phase, samples, p50Ms, p99Ms, }) => ({
+        phase,
+        samples,
+        p50Ms,
+        p99Ms,
+    });
+    const rankBy = (primary, secondary) => [...summaries]
+        .sort((a, b) => b[primary] - a[primary] ||
+        b[secondary] - a[secondary] ||
+        tieBreak(a, b))
+        .slice(0, limit)
+        .map(toPublic);
+    return {
+        sampleCount,
+        phaseCount: durationsByPhase.size,
+        oldestTs: oldestTimestamp?.iso,
+        newestTs: newestTimestamp?.iso,
+        slowestByP50: rankBy("p50RawMs", "p99RawMs"),
+        slowestByP99: rankBy("p99RawMs", "p50RawMs"),
+    };
+}
+async function readPhaseLogTail(filePath, windowBytes, maxSamples, processId, sessionStartedAt) {
+    const empty = () => ({
+        logEntries: [],
+        sessionEntries: [],
+        windowTruncated: false,
+        logSamplesTruncated: false,
+        sessionSamplesTruncated: false,
+        totalPhaseSamples: 0,
+        totalSessionPhaseSamples: 0,
+        malformedLines: 0,
+        invalidRecords: 0,
+    });
+    let handle;
+    try {
+        handle = await fs.promises.open(filePath, "r");
+        const stat = await handle.stat();
+        if (!stat.isFile()) {
+            // POSIX rejects opening a directory with EISDIR, but Windows opens it
+            // successfully with size 0 — which would fall into the empty() branch
+            // and conflate "unreadable path" with "no data yet". Throw the same
+            // error POSIX would so both platforms surface the bad path.
+            const notAFile = new Error(`EISDIR: illegal operation on a directory, read '${filePath}'`);
+            notAFile.code = "EISDIR";
+            throw notAFile;
+        }
+        if (stat.size === 0)
+            return empty();
+        const sampleLimit = boundedPositiveInteger(maxSamples, MAX_PERF_PHASE_SAMPLES);
+        const start = Math.max(0, stat.size - windowBytes);
+        let discardPartialFirstLine = false;
+        if (start > 0) {
+            const previousByte = Buffer.alloc(1);
+            const { bytesRead } = await handle.read(previousByte, 0, 1, start - 1);
+            discardPartialFirstLine = bytesRead === 1 && previousByte[0] !== 0x0a;
+        }
+        const stream = handle.createReadStream({
+            start,
+            end: stat.size - 1,
+            autoClose: false,
+            encoding: "utf8",
+        });
+        const lines = readline.createInterface({
+            input: stream,
+            crlfDelay: Infinity,
+        });
+        const logBuffer = createPhaseBuffer(sampleLimit);
+        const sessionBuffer = createPhaseBuffer(sampleLimit);
+        let malformedLines = 0;
+        let invalidRecords = 0;
+        let lineCount = 0;
+        for await (const line of lines) {
+            lineCount += 1;
+            if (lineCount % PARSE_YIELD_EVERY === 0) {
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+            if (discardPartialFirstLine) {
+                discardPartialFirstLine = false;
+                continue;
+            }
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const value = JSON.parse(trimmed);
+                if (isPhaseSample(value)) {
+                    retainEntry(logBuffer, value);
+                    if (isCurrentSessionSample(value, processId, sessionStartedAt)) {
+                        retainEntry(sessionBuffer, value);
+                    }
+                }
+                else if (!isPhaseRecord(value) &&
+                    (!isEntryObject(value) || value.type === "phase")) {
+                    invalidRecords += 1;
+                }
+            }
+            catch {
+                malformedLines += 1;
+            }
+        }
+        return {
+            logEntries: orderedEntries(logBuffer),
+            sessionEntries: orderedEntries(sessionBuffer),
+            windowTruncated: start > 0,
+            logSamplesTruncated: logBuffer.total > sampleLimit,
+            sessionSamplesTruncated: sessionBuffer.total > sampleLimit,
+            totalPhaseSamples: logBuffer.total,
+            totalSessionPhaseSamples: sessionBuffer.total,
+            malformedLines,
+            invalidRecords,
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return empty();
+        throw error;
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+export async function collectLatencyPerformance(options) {
+    await flushLatencyLog();
+    const logPath = options.logPath ?? getLatencyLogPath();
+    const processId = options.processId ?? process.pid;
+    const topN = boundedPositiveInteger(options.topN ?? DEFAULT_PERF_TOP_N, MAX_PERF_TOP_N, DEFAULT_PERF_TOP_N);
+    const byteBudget = resolveLogByteBudget();
+    const windowBytes = boundedPositiveInteger(options.maxBytes ?? byteBudget, byteBudget);
+    const tail = await readPhaseLogTail(logPath, windowBytes, options.maxSamples ?? MAX_PERF_PHASE_SAMPLES, processId, options.sessionStartedAt);
+    const { logEntries, sessionEntries, ...counters } = tail;
+    return {
+        logPath,
+        topN,
+        windowBytes,
+        ...counters,
+        session: summarizePhaseLatency(sessionEntries, topN),
+        logWindow: summarizePhaseLatency(logEntries, topN),
+    };
+}
+function formatDuration(ms) {
+    if (ms >= 1000)
+        return `${(ms / 1000).toFixed(2)}s`;
+    if (ms > 0 && ms < 1)
+        return `${ms.toFixed(2)}ms`;
+    return `${Number.isInteger(ms) ? ms : ms.toFixed(1)}ms`;
+}
+function formatByteBudget(bytes) {
+    if (bytes >= 1024 * 1024) {
+        return `${Number((bytes / (1024 * 1024)).toFixed(1))}MB`;
+    }
+    if (bytes >= 1024)
+        return `${Number((bytes / 1024).toFixed(1))}KB`;
+    return `${bytes}B`;
+}
+function formatTimestamp(ts) {
+    const parsed = new Date(ts);
+    return Number.isFinite(parsed.getTime())
+        ? `${parsed.toISOString().slice(0, 19).replace("T", " ")}Z`
+        : ts;
+}
+function renderRanking(lines, label, phases) {
+    lines.push(`  ${label}:`);
+    for (const phase of phases) {
+        lines.push(`    ${phase.phase}: p50 ${formatDuration(phase.p50Ms)}, p99 ${formatDuration(phase.p99Ms)}, n=${phase.samples}`);
+    }
+}
+function renderScope(lines, label, scope) {
+    const range = scope.oldestTs && scope.newestTs
+        ? `, ${formatTimestamp(scope.oldestTs)} to ${formatTimestamp(scope.newestTs)}`
+        : "";
+    lines.push("", `${label} (${scope.sampleCount} samples across ${scope.phaseCount} phases${range})`);
+    if (scope.slowestByP99.length === 0) {
+        lines.push("  No phase timings yet.");
+        return;
+    }
+    renderRanking(lines, "Highest p50", scope.slowestByP50);
+    renderRanking(lines, "Highest p99", scope.slowestByP99);
+}
+export function renderLatencyPerformanceReport(report) {
+    const lines = [
+        "⏱️ PI-LENS PERFORMANCE",
+        `Top ${report.topN} sustained and tail latency phases.`,
+    ];
+    renderScope(lines, "Current process session", report.session);
+    renderScope(lines, "Machine-wide active log window", report.logWindow);
+    lines.push("", `Source: ${report.logPath}`);
+    if (report.windowTruncated) {
+        lines.push(`Both scopes use only the newest ${formatByteBudget(report.windowBytes)} of the active log.`);
+    }
+    if (report.sessionSamplesTruncated) {
+        lines.push(`Session percentiles use the newest ${report.session.sampleCount.toLocaleString("en-US")} of ${report.totalSessionPhaseSamples.toLocaleString("en-US")} phase samples.`);
+    }
+    if (report.logSamplesTruncated) {
+        lines.push(`Machine-wide percentiles use the newest ${report.logWindow.sampleCount.toLocaleString("en-US")} of ${report.totalPhaseSamples.toLocaleString("en-US")} phase samples.`);
+    }
+    if (report.malformedLines > 0 || report.invalidRecords > 0) {
+        lines.push(`Skipped ${report.malformedLines} malformed line(s) and ${report.invalidRecords} invalid record(s).`);
+    }
+    return lines.join("\n");
+}