pi-lens 4.4.11 → 4.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/CHANGELOG-USER.md +12 -12
  2. package/CHANGELOG.md +202 -0
  3. package/README.md +104 -217
  4. package/dist/{chunk-34RXPR7M.js → chunk-27JQHK7Y.js} +1 -1
  5. package/dist/{chunk-W6VLB6LL.js → chunk-2APSZHHI.js} +61 -3
  6. package/dist/{chunk-NLRKB32C.js → chunk-2H5GHZKC.js} +8 -8
  7. package/dist/{chunk-BJDB7PXU.js → chunk-2H7NFZ4Q.js} +11 -11
  8. package/dist/{chunk-OC4ZGVMH.js → chunk-37IDWT6O.js} +65 -19
  9. package/dist/{chunk-A4HKPAEN.js → chunk-3PAS2ERX.js} +8 -8
  10. package/dist/{chunk-DNB4ZQGN.js → chunk-3PO4YYOX.js} +9 -17
  11. package/dist/{chunk-SQBDX6IO.js → chunk-3QXFUP6T.js} +11 -11
  12. package/dist/{chunk-YVPB5YGO.js → chunk-3TSMQZG6.js} +32 -11
  13. package/dist/{chunk-3C6ZZAB2.js → chunk-4DAHGU3V.js} +16 -17
  14. package/dist/{chunk-BN36MQW5.js → chunk-4IZZEN63.js} +33 -36
  15. package/dist/{chunk-OYXD2MOM.js → chunk-5HBQL7DH.js} +2 -2
  16. package/dist/{chunk-B4FAFEBP.js → chunk-5JB4WENL.js} +1 -1
  17. package/dist/chunk-5YJXF2IS.js +56 -0
  18. package/dist/{chunk-AVOUHMCS.js → chunk-6CFSDLHE.js} +22 -18
  19. package/dist/{chunk-C4ICGFEO.js → chunk-6E5QLMWI.js} +24 -22
  20. package/dist/{chunk-WBXCIRVI.js → chunk-6GLMMGCX.js} +2 -2
  21. package/dist/{chunk-C2REOMPO.js → chunk-74AMPWNC.js} +2 -2
  22. package/dist/{chunk-K2GV34T2.js → chunk-7CLWC2UH.js} +26 -37
  23. package/dist/{chunk-NQFXN5U7.js → chunk-7DPXUPRF.js} +2 -2
  24. package/dist/{chunk-QAM2Q3VO.js → chunk-7U36VQL6.js} +2 -2
  25. package/dist/{chunk-2SD2CGVH.js → chunk-7WKVCZI4.js} +1 -1
  26. package/dist/{chunk-R2VUZZPJ.js → chunk-7ZVTFLCC.js} +10 -10
  27. package/dist/{chunk-IT7MFVGP.js → chunk-ADYQRETD.js} +2 -2
  28. package/dist/{chunk-532X3OCZ.js → chunk-ARTYCUGF.js} +28 -15
  29. package/dist/{chunk-DBAHJFBU.js → chunk-AXAR5ZW2.js} +228 -112
  30. package/dist/{chunk-KNP4ENFT.js → chunk-AZG5UJYY.js} +1 -1
  31. package/dist/{chunk-ITAPXBIB.js → chunk-B2OXE4AH.js} +60 -21
  32. package/dist/{chunk-PSUXESQ5.js → chunk-B42AIWPJ.js} +2 -2
  33. package/dist/{chunk-AJ62EQIQ.js → chunk-BBSDJTOV.js} +18 -16
  34. package/dist/{chunk-R2UF54ON.js → chunk-BKWFDWYM.js} +16 -16
  35. package/dist/{chunk-ZD4KVFXI.js → chunk-C5PLBTNR.js} +172 -3
  36. package/dist/{chunk-SRXYSLMW.js → chunk-CQY2HEH7.js} +1 -1
  37. package/dist/{chunk-7424ANRU.js → chunk-CXQYK4YT.js} +1 -1
  38. package/dist/{chunk-WXMUGUZV.js → chunk-CZJGAOKL.js} +8 -7
  39. package/dist/{chunk-QUZYRDT6.js → chunk-DCA2MXVQ.js} +11 -11
  40. package/dist/{chunk-HASJPQBC.js → chunk-DFKOA74L.js} +9 -9
  41. package/dist/{chunk-AYDE7RFV.js → chunk-DI4AZZNY.js} +2 -2
  42. package/dist/{chunk-GL6J5R34.js → chunk-G53LBDNU.js} +99 -5
  43. package/dist/chunk-GCSDF5IE.js +27 -0
  44. package/dist/{chunk-KBSC5Z3G.js → chunk-H5API74E.js} +6 -6
  45. package/dist/chunk-HBX55MWO.js +27 -0
  46. package/dist/{chunk-6RXMQYNU.js → chunk-HIJ4CHFF.js} +2 -2
  47. package/dist/{chunk-NWK7KKNO.js → chunk-HIRBC72R.js} +4 -4
  48. package/dist/{chunk-4WWPDMRA.js → chunk-HRLF35WL.js} +8 -8
  49. package/dist/{chunk-NR4KQOXZ.js → chunk-I2FYOZNW.js} +9 -9
  50. package/dist/{chunk-VDMF7Q2P.js → chunk-I3NZVAMN.js} +9 -9
  51. package/dist/{chunk-DPDA3ILA.js → chunk-INBK3HIT.js} +3 -3
  52. package/dist/{chunk-VI3BJMZO.js → chunk-J2ZB5MDS.js} +22 -24
  53. package/dist/{chunk-6XNVY3FW.js → chunk-JGUDT5KD.js} +4 -4
  54. package/dist/chunk-JOIKBUQN.js +88 -0
  55. package/dist/{chunk-VTXJAO5R.js → chunk-K4Z7MK6T.js} +169 -165
  56. package/dist/{chunk-GTNO6F6K.js → chunk-K7O6AHSJ.js} +10 -10
  57. package/dist/{chunk-WMCAEP2K.js → chunk-KNJH6WJQ.js} +6 -6
  58. package/dist/{chunk-SUIZOCSY.js → chunk-KNSOA43J.js} +1 -1
  59. package/dist/{chunk-OP5BMZKK.js → chunk-KXGTLAUW.js} +2 -2
  60. package/dist/{chunk-BLL4VYGZ.js → chunk-KZ732ZVW.js} +1 -1
  61. package/dist/{chunk-TRYOYWWU.js → chunk-L6BDRYUK.js} +19 -17
  62. package/dist/{chunk-FVEEEEIM.js → chunk-LGH2HHZG.js} +24 -6
  63. package/dist/{chunk-3R3Z54J7.js → chunk-LOEJFTF2.js} +1 -1
  64. package/dist/{chunk-HGEE5LDW.js → chunk-LQQNFCQJ.js} +1 -1
  65. package/dist/chunk-LVLPA32Q.js +810 -0
  66. package/dist/chunk-M2YMBT5G.js +73 -0
  67. package/dist/{chunk-KX4DF6XX.js → chunk-MJRGPEQ5.js} +11 -11
  68. package/dist/{chunk-3QCI3V6C.js → chunk-MOAVEPC4.js} +10 -10
  69. package/dist/{chunk-AFNPNHJV.js → chunk-NGNBJIUO.js} +7 -7
  70. package/dist/{chunk-AGEQRJ5A.js → chunk-NHA5K226.js} +1 -1
  71. package/dist/{chunk-HTUG7ZFK.js → chunk-NNEQOC3U.js} +31 -59
  72. package/dist/{chunk-6K4X7IIF.js → chunk-O2MHF7QM.js} +35 -38
  73. package/dist/{chunk-4HNBY7S7.js → chunk-OLWGYBYT.js} +15 -18
  74. package/dist/{chunk-IBEYUBCM.js → chunk-OZQQ3AIR.js} +17 -20
  75. package/dist/{chunk-LXE7JAMV.js → chunk-P5MSLVUW.js} +10 -10
  76. package/dist/{chunk-TBE4OLPA.js → chunk-PFJLYRO3.js} +37 -40
  77. package/dist/chunk-PKWEBMCA.js +2957 -0
  78. package/dist/{chunk-LHU6NG5Z.js → chunk-PPQHMSPH.js} +16 -15
  79. package/dist/{chunk-6EIV3H7O.js → chunk-PQF6YGYB.js} +12 -5
  80. package/dist/{chunk-BBJXIZ3X.js → chunk-PQXUZYTQ.js} +6 -35
  81. package/dist/{chunk-IJ55MYO6.js → chunk-Q7J3JYJ2.js} +13 -12
  82. package/dist/{chunk-BMMRLJA4.js → chunk-QE5DJ7MX.js} +27 -10
  83. package/dist/{chunk-E6Z3CJT2.js → chunk-QE7BJQ6K.js} +7 -7
  84. package/dist/{chunk-UY3WWW5R.js → chunk-QMWKSYWB.js} +4 -4
  85. package/dist/{chunk-QJ4T73J5.js → chunk-QV3JPCMK.js} +1 -1
  86. package/dist/{chunk-3NVGBFJS.js → chunk-R4L7KZ7R.js} +5 -5
  87. package/dist/{chunk-KDMJ2DJD.js → chunk-RIH3UBK4.js} +10 -10
  88. package/dist/{chunk-T5EGSBM2.js → chunk-RJ3APNIP.js} +3 -3
  89. package/dist/{chunk-D5L7Q57Z.js → chunk-S6MCMD27.js} +35 -12
  90. package/dist/{chunk-LPM6NKVI.js → chunk-SCU62JLX.js} +6 -6
  91. package/dist/{chunk-LHCDWFDB.js → chunk-SDYLT45T.js} +3 -3
  92. package/dist/chunk-TFKN5EIR.js +27 -0
  93. package/dist/{chunk-TPMBNWHO.js → chunk-TKOFTLGB.js} +34 -26
  94. package/dist/chunk-TQWRH25U.js +35 -0
  95. package/dist/{chunk-QBUSONNE.js → chunk-TWEOJE3D.js} +307 -74
  96. package/dist/{chunk-5RLEDUUE.js → chunk-UN72ZAJ5.js} +8 -8
  97. package/dist/{chunk-LIDFFCZZ.js → chunk-UNP6Y4JV.js} +16 -16
  98. package/dist/{chunk-HIUVHRLM.js → chunk-VGRGW4UL.js} +63 -57
  99. package/dist/{chunk-AOQKQWZU.js → chunk-VSQT6IHZ.js} +2 -2
  100. package/dist/{chunk-B4K6OSLL.js → chunk-VWEBZ2JV.js} +39 -40
  101. package/dist/chunk-W26QZ3OM.js +355 -0
  102. package/dist/{chunk-KDGKKK7A.js → chunk-XDNWR7SG.js} +2 -2
  103. package/dist/{chunk-TTGDTNSN.js → chunk-XSC3BCN3.js} +5 -5
  104. package/dist/{chunk-ME6MF2N2.js → chunk-YCR6ZYTE.js} +1 -1
  105. package/dist/{chunk-QDZ3ZZMY.js → chunk-ZI7YHV6I.js} +5 -5
  106. package/dist/{chunk-E3PNZDPH.js → chunk-ZQSSO7LO.js} +33 -1
  107. package/dist/{chunk-ECYUBKYX.js → chunk-ZULZS2I6.js} +391 -410
  108. package/dist/index.js +7314 -5703
  109. package/dist/mcp/analyze-cli.js +11 -13
  110. package/dist/mcp/cli.js +39 -40
  111. package/dist/mcp/server.js +618 -360
  112. package/dist/mcp/worker.js +57 -60
  113. package/dist/probes/installer.js +19 -17
  114. package/docs/agent-tools.md +54 -12
  115. package/docs/architecture.md +113 -0
  116. package/docs/ast-grep_rules_catalog.md +2 -2
  117. package/docs/ci.md +18 -4
  118. package/docs/configuration.md +3 -3
  119. package/docs/defect-shapes.md +41 -3
  120. package/docs/dependencies.md +10 -10
  121. package/docs/features.md +3 -3
  122. package/docs/globalconfig.md +8 -1
  123. package/docs/invariants/dispatch-runners.md +13 -1
  124. package/docs/invariants/lsp-trust-exec.md +26 -0
  125. package/docs/language-coverage.md +39 -0
  126. package/docs/lsp-capability-matrix.md +10 -4
  127. package/docs/lsp-idle-eviction.md +1 -1
  128. package/docs/mcp.md +2 -1
  129. package/docs/pi-lens-fixer.md +4 -0
  130. package/docs/pi-lens-merge-policy.md +1 -1
  131. package/docs/pi-lens-reviewer.md +4 -5
  132. package/docs/pi-lens-subagent.md +5 -2
  133. package/docs/prose-standard.md +112 -0
  134. package/docs/servercapabilities.md +1 -1
  135. package/docs/usage.md +51 -1
  136. package/package.json +1 -1
  137. package/rules/ast-grep-rules/rule-tests/array-callback-return-js-test.yml +23 -0
  138. package/rules/ast-grep-rules/rule-tests/array-callback-return-test.yml +23 -0
  139. package/rules/ast-grep-rules/rule-tests/no-negation-in-equality-check-js-test.yml +8 -0
  140. package/rules/ast-grep-rules/rule-tests/no-negation-in-equality-check-test.yml +8 -0
  141. package/rules/ast-grep-rules/rule-tests/unchecked-throwing-call-js-test.yml +16 -0
  142. package/rules/ast-grep-rules/rule-tests/unchecked-throwing-call-test.yml +16 -0
  143. package/rules/ast-grep-rules/rules/array-callback-return-js.yml +8 -0
  144. package/rules/ast-grep-rules/rules/array-callback-return.yml +8 -0
  145. package/rules/ast-grep-rules/rules/no-negation-in-equality-check-js.yml +17 -5
  146. package/rules/ast-grep-rules/rules/no-negation-in-equality-check.yml +17 -5
  147. package/rules/ast-grep-rules/rules/unchecked-throwing-call-js.yml +8 -1
  148. package/rules/ast-grep-rules/rules/unchecked-throwing-call.yml +8 -1
  149. package/rules/tree-sitter-queries/typescript/ts-react-antipatterns.yml +8 -0
  150. package/dist/chunk-3HZ6MNB2.js +0 -140
  151. package/dist/chunk-43KD3PPM.js +0 -162
  152. package/dist/chunk-5YTDZ5WP.js +0 -38
  153. package/dist/chunk-CKEQFGLT.js +0 -32
  154. package/dist/chunk-F37CCZUA.js +0 -27
  155. package/dist/chunk-JSQK5DH3.js +0 -256
  156. package/dist/chunk-R5BNSOIV.js +0 -29
  157. package/dist/chunk-RV5VX2XW.js +0 -29
  158. package/dist/chunk-UELHWF5I.js +0 -1037
  159. package/dist/chunk-UG4YLCJ5.js +0 -58
  160. package/dist/chunk-UQ6OZYTO.js +0 -91
  161. package/dist/chunk-V7IPIAE5.js +0 -74
  162. package/dist/chunk-YUF4DRYB.js +0 -2417
package/CHANGELOG-USER.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # User changelog
2
2
 
3
+ ## [4.5.0] - 2026-11-14
4
+
5
+ 31 fixes, 2 other changes.
6
+
7
+ Full notes: https://github.com/apmantza/pi-lens/releases/tag/v4.5.0
8
+
9
+ ## [4.4.12] - 2026-11-10
10
+
11
+ 1 feature, 2 fixes.
12
+
13
+ Full notes: https://github.com/apmantza/pi-lens/releases/tag/v4.4.12
14
+
3
15
  ## [4.4.11] - 2026-11-09
4
16
 
5
17
  32 fixes, 2 other changes.
@@ -17,15 +29,3 @@ Full notes: https://github.com/apmantza/pi-lens/releases/tag/v4.4.10
17
29
  3 features, 29 fixes, 8 other changes.
18
30
 
19
31
  Full notes: https://github.com/apmantza/pi-lens/releases/tag/v4.4.9
20
-
21
- ## [4.4.8] - 2026-11-01
22
-
23
- 1 feature, 28 fixes, 6 other changes.
24
-
25
- Full notes: https://github.com/apmantza/pi-lens/releases/tag/v4.4.8
26
-
27
- ## [4.4.7] - 2026-10-29
28
-
29
- 2 features, 21 fixes.
30
-
31
- Full notes: https://github.com/apmantza/pi-lens/releases/tag/v4.4.7
package/CHANGELOG.md CHANGED
@@ -16,6 +16,208 @@ All notable changes to pi-lens will be documented in this file.
16
16
 
17
17
  ### Security
18
18
 
19
+ ## [4.5.0] - 2026-11-14
20
+
21
+ ### Changed
22
+
23
+ #### Runners and scanners
24
+
25
+ - **Formatter and linter config checks now stop at your home directory.** A `.clang-format`, `.oxlintrc.json`, `.prettierrc` or similar file above `$HOME` no longer selects its tool, and a commented or look-alike gem in a Gemfile no longer selects rubocop or standardrb. (refs #5408)
26
+
27
+ - **Kotlin formatter and Svelte config-file checks now stop at your home directory.** A `.ktfmt` file, a Spotless block or an `oxfmt.toml` above `$HOME` no longer selects ktfmt, ktlint or oxfmt for `.svelte`. Helm, Trivy, golangci-lint, detekt and Java also check their binary once per working directory now, so a lint run and its autofix in the same directory no longer probe the same tool twice. (refs #5408, #5410)
28
+
29
+ ### Fixed
30
+
31
+ #### Language servers
32
+
33
+ - **Public Rust functions now bring their callers into the neighbour cascade.** The cascade asked the language server at the `pub` keyword, where rust-analyzer returns no references, so an edit to a `pub fn` listed no dependents. It now asks at the function name, and methods in the other tree-sitter languages get the same position. (refs #5559)
34
+
35
+ - **`lens_diagnostics` in full mode now keeps one rule's findings apart when their columns differ.** Findings that share a rule and line now stay separate by column. LSP hints were already listed as warnings; only their semantic label now matches the CLI advisory tier. (refs #5412)
36
+
37
+ - **A cold Deno server now gets seven seconds on diagnostics calls, not on edits.** The pull wait fell back to the 1.5 second default, so a first check on a slow machine was abandoned and read as no answer. Per-edit checks stay capped at 2.5 seconds and the MCP warm-up at 6 seconds. The budget is only a ceiling, so a fast Deno answer returns at once. (refs #5464)
38
+
39
+ - **ElixirLS document symbol requests no longer fail on an omitted capability.** The client explicitly declares support for hierarchical document symbols while continuing to accept flat responses. Definition fallback uses the symbol name range so navigation and search-read coverage do not include the whole body. (refs #5476)
40
+
41
+ - **A cold Rust touch no longer reads clean while rust-analyzer is still loading.** The language server now says when it has finished loading, and the diagnostics read waits for that. If the wait runs out first, the result says the server is still loading. A workspace that failed to load (a broken manifest) is named with the server's message and a hint to fix the manifest. Neither case reads as a clean file. (refs #5487)
42
+
43
+ - **A fixed `Cargo.toml`, `go.mod` or `go.work` at the project root now reaches the running language server.** Before, rust-analyzer kept reporting that its workspace failed to load, and gopls kept an old `go` version's findings, until the server restarted. The manifest or workspace file at the project root is sent as a watched-files event when it changes outside the editor session. (refs #5501)
44
+
45
+ - **TypeScript 7 installed as `@typescript/native` now runs the native language server.** With `node_modules/typescript` at version 6 or older, pi-lens launches the alias's own `bin/tsc` with Node. An `effect-tsgo` that exits during startup now falls back to the native launch, and an alias that cannot start falls back to the classic server, so JavaScript and TypeScript files keep a language server. (refs #5504)
46
+
47
+ - **LSP command arguments opt out of strict schema conversion.** `lsp_navigation` advertises the full JSON value space for `commandArguments` without a strict opt-in, so providers can receive object arguments unchanged. Live confirmation on a strict-schema provider remains outstanding. (refs #5506)
48
+
49
+ #### Blockers and sessions
50
+
51
+ - **The footer keeps every file with findings visible.** Two files sharing a basename no longer collapse into one footer row. Rows are keyed on the file path and same-named files show enough of the parent directory to tell them apart, so a blocking file can no longer hide behind a clean one and the header keeps counting every recorded file. (refs #5460)
52
+
53
+ - **A blocker you cannot fix now reaches the agent in full at most three times.** After that, each prompt gets a one-line pointer to `lens_diagnostics` for it, however many other blockers are raised or fixed meanwhile. The blocker stays listed there and still blocks a `--lens-guard` commit, a fix stops the pointer at once, and a blocker re-raised with changed content gets three full deliveries again. (refs #5532)
54
+
55
+ #### Runners and scanners
56
+
57
+ - **`ast_grep_search` and `ast_grep_replace` stop answering "no matches" in some checkouts.** A rule-mode scan now runs inside the tree it scans, so the project's own ignore globs match paths relative to the scan root instead of an ancestor that happens to be named `.claude` or `build`; reported match paths stay absolute. The `npx` fallback keeps its isolated child cwd, while repository trees use native ignore handling and marker-less trees retain the project's own exclude globs. A glob or path you passed the tool yourself is still matched unchanged. (refs #5545)
58
+
59
+ - **A slow runner no longer piles up processes across edits.** A runner whose process outlives the dispatch budget, such as SpotBugs or Trivy Config, now holds its slot until that process exits, so the next edit joins the running check instead of starting another one. SpotBugs and Trivy Config also declare their existing spawn timeouts. (refs #5547)
60
+
61
+ - **A file whose checks were all skipped now says why it was not checked.** The write notice names each runner's cause (`spellcheck: not installed`, `vale: not configured`, a managed install turned off by `PI_LENS_DISABLE_TOOL_INSTALL=1`, a version probe that timed out or was rejected, a project binary that pi trust refused, a missing Java runtime, a project policy that prefers another tool) instead of one sentence for a missing tool, a timeout and a failure alike. Nothing that was unchecked reads clean. (refs #5258)
62
+
63
+ - **A tool config above your home directory no longer counts as project config.** ESLint, Biome, golangci-lint, PHPStan, Stylelint, markdownlint, Vite+, Vale, ShellCheck and the Java build check now stop their config search at your home directory, and a `vite.config` that only mentions `vite-plus` in a comment no longer selects the Vite+ tools. ShellCheck also reads a `.shellcheckrc` beside the script. (refs #5408)
64
+
65
+ - **Formatters now find their tool the way the linters do.** A formatter no longer runs a parent directory's Python virtualenv (a monorepo whose only venv sits at the repo root must put black on PATH), and a broken copy on PATH no longer hides a working managed install of shfmt, taplo, ktlint, ktfmt, typstyle, black, google-java-format or cljfmt. The order is the project's own tool, then PATH, then the managed copy: a working PATH formatter still wins, so a team that pins its formatter version is not overridden. A formatter that is installed but fails its version check is reported as failed, with its error output, instead of "not found", and a broken sqlfluff is no longer run and read as an unchanged file. (refs #5410)
66
+
67
+ - **oxlint and ESLint now run in the directory of their config.** A repo-root config with a path that a plugin resolves from the working directory no longer reports false findings for files under a nested workspace package, while the lint policy and the install lookup stay in the package. (refs #5541)
68
+
69
+ - **Lint findings now appear for files a linter had silently skipped.** `yamllint` and `markdownlint` were handed the absolute path of the dispatched file, and both match their config's ignore globs against that string, so a glob naming an ancestor of the file (such as `**/.claude/**` inside a `.claude/worktrees/` lane) skipped the file: the tool answered "no files selected", exited 0, and the runner reported a clean file it had never linted. Both now receive the path relative to the project, the form `actionlint` already uses, so a root-anchored ignore such as yamllint's `/src/` or markdownlint's `/src/**` now skips the files under it, which the absolute path had linted. A root-level name such as `-a.yml`, `#a.md` or `:a.md` is still read as a path, and `--fix` gets the same argument. (refs #5544)
70
+
71
+ - **Oxlint now lints files in ignored-ancestor worktrees.** The lint and autofix
72
+ paths now pass the project-relative file argument, so an `.eslintignore` glob
73
+ naming an ancestor cannot silently make oxlint skip the dispatched file.
74
+ A root-level name such as `-D.ts` is still read as a path, not an oxlint
75
+ option. Findings remain attributed to the dispatched path. (refs #5556)
76
+
77
+ - **Ruff autofix now uses the lint runner's resolved Ruff command.** Nested packages whose own `.venv` holds the only Ruff no longer get skipped when dispatch starts at a workspace root. (refs #5410)
78
+
79
+ - **A Gradle edit that keeps its timestamp now changes the Kotlin formatter pi-lens picks.** The Spotless check in `build.gradle(.kts)` remembered its answer by modification time alone, so a rewrite that kept the time (a copy that preserves times, an archive extract) and changed the length still read as the old `ktlint` or `ktfmt` choice. It now compares the length too. (refs #4907)
80
+
81
+ #### Rules
82
+
83
+ - **Four bundled rules now report far fewer false positives.**
84
+ `array-callback-return` exempts async callbacks and
85
+ `no-negation-in-equality-check` exempts double-negation comparisons in both
86
+ language twins, `ts-react-antipatterns` reports only files that import a
87
+ React or React-like hook source or contain JSX, and
88
+ `unchecked-throwing-call` drops to `warning` and documents that its `try`
89
+ check is lexical. (refs #5466)
90
+
91
+ #### Tools and reports
92
+
93
+ - **Esc now stops an `ast_grep_replace` apply's precheck.** The structural-rule precheck carries the call's abort signal, so a host with no tool scope stops it too. Esc does not stop the `--update-all` write once it starts: the write runs to completion, so an Esc leaves 0 or all matched files rewritten. (refs #5097)
94
+
95
+ - **pi-lens no longer calls a file clean when its check did not finish.**
96
+ The `lens_diagnostics` header and its check line say "unconfirmed" when a
97
+ full sweep stopped early, an analyzer failed, ran partly or was stopped,
98
+ a file changed after its last check or still has a check pending, or a
99
+ shown finding is stale. Delta mode reports "no new findings" instead of
100
+ "clean". Knip exiting with no report is named as unread, not "No issues
101
+ found". A warning re-check keeps each warning whose code-action lookup
102
+ never answered, and still retires the ones it confirmed fixed. (refs #5258)
103
+
104
+ - **A wedged formatter no longer starts a new child on every write.** Writes that one formatter handles in one project now wait their turn, so a hung child is never joined by a second one. Once a child runs out its own time, later writes skip that formatter for the session with a recorded reason, and a repeated deferred format failure is retried once. (refs #5549)
105
+
106
+ - **`/lens-allow-edit`, `effective_config` and the MCP analyze and turn-end tools read `~` and `@` paths.** They resolved a path such as `@src/a.ts` or `~/proj/a.ts` to a file that cannot exist, so `/lens-allow-edit` armed nothing, `effective_config` reported on a missing file, and `pilens_analyze` and `pilens_turn_end` checked a ghost path. They now resolve it as pi does, `pilens_analyze` reads a `~` cwd as the home directory, and `pilens_turn_end` no longer counts a file outside the workspace as registered. (refs #4907)
107
+
108
+ #### Install and updates
109
+
110
+ - **CMake language-server installs now refuse unsupported Python versions visibly.** The package floor prevents Python 3.14 from silently selecting 0.1.5, and nightly tool-smoke uses a pinned Ubuntu image. (refs #5561)
111
+
112
+ #### Hosts and integrations
113
+
114
+ - **Warm IPC never crosses workspaces under a long temporary directory.** Bind and connect use the bounded Unix socket path, so a `TMPDIR` that cuts only the `.sock` suffix keeps the warm side channel on hosts that reject an over-long socket path with `EINVAL`. A longer `TMPDIR` cuts the workspace identity out of the name: the MCP server does not bind it, no hook dials it, the server logs that the warm side channel is unavailable, and hooks fall back to cold analysis. (refs #4353)
115
+
116
+ - **Reloading the extension no longer slows every async operation a little more.** The spawn cancellation and cooldown scopes are now one per process instead of one per reload, so a long session that reloads pi-lens stays as fast as a fresh one. (refs #5182, #5413)
117
+
118
+ - **Bash overwrites that keep an old mtime are now seen.** A recognized `mv` or `cp -p` into a file that was clean before the command now reaches the normal dispatch path, including from a package-subdirectory session, even when the destination keeps its source's old modification time. A file you had already edited is still judged by mtime. (refs #5552)
119
+
120
+ #### Security
121
+
122
+ - **A secret found by gitleaks and trivy now shows as one blocker row.** The turn-end report used to list the same line twice, once per scanner, because gitleaks cites an absolute path and trivy a path relative to its scan root. A secret only trivy finds now also drops its ast-grep copy from the fixable-warnings advisory. (refs #5459)
123
+
124
+ - **A project under a scratch-named parent directory now keeps its scan results.** A checkout under `.claude/worktrees/<lane>` or a `.pi-lens` temp root had every gitleaks finding dropped or demoted, so the turn-end secrets blocker never fired. Opengrep and vulture also skipped the whole project there. Scratch directories are now judged below the project root only, and a gitleaks or trivy scan of a symlinked project root now scans the real directory instead of reporting nothing. (refs #5500)
125
+
126
+ ### Internal
127
+
128
+ <details>
129
+ <summary>27 internal changes: tests, CI, tooling, and refactors</summary>
130
+
131
+ - The clean-claim census owner test now carries a planted-stale-row cell, so master's baseline-owner governance is green again. (refs #5072)
132
+
133
+ - Move the documentation and prose standard to `docs/prose-standard.md`, name its sources, add the judgement-only ASD-STE100 rules and the collapsed comment layout, and add a pointer-only `write` skill. (refs #5510)
134
+
135
+ - The comment layout rule is now a repo check, `node scripts/check-prose.mjs --comment`: a comment over 12 lines needs at most 8 visible lines and a model-named fold. (refs #5558)
136
+
137
+ - **Generation-ledger stamp tests no longer follow the temp path length.** Five cells in three test files matched the end of a record whose text the ledger bounds at 200 characters, so a long `TMPDIR` cut the tail and reddened them. They now select each record by the bounded rendering of the identity its producer writes, and one cell pins the stamp's size component where it decides behaviour: the resolver's verdict memo. (refs #5575, #5576)
138
+
139
+ - **The cold-cache strict install now runs from its own workflow file.** `strict-install.yml` triggers on a master push and a manual dispatch only, so a pull request no longer shows a skipped `Strict install` row; the merge queue and the bot-PR dispatch no longer run it. (refs #5002)
140
+
141
+ - Shard 5 prints a per-file census of managed processes whose owner pid is dead, naming the test file whose worker spawned each (refs #5528).
142
+
143
+ - Join the registered deferred writers before `tests/index-3814-deferred-blocker-gate.test.ts` removes its witness home, watch the removed path, and spell the home at an `mkdtempSync` call the tmp-fixture census can attribute. (refs #5098)
144
+
145
+ - **Test witnesses wait for marker content, not existence.**
146
+ An empty marker can release a waiter that reads a report path or PID
147
+ from it. The scanner, tool-abort and madge witnesses, and the mutate
148
+ and outside-root waits, now wait for nonempty marker content.
149
+ (refs #5105)
150
+
151
+ - Require explicit boolean npm cache intent for every setup-node step, scope workflow writes to jobs, and cancel superseded PR scans. (refs #5182)
152
+
153
+ - Read `vi.doMock` in the whole-module mock-export sweep. Only hoisted `vi.mock` skips an importer, and the flake-shape scan and the trust-seam ratchet share one registration list. (refs #5256)
154
+
155
+ - **The test harness opts the loaded extension copy out of arming the orphan backstop.** `startPiSession` holds `PI_LENS_DISABLE_ORPHAN_BACKSTOP=1` across a tier-2 session start and `scheduleUntrackedOrphanSweep` reads it at arm time, so a harness session cannot SIGKILL fixture processes whose owner tags point at pids the harness already reaped. The key is a harness knob, not a supported user setting: `vitest-setup` scrubs a shell's value, and the spelling and the literal `"1"` contract are pinned by `tests/support/pi-session.test.ts` and `tests/clients/env-boolean-knob-literals.test.ts`. (refs #5267)
156
+
157
+ - The pre-push gate pins its own temp root instead of inheriting the caller's `TMPDIR`: `scripts/pre-push-targeted-tests.mjs` resolves `<PI_LENS_HOME or ~/.pi-lens>/prepush-tmp` (falling back to `~/.pi-lens/prepush-tmp`, with one notice line, when a `PI_LENS_HOME` base sits at or inside the checkout, where Vitest's worker home would trip the home-ceiling guard), creates a fresh real `run-*` directory for each run, removed after completion (including failure); interrupts first terminate and drain the owned wrapper and Vitest tree, and a drain timeout preserves the original directory with a warning, and points `TMPDIR`/`TEMP`/`TMP` there before any build, self-scan, selection, or test spawn, so macOS's long, symlinked `/private/var/folders/...` root can no longer red path-sensitive tests on the same commit that passes under a short real root. Allocation uses the existing scratch owner seam rather than a special hygiene admission. `PI_LENS_PREPUSH_TMPDIR` is the operator escape hatch, and the startup line records the resolved root and the caller's value (refs #5439). At startup the pre-push gate removes stale `run-*` directories left by detached late writers, preserves live scratch owners, and skips unsafe entries with one degradation line (refs #5439).
158
+
159
+ - Delete two wait-strategy rows keyed by names no LSP server has (`rust-analyzer`, `eslint`), measure why rust must not be re-keyed as it was, and fail any strategy key that is not a registry id. (refs #5485)
160
+
161
+ - **The server-teardown admission re-check now classifies each admitted file once.** Four admitted rows named three files, and the guard read and parsed each file again per row and again for the mechanism, so the case cost 1.07 s on Linux and timed out once at 5000 ms on the Windows leg (#5508). It now reads and classifies each distinct file once and checks every row against that one classification, which cut it to about 0.2 s on Linux. The Windows leg did not get faster (1.48 s on this change), so the fix there is a scaled 20 s budget in place of vitest's 5 s default. Every row is still re-checked, and a new case pins that one binding's close evidence no longer carries another's. (refs #5508)
162
+
163
+ - Run the `/lens-perf` render cell under a pinned trusted project, so a spawn left in flight can no longer add a `trust-refusal` row to its exact-list assertion. (refs #5509)
164
+
165
+ - Reach the workspace-glob memo cap from a 119-character member path instead of a 1,415-character one (the server-policy Cargo cell and the uv consumer cell no longer hit macOS `PATH_MAX`), and pass the generated pre-push probe's paths and argv through environment variables instead of interpolating them into its source (resolves CodeQL alerts 83 and 84). (refs #5521)
166
+
167
+ - The nightly capability doc keeps the raw-capability intro above carried server bullets (refs #5526).
168
+
169
+ - The #3179 race test drops `-p` from its churner `mkdir`, so a late writer cannot recreate the temp root the test removed (#5527).
170
+
171
+ - The pre-push gate's default temp root moves from `~/.pi-lens/prepush-tmp` to `~/.local/share/pi-lens-prepush`, outside every path `isPiLensInternalPath` treats as pi-lens-owned, so fixtures built under `os.tmpdir()` are no longer dropped and the turn-scenarios gitleaks cell stops redding every push that selects it (refs #5536).
172
+
173
+ - The turn-id observability test drains every log sink before it removes its temp home, so a row queued by its last case no longer recreates the directory during teardown (refs #5569).
174
+
175
+ - Join the `session_start` global-bin-dir prime in the test harness's background-write drains, so a tier-2 session's late `spawn_resource_usage` row no longer re-creates its removed fixture home and reds `tmp-fixture-hygiene`. (refs #4909)
176
+
177
+ - **Three hand-written realpath fallbacks now answer through the path-identity seam.** The probe-home tmpdir and real-home checks, the explicit analysis root of a fresh project run, and the git checkout `root` and `commonDir` now share `realpathOrResolve` and `isWithinIdentity`, and the three `PRE_4689` `raw-realpath` pins are gone. An answer changes only for a missing path spelled through a symbolic link; the fresh-run root answers as before, because its directory check runs first. (refs #4907)
178
+
179
+ - A governance check now fails the suite when a checked-in baseline has no owner test, or an owner that never reddens on a planted stale row. It takes every tracked file, finds baselines by name, by an exported binding name, or by JSON rows that name repo files, and fails on any it cannot place. Twenty baselines are covered, each by a planted-stale-row cell in its owner (refs #5072).
180
+
181
+ - **The run-outcome ratchet now audits `scripts/` and `clients/lsp/`.** A file under either root that starts a child process either routes through `classifyRunOutcome`, or carries a baseline row spelling out how a failed child reaches it (it throws, or it reads `status`/`exitCode`/`signal`/`killed`/`error`); the census follows a spawn that arrives through an import alias, an injected default, a namespace member, or a hand-off, and reports a `require`, a dynamic `import()`, or a re-export it cannot open instead of skipping it. 77 files with 152 spawn sites carry a row today. (refs #5308)
182
+
183
+ - Avoid an unnecessary complexity-analysis wait in path-attribution tests. (refs #5566)
184
+
185
+ - Make the self-scan and dependency-cruiser baselines red on a row nothing matches any more, so a fixed finding or cycle cannot leave a free pass behind. (refs #4907)
186
+
187
+ - Make the label-triage and ci-verdict pagination tests read the bearer header of every page they fetch, drop the kill-signal assertion from the knip purge timeout test (a 1 ms timeout on a real `git` races the child's exit, so only the `ETIMEDOUT` code is stable), and delete a self-asserting install-smoke drift case. (refs #4907)
188
+
189
+ </details>
190
+
191
+ ## [4.4.12] - 2026-11-10
192
+
193
+ ### Added
194
+
195
+ #### Rules
196
+
197
+ - **Edits now name functions they made more complex than main.**
198
+ An edit's result gains one short line, such as
199
+ `⚠ complexity vs main: Store.get cc 12→19 (≥15)`, naming the functions the
200
+ edit itself made worse than the default branch has them, at or past the
201
+ `high-complexity` thresholds (15 and 6 for every language until per-language
202
+ ones exist). A function the edit did not change, or improved, is never
203
+ named; neither is an anonymous callback, and the line waits while the edit
204
+ has blockers. The line is bounded: past its length budget the remaining
205
+ names collapse into `+N more`, and only a file's first 512 functions are
206
+ judged. Outside a repository it compares with the file as it was before the
207
+ edit. `--no-complexity` or disabling `high-complexity` turns it off, and a
208
+ file over 256 KiB is not judged. Owner matching is linear,
209
+ and first touches defer it until an edit reads the baseline. (refs #5087)
210
+
211
+ ### Fixed
212
+
213
+ #### Language servers
214
+
215
+ - **Edits to a project outside the session folder now get language server diagnostics.** An edit to a file in a sibling project (an adopted root) used to report "not analyzed" even while its language server ran. In pi, language servers that run project code, such as rust-analyzer, now start there only when pi itself would trust that project: a saved decision on it or a parent folder, pi's default for a folder without `.pi` resources, or `defaultProjectTrust`. They no longer borrow the session's trust. Under MCP, pi's trust is not read; the MCP client owns workspace trust. (refs #5469)
216
+
217
+ #### Hosts and integrations
218
+
219
+ - **Providers that rejected pi-lens's strict tool schemas work again.** With 4.4.11, opencode-go beam-free failed every turn with “Invalid request” and Amazon Bedrock's Anthropic models with “For 'array' type, property 'maxItems' is not supported”; the five tools whose schemas they rejected no longer request strict mode, and the three that still do use only schema keywords strict mode accepts. (refs #5471, #5480)
220
+
19
221
  ## [4.4.11] - 2026-11-09
20
222
 
21
223
  ### Changed
package/README.md CHANGED
@@ -6,251 +6,131 @@
6
6
 
7
7
  [![omp status](https://omppackages.com/badge/pi-lens.svg)](https://omppackages.com/packages/pi-lens)
8
8
 
9
- pi-lens gives AI coding agents fast, language-aware feedback while they write/edit.
10
-
11
- > **Working in this project as an AI agent?** Read the [agent guide](docs/agent-guide.md)
12
- > for how pi-lens surfaces diagnostics (honesty labels, blockers, read-before-edit)
13
- > and how to respond.
14
-
15
- ## What It Does
16
-
17
- - LSP diagnostics and navigation across supported languages
18
- - Impact cascade diagnostics that show which related files were affected and run LSP diagnostics on them
19
- - Language-specific linters, type-checkers, and scanners on every write/edit
20
- - Safe formatting/autofix where tools are configured or confidently detected
21
- - ast-grep and tree-sitter structural rules for correctness/security smells
22
- - Agent-facing tools for LSP navigation/diagnostics, AST search/replace,
23
- diagnostics state, and project intelligence
24
- - Review-graph intelligence for supported languages via bundled tree-sitter WASMs
25
- - Ranked identifier search (`symbol_search`) over an always-warm word index,
26
- feeding the discovery funnel (symbol_search → module_report → read_symbol)
27
- - Diagnostic triage (`lens_diagnostic_mark`): findings can be marked
28
- false-positive, suppressed in source, deferred, or flagged-to-fix — honored
29
- across all surfaces
30
- - `/lens-map` — interactive HTML dependency map of the project
31
- - Read-guard and edit-autopatch support to reduce bad edits
32
- - Background security/dependency scans for opted-in projects
33
- - Runtime health telemetry (`/lens-health`) including a bounded degradation
34
- ledger for silently-degraded behavior (LSP breakers, formatter
35
- skips/failures, idle evictions, timeouts)
36
- - MCP server (experimental) so Claude Code or any MCP client can drive the
37
- same diagnostics/read-substitute tools pi-lens exposes to pi
38
-
39
- ## Architecture
40
-
41
- Most lifecycle events enter through one wrapper, which drops and counts events
42
- that arrive on a replaced session. `tool_call` registers raw: it delegates
43
- straight to a handler that owns its own total guard. Events fan out into the
44
- edit-time lane and the LSP lane. Both lanes write into the findings stores.
45
- Nothing reaches the agent from those stores until a freshness gate or an
46
- explicit age label clears it.
47
-
48
- ```mermaid
49
- flowchart TD
50
- subgraph host["pi host"]
51
- HOST["Host events<br/>tool_call, tool_result, turn_start/end,<br/>session_start/shutdown, agent_end, context"]
52
- WRAP["Stale-ctx wrapper<br/>skips and counts events on a replaced session<br/>tool_result, turn_start, turn_end, agent_end,<br/>agent_settled, session_start, context"]
53
- end
54
-
55
- subgraph guards["Guards"]
56
- RG["Read-guard<br/>blocks edits that lack prior reading"]
57
- GG["Git-guard<br/>holds commit/push while findings stay unresolved"]
58
- end
59
-
60
- subgraph edit["Edit-time lane"]
61
- PIPE["Post-write pipeline<br/>secrets, format, autofix, sync, lint, tests"]
62
- PLAN["Dispatch plan<br/>per file kind, per capability group"]
63
- RUN["Runners<br/>format, lint, types, security, smells, docs"]
64
- STRUCT["Structural rules<br/>tree-sitter queries and ast-grep"]
65
- BUS["files-touched bus<br/>tells extensions which paths moved"]
66
- end
67
-
68
- subgraph lsp["LSP lane"]
69
- POOL["Client pool<br/>warm reuse, idle eviction"]
70
- DIAGS["File and workspace diagnostics"]
71
- CASC["Impact cascade<br/>tiered wait policy"]
72
- end
73
-
74
- STORES["Findings stores<br/>widget state, warning caches, project snapshot"]
75
-
76
- subgraph gate["Freshness gating"]
77
- FRESH["Path freshness<br/>mtime vs scan time, past-EOF, dependency drift"]
78
- DISPO["Dispositions<br/>false-positive, suppress, defer, flagged"]
79
- LABEL["Explicit age label<br/>for findings no path gate can check"]
80
- end
81
-
82
- subgraph deliver["Delivery surfaces"]
83
- TURN["Turn-end findings injection"]
84
- WIDGET["Widget and footer tally"]
85
- TOOLS["lens_diagnostics tool"]
86
- NUDGE["Agent nudges"]
87
- end
88
-
89
- SESSION["Session lifecycle<br/>primary, sequential replacement, concurrent secondary"]
90
- SINKS["Observability sinks<br/>latency.log, degradation ledger, bounded telemetry,<br/>cache observability, cascade and tree-sitter logs"]
91
- CONFIG["Config-core<br/>resolve, merge, deny"]
92
- REVIEWGRAPH["Review-graph intelligence<br/>call graph, reverse deps, import resolution"]
93
-
94
- HOST --> WRAP
95
- HOST -->|tool_call, raw| RG
96
- HOST -->|tool_call, raw| GG
97
- WRAP -->|session_start| SESSION
98
- WRAP -->|tool_result| PIPE
99
- WRAP -->|tool_result, records reads and writes| RG
100
- SESSION --> POOL
101
- SESSION --> STORES
102
- PIPE --> PLAN
103
- PLAN --> RUN
104
- PLAN --> STRUCT
105
- PIPE --> POOL
106
- PIPE --> BUS
107
- CONFIG --> PIPE
108
- CONFIG --> PLAN
109
- STRUCT --> REVIEWGRAPH
110
- REVIEWGRAPH --> CASC
111
- POOL --> DIAGS
112
- DIAGS --> CASC
113
- RUN --> STORES
114
- STRUCT --> STORES
115
- DIAGS --> STORES
116
- CASC --> STORES
117
- BUS --> NUDGE
118
- RG -->|read and edit history filter| NUDGE
119
- STORES --> FRESH
120
- STORES --> LABEL
121
- FRESH --> DISPO
122
- DISPO --> TURN
123
- DISPO --> WIDGET
124
- DISPO --> TOOLS
125
- LABEL --> TURN
126
- TURN --> GG
127
- WRAP --> SINKS
128
- PIPE --> SINKS
129
- RUN --> SINKS
130
- STRUCT --> SINKS
131
- POOL --> SINKS
132
- CASC --> SINKS
133
- RG --> SINKS
134
- GG --> SINKS
135
- FRESH --> SINKS
136
- ```
137
-
138
- Architecture-level view, updated when a lane changes. Per-tool inventories live
139
- in [features](docs/features.md) and
140
- [language coverage](docs/language-coverage.md). Today the edit-time lane carries
141
- 45+ runner modules over 35+ file kinds, and the LSP lane speaks to 50
142
- language server definitions.
9
+ pi-lens gives AI coding agents fast, language-aware feedback while they write and edit code. It is an extension for the pi coding agent, with an experimental [MCP server](docs/mcp.md) for other hosts.
143
10
 
144
- The gating box is an abstraction, not a call order. Freshness covers several
145
- independent mechanisms: path freshness against scan time, past-EOF line checks,
146
- and forward-import dependency drift. Dispositions are one more filter alongside
147
- them, not a second stage every finding walks through. Read the box as "a finding
148
- passes the gates that apply to it", and see `clients/finding-delivery-gate.ts`
149
- for the per-surface contract.
11
+ > **An AI agent working with pi-lens?** Read the [agent guide](docs/agent-guide.md). It explains the findings you will see and how to respond.
12
+ >
13
+ > **An AI agent changing pi-lens itself?** Read [`AGENTS.md`](AGENTS.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md). A one-line-per-doc index for agents is in [`llms.txt`](llms.txt).
150
14
 
151
- ## Install
15
+ ## Quick start
152
16
 
153
17
  ```bash
154
18
  pi install npm:pi-lens
155
19
  ```
156
20
 
157
- Or from git:
158
-
159
- ```bash
160
- pi install git:github.com/apmantza/pi-lens
161
- ```
21
+ Or from git: `pi install git:github.com/apmantza/pi-lens`.
162
22
 
163
- pi-lens delivers its four skills through the `pi.skills` package manifest, so
164
- install it as a package (`npm:`, `git:`, or a local path); a package install
165
- honours the host's `packages[].skills` filters (for example `[]`,
166
- `!skills/<name>/SKILL.md`, or `-skills/<name>/SKILL.md`). Loading the extension
167
- file directly (`pi --extension ./index.js`) does not read that manifest and
168
- loads no pi-lens skills.
23
+ Requirements: Node.js >=22.19.0 and a pi host of 0.86.1 or newer. On pi 0.80–0.85, pi-lens gives no findings, because those hosts keep the prompt where the extension cannot write to it. [Release QA baseline](docs/release-qa-baseline.md) lists the certified hosts. See [Troubleshooting](#troubleshooting) for npm v12, Android, and skills-manifest notes.
169
24
 
170
- Requires Node.js >=22.19.0 (matches the pi host's own floor — see `engines`
171
- in `package.json`), and a pi host of 0.86.1 or newer. pi 0.80–0.85 keep the
172
- prompt outside the request the extension can write to, so pi-lens delivers no
173
- findings there; `docs/release-qa-baseline.md` lists the certified hosts.
25
+ Install it and start a session. The language servers and many linters start with no setup. Some tools need your project's config, and a few are opt-in. See [What runs by default](#what-runs-by-default) and [Settings](docs/settings.md).
174
26
 
175
- Letting a coding agent do it: paste this into its prompt.
27
+ To let a coding agent install it, paste this into its prompt:
176
28
 
177
29
  ```text
178
- Install pi-lens (npm:pi-lens) into pi, then read AGENTS.md in
179
- https://github.com/apmantza/pi-lens for how the extension works and how it
180
- expects to be operated.
30
+ Install pi-lens (npm:pi-lens) into pi, then read docs/agent-guide.md in
31
+ https://github.com/apmantza/pi-lens for how to read and respond to its findings.
181
32
  ```
182
33
 
183
- > **npm v12 users:** dependency lifecycle scripts (e.g. `@ast-grep/cli`'s
184
- > `postinstall`) now require explicit approval — if `npm install` warns about
185
- > unreviewed install scripts, review and allow them with
186
- > `npm approve-scripts`, or trust the `allowScripts` entries already declared
187
- > in this package's `package.json` (maintainers: see CONTRIBUTING.md
188
- > "Lifecycle-script approvals"). Installing from a git source (`pi install
189
- > git:...` / `pi update --extension git:...`) may similarly prompt for
190
- > git-dependency approval; accept it to let the `prepare` build step run.
34
+ ## What the agent sees
35
+
36
+ After an edit, the tool result carries any blocking findings, with the offending line. At the end of the turn, pi-lens injects the findings that remain. The text below follows the real renderers: the `STOP` block from `clients/pipeline.ts`, and the turn-end framing, `Advisory` label, and warnings summary from `clients/runtime-context.ts` and `clients/runtime-turn.ts`.
191
37
 
192
- ### Android/Termux fallback
38
+ ```text
39
+ 🔴 STOP — 1 issue(s) must be fixed:
40
+ L4: 'randomInt' is declared but its value is never read.
41
+ → const randomInt = Math.floor(result);
193
42
 
194
- Try the normal install first. If it fails in `@ast-grep/cli`'s
195
- `postinstall.js` with `Failed to locate @ast-grep/cli native binary`, the
196
- fallback below has worked in one Termux environment:
43
+ [pi-lens automated check — not a user request] Address 🔴 blockers before continuing; ℹ️ advisories are informational only.
197
44
 
198
- ```bash
199
- pkg install rust clang
200
- cargo install ast-grep --locked
201
- ast-grep --version
202
- npm_config_ignore_scripts=true pi install npm:pi-lens
45
+ ℹ️ Advisory — no action required this turn:
46
+ 🟡 Fixable warnings introduced this turn: 1.
47
+ Use lens_diagnostics with mode=delta to inspect these warnings.
48
+ Files:
49
+ src/app.ts: 1
203
50
  ```
204
51
 
205
- `npm_config_ignore_scripts=true` skips every dependency lifecycle script for
206
- that `pi install` command, not only the failing `@ast-grep/cli` script. Use it
207
- only for this fallback after installing and checking the Rust-built `ast-grep`
208
- binary separately. `pi update` runs the same postinstall, so set the variable
209
- for it too. `ast-grep --version` must succeed from a new shell, which means
210
- `~/.cargo/bin` is on your `PATH`.
52
+ The agent must clear a 🔴 blocker before it reports the task as done. A result marked partial, stale, or unconfirmed is never reported as clean.
53
+
54
+ ## What you get
55
+
56
+ - **Real diagnostics on every edit.** Language servers, linters, type-checkers, and scanners check each written file, and an impact cascade checks the files that depend on it. See [language coverage](docs/language-coverage.md).
57
+ - **Safe formatting and autofix.** pi-lens formats and fixes files with the tools you configure or it confidently detects.
58
+ - **Structural rules.** ast-grep and tree-sitter rules flag correctness and security smells, and you can add [custom rules](docs/custom-rules.md).
59
+ - **Code navigation for the agent.** Tools cover LSP navigation, ranked identifier search, module reports, and symbol reads, so the agent reads less code. See [agent tools](docs/agent-tools.md).
60
+ - **Guards and triage.** Read-before-edit blocks blind edits, an optional git guard holds `git commit` while blockers stand, and on pi you can mark a finding false-positive, suppressed, or deferred. The marking tool has no MCP endpoint, and under pi's lazy tool loading the agent activates it first. See [dispositions](docs/dispositions.md) and [agent tools](docs/agent-tools.md).
61
+ - **Health and scans.** `/lens-health` reports runtime health, and opted-in projects get background security and dependency scans.
62
+
63
+ The [feature reference](docs/features.md) covers everything.
64
+
65
+ ## What runs by default
66
+
67
+ pi-lens runs tools in three tiers. The [per-tool table](docs/language-coverage.md#what-runs-by-default) lists every gate and where it lives in the code.
68
+
69
+ - **No project config.** Language servers start by default, and `--no-lsp` turns them off. Many linters and formatters also run when the tool is available. Examples: ruff, shellcheck, hadolint, and ktlint for linting; oxlint or Biome for JS and TS when the project has no ESLint config; Biome and shfmt for formatting.
70
+ - **Your project's config.** ESLint, golangci-lint, mypy, phpstan, and vale skip a project that lacks their config. detekt needs a detekt config file, credo needs `mix.exs`, and the taplo and clang-format formatters wait for config.
71
+ - **Opt-in.** trivy (`trivy.enabled`), SpotBugs (`--lens-spotbugs`), Helm render validation (`helm.renderValidation.enabled`), and the commit guard (`--lens-guard`) stay off until you enable them.
72
+
73
+ Project-local binaries, such as `node_modules/.bin/eslint` or `.venv/bin/ruff`, run only when pi trusts the project.
211
74
 
212
- In the verified environment, `/lens-health` reported zero pipeline crashes and
213
- listed the `ast-grep` and `bash` LSP servers as available. This confirms startup
214
- and server discovery only; `ast_grep_search` was not tested end to end.
75
+ ## Commands you'll use
215
76
 
216
- pi-lens only looks for an `ast-grep` on `PATH` (such as Cargo's
217
- `~/.cargo/bin/ast-grep`) when pi trusts the project, so in an untrusted
218
- project this fallback leaves `ast_grep_search` unavailable. The in-process
219
- ast-grep rules (`@ast-grep/napi`) and Biome have no Android build, so they stay
220
- unavailable either way.
77
+ | Command | What it does |
78
+ |---|---|
79
+ | `/lens-health` | Show runtime health, latency, and degradation counts |
80
+ | `/lens-widget-toggle` | Show or hide the diagnostics widget below the editor |
81
+ | `/lens-toggle` | Turn pi-lens on or off for the session |
82
+ | `/lens-map` | Build an interactive HTML dependency map of the project |
83
+ | `/lens-allow-edit <path>` | Override the read-before-edit guard for one edit |
84
+ | `/lens-tools` | Show which tools are installed, auto-installed, or fall back to `npx` |
85
+
86
+ The full list of commands and runtime flags is in [Tools and commands](docs/tools.md).
221
87
 
222
88
  ## Documentation
223
89
 
224
- - [Agent guide](docs/agent-guide.md) — how an AI agent should consume and respond to pi-lens
225
- - [Agent tools](docs/agent-tools.md) — pi tool names, scopes, and arguments
226
- - [Usage guide](docs/usage.md) — lifecycle, tool behavior, MCP notes, and
227
- troubleshooting
228
- - [Features](docs/features.md) — detailed feature reference
229
- - [Word index](docs/word-index.md) — identifier search (`symbol_search`) and
230
- the discovery funnel
231
- - [Tools and commands](docs/tools.md) — runtime flags and slash commands
232
- - [Diagnostic dispositions](docs/dispositions.md) — triage: false-positive,
233
- suppress, defer, flagged-to-fix
234
- - [Settings](docs/settings.md) — the configuration hub: defaults, env vars, CLI
235
- flags, and global vs project config at a glance
236
- - [Configuration](docs/globalconfig.md) — global and project config files
237
- - [Environment variables](docs/environment-variables.md) — common env vars and
238
- full reference
239
- - [Language coverage](docs/language-coverage.md) — supported languages, runners,
240
- and formatters
241
- - [Dependencies](docs/dependencies.md) — auto-install policy and external tools
242
- - [Custom rules](docs/custom-rules.md) — project ast-grep and tree-sitter rules
243
- - [MCP server](docs/mcp.md) — experimental MCP server for Claude Code and
244
- other MCP clients
245
- - [Architecture decision records](docs/adr/README.md) — settled design
246
- decisions, linked from the engineering-defect catalog
90
+ ### Use
91
+
92
+ - [Agent guide](docs/agent-guide.md): how an agent reads and responds to pi-lens
93
+ - [Agent tools](docs/agent-tools.md): tool names, scopes, and arguments
94
+ - [Usage guide](docs/usage.md): lifecycle, tool behavior, MCP notes, and troubleshooting
95
+ - [Features](docs/features.md): the detailed feature reference
96
+ - [Diagnostic dispositions](docs/dispositions.md): triage with false-positive, suppress, defer, and flagged-to-fix
97
+ - [Word index](docs/word-index.md): identifier search and the discovery funnel
98
+
99
+ ### Configure
100
+
101
+ - [Settings](docs/settings.md): defaults, environment variables, flags, and global versus project config
102
+ - [Configuration](docs/globalconfig.md): global and project config files
103
+ - [Environment variables](docs/environment-variables.md): the full reference
104
+ - [Language coverage](docs/language-coverage.md): supported languages, runners, and formatters
105
+ - [Dependencies](docs/dependencies.md): auto-install policy and external tools
106
+
107
+ ### Extend
108
+
109
+ - [Custom rules](docs/custom-rules.md): project ast-grep and tree-sitter rules
110
+ - [MCP server](docs/mcp.md): the experimental server for Claude Code and other MCP clients
111
+ - [Architecture](docs/architecture.md): how events reach the findings the agent sees
112
+ - [Architecture decision records](docs/adr/README.md): settled design decisions
113
+
114
+ ## Troubleshooting
115
+
116
+ <details>
117
+ <summary>Install problems</summary>
118
+
119
+ The install notes in the [usage guide](docs/usage.md#install-notes) cover three cases:
120
+
121
+ - **npm v12** asks you to approve dependency install scripts such as the `@ast-grep/cli` postinstall.
122
+ - **Android and Termux** can fail to find the `@ast-grep/cli` native binary. The notes give a verified fallback.
123
+ - **Skills** arrive through the package manifest. Loading the extension file directly (`pi --extension ./index.js`) loads no pi-lens skills.
124
+
125
+ </details>
126
+
127
+ For runtime problems, run `/lens-health` and read the [usage guide troubleshooting section](docs/usage.md#troubleshooting).
247
128
 
248
129
  ## Contributing
249
130
 
250
- See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow, runner,
251
- LSP, formatter, and rule checklists, and issue/PR conventions.
131
+ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow, runner, LSP, formatter, and rule checklists, and for issue and PR conventions.
252
132
 
253
- Security issues should be reported privately; see [`SECURITY.md`](SECURITY.md).
133
+ Report security issues privately; see [`SECURITY.md`](SECURITY.md).
254
134
  pi-lens is released under the [MIT License](LICENSE).
255
135
 
256
136
  ## Contributors
@@ -554,6 +434,13 @@ Thanks goes to these wonderful people:
554
434
  <td align="center" valign="top" width="14.28%"><a href="https://github.com/aprudkin"><img src="https://avatars.githubusercontent.com/u/126267327?v=4" width="100px;" alt=""/><br /><sub><b>aprudkin</b></sub></a><br /><a href="#bug-aprudkin" title="Bug reports">🐛</a></td>
555
435
  <td align="center" valign="top" width="14.28%"><a href="https://github.com/ProphetOfDoom-PoD"><img src="https://avatars.githubusercontent.com/u/260035065?v=4" width="100px;" alt=""/><br /><sub><b>Prophet Of Doom</b></sub></a><br /><a href="#ideas-ProphetOfDoom-PoD" title="Ideas & Planning">🤔</a></td>
556
436
  <td align="center" valign="top" width="14.28%"><a href="http://www.apostolapostolov.com/"><img src="https://avatars.githubusercontent.com/u/4083812?v=4" width="100px;" alt=""/><br /><sub><b>Apostol Apostolov</b></sub></a><br /><a href="#bug-apoapostolov" title="Bug reports">🐛</a></td>
437
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/spearmootz"><img src="https://avatars.githubusercontent.com/u/19737290?v=4" width="100px;" alt=""/><br /><sub><b>Ricardo Spear</b></sub></a><br /><a href="#bug-spearmootz" title="Bug reports">🐛</a></td>
438
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/lluppi"><img src="https://avatars.githubusercontent.com/u/88203649?v=4" width="100px;" alt=""/><br /><sub><b>Lee Luppi</b></sub></a><br /><a href="#ideas-lluppi" title="Ideas & Planning">🤔</a> <a href="#code-lluppi" title="Code">💻</a></td>
439
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/gezerui888"><img src="https://avatars.githubusercontent.com/u/17674876?v=4" width="100px;" alt=""/><br /><sub><b>Zerui Ge</b></sub></a><br /><a href="#code-gezerui888" title="Code">💻</a></td>
440
+ </tr>
441
+ <tr>
442
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/HyeokjaeLee"><img src="https://avatars.githubusercontent.com/u/71566740?v=4" width="100px;" alt=""/><br /><sub><b>HyeokjaeLee</b></sub></a><br /><a href="#code-HyeokjaeLee" title="Code">💻</a> <a href="#bug-HyeokjaeLee" title="Bug reports">🐛</a></td>
443
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/dmarchevsky"><img src="https://avatars.githubusercontent.com/u/32597866?v=4" width="100px;" alt=""/><br /><sub><b>Dima Marchevskyi</b></sub></a><br /><a href="#bug-dmarchevsky" title="Bug reports">🐛</a></td>
557
444
  </tr>
558
445
  </tbody>
559
446
  </table>