pi-lens 1.1.0

package/README.md

@@ -0,0 +1,152 @@
+# pi-lens
+
+Real-time code quality feedback for [pi](https://github.com/mariozechner/pi-coding-agent). Every write and edit is automatically analysed — diagnostics are injected directly into the tool result so the agent sees them without any extra steps.
+
+---
+
+## Features
+
+### On every write / edit
+
+| Tool | What it checks |
+|---|---|
+| **TypeScript LSP** | Type errors and warnings, using the project's `tsconfig.json` (walks up from the file to find it; falls back to `ES2020 + DOM` defaults) |
+| **ast-grep** | 60+ structural rules: `no-var`, `no-eval`, `no-debugger`, `no-as-any`, `prefer-template`, `no-throw-string`, `no-hardcoded-secrets`, `no-return-await`, nested ternaries, strict equality, and more |
+| **Biome** | Lint + format for JS/TS/JSX/TSX/CSS/JSON. Auto-fixes on every write by default |
+| **Ruff** | Lint + format for Python. Auto-fixes on every write by default |
+
+### Pre-write hints
+
+Before every write or edit to an existing file, the agent sees a summary of what's already broken:
+
+```
+⚠ Pre-write: file already has 5 TypeScript error(s) — fix before adding more
+⚠ Pre-write: file already has 9 Biome issue(s)
+⚠ Pre-write: file already has 8 structural violations
+```
+
+Prevents piling new errors on top of existing ones.
+
+### Session start summary (injected into first tool result)
+
+On every new session, the following scans run against the whole project and are delivered once into the first tool result:
+
+| Tool | What it reports |
+|---|---|
+| **TODO scanner** | All TODO / FIXME / HACK / BUG / DEPRECATED annotations, sorted by severity |
+| **Knip** | Unused exports, types, and unlisted dependencies |
+| **jscpd** | Duplicate code blocks — file, line, size, percentage of codebase |
+| **type-coverage** | Percentage of identifiers properly typed; lists exact locations of `any` |
+
+Example:
+
+```
+[Session Start]
+[TODOs] 3 annotation(s) found (2 FIXME, 1 TODO):
+  🔴 src/auth.ts:42 — FIXME: token refresh not implemented
+  🟠 src/parser.ts:17 — HACK: bypassing validation
+  📝 src/api.ts:88 — TODO: add rate limiting
+
+[Knip] 2 issue(s) — 2 unused export(s):
+  Unused exports:
+    - legacyFormat (utils.ts)
+    - oldParser (parser.ts)
+
+[jscpd] 2 duplicate block(s) — 1.2% of codebase (47/3920 lines):
+  16 lines — openrouter.ts:183 ↔ openrouter.ts:135
+  11 lines — cline-auth.ts:51 ↔ kilo-auth.ts:9
+
+[type-coverage] ⚠ 94.3% typed (3870/4107 identifiers):
+  auth.ts:138:44 — undefined as any
+  config.ts:52:12 — err
+  ... and 12 more
+```
+
+### On-demand commands
+
+| Command | Description |
+|---|---|
+| `/find-todos [path]` | Scan for TODO/FIXME/HACK annotations |
+| `/dead-code` | Find unused exports/files/dependencies (requires knip) |
+| `/check-deps` | Circular dependency scan (requires madge) |
+| `/format [file\|--all]` | Apply Biome formatting |
+
+---
+
+## Installation
+
+```bash
+# Core (required for JS/TS feedback)
+npm install -D @biomejs/biome @ast-grep/cli
+
+# Dead code + duplicate detection + type coverage (highly recommended)
+npm install -D knip jscpd type-coverage
+
+# Circular dependency detection
+npm install -D madge
+
+# Python support
+pip install ruff
+```
+
+---
+
+## Flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--autofix-biome` | **`true`** | Auto-fix Biome lint/format issues on every write |
+| `--autofix-ruff` | **`true`** | Auto-fix Ruff issues on every write |
+| `--no-biome` | `false` | Disable Biome |
+| `--no-ast-grep` | `false` | Disable ast-grep |
+| `--no-ruff` | `false` | Disable Ruff |
+| `--no-lsp` | `false` | Disable TypeScript LSP |
+| `--lens-verbose` | `false` | Enable verbose logging |
+
+---
+
+## ast-grep rules
+
+Rules live in `rules/ast-grep-rules/rules/`. All rules are YAML files you can edit or extend.
+
+**Security**
+`no-eval`, `no-implied-eval`, `no-hardcoded-secrets`, `no-insecure-randomness`, `no-open-redirect`, `no-sql-in-code`, `no-inner-html`, `no-dangerously-set-inner-html`, `no-javascript-url`
+
+**TypeScript**
+`no-any-type`, `no-as-any`, `no-non-null-assertion`
+
+**Style**
+`no-var`, `prefer-const`, `prefer-template`, `no-useless-concat`, `prefer-nullish-coalescing`, `prefer-optional-chain`, `nested-ternary`, `no-lonely-if`
+
+**Correctness**
+`no-debugger`, `no-throw-string`, `no-return-await`, `no-await-in-loop`, `no-await-in-promise-all`, `require-await`, `empty-catch`, `strict-equality`, `strict-inequality`
+
+**Patterns**
+`no-console-log`, `no-alert`, `no-delete-operator`, `no-shadow`, `no-star-imports`, `switch-needs-default`
+
+---
+
+## External dependencies summary
+
+| Package | Install | Purpose |
+|---|---|---|
+| `@biomejs/biome` | `npm i -D @biomejs/biome` | JS/TS/CSS/JSON lint + format + autofix |
+| `@ast-grep/cli` | `npm i -D @ast-grep/cli` | 60+ structural pattern rules |
+| `knip` | `npm i -D knip` | Unused exports, types, unlisted deps |
+| `jscpd` | `npm i -D jscpd` | Copy-paste / duplicate code detection |
+| `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 |
+
+---
+
+## TypeScript LSP — tsconfig detection
+
+The LSP walks up from the edited file's directory until it finds a `tsconfig.json`. If found, it uses that project's exact `compilerOptions` (paths, strict settings, lib, etc.). If not found, it falls back to sensible defaults:
+
+- `target: ES2020`
+- `lib: ["es2020", "dom", "dom.iterable"]`
+- `moduleResolution: bundler`
+- `strict: true`
+
+The compiler options are refreshed automatically when you switch between projects within a session.

package/clients/ast-grep-client.ts

@@ -0,0 +1,254 @@
+/**
+ * AstGrep Client for pi-lens
+ *
+ * Structural code analysis using ast-grep CLI.
+ * Scans files against YAML rule definitions.
+ *
+ * Requires: npm install -D @ast-grep/cli
+ * Rules: ./rules/ directory
+ */
+
+import { spawnSync } from "node:child_process";
+import * as path from "node:path";
+import * as fs from "node:fs";
+
+// --- Types ---
+
+export interface AstGrepDiagnostic {
+  line: number;
+  column: number;
+  endLine: number;
+  endColumn: number;
+  severity: "error" | "warning" | "info" | "hint";
+  message: string;
+  rule: string;
+  file: string;
+  fix?: string;
+}
+
+// New ast-grep JSON format
+interface AstGrepJsonDiagnostic {
+  ruleId: string;
+  severity: string;
+  message: string;
+  note?: string;
+  labels: Array<{
+    text: string;
+    range: {
+      start: { line: number; column: number };
+      end: { line: number; column: number };
+    };
+    file?: string;
+    style: string;
+  }>;
+  // Legacy format support
+  Message?: { text: string };
+  Severity?: string;
+  spans?: Array<{
+    context: string;
+    range: {
+      start: { line: number; column: number };
+      end: { line: number; column: number };
+    };
+    file: string;
+  }>;
+  name?: string;
+}
+
+// --- Client ---
+
+export class AstGrepClient {
+  private available: boolean | null = null;
+  private ruleDir: string;
+  private log: (msg: string) => void;
+
+  constructor(ruleDir?: string, verbose = false) {
+    this.ruleDir = ruleDir || path.join(typeof __dirname !== "undefined" ? __dirname : ".", "..", "rules");
+    this.log = verbose
+      ? (msg: string) => console.log(`[ast-grep] ${msg}`)
+      : () => {};
+    try {
+      const nodeFs2 = require("node:fs") as typeof import("node:fs");
+      nodeFs2.appendFileSync("C:/Users/R3LiC/Desktop/pi-lens-debug.log",
+        `[${new Date().toISOString()}] AstGrepClient constructed, __dirname=${typeof __dirname !== "undefined" ? __dirname : "undefined"}, ruleDir=${this.ruleDir}\n`);
+    } catch {}
+  }
+
+  /**
+   * Check if ast-grep CLI is available
+   */
+  isAvailable(): boolean {
+    if (this.available !== null) return this.available;
+
+    const result = spawnSync("npx", ["sg", "--version"], {
+      encoding: "utf-8",
+      timeout: 10000,
+      shell: true,
+    });
+
+    this.available = !result.error && result.status === 0;
+    if (this.available) {
+      this.log("ast-grep available");
+    }
+
+    return this.available;
+  }
+
+  /**
+   * Scan a file against all rules
+   */
+  scanFile(filePath: string): AstGrepDiagnostic[] {
+    if (!this.isAvailable()) return [];
+
+    const absolutePath = path.resolve(filePath);
+    if (!fs.existsSync(absolutePath)) return [];
+
+    const configPath = path.join(this.ruleDir, ".sgconfig.yml");
+
+    try {
+      const result = spawnSync("npx", [
+        "sg",
+        "scan",
+        "--config", configPath,
+        "--json",
+        absolutePath,
+      ], {
+        encoding: "utf-8",
+        timeout: 15000,
+        shell: true,
+      });
+
+      // ast-grep exits 1 when it finds issues
+      const output = result.stdout || result.stderr || "";
+      if (!output.trim()) return [];
+
+      return this.parseOutput(output, absolutePath);
+    } catch (err: any) {
+      this.log(`Scan error: ${err.message}`);
+      return [];
+    }
+  }
+
+  /**
+   * Format diagnostics for LLM consumption
+   */
+  formatDiagnostics(diags: AstGrepDiagnostic[]): string {
+    if (diags.length === 0) return "";
+
+    const errors = diags.filter(d => d.severity === "error");
+    const warnings = diags.filter(d => d.severity === "warning");
+
+    let output = `[ast-grep] ${diags.length} structural issue(s)`;
+    if (errors.length) output += ` — ${errors.length} error(s)`;
+    if (warnings.length) output += ` — ${warnings.length} warning(s)`;
+    output += ":\n";
+
+    for (const d of diags.slice(0, 15)) {
+      const loc = d.line === d.endLine
+        ? `L${d.line}`
+        : `L${d.line}-${d.endLine}`;
+      const fix = d.fix ? " [fixable]" : "";
+      output += `  [${d.rule}] ${loc} ${d.message}${fix}\n`;
+    }
+
+    if (diags.length > 15) {
+      output += `  ... and ${diags.length - 15} more\n`;
+    }
+
+    return output;
+  }
+
+  // --- Internal ---
+
+  private parseOutput(output: string, filterFile: string): AstGrepDiagnostic[] {
+    const diagnostics: AstGrepDiagnostic[] = [];
+    const resolvedFilterFile = path.resolve(filterFile);
+
+    // Try parsing as JSON array first (new format)
+    try {
+      const items: AstGrepJsonDiagnostic[] = JSON.parse(output);
+      if (Array.isArray(items)) {
+        for (const item of items) {
+          const diag = this.parseDiagnostic(item, resolvedFilterFile);
+          if (diag) diagnostics.push(diag);
+        }
+        return diagnostics;
+      }
+    } catch {
+      // Not a JSON array, try ndjson format (legacy)
+    }
+
+    // Parse ndjson (one JSON object per line) - legacy format
+    const lines = output.split("\n").filter(l => l.trim());
+
+    for (const line of lines) {
+      try {
+        const item: AstGrepJsonDiagnostic = JSON.parse(line);
+        const diag = this.parseDiagnostic(item, resolvedFilterFile);
+        if (diag) diagnostics.push(diag);
+      } catch {
+        // Skip unparseable lines
+      }
+    }
+
+    return diagnostics;
+  }
+
+  private parseDiagnostic(item: AstGrepJsonDiagnostic, filterFile: string): AstGrepDiagnostic | null {
+    // New format uses labels array
+    if (item.labels && item.labels.length > 0) {
+      const label = item.labels.find(l => l.style === "primary") || item.labels[0];
+      const filePath = path.resolve(label.file || filterFile);
+
+      // Filter to our file
+      if (filePath !== filterFile) return null;
+
+      const start = label.range?.start || { line: 0, column: 0 };
+      const end = label.range?.end || start;
+
+      return {
+        line: start.line + 1, // ast-grep is 0-indexed, we want 1-indexed
+        column: start.column,
+        endLine: end.line + 1,
+        endColumn: end.column,
+        severity: this.mapSeverity(item.severity),
+        message: item.message || "Unknown issue",
+        rule: item.ruleId || "unknown",
+        file: filePath,
+      };
+    }
+
+    // Legacy format uses spans array
+    if (item.spans && item.spans.length > 0) {
+      const span = item.spans[0];
+      const filePath = path.resolve(span.file || filterFile);
+
+      // Filter to our file
+      if (filePath !== filterFile) return null;
+
+      const start = span.range?.start || { line: 0, column: 0 };
+      const end = span.range?.end || start;
+
+      return {
+        line: start.line + 1,
+        column: start.column,
+        endLine: end.line + 1,
+        endColumn: end.column,
+        severity: this.mapSeverity(item.severity || item.Severity || "warning"),
+        message: item.Message?.text || item.message || "Unknown issue",
+        rule: item.name || item.ruleId || "unknown",
+        file: filePath,
+      };
+    }
+
+    return null;
+  }
+
+  private mapSeverity(severity: string): AstGrepDiagnostic["severity"] {
+    const lower = severity.toLowerCase();
+    if (lower === "error") return "error";
+    if (lower === "warning") return "warning";
+    if (lower === "info") return "info";
+    return "hint";
+  }
+}