pi-lens 3.7.1 → 3.8.2

package/docs/COMPLEXITY_METRICS.md

@@ -0,0 +1,120 @@
+# Complexity Metrics
+
+pi-lens calculates comprehensive code quality metrics for every source file. These are used by `/lens-tdi` and shown in `/lens-booboo` reports.
+
+## Metrics Overview
+
+| Metric | Range | Description | Thresholds |
+|--------|-------|-------------|------------|
+| **Maintainability Index (MI)** | 0-100 | Composite score combining complexity, size, and structure | <20: 🔴 Unmaintainable, 20-40: 🟡 Poor, >60: ✅ Good |
+| **Cognitive Complexity** | 0+ | Human mental effort to understand code (nesting penalties) | >20: 🟡 Hard to understand, >50: 🔴 Very complex |
+| **Cyclomatic Complexity** | 1+ | Independent code paths (branch points + 1) | >10: 🟡 Complex function, >20: 🔴 Highly complex |
+| **Max Cyclomatic** | 1+ | Worst function in file | >10 flagged |
+| **Nesting Depth** | 0+ | Maximum block nesting level | >4: 🟡 Deep nesting, >6: 🔴 Excessive |
+| **Code Entropy** | 0-8+ bits | Shannon entropy — unpredictability of code patterns | >4.0: 🟡 Risky, >7.0: 🔴 Very unpredictable |
+| **Halstead Volume** | 0+ | Vocabulary × length — unique ops/operands | High = many different operations |
+
+## Formulas
+
+### Maintainability Index (Microsoft)
+
+```
+MI = max(0, (171 - 5.2*ln(Halstead) - 0.23*Cyclomatic - 16.2*ln(LOC)) * 100/171) + commentBonus
+```
+
+Where:
+- **Halstead** = Halstead Volume
+- **Cyclomatic** = Average cyclomatic complexity
+- **LOC** = Lines of code
+- **commentBonus** = up to +10% for well-commented code
+
+### Cognitive Complexity (SonarSource)
+
+- +1 for each structural node (if, for, while, case, catch, switch)
+- +1 for each level of nesting
+- +1 for each && and || in binary expressions
+- Exception: else-if chains don't add nesting
+
+### Cyclomatic Complexity (McCabe)
+
+```
+M = E - N + 2P
+```
+
+Where:
+- **E** = Number of edges in control flow graph
+- **N** = Number of nodes
+- **P** = Number of connected components (usually 1)
+
+Simplified: Count branch points + 1
+
+### Code Entropy (Shannon)
+
+```
+H = -Σ(p(i) * log2(p(i)))
+```
+
+Where:
+- **p(i)** = frequency of token i / total tokens
+
+Thresholds:
+- ≤4.0 bits: Predictable, conventional code ✅
+- 4.0-7.0 bits: Moderate complexity 🟡
+- ≥7.0 bits: Unpredictable, hard to maintain 🔴
+
+### Halstead Volume
+
+```
+V = N * log2(n)
+```
+
+Where:
+- **N** = total operators + operands (program length)
+- **n** = unique operators + operands (vocabulary size)
+
+## Technical Debt Index (TDI)
+
+The TDI provides a single score (0-100) representing overall codebase health. Lower is better.
+
+### Formula
+
+```
+TDI = MI-debt(45%) + cognitive(30%) + nesting(10%) + maxCyc(10%) + entropy(5%)
+```
+
+### Debt Calculation per Factor
+
+| Factor | Debt Formula | Good | Bad |
+|--------|---------------|------|-----|
+| **MI** | `(100 - MI) / 100` | 100 | 0 |
+| **Cognitive** | `min(1, cognitive / 200)` | 0 | ≥500 |
+| **Nesting** | `max(0, nesting - 3) / 7` | ≤3 | ≥10 |
+| **Max Cyclomatic** | `max(0, maxCyc - 10) / 20` | ≤10 | ≥30 |
+| **Entropy** | `max(0, entropy - 4.0) / 3.0` | ≤4.0 | ≥7.0 |
+
+### Grades
+
+- **A** (0-15%): Excellent codebase health
+- **B** (16-30%): Good, minor improvements possible
+- **C** (31-50%): Moderate debt, consider refactoring
+- **D** (51-70%): Significant debt, plan refactoring
+- **F** (71%+): High debt, immediate attention needed
+
+### Usage
+
+```bash
+/lens-tdi  # Display TDI score with breakdown by category
+```
+
+## AI Slop Indicators
+
+Metrics suggesting potentially AI-generated low-quality code:
+
+- **Low MI + high cognitive + high entropy** = potential spaghetti code
+- **Excessive comments (>40%) + low MI** = hand-holding anti-patterns
+- **Single-use helpers with high entropy** = over-abstraction
+- **Many small functions with high cyclomatic** = fragmented complexity
+
+**Usage:**
+- `/lens-booboo` — Shows complexity table for all files
+- `tool_result` — Complexity tracked per file, warnings inline

package/docs/EXCLUSIONS.md

@@ -0,0 +1,83 @@
+# File Exclusions
+
+pi-lens automatically excludes certain files from analysis to reduce noise.
+
+## Test Files
+
+All runners respect test file exclusions.
+
+**Excluded patterns:**
+```
+**/*.test.ts      **/*.test.tsx      **/*.test.js      **/*.test.jsx
+**/*.spec.ts      **/*.spec.tsx      **/*.spec.js      **/*.spec.jsx
+**/*.poc.test.ts  **/*.poc.test.tsx
+**/test-utils.ts  **/test-*.ts
+**/__tests__/**  **/tests/**  **/test/**
+```
+
+**Why:** Test files intentionally duplicate patterns and have different complexity standards.
+
+## Build Artifacts (Source-Filter Module)
+
+**New in 3.8.0:** pi-lens uses **sibling-file detection** via `clients/source-filter.ts` to eliminate build artifacts:
+
+**How it works:**
+- For each file, check if a "higher precedence" source sibling exists
+- If yes, skip as build artifact; if no, keep as hand-written source
+
+**Source precedence rules:**
+| Source Extension | Shadows (Excluded) |
+|------------------|-------------------|
+| `.ts` | `.js`, `.mjs`, `.cjs` |
+| `.tsx` | `.jsx`, `.js`, `.mjs`, `.cjs` |
+| `.vue` | `.js`, `.mjs` |
+| `.svelte` | `.js`, `.mjs` |
+| `.coffee` | `.js` |
+
+**Example:**
+```
+src/
+  utils.ts      ✓ Kept (source)
+  utils.js      ✗ Excluded (has .ts sibling)
+  
+  manual.js     ✓ Kept (no higher-precedence sibling)
+```
+
+**Benefits:**
+- Works in mixed TS/JS projects (pure JS files kept when no TS sibling)
+- Handles Vue/Svelte → JavaScript compilation
+- No dependency on `tsconfig.json` detection
+
+## Excluded Directories
+
+| Directory | Reason |
+|-----------|--------|
+| `node_modules/` | Third-party dependencies |
+| `.git/` | Version control metadata |
+| `dist/`, `build/` | Build outputs |
+| `.pi-lens/`, `.pi/` | pi agent internal files |
+| `.next/`, `.ruff_cache/` | Framework/build caches |
+| `coverage/` | Test coverage reports |
+
+## Per-Runner Summary
+
+| Runner | Test Files | Build Artifacts | Directories |
+|--------|-----------|-----------------|-------------|
+| **dispatch runners** | ✅ `skipTestFiles` | ✅ `isBuildArtifact()` from source-filter | ✅ `EXCLUDED_DIRS` |
+| **booboo /lens-booboo** | ✅ `shouldIncludeFile()` | ✅ `collectSourceFiles()` from source-filter | ✅ `EXCLUDED_DIRS` |
+| **Secrets scan** | ❌ No exclusion (security) | ❌ No exclusion | ✅ Dirs excluded |
+
+Secrets scanning excludes nothing — security takes precedence over noise reduction.
+
+**API:**
+```typescript
+// Check if a file is a build artifact
+import { isBuildArtifact } from "./clients/source-filter.js";
+if (isBuildArtifact("src/utils.js")) {
+  // Has src/utils.ts sibling → skip
+}
+
+// Collect deduplicated source files
+import { collectSourceFiles } from "./clients/source-filter.js";
+const files = collectSourceFiles("./src"); // No build artifacts
+```

package/docs/LSP_CONFIG.md

@@ -0,0 +1,240 @@
+# LSP Configuration Guide
+
+pi-lens supports **31 built-in LSP servers** covering most popular languages. If you need additional servers or want to customize existing ones, you can define them via configuration.
+
+## Quick Start
+
+Create `.pi-lens/lsp.json` in your project root:
+
+```json
+{
+  "servers": {
+    "graphql": {
+      "name": "GraphQL Language Server",
+      "extensions": [".graphql", ".gql"],
+      "command": "graphql-lsp",
+      "args": ["server", "--method=stream"]
+    }
+  }
+}
+```
+
+## Configuration File
+
+pi-lens looks for config in these locations (first found wins):
+
+1. `.pi-lens/lsp.json`
+2. `.pi-lens.json`  
+3. `pi-lsp.json`
+
+## Server Definition
+
+Each server requires:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Display name |
+| `extensions` | string[] | File extensions (e.g., [".rs"]) |
+| `command` | string | Executable name or path |
+| `args` | string[] | Command arguments (optional) |
+| `rootMarkers` | string[] | Files that indicate project root (optional) |
+| `env` | object | Environment variables (optional) |
+
+## Examples
+
+### GraphQL
+
+```json
+{
+  "servers": {
+    "graphql": {
+      "name": "GraphQL Language Server",
+      "extensions": [".graphql", ".gql"],
+      "command": "graphql-lsp",
+      "args": ["server", "--method=stream"]
+    }
+  }
+}
+```
+
+Install first: `npm i -g @graphql-codegen/cli graphql-language-service-cli`
+
+### Scala (Metals)
+
+```json
+{
+  "servers": {
+    "scala": {
+      "name": "Metals",
+      "extensions": [".scala", ".sc"],
+      "command": "metals",
+      "args": ["-Dmetals.http=false"],
+      "rootMarkers": ["build.sbt", ".scala-build"]
+    }
+  }
+}
+```
+
+Install first: `cs install metals`
+
+### R Language Server
+
+```json
+{
+  "servers": {
+    "r": {
+      "name": "R Language Server",
+      "extensions": [".r", ".R"],
+      "command": "R",
+      "args": ["--slave", "-e", "languageserver::run()"]
+    }
+  }
+}
+```
+
+Install first: `R -e "install.packages('languageserver')"`
+
+### Astro
+
+```json
+{
+  "servers": {
+    "astro": {
+      "name": "Astro Language Server",
+      "extensions": [".astro"],
+      "command": "astro-ls",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+Install first: `npm i -g @astrojs/language-server`
+
+## Disabling Built-in Servers
+
+To disable a built-in server (e.g., if you prefer a different one):
+
+```json
+{
+  "disabledServers": ["typescript", "eslint"]
+}
+```
+
+## Environment Variables
+
+Set custom environment for a server:
+
+```json
+{
+  "servers": {
+    "python": {
+      "name": "Pyright with venv",
+      "extensions": [".py"],
+      "command": "pyright-langserver",
+      "args": ["--stdio"],
+      "env": {
+        "PYTHONPATH": "/path/to/my/venv/lib/python3.11/site-packages"
+      }
+    }
+  }
+}
+```
+
+## Complete Example
+
+```json
+{
+  "servers": {
+    "graphql": {
+      "name": "GraphQL Language Server",
+      "extensions": [".graphql", ".gql"],
+      "command": "graphql-lsp",
+      "args": ["server", "--method=stream"],
+      "rootMarkers": [".graphqlconfig", "codegen.yml"]
+    },
+    "toml": {
+      "name": "Taplo (TOML)",
+      "extensions": [".toml"],
+      "command": "taplo",
+      "args": ["lsp", "stdio"]
+    }
+  },
+  "disabledServers": ["eslint"]
+}
+```
+
+## Auto-Installation
+
+For the **31 built-in servers**, pi-lens can auto-install via npm/pip when `--lens-lsp` is enabled:
+
+- TypeScript: `typescript-language-server`
+- Python: `pyright`
+- Vue: `@vue/language-server`
+- Svelte: `svelte-language-server`
+- And more...
+
+**Custom servers** must be installed manually before use.
+
+## Troubleshooting
+
+### Server not found
+
+Check that the command is in your PATH:
+```bash
+which graphql-lsp
+# or
+graphql-lsp --version
+```
+
+### LSP not starting
+
+Enable debug mode to see errors:
+```bash
+pi --lens-lsp --lens-verbose
+```
+
+### Root detection failing
+
+Add appropriate `rootMarkers` for your project structure:
+```json
+{
+  "rootMarkers": ["package.json", ".git", "my-project.config.js"]
+}
+```
+
+## Built-in Servers (31 Total)
+
+| Language | Server |
+|----------|--------|
+| TypeScript/JavaScript | typescript-language-server |
+| Python | pyright |
+| Go | gopls |
+| Rust | rust-analyzer |
+| Ruby | ruby-lsp |
+| PHP | intelephense |
+| C# | csharp-ls |
+| F# | fsautocomplete |
+| Java | JDTLS |
+| Kotlin | kotlin-language-server |
+| Swift | sourcekit-lsp |
+| Dart | dart |
+| Lua | lua-language-server |
+| C/C++ | clangd |
+| Zig | zls |
+| Haskell | haskell-language-server |
+| Elixir | elixir-ls |
+| Gleam | gleam |
+| OCaml | ocamllsp |
+| Clojure | clojure-lsp |
+| Terraform | terraform-ls |
+| Nix | nixd |
+| Bash | bash-language-server |
+| Docker | dockerfile-language-server |
+| YAML | yaml-language-server |
+| JSON | vscode-json-languageserver |
+| Prisma | @prisma/language-server |
+| **Vue** | @vue/language-server |
+| **Svelte** | svelte-language-server |
+| **ESLint** | vscode-eslint |
+| **CSS/SCSS** | vscode-css-languageserver |