pi-lens 4.4.12 → 4.5.1

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 (169) hide show
  1. package/CHANGELOG-USER.md +12 -12
  2. package/CHANGELOG.md +304 -0
  3. package/README.md +105 -217
  4. package/config/dependency-cruiser-eager-allowlist.json +1 -0
  5. package/dist/{chunk-OVPR3GQ6.js → chunk-25CAONWT.js} +52 -23
  6. package/dist/{chunk-W6VLB6LL.js → chunk-2APSZHHI.js} +61 -3
  7. package/dist/{chunk-E3PNZDPH.js → chunk-2DWNYVUN.js} +34 -2
  8. package/dist/{chunk-ME6MF2N2.js → chunk-2RQREVGO.js} +1 -1
  9. package/dist/{chunk-7T64QA5D.js → chunk-2XALJI2K.js} +42 -41
  10. package/dist/{chunk-VU2PRGRI.js → chunk-2YQ5LI7R.js} +4 -4
  11. package/dist/{chunk-DFAY7JUN.js → chunk-35UJUF27.js} +18 -4
  12. package/dist/{chunk-PTJXMYRY.js → chunk-3IWMNN2S.js} +17 -18
  13. package/dist/chunk-3UTDLQWO.js +88 -0
  14. package/dist/chunk-3Z7Z3B7V.js +27 -0
  15. package/dist/{chunk-AD7JDEI6.js → chunk-4E4OCW3L.js} +17 -17
  16. package/dist/{chunk-6GWCYEP7.js → chunk-4GLSO2EM.js} +69 -19
  17. package/dist/{chunk-QJ4T73J5.js → chunk-5HVDD7IA.js} +1 -1
  18. package/dist/{chunk-ZRQMENT4.js → chunk-62PIU4TO.js} +1 -1
  19. package/dist/{chunk-HWMNTQBJ.js → chunk-6MDWNZ7E.js} +32 -11
  20. package/dist/{chunk-WLD6BGON.js → chunk-6MWX2J5H.js} +4 -0
  21. package/dist/{chunk-SF7KSXB5.js → chunk-6MZLS6CK.js} +7 -7
  22. package/dist/{chunk-ORYQGVC3.js → chunk-7BWPQZHE.js} +3 -3
  23. package/dist/{chunk-5FDUKJZO.js → chunk-7JMEPY6P.js} +10 -10
  24. package/dist/{chunk-MOEWCPMC.js → chunk-7ORBRDFY.js} +2 -2
  25. package/dist/chunk-7WAQ3K26.js +52 -0
  26. package/dist/{chunk-5EEWCJG7.js → chunk-AB26NAHA.js} +9 -9
  27. package/dist/{chunk-IC4L65U7.js → chunk-AFSG6YUB.js} +13 -14
  28. package/dist/{chunk-2HWVG3IM.js → chunk-ALTHJUZO.js} +2 -2
  29. package/dist/{chunk-R67WQ5RY.js → chunk-AOEVZXR6.js} +9 -9
  30. package/dist/{chunk-F7AMFFVK.js → chunk-ARTCVE6I.js} +9 -9
  31. package/dist/{chunk-HGEE5LDW.js → chunk-B2QO7GHY.js} +1 -1
  32. package/dist/{chunk-HSTN27NR.js → chunk-BJGWP4UX.js} +10 -10
  33. package/dist/{chunk-6EXGCXM5.js → chunk-BKJ6WZKP.js} +99 -5
  34. package/dist/{chunk-6JLNZ6DP.js → chunk-BQ72NQQM.js} +11 -11
  35. package/dist/{chunk-WTSQKJAR.js → chunk-BWGNVM33.js} +11 -11
  36. package/dist/{chunk-IT7MFVGP.js → chunk-BYIEU4E4.js} +2 -2
  37. package/dist/{chunk-ILC2B7IJ.js → chunk-CDAJQBKJ.js} +11 -11
  38. package/dist/{chunk-HJWF7CGW.js → chunk-D3UQWOCB.js} +17 -17
  39. package/dist/{chunk-OEPWTSUG.js → chunk-DHFJS2I4.js} +8 -8
  40. package/dist/{chunk-SUIZOCSY.js → chunk-DKXIUGNA.js} +2 -2
  41. package/dist/{chunk-3R3Z54J7.js → chunk-DLGJYQML.js} +2 -2
  42. package/dist/{chunk-D6ANA6YU.js → chunk-DNJJVKJZ.js} +64 -56
  43. package/dist/{chunk-OYXD2MOM.js → chunk-EBXCYEII.js} +3 -3
  44. package/dist/chunk-EH6EHFW2.js +73 -0
  45. package/dist/{chunk-HRQTYU2T.js → chunk-EKQDQPX6.js} +10 -10
  46. package/dist/{chunk-DZSQXG66.js → chunk-EXHSWN3P.js} +1093 -411
  47. package/dist/{chunk-PCREZ4HJ.js → chunk-F7BFIENK.js} +35 -36
  48. package/dist/{chunk-LD7SXICE.js → chunk-FD4LJQ6Y.js} +5 -5
  49. package/dist/{chunk-7ZVEFWOE.js → chunk-GFCPPCNR.js} +11 -11
  50. package/dist/{chunk-B4FAFEBP.js → chunk-GIK6VUCY.js} +1 -1
  51. package/dist/{chunk-JLMS7EMD.js → chunk-GNK2IHVG.js} +17 -16
  52. package/dist/{chunk-7424ANRU.js → chunk-H6DNTQ4V.js} +2 -2
  53. package/dist/{chunk-TOOXNL6M.js → chunk-HERQPNY6.js} +8 -8
  54. package/dist/{chunk-NZINZCHB.js → chunk-HFIFEH46.js} +3 -3
  55. package/dist/{chunk-PXGVB2CY.js → chunk-HKRESBMC.js} +21 -19
  56. package/dist/{chunk-PK3GDU4M.js → chunk-HMXWZUQW.js} +1 -1
  57. package/dist/{chunk-75TVYCQW.js → chunk-HOWHAKXO.js} +6 -6
  58. package/dist/{chunk-K2GV34T2.js → chunk-HUWW77QY.js} +27 -38
  59. package/dist/{chunk-OHEUOWYT.js → chunk-IO6P3NBP.js} +1 -1
  60. package/dist/{chunk-PPYUBO6Y.js → chunk-J7VNGHLN.js} +2 -2
  61. package/dist/{chunk-IZ36G463.js → chunk-JGCBMCCS.js} +8 -8
  62. package/dist/{chunk-OF2YGDUE.js → chunk-KIQSNH3F.js} +39 -40
  63. package/dist/{chunk-HYDJUVOE.js → chunk-KSQJBGRO.js} +5 -5
  64. package/dist/{chunk-T5EGSBM2.js → chunk-KXKM2DFP.js} +4 -4
  65. package/dist/chunk-L3Q72QGQ.js +25 -0
  66. package/dist/{chunk-AVBEPUCD.js → chunk-LDPY22FS.js} +2 -2
  67. package/dist/{chunk-ET3DSSFZ.js → chunk-M3QGXGY4.js} +3796 -3825
  68. package/dist/{chunk-YLW26OHX.js → chunk-MET776XM.js} +35 -61
  69. package/dist/{chunk-X33QECRJ.js → chunk-MKQFSW2Q.js} +2 -2
  70. package/dist/{chunk-7BEADGAZ.js → chunk-MKW7ZUTT.js} +3 -3
  71. package/dist/{chunk-6EIV3H7O.js → chunk-N2U644ZW.js} +4 -11
  72. package/dist/{chunk-AYDE7RFV.js → chunk-NAACKIKT.js} +2 -2
  73. package/dist/{chunk-O6LCSHHI.js → chunk-NHHS5T52.js} +1 -1
  74. package/dist/{chunk-DIIDMDZU.js → chunk-NIZKGBOU.js} +51 -27
  75. package/dist/chunk-NNDZ7DOP.js +3040 -0
  76. package/dist/{chunk-MV6ST2KT.js → chunk-NZ7NSKIW.js} +14 -13
  77. package/dist/{chunk-AAIVSSUU.js → chunk-OG3UCAHV.js} +35 -12
  78. package/dist/{chunk-C6V2DSZZ.js → chunk-OHTHVILU.js} +12 -12
  79. package/dist/{chunk-AGEQRJ5A.js → chunk-P7EV5ISR.js} +17 -2
  80. package/dist/{chunk-G3LR6V6N.js → chunk-PVV27TOX.js} +20 -18
  81. package/dist/{chunk-3MHY4BQY.js → chunk-Q32RJDYC.js} +4 -4
  82. package/dist/{chunk-BMMRLJA4.js → chunk-Q4UQNTLB.js} +29 -12
  83. package/dist/{chunk-FDLGJFAE.js → chunk-QQGZY2BR.js} +3 -3
  84. package/dist/{chunk-E5SSUV2A.js → chunk-S247BOH2.js} +4 -4
  85. package/dist/{chunk-NCDH2JB7.js → chunk-S7KUDW73.js} +136 -18
  86. package/dist/{chunk-GHATCG2A.js → chunk-SJ2SR432.js} +23 -19
  87. package/dist/{chunk-SRXYSLMW.js → chunk-SL4G67AP.js} +2 -2
  88. package/dist/chunk-T2D2WWP6.js +847 -0
  89. package/dist/{chunk-JRSS6KM4.js → chunk-T7KHGEJ5.js} +3 -3
  90. package/dist/{chunk-YTXFNCVN.js → chunk-TABDCX35.js} +2 -2
  91. package/dist/chunk-TFSBHRL2.js +25 -0
  92. package/dist/{chunk-S6ZQFPOX.js → chunk-TQKWR5AZ.js} +7 -7
  93. package/dist/chunk-TQWRH25U.js +35 -0
  94. package/dist/chunk-TWAQFMLW.js +110 -0
  95. package/dist/{chunk-Y7XMKBFP.js → chunk-UARVPNAU.js} +35 -27
  96. package/dist/chunk-UWBD3JMH.js +56 -0
  97. package/dist/{chunk-AZXTLZHE.js → chunk-VEF3GFOL.js} +170 -166
  98. package/dist/{chunk-QY6J2FTK.js → chunk-W2JPGW7Q.js} +28 -25
  99. package/dist/{chunk-HYR25MV3.js → chunk-W2YHHNY3.js} +9 -8
  100. package/dist/{chunk-3PMLYGJN.js → chunk-WA6U2URH.js} +9 -9
  101. package/dist/{chunk-JKAVKTMY.js → chunk-WAK2AXQQ.js} +18 -21
  102. package/dist/{chunk-K2LD6YNH.js → chunk-WH6O4IFD.js} +10 -10
  103. package/dist/{chunk-KXDQD34C.js → chunk-WJ7GY5WJ.js} +1 -1
  104. package/dist/{chunk-3QMLB4TI.js → chunk-WWZLT6AM.js} +2 -2
  105. package/dist/{chunk-ZWZD4TJ5.js → chunk-XRLZ75YY.js} +39 -40
  106. package/dist/chunk-XWWFESYZ.js +27 -0
  107. package/dist/chunk-XZSXSM4K.js +27 -0
  108. package/dist/{chunk-D2ZYRI7M.js → chunk-Y2LIOCA7.js} +1 -1
  109. package/dist/{chunk-Z6WTLVUL.js → chunk-YIEHUKX2.js} +291 -255
  110. package/dist/{chunk-NRVWLTOY.js → chunk-YOMLAKU6.js} +231 -190
  111. package/dist/{chunk-3EIZMRXI.js → chunk-YV7XVYSJ.js} +11 -11
  112. package/dist/{chunk-T6PPK3T6.js → chunk-ZVQUYCBU.js} +1317 -708
  113. package/dist/index.js +10797 -7167
  114. package/dist/mcp/analyze-cli.js +11 -11
  115. package/dist/mcp/cli.js +42 -41
  116. package/dist/mcp/server.js +813 -469
  117. package/dist/mcp/worker.js +60 -61
  118. package/dist/probes/installer.js +22 -20
  119. package/docs/architecture.md +113 -0
  120. package/docs/ast-grep_rules_catalog.md +2 -2
  121. package/docs/ci-bot-pr-checks.md +18 -9
  122. package/docs/ci.md +25 -4
  123. package/docs/defect-shapes.md +83 -30
  124. package/docs/dependencies.md +10 -10
  125. package/docs/features.md +3 -3
  126. package/docs/globalconfig.md +1 -0
  127. package/docs/invariants/dispatch-runners.md +28 -1
  128. package/docs/invariants/lsp-trust-exec.md +19 -0
  129. package/docs/language-coverage.md +39 -0
  130. package/docs/lsp-capability-matrix.md +13 -7
  131. package/docs/lsp-idle-eviction.md +3 -2
  132. package/docs/module-report-read-symbol.md +6 -2
  133. package/docs/pi-lens-fixer.md +4 -0
  134. package/docs/pi-lens-merge-policy.md +4 -3
  135. package/docs/pi-lens-orchestration.md +2 -1
  136. package/docs/pi-lens-reviewer.md +4 -5
  137. package/docs/pi-lens-subagent.md +7 -3
  138. package/docs/prose-standard.md +112 -0
  139. package/docs/servercapabilities.md +1 -1
  140. package/docs/settings.md +1 -0
  141. package/docs/usage.md +51 -0
  142. package/package.json +1 -1
  143. package/rules/ast-grep-rules/rule-tests/array-callback-return-js-test.yml +23 -0
  144. package/rules/ast-grep-rules/rule-tests/array-callback-return-test.yml +23 -0
  145. package/rules/ast-grep-rules/rule-tests/no-negation-in-equality-check-js-test.yml +8 -0
  146. package/rules/ast-grep-rules/rule-tests/no-negation-in-equality-check-test.yml +8 -0
  147. package/rules/ast-grep-rules/rule-tests/unchecked-throwing-call-js-test.yml +16 -0
  148. package/rules/ast-grep-rules/rule-tests/unchecked-throwing-call-test.yml +16 -0
  149. package/rules/ast-grep-rules/rules/array-callback-return-js.yml +8 -0
  150. package/rules/ast-grep-rules/rules/array-callback-return.yml +8 -0
  151. package/rules/ast-grep-rules/rules/no-negation-in-equality-check-js.yml +17 -5
  152. package/rules/ast-grep-rules/rules/no-negation-in-equality-check.yml +17 -5
  153. package/rules/ast-grep-rules/rules/unchecked-throwing-call-js.yml +8 -1
  154. package/rules/ast-grep-rules/rules/unchecked-throwing-call.yml +8 -1
  155. package/rules/tree-sitter-queries/typescript/ts-react-antipatterns.yml +8 -0
  156. package/dist/chunk-3VWEZ6H2.js +0 -72
  157. package/dist/chunk-5KLRCUDT.js +0 -67
  158. package/dist/chunk-7KWI5UHL.js +0 -28
  159. package/dist/chunk-7M64NTAK.js +0 -38
  160. package/dist/chunk-BEIPWPVR.js +0 -1037
  161. package/dist/chunk-D7OEGXDX.js +0 -2417
  162. package/dist/chunk-FVQKX5KI.js +0 -50
  163. package/dist/chunk-KUDUKKQE.js +0 -89
  164. package/dist/chunk-TM3A3K7T.js +0 -28
  165. package/dist/chunk-TS5EIWEF.js +0 -25
  166. package/dist/chunk-VD7MQFEV.js +0 -56
  167. package/dist/chunk-YLHJWAQS.js +0 -256
  168. package/dist/chunk-YULIERZW.js +0 -27
  169. package/dist/chunk-Z2W5YJBW.js +0 -25
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
@@ -555,6 +435,14 @@ Thanks goes to these wonderful people:
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>
557
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>
444
+ <td align="center" valign="top" width="14.28%"><a href="https://jennyleidig.straw.page/"><img src="https://avatars.githubusercontent.com/u/131712584?v=4" width="100px;" alt=""/><br /><sub><b>Jenny Leidig</b></sub></a><br /><a href="#code-jennymaeleidig" title="Code">💻</a> <a href="#ideas-jennymaeleidig" title="Ideas & Planning">🤔</a></td>
445
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/yorch"><img src="https://avatars.githubusercontent.com/u/60499?v=4" width="100px;" alt=""/><br /><sub><b>Jorge Barnaby</b></sub></a><br /><a href="#bug-yorch" title="Bug reports">🐛</a></td>
558
446
  </tr>
559
447
  </tbody>
560
448
  </table>
@@ -37,6 +37,7 @@
37
37
  "./clients/instance-reaper.js",
38
38
  "./clients/instance-registry.js",
39
39
  "./clients/io-bridge.js",
40
+ "./clients/issues-status.js",
40
41
  "./clients/language-profile.js",
41
42
  "./clients/latency-logger.js",
42
43
  "./clients/lens-config.js",
@@ -2,14 +2,17 @@ import { createRequire as __pilensCreateRequire } from "node:module"; const requ
2
2
  import {
3
3
  createAvailabilityProbeFlight,
4
4
  probeToolAsync
5
- } from "./chunk-3QMLB4TI.js";
5
+ } from "./chunk-WWZLT6AM.js";
6
6
  import {
7
7
  classifyFinderFailure,
8
8
  createAvailabilityLatch,
9
9
  isTransientDecision,
10
10
  logAvailabilityDecision,
11
11
  startHostStallSampler
12
- } from "./chunk-AVBEPUCD.js";
12
+ } from "./chunk-LDPY22FS.js";
13
+ import {
14
+ registerBackgroundWriteDrain
15
+ } from "./chunk-UYXV5NIS.js";
13
16
  import {
14
17
  NODE_MODULES_BIN_DIRS,
15
18
  createGenerationSource,
@@ -17,20 +20,21 @@ import {
17
20
  projectLocalBinDirs,
18
21
  recordProjectCommandRefusal,
19
22
  safeSpawnAsync
20
- } from "./chunk-ET3DSSFZ.js";
23
+ } from "./chunk-M3QGXGY4.js";
21
24
  import {
22
- getProjectTrustState
23
- } from "./chunk-HRQTYU2T.js";
25
+ getProjectTrustState,
26
+ withDeadline
27
+ } from "./chunk-EKQDQPX6.js";
24
28
  import {
25
29
  logExtension,
26
30
  recordDegradationOnce
27
- } from "./chunk-AGEQRJ5A.js";
31
+ } from "./chunk-P7EV5ISR.js";
28
32
  import {
29
33
  isAtOrAboveHomeDir,
30
34
  isUnderDir,
31
35
  realpathOrResolve,
32
36
  walkUpDirs
33
- } from "./chunk-WLD6BGON.js";
37
+ } from "./chunk-6MWX2J5H.js";
34
38
 
35
39
  // dist/clients/package-manager.js
36
40
  import * as fs from "node:fs";
@@ -202,10 +206,10 @@ async function globalBinDirsFor(pm) {
202
206
  if (cached)
203
207
  return cached;
204
208
  const generation = packageManagerCacheGeneration.capture();
205
- const shared = globalBinDirProbeFlights.run(key, () => probeGlobalBinDirs(pm, key, scoped, generation));
209
+ const shared = globalBinDirProbeFlights.run(key, () => probeGlobalBinDirs(pm, key, generation));
206
210
  return shared.promise;
207
211
  }
208
- async function probeGlobalBinDirs(pm, key, scoped, generation) {
212
+ async function probeGlobalBinDirs(pm, key, generation) {
209
213
  if (pm === "bun") {
210
214
  const base = process.env.BUN_INSTALL || path.join(os.homedir(), ".bun");
211
215
  const dirs2 = [path.join(base, "bin")];
@@ -217,7 +221,7 @@ async function probeGlobalBinDirs(pm, key, scoped, generation) {
217
221
  const query = pm === "npm" ? ["config", "get", "prefix"] : pm === "pnpm" ? ["bin", "-g"] : ["global", "bin"];
218
222
  const res = await safeSpawnAsync(pmBinary(pm), query, {
219
223
  timeout: 5e3,
220
- ...scoped && { cwd: os.homedir() }
224
+ cwd: os.homedir()
221
225
  });
222
226
  if (res.status !== 0 || res.error)
223
227
  return [];
@@ -237,7 +241,7 @@ async function allAvailableGlobalBinDirs(onTransient) {
237
241
  if (!await isAvailable(pm, onTransient))
238
242
  continue;
239
243
  for (const dir of await globalBinDirsFor(pm)) {
240
- const normalized = path.resolve(dir);
244
+ const normalized = path.resolve(os.homedir(), dir);
241
245
  if (seen.has(normalized))
242
246
  continue;
243
247
  seen.add(normalized);
@@ -246,6 +250,16 @@ async function allAvailableGlobalBinDirs(onTransient) {
246
250
  }
247
251
  return dirs;
248
252
  }
253
+ var primesRunning = 0;
254
+ var primesSettled = Promise.resolve();
255
+ var PRIME_SETTLE_BOUND_MS = 1e4;
256
+ function settlePrimedGlobalBinDirsForTests() {
257
+ return withDeadline(primesSettled, {
258
+ ms: PRIME_SETTLE_BOUND_MS,
259
+ onTimeout: "undefined"
260
+ }).then(() => primesRunning > 0 ? "global-bin-dir prime still running after the bounded wait" : void 0);
261
+ }
262
+ registerBackgroundWriteDrain(settlePrimedGlobalBinDirsForTests);
249
263
  async function findGlobalBinary(command, windowsExt = ".cmd") {
250
264
  const candidates = onWindows() ? [`${command}${windowsExt}`, `${command}.exe`, command] : [command];
251
265
  try {
@@ -265,6 +279,9 @@ async function findGlobalBinary(command, windowsExt = ".cmd") {
265
279
  }
266
280
  return void 0;
267
281
  }
282
+ function isLocalBinTrustRefusal(value) {
283
+ return typeof value === "object" && value !== null && value.kind === "refused-by-trust";
284
+ }
268
285
  function localBinPath(value) {
269
286
  return typeof value === "string" ? value : void 0;
270
287
  }
@@ -297,12 +314,23 @@ function commandSearchReachesProject(cwd) {
297
314
  const posix = process.platform !== "win32";
298
315
  return (process.env.PATH ?? "").split(path.delimiter).some((entry) => entry === "" ? posix : !path.isAbsolute(entry) || isUnderDir(entry, cwd) || isProjectLocalBinPath(entry, cwd));
299
316
  }
300
- function expandCandidateNames(tools, windowsExt, isWindows) {
301
- return isWindows && windowsExt !== "" ? tools.flatMap((tool) => [`${tool}${windowsExt}`, tool]) : [...tools];
302
- }
303
- function* matchesInDir(dir, names, binDirs) {
304
- for (const name of names) {
305
- for (const binDir of binDirs) {
317
+ function* matchesInDir(dir, tools, binDirs, windowsExt, binDirWindowsExt, isWindows) {
318
+ const extsByDir = binDirs.map((binDir) => isWindows ? [
319
+ ...new Set([binDirWindowsExt?.[binDir], windowsExt].flatMap((ext) => ext ? [ext] : []))
320
+ ] : []);
321
+ const rounds = Math.max(0, ...extsByDir.map((exts) => exts.length));
322
+ for (const tool of tools) {
323
+ const candidates = [];
324
+ for (let round = 0; round < rounds; round++) {
325
+ for (const [i, binDir] of binDirs.entries()) {
326
+ const ext = extsByDir[i]?.[round];
327
+ if (ext !== void 0)
328
+ candidates.push([binDir, tool + ext]);
329
+ }
330
+ }
331
+ for (const binDir of binDirs)
332
+ candidates.push([binDir, tool]);
333
+ for (const [binDir, name] of candidates) {
306
334
  const full = path.join(dir, binDir, name);
307
335
  if (fs.existsSync(full))
308
336
  yield full;
@@ -310,15 +338,14 @@ function* matchesInDir(dir, names, binDirs) {
310
338
  }
311
339
  }
312
340
  function* localBinMatches(tools, startDir, options) {
313
- const { windowsExt = ".cmd", homeDir = os.homedir(), binDirs = NODE_MODULES_BIN_DIRS, isWindows = onWindows(), ceiling = true } = options;
314
- const names = expandCandidateNames(tools, windowsExt, isWindows);
341
+ const { windowsExt = ".cmd", homeDir = os.homedir(), binDirs = NODE_MODULES_BIN_DIRS, binDirWindowsExt, isWindows = onWindows(), ceiling = true } = options;
315
342
  const home = ceiling ? realpathOrResolve(homeDir) : homeDir;
316
343
  let startIsReal;
317
344
  for (const dir of walkUpDirs(startDir, { spelling: true })) {
318
345
  startIsReal ??= ceiling && realpathOrResolve(dir) === dir;
319
346
  if (ceiling && isAtOrAboveHomeDir(startIsReal ? dir : realpathOrResolve(dir), home))
320
347
  return;
321
- yield* matchesInDir(dir, names, binDirs);
348
+ yield* matchesInDir(dir, tools, binDirs, windowsExt, binDirWindowsExt, isWindows);
322
349
  }
323
350
  }
324
351
  function findLocalBinUpwards(tool, startDir, options = {}) {
@@ -330,9 +357,10 @@ function findLocalBinUpwards(tool, startDir, options = {}) {
330
357
  return match;
331
358
  }
332
359
  function findLocalBinsAt(tools, dir, options = {}) {
333
- const { windowsExt = ".cmd", binDirs = NODE_MODULES_BIN_DIRS, isWindows = onWindows() } = options;
334
- const names = expandCandidateNames(tools, windowsExt, isWindows);
335
- const matches = [...matchesInDir(path.resolve(dir), names, binDirs)];
360
+ const { windowsExt = ".cmd", binDirs = NODE_MODULES_BIN_DIRS, binDirWindowsExt, isWindows = onWindows() } = options;
361
+ const matches = [
362
+ ...matchesInDir(path.resolve(dir), tools, binDirs, windowsExt, binDirWindowsExt, isWindows)
363
+ ];
336
364
  if (matches.length === 0 || getProjectTrustState() === "trusted")
337
365
  return matches;
338
366
  return [refuseLocalBin(tools.join(","), dir)];
@@ -354,6 +382,7 @@ export {
354
382
  updateArgs,
355
383
  allAvailableGlobalBinDirs,
356
384
  findGlobalBinary,
385
+ isLocalBinTrustRefusal,
357
386
  localBinPath,
358
387
  isProjectLocalBinPath,
359
388
  commandSearchReachesProject,