pi-lens 4.1.2 → 4.1.4

package/docs/ast-grep_rules_catalog.md

@@ -2,16 +2,17 @@
 
 <!-- GENERATED by scripts/gen-rule-catalogs.mjs — do not edit by hand. Run `npm run docs:rule-catalogs` after changing rules. -->
 
-pi-lens bundles **455 enabled** ast-grep rules (271 pi-lens-authored + 184 vendored from CodeRabbit) across **16 languages**, plus 16 disabled.
+pi-lens bundles **481 enabled** ast-grep rules (297 pi-lens-authored + 184 vendored from CodeRabbit) across **17 languages**, plus 16 disabled.
 
 See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `rules/ast-grep-rules/rules/` (pi-lens), `rules/ast-grep-rules/coderabbit/rules/` (vendored).
 
 ## Enabled rules
 
-### C (9)
+### C (10)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
+| `c-no-malloc-free` | warning | no | pi-lens | Manual malloc/calloc/realloc/free; verify ownership and error handling |
 | `dont-call-system-c` | warning | no | CodeRabbit | Don't call `system`. It's a high-level wrapper that allows for stacking multiple commands. Always prefer a more restrictive API such as cal… |
 | `file-access-before-action-c` | warning | no | CodeRabbit | A check is done with `access` and then the file is later used. There is no guarantee that the status of the file has not changed since the… |
 | `file-stat-before-action-c` | warning | no | CodeRabbit | A check is done with `stat` and then the file is used. There is no guarantee that the status of the file has not changed since the call to… |
@@ -22,10 +23,12 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `small-key-size-c` | warning | no | CodeRabbit | $KEY_FUNCTION` is using a key size of only $KEY_BITS bits. This is less than the recommended key size of 2048 bits. |
 | `world-writable-file-c` | warning | no | CodeRabbit | This call makes a world-writable file which allows any user on a machine to write to the file. This may allow attackers to influence the be… |
 
-### C++ (15)
+### C++ (17)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
+| `cpp-no-malloc-free` | warning | no | pi-lens | Manual malloc/calloc/realloc/free in C++; consider RAII (new/unique_ptr/vector) |
+| `cpp-no-printf` | warning | no | pi-lens | Avoid printf in C++; prefer std::cout/std::format for type-safe formatting |
 | `dont-call-system-cpp` | warning | no | CodeRabbit | Don't call `system`. It's a high-level wrapper that allows for stacking multiple commands. Always prefer a more restrictive API such as cal… |
 | `file-access-before-action-cpp` | warning | no | CodeRabbit | A check is done with `access` and then the file is later used. There is no guarantee that the status of the file has not changed since the… |
 | `file-stat-before-action-cpp` | warning | no | CodeRabbit | A check is done with `stat` and then the file is used. There is no guarantee that the status of the file has not changed since the call to… |
@@ -58,13 +61,24 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `stacktrace-disclosure-csharp` | warning | no | CodeRabbit | Stacktrace information is displayed in a non-Development environment. Accidentally disclosing sensitive stack trace information in a produc… |
 | `use-ecb-mode-csharp` | warning | no | CodeRabbit | "Usage of the insecure ECB mode detected. You should use an authenticated encryption mode instead, which is implemented by the classes AesG… |
 
-### Go (23)
+### CSS (1)
+
+| Rule | Severity | Fixable | Source | Description |
+|---|---|---|---|---|
+| `no-important` | warning | no | pi-lens | Avoid `!important` — increase selector specificity instead |
+
+### Go (28)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
 | `avoid-bind-to-all-interfaces-go` | warning | no | CodeRabbit | "Detected a network listener listening on 0.0.0.0 or an empty string. This could unexpectedly expose the server publicly as it binds to all… |
 | `defer-in-loop` | warning | no | pi-lens | defer is used inside a loop. This defers execution until after the entire function, not each iteration. |
 | `go-defer-func-call-antipattern` | warning | yes | pi-lens | defer with function-call args — arguments are evaluated immediately, not at defer time |
+| `go-no-fmt-println` | warning | no | pi-lens | Avoid fmt.Println/Printf-family calls in production code; use a structured logger |
+| `go-no-panic-in-lib` | warning | no | pi-lens | Avoid panic() in library code; return errors instead |
+| `go-no-underscore-func-name` | hint | no | pi-lens | Use camelCase for Go function names, not snake_case |
+| `go-prefer-errors-is` | hint | no | pi-lens | Use errors.Is(err, target) instead of direct comparison for error checking |
+| `go-prefer-string-builder` | hint | no | pi-lens | Use strings.Builder instead of repeated string concatenation |
 | `go-test-functions` | warning | yes | pi-lens | Go test function detected — verify it follows the project's test naming convention |
 | `gorilla-cookie-store-hardcoded-session-key-go` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
 | `gorilla-csrf-hardcoded-auth-key-go` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
@@ -92,7 +106,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 |---|---|---|---|---|
 | `plaintext-http-link-html` | warning | no | CodeRabbit | "This link points to a plaintext HTTP URL. Prefer an encrypted HTTPS URL if possible." |
 
-### Java (36)
+### Java (40)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
@@ -118,7 +132,11 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `missing-httponly-java` | warning | no | CodeRabbit | Detected a cookie where the `HttpOnly` flag is either missing or disabled. The `HttpOnly` cookie flag instructs the browser to forbid clien… |
 | `missing-secure-java` | warning | no | CodeRabbit | Detected a cookie where the `Secure` flag is either missing or disabled. The `Secure` cookie flag instructs the browser to forbid sending t… |
 | `no-null-cipher-java` | warning | no | CodeRabbit | NullCipher was detected. This will not encrypt anything; the cipher text will be the same as the plain text. Use a valid, secure cipher: Ci… |
+| `no-raw-types` | warning | no | pi-lens | Use parameterized types instead of raw types. |
+| `no-string-concat-in-loop` | warning | no | pi-lens | Use StringBuilder instead of string concatenation in loops. |
+| `no-system-out-println` | warning | no | pi-lens | Avoid System.out.println; use a logging framework instead. |
 | `passwordauthentication-hardcoded-password-java` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
+| `prefer-string-is-empty` | warning | no | pi-lens | Use .isEmpty() instead of .length() == 0 or .equals(""). |
 | `rsa-no-padding-java` | warning | no | CodeRabbit | Using RSA without OAEP mode weakens the encryption. |
 | `simple-command-injection-direct-input-java` | warning | no | CodeRabbit | "Untrusted input might be injected into a command executed by the application, which can lead to a command injection vulnerability. An atta… |
 | `system-setproperty-hardcoded-secret-java` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
@@ -217,13 +235,21 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `unchecked-throwing-call-js` | error | no | pi-lens | $CALL without try/catch — throws on invalid input |
 | `weak-rsa-key-js` | error | no | pi-lens | Weak RSA key size — use at least 2048 bits |
 
-### Kotlin (5)
+### Kotlin (13)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
 | `des-is-deprecated-kotlin` | warning | no | CodeRabbit | DES is considered deprecated. AES is the recommended cipher. Upgrade to use AES. See https://www.nist.gov/news-events/news/2005/06/nist-wit… |
 | `desede-is-deprecated-kotlin` | warning | no | CodeRabbit | Triple DES (3DES or DESede) is considered deprecated. AES is the recommended cipher. Upgrade to use AES. |
 | `jwt-hardcode-kotlin` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
+| `kotlin-no-lateinit` | warning | no | pi-lens | Avoid lateinit var; prefer a nullable type or constructor injection |
+| `kotlin-no-nullable-boolean` | warning | no | pi-lens | Avoid a nullable Boolean; a two-value enum or a non-null default is usually clearer |
+| `kotlin-no-println` | warning | no | pi-lens | Avoid println/print; use a structured logger |
+| `kotlin-no-unnecessary-let` | warning | no | pi-lens | let on a non-null-checked receiver adds indirection; use the value directly |
+| `kotlin-no-unsafe-cast` | warning | no | pi-lens | Unsafe cast (as) throws ClassCastException on a mismatch; consider as? |
+| `kotlin-no-var` | warning | no | pi-lens | Prefer val over var; mutability should be explicit and scoped |
+| `kotlin-prefer-data-class` | warning | no | pi-lens | This class looks like a plain value holder; consider a data class |
+| `kotlin-prefer-is-empty` | warning | no | pi-lens | Use isEmpty() instead of comparing size/length to zero |
 | `rsa-no-padding-kotlin` | warning | no | CodeRabbit | Using RSA without OAEP mode weakens the encryption. |
 | `system-setproperty-hardcoded-secret-kotlin` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
 
@@ -234,7 +260,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `openssl-cbc-static-iv-php` | warning | no | CodeRabbit | Static IV used with AES in CBC mode. Static IVs enable chosen-plaintext attacks against encrypted data. |
 | `search-active-debug-php` | warning | no | CodeRabbit | Debug logging is explicitly enabled. This can potentially disclose sensitive information and should never be active on production systems. |
 
-### Python (96)
+### Python (98)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
@@ -308,6 +334,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `python-mysqlclient-hardcoded-secret-python` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
 | `python-neo4j-empty-password-python` | warning | no | CodeRabbit | The application creates a database connection with an empty password. This can lead to unauthorized access by either an internal or externa… |
 | `python-neo4j-hardcoded-secret-python` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
+| `python-optional-type` | hint | no | pi-lens | Optional[T] requires Python 3.10+ to rewrite as T \| None |
 | `python-peewee-mysql-empty-password-python` | warning | no | CodeRabbit | The application creates a database connection with an empty password. This can lead to unauthorized access by either an internal or externa… |
 | `python-peewee-mysql-hardcoded-secret-python` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
 | `python-peewee-pg-empty-password-python` | warning | no | CodeRabbit | The application creates a database connection with an empty password. This can lead to unauthorized access by either an internal or externa… |
@@ -333,9 +360,10 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `python-urllib3-hardcoded-secret-python` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
 | `python-webrepl-empty-password-python` | warning | no | CodeRabbit | The application creates a database connection with an empty password. This can lead to unauthorized access by either an internal or externa… |
 | `python-webrepl-hardcoded-secret-python` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
+| `reducible-list-comprehension` | warning | yes | pi-lens | A list comprehension is unnecessary here; use a generator expression |
 | `unchecked-throwing-call-python` | error | no | pi-lens | Call without try/except — throws on invalid input or missing file |
 
-### Ruby (19)
+### Ruby (20)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
@@ -358,8 +386,9 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `ruby-pg-hardcoded-secret-ruby` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
 | `ruby-redis-empty-password-ruby` | warning | no | CodeRabbit | The application creates a database connection with an empty password. This can lead to unauthorized access by either an internal or externa… |
 | `ruby-redis-hardcoded-secret-ruby` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
+| `ruby-symbol-to-proc-candidate` | warning | yes | pi-lens | Use a symbol-to-proc shorthand for this simple iterator block |
 
-### Rust (11)
+### Rust (12)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
@@ -370,6 +399,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `redundant-unsafe-function` | error | no | pi-lens | Unsafe function without unsafe block inside |
 | `reqwest-accept-invalid-rust` | warning | no | CodeRabbit | Dangerously accepting invalid TLS |
 | `rust-2024-let-chain-candidate` | info | no | pi-lens | nested if conditions can be collapsed into a Rust 2024 let-chain |
+| `rust-no-chars-enumerate` | warning | no | pi-lens | chars().enumerate() may confuse character indices with byte offsets |
 | `secrets-reqwest-hardcoded-auth-rust` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
 | `ssl-verify-none-rust` | warning | no | CodeRabbit | SSL verification disabled, this allows for MitM attacks |
 | `tokio-postgres-empty-password-rust` | warning | no | CodeRabbit | The application uses an empty credential. This can lead to unauthorized access by either an internal or external malicious actor. It is rec… |
@@ -392,10 +422,11 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `insecure-biometrics-swift` | info | no | CodeRabbit | The application was observed to leverage biometrics via Local Authentication, which returns a simple boolean result for authentication. Thi… |
 | `rabbit-hardcoded-secret-swift` | warning | no | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |
 
-### TSX (7)
+### TSX (8)
 
 | Rule | Severity | Fixable | Source | Description |
 |---|---|---|---|---|
+| `hyphenated-svg-attribute` | warning | no | pi-lens | Use camelCase for this known SVG attribute in JSX |
 | `inline-styles` | hint | no | pi-lens | Inline styles — use CSS modules or styled components |
 | `jsx-boolean-short-circuit` | error | yes | pi-lens | React JSX && pitfall — potentially renders 0 or NaN |
 | `no-nested-links` | error | no | pi-lens | Nested <a> tags are invalid HTML and cause unexpected behavior |

package/docs/astplayground.md

@@ -27,38 +27,49 @@ released `ast-grep`), so we get a fresh-engine cross-check.
 
 ## What the playground actually does
 
-The playground's source code is **fixed** — the user cannot inject custom
-source via the URL hash. The URL hash only carries:
+The verifier encodes `--code` into the playground's URL-hash state so the
+upstream engine matches the rule against it. The state (`ast-grep/ast-
+grep.github.io`, `website/src/components/astGrep/state.ts` +
+`index.ts`) carries:
 
 - `mode: "Config"` + `config: <rule YAML>` (the rule)
-- `query` (an ast-grep pattern string, only used in `mode: "Pattern"`)
+- `source: <code>` — the code the rule is matched against, in **both**
+  modes
+- `query` — an ast-grep pattern string, used only in `mode: "Pattern"`
+  (irrelevant here; the verifier always requests Config mode)
 
-So this verifier is a **pattern-level smoke test**: "does the rule's
-pattern fire on the playground's hardcoded sample source?" It catches:
+So this verifier checks: "does the rule match `--code` on the upstream
+engine, and does the count agree with the local `ast-grep` CLI?" It catches:
 
 - **YAML/pattern rejection** — the playground shows an error if the rule's
   YAML uses features the upstream engine doesn't support
 - **Pattern-engine divergence** — local ast-grep matches but upstream
   doesn't (or vice versa)
 - **Match-count drift** — `Found N match(es)` count differs between local
-  and upstream
+  and upstream, for the *same* source
 
-It does **not** catch rule-vs-source bugs where the source is what the user
-wrote — the local CLI test is the source of truth for that.
+#2208: earlier versions of this verifier wrote `--code` into `query`
+instead of `source`. Since `query` is ignored in Config mode, the hash
+carried no source at all, and the playground's `{...defaultState,
+...parsed}` state merge silently fell back to its own hardcoded sample —
+every run graded that fixed sample, not `--code`. Every "ok:true
+matches:N" this verifier produced before the fix reflected the playground's
+sample source, never the caller's code.
 
 ## Usage
 
 ```bash
-# Smoke-test a single rule (auto-launches headless Chrome on 9224, then kills it)
-node scripts/playground-verify-rule.mjs rules/ast-grep-rules/rules/no-console-except-error.yml --code "ignored"
+# Smoke-test a single rule against a snippet it matches
+# (auto-launches headless Chrome on 9224, then kills it)
+node scripts/playground-verify-rule.mjs rules/ast-grep-rules/rules/no-console-except-error.yml --code "console.log('x');"
 
 # Assert a specific match count
 node scripts/playground-verify-rule.mjs rules/ast-grep-rules/rules/jsx-boolean-short-circuit.yml \
-  --code "ignored" --expected 0
+  --code "const a = 1;" --expected 0
 
 # Keep Chrome alive for follow-up runs (avoids the 5–10s cold-start cost)
 node scripts/playground-verify-rule.mjs rules/ast-grep-rules/rules/no-console-except-error.yml \
-  --code "ignored" --keep-chrome
+  --code "console.log('x');" --keep-chrome
 
 ```
 
@@ -142,7 +153,9 @@ Three scripts, one job each:
   resolution, accessibility tree, and network tracing stripped out.
 - `playground-verify-rule.mjs` — the CLI the user invokes. Reads the rule,
   builds the playground URL, runs the page through CDP, scrapes the
-  result, prints JSON, kills Chrome.
+  result, prints JSON, and kills Chrome. Its source-drift sentinel reads only
+  the first `.monaco-editor` in the source pane, not the config editor, so a
+  rule note cannot satisfy the check by repeating the fixture text.
 
 ## Skipping the test
 
@@ -165,10 +178,6 @@ auto-skipped when Google Chrome is not on `PATH` and
 
 ## Known limitations
 
-- **Source is fixed.** The playground uses its own hardcoded sample
-  source. Custom source code passed via `--code` is ignored by the
-  upstream playground in `mode: "Config"`. This is by design — the
-  playground is a manual tool, not a test harness.
 - **Slow.** ~11s per rule. Don't enable in the default `npm test` run.
 - **Line numbers are best-effort.** The playground's gutter layout
   changes between builds. If the line-extraction JS misses, `lines` is

package/docs/configuration.md

@@ -0,0 +1,222 @@
+# Configuring pi-lens
+
+There are **two** pi-lens config files:
+
+| File | Scope | Notes |
+| --- | --- | --- |
+| `.pi-lens.json` | the project | Committed or not, your call. Nearest one wins **per field** — a package can override one setting without restating the repo root's. |
+| `~/.pi-lens/config.json` | the machine | Your defaults across every project. `PI_LENS_CONFIG_PATH` relocates it. |
+
+Both files have the same shape, with one exception noted below the example:
+everything LSP-related lives under an `lsp` namespace inside them.
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/apmantza/pi-lens/master/docs/schema/pi-lens-config-v1.json",
+  "ignore": ["dist/**"],
+  "maxProjectFiles": 8000,
+  "rules": { "high-complexity": { "threshold": 25 } },
+  "lsp": {
+    "disabledServers": ["typos"],
+    "warmFiles": ["src/main.rs"],
+    "servers": {
+      "my-server": {
+        "name": "My Custom LSP",
+        "extensions": [".myext"],
+        "command": "my-lsp-server",
+        "args": ["--stdio"]
+      }
+    },
+    "serverOverrides": {
+      "rust": {
+        "initializationOptions": { "check": { "command": "clippy" } }
+      }
+    }
+  }
+}
+```
+
+**Some settings are global-only.** A handful of switches — `lsp.enabled`
+(`--no-lsp`), `tests.enabled`, `delta.enabled` and the other session-wide
+toggles — are decided once for the machine, not per project, so writing one in a
+`.pi-lens.json` does nothing. It is not ignored quietly: the project loader says
+so, naming the key. `docs/settings.md` lists which flags are which.
+
+## Which file wins
+
+One order, lowest precedence first. A later tier replaces an earlier tier's
+value **for that field only** — objects are merged field-wise, never replaced
+whole, so setting one key never silently drops the rest of a section.
+
+1. **global** — `~/.pi-lens/config.json`.
+2. **project root** — the outermost `.pi-lens.json` at or above your working
+   directory.
+3. **nested-project** — every `.pi-lens.json` between that root and your working
+   directory, outermost first. The nearest file wins, per field.
+
+Those three are the tiers the config **files** resolve through, and they are the
+only ones this resolution populates. Four more tiers are reserved in the
+precedence table — `builtin` below them, and `env`, `cli`, `host` above — and
+nothing writes into them yet; #2427 (env/CLI) and #2416 (host and project trust)
+are what fill them in.
+
+Until they do, environment variables and CLI flags are read by their own
+accessors rather than through this resolution, and their effective precedence
+for a pi-lens toggle is:
+
+1. a `PI_LENS_*` environment variable set to `1` — checked first, and it wins
+   outright;
+2. the matching `--lens-*` / `--no-*` CLI flag;
+3. the nearest project `.pi-lens.json`, then the outer ones (project-scoped
+   settings only);
+4. `~/.pi-lens/config.json`;
+5. the built-in default.
+
+Subsystem-specific env overrides follow the same shape: a
+`PI_LENS_REVIEW_GRAPH_MAX_FILES` beats a `.pi-lens.json`'s
+`reviewGraph.maxFiles`. `docs/environment-variables.md` and `docs/settings.md`
+are the per-setting references.
+
+### One exception: `lsp.disabledServers` is a denial, not a value
+
+Ordinary settings are last-tier-wins. A **denial** is not, because the tier
+that made it is usually the one you control and the tier that would override it
+is usually one that arrived with somebody else's checkout.
+
+`lsp.disabledServers` resolves as the **union of every tier's entries**. A
+project `.pi-lens.json` can add to it and can never subtract from it, so a
+repository cannot re-enable a server you turned off in
+`~/.pi-lens/config.json`. There is no vocabulary for un-denying an entry: if
+you change your mind, edit the file that denied. The provenance reports, per
+denied server, the tier that contributed it.
+
+```console
+$ # which servers run for this file, and why
+$ pilens_effective_config file=src/main.rs
+  ✗ typos — disabled-by-config (global ~/.pi-lens/config.json → /lsp/disabledServers/0)
+```
+
+The union spans **both spellings**: a document's deprecated root keys
+(`servers`, `serverOverrides`, `disabledServers`, `warmFiles`) are read
+into the `lsp` namespace before any tier is merged, so one setting is resolved
+once no matter which spelling each file uses. Migrating does not change the
+answer, staying un-migrated is not a way around the denial, and a half-migrated
+pair of files merges rather than one clobbering the other.
+
+Two rules make the rest of the table unambiguous:
+
+- **The search stops at `$HOME`.** pi-lens never reads a config file in your
+  home directory or above it. A stray `pi-lens.json` in `$HOME` (or at `C:\`)
+  is not adopted by every project on the machine. The machine-global file is
+  read by its own path, so it is unaffected.
+- **The canonical spelling wins.** Where a legacy file or a legacy key means the
+  same thing as the canonical one, the canonical one is used — otherwise the
+  migration below could never be completed.
+
+## Legacy locations (still read; being removed)
+
+These are read for their deprecation window and then **removed**. Each one you
+still have produces one warning per setting, naming exactly where to move it —
+carrying the stable code `PILENS_CFG_0003` (a deprecated file) or
+`PILENS_CFG_0002` (a deprecated key), so you can match or suppress on the code
+rather than on the prose.
+
+| Legacy | Move it to | Code |
+| --- | --- | --- |
+| `.pi-lens/lsp.json` | `.pi-lens.json` → `lsp.*` | `PILENS_CFG_0003` |
+| `pi-lsp.json` | `.pi-lens.json` → `lsp.*` | `PILENS_CFG_0003` |
+| `pi-lens.json` (undotted) | `.pi-lens.json` | `PILENS_CFG_0003` |
+| `~/.pi-lens/lsp.json` | `~/.pi-lens/config.json` → `lsp.*` | `PILENS_CFG_0003` |
+| `servers` at the file root | `lsp.servers` | `PILENS_CFG_0002` |
+| `serverOverrides` at the file root | `lsp.serverOverrides` | `PILENS_CFG_0002` |
+| `disabledServers` at the file root | `lsp.disabledServers` | `PILENS_CFG_0002` |
+| `warmFiles` at the file root | `lsp.warmFiles` | `PILENS_CFG_0002` |
+
+**Deprecated since 4.1.4. Read for the last time before 5.0.0.** The window is
+declared as data in `clients/config-diagnostic-codes.ts`
+(`DEPRECATED_CONFIG_SURFACES`) and enforced by test, so the schedule above and
+the code cannot drift apart. `docs/public-api-stability.md` describes the policy
+these dates instantiate.
+
+A `.pi-lens.json` that mixes both spellings is fine while you migrate: the
+canonical key wins, and the keys you have not moved yet keep working.
+
+Only keys pi-lens actually recognizes get "move it to …" advice. A key in a
+legacy file that is not a pi-lens setting at all — a typo, or a leftover from
+another tool — cannot be migrated anywhere, so it gets the ordinary
+unrecognized-key notice (`PILENS_CFG_0001`) and is counted in ONE whole-file
+`PILENS_CFG_0003` notice for the file rather than being told to move.
+
+## When a config is ignored
+
+A file that cannot be read or parsed is **ignored, never partially applied** —
+pi-lens runs on defaults for it and says so once, with the code
+`PILENS_CFG_0001`. A field whose value does not match its declared type is
+dropped on its own (`PILENS_CFG_0005`), and an unrecognized field is dropped
+with a message naming the key (`PILENS_CFG_0004`). If resolving a file fails
+internally the whole file is ignored and said so under its own code
+(`PILENS_CFG_0008`), so "one field went missing" and "none of this file is in
+effect" are never the same code. Nothing about your config is ever ignored
+silently.
+
+The number of notices one file can produce is bounded PER NOTICE LIST, because
+the number of keys in a file is not. There are two lists, split by who composes
+them rather than by what they say — both are about values that were rejected:
+
+- what **resolving** the file produced — the per-field rejections
+  (`PILENS_CFG_0004`, `PILENS_CFG_0005`, `PILENS_CFG_0006`) together with the
+  deprecation notices (`PILENS_CFG_0002`, `PILENS_CFG_0003`), which share this
+  list;
+- what the **loader** reading the file produced on its own — unknown top-level
+  keys and settings it refused (`PILENS_CFG_0001`).
+
+Each list is bounded at 20 records: up to 19 notices plus, when the bound bit,
+a single `PILENS_CFG_0007` summary giving the count that was suppressed, so a
+truncated list always says that it is truncated. That summary is about the
+LIST, not about the file: a config whose every setting was applied can still
+overflow the bound, so it is worded and recorded as a summary rather than as an
+ignored config.
+
+One notice is never suppressed by that bound: `PILENS_CFG_0008`, which says the
+whole file is out of effect. It is not one more rejected key competing for a
+slot — it is what tells you the rejections above it are no longer the whole
+story — so it is kept however full the list already was.
+
+## Asking what is actually in effect
+
+You never have to reconstruct the table above by hand. `pilens_effective_config`
+(MCP) and `effective_config` (pi) return the resolved configuration with the
+provenance of **every** leaf — the tier, the file, the key, and the trust
+decision that applied — plus, for a file you name, its language, every LSP
+server with the reason it was selected or denied, and the runners that would
+dispatch. That is the answer to "why is this running" and to "why is this *not*
+running", without reading a log.
+
+Naming a `file` resolves the configuration **at that file's own directory**,
+which is where the runtime decides from — so a nested `repo/sub/.pi-lens.json`
+layer contributes to the answer, appears in the reported document list, and is
+named as the file behind any decision it made. The walk runs upward and is
+**confined to `cwd`**: a `file` that resolves outside `cwd` — including a
+sibling package in the same monorepo — is rejected rather than answered from
+its own unrelated tree, because the per-file answer is only ever correct when
+it is a superset of the workspace's own; the rejection names the `cwd` it was
+measured against and the remedy is to re-query with `cwd` set to that file's
+own workspace. A confined `file` always passes back through the workspace's
+own documents on its way up, so they are always included too.
+
+It reports **sources, never values**. Environment values never appear, a custom
+server's command line is cut to the binary itself, and every path is rewritten
+`~`-relative. There is no un-redacted mode: the un-redacted data is the config
+file you already have.
+
+`pilens_health` embeds the same provenance as **counts per tier** — how many
+settings each source decided, and which `PILENS_CFG_*` notices the resolution
+produced — so a session's config posture is visible without the detail.
+
+## See also
+
+- `docs/globalconfig.md` — every key of `~/.pi-lens/config.json`, in detail.
+- `docs/settings.md` — the CLI flags and what they map to.
+- `docs/environment-variables.md` — the `PI_LENS_*` tier.
+- `docs/public-api-stability.md` — what `x-stability`, the `PILENS_CFG_*` codes,
+  and the deprecation windows commit pi-lens to.

package/docs/dependencies.md

@@ -40,9 +40,9 @@ Auto-install behavior depends on gate type:
 | `intelephense`                      | PHP LSP                          | Yes            | Flow-gated                         |
 | `bash-language-server`              | Bash LSP                         | Yes            | Language-default                   |
 | `yaml-language-server`              | YAML LSP                         | Yes            | Language-default                   |
-| `vscode-langservers-extracted`      | JSON/ESLint/CSS/HTML LSP         | Yes            | Language-default                   |
-| `vscode-css-languageserver`         | CSS LSP                          | Yes            | Language-default                   |
-| `vscode-html-languageserver-bin`    | HTML LSP                         | Yes            | Language-default                   |
+| `vscode-json-language-server`       | JSON LSP (`vscode-langservers-extracted`) | Yes  | Language-default                   |
+| `vscode-css-languageserver`         | CSS LSP (`vscode-langservers-extracted`)  | Yes  | Language-default                   |
+| `vscode-html-languageserver-bin`    | HTML LSP (`vscode-langservers-extracted`) | Yes  | Language-default                   |
 | `svelte-language-server`            | Svelte LSP                       | Yes            | Flow-gated                         |
 | `@vue/language-server`              | Vue LSP                          | Yes            | Flow-gated                         |
 | `opengrep`                          | Experimental security dispatch   | Auto-install   | Local config / explicit opt-in     |

package/docs/features.md

@@ -53,6 +53,43 @@ so the final state is formatter-stable. A `write` immediately followed by an
 deferred too. See `clients/pipeline.ts`, `clients/runtime-tool-result.ts`, and
 `clients/runtime-agent-end.ts`.
 
+A tool pi-lens does not name is classified by the SHAPE of its arguments
+(`clients/mutating-tool.ts`). A host or extension edit tool called `replace` or
+`insert` therefore gets a turn-state entry, a change-log receipt attributed to
+the tool itself, and the deferred autofix and format pass — the same chain
+`edit` gets. Its lines are resolved when the anchor is unambiguous (roughly
+two-thirds of anchors in practice — `clients/hashline-anchor.ts`); otherwise
+the mutation is recorded whole-file with lines unknown, and the
+read-before-edit guard takes its no-line-info arm rather than guessing.
+Deferred is the default for any edit-shaped tool pi-lens cannot place, because
+formatting between the calls of a multi-step rewrite fights the tool that is
+still writing. A tool whose SHAPE is unrecognized too is caught by observation:
+pi-lens takes a bounded snapshot of the path that call names — and only that
+path, so a change to a neighbouring file is never blamed on it — replays
+whatever actually changed through the same chain, then remembers that tool as
+mutating for the session, and on disk under the project's data directory once a
+second observation confirms it, so later sessions classify it by name with no
+snapshot at all. A tool that names no file is caught at `agent_settled` by an
+incremental content check over the files pi-lens has already read, written,
+diagnosed or opened on a language server: a rotating window of the set each
+turn, reading only the files whose size or timestamp actually moved, so the
+check stays affordable as the set grows. A file it has never seen has no
+baseline and is therefore not covered, and a file it cannot verify is named
+rather than reformatted on a timestamp alone
+(`clients/observed-mutation.ts`).
+
+**Bundled fallback lint configs stay conservative.** When a project ships no
+tool config, the package-owned fallback configs set the rules (`config/biome/core.jsonc`,
+`config/ruff/core.toml`, `config/markdownlint/core.json`). The biome fallback
+disables `useImportType`: its safe fix rewrites a value import used only in
+type positions into `import type`, which erases the runtime binding that
+experimental decorator metadata (`emitDecoratorMetadata`) still needs and
+breaks decorator-based dependency injection (refs #2385). Every other
+recommended rule stays on, and an explicit project `biome.json(c)` remains
+authoritative: if you enable `useImportType` there, pi-lens does not override
+it. The ruff fallback selects no flake8-type-checking (TC) rules and applies
+only safe fixes, so it never hoists imports into `TYPE_CHECKING` blocks.
+
 Deferred formatting (the `agent_end` default) runs with **bounded
 concurrency**: at most three formatter subprocesses in flight at once, with
 results applied in admission order and cooperative yields between files, so a
@@ -140,12 +177,14 @@ pi-lens MCP server expose the same shape to Claude Code / any MCP client.
 
 ### Actionable Warnings
 
-At `turn_end`, pi-lens writes `.pi-lens/cache/actionable-warnings.json` summarizing fixable warnings introduced by the current turn. This powers the optional conservative autofix at `agent_end`.
+At `turn_end`, pi-lens writes `<project-data-dir>/cache/actionable-warnings.json` summarizing fixable warnings introduced by the current turn. This powers the optional conservative autofix at `agent_end`.
+
+`<project-data-dir>` is whatever `getProjectDataDir(cwd)` resolves to: `<project>/.pi-lens` only when that legacy directory already exists, otherwise `~/.pi-lens/projects/<project-slug>` (or a `PILENS_DATA_DIR` location). The turn-end advisory points at `lens_diagnostics mode=delta` first and names the resolved file second, so you never have to work the layout out by hand (#2521).
 
 **Report contents:**
 
 - Warnings are delta-only by default: only diagnostics in lines touched during the current turn are included. Pass `--lens-actionable-warning-all` to report all warnings regardless of location
-- Each warning carries a stable `aw:<hash>` ID derived from file, rule, and message, so suppression state persists across turns in `.pi-lens/cache/actionable-warning-state.json`
+- Each warning carries a stable `aw:<hash>` ID derived from file, rule, and message, so suppression state persists across turns in `<project-data-dir>/cache/actionable-warning-state.json`
 - Sources: pipeline `fixable` diagnostics (always included) and LSP code-action warnings when `--lens-actionable-warning-actions` is set
 - When warnings are present, a concise advisory is injected into the agent context (no blocker language)
 
@@ -354,14 +393,14 @@ pi-lens ships an MCP (Model Context Protocol) server so Claude Code — or any M
 
 **Why a second host:** the pi extension's tools are registered via the host SDK and run on pi's event loop. Claude Code lives in a different process with no SDK access. The MCP server sits in that gap, speaking JSON-RPC over stdio (or a warm Unix socket / Windows named pipe side-channel for the Claude Code PostToolUse hook). It's the easiest way to live-test, debug, and dogfood pi-lens — including running a **review loop** where Claude commits to pi-lens and re-measures.
 
-**16 tools, grouped by lifecycle layer** (the same three layers the pi agent hooks use):
+**18 tools, grouped by lifecycle layer** (the same three layers the pi agent hooks use):
 
 | Layer | MCP tools | What they expose |
 |---|---|---|
-| **Per-edit** | `pilens_analyze`, `pilens_lsp_diagnostics`, `pilens_lsp_navigation`, `pilens_ast_grep_search`, `pilens_ast_grep_replace`, `pilens_module_report`, `pilens_read_symbol` | The fast pipeline (format → autofix → LSP diagnostics → parallel runners) plus the structured read-substitute pair. `analyze` accepts `mode: warm \| fresh` — `warm` reuses the server's in-process LSP, `fresh` forks a worker that loads freshly-built code from disk so the result reflects the latest commit. |
+| **Per-edit** | `pilens_analyze`, `pilens_lsp_diagnostics`, `pilens_lsp_navigation`, `pilens_ast_grep_search`, `pilens_ast_grep_replace`, `pilens_module_report`, `pilens_read_symbol`, `pilens_read_enclosing` | The fast pipeline (format → autofix → LSP diagnostics → parallel runners) plus the structured read-substitute pair. `analyze` accepts `mode: warm \| fresh` — `warm` reuses the server's in-process LSP, `fresh` forks a worker that loads freshly-built code from disk so the result reflects the latest commit. |
 | **Per-turn** | `pilens_turn_end` | Drives the **real** `handleTurnEnd` (knip incremental, dep-circular, cascade, tests, actionable+code-quality warnings) — not a re-implementation. Caller-supplied edited files are auto-registered into turn-state via `addModifiedRange`. |
 | **Per-session** | `pilens_session_start` | Drives the **real** `handleSessionStart` — full jscpd/knip/madge/govulncheck/gitleaks/trivy scans + complexity baselines + LSP warm. The error-debt baseline is not currently populated by the production session-start path. |
-| **Project / observability** | `pilens_project_scan`, `pilens_diagnostics`, `pilens_health`, `pilens_latency`, `pilens_symbol_search` | Cheap project-wide scans, cached diagnostic state, latency telemetry, ranked identifier search (BM25 over the persisted word index — see [docs/word-index.md](word-index.md)). Cross-file blast radius now lives in `pilens_module_report`'s `blastRadius` option. `pilens_health` (and its pi-side `/lens-health` counterpart) also reports a bounded, process-local **degradation ledger** — trust refusals, mode suppressions, LSP breaker trips, formatter skips/failures, TypeScript/word-index/review-graph/project-snapshot idle evictions, WASM aborts, and diagnostics-timeout tallies — so silently degraded behavior stays visible instead of vanishing into a log. |
+| **Project / observability** | `pilens_project_scan`, `pilens_project_report`, `pilens_diagnostics`, `pilens_health`, `pilens_latency`, `pilens_symbol_search`, `pilens_effective_config` | Cheap project-wide scans, cached diagnostic state, latency telemetry, ranked identifier search (BM25 over the persisted word index — see [docs/word-index.md](word-index.md)). Cross-file blast radius now lives in `pilens_module_report`'s `blastRadius` option. `pilens_health` (and its pi-side `/lens-health` counterpart) also reports a bounded, process-local **degradation ledger** — trust refusals, mode suppressions, LSP breaker trips, formatter skips/failures, TypeScript/word-index/review-graph/project-snapshot idle evictions, WASM aborts, and diagnostics-timeout tallies — so silently degraded behavior stays visible instead of vanishing into a log. `pilens_effective_config` answers **“why is X running / why is X not running”** from one query — the resolved configuration with the provenance of every setting, and for a file you name, its language plus every LSP server with the reason it was selected or denied and the runners that would dispatch. It reports sources, never values. |
 | **Lifecycle / loop** | `pilens_rebuild` | Runs `npm run build:dist` so `pilens_analyze mode=fresh` reflects the latest commit. Makes the review loop self-contained: commit → `pilens_rebuild` → `pilens_analyze mode=fresh` → `pilens_latency`. |
 
 **Honest limits** (live-tested, documented in `mcp.md`):

package/docs/language-coverage.md

@@ -17,8 +17,8 @@ Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen i
 | Shell                 | ✓   | lsp, shellcheck                                                                                                | shfmt                   |
 | Fish                  | ✓ (fish-lsp) | lsp, fish-indent                                                                                      | fish_indent             |
 | CSS/SCSS/Less         | ✓   | lsp, stylelint                                                                                                 | biome, prettier         |
-| HTML                  | ✓   | lsp, htmlhint                                                                                                  | prettier                |
-| YAML                  | ✓   | lsp, yamllint, actionlint (GitHub workflows), trivy-config (opt-in; Kubernetes manifests, CloudFormation)      | prettier                |
+| HTML                  | ✓   | lsp, htmlhint                                                                                                  | prettier (with project config) |
+| YAML                  | ✓   | lsp, yamllint, actionlint (GitHub workflows), trivy-config (opt-in; Kubernetes manifests, CloudFormation)      | prettier (with project config) |
 | JSON                  | ✓   | lsp, trivy-config (opt-in; CloudFormation templates only)                                                      | biome, prettier         |
 | Svelte                | ✓   | lsp                                                                                                            | oxfmt (needs `svelte` pkg installed + config `svelte: true`) |
 | Vue                   | ✓   | lsp                                                                                                            | prettier, oxfmt         |

package/docs/pi-lens-fixer.md

@@ -0,0 +1,25 @@
+# Fixer contract
+
+Deliver a root-caused fix with red proof and a reviewable handoff.
+
+Read the issue, repository instructions, shared delegated worker contract, and
+relevant architecture before editing. Reuse the shared seam and existing
+machinery. Keep the change localized and compatible with concurrent branches.
+
+Build the smallest faithful reproduction first. Preserve its pre-fix failure
+output. After fixing, prove every new guard mutation-sensitive. Run a pattern
+sweep and a population sweep for the defect class. Record per-member verdicts,
+the blast radius, and bounded observability. Add a changelog fragment for a code
+change.
+
+## Tautological tests considered harmful
+
+Do not assert a value that the test setup already supplied, duplicate the source
+predicate in the test, or replace a real in-process seam with a fake to keep the
+test green. Drive the production path and assert an independent observable. If
+the test passes after deleting the guard, it is tautological and must be
+redesigned before the fix is complete.
+
+Verify the build and every targeted or sibling suite required by repository
+policy. Follow the shared contract's Git authority. Report what ran, what was
+skipped, and why. Use active, plain prose.