pi-lens 3.8.21 → 3.8.22

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to pi-lens will be documented in this file.
 
+## [3.8.22] - 2026-04-09
+
+### Changed
+- **Quick startup path for one-shot print sessions** — `--print`/`-p` now auto-selects quick startup mode to skip heavy bootstrap work and reduce startup latency. Added `PI_LENS_STARTUP_MODE=full|minimal|quick` override for explicit control.
+
+### Fixed
+- **Cascade diagnostics formatting clarity** — turn-end cascade entries now render source location as `line <n>, col <m> code=<id>:` so diagnostic codes (for example `TS2322`) are no longer formatted in a way that can be mistaken for file line numbers.
+
 ## [3.8.21] - 2026-04-08
 
 ### Changed

package/README.md

@@ -28,6 +28,8 @@ At `session_start`, pi-lens:
 - emits missing-tool install hints for detected languages when relevant
 - injects session guidance through internal context (non-user channel) to reduce acknowledgement-only first responses
 
+For one-shot print sessions (for example `pi --print ...`), pi-lens auto-uses a quick startup path that skips heavy bootstrap work to reduce startup latency. You can override startup behavior with `PI_LENS_STARTUP_MODE=full|minimal|quick`.
+
 ### Turn End
 
 At `turn_end`, pi-lens:

package/clients/dispatch/runners/lsp.ts

@@ -25,6 +25,33 @@ import { readFileContent } from "./utils.js";
 
 const LSP_MAX_FILE_BYTES = RUNTIME_CONFIG.pipeline.lspMaxFileBytes;
 const LSP_MAX_FILE_LINES = RUNTIME_CONFIG.pipeline.lspMaxFileLines;
+const MAX_CODE_ACTION_LOOKUPS = 6;
+const MAX_CODE_ACTION_TITLES = 3;
+
+function normalizeActionTitle(title: string): string {
+	return title.replace(/\s+/g, " ").trim();
+}
+
+function buildCodeActionSuggestion(
+	actions: import("../../lsp/client.js").LSPCodeAction[],
+): string | undefined {
+	if (!actions.length) return undefined;
+	const quickFixes = actions.filter((action) =>
+		action.kind?.startsWith("quickfix"),
+	);
+	if (!quickFixes.length) return undefined;
+
+	const titles = Array.from(
+		new Set(
+			quickFixes
+				.map((action) => normalizeActionTitle(action.title))
+				.filter((title) => title.length > 0),
+		),
+	).slice(0, MAX_CODE_ACTION_TITLES);
+
+	if (!titles.length) return undefined;
+	return `LSP quick fixes: ${titles.join("; ")}`;
+}
 
 const lspRunner: RunnerDefinition = {
 	id: "lsp",
@@ -125,9 +152,35 @@ const lspRunner: RunnerDefinition = {
 
 		// Convert LSP diagnostics to our format
 		// Defensive: filter out malformed diagnostics that may lack range
-		const diagnostics: Diagnostic[] = lspDiags
-			.filter((d) => d.range?.start?.line !== undefined)
-			.map((d) => ({
+		const validLspDiags = lspDiags.filter((d) => d.range?.start?.line !== undefined);
+		const fixSuggestionByIndex = new Map<number, string>();
+
+		const blockingDiagIndexes = validLspDiags
+			.map((d, idx) => ({ d, idx }))
+			.filter(({ d }) => d.severity === 1)
+			.slice(0, MAX_CODE_ACTION_LOOKUPS);
+
+		for (const { d, idx } of blockingDiagIndexes) {
+			try {
+				const start = d.range.start;
+				const end = d.range.end ?? d.range.start;
+				const actions = await lspService.codeAction(
+					ctx.filePath,
+					start.line,
+					start.character,
+					end.line,
+					end.character,
+				);
+				const suggestion = buildCodeActionSuggestion(actions);
+				if (suggestion) {
+					fixSuggestionByIndex.set(idx, suggestion);
+				}
+			} catch {
+				// Best-effort enrichment only; base diagnostics remain authoritative.
+			}
+		}
+
+		const diagnostics: Diagnostic[] = validLspDiags.map((d, idx) => ({
 				id: `lsp:${d.code ?? "unknown"}:${d.range.start.line}`,
 				message: d.message,
 				filePath: diagnosticPath,
@@ -143,6 +196,8 @@ const lspRunner: RunnerDefinition = {
 							: "none",
 				tool: "lsp",
 				code: String(d.code ?? ""),
+				fixable: fixSuggestionByIndex.has(idx),
+				fixSuggestion: fixSuggestionByIndex.get(idx),
 			}));
 
 		const hasErrors = diagnostics.some((d) => d.semantic === "blocking");

package/clients/dispatch/runners/tree-sitter.ts

@@ -8,7 +8,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { RuleCache } from "../../cache/rule-cache.js";
+import { getSourceFiles } from "../../scan-utils.js";
 import { TreeSitterClient } from "../../tree-sitter-client.js";
+import { logTreeSitter } from "../../tree-sitter-logger.js";
 import { classifyDefect } from "../diagnostic-taxonomy.js";
 import {
 	queryLoader,
@@ -25,6 +27,294 @@ import type {
 // Creating a new TreeSitterClient() on every write resets TRANSFER_BUFFER (a module-level
 // WASM pointer) — concurrent writes race on _ts_init() and corrupt shared WASM state → crash.
 let _sharedClient: TreeSitterClient | null = null;
+const entitySnapshotByFile = new Map<string, Map<string, string>>();
+const blastFileCache = new Map<string, { expiresAt: number; files: string[] }>();
+const blastCooldownByFile = new Map<string, number>();
+const BLAST_CACHE_TTL_MS = 30_000;
+const MAX_BLAST_FILES = 300;
+const MAX_BLAST_ENTITIES = 8;
+const BLAST_MAX_FILE_BYTES = 128 * 1024;
+const BLAST_MAX_TOTAL_BYTES = 2 * 1024 * 1024;
+const BLAST_MAX_ELAPSED_MS = 120;
+const BLAST_COOLDOWN_MS = 5_000;
+
+interface EntityQueryDef {
+	id: string;
+	kind: string;
+	query: string;
+}
+
+const ENTITY_QUERIES: Partial<Record<string, EntityQueryDef[]>> = {
+	typescript: [
+		{
+			id: "entity-ts-function",
+			kind: "function",
+			query: "(function_declaration name: (identifier) @NAME)",
+		},
+		{
+			id: "entity-ts-class",
+			kind: "class",
+			query: "(class_declaration name: (type_identifier) @NAME)",
+		},
+		{
+			id: "entity-ts-method",
+			kind: "method",
+			query: "(method_definition name: (property_identifier) @NAME)",
+		},
+	],
+	javascript: [
+		{
+			id: "entity-js-function",
+			kind: "function",
+			query: "(function_declaration name: (identifier) @NAME)",
+		},
+		{
+			id: "entity-js-class",
+			kind: "class",
+			query: "(class_declaration name: (identifier) @NAME)",
+		},
+		{
+			id: "entity-js-method",
+			kind: "method",
+			query: "(method_definition name: (property_identifier) @NAME)",
+		},
+	],
+	python: [
+		{
+			id: "entity-py-function",
+			kind: "function",
+			query: "(function_definition name: (identifier) @NAME)",
+		},
+		{
+			id: "entity-py-class",
+			kind: "class",
+			query: "(class_definition name: (identifier) @NAME)",
+		},
+	],
+	go: [
+		{
+			id: "entity-go-function",
+			kind: "function",
+			query: "(function_declaration name: (identifier) @NAME)",
+		},
+		{
+			id: "entity-go-method",
+			kind: "method",
+			query: "(method_declaration name: (field_identifier) @NAME)",
+		},
+		{
+			id: "entity-go-type",
+			kind: "type",
+			query: "(type_spec name: (type_identifier) @NAME)",
+		},
+	],
+	rust: [
+		{
+			id: "entity-rs-function",
+			kind: "function",
+			query: "(function_item name: (identifier) @NAME)",
+		},
+		{
+			id: "entity-rs-struct",
+			kind: "struct",
+			query: "(struct_item name: (type_identifier) @NAME)",
+		},
+		{
+			id: "entity-rs-enum",
+			kind: "enum",
+			query: "(enum_item name: (type_identifier) @NAME)",
+		},
+	],
+	ruby: [
+		{
+			id: "entity-rb-method",
+			kind: "method",
+			query: "(method name: (identifier) @NAME)",
+		},
+		{
+			id: "entity-rb-class",
+			kind: "class",
+			query: "(class name: (constant) @NAME)",
+		},
+		{
+			id: "entity-rb-module",
+			kind: "module",
+			query: "(module name: (constant) @NAME)",
+		},
+	],
+};
+
+function escapeRegex(name: string): string {
+	return name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+async function extractEntitySnapshot(
+	client: TreeSitterClient,
+	filePath: string,
+	languageId: string,
+): Promise<Map<string, string>> {
+	const defs = ENTITY_QUERIES[languageId] ?? [];
+	const snapshot = new Map<string, string>();
+
+	for (const def of defs) {
+		const matches = await client.runQueryOnFile(
+			{
+				id: def.id,
+				name: def.id,
+				severity: "info",
+				category: "entity",
+				language: languageId,
+				message: "",
+				query: def.query,
+				metavars: ["NAME"],
+				has_fix: false,
+				filePath: "",
+			},
+			filePath,
+			languageId,
+			{ maxResults: 200 },
+		);
+
+		for (const match of matches) {
+			const name = match.captures.NAME?.trim();
+			if (!name) continue;
+			const key = `${def.kind}:${name}`;
+			snapshot.set(key, `${match.line}:${match.matchedText.slice(0, 400)}`);
+		}
+	}
+
+	return snapshot;
+}
+
+function diffEntitySnapshot(
+	prev: Map<string, string> | undefined,
+	next: Map<string, string>,
+): { added: string[]; removed: string[]; modified: string[] } {
+	if (!prev) {
+		return { added: [...next.keys()], removed: [], modified: [] };
+	}
+
+	const added: string[] = [];
+	const removed: string[] = [];
+	const modified: string[] = [];
+
+	for (const [key, value] of next.entries()) {
+		if (!prev.has(key)) {
+			added.push(key);
+			continue;
+		}
+		if (prev.get(key) !== value) {
+			modified.push(key);
+		}
+	}
+
+	for (const key of prev.keys()) {
+		if (!next.has(key)) {
+			removed.push(key);
+		}
+	}
+
+	return { added, removed, modified };
+}
+
+function getBlastFiles(cwd: string): string[] {
+	const now = Date.now();
+	const cached = blastFileCache.get(cwd);
+	if (cached && cached.expiresAt > now) return cached.files;
+
+	const files = getSourceFiles(cwd).slice(0, MAX_BLAST_FILES);
+	blastFileCache.set(cwd, { files, expiresAt: now + BLAST_CACHE_TTL_MS });
+	return files;
+}
+
+function computeBlastRadius(
+	entityNames: string[],
+	filePath: string,
+	cwd: string,
+): {
+	entities: Array<{ entity: string; dependentFiles: number; references: number }>;
+	scannedFiles: number;
+	scannedBytes: number;
+	totalCandidates: number;
+	truncated: boolean;
+	elapsedMs: number;
+} {
+	const startedAt = Date.now();
+	const limited = entityNames.slice(0, MAX_BLAST_ENTITIES);
+	if (limited.length === 0) {
+		return {
+			entities: [],
+			scannedFiles: 0,
+			scannedBytes: 0,
+			totalCandidates: 0,
+			truncated: false,
+			elapsedMs: 0,
+		};
+	}
+
+	const regexByEntity = new Map(
+		limited.map((name) => [name, new RegExp(`\\b${escapeRegex(name)}\\b`, "g")]),
+	);
+	const files = getBlastFiles(cwd);
+	const stats = new Map(
+		limited.map((name) => [name, { dependentFiles: 0, references: 0 }]),
+	);
+	let scannedFiles = 0;
+	let scannedBytes = 0;
+	let truncated = false;
+
+	for (const candidate of files) {
+		if (Date.now() - startedAt > BLAST_MAX_ELAPSED_MS) {
+			truncated = true;
+			break;
+		}
+
+		if (path.resolve(candidate) === path.resolve(filePath)) continue;
+		let size = 0;
+		try {
+			size = fs.statSync(candidate).size;
+		} catch {
+			continue;
+		}
+		if (size > BLAST_MAX_FILE_BYTES) continue;
+		if (scannedBytes + size > BLAST_MAX_TOTAL_BYTES) {
+			truncated = true;
+			break;
+		}
+
+		let content = "";
+		try {
+			content = fs.readFileSync(candidate, "utf-8");
+		} catch {
+			continue;
+		}
+		scannedFiles += 1;
+		scannedBytes += size;
+
+		for (const [name, regex] of regexByEntity.entries()) {
+			const matches = content.match(regex);
+			if (!matches || matches.length === 0) continue;
+			const current = stats.get(name);
+			if (!current) continue;
+			current.dependentFiles += 1;
+			current.references += matches.length;
+		}
+	}
+
+	const entities = limited
+		.map((name) => ({ entity: name, ...stats.get(name)! }))
+		.sort((a, b) => b.dependentFiles - a.dependentFiles)
+		.slice(0, 5);
+
+	return {
+		entities,
+		scannedFiles,
+		scannedBytes,
+		totalCandidates: files.length,
+		truncated,
+		elapsedMs: Date.now() - startedAt,
+	};
+}
 
 const SILENT_ERROR_QUERY_IDS = new Set([
 	"empty-catch",
@@ -78,12 +368,25 @@ const treeSitterRunner: RunnerDefinition = {
 	async run(ctx: DispatchContext): Promise<RunnerResult> {
 		// Use singleton client — WASM must never be re-initialized after first call
 		const client = getSharedClient();
+		logTreeSitter({ phase: "runner_start", filePath: ctx.filePath });
 		if (!client.isAvailable()) {
+			logTreeSitter({
+				phase: "runner_skip",
+				filePath: ctx.filePath,
+				reason: "client_unavailable",
+				status: "skipped",
+			});
 			return { status: "skipped", diagnostics: [], semantic: "none" };
 		}
 
 		const initialized = await client.init();
 		if (!initialized) {
+			logTreeSitter({
+				phase: "runner_skip",
+				filePath: ctx.filePath,
+				reason: "client_init_failed",
+				status: "skipped",
+			});
 			return { status: "skipped", diagnostics: [], semantic: "none" };
 		}
 
@@ -106,6 +409,12 @@ const treeSitterRunner: RunnerDefinition = {
 		};
 		const languageId = EXT_TO_LANG[ext];
 		if (!languageId) {
+			logTreeSitter({
+				phase: "runner_skip",
+				filePath: ctx.filePath,
+				reason: `unsupported_extension:${ext}`,
+				status: "skipped",
+			});
 			return { status: "skipped", diagnostics: [], semantic: "none" };
 		}
 
@@ -132,8 +441,10 @@ const treeSitterRunner: RunnerDefinition = {
 
 		// Try cache
 		const cached = cache.get(ruleFiles);
+		let cacheHit = false;
 		if (cached) {
 			// Use cached queries
+			cacheHit = true;
 			languageQueries = cached.queries.map(
 				(q) =>
 					({
@@ -173,6 +484,16 @@ const treeSitterRunner: RunnerDefinition = {
 		}
 
 		if (languageQueries.length === 0) {
+			logTreeSitter({
+				phase: "runner_complete",
+				filePath,
+				languageId,
+				status: "succeeded",
+				diagnostics: 0,
+				blocking: 0,
+				queryCount: 0,
+				effectiveQueryCount: 0,
+			});
 			return { status: "succeeded", diagnostics: [], semantic: "none" };
 		}
 
@@ -186,6 +507,16 @@ const treeSitterRunner: RunnerDefinition = {
 				)
 			: languageQueries;
 
+		logTreeSitter({
+			phase: "queries_loaded",
+			filePath,
+			languageId,
+			queryCount: languageQueries.length,
+			effectiveQueryCount: effectiveQueries.length,
+			cacheHit,
+			metadata: { blockingOnly: !!ctx.blockingOnly },
+		});
+
 		const diagnostics: Diagnostic[] = [];
 
 		// Run each query against the file
@@ -244,15 +575,151 @@ const treeSitterRunner: RunnerDefinition = {
 			} catch (err) {
 				// Individual query failure shouldn't stop other queries
 				console.error(`[tree-sitter] Query ${query.id} failed:`, err);
+				logTreeSitter({
+					phase: "query_error",
+					filePath,
+					languageId,
+					queryId: query.id,
+					error: err instanceof Error ? err.message : String(err),
+				});
 			}
 		}
 
 		if (diagnostics.length === 0) {
+			try {
+				const snapshot = await extractEntitySnapshot(client, filePath, languageId);
+				const prev = entitySnapshotByFile.get(filePath);
+				const diff = diffEntitySnapshot(prev, snapshot);
+				entitySnapshotByFile.set(filePath, snapshot);
+				const changedEntityKeys = [...diff.added, ...diff.modified, ...diff.removed];
+				const changedNames = [...new Set(changedEntityKeys.map((k) => k.split(":")[1]).filter(Boolean))];
+
+				if (changedEntityKeys.length > 0) {
+					logTreeSitter({
+						phase: "entity_diff",
+						filePath,
+						languageId,
+						metadata: {
+							added: diff.added,
+							modified: diff.modified,
+							removed: diff.removed,
+							totalChanged: changedEntityKeys.length,
+						},
+					});
+
+					const lastBlast = blastCooldownByFile.get(filePath) ?? 0;
+					if (Date.now() - lastBlast < BLAST_COOLDOWN_MS) {
+						logTreeSitter({
+							phase: "blast_radius",
+							filePath,
+							languageId,
+							metadata: { skipped: "cooldown", cooldownMs: BLAST_COOLDOWN_MS },
+						});
+					} else {
+						blastCooldownByFile.set(filePath, Date.now());
+						const blastRadius = computeBlastRadius(changedNames, filePath, ctx.cwd);
+						logTreeSitter({
+							phase: "blast_radius",
+							filePath,
+							languageId,
+							metadata: {
+								entities: blastRadius.entities,
+								scannedFiles: blastRadius.scannedFiles,
+								scannedBytes: blastRadius.scannedBytes,
+								totalCandidates: blastRadius.totalCandidates,
+								truncated: blastRadius.truncated,
+								elapsedMs: blastRadius.elapsedMs,
+							},
+						});
+					}
+				}
+			} catch {}
+
+			logTreeSitter({
+				phase: "runner_complete",
+				filePath,
+				languageId,
+				status: "succeeded",
+				diagnostics: 0,
+				blocking: 0,
+				queryCount: languageQueries.length,
+				effectiveQueryCount: effectiveQueries.length,
+			});
 			return { status: "succeeded", diagnostics: [], semantic: "none" };
 		}
 
 		// Check if any blocking issues
 		const hasBlocking = diagnostics.some((d) => d.semantic === "blocking");
+		const blockingCount = diagnostics.filter(
+			(d) => d.semantic === "blocking",
+		).length;
+		try {
+			const snapshot = await extractEntitySnapshot(client, filePath, languageId);
+			const prev = entitySnapshotByFile.get(filePath);
+			const diff = diffEntitySnapshot(prev, snapshot);
+			entitySnapshotByFile.set(filePath, snapshot);
+			const changedEntityKeys = [
+				...diff.added,
+				...diff.modified,
+				...diff.removed,
+			];
+			const changedNames = [
+				...new Set(changedEntityKeys.map((k) => k.split(":")[1]).filter(Boolean)),
+			];
+
+			if (changedEntityKeys.length > 0) {
+				logTreeSitter({
+					phase: "entity_diff",
+					filePath,
+					languageId,
+					metadata: {
+						added: diff.added,
+						modified: diff.modified,
+						removed: diff.removed,
+						totalChanged: changedEntityKeys.length,
+					},
+				});
+
+				const lastBlast = blastCooldownByFile.get(filePath) ?? 0;
+				if (Date.now() - lastBlast < BLAST_COOLDOWN_MS) {
+					logTreeSitter({
+						phase: "blast_radius",
+						filePath,
+						languageId,
+						metadata: { skipped: "cooldown", cooldownMs: BLAST_COOLDOWN_MS },
+					});
+				} else {
+					blastCooldownByFile.set(filePath, Date.now());
+					const blastRadius = computeBlastRadius(changedNames, filePath, ctx.cwd);
+					logTreeSitter({
+						phase: "blast_radius",
+						filePath,
+						languageId,
+						metadata: {
+							entities: blastRadius.entities,
+							scannedFiles: blastRadius.scannedFiles,
+							scannedBytes: blastRadius.scannedBytes,
+							totalCandidates: blastRadius.totalCandidates,
+							truncated: blastRadius.truncated,
+							elapsedMs: blastRadius.elapsedMs,
+						},
+					});
+				}
+			}
+		} catch {
+			// best-effort experimental telemetry only
+		}
+
+		logTreeSitter({
+			phase: "runner_complete",
+			filePath,
+			languageId,
+			status: hasBlocking ? "failed" : "succeeded",
+			diagnostics: diagnostics.length,
+			blocking: blockingCount,
+			queryCount: languageQueries.length,
+			effectiveQueryCount: effectiveQueries.length,
+		});
 
 		return {
 			status: hasBlocking ? "failed" : "succeeded",