pi-lens 2.1.1 → 2.2.1

package/CHANGELOG.md

@@ -298,6 +298,21 @@ All notable changes to pi-lens will be documented in this file.
 ### Changed
 - **Improved ast-grep tool descriptions**: Better pattern guidance to prevent overly broad searches.
 
+## [2.2.1] - 2026-03-29
+
+### Fixed
+- **No auto-install**: Runners (biome, pyright) now use direct CLI commands instead of `npx`. If not installed, gracefully skip instead of attempting to download.
+
+## [2.2.0] - 2026-03-29
+
+### Added
+- **`/lens-rate` command**: Visual code quality scoring across 6 dimensions (Type Safety, Complexity, Security, Architecture, Dead Code, Tests). Shows grade A-F and colored progress bars.
+- **Pyright runner**: Real Python type-checking via pyright. Catches type errors like `result: str = add(1, 2)` that ruff misses. Runs alongside ruff (pyright for types, ruff for linting).
+- **Vitest config**: Increased test timeout to 15s for CLI spawn tests. Fixes flaky test failures when npx downloads packages.
+
+### Fixed
+- **Test flakiness**: Availability tests (biome, knip, jscpd) no longer timeout when npx is downloading packages.
+
 ## [1.3.0] - 2026-03-23
 
 ### Changed

package/README.md

@@ -16,6 +16,43 @@ pi install git:github.com/apmantza/pi-lens
 
 ---
 
+## What's New (v2.2)
+
+### `/lens-rate` — Code Quality Scoring
+
+Visual scoring breakdown across 6 dimensions with grade A-F:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  📊 CODE QUALITY SCORE: 85/100 (B)                      │
+├─────────────────────────────────────────────────────────┤
+│  🔷 Type Safety  🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜  85 │
+│  🧩 Complexity   🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜  82 │
+│  🔒 Security     🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 100 │
+│  🏗️ Architecture  🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜  80 │
+│  🗑️ Dead Code    🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜  90 │
+│  ✅ Tests        🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 100 │
+└─────────────────────────────────────────────────────────┘
+```
+
+Scores are calculated from real scan data: type-coverage, complexity metrics, secret detection, architect rules, knip, and test results.
+
+### Python Type-Checking (Pyright)
+
+Python files now get **real type-checking** via pyright, not just linting:
+
+```python
+# ruff won't catch this, but pyright will:
+def add(x: int, y: int) -> int:
+    return x + y
+
+result: str = add(1, 2)  # ❌ pyright: Type "int" not assignable to "str"
+```
+
+Pyright runs alongside ruff — pyright catches type errors, ruff catches style issues.
+
+---
+
 ## What's New (v2.1)
 
 ### Content-Level Secret Scanning
@@ -358,6 +395,7 @@ Each rule includes a `message` and `note` that are shown in diagnostics, so the
 | `type-coverage` | `npm i -D type-coverage` | TypeScript `any` coverage percentage |
 | `madge` | `npm i -D madge` | Circular dependency detection |
 | `ruff` | `pip install ruff` | Python lint + format + autofix |
+| `pyright` | `pip install pyright` or `npm i -g pyright` | Python type-checking (optional, graceful skip if not installed) |
 
 ---
 

package/clients/dispatch/runners/biome.js

@@ -1,27 +1,38 @@
 /**
  * Biome runner for dispatch system
+ *
+ * Requires: @biomejs/biome (npm install -D @biomejs/biome)
  */
 import { spawnSync } from "node:child_process";
+// Cache biome availability check
+let biomeAvailable = null;
+function isBiomeAvailable() {
+    if (biomeAvailable !== null)
+        return biomeAvailable;
+    // Check if biome CLI is available (do NOT auto-install via npx)
+    const check = spawnSync("biome", ["--version"], {
+        encoding: "utf-8",
+        timeout: 5000,
+        shell: true,
+    });
+    biomeAvailable = !check.error && check.status === 0;
+    return biomeAvailable;
+}
 const biomeRunner = {
     id: "biome-lint",
     appliesTo: ["jsts", "json"],
     priority: 10,
     enabledByDefault: true,
     async run(ctx) {
-        // Check if biome is available
-        const check = spawnSync("npx", ["@biomejs/biome", "--version"], {
-            encoding: "utf-8",
-            timeout: 5000,
-            shell: true,
-        });
-        if (check.error || check.status !== 0) {
+        // Skip if biome is not installed
+        if (!isBiomeAvailable()) {
             return { status: "skipped", diagnostics: [], semantic: "none" };
         }
-        // Run biome check
+        // Run biome check (use direct command, not npx)
         const args = ctx.autofix
             ? ["check", "--write", ctx.filePath]
             : ["check", ctx.filePath];
-        const result = spawnSync("npx", ["@biomejs/biome", ...args], {
+        const result = spawnSync("biome", args, {
             encoding: "utf-8",
             timeout: 30000,
             shell: true,

package/clients/dispatch/runners/biome.ts

@@ -1,5 +1,7 @@
 /**
  * Biome runner for dispatch system
+ *
+ * Requires: @biomejs/biome (npm install -D @biomejs/biome)
  */
 
 import { spawnSync } from "node:child_process";
@@ -10,6 +12,22 @@ import type {
 	RunnerResult,
 } from "../types.js";
 
+// Cache biome availability check
+let biomeAvailable: boolean | null = null;
+
+function isBiomeAvailable(): boolean {
+	if (biomeAvailable !== null) return biomeAvailable;
+
+	// Check if biome CLI is available (do NOT auto-install via npx)
+	const check = spawnSync("biome", ["--version"], {
+		encoding: "utf-8",
+		timeout: 5000,
+		shell: true,
+	});
+	biomeAvailable = !check.error && check.status === 0;
+	return biomeAvailable;
+}
+
 const biomeRunner: RunnerDefinition = {
 	id: "biome-lint",
 	appliesTo: ["jsts", "json"],
@@ -17,23 +35,17 @@ const biomeRunner: RunnerDefinition = {
 	enabledByDefault: true,
 
 	async run(ctx: DispatchContext): Promise<RunnerResult> {
-		// Check if biome is available
-		const check = spawnSync("npx", ["@biomejs/biome", "--version"], {
-			encoding: "utf-8",
-			timeout: 5000,
-			shell: true,
-		});
-
-		if (check.error || check.status !== 0) {
+		// Skip if biome is not installed
+		if (!isBiomeAvailable()) {
 			return { status: "skipped", diagnostics: [], semantic: "none" };
 		}
 
-		// Run biome check
+		// Run biome check (use direct command, not npx)
 		const args = ctx.autofix
 			? ["check", "--write", ctx.filePath]
 			: ["check", ctx.filePath];
 
-		const result = spawnSync("npx", ["@biomejs/biome", ...args], {
+		const result = spawnSync("biome", args, {
 			encoding: "utf-8",
 			timeout: 30000,
 			shell: true,

package/clients/dispatch/runners/index.js

@@ -7,12 +7,14 @@ import architectRunner from "./architect.js";
 import astGrepRunner from "./ast-grep.js";
 import biomeRunner from "./biome.js";
 import goVetRunner from "./go-vet.js";
+import pyrightRunner from "./pyright.js";
 import ruffRunner from "./ruff.js";
 import rustClippyRunner from "./rust-clippy.js";
 import tsLspRunner from "./ts-lsp.js";
 import typeSafetyRunner from "./type-safety.js";
 // Register all runners (ordered by priority)
-registerRunner(tsLspRunner);
+registerRunner(tsLspRunner); // TypeScript type-checking
+registerRunner(pyrightRunner); // Python type-checking
 registerRunner(biomeRunner);
 registerRunner(ruffRunner);
 registerRunner(typeSafetyRunner);

package/clients/dispatch/runners/index.ts

@@ -8,13 +8,15 @@ import architectRunner from "./architect.js";
 import astGrepRunner from "./ast-grep.js";
 import biomeRunner from "./biome.js";
 import goVetRunner from "./go-vet.js";
+import pyrightRunner from "./pyright.js";
 import ruffRunner from "./ruff.js";
 import rustClippyRunner from "./rust-clippy.js";
 import tsLspRunner from "./ts-lsp.js";
 import typeSafetyRunner from "./type-safety.js";
 
 // Register all runners (ordered by priority)
-registerRunner(tsLspRunner);
+registerRunner(tsLspRunner); // TypeScript type-checking
+registerRunner(pyrightRunner); // Python type-checking
 registerRunner(biomeRunner);
 registerRunner(ruffRunner);
 registerRunner(typeSafetyRunner);

package/clients/dispatch/runners/pyright.js

@@ -0,0 +1,88 @@
+/**
+ * Pyright runner for dispatch system
+ *
+ * Provides real Python type-checking (not just linting).
+ * Catches type errors like: result: str = add(1, 2)  # Type "int" not assignable to "str"
+ *
+ * Requires: pyright (pip install pyright or npm install -g pyright)
+ */
+import { spawnSync } from "node:child_process";
+// Cache pyright availability check
+let pyrightAvailable = null;
+function isPyrightAvailable() {
+    if (pyrightAvailable !== null)
+        return pyrightAvailable;
+    // Check if pyright CLI is available (do NOT auto-install via npx)
+    const check = spawnSync("pyright", ["--version"], {
+        encoding: "utf-8",
+        timeout: 5000,
+        shell: true,
+    });
+    pyrightAvailable = !check.error && check.status === 0;
+    return pyrightAvailable;
+}
+const pyrightRunner = {
+    id: "pyright",
+    appliesTo: ["python"],
+    priority: 5, // Higher priority than ruff (10) - type errors are more important
+    enabledByDefault: true,
+    async run(ctx) {
+        // Skip if pyright is not installed
+        if (!isPyrightAvailable()) {
+            return { status: "skipped", diagnostics: [], semantic: "none" };
+        }
+        // Run pyright with JSON output (use direct command, not npx)
+        const result = spawnSync("pyright", ["--outputjson", ctx.filePath], {
+            encoding: "utf-8",
+            timeout: 60000,
+            shell: true,
+        });
+        // Pyright returns non-zero when errors found, that's OK
+        if (result.error) {
+            return { status: "skipped", diagnostics: [], semantic: "none" };
+        }
+        const output = (result.stdout || "").trim();
+        if (!output) {
+            return { status: "succeeded", diagnostics: [], semantic: "none" };
+        }
+        try {
+            const data = JSON.parse(output);
+            const diagnostics = parsePyrightOutput(data, ctx.filePath);
+            if (diagnostics.length === 0) {
+                return { status: "succeeded", diagnostics: [], semantic: "none" };
+            }
+            const hasErrors = diagnostics.some((d) => d.severity === "error");
+            return {
+                status: hasErrors ? "failed" : "succeeded",
+                diagnostics,
+                semantic: "warning",
+            };
+        }
+        catch {
+            // JSON parse failed, skip
+            return { status: "skipped", diagnostics: [], semantic: "none" };
+        }
+    },
+};
+function parsePyrightOutput(data, filePath) {
+    if (!data.generalDiagnostics)
+        return [];
+    return data.generalDiagnostics
+        .filter((d) => {
+        // Only include errors and warnings, skip informational
+        return d.severity === "error" || d.severity === "warning";
+    })
+        .map((d) => ({
+        id: `pyright-${d.range.start.line}-${d.rule}`,
+        message: d.message.split("\n")[0], // First line only (pyright has multi-line messages)
+        filePath,
+        line: d.range.start.line + 1, // Pyright is 0-indexed, we're 1-indexed
+        column: d.range.start.character + 1,
+        severity: d.severity === "error" ? "error" : "warning",
+        semantic: d.severity === "error" ? "blocking" : "warning",
+        tool: "pyright",
+        rule: d.rule,
+        fixable: false, // Pyright can't auto-fix, only suggest
+    }));
+}
+export default pyrightRunner;

package/clients/dispatch/runners/pyright.test.js

@@ -0,0 +1,84 @@
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { describe, expect, it } from "vitest";
+function createMockContext(filePath) {
+    return {
+        filePath,
+        cwd: process.cwd(),
+        kind: "python",
+        autofix: false,
+        deltaMode: false,
+        baselines: { get: () => [], add: () => { }, save: () => { } },
+        pi: {},
+        hasTool: async () => false,
+        log: () => { },
+    };
+}
+describe("pyright runner", () => {
+    const require = createRequire(import.meta.url);
+    it("should have correct runner definition", async () => {
+        const pyrightModule = await import("./pyright.js");
+        const runner = pyrightModule.default;
+        expect(runner.id).toBe("pyright");
+        expect(runner.appliesTo).toEqual(["python"]);
+        expect(runner.priority).toBe(5); // Higher priority than ruff
+        expect(runner.enabledByDefault).toBe(true);
+    });
+    it("should detect pyright availability", () => {
+        const { spawnSync } = require("node:child_process");
+        const result = spawnSync("npx", ["pyright", "--version"], {
+            encoding: "utf-8",
+            timeout: 10000,
+            shell: true,
+        });
+        expect(result.error || result.status !== 0 ? "not available" : "available").toBe("available");
+    });
+    it("should type-check Python files and find errors", async () => {
+        const tmpFile = path.join(process.env.TEMP || "/tmp", `pyright_test_${Date.now()}.py`);
+        fs.writeFileSync(tmpFile, `def add(x: int, y: int) -> int:
+    return x + y
+
+result: str = add(1, 2)
+
+def greet(name: str) -> str:
+    return "Hello " + name
+
+greet(123)
+`);
+        try {
+            const pyrightModule = await import("./pyright.js");
+            const runner = pyrightModule.default;
+            const result = await runner.run(createMockContext(tmpFile));
+            expect(result.diagnostics.length).toBeGreaterThanOrEqual(2);
+            expect(result.diagnostics.some((d) => d.tool === "pyright")).toBe(true);
+            expect(result.diagnostics.some((d) => d.severity === "error")).toBe(true);
+        }
+        finally {
+            fs.unlinkSync(tmpFile);
+        }
+    });
+    it("should pass valid Python files", async () => {
+        const tmpFile = path.join(process.env.TEMP || "/tmp", `pyright_test_ok_${Date.now()}.py`);
+        fs.writeFileSync(tmpFile, `def add(x: int, y: int) -> int:
+    return x + y
+
+result: str = str(add(1, 2))
+
+def greet(name: str) -> str:
+    return "Hello " + name
+
+greet("world")
+`);
+        try {
+            const pyrightModule = await import("./pyright.js");
+            const runner = pyrightModule.default;
+            const result = await runner.run(createMockContext(tmpFile));
+            expect(result.status).toBe("succeeded");
+            expect(result.diagnostics.length).toBe(0);
+        }
+        finally {
+            fs.unlinkSync(tmpFile);
+        }
+    });
+});

package/clients/dispatch/runners/pyright.test.ts

@@ -0,0 +1,109 @@
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { describe, expect, it } from "vitest";
+import type { DispatchContext } from "../types.js";
+
+function createMockContext(filePath: string): DispatchContext {
+	return {
+		filePath,
+		cwd: process.cwd(),
+		kind: "python" as any,
+		autofix: false,
+		deltaMode: false,
+		baselines: { get: () => [], add: () => {}, save: () => {} } as any,
+		pi: {} as any,
+		hasTool: async () => false,
+		log: () => {},
+	};
+}
+
+describe("pyright runner", () => {
+	const require = createRequire(import.meta.url);
+
+	it("should have correct runner definition", async () => {
+		const pyrightModule = await import("./pyright.js");
+		const runner = pyrightModule.default;
+
+		expect(runner.id).toBe("pyright");
+		expect(runner.appliesTo).toEqual(["python"]);
+		expect(runner.priority).toBe(5); // Higher priority than ruff
+		expect(runner.enabledByDefault).toBe(true);
+	});
+
+	it("should detect pyright availability", () => {
+		const { spawnSync } =
+			require("node:child_process") as typeof import("node:child_process");
+		const result = spawnSync("npx", ["pyright", "--version"], {
+			encoding: "utf-8",
+			timeout: 10000,
+			shell: true,
+		});
+		expect(
+			result.error || result.status !== 0 ? "not available" : "available",
+		).toBe("available");
+	});
+
+	it("should type-check Python files and find errors", async () => {
+		const tmpFile = path.join(
+			process.env.TEMP || "/tmp",
+			`pyright_test_${Date.now()}.py`,
+		);
+		fs.writeFileSync(
+			tmpFile,
+			`def add(x: int, y: int) -> int:
+    return x + y
+
+result: str = add(1, 2)
+
+def greet(name: str) -> str:
+    return "Hello " + name
+
+greet(123)
+`,
+		);
+
+		try {
+			const pyrightModule = await import("./pyright.js");
+			const runner = pyrightModule.default;
+			const result = await runner.run(createMockContext(tmpFile));
+
+			expect(result.diagnostics.length).toBeGreaterThanOrEqual(2);
+			expect(result.diagnostics.some((d) => d.tool === "pyright")).toBe(true);
+			expect(result.diagnostics.some((d) => d.severity === "error")).toBe(true);
+		} finally {
+			fs.unlinkSync(tmpFile);
+		}
+	});
+
+	it("should pass valid Python files", async () => {
+		const tmpFile = path.join(
+			process.env.TEMP || "/tmp",
+			`pyright_test_ok_${Date.now()}.py`,
+		);
+		fs.writeFileSync(
+			tmpFile,
+			`def add(x: int, y: int) -> int:
+    return x + y
+
+result: str = str(add(1, 2))
+
+def greet(name: str) -> str:
+    return "Hello " + name
+
+greet("world")
+`,
+		);
+
+		try {
+			const pyrightModule = await import("./pyright.js");
+			const runner = pyrightModule.default;
+			const result = await runner.run(createMockContext(tmpFile));
+
+			expect(result.status).toBe("succeeded");
+			expect(result.diagnostics.length).toBe(0);
+		} finally {
+			fs.unlinkSync(tmpFile);
+		}
+	});
+});

package/clients/dispatch/runners/pyright.ts

@@ -0,0 +1,125 @@
+/**
+ * Pyright runner for dispatch system
+ *
+ * Provides real Python type-checking (not just linting).
+ * Catches type errors like: result: str = add(1, 2)  # Type "int" not assignable to "str"
+ *
+ * Requires: pyright (pip install pyright or npm install -g pyright)
+ */
+
+import { spawnSync } from "node:child_process";
+import type {
+	Diagnostic,
+	DispatchContext,
+	RunnerDefinition,
+	RunnerResult,
+} from "../types.js";
+
+// Cache pyright availability check
+let pyrightAvailable: boolean | null = null;
+
+function isPyrightAvailable(): boolean {
+	if (pyrightAvailable !== null) return pyrightAvailable;
+
+	// Check if pyright CLI is available (do NOT auto-install via npx)
+	const check = spawnSync("pyright", ["--version"], {
+		encoding: "utf-8",
+		timeout: 5000,
+		shell: true,
+	});
+	pyrightAvailable = !check.error && check.status === 0;
+	return pyrightAvailable;
+}
+
+const pyrightRunner: RunnerDefinition = {
+	id: "pyright",
+	appliesTo: ["python"],
+	priority: 5, // Higher priority than ruff (10) - type errors are more important
+	enabledByDefault: true,
+
+	async run(ctx: DispatchContext): Promise<RunnerResult> {
+		// Skip if pyright is not installed
+		if (!isPyrightAvailable()) {
+			return { status: "skipped", diagnostics: [], semantic: "none" };
+		}
+
+		// Run pyright with JSON output (use direct command, not npx)
+		const result = spawnSync("pyright", ["--outputjson", ctx.filePath], {
+			encoding: "utf-8",
+			timeout: 60000,
+			shell: true,
+		});
+
+		// Pyright returns non-zero when errors found, that's OK
+		if (result.error) {
+			return { status: "skipped", diagnostics: [], semantic: "none" };
+		}
+
+		const output = (result.stdout || "").trim();
+		if (!output) {
+			return { status: "succeeded", diagnostics: [], semantic: "none" };
+		}
+
+		try {
+			const data = JSON.parse(output);
+			const diagnostics = parsePyrightOutput(data, ctx.filePath);
+
+			if (diagnostics.length === 0) {
+				return { status: "succeeded", diagnostics: [], semantic: "none" };
+			}
+
+			const hasErrors = diagnostics.some((d) => d.severity === "error");
+
+			return {
+				status: hasErrors ? "failed" : "succeeded",
+				diagnostics,
+				semantic: "warning",
+			};
+		} catch {
+			// JSON parse failed, skip
+			return { status: "skipped", diagnostics: [], semantic: "none" };
+		}
+	},
+};
+
+interface PyrightDiagnostic {
+	file: string;
+	severity: "error" | "warning" | "information";
+	message: string;
+	range: {
+		start: { line: number; character: number };
+		end: { line: number; character: number };
+	};
+	rule: string;
+}
+
+interface PyrightResult {
+	generalDiagnostics: PyrightDiagnostic[];
+}
+
+function parsePyrightOutput(
+	data: PyrightResult,
+	filePath: string,
+): Diagnostic[] {
+	if (!data.generalDiagnostics) return [];
+
+	return data.generalDiagnostics
+		.filter((d) => {
+			// Only include errors and warnings, skip informational
+			return d.severity === "error" || d.severity === "warning";
+		})
+		.map((d) => ({
+			id: `pyright-${d.range.start.line}-${d.rule}`,
+			message: d.message.split("\n")[0], // First line only (pyright has multi-line messages)
+			filePath,
+			line: d.range.start.line + 1, // Pyright is 0-indexed, we're 1-indexed
+			column: d.range.start.character + 1,
+			severity: d.severity === "error" ? "error" : "warning",
+			semantic: d.severity === "error" ? "blocking" : "warning",
+			tool: "pyright",
+			rule: d.rule,
+			fixable: false, // Pyright can't auto-fix, only suggest
+		}));
+}
+
+export default pyrightRunner;