pi-lens 3.8.73 → 4.0.0

package/docs/settings.md

@@ -0,0 +1,192 @@
+# Settings
+
+How pi-lens is configured, and what you can change. This page is the overview
+hub. For the full per-field docs of the config JSON, see the
+[Configuration reference](./globalconfig.md); for the complete environment-variable
+reference, see [Environment variables](./environment-variables.md); for the CLI
+flags in context, see [Usage](./usage.md).
+
+pi-lens ships with sensible defaults, so **zero configuration is needed** — it
+works out of the box. Everything below is optional tuning.
+
+## The three ways to configure pi-lens
+
+1. **Environment variables** (`PI_LENS_*`) — read at process start; set them in
+   the shell that launches pi, your process manager, or CI. Best for machine- or
+   CI-scoped switches and for the handful of tuning knobs that have no config key.
+2. **CLI flags** (`--no-lsp`, `--immediate-format`, …) — per-session, passed on
+   the pi command line.
+3. **Config JSON** — a per-user global file (`~/.pi-lens/config.json`) and an
+   optional per-project file (`.pi-lens.json` at the repo root).
+
+Every runtime toggle is settable **both** from the CLI and from `config.json`;
+the two surfaces are driven by one declarative registry
+(`clients/lens-flag-registry.ts`), so neither can gain a toggle the other lacks.
+
+## Precedence
+
+For a single toggle, highest priority first:
+
+1. **Environment variable**, for the toggles that have one bound (only
+   `PI_LENS_NO_CONTEXT_INJECTION` today).
+2. **CLI flag**.
+3. **Nearest project `.pi-lens.json`** that defines the key — for the three
+   project-scoped mutation controls only (`format.enabled`, `autofix.enabled`,
+   `actionableWarnings.autoFix.enabled`). In a monorepo the closest config to the
+   edited file wins.
+4. **Global `~/.pi-lens/config.json`**.
+5. **Built-in default**.
+
+**The `--no-*` one-way rule.** Config keys are positive (`"enabled": true` means
+the feature runs), so a `--no-*` flag corresponds to setting its key `false`. A
+`--no-*` flag on the command line is a *one-way switch*: it can disable but never
+re-enable. `--no-lsp` overrides `lsp.enabled: true`, but nothing on the CLI
+overrides `lsp.enabled: false`. To re-enable, set the config key back to `true`.
+
+## Defaults at a glance
+
+### Runtime toggles (flags)
+
+Each is settable via the CLI flag *or* the `config.json` key. The **Default**
+column is the effective behavior when nothing is set.
+
+| CLI flag | `config.json` key | Scope | Default |
+| --- | --- | --- | --- |
+| `--no-lens` | `lens.enabled` | global | pi-lens **on** |
+| `--no-lsp` | `lsp.enabled` | global | LSP diagnostics **on** |
+| `--no-autoformat` | `format.enabled` | project | autoformat **on** (deferred) |
+| `--immediate-format` | `format.mode` (`"immediate"`) | global | `"deferred"` |
+| `--no-autofix` | `autofix.enabled` | project | autofix **on** |
+| `--no-tests` | `tests.enabled` | global | test runner **on** |
+| `--no-delta` | `delta.enabled` | global | delta mode **on** (new diagnostics only) |
+| `--lens-guard` | `guard.enabled` | global | **off** |
+
+| `--no-opengrep` | `opengrep.enabled` | global | Opengrep scanner **on** |
+| `--no-read-guard` | `readGuard.enabled` | global | read-before-edit monitor **on** |
+| `--no-lens-context` | `contextInjection.enabled` | global | context injection **on** |
+| `--lens-turn-summary` | `turnSummary.enabled` | global | **off** |
+| `--lens-actionable-warnings` | `actionableWarnings.enabled` | global | **off** |
+| `--lens-actionable-warning-actions` | `actionableWarnings.includeLspCodeActions` | global | **off** |
+| `--lens-actionable-warning-autofix` | `actionableWarnings.autoFix.enabled` | project | **off** |
+| `--lens-actionable-warning-all` | `actionableWarnings.deltaOnly` (`false`) | global | `deltaOnly` **on** (report this turn only) |
+| `--lens-compact-tool-line` | `ui.compactToolLine` | global | **off** (two-row tool rendering) |
+
+`--lens-guard` is **EXPERIMENTAL and strictly opt-in**. When enabled, actual
+`git commit`/`git push` commands are blocked only for current, structured
+blocking findings (including blocking test failures); advisory/no-action-required
+findings do not block. Stale, malformed, or ambiguous persisted state blocks
+conservatively until checks run again.
+
+`--immediate-format` and `--lens-actionable-warning-all` are not `--no-*` flags,
+so they set a value rather than flipping a boolean off.
+
+### Non-flag config knobs
+
+These take values (numbers, arrays, strings) rather than being on/off, so they
+have no CLI flag. See the [Configuration reference](./globalconfig.md) for full
+field docs.
+
+| Key | Where | Default | What it does |
+| --- | --- | --- | --- |
+| `ignore` | global + project | `[]` | Gitignore-style globs excluded from every scan |
+| `widget.visible` | global | `true` | Whether the diagnostics widget shows at session start |
+| `dispatch.runnerTimeoutFloorMs` | global | none (no floor) | Minimum wall-clock budget per dispatch runner |
+| `format.mode` | global | `"deferred"` | `"deferred"` (at `agent_end`) or `"immediate"` |
+| `actionableWarnings.autoFix.maxFixes` | global | `5` | Cap on quickfixes applied per turn (`0` = report only) |
+| `rules.high-complexity.threshold` | project | `15` | Cyclomatic-complexity threshold |
+| `rules.high-fan-out.threshold` | project | `20` | Distinct-function-call threshold |
+| `rules.<id>.disable` | project | absent | Disable diagnostics for a rule (output-only filter, project-wide; same normalization as `pi-lens-ignore`) |
+| `rules.<id>.select` | project | absent | Allowlist of rule ids (output-only filter, project-wide across every key; disable wins over select) |
+| `maxProjectFiles` | project | `2000` | Base scale knob; derives five subsystem size budgets |
+| `reviewGraph.maxFiles` | project | derived (clamped `100`–`20000`) | Explicit review-graph file budget |
+| `trivy.enabled` / `trivy.minSeverity` | project | off | Opt-in Trivy vulnerability scanning |
+
+## Global vs project config
+
+### Global — `~/.pi-lens/config.json`
+
+User-level. Applies to **every** project. Honors **all** flag keys from the
+table above plus the non-flag global knobs (`ignore`, `widget.visible`,
+`dispatch.runnerTimeoutFloorMs`, `format.mode`,
+`actionableWarnings.autoFix.maxFixes`). On Windows the path is
+`%USERPROFILE%\.pi-lens\config.json`.
+
+```json
+{
+  "lsp": { "enabled": true },
+  "tests": { "enabled": false },
+  "widget": { "visible": false },
+  "format": { "enabled": true, "mode": "immediate" },
+  "actionableWarnings": {
+    "enabled": true,
+    "autoFix": { "enabled": false, "maxFixes": 5 }
+  }
+}
+```
+
+### Project — `.pi-lens.json`
+
+Per-repo. Discovered by walking **upward** from the current directory, so a
+monorepo can keep one config at the repo root and every subdirectory picks it up
+(closest config wins per edited file). `pi-lens.json` (no leading dot) is also
+accepted.
+
+A project file honors **only**:
+
+- the three mutation controls — `format.enabled`, `autofix.enabled`,
+  `actionableWarnings.autoFix.enabled`;
+- `ignore`, `rules`, `maxProjectFiles`, `reviewGraph`, and `trivy`.
+
+Most toggles are **global-only**. Putting a global-only key such as
+`"lsp": { "enabled": false }` in a `.pi-lens.json` is **not** honored at project
+scope — pi-lens logs a one-time warning saying so (rather than silently doing
+nothing) and you should set it in `~/.pi-lens/config.json` or pass the CLI flag
+instead. Foreign LSP-loader namespaces that a shared file legitimately carries
+(`servers`, `serverOverrides`, `disabledServers`, `warmFiles`) and `$schema` are
+tolerated without warning; anything else is logged once as a likely typo.
+
+```json
+{
+  "ignore": ["**/*.test.ts", "vendor/**"],
+  "rules": {
+    "high-complexity": { "threshold": 25 },
+    "high-fan-out": { "threshold": 30 },
+    "no-eval": { "disable": ["no-eval", "ast-grep:no-eval", "no-eval-js"] }
+  },
+  "maxProjectFiles": 5000,
+  "format": { "enabled": false }
+}
+```
+
+A project's own mutation-control value wins over the global default in **either**
+direction (a repo can re-enable a mutation path the user disabled globally, and
+vice versa); only an explicit disabling CLI flag (`--no-autoformat`,
+`--no-autofix`) outranks it. See
+[Mutation controls](./globalconfig.md#mutation-controls) for the full precedence.
+
+## Environment variables
+
+Environment variables are read once at process start; set them in the launching
+shell (`export VAR=…` in bash, `$env:VAR = "…"` in PowerShell), your process
+manager, or CI config. The handful you are most likely to reach for:
+
+- `PI_LENS_NO_CONTEXT_INJECTION=1` — disable automatic context injection while
+  keeping tools, LSP, read-guard, and formatting active.
+- `PILENS_DATA_DIR` — relocate per-project persistent state (caches, snapshot,
+  review graph) out of the workspace.
+- `PI_LENS_HOME` — relocate the machine-global root (logs, tool binaries, install
+  caches, instance registry).
+- `PI_LENS_MAX_PROJECT_FILES` — base project-size scale knob (default `2000`).
+- `PI_LENS_STARTUP_MODE` — force the startup path: `full`, `minimal`, or `quick`.
+
+**Full environment-variable reference:** [environment-variables.md](./environment-variables.md)
+— every supported variable with its default, behavior, and precedence (install
+control, scale/limit knobs, logging, language-specific, and more).
+
+## See also
+
+- [Configuration reference](./globalconfig.md) — full field-by-field docs for
+  `~/.pi-lens/config.json` and `.pi-lens.json`.
+- [Usage](./usage.md) — the CLI flags in context.
+- [Environment variables](./environment-variables.md) — the complete
+  environment-variable reference.

package/docs/tools.md

@@ -5,7 +5,11 @@ pi-lens registers the following slash commands with the pi host:
 - `/lens-toggle` — toggle pi-lens on/off for the current session without restarting
 - `/lens-context-toggle` — toggle automatic context injection on/off for the session (tools/LSP/read-guard/formatting stay active)
 - `/lens-widget-toggle` — show/hide the pi-lens diagnostics widget below the editor
-- `/lens-health` — runtime health, latency, and diagnostic telemetry
+- `/lens-health` — runtime health, latency, and diagnostic telemetry, including
+  bounded per-session degradation counts (trust refusals, LSP breakers,
+  formatter skips/failures, idle evictions, WASM aborts, timeout tallies, and
+  more)
+- `/lens-perf` — independent top-five p50 and p99 rankings for the current process session and machine-wide active latency-log window
 - `/lens-allow-edit <path>` — override the read-before-edit guard for a single edit
 - `/lens-tools` — tool installation status: globally installed, auto-installed, or npx fallback
 - `/lens-tdi` — Technical Debt Index (TDI) and project health trend
@@ -14,3 +18,16 @@ pi-lens registers the following slash commands with the pi host:
   the project data dir, path shown on completion)
 
 For runtime startup flags (`--no-lens`, `--no-lsp`, etc.) see [`usage.md`](usage.md).
+
+## Standalone CLI
+
+Build and persist the review graph out of band for CI or cron:
+
+```bash
+npx pi-lens build-graph [--cwd <dir>]
+```
+
+The command uses the same graph builder, project configuration, file cap, and
+persist cap as an interactive session. It prints file/node/edge/element count,
+snapshot JSON bytes, and duration on success; an unsafe root, build skip/error,
+or failed/skipped persistence exits non-zero with the reason on stderr.

package/docs/tree-sitter_rules_catalog.md

@@ -2,7 +2,7 @@
 
 <!-- GENERATED by scripts/gen-rule-catalogs.mjs — do not edit by hand. Run `npm run docs:rule-catalogs` after changing rules. -->
 
-pi-lens bundles **164 enabled** tree-sitter query rules across **14 languages**, plus 21 disabled.
+pi-lens bundles **158 enabled** tree-sitter query rules across **14 languages**, plus 12 disabled.
 
 Rule source: `rules/tree-sitter-queries/<language>/`.
 
@@ -25,15 +25,13 @@ Rule source: `rules/tree-sitter-queries/<language>/`.
 | `non-case-label-in-switch` | error | maintainability | non-case label inside switch statement — move label outside or restructure |
 | `noreturn-returns` | error | reliability | function declared with noreturn attribute contains a return statement |
 
-### C++ (6)
+### C++ (4)
 
 | Rule | Severity | Category | Description |
 |---|---|---|---|
 | `no-auto-ptr` | error | reliability | std::auto_ptr should not be used — use std::unique_ptr instead |
-| `no-confused-move-forward` | error | reliability | std::move and std::forward should not be confused |
-| `no-memset-sensitive-data` | error | security | memset should not be used to delete sensitive data — use SecureZeroMemory or explicit_bzero |
+| `no-memset-sensitive-data` | warning | security | memset should not be used to delete sensitive data — use SecureZeroMemory or explicit_bzero |
 | `no-scoped-lock-without-args` | error | reliability | std::scoped_lock should be created with constructor arguments |
-| `noexcept-functions` | error | reliability | Function should be declared noexcept |
 | `unnecessary-bit-ops` | error | maintainability | Unnecessary bit operation - has no effect |
 
 ### C# (5)
@@ -67,14 +65,14 @@ Rule source: `rules/tree-sitter-queries/<language>/`.
 | `go-ignored-call-result` | warning | error-handling | Call result assigned to '_' — verify this discard is intentional |
 | `go-insecure-random` | warning | security | Insecure randomness source detected — use crypto/rand for security-sensitive values |
 | `go-log-fatal` | warning | reliability | log.Fatal/log.Panic terminates execution — prefer returning errors from core logic |
-| `go-mutex-copy` | warning | concurrency | sync.Mutex copied by value — copy breaks the lock; use a pointer receiver or embed via pointer |
+| `go-mutex-copy` | warning | concurrency | sync.Mutex parameter taken by value — the callee locks a copy; take *sync.Mutex instead |
 | `go-path-traversal` | warning | security | Potential path traversal sink — sanitize and constrain file paths |
 | `go-shared-map-write-goroutine` | error | concurrency | Map write inside goroutine may race — guard with synchronization or ownership boundaries |
 | `go-sql-injection` | error | security | Potential SQL injection sink — use parameterized queries |
 | `go-time-sleep-test` | warning | correctness | time.Sleep in test — use synchronisation (channel, WaitGroup, Eventually) instead of arbitrary sleeps |
 | `go-weak-hash` | error | security | Weak hash primitive detected (md5/sha1) — use sha256+ for security-sensitive contexts |
 
-### Java (24)
+### Java (20)
 
 | Rule | Severity | Category | Description |
 |---|---|---|---|
@@ -82,7 +80,6 @@ Rule source: `rules/tree-sitter-queries/<language>/`.
 | `infinite-recursion` | error | reliability | Method '{{NAME}}' appears to recurse without termination condition |
 | `junit-call-super` | error | maintainability | JUnit test case should call super method |
 | `main-should-not-throw` | warning | reliability | main() should not declare throws — handle exceptions internally |
-| `mockito-initialized` | error | reliability | @Mock/@InjectMocks object should be initialized with MockitoAnnotations.openMocks() |
 | `name-capitalization-conflict` | error | maintainability | '{{NAME}}' differs only by capitalization from existing field/method |
 | `no-clone-override` | warning | reliability | clone() should not be overridden — use copy constructor instead |
 | `no-double-checked-locking` | error | reliability | Double-checked locking should not be used |
@@ -92,15 +89,12 @@ Rule source: `rules/tree-sitter-queries/<language>/`.
 | `no-octal-values` | error | maintainability | Octal value '{{VALUE}}' should not be used - use explicit 0o prefix if intended |
 | `no-threadgroup` | warning | reliability | ThreadGroup should not be used — it's obsolete and unsafe |
 | `no-threads-in-constructors` | error | maintainability | Threads should not be started in constructors |
-| `no-wait-notify-on-thread` | error | reliability | {{METHOD}}() should not be called on Thread instances |
 | `prepared-statement-valid-indices` | error | reliability | PreparedStatement/ResultSet methods should use valid indices (1-based) |
-| `resources-closed` | error | reliability | Resource '{{RESOURCE}}' should be closed in finally block |
-| `short-circuit-logic` | error | maintainability | Use '{{OP}}' instead of '{{BAD_OP}}' for short-circuit evaluation |
-| `spring-session-attributes-setcomplete` | error | reliability | @Controller with @SessionAttributes must call setComplete on SessionStatus |
+| `resources-closed` | warning | reliability | Resource '{{RESOURCE}}' should be closed in finally block |
 | `springboot-default-package` | error | reliability | @SpringBootApplication and @ComponentScan should not be used in default package |
 | `switch-fall-through` | error | maintainability | Switch case should end with an unconditional break statement |
 | `switch-non-case-labels` | error | reliability | Non-case labels should not be used inside switch statements |
-| `tests-include-assertions` | error | maintainability | Test method should include at least one assertion |
+| `tests-include-assertions` | warning | maintainability | Test method should include at least one assertion |
 | `unnecessary-bit-ops-java` | error | maintainability | Unnecessary bit operation - has no effect |
 
 ### JavaScript (2)
@@ -216,7 +210,7 @@ Rule source: `rules/tree-sitter-queries/<language>/`.
 | `deep-promise-chain` | warning | complexity | Promise chain {{M1}} → {{M2}} → {{M3}} → {{M4}} — consider async/await |
 | `default-not-last` | error | maintainability | default clause should be the last case |
 | `duplicate-function-arg` | error | reliability | Duplicate parameter name '{{NAME}}' |
-| `empty-switch-case` | error | reliability | Switch case should not be empty |
+| `empty-switch-case` | error | reliability | Switch case is empty and shares no body with a following label |
 | `infinite-loop` | error | reliability | Loop appears to be infinite with no termination condition |
 | `mixed-async-styles` | warning | style | Mixed async/await + promise chains — use consistent async style |
 | `no-console-in-tests` | warning | testing | console.{{METHOD}} in test block — use proper assertions or logging |
@@ -239,17 +233,11 @@ Rule source: `rules/tree-sitter-queries/<language>/`.
 | `ts-ssrf` | error | security | Potential SSRF sink — validate and allowlist outbound URLs |
 | `ts-weak-hash` | error | security | Weak hash primitive selected (md5/sha1) — use sha256+ for security-sensitive contexts |
 | `ts-xss-dom-sink` | error | security | XSS risk — dynamic value written to innerHTML/outerHTML or document.write() |
-| `unsafe-regex` | error | security | Dynamic regex from user input — can cause ReDoS (Regular Expression Denial of Service) |
+| `unsafe-regex` | warning | security | Dynamic regex from user input — can cause ReDoS (Regular Expression Denial of Service) |
 | `variable-shadowing` | warning | maintainability | Variable '{{NAME}}' shadows a parameter — use a distinct name |
 
 ## Disabled rules
 
-### ABAP (1)
-
-| Rule | Severity | Category | Description |
-|---|---|---|---|
-| `delete-where` | error | reliability | DELETE FROM statement should have a WHERE clause |
-
 ### C (1)
 
 | Rule | Severity | Category | Description |
@@ -263,19 +251,12 @@ Rule source: `rules/tree-sitter-queries/<language>/`.
 | `alter-statement` | warning | maintainability | ALTER should not be used - causes spaghetti code |
 | `lock-table-cobol` | error | maintainability | LOCK TABLE should not be used |
 
-### PL/SQL (9)
+### PL/SQL (2)
 
 | Rule | Severity | Category | Description |
 |---|---|---|---|
-| `delete-update-where` | error | reliability | {{STATEMENT}} statement should contain a WHERE clause |
-| `end-loop-semicolon` | error | reliability | END LOOP should be followed by a semicolon |
-| `fetch-bulk-collect-limit` | error | reliability | FETCH ... BULK COLLECT INTO should not be used without a LIMIT clause |
-| `forallsave-exceptions` | error | reliability | FORALL statement should use the SAVE EXCEPTIONS clause |
 | `lock-table` | error | maintainability | LOCK TABLE should not be used |
-| `nchar-nvarchar2-bytes` | error | reliability | NCHAR/NVARCHAR2 size should be in characters, not bytes |
 | `no-synchronize` | error | reliability | SYNCHRONIZE should not be used |
-| `not-null-initialization` | error | reliability | NOT NULL variable should be initialized |
-| `raise-application-error-codes` | error | reliability | RAISE_APPLICATION_ERROR should only be used with error codes from -20000 to -20999 |
 
 ### Python (1)
 
@@ -283,7 +264,7 @@ Rule source: `rules/tree-sitter-queries/<language>/`.
 |---|---|---|---|
 | `python-print-statement` | warning | debugging | print() — remove debug output before committing |
 
-### TypeScript (7)
+### TypeScript (6)
 
 | Rule | Severity | Category | Description |
 |---|---|---|---|
@@ -293,4 +274,3 @@ Rule source: `rules/tree-sitter-queries/<language>/`.
 | `hardcoded-secrets` | error | security | Hardcoded secret in variable assignment — use environment variables |
 | `long-parameter-list` | warning | complexity | Function has {{PARAM_COUNT}} parameters — use object pattern |
 | `nested-ternary` | warning | readability | Nested ternary — use if/else or early returns for clarity |
-| `ts-path-traversal` | error | security | Potential path traversal sink — avoid filesystem I/O with untrusted input |

package/docs/usage.md

@@ -89,8 +89,22 @@ pi --no-tests            # Skip test runner
 pi --no-delta            # Disable delta mode (show all diagnostics, not just new ones)
 pi --lens-guard          # Block git commit/push when unresolved blockers exist (experimental)
 pi --no-opengrep         # Disable the Opengrep security scanner (default-on auxiliary LSP)
+pi --no-read-guard       # Disable the read-before-edit behavior monitor
+pi --lens-turn-summary   # Persist a per-turn summary of diagnostics, autofixes, and autoformats
+pi --lens-compact-tool-line   # Render tool results as one compact, theme-aware line (closes #1327)
+
+# Actionable warnings (all default off)
+pi --lens-actionable-warnings          # Report fixable warnings at turn end
+pi --lens-actionable-warning-actions   # Enrich the report with LSP code-action titles
+pi --lens-actionable-warning-autofix   # Apply conservative LSP quickfixes at agent_end
+pi --lens-actionable-warning-all       # Report every warning, not just this turn's
 ```
 
+Every one of these has a `~/.pi-lens/config.json` equivalent, so you can set it
+once instead of per session. See
+[Global and Project Config](globalconfig.md#every-toggle-both-ways) for the
+flag-to-key table and the precedence order.
+
 ## Rules
 
 ### Tree-sitter rules
@@ -128,6 +142,23 @@ second host adapter that calls the same `clients/lens-engine.ts` seam as the pi
 extension. Use `npm run build:dist` after MCP/engine changes so the user-scoped
 server loads fresh compiled code.
 
+Two Claude Code hooks give the MCP mirror the same automatic cadence the pi
+extension has. PostToolUse runs the per-edit pass, `Stop` runs the per-turn one:
+
+```json
+{ "hooks": {
+  "PostToolUse": [
+    { "matcher": "Edit|Write",
+      "hooks": [ { "type": "command", "command": "pi-lens-analyze --hook" } ] } ],
+  "Stop": [
+    { "hooks": [ { "type": "command", "command": "pi-lens-analyze --turn-end", "timeout": 60 } ] } ]
+} }
+```
+
+The `Stop` hook only works against a running MCP server because only that
+process owns the session state and pending turn work. With no warm server the
+turn-end is skipped, not faked: one line on stderr and nothing on stdout.
+
 ## Troubleshooting
 
 - Run `npm run build` before tests after editing TypeScript; tests import