pi-lens 4.4.7 → 4.4.9
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.
- package/CHANGELOG-USER.md +31 -0
- package/CHANGELOG.md +327 -0
- package/README.md +13 -2
- package/config/dependency-cruiser-eager-allowlist.json +1 -1
- package/config/markdownlint/run-no-fix.mjs +36 -0
- package/dist/{chunk-4LM3VAZH.js → chunk-2VZ3VN3N.js} +2 -2
- package/dist/{chunk-PUZ3E2J4.js → chunk-3HTZDY3C.js} +8 -6
- package/dist/{chunk-RORGS5II.js → chunk-3NPWO5UO.js} +7 -13
- package/dist/{chunk-MNJIXFX4.js → chunk-47UCC4MM.js} +1 -1
- package/dist/chunk-4ENEJHF4.js +198 -0
- package/dist/chunk-5GEYJJHG.js +22 -0
- package/dist/{chunk-U6VN4NVL.js → chunk-5YSEQHJN.js} +3 -3
- package/dist/{chunk-6IR3ZYIB.js → chunk-6GPB3JLL.js} +3 -3
- package/dist/{chunk-MB6PXBUA.js → chunk-7R5GZIA6.js} +7 -15
- package/dist/{chunk-DH5JPM3K.js → chunk-7UTSNTWM.js} +10 -9
- package/dist/{chunk-24BILSZW.js → chunk-7YTRG6YW.js} +2 -2
- package/dist/{chunk-KW5JQPO5.js → chunk-AACN5GNE.js} +2 -2
- package/dist/{chunk-PKES3ISE.js → chunk-ACRJ2GZ5.js} +2 -2
- package/dist/{chunk-4ZYJHQMB.js → chunk-C3YRO3EU.js} +10 -12
- package/dist/{chunk-PQJFG24Z.js → chunk-CB7PEVOJ.js} +1300 -946
- package/dist/{chunk-ABPKUVA4.js → chunk-CDFJF5YD.js} +1 -1
- package/dist/{chunk-T7A2HK2B.js → chunk-CJS6WE66.js} +17 -18
- package/dist/{chunk-3YY7IXIL.js → chunk-CM6BDY4E.js} +14 -60
- package/dist/{chunk-RZOXUSPC.js → chunk-CZCAZVTD.js} +16 -2
- package/dist/chunk-DGKFWQK4.js +23 -0
- package/dist/{chunk-NA7SEXHE.js → chunk-E65WJVI5.js} +7 -9
- package/dist/{chunk-2TF6RXWB.js → chunk-EKNYSXFB.js} +8 -10
- package/dist/{chunk-RRV3FNNM.js → chunk-EY6LY2HO.js} +27 -30
- package/dist/{chunk-LBLBAFG3.js → chunk-F6BEQWAK.js} +17 -5
- package/dist/{chunk-4L36HG27.js → chunk-FGNSESAC.js} +12 -14
- package/dist/{chunk-3FRLWYBG.js → chunk-FRUBVFXV.js} +39 -42
- package/dist/{chunk-FB5SCCPT.js → chunk-G22UNQID.js} +14 -15
- package/dist/{chunk-LV4UMYVH.js → chunk-GQTQUNCG.js} +26 -27
- package/dist/{chunk-E7HJ56Y7.js → chunk-H3BVMK47.js} +64 -73
- package/dist/chunk-H6FLQ5NW.js +28 -0
- package/dist/{chunk-QHSNL7B2.js → chunk-HEA3EM23.js} +15 -19
- package/dist/{chunk-AWDSEDER.js → chunk-HSOBIN22.js} +2 -2
- package/dist/{chunk-EAOK7MIZ.js → chunk-HYSKJMZK.js} +17 -4
- package/dist/{chunk-VUZWQ7UG.js → chunk-IICERRFF.js} +46 -72
- package/dist/{chunk-OXOI55RU.js → chunk-IILEH3ZC.js} +8 -10
- package/dist/{chunk-ZKXQKGWZ.js → chunk-J3Q2NYJR.js} +4 -3
- package/dist/{chunk-YHC2O2WO.js → chunk-JUZ67QZQ.js} +20 -9
- package/dist/chunk-KR5VGMVT.js +25 -0
- package/dist/{chunk-F7K5IBZG.js → chunk-KV6GQOGN.js} +41 -44
- package/dist/{chunk-SNDXCFRS.js → chunk-KXMJLOZF.js} +25 -23
- package/dist/{chunk-CB4WHS4H.js → chunk-L4Y3ROKQ.js} +3 -3
- package/dist/{chunk-3F6BMY53.js → chunk-L6WBJGQS.js} +1 -1
- package/dist/{chunk-MPKRJBPK.js → chunk-L7O774U7.js} +30 -32
- package/dist/{chunk-URCQWAQ4.js → chunk-LAHHGNAY.js} +21 -21
- package/dist/{chunk-V63BC55Q.js → chunk-LT62P654.js} +1 -1
- package/dist/{chunk-ZMAUPOMG.js → chunk-LWOM6LVS.js} +34 -34
- package/dist/{chunk-HO6LWE2E.js → chunk-MKPDIAZH.js} +21 -1
- package/dist/{chunk-2PHMIAKO.js → chunk-MN635QYA.js} +3 -4
- package/dist/{chunk-KDX35VXP.js → chunk-MQ4PPCJB.js} +166 -149
- package/dist/{chunk-QOE342SU.js → chunk-MRLH4MYU.js} +2 -2
- package/dist/{chunk-CE6VMBCB.js → chunk-N56BNAA6.js} +20 -21
- package/dist/{chunk-L3CMBQMH.js → chunk-N5CEGQPG.js} +14 -17
- package/dist/{chunk-7E2563GA.js → chunk-NCLO6E6N.js} +13 -33
- package/dist/{chunk-J6JP25XU.js → chunk-NL5LSKVD.js} +4 -3
- package/dist/{chunk-U7BD2QL7.js → chunk-NMUSOZ2D.js} +10 -12
- package/dist/{chunk-BZARLRJW.js → chunk-NOWH2VA2.js} +8 -33
- package/dist/{chunk-U2SDMG7C.js → chunk-NUSXS6YB.js} +6 -5
- package/dist/{chunk-ZJTT47IG.js → chunk-OSEKJEUU.js} +2 -2
- package/dist/{chunk-FZKFVUEC.js → chunk-OUYAUXAT.js} +647 -355
- package/dist/{chunk-ZE3KXHS7.js → chunk-PBZNYHMM.js} +84 -4
- package/dist/{chunk-U5HPROLA.js → chunk-PIIUNJIT.js} +2 -4
- package/dist/chunk-PKLB2XJL.js +8 -0
- package/dist/{chunk-RC2Z6K47.js → chunk-PRHYIA6X.js} +15 -6
- package/dist/{chunk-RQS4QQSD.js → chunk-PXQ45SGD.js} +2 -2
- package/dist/chunk-Q6JQKWPK.js +25 -0
- package/dist/{chunk-F6X3YJWD.js → chunk-QB7T2PHK.js} +2 -2
- package/dist/{chunk-TIQJPRDD.js → chunk-QGITU23N.js} +3 -2
- package/dist/chunk-QJJKOHLH.js +57 -0
- package/dist/{chunk-4LOE5R5P.js → chunk-QP33NKYC.js} +18 -15
- package/dist/{chunk-N5WSK2K7.js → chunk-QVBOXT3L.js} +12 -17
- package/dist/{chunk-DPGEAHZT.js → chunk-RNJFRXEN.js} +10 -18
- package/dist/{chunk-EKWX4WD3.js → chunk-RNXOWDM6.js} +10 -10
- package/dist/{chunk-O4BJFESU.js → chunk-RTFMDIKV.js} +1 -1
- package/dist/{chunk-LS3QJRUB.js → chunk-SIQHOB6P.js} +11 -13
- package/dist/{chunk-3K2F6UDZ.js → chunk-SLSMJPEF.js} +43 -42
- package/dist/chunk-T5QSLSMM.js +50 -0
- package/dist/chunk-TGQDAG4B.js +88 -0
- package/dist/{chunk-4YHYPW2G.js → chunk-THYHUIDR.js} +44 -13
- package/dist/{chunk-YVHBNSME.js → chunk-TMNUTMT5.js} +1099 -1100
- package/dist/{chunk-WDBICWH3.js → chunk-TOE2RRCS.js} +1 -1
- package/dist/chunk-TYHPVE5H.js +25 -0
- package/dist/chunk-UAKO2M6B.js +73 -0
- package/dist/chunk-UC5AXW5Z.js +20 -0
- package/dist/chunk-UTJP6WOS.js +28 -0
- package/dist/{chunk-DQZFQSR5.js → chunk-UXTQ3QPD.js} +4 -4
- package/dist/chunk-UYXV5NIS.js +20 -0
- package/dist/{chunk-KKCK636N.js → chunk-V2WDBOLZ.js} +10 -12
- package/dist/{chunk-PR6PO3ES.js → chunk-V67D6TMU.js} +22 -20
- package/dist/{chunk-VSFLRN5Y.js → chunk-VCRVNLE7.js} +135 -2
- package/dist/{chunk-CPSR3AVL.js → chunk-VO4JFPTV.js} +2 -2
- package/dist/{chunk-XT2HTCJ5.js → chunk-VWLSU3XV.js} +6 -5
- package/dist/{chunk-WME2OQST.js → chunk-W5E72HJA.js} +66 -24
- package/dist/{chunk-LLS45EWB.js → chunk-W7TY6HYX.js} +6 -8
- package/dist/{chunk-CCV2EU7T.js → chunk-WSSLVMDA.js} +12 -13
- package/dist/{chunk-YISME6ON.js → chunk-WTB4GKMH.js} +10 -1
- package/dist/{chunk-KPPJTH44.js → chunk-X5BJ3G2P.js} +64 -35
- package/dist/{chunk-JMEKXFOL.js → chunk-XKFO2SZV.js} +39 -34
- package/dist/{chunk-HR3OJ3TH.js → chunk-XLAI7UYY.js} +84 -31
- package/dist/{chunk-H7OR7DFZ.js → chunk-XO756WE5.js} +53 -37
- package/dist/{chunk-F5Z6URKM.js → chunk-XVB3Q2PG.js} +2 -4
- package/dist/{chunk-R5MOQM2H.js → chunk-YOXCCJDF.js} +607 -366
- package/dist/{chunk-ZGSJDWQU.js → chunk-ZCQBNPRH.js} +2 -2
- package/dist/chunk-ZD4KVFXI.js +234 -0
- package/dist/{chunk-WGRJOXED.js → chunk-ZDMFGACN.js} +1295 -966
- package/dist/{chunk-OSTKYB55.js → chunk-ZMMHHXSW.js} +1 -1
- package/dist/{chunk-75GAYVNO.js → chunk-ZPM7ZIFL.js} +6 -6
- package/dist/{chunk-LUBPZN36.js → chunk-ZVCDHYWZ.js} +9 -11
- package/dist/{chunk-Y7F7IEE3.js → chunk-ZZN74OGD.js} +102 -7
- package/dist/{chunk-L5JYIU47.js → chunk-ZZSJAR76.js} +39 -20
- package/dist/index.js +10933 -8644
- package/dist/mcp/analyze-cli.js +12 -17
- package/dist/mcp/cli.js +43 -42
- package/dist/mcp/server.js +3073 -1147
- package/dist/mcp/worker.js +61 -61
- package/dist/probes/installer.js +18 -19
- package/docs/adr/0003-git-guard-latch-writer.md +11 -6
- package/docs/agent-tools.md +58 -16
- package/docs/alignment-families.md +29 -0
- package/docs/analysisall.md +1 -1
- package/docs/ast-grep_rules_catalog.md +6 -4
- package/docs/ci-bot-pr-checks.md +128 -0
- package/docs/configuration.md +150 -12
- package/docs/defect-shapes.md +107 -15
- package/docs/engineering-principles.md +27 -2
- package/docs/environment-variables.md +18 -1
- package/docs/features.md +14 -7
- package/docs/globalconfig.md +11 -3
- package/docs/invariants/git-guard-host.md +7 -3
- package/docs/invariants/language-config.md +15 -4
- package/docs/invariants/lsp-trust-exec.md +25 -4
- package/docs/invariants/paths-os.md +4 -2
- package/docs/invariants/session-telemetry.md +2 -2
- package/docs/language-coverage.md +1 -0
- package/docs/lsp-capability-matrix.md +167 -65
- package/docs/lsp-idle-eviction.md +4 -1
- package/docs/merge-queue-rollout.md +10 -8
- package/docs/module-report-read-symbol.md +34 -23
- package/docs/pi-lens-fixer.md +34 -17
- package/docs/pi-lens-investigator.md +3 -0
- package/docs/pi-lens-merge-policy.md +34 -17
- package/docs/pi-lens-monitor.md +9 -0
- package/docs/pi-lens-orchestration.md +4 -1
- package/docs/pi-lens-reviewer.md +6 -6
- package/docs/pi-lens-subagent.md +19 -3
- package/docs/public-api-stability.md +57 -7
- package/docs/release-qa-baseline.md +7 -4
- package/docs/schema/pi-lens-config-v1.json +21 -2
- package/docs/servercapabilities.md +3 -1
- package/docs/settings.md +11 -7
- package/docs/word-index.md +20 -7
- package/package.json +11 -4
- package/rules/ast-grep-rules/rule-tests/no-accumulating-spread-js-test.yml +37 -0
- package/rules/ast-grep-rules/rule-tests/ts-redundant-filter-map-test.yml +12 -1
- package/rules/ast-grep-rules/rule-tests-disabled/filter-then-map-js-test.yml +12 -0
- package/rules/ast-grep-rules/rule-tests-disabled/filter-then-map-test.yml +25 -0
- package/rules/ast-grep-rules/rules/no-accumulating-spread-js.yml +49 -1
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +1 -2
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +1 -2
- package/rules/ast-grep-rules/rules/ts-redundant-filter-map.yml +9 -1
- package/rules/ast-grep-rules/rules-disabled/filter-then-map-js.yml +17 -0
- package/rules/ast-grep-rules/rules-disabled/filter-then-map.yml +36 -0
- package/rules/ast-grep-rules/self-scan-baseline.json +1 -1
- package/scripts/download-grammars.js +3 -2
- package/skills/pi-lens-lsp-navigation/SKILL.md +5 -1
- package/dist/chunk-46TNM7XZ.js +0 -88
- package/dist/chunk-72OKUXSD.js +0 -31
- package/dist/chunk-7GLOLOSH.js +0 -57
- package/dist/chunk-AKUUMGD5.js +0 -26
- package/dist/chunk-ASUXV767.js +0 -22
- package/dist/chunk-CTADOKYM.js +0 -25
- package/dist/chunk-GNSIWBAT.js +0 -106
- package/dist/chunk-HWDAVBFU.js +0 -49
- package/dist/chunk-JJ2RRESP.js +0 -58
- package/dist/chunk-KXF5R4UN.js +0 -48
- package/dist/chunk-LSC3VADM.js +0 -23
- package/dist/chunk-OE5ZBP7F.js +0 -443
- package/dist/chunk-SHLDT3OI.js +0 -27
- package/dist/chunk-UF7RTZSO.js +0 -27
- package/dist/chunk-W4WP2ERB.js +0 -30
- package/dist/chunk-YES5CACN.js +0 -73
- package/dist/chunk-Z2XAOKHK.js +0 -136
package/docs/configuration.md
CHANGED
|
@@ -10,10 +10,26 @@ There are **two** pi-lens config files:
|
|
|
10
10
|
Both files have the same shape, with one exception noted below the example:
|
|
11
11
|
everything LSP-related lives under an `lsp` namespace inside them.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
13
|
+
LSP fields from a project config are admitted without trust only when they
|
|
14
|
+
are on a short list. On an `lsp.servers.<id>` entry an untrusted project may
|
|
15
|
+
set `name` and nothing else. It may not set `command`, `args`, `extensions`,
|
|
16
|
+
`rootMarkers`, `env`, `initializationOptions`, `covers`, `enabled`, `role`, or
|
|
17
|
+
any field pi-lens does not recognise; on `lsp.serverOverrides.<id>` it may set
|
|
18
|
+
none of `command`, `env`, `initializationOptions`, or any other field. Those
|
|
19
|
+
fields need pi to have marked the project trusted. An untrusted project that
|
|
20
|
+
sets one of them on an `lsp.servers.<id>` entry disables that server for the
|
|
21
|
+
project: pi-lens does not start it, rather than start it on a configuration
|
|
22
|
+
where the project's value replaced one you set in your global config. Under
|
|
23
|
+
`serverOverrides.<id>`, the project's fields are dropped and your global
|
|
24
|
+
override for that built-in applies field by field: a global wrapper `command`
|
|
25
|
+
stays, a global value the project replaced comes back, and a field you did not
|
|
26
|
+
set globally runs on the pi-lens default. The built-in server stays on. Look
|
|
27
|
+
for the `lsp-registry-decision` record: its reason reads "project LSP <field>
|
|
28
|
+
refused for <id>: pi project trust is <state>; the <id> entry is not applied
|
|
29
|
+
for this project" for a server, or "...; the project's <id> override is not
|
|
30
|
+
applied" for an override. An `lsp.servers.<id>` entry with no `extensions`
|
|
31
|
+
list is not registered, since no file can select it. An untrusted or older host
|
|
32
|
+
is fail-closed and emits one bounded notice telling you to mark the project
|
|
17
33
|
trusted in pi or upgrade pi. Global config remains trusted, and a project can
|
|
18
34
|
always disable a server. pi-lens does not maintain a second trust setting.
|
|
19
35
|
|
|
@@ -21,9 +37,14 @@ The editor-facing JSON Schema is published at
|
|
|
21
37
|
[`docs/schema/pi-lens-config-v1.json`](schema/pi-lens-config-v1.json). LSP
|
|
22
38
|
server entries also accept canonical argv arrays, optional `name` (defaulting
|
|
23
39
|
to the map id), `enabled`, `role` (`language` or `auxiliary`), `args`, and
|
|
24
|
-
`rootMarkers`.
|
|
25
|
-
|
|
26
|
-
|
|
40
|
+
`rootMarkers`. A `command` is either a bare string (launched with `args`,
|
|
41
|
+
default `["--stdio"]`) or an argv array whose first element is the program;
|
|
42
|
+
the array's remaining elements come before `args`, and no `--stdio` is added to
|
|
43
|
+
it. A `command` that is neither, or an empty or non-string array, fails at
|
|
44
|
+
launch with a message naming the field. These new fields are experimental;
|
|
45
|
+
reserved role, root-policy, and timing semantics are inert until their planned
|
|
46
|
+
catalog slices land, so this schema slice does not change server launch
|
|
47
|
+
behavior.
|
|
27
48
|
|
|
28
49
|
```jsonc
|
|
29
50
|
{
|
|
@@ -231,6 +252,14 @@ once no matter which spelling each file uses. Migrating does not change the
|
|
|
231
252
|
answer, staying un-migrated is not a way around the denial, and a half-migrated
|
|
232
253
|
pair of files merges rather than one clobbering the other.
|
|
233
254
|
|
|
255
|
+
An entry must name a server pi-lens knows: a built-in server id or a server
|
|
256
|
+
declared under `lsp.servers`. An entry that names neither is dropped and
|
|
257
|
+
reported with one `PILENS_CFG_0005` notice per distinct id, which quotes the
|
|
258
|
+
entry and says it is not a recognized LSP server id. Without that notice a
|
|
259
|
+
misspelled id would match no server, so the server you meant to turn off would
|
|
260
|
+
keep running. Entries that are not strings are kept as written and match no
|
|
261
|
+
server.
|
|
262
|
+
|
|
234
263
|
Denying a file's **language server** (its primary, such as `json` or
|
|
235
264
|
`typescript`) leaves that file unchecked for the language itself. Every
|
|
236
265
|
diagnostics route then reports a file with no findings as **unconfirmed**, not
|
|
@@ -252,6 +281,115 @@ Two rules make the rest of the table unambiguous:
|
|
|
252
281
|
same thing as the canonical one, the canonical one is used — otherwise the
|
|
253
282
|
migration below could never be completed.
|
|
254
283
|
|
|
284
|
+
### `dispatch.disabledRunners` — turning a dispatch runner off
|
|
285
|
+
|
|
286
|
+
`lsp.disabledServers` switches off a language server. A dispatch **runner**
|
|
287
|
+
(a linter, type-checker, or build such as `dotnet-build`, `javac`, or
|
|
288
|
+
`rust-clippy`) has its own denial list, with the same semantics:
|
|
289
|
+
|
|
290
|
+
```jsonc
|
|
291
|
+
// ~/.pi-lens/config.json (or a project .pi-lens.json)
|
|
292
|
+
{ "dispatch": { "disabledRunners": ["dotnet-build"] } }
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
- **Union across tiers.** Like `lsp.disabledServers`, the list is the union of
|
|
296
|
+
`~/.pi-lens/config.json`, the project `.pi-lens.json`, and any nested
|
|
297
|
+
`.pi-lens.json`. A project can add a runner and can never re-enable one a
|
|
298
|
+
farther tier denied.
|
|
299
|
+
- **The tool never spawns.** The dispatcher skips a disabled runner before its
|
|
300
|
+
precondition and before it runs, so no availability probe, no `dotnet build`,
|
|
301
|
+
nothing. The skip is recorded with the reason `disabled-by-config`
|
|
302
|
+
(`latency.log`, `skipReason`). It is an operator decision, not a failure: it
|
|
303
|
+
raises no blocker and no "tool failed" notice, and a `fallback` group (such as
|
|
304
|
+
C#'s `lsp`, then `dotnet-build`) simply moves on to its next member. The other
|
|
305
|
+
runners of the group, the language server included, run as before.
|
|
306
|
+
- **Unknown ids are dropped, not ignored silently.** An entry that names no
|
|
307
|
+
registered runner is dropped with a `PILENS_CFG_0005` warning that quotes the
|
|
308
|
+
entry, so a typo does not read as a runner that was turned off.
|
|
309
|
+
- **Edits apply on the next dispatch.** The list is resolved for each dispatch,
|
|
310
|
+
so a change to the file needs no restart.
|
|
311
|
+
- **The nearest config owns the file.** A nested `.pi-lens.json` governs the
|
|
312
|
+
files under it, so a denial there applies to those files only. `rules` reads
|
|
313
|
+
the same per-file resolution (see below).
|
|
314
|
+
- **Disabling the only checker leaves the file unconfirmed.** Turning off a
|
|
315
|
+
runner that was the sole check for a file kind produces a notice that names
|
|
316
|
+
`dispatch.disabledRunners` (once per session, then the status line alone)
|
|
317
|
+
rather than a clean result. When another runner of the file is missing,
|
|
318
|
+
timed out, or failed as well, the notice says so and names the denial beside
|
|
319
|
+
it.
|
|
320
|
+
|
|
321
|
+
`pilens_effective_config file=Program.cs` reports the runner as denied, with the
|
|
322
|
+
tier and file that denied it, while the language server stays selected:
|
|
323
|
+
|
|
324
|
+
```console
|
|
325
|
+
$ pilens_effective_config file=src/Program.cs
|
|
326
|
+
tools:
|
|
327
|
+
lsp selected
|
|
328
|
+
dotnet-build ✗ disabled-by-config (global ~/.pi-lens/config.json → /dispatch/disabledRunners/0)
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
`dispatch.runnerTimeoutFloorMs`, the other `dispatch` key, stays global-only.
|
|
332
|
+
Putting it in a project `.pi-lens.json` logs the usual one-time "global-only"
|
|
333
|
+
notice.
|
|
334
|
+
|
|
335
|
+
### `rules.<id>` — read from each file's own config
|
|
336
|
+
|
|
337
|
+
`rules.<id>.disable`, `select`, and `ignorePaths` are resolved for each file
|
|
338
|
+
from the nearest directory at or above it that holds a `.pi-lens.json`, up to
|
|
339
|
+
the workspace root. That resolution layers the global file, the workspace
|
|
340
|
+
root's file, and every nested file between, by the field-wise order above. So a
|
|
341
|
+
nested `.pi-lens.json` governs the files under it and no others, and the
|
|
342
|
+
workspace root's policy still reaches them. Every surface that filters by rule
|
|
343
|
+
policy reads it this way: the per-edit dispatch, `lens_diagnostics`,
|
|
344
|
+
`lsp_diagnostics`, and the turn-end advisories.
|
|
345
|
+
|
|
346
|
+
`rules.<id>.disable` is a denial, like `lsp.disabledServers`: it resolves as the
|
|
347
|
+
union of every tier's list. A project or nested file can add rules to what the
|
|
348
|
+
global or root file disabled and can never re-enable one. `select` is an
|
|
349
|
+
allowlist, not a denial: per grouping key, the nearest file that sets it supplies
|
|
350
|
+
the whole list. Lists under different keys are unioned, so a global `k.select:
|
|
351
|
+
[x]` and a nearer file's `k2.select: [y]` keep both `x` and `y`.
|
|
352
|
+
|
|
353
|
+
In both lists a member that is not a string, or a value that is not an array,
|
|
354
|
+
is dropped and the valid members keep their effect. A string member is trimmed
|
|
355
|
+
before it is matched, so `" ra "` names `ra`, and a blank member is dropped. The
|
|
356
|
+
global file reports
|
|
357
|
+
each one with a `PILENS_CFG_0005` notice. A project or nested file reports a
|
|
358
|
+
value that is not an array, or a list whose members are all dropped, with the
|
|
359
|
+
same notice; a non-string member beside a valid string is dropped without one.
|
|
360
|
+
A `select` array whose members are all dropped still sets that key's list: it
|
|
361
|
+
is empty, so it lifts a farther file's allowlist for the key, as `select: []`
|
|
362
|
+
does. A `select` that is not an array is ignored, and the farther list stands.
|
|
363
|
+
|
|
364
|
+
`ignorePaths` entries follow the same gitignore rules as the `ignore` field. Each entry is
|
|
365
|
+
relative to the directory of the file that declares it: a global entry, and an entry in the
|
|
366
|
+
workspace root's own file, match against the workspace root, and an entry in `pkg/.pi-lens.json`
|
|
367
|
+
matches under `pkg/`:
|
|
368
|
+
|
|
369
|
+
```jsonc
|
|
370
|
+
// pkg/.pi-lens.json — carves out pkg/legacy/** except pkg/legacy/keep.ts; nothing at the root
|
|
371
|
+
{ "rules": { "no-eval": { "ignorePaths": ["legacy/**", "!legacy/keep.ts"] } } }
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
- The last matching entry wins, so `!` re-includes a file an earlier entry carved out, and an
|
|
375
|
+
entry placed after a `!` ignores it again.
|
|
376
|
+
- A leading `/` roots the entry at the declaring file's directory: `/legacy/**` is `legacy/**`
|
|
377
|
+
there and nowhere deeper.
|
|
378
|
+
- A trailing `/` names a directory: `legacy/` carves out every directory named `legacy` at any
|
|
379
|
+
depth below the file, and everything in it.
|
|
380
|
+
- An entry with no slash matches at any depth below the file: `*.gen.ts` carves out
|
|
381
|
+
`pkg/a.gen.ts` and `pkg/src/b.gen.ts`. To carve out a whole directory, end the entry with `/` or
|
|
382
|
+
`/**`: a bare `legacy` names a file called `legacy`, not the files inside a directory of that name.
|
|
383
|
+
- An entry that climbs out of the declaring directory, such as `../other/**`, matches nothing.
|
|
384
|
+
A file outside the workspace root is never carved out.
|
|
385
|
+
- A line starting with `#` is a comment, as in `.gitignore`, and is dropped.
|
|
386
|
+
|
|
387
|
+
The files are a union: a path is carved out when any file's entries carve it out. A nearer file
|
|
388
|
+
adds carve-outs and never lifts one, so a `!` entry re-includes only against the entries of its
|
|
389
|
+
own file, and a project `!` cannot clear a carve-out the global config declared. Unlike the
|
|
390
|
+
`ignore` field, `ignorePaths` has no cross-file lift: a nearer file's `!` can lift a path that a
|
|
391
|
+
parent file's `ignore` line hid, but never a path that a parent file's `ignorePaths` entry carves out.
|
|
392
|
+
|
|
255
393
|
## Legacy locations (still read; being removed)
|
|
256
394
|
|
|
257
395
|
These are read for their deprecation window and then **removed**. Each one you
|
|
@@ -283,14 +421,14 @@ canonical key wins, and the keys you have not moved yet keep working.
|
|
|
283
421
|
Only keys pi-lens actually recognizes get "move it to …" advice. A key in a
|
|
284
422
|
legacy file that is not a pi-lens setting at all — a typo, or a leftover from
|
|
285
423
|
another tool — cannot be migrated anywhere, so it gets the ordinary
|
|
286
|
-
unrecognized-key notice (`
|
|
424
|
+
unrecognized-key notice (`PILENS_CFG_0004`) and is counted in ONE whole-file
|
|
287
425
|
`PILENS_CFG_0003` notice for the file rather than being told to move.
|
|
288
426
|
|
|
289
427
|
## When a config is ignored
|
|
290
428
|
|
|
291
|
-
A file that
|
|
292
|
-
pi-lens runs on defaults for it and says so once, with the
|
|
293
|
-
`PILENS_CFG_0001`. A field whose value does not match its declared type is
|
|
429
|
+
A file that is unreadable, unparsable, or not a JSON object is **ignored, never
|
|
430
|
+
partially applied** — pi-lens runs on defaults for it and says so once, with the
|
|
431
|
+
code `PILENS_CFG_0001`. A field whose value does not match its declared type is
|
|
294
432
|
dropped on its own (`PILENS_CFG_0005`), and an unrecognized field is dropped
|
|
295
433
|
with a message naming the key (`PILENS_CFG_0004`). If resolving a file fails
|
|
296
434
|
internally the whole file is ignored and said so under its own code
|
|
@@ -307,7 +445,7 @@ them rather than by what they say — both are about values that were rejected:
|
|
|
307
445
|
deprecation notices (`PILENS_CFG_0002`, `PILENS_CFG_0003`), which share this
|
|
308
446
|
list;
|
|
309
447
|
- what the **loader** reading the file produced on its own — unknown top-level
|
|
310
|
-
keys and
|
|
448
|
+
keys (`PILENS_CFG_0004`) and values it refused (`PILENS_CFG_0005`).
|
|
311
449
|
|
|
312
450
|
Each list is bounded at 20 records: up to 19 notices plus, when the bound bit,
|
|
313
451
|
a single `PILENS_CFG_0007` summary giving the count that was suppressed, so a
|
package/docs/defect-shapes.md
CHANGED
|
@@ -170,6 +170,9 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
170
170
|
path discloses its truncation on the rendered surface; a count recorded
|
|
171
171
|
only in `latency.log` is not disclosure (#3166 r2: an 80-finding input
|
|
172
172
|
bound zeroed a neighbour's genuine errors, counted only in the log).
|
|
173
|
+
Removing a false "unavailable" notice never turns the file clean: a file
|
|
174
|
+
no analyzer applies to reads "not analyzed" (#5238 r2 read
|
|
175
|
+
`build.gradle` as "Groovy clean" after its notice was dropped).
|
|
173
176
|
An out-of-session-root project edit records one bounded degradation and
|
|
174
177
|
uses the existing advisory notice seam; intended vendor skips and pi-owned
|
|
175
178
|
OS-temp artifacts stay silent (`clients/runtime-tool-result.ts`,
|
|
@@ -179,9 +182,12 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
179
182
|
decides only delivery, and a run with no verdict (failed, unanswered, in
|
|
180
183
|
flight) observes nothing, so neither retires a recorded blocker. A skip
|
|
181
184
|
has a verdict only with a stated not-applicable reason
|
|
182
|
-
(`RUNNER_SKIP_REASONS`).
|
|
183
|
-
|
|
184
|
-
|
|
185
|
+
(`RUNNER_SKIP_REASONS`). `not-enabled` (an opt-in runner left off, #5042)
|
|
186
|
+
is the one stated reason that stays a no-verdict: admitting it would retire
|
|
187
|
+
recorded helm-render blockers and stop their owed ranges. A recorded blocker
|
|
188
|
+
is still observed only at its own line, aligned to the current bytes:
|
|
189
|
+
another occurrence of the same rule is not it. A fallback for missing
|
|
190
|
+
evidence narrows what retires:
|
|
185
191
|
with no alignment, its identity anywhere keeps it. It stays a per-write
|
|
186
192
|
hold and never widens what counts as the same finding: the match still
|
|
187
193
|
needs the entry's own line text, and owed lines are matched by content,
|
|
@@ -195,6 +201,18 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
195
201
|
kept entry with no place in a write's bytes is recorded as such
|
|
196
202
|
(`positionStale`), never inferred later from one line's hash, and a line
|
|
197
203
|
with no word character owes nothing by its text.
|
|
204
|
+
A non-authoritative answer never stands in for a primary that never
|
|
205
|
+
answered: a `fallbackFor` alternate (python-jedi beside a pyright that was
|
|
206
|
+
trust-refused, failed to start, sat in a breaker cool-down or was not
|
|
207
|
+
installed) is not its owner, so the file reads unavailable with the owner
|
|
208
|
+
named, never "confirmed clean" (#5014). The rule admits the known-good
|
|
209
|
+
forms (a non-alternate primary acquired, an alternate standing in for an
|
|
210
|
+
owner the operator disabled, an alternate whose owner resolved no root) in
|
|
211
|
+
`unansweredPrimaries` (`clients/lsp/index.ts`); every other cause, listed or
|
|
212
|
+
not, lands unconfirmed. Screen: can a file read clean when its primary
|
|
213
|
+
never answered? Population enforcer:
|
|
214
|
+
`tests/clients/lsp/unanswered-primaries-fallback-5014.test.ts` (every
|
|
215
|
+
registered `fallbackFor` alternate).
|
|
198
216
|
Enforced by `tests/clients/dispatch/runners/run-outcome-ratchet.test.ts`,
|
|
199
217
|
`tests/clients/dispatch/runners/parsed-nothing-sweep.test.ts` and
|
|
200
218
|
`tests/clients/delivery-surface-ratchet.test.ts` (partial: no detector
|
|
@@ -273,7 +291,17 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
273
291
|
for). Derive the named set from the registry, never a hand list. Screen:
|
|
274
292
|
render the prose under each posture combination and each host, and assert
|
|
275
293
|
every clause is true (#4293, #4294 enabled axis; #4682 lazy axis and the
|
|
276
|
-
hand list that dropped two tools).
|
|
294
|
+
hand list that dropped two tools). User docs that say which tools a
|
|
295
|
+
script or user can call are in scope too (#5242: "every pi-lens tool"
|
|
296
|
+
under `--no-lazy-tools` missed the enabled axis).
|
|
297
|
+
|
|
298
|
+
90. **Generated proof line for a step that did not run:** a composer that
|
|
299
|
+
writes a PR, issue or report body states what ran. A branch where the step
|
|
300
|
+
failed, was skipped or timed out renders that outcome, never the success
|
|
301
|
+
sentence (#5243 r1: the nightly refresh body said the flips were
|
|
302
|
+
classified against master when the flip check had failed). Screen: for
|
|
303
|
+
each proof sentence a composer emits, which input proves the step ran,
|
|
304
|
+
and does the failed branch render something else?
|
|
277
305
|
|
|
278
306
|
</important>
|
|
279
307
|
|
|
@@ -328,6 +356,24 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
328
356
|
try) by `tests/clients/worker-message-boundary-ratchet.test.ts`; screen
|
|
329
357
|
`close` and timer callbacks by hand.
|
|
330
358
|
|
|
359
|
+
89. **Serial await of independent work on a hot path:** a `for` loop or a run
|
|
360
|
+
of `await`s on the edit, write or turn-end path waits for each call before
|
|
361
|
+
starting the next, though no call needs another's result. The cost is the
|
|
362
|
+
sum of the calls instead of the slowest one: LSP servers spawned one after
|
|
363
|
+
another made a cold first edit block ~7 s (#2540), and a serial stat walk
|
|
364
|
+
took 8 s on a slow filesystem (#1409). Overlapping is not always a win:
|
|
365
|
+
some servers answer one request at a time (typescript-language-server
|
|
366
|
+
forwards to one tsserver; #387, #631), and a write-ordered loop
|
|
367
|
+
(`runtime.nextWriteIndex()`, a pipeline claim) must stay serial. Screen: do
|
|
368
|
+
the calls this loop or sequence awaits one at a time need each other's
|
|
369
|
+
results, share a write order, or go to one server that answers one request
|
|
370
|
+
at a time? If none, overlap them through `clients/map-with-concurrency.ts`;
|
|
371
|
+
if one does, a comment at the loop names it. Measure before overlapping
|
|
372
|
+
calls to one server. #5174 is the open instance. Census: not
|
|
373
|
+
countable. Enforcer: none: judgment-only; a scan cannot tell an
|
|
374
|
+
independent await from an ordered one without reading what each call
|
|
375
|
+
feeds. Instances and dates: `HISTORY.md`.
|
|
376
|
+
|
|
331
377
|
60. **Wasm failure outside the #3605 containment:** every failure thrown out
|
|
332
378
|
of web-tree-sitter classifies through `classifyTreeSitterWasmError`, and a
|
|
333
379
|
`catch` inside a `withParsedTree` consumer calls `reportWasmAbort` before it
|
|
@@ -411,6 +457,20 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
411
457
|
tell a copied rule from a coincidental literal without reading what the
|
|
412
458
|
value feeds. Instances and dates: `HISTORY.md`.
|
|
413
459
|
|
|
460
|
+
88. **Learned attribution keyed on a name alone:** tier 4 of
|
|
461
|
+
`classifyMutatingTool` admits any tool name that was once seen with a disk
|
|
462
|
+
change in its call window and a `path` field, then classifies every later
|
|
463
|
+
call of that name as an edit. A tool that never wrote (one operation of a
|
|
464
|
+
mixed tool, #4139) and a call whose work already ran (a provider's
|
|
465
|
+
display-only replay, #5160) both reach it on name plus path alone. Tier 4 is
|
|
466
|
+
admit-by-default with enumerated exemptions (the registry names, the
|
|
467
|
+
`cursor-replay-` id prefix); a third carve-out is the trigger to redesign it
|
|
468
|
+
fail-closed, learning only when the call, not the window, owns the change.
|
|
469
|
+
Screen: can a call whose work already ran, or a tool that never wrote, reach
|
|
470
|
+
the learned lookup or the arm gate on name plus path alone? Census: not
|
|
471
|
+
countable. Enforcer: none: judgment-only, the exempt population is whatever
|
|
472
|
+
other providers replay or mix. Instances and dates: `HISTORY.md`.
|
|
473
|
+
|
|
414
474
|
</important>
|
|
415
475
|
|
|
416
476
|
<important if="a test double, ratchet or sweep">
|
|
@@ -455,8 +515,9 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
455
515
|
38. **Data-only admission:** a new exemption or baseline row requires a reason
|
|
456
516
|
in a separate checked file and a fixture that crosses the boundary.
|
|
457
517
|
|
|
458
|
-
44. **Portable entry-module check:**
|
|
459
|
-
`
|
|
518
|
+
44. **Portable entry-module check:** decide the entry module only with
|
|
519
|
+
`isMainModule(import.meta.url)` from `scripts/lib/is-main-module.mjs`;
|
|
520
|
+
`scripts/hooks/guard-bash.mjs` is the one standalone gate.
|
|
460
521
|
|
|
461
522
|
45. **Root wrapper drops metadata:** wrappers preserve the complete marker table
|
|
462
523
|
and are checked against direct root resolution.
|
|
@@ -583,6 +644,9 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
583
644
|
(`~/.config/.opengrep`, `~/.config/.semgrep`), and a symlinked managed `bin`
|
|
584
645
|
lets an installer write through to the real `~/.pi-lens/bin`. The pin is
|
|
585
646
|
the whole set, assigned once in the worker so every child inherits it.
|
|
647
|
+
npm's cache and log directory (`npm_config_cache`, default `~/.npm`) is
|
|
648
|
+
in the set: two probes on 2026-11-04 (the #5239 fixer, the #5244
|
|
649
|
+
reviewer) wrote `~/.npm/_logs` through `npx`.
|
|
586
650
|
Screen: which directory does the process I run resolve from, and is every
|
|
587
651
|
variable that names it pinned? Enforcer:
|
|
588
652
|
`tests/clients/worker-home-pin-hermeticity.test.ts` (a real child reports
|
|
@@ -605,11 +669,13 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
605
669
|
the lane's timeout scale and is refused; a same-named local constant is
|
|
606
670
|
admitted and an import alias of the shared one is refused (no live member
|
|
607
671
|
either way). Screen: does this case call a walker or read a binding one
|
|
608
|
-
produced, and is its third argument one of those two forms? Census:
|
|
609
|
-
`tests/config`, all budgeted;
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
672
|
+
produced, and is its third argument one of those two forms? Census: 244
|
|
673
|
+
under `tests/` (154 in `tests/config`, all budgeted; 90 outside it, of which
|
|
674
|
+
87 are refused and admitted by name in
|
|
675
|
+
`tests/config/tree-census-timeout.baseline.json`, and 3 budgeted). Enforcer:
|
|
676
|
+
`tests/config/tree-census-timeout.test.ts` (it derives the declaration
|
|
677
|
+
callee from the file's vitest imports, resolves walker aliases, and counts a
|
|
678
|
+
test-shaped call it cannot trace as a census).
|
|
613
679
|
It does not read a walker reached through a helper in another module, a
|
|
614
680
|
variable-bound arrow-function walker, a local spawn wrapper, or a walk named
|
|
615
681
|
only by an enclosing `describe.each` or loop; `Unit tests Windows` is the
|
|
@@ -622,8 +688,15 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
622
688
|
(`tests/clients/interleaving-kit.ts`), which reads a real-clock deadline
|
|
623
689
|
scaled by `PI_LENS_TEST_TIMEOUT_SCALE`, and give the test a timeout above
|
|
624
690
|
that deadline. Screen: does the wait end on the event it waits for or on a
|
|
625
|
-
real-clock deadline, never on a count? Enforcer:
|
|
626
|
-
|
|
691
|
+
real-clock deadline, never on a count? Enforcer: the governance ast-grep
|
|
692
|
+
rules `turn-count-wait` and `turn-count-wait-test-hook`
|
|
693
|
+
(`scripts/governance-rules/`, run by `npm run astgrep:self-scan`), with a
|
|
694
|
+
reasoned baseline. It does not see a count loop with no exit besides the
|
|
695
|
+
count (a pure `for (N) await yield` flush), a wait spelled as recursion, a
|
|
696
|
+
count written as iteration over a generated range
|
|
697
|
+
(`for (const _ of Array.from({ length: N }))`), or a loop that compares a
|
|
698
|
+
clock value for some other purpose.
|
|
699
|
+
Instances and dates: `HISTORY.md`.
|
|
627
700
|
|
|
628
701
|
</important>
|
|
629
702
|
|
|
@@ -718,8 +791,27 @@ file-scoped worklist and receives no project-wide scanner output.
|
|
|
718
791
|
<reason>`, and a `session` owner states `sessionSeamException`, why a scope
|
|
719
792
|
cell cannot hold it yet. A moved store has no process container and no
|
|
720
793
|
entry; `scanScopeCellKeys` pins every cell by file and key
|
|
721
|
-
(`SESSION_CELL_KEYS`).
|
|
722
|
-
|
|
794
|
+
(`SESSION_CELL_KEYS`). The same `auditOwnerKeys` reads all three lists:
|
|
795
|
+
`SESSION_STATE_REGISTRY`, the file-level `EXEMPT_SESSION_STATE_FILES` rows
|
|
796
|
+
and the declared `SESSION_STORE_REGISTRY` rows (#5027); a file with several
|
|
797
|
+
owners states the narrowest. The scan behind them
|
|
798
|
+
(`scanSessionStateCandidates`) flags a file for a module-level container
|
|
799
|
+
with or without a reset, except one admitted constant: an UPPER_SNAKE
|
|
800
|
+
built-in `Map`/`Set`/`WeakMap`/`WeakSet` declared `const` whose every use
|
|
801
|
+
in `clients/`, `tools/`, `mcp/` and `index.ts` is a read; and for a class
|
|
802
|
+
field or `this.x` assignment bound to `new <container or clients/ class>`
|
|
803
|
+
or `[]`, or a depth-1 `key: new <container>` member of a module-level
|
|
804
|
+
object literal (`globalState = { reads: new Map() }`). An admitted
|
|
805
|
+
constant removes the symbol, not the file: a file that also exports a
|
|
806
|
+
reset stays a candidate with a 0 pin. One symbol-count pin counts the
|
|
807
|
+
containers, fields and members. Partial: it walks `clients/`;
|
|
808
|
+
`tools/` holds no candidate today, `index.ts` is censused by
|
|
809
|
+
`tests/config/session-scope-sweep.test.ts` (#3611), and `mcp/server.ts`
|
|
810
|
+
(`lspReadyCwds`) is outside the scan root. A field built by a factory call,
|
|
811
|
+
through another binding or an aliased constructor is not read, and an
|
|
812
|
+
admitted constant's `forEach` callback or stored value can be mutated
|
|
813
|
+
unseen (`SWEEP_HEURISTIC_LIMITS`; live population 0), and the owner value
|
|
814
|
+
itself is a judgment the audit only forces to be stated.
|
|
723
815
|
|
|
724
816
|
87. **Factory-time read of a host value set later:** pi applies an extension flag's command-line value after every factory has run, so a flag read while the factory runs answers the registered default. Screen: does any flag read run while the factory runs, and does the host test apply the value after the factory, as pi does? Read it in a handler, a command or a tool, or once in `session_start`. Enforcer: `tests/config/factory-flag-read-sweep.test.ts` (partial: a reader handed to a callee that invokes it synchronously is not seen). Instances and dates: `HISTORY.md`.
|
|
725
817
|
|
|
@@ -72,8 +72,10 @@ verdict (a trust check, a lint, a census, a body check), it admits a short list
|
|
|
72
72
|
of known-good forms and refuses everything else. It never enumerates known-bad
|
|
73
73
|
spellings. Each review of an enumerated gate finds the next spelling it missed;
|
|
74
74
|
one gate took sixteen rounds that way. Once a second round finds a new
|
|
75
|
-
spelling, stop patching and redesign.
|
|
76
|
-
|
|
75
|
+
spelling, stop patching and redesign. A value the gate cannot resolve to a
|
|
76
|
+
known-good literal (computed, concatenated, aliased, templated, reached through
|
|
77
|
+
an indirection) is unrecognized: it counts as a hit, never a pass. Screen: can
|
|
78
|
+
an input nobody planned for pass the gate?
|
|
77
79
|
|
|
78
80
|
**Blast radius as a call-tree diff.** For any change to a shared seam, list the
|
|
79
81
|
changed symbol, its callers above, its callees below, with plus and minus on the
|
|
@@ -115,6 +117,13 @@ it, and paste the red. A checked box with no transcript is treated as false. A
|
|
|
115
117
|
mutation that fails to compile proves nothing about the test; redo it as a
|
|
116
118
|
compile-valid change. A guard that cannot be made to red does not need to exist.
|
|
117
119
|
|
|
120
|
+
**A precision figure names its judgement and an outside sample.** A claim that
|
|
121
|
+
a rule, check or heuristic is N% precise states what counts as a true positive,
|
|
122
|
+
and someone other than its author judges a random sample. "The pattern matched"
|
|
123
|
+
is not "the finding is worth acting on": one rule reported 611 of 611 hits real
|
|
124
|
+
on a type check, and an independent sample of 58 found none worth the rewrite.
|
|
125
|
+
Below the stated bar, the rule ships disabled with the count recorded.
|
|
126
|
+
|
|
118
127
|
**Tautological tests are harmful.** A test observes behaviour through the real
|
|
119
128
|
seam and asserts an independent effect. It never restates the implementation,
|
|
120
129
|
never asserts a value its own setup supplied, and never swaps a real in-process
|
|
@@ -138,6 +147,13 @@ thing is required, a registry entry, a baseline row and lane membership. A
|
|
|
138
147
|
mocked seam is not a real spawn and gets an exemption with its reason, never an
|
|
139
148
|
admission.
|
|
140
149
|
|
|
150
|
+
**A gate judges the actor's delta, not inherited state.** A check run on an
|
|
151
|
+
artifact someone edits (a tracker body, a shared file, a long-lived record)
|
|
152
|
+
judges only what that edit adds or changes. Inherited violations belong in a
|
|
153
|
+
baseline that shrinks on purpose. Refusing an honest edit for debt it did not
|
|
154
|
+
create blocks the work or invites routing around the gate. If the gate cannot
|
|
155
|
+
compute the delta, it checks the whole artifact, failing closed.
|
|
156
|
+
|
|
141
157
|
**A new ratchet sweeps the open changes before it lands.** A governance test
|
|
142
158
|
that rejects a new pattern fails every open change that already adds one, and
|
|
143
159
|
none of them conflict textually, so nothing warns. Before merging a ratchet,
|
|
@@ -219,6 +235,15 @@ cleanup, triage and status upkeep. The script surfaces unfinished work and
|
|
|
219
235
|
never hides it: stalled work is restarted, not unassigned, archived or deleted.
|
|
220
236
|
Screen: is this the second time this step was done by hand?
|
|
221
237
|
|
|
238
|
+
**Process carries the net-count rule too.** A new guard, hook, script, lint
|
|
239
|
+
rule, ratchet or scheduled routine retires one of the same kind in the same
|
|
240
|
+
change, or it cites fire data showing what the existing ones miss. Each rule
|
|
241
|
+
must also earn its keep: count how often it fired, and what each fire led to
|
|
242
|
+
(a real fix, a wording edit, or a route-around). One that never fired in its
|
|
243
|
+
window and names no recurrence is demoted or deleted. Process cost is paid on
|
|
244
|
+
every change, while the bug a rule prevents may never arrive. Screen: what
|
|
245
|
+
does this rule retire, and when did the last one like it fire?
|
|
246
|
+
|
|
222
247
|
## 4. Honesty and records
|
|
223
248
|
|
|
224
249
|
**Closes versus refs follows delivery, not optimism.** Close only when every
|
|
@@ -173,7 +173,14 @@ Set to `1` to skip auto-installing language servers. Off by default.
|
|
|
173
173
|
### `PI_LENS_DISABLE_TOOL_INSTALL`
|
|
174
174
|
|
|
175
175
|
Set to `1` to skip auto-installing managed tools (formatters, linters,
|
|
176
|
-
scanners). Off by default.
|
|
176
|
+
scanners). Off by default. It stops four things: the managed installer, the
|
|
177
|
+
lazy installer (`gem install rubocop`, `rustup component add clippy|rustfmt`),
|
|
178
|
+
govulncheck's `go install`, and any `npx` package-runner spawn, which runs
|
|
179
|
+
offline (`npm_config_offline=true`): it uses npm's cache or fails, and never
|
|
180
|
+
downloads. A refused lazy or govulncheck install records one `install-disabled`
|
|
181
|
+
degradation row per tool per session. It does not cover `bunx` (which ignores
|
|
182
|
+
that variable; pi-lens never spawns it) or language-server installs (see
|
|
183
|
+
`PI_LENS_DISABLE_LSP_INSTALL`).
|
|
177
184
|
|
|
178
185
|
## Context injection
|
|
179
186
|
|
|
@@ -260,6 +267,16 @@ Explicit path to a Lombok jar for the Java language server, used when
|
|
|
260
267
|
auto-resolution does not find one. The legacy `LOMBOK_JAR` variable is also
|
|
261
268
|
honored.
|
|
262
269
|
|
|
270
|
+
### `GROOVY_LANGUAGE_SERVER_JAR`
|
|
271
|
+
|
|
272
|
+
Path to the `groovy-language-server-all.jar` the built-in Groovy row runs as
|
|
273
|
+
`java -jar <jar>`, when no `groovy-language-server` launcher is on `PATH`.
|
|
274
|
+
groovy-language-server publishes no release: build it with `./gradlew build` in
|
|
275
|
+
a checkout of GroovyLanguageServer/groovy-language-server and point this at
|
|
276
|
+
`build/libs/groovy-language-server-all.jar`. Java 17 or newer is found the same
|
|
277
|
+
way the Java language server finds it. A path that is not a file reads as not
|
|
278
|
+
installed, and the session start log says so.
|
|
279
|
+
|
|
263
280
|
## Project map
|
|
264
281
|
|
|
265
282
|
### `PI_LENS_MAP_MAX_NODES`
|
package/docs/features.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
### LSP Support
|
|
4
4
|
|
|
5
|
-
pi-lens includes **
|
|
5
|
+
pi-lens includes **51 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — and one opt-in, JS/TS-only auxiliary, fallow, off unless `fallow.enabled` is set; see below). LSP is **enabled by default**; use `--no-lsp` to disable it for a session. Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server with a managed installer is not installed, pi-lens offers an interactive install prompt; toolchain-bundled servers, such as Lean's `lake`, are PATH-only, and pi-lens never installs or manages them.
|
|
6
6
|
|
|
7
7
|
**LSP Idle Management:** LSP servers shut down after 240 seconds of inactivity (no files modified) to free resources. The timer resets when you resume editing, preventing cold-start penalties during active development.
|
|
8
8
|
|
|
@@ -19,7 +19,9 @@ pi-lens includes **50 language server definitions** (including four cross-cuttin
|
|
|
19
19
|
- **`capabilities`** — shows which operations are supported by the active LSP server(s) for a file, read directly from the cached `initialize` response (no round-trip).
|
|
20
20
|
- **Symbol column resolution** — passing `symbol: "myFunc"` instead of an exact `character` position resolves the correct column automatically. Use `symbol: "foo#2"` for the second occurrence of `foo` on the line.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
`lsp_navigation` answers with Neovim-style text by default: a `path:line:col` location list, `hover` markdown, an indented `start-end kind name` symbol tree, and `path:line:col: severity: message` diagnostic rows. Pass `view: "json"` for the structured envelope the pre-text default returned (refs #1449).
|
|
23
|
+
|
|
24
|
+
LSP servers for: TypeScript, Deno, Python (pyright/basedpyright + jedi), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, PowerShell, C# (omnisharp), F#, Java (JDT LS, with Lombok javaagent support when a Lombok jar is available), Kotlin, Groovy (groovy-language-server, from PATH or `GROOVY_LANGUAGE_SERVER_JAR`), Lean, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, Typst (tinymist), Markdown (marksman), OCaml, Clojure, CUE (syntax and parse diagnostics; evaluation errors via the cue-vet auxiliary runner), Terraform, Nix, Bash, Shuck (zsh-aware shell language server), Fish, CMake, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, CSS.
|
|
23
25
|
|
|
24
26
|
|
|
25
27
|
### TypeScript and JavaScript server
|
|
@@ -149,6 +151,8 @@ pi-lens enforces a **read-before-edit** policy on all file writes and edits. Bef
|
|
|
149
151
|
|
|
150
152
|
Coverage is tracked across multiple reads: two reads of lines 1–100 and 101–200 together satisfy a full-file write. Symbol-expanded reads (small reads widened to the enclosing symbol via tree-sitter, labelled with a leading note) count toward coverage at the symbol level. Markdown files generate a warning instead of blocking (edits outside the section-expanded read range are warned, not silently passed). Plain-text (`.txt`) and log (`.log`) files remain fully exempt.
|
|
151
153
|
|
|
154
|
+
A provider extension's display-only replay of work that already ran is not guarded. pi-cursor-sdk replays Cursor's native edits as tool calls whose ids start with `cursor-replay-`; the files were written before the replay arrived, so an "Edit without read" refusal would protect nothing and only turn the replayed card into an error. Such a call is never checked by the read guard and never taught to pi-lens as a mutating tool name. A real `edit` or `write` call and Cursor's real bridged executions (`cursor-pi-bridge-*`) are checked as usual.
|
|
155
|
+
|
|
152
156
|
Override for a single edit: `/lens-allow-edit <path>`
|
|
153
157
|
|
|
154
158
|
Configure behavior with `--no-read-guard` to disable it entirely, or use the
|
|
@@ -164,7 +168,7 @@ instead of a flat blob of source. See
|
|
|
164
168
|
[`module-report-read-symbol.md`](module-report-read-symbol.md)
|
|
165
169
|
for the full design and token-efficiency numbers.
|
|
166
170
|
|
|
167
|
-
**`module_report(
|
|
171
|
+
**`module_report(path, maxRefsPerSymbol?, focus?, view?, blastRadius?, blastRadiusDepth?)`** —
|
|
168
172
|
returns a structured outline: every symbol's name/kind/startLine/endLine/signature
|
|
169
173
|
(plus a first-line `doc` summary when a doc comment is attached — #512),
|
|
170
174
|
exported vs internal split (with class/interface members nested under their
|
|
@@ -178,13 +182,16 @@ path since they point at a different file. Pass `blastRadius: true` to also get
|
|
|
178
182
|
the cross-file **blast radius** — transitive dependents aggregated to ranked
|
|
179
183
|
file `read` args ("if you change this, verify these files"); read-only over
|
|
180
184
|
the cached graph, omitted when cold (this replaced the standalone
|
|
181
|
-
`pilens_impact` tool). `view
|
|
182
|
-
|
|
183
|
-
|
|
185
|
+
`pilens_impact` tool). `view` selects an output preset, projection × format
|
|
186
|
+
(`"summary-text"` default = metrics off, text; `"summary-json"`; `"full-text"`;
|
|
187
|
+
`"full-json"` = every field, JSON) — the text cell is lossless against the
|
|
188
|
+
JSON payload; the default leaves out `usedBy`, `fanout` and `complexity`, at
|
|
189
|
+
roughly half the byte
|
|
190
|
+
size. Tree-sitter extract + cached review-graph
|
|
184
191
|
lookup; never builds the graph, never calls LSP on this path.
|
|
185
192
|
`semantic.source` reports what backed the data (`review-graph` | `none`).
|
|
186
193
|
|
|
187
|
-
**`read_symbol(
|
|
194
|
+
**`read_symbol(path, symbol)`** — returns the verbatim body of one
|
|
188
195
|
named symbol plus a one-line header (`<kind> <name> <basename>:<startLine>-<endLine>`).
|
|
189
196
|
Records the read against the read-guard so a follow-up edit anywhere in
|
|
190
197
|
that symbol's range passes the read-before-edit check (an outline from
|
package/docs/globalconfig.md
CHANGED
|
@@ -144,7 +144,9 @@ Hide the diagnostics widget by default, run formatting immediately after write/e
|
|
|
144
144
|
|
|
145
145
|
`contextInjection.enabled` (default `true`) controls whether pi-lens prepends automatic findings — session-start guidance, turn-end findings, and test findings — into the next model turn. Set it to `false` (or use `--no-lens-context` / `PI_LENS_NO_CONTEXT_INJECTION=1` / `/lens-context-toggle`) to keep tools, LSP, read-guard, and formatting running while avoiding the prompt-cache invalidation that injected messages cause in long, cache-sensitive sessions. Findings are still cached, so `lens_diagnostics` and `/lens-health` keep working.
|
|
146
146
|
|
|
147
|
-
|
|
147
|
+
While a 🔴 blocker the model was told about stays unresolved, the first request of each later prompt repeats it once, headed "Still unresolved (already reported on an earlier turn, not new)" and ending with a `lens_diagnostics` call that lists every blocker, because pi rebuilds that request from its transcript and a blocker from a nested write (a codemode script that drops the STOP note) is not in it. Requests inside one prompt, blockers the session has fixed or marked (whatever another session still holds), and the MCP host repeat nothing; `contextInjection.enabled: false` repeats nothing either.
|
|
148
|
+
|
|
149
|
+
`contextInjection.retain` (default `false`, or `--lens-retain-injections`) keeps injection on and makes it cache-stable instead. An injection normally rides one provider request: pi rebuilds the next request from its own transcript, so that request no longer carries it, and an engine that caches by exact prefix (a local llama.cpp or Qwen server) re-processes everything after the point where it sat. With `retain` on, pi-lens re-sends each injection's bytes unchanged, at the same place, in every later request of the session, so each request is the previous one plus new content. Findings are still delivered once, and a repeat of a blocker a retained block already carries is skipped, so it spends none of the cap; each retained block ends with a snapshot label naming `lens_diagnostics` for the current state. A compaction, a `/tree` move, or a new, resumed, forked or reloaded session drops what was retained. A session holds at most 64 retained injections and 256 KiB; past either, a new injection reaches its one request only and one `context-injection-retain-declined` degradation row is recorded.
|
|
148
150
|
|
|
149
151
|
`contextInjection.requirePreExistingFixes` (default `true`) controls whether the session-start orientation tells the agent to fix pre-existing blocking errors; set `false` to scope that demand to errors its own edits introduce.
|
|
150
152
|
|
|
@@ -265,10 +267,16 @@ Per-rule threshold overrides and policy filters. Currently honored:
|
|
|
265
267
|
`no-eval` once and the filter covers `no-eval`, `ast-grep:no-eval`, and
|
|
266
268
|
`no-eval-js`. Side effect: a rule whose real name genuinely ends in `-js`
|
|
267
269
|
(e.g. `prefer-js`) is conflated with its stem (`prefer`) — disabling or
|
|
268
|
-
selecting one also disables or selects the other.
|
|
270
|
+
selecting one also disables or selects the other. The list is a denial: the
|
|
271
|
+
union of the global, project and nested files' lists, so a nearer file adds
|
|
272
|
+
rules and never re-enables one.
|
|
269
273
|
- `<id>.select` — allowlist of rule ids; only the listed rule ids survive
|
|
270
274
|
filtering. Disable wins over select project-wide, even when the two lists
|
|
271
|
-
are configured under different keys.
|
|
275
|
+
are configured under different keys. Unlike `disable`, the nearest file that
|
|
276
|
+
sets `select` supplies the whole list per grouping key; a global `select`
|
|
277
|
+
applies to a key no nearer file sets. Lists under different keys are unioned,
|
|
278
|
+
so a global `k.select: [x]` and a nearer `k2.select: [y]` keep both `x` and
|
|
279
|
+
`y`.
|
|
272
280
|
|
|
273
281
|
The `<id>` key is a grouping label only — it does not scope which rules the
|
|
274
282
|
`disable`/`select` list underneath it can match. Matching is **project-wide**:
|
|
@@ -44,9 +44,13 @@
|
|
|
44
44
|
The commit gate reads every record, whoever owns it, because the tree is
|
|
45
45
|
shared. A turn end reads only its own session's records: it delivers,
|
|
46
46
|
sweeps, re-judges and consumes those, and files its guard section under its
|
|
47
|
-
own id.
|
|
48
|
-
|
|
49
|
-
|
|
47
|
+
own id. The gate reads every record but retires only its own session's: its
|
|
48
|
+
missing-file sweep (#5020) persists into the cache of the acting session's
|
|
49
|
+
own records, whose cache is the coordinator root's cache or the session
|
|
50
|
+
cwd's, whichever wrote them, so another session's dead-cite row waits for
|
|
51
|
+
that session's own gate or turn end. Only a write by the coordinator's
|
|
52
|
+
session latches `session_mismatch`; a concurrent session's write leaves
|
|
53
|
+
another session's record and the latch alone.
|
|
50
54
|
- The commit gate is keyed by the repository being committed (#4941), not by
|
|
51
55
|
session. A commit/push is judged by the unresolved blockers whose files lie
|
|
52
56
|
in the git checkout it targets (`resolveGitCheckout`, the seam the review
|