pi-lens 4.4.4 → 4.4.6
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.md +477 -0
- package/README.md +45 -3
- package/config/biome/core.jsonc +3 -3
- package/config/dependency-cruiser-eager-allowlist.json +1 -0
- package/dist/{chunk-UBOQLVT2.js → chunk-2DDDCJDL.js} +4 -4
- package/dist/{chunk-RKKOYPRA.js → chunk-2DMLM3ZO.js} +13 -15
- package/dist/chunk-2F47TQOA.js +73 -0
- package/dist/{chunk-O4NWQT6I.js → chunk-2PHMIAKO.js} +4 -4
- package/dist/{chunk-DGUKIYSI.js → chunk-2RLWJO5K.js} +8 -10
- package/dist/{chunk-S67KYG37.js → chunk-2X4VLOCC.js} +2 -2
- package/dist/{chunk-TIQ2PKDW.js → chunk-3MYEA7QD.js} +4 -4
- package/dist/{chunk-3DA2JDOL.js → chunk-3WEPUD2V.js} +551 -203
- package/dist/{chunk-AMERCH6V.js → chunk-4AVZ3TG7.js} +15 -16
- package/dist/{chunk-IYNJ6YPZ.js → chunk-4PCQCU47.js} +4 -4
- package/dist/chunk-4WX4CTUE.js +57 -0
- package/dist/{chunk-P63GXC37.js → chunk-5APMQ2IJ.js} +31 -4
- package/dist/{chunk-ZIVJBOO3.js → chunk-5CV5ITZF.js} +2 -2
- package/dist/{chunk-6DLWKFEX.js → chunk-5ZR3APIM.js} +41 -42
- package/dist/{chunk-XTBDCR27.js → chunk-63RIVFQI.js} +4 -4
- package/dist/{chunk-GSLNCYGG.js → chunk-75SY4F24.js} +13 -14
- package/dist/{chunk-U44DJXQP.js → chunk-7RQXA5GG.js} +15 -18
- package/dist/chunk-A3YNG5KP.js +45 -0
- package/dist/{chunk-5OFV52AM.js → chunk-AE37FEGH.js} +1 -1
- package/dist/{chunk-BWD5EPKO.js → chunk-AMXIUN2R.js} +4 -6
- package/dist/{chunk-3KAZU3VR.js → chunk-ARD426WI.js} +2 -2
- package/dist/{chunk-BW5KFIQC.js → chunk-AWQWXSW4.js} +1 -0
- package/dist/{chunk-YH5MVY2U.js → chunk-BHUWL2Y3.js} +7 -7
- package/dist/{chunk-CT4MN5IU.js → chunk-BI5LAQ3Y.js} +353 -359
- package/dist/{chunk-KAPJINKN.js → chunk-BM5GS6ZH.js} +2 -2
- package/dist/{chunk-TLX72JTG.js → chunk-BWYQUPOS.js} +1 -1
- package/dist/chunk-CFRQMBGP.js +49 -0
- package/dist/{chunk-RMLC67LF.js → chunk-CJYKEW2L.js} +2 -30
- package/dist/chunk-CKEQFGLT.js +32 -0
- package/dist/{chunk-IWDLU6K3.js → chunk-DC4CFXM5.js} +4 -6
- package/dist/{chunk-ZVUL7QYY.js → chunk-DMSLNKF7.js} +29 -32
- package/dist/{chunk-KN35K52N.js → chunk-DQXSPYRI.js} +3 -3
- package/dist/{chunk-HYGZEMX6.js → chunk-EVDGNG4F.js} +11 -5
- package/dist/{chunk-SRYEJNES.js → chunk-F5Z6URKM.js} +2 -2
- package/dist/{chunk-UMS2MFPZ.js → chunk-F6X3YJWD.js} +2 -3
- package/dist/{chunk-XYURS6EN.js → chunk-FA5LDARD.js} +15 -17
- package/dist/{chunk-24AKHFGP.js → chunk-FFL3A2VP.js} +6 -6
- package/dist/chunk-FJIVKLPH.js +31 -0
- package/dist/chunk-G2B7F6ZU.js +88 -0
- package/dist/{chunk-US7ECLD7.js → chunk-GAACZY6R.js} +131 -41
- package/dist/{chunk-MZGQNL3Y.js → chunk-GMTFDAOK.js} +12 -13
- package/dist/{chunk-VOOAPROD.js → chunk-GNSIWBAT.js} +3 -3
- package/dist/chunk-GTAI2J6U.js +27 -0
- package/dist/{chunk-RVK72CZX.js → chunk-GZE7WOI4.js} +1362 -459
- package/dist/{chunk-IUE7SSKV.js → chunk-H7HTEQUZ.js} +13 -7
- package/dist/{chunk-EUXZEFTV.js → chunk-HK6JVFZC.js} +3 -3
- package/dist/chunk-IPDG45G5.js +26 -0
- package/dist/{chunk-5HSRT26B.js → chunk-J6JP25XU.js} +16 -15
- package/dist/{chunk-HWCCCQNX.js → chunk-JL6CXUMW.js} +13 -6
- package/dist/{chunk-EBC36LNN.js → chunk-K2YGBXOA.js} +17 -17
- package/dist/{chunk-WMYE35PX.js → chunk-KLQVC3XC.js} +7 -5
- package/dist/{chunk-ATKJFDQN.js → chunk-KSR7RGQY.js} +12 -14
- package/dist/{chunk-POMLXPMY.js → chunk-KXF5R4UN.js} +1 -1
- package/dist/{chunk-LLJNQKQW.js → chunk-LEJOJDXL.js} +20 -13
- package/dist/{chunk-JUKMK5Y4.js → chunk-MA77RSFN.js} +10 -11
- package/dist/{chunk-GAQ7OQG6.js → chunk-MKVZQUEG.js} +85 -96
- package/dist/{chunk-2EECBNC5.js → chunk-MN7MHUXQ.js} +75 -0
- package/dist/{chunk-DEL2U6CM.js → chunk-MT6BVNFW.js} +16 -14
- package/dist/chunk-NDMCVUYK.js +507 -0
- package/dist/{chunk-HRNHZA3N.js → chunk-NIU2IPC5.js} +12 -16
- package/dist/{chunk-AGSS7277.js → chunk-NNKXDXXS.js} +7 -24
- package/dist/{chunk-V35JG4JB.js → chunk-OJLTLYHB.js} +152 -334
- package/dist/{chunk-J6MPGQTS.js → chunk-OLAWH5UQ.js} +81 -15
- package/dist/{chunk-T57LYLZT.js → chunk-OOU2WZZE.js} +1 -1
- package/dist/{chunk-CYRKQRPM.js → chunk-OSTKYB55.js} +2 -4
- package/dist/chunk-P4QNXS6I.js +27 -0
- package/dist/chunk-PKES3ISE.js +297 -0
- package/dist/{chunk-ROYSX2S5.js → chunk-PO45POGF.js} +2 -2
- package/dist/{chunk-T7FEBKXN.js → chunk-PPIBVH4R.js} +7 -9
- package/dist/{chunk-3RKP3FMS.js → chunk-PQJFG24Z.js} +295 -23
- package/dist/{chunk-KUA4OJ5Y.js → chunk-Q3UZHW6N.js} +846 -350
- package/dist/{chunk-N5FLEO7W.js → chunk-Q4EMRFNA.js} +37 -37
- package/dist/{chunk-5IUSNGOC.js → chunk-Q4FCYCRE.js} +28 -21
- package/dist/chunk-Q6D6VMI4.js +22 -0
- package/dist/{chunk-UZ2XCLYS.js → chunk-QGSTQH4D.js} +8 -8
- package/dist/{chunk-DUO2TU77.js → chunk-RZOXUSPC.js} +10 -4
- package/dist/{chunk-JMYYOTQG.js → chunk-S26LC76R.js} +13 -1
- package/dist/{chunk-GMX5OS7B.js → chunk-S67UJDGQ.js} +11 -12
- package/dist/chunk-SCIUNBPF.js +44 -0
- package/dist/{chunk-RKBXZN3A.js → chunk-SJJYRZB4.js} +2 -2
- package/dist/chunk-SXGD4ANG.js +25 -0
- package/dist/{chunk-YCWYO6TQ.js → chunk-T7FTXGS3.js} +48 -45
- package/dist/{chunk-FM4RDMKT.js → chunk-TIQJPRDD.js} +115 -61
- package/dist/{chunk-XHJBS436.js → chunk-TIYGSODX.js} +25 -25
- package/dist/{chunk-S2HEXIWI.js → chunk-U2SDMG7C.js} +10 -6
- package/dist/{chunk-2KXTHF3M.js → chunk-U6OC3QEM.js} +253 -33
- package/dist/{chunk-AWSCPCN2.js → chunk-UCGQT677.js} +19 -19
- package/dist/chunk-UHGF5UT5.js +32 -0
- package/dist/{chunk-JW3YWBVB.js → chunk-UN4TEBWN.js} +17 -19
- package/dist/{chunk-ZHH37KZL.js → chunk-V3APN3DY.js} +17 -17
- package/dist/{chunk-ED36RF6Y.js → chunk-V63BC55Q.js} +1 -1
- package/dist/{chunk-XBJVAEEO.js → chunk-VG5JS5SW.js} +3 -2
- package/dist/{chunk-W66O5E25.js → chunk-VPBIMOAQ.js} +13 -15
- package/dist/chunk-VQH24FIP.js +37 -0
- package/dist/{chunk-YNE3RP52.js → chunk-VSFLRN5Y.js} +8 -1
- package/dist/{chunk-7D6L4MTX.js → chunk-W2V54OCL.js} +3 -3
- package/dist/{chunk-2FN63LPV.js → chunk-W5LGKNET.js} +13 -14
- package/dist/{chunk-IQWN5JCP.js → chunk-W5R5SABV.js} +13 -14
- package/dist/{chunk-R3T7CLQ2.js → chunk-WIZWZR4C.js} +41 -41
- package/dist/{chunk-TOY6QKOH.js → chunk-WQOIR3QY.js} +17 -17
- package/dist/{chunk-Y6GZHWSJ.js → chunk-XAIT2YGS.js} +6 -6
- package/dist/chunk-XCUHKYCQ.js +23 -0
- package/dist/{chunk-GSM5UU7A.js → chunk-XQCSWV2G.js} +44 -35
- package/dist/{chunk-OHKJ7PQF.js → chunk-YBSONGSZ.js} +43 -39
- package/dist/{chunk-GXFV6MYU.js → chunk-YISME6ON.js} +72 -39
- package/dist/chunk-YRD4ISED.js +30 -0
- package/dist/{chunk-SD4I7ZO4.js → chunk-YSBHPOY6.js} +43 -53
- package/dist/{chunk-QBFBRV2B.js → chunk-Z2XAOKHK.js} +4 -2
- package/dist/{chunk-5VSF4UUQ.js → chunk-Z7IGUAXL.js} +34 -39
- package/dist/{chunk-MPNJLASA.js → chunk-ZKXQKGWZ.js} +10 -13
- package/dist/{chunk-J64T55EI.js → chunk-ZQ6NZZTB.js} +75 -9
- package/dist/chunk-ZUUI3ZSA.js +38 -0
- package/dist/{chunk-7HXE67BN.js → chunk-ZYNI26MI.js} +2 -2
- package/dist/index.js +32674 -27567
- package/dist/mcp/analyze-cli.js +11 -12
- package/dist/mcp/cli.js +46 -45
- package/dist/mcp/server.js +1210 -574
- package/dist/mcp/worker.js +65 -65
- package/dist/probes/installer.js +21 -23
- package/docs/adr/0010-trace-validation-session-lifecycle.md +390 -0
- package/docs/adr/README.md +1 -0
- package/docs/agent-tools.md +28 -7
- package/docs/ast-grep_rules_catalog.md +5 -3
- package/docs/configuration.md +12 -1
- package/docs/defect-shapes.md +738 -0
- package/docs/engineering-principles.md +12 -0
- package/docs/environment-variables.md +20 -0
- package/docs/features.md +16 -1
- package/docs/globalconfig.md +37 -8
- package/docs/invariants/caches-stores.md +30 -0
- package/docs/invariants/dispatch-runners.md +164 -0
- package/docs/invariants/git-guard-host.md +53 -0
- package/docs/invariants/language-config.md +31 -0
- package/docs/invariants/lsp-trust-exec.md +286 -0
- package/docs/invariants/paths-os.md +59 -0
- package/docs/invariants/session-telemetry.md +74 -0
- package/docs/lsp-capability-matrix.md +105 -12
- package/docs/lsp-idle-eviction.md +37 -18
- package/docs/pi-lens-fixer.md +24 -2
- package/docs/pi-lens-investigator.md +14 -0
- package/docs/pi-lens-merge-policy.md +32 -17
- package/docs/pi-lens-monitor.md +66 -10
- package/docs/pi-lens-orchestration.md +41 -0
- package/docs/pi-lens-release.md +20 -0
- package/docs/pi-lens-retro.md +5 -4
- package/docs/pi-lens-reviewer.md +54 -7
- package/docs/pi-lens-subagent.md +10 -3
- package/docs/release-qa-baseline.md +19 -7
- package/docs/servercapabilities.md +47 -47
- package/docs/settings.md +9 -5
- package/docs/subagent-compat.md +1 -1
- package/docs/usage.md +1 -0
- package/package.json +8 -5
- package/rules/ast-grep-rules/rule-tests/no-return-value-in-generator-test.yml +17 -0
- package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-js-test.yml +86 -0
- package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-test.yml +86 -0
- package/rules/ast-grep-rules/rule-tests/unchecked-numeric-parse-python-test.yml +15 -0
- package/rules/ast-grep-rules/rules/no-return-value-in-generator.yml +9 -4
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +119 -0
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +119 -0
- package/rules/ast-grep-rules/rules/unchecked-numeric-parse-python.yml +13 -2
- package/rules/rule-catalog.json +25 -1
- package/scripts/analyze-pi-lens-logs.mjs +15 -5
- package/scripts/lib/is-main-module.mjs +27 -0
- package/scripts/lib/scratch-home-env.mjs +21 -0
- package/scripts/rpc-load-check.mjs +4 -6
- package/scripts/warm-loader-cache.mjs +2 -5
- package/dist/chunk-3PTHXJXR.js +0 -28
- package/dist/chunk-3QED2P4V.js +0 -31
- package/dist/chunk-5WRPDP2A.js +0 -47
- package/dist/chunk-ABBOA7UD.js +0 -157
- package/dist/chunk-CUHSHSB6.js +0 -273
- package/dist/chunk-GL5LUMZE.js +0 -51
- package/dist/chunk-HAD7QRQI.js +0 -30
- package/dist/chunk-JORED7EX.js +0 -44
- package/dist/chunk-KYUB6QDC.js +0 -72
- package/dist/chunk-LZSEQW6A.js +0 -57
- package/dist/chunk-M2IFVFWU.js +0 -79
- package/dist/chunk-M2UD3LPU.js +0 -88
- package/dist/chunk-MBKQHGA7.js +0 -39
- package/dist/chunk-R7YOCSNV.js +0 -23
- package/dist/chunk-SKAMFC7A.js +0 -28
- package/dist/chunk-SYE6T2EB.js +0 -28
- package/dist/chunk-TRETHTQO.js +0 -26
- package/dist/chunk-UA7ZXYDR.js +0 -184
- package/dist/chunk-XTFDJI3T.js +0 -24
- package/dist/chunk-Z3CCVDUB.js +0 -76
|
@@ -20,6 +20,18 @@ the deliverable is the recorded refutation (which invariant covers it, with the
|
|
|
20
20
|
probe) and, where cheap, an assertion that pins it, not machinery for a
|
|
21
21
|
collision that cannot occur.
|
|
22
22
|
|
|
23
|
+
**Speculative robustness needs buy-in.** Before adding mechanism for a race,
|
|
24
|
+
security edge case or failure nobody has reproduced, state the trigger path
|
|
25
|
+
(which inputs, in what order, through which production caller), the evidence
|
|
26
|
+
that it can happen, and the cost (new state, seams, tests to maintain). Without
|
|
27
|
+
a reproduction the default is no new mechanism: record the case as a hypothesis
|
|
28
|
+
or an accepted residual for the maintainer to decide. Workers flag it in the
|
|
29
|
+
hand-back and do not build it; reviewers file an unproven race as a hypothesis,
|
|
30
|
+
not a high-severity finding. This never waives validation, error handling or
|
|
31
|
+
security at a real trust boundary; it bounds new mechanism, not hygiene.
|
|
32
|
+
Screen: can the author name the production sequence that triggers it, with
|
|
33
|
+
evidence?
|
|
34
|
+
|
|
23
35
|
**Climb the minimalism ladder before writing code.** Be lazy about the
|
|
24
36
|
solution, never about reading. Trace the real flow, then ask in order: does this
|
|
25
37
|
need to exist at all; does the codebase already do it (reuse the seam); does the
|
|
@@ -210,6 +210,26 @@ back to a local LSP fleet for that session.
|
|
|
210
210
|
|
|
211
211
|
## Language-specific
|
|
212
212
|
|
|
213
|
+
### Ambient Python environments (`VIRTUAL_ENV`, `CONDA_PREFIX`, `UV_PROJECT_ENVIRONMENT`)
|
|
214
|
+
|
|
215
|
+
pi-lens reads three ambient channels when it resolves the interpreter that runs
|
|
216
|
+
pyright and jedi. `UV_PROJECT_ENVIRONMENT` names a uv project environment path
|
|
217
|
+
(relative paths resolve against the uv project root) and is consulted only when
|
|
218
|
+
the directory is a uv project root. The full chain, in the order the code walks
|
|
219
|
+
it, is: `UV_PROJECT_ENVIRONMENT`, a uv workspace's `.venv` for a declared
|
|
220
|
+
member, `VIRTUAL_ENV`, `CONDA_PREFIX`, the project's `.venv`, then its `venv`
|
|
221
|
+
(relative to the root being resolved). The first that holds
|
|
222
|
+
`bin/python` (`Scripts/python.exe` on Windows) wins, and the three variables are
|
|
223
|
+
read in that position, not ahead of the workspace environment. An ambient
|
|
224
|
+
environment is already active in the calling shell, so it needs no project
|
|
225
|
+
trust; a `.venv` or `venv` found inside the project does, because its binary is
|
|
226
|
+
project-sourced. Untrusted or absent, resolution falls through to the managed
|
|
227
|
+
install and then `PATH`.
|
|
228
|
+
|
|
229
|
+
These channels select an interpreter only. They never declare a syntax level;
|
|
230
|
+
that comes from `target-version`, `pythonVersion`, `requires-python`, or
|
|
231
|
+
`.python-version` (see [Features](features.md)).
|
|
232
|
+
|
|
213
233
|
### `PI_LENS_VULTURE_MIN_CONFIDENCE`
|
|
214
234
|
|
|
215
235
|
Minimum confidence for the Python dead-code (Vulture) scanner. **Default:** `60`.
|
package/docs/features.md
CHANGED
|
@@ -21,6 +21,21 @@ pi-lens includes **49 language server definitions** (including four cross-cuttin
|
|
|
21
21
|
|
|
22
22
|
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, 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
23
|
|
|
24
|
+
|
|
25
|
+
### Python: interpreter and syntax level
|
|
26
|
+
|
|
27
|
+
Python carries two separate declarations, and pi-lens reads both from the project rather than from whichever interpreter happens to run a checker.
|
|
28
|
+
|
|
29
|
+
**Interpreter** — `detectPythonEnvironment` takes the first directory that holds a Python binary, in this order: `UV_PROJECT_ENVIRONMENT` (only at a uv project root), a uv workspace's `.venv` for a declared member, `VIRTUAL_ENV`, `CONDA_PREFIX`, the project's `.venv`, then its `venv`. pyright and jedi both launch from it. A binary that comes from a project's own environment needs project trust; without it pi-lens falls back to the managed install and then `PATH`, and records the refusal once per session. A project launch that fails for any other reason also falls through to that fallback.
|
|
30
|
+
|
|
31
|
+
**Syntax level** — `detectPythonTargetVersion` walks up from the file and, in each directory, takes the first readable declaration of ruff `target-version` (`.ruff.toml`, then `ruff.toml`, then `pyproject.toml` `[tool.ruff]`, the order ruff itself measures), pyright `pythonVersion` (`pyrightconfig.json`, which may use comments and trailing commas, then `pyproject.toml` `[tool.pyright]`), `requires-python` from `pyproject.toml` `[project]` reduced to its strongest lower bound (`>=3.12,>=3.14` is 3.14 in either order), then the first line of `.python-version`. The nearest directory holding a declaration wins. Each source ends its own walk where its tool stops: ruff at a ruff config (`.ruff.toml`, `ruff.toml`, or a `pyproject.toml` with `[tool.ruff]`, even one that sets no `target-version`), pyright at `pyrightconfig.json` or `[tool.pyright]`, `requires-python` at a `pyproject.toml` that carries the key, and `.python-version` at itself. A `pyproject.toml` that holds none of these is walked past, as ruff and pyright walk past it, so a nested config that owns a source blocks an ancestor's level for that source and nothing else does. Text that names no CPython major/minor — a `pypy-3.10` or branch name in `.python-version`, an empty file, a specifier with no lower bound — is no declaration at all; pi-lens never invents a default.
|
|
32
|
+
|
|
33
|
+
When the declared level is 3.14 or newer, jedi's `compile` findings are dropped. jedi compiles with the interpreter it launched, so a 3.14-only construct reports a spurious `SyntaxError` (PEP 758's unparenthesized `except` is the common case). The drop is recorded once per session and file, naming the declared level and the file that declared it, and it applies to the fresh probe, its cached replay, `lsp_navigation`, `mode=full`, and the post-write runner that delivers the same server's answer. Every one of those surfaces names the rows it withheld on the text the agent reads (the count and the declaring file), including when the file would otherwise read as clean. A call that spans projects with different declarations cites each declaration with its own count. The structured result carries the same `details.withheldCompile` object (`count`, `declared`, and `declarations` when there is more than one) on `lsp_diagnostics`, `lens_diagnostics` and `lsp_navigation`. Pyright is unaffected: it parses at the level it resolves and stays the authority on type errors.
|
|
34
|
+
|
|
35
|
+
ruff needs no override. Its pre-check, `--fix` pass, and lint run all read `target-version` from the project config, so pi-lens passes no level to any of them, and pre-check and fix cannot disagree about which syntax parses.
|
|
36
|
+
|
|
37
|
+
Non-goal: pi-lens never installs, selects, or pins a Python interpreter, and never rewrites a project's declaration.
|
|
38
|
+
|
|
24
39
|
### Formatters
|
|
25
40
|
|
|
26
41
|
pi-lens auto-detects and runs **35 formatters** based on project config:
|
|
@@ -373,7 +388,7 @@ Pattern-based structural rules in `rules/ast-grep-rules/` across JS, TS, and Pyt
|
|
|
373
388
|
[Opengrep](https://github.com/opengrep/opengrep) (an open, login-free fork of Semgrep) runs as a pi-lens **auxiliary diagnostic LSP** — a cross-cutting, diagnostic-only language server that attaches *alongside* the file's normal language server (TypeScript, Python, …) and contributes findings on the same on-write diagnostics path. Running it as a warm LSP server compiles its ruleset **once per session** rather than on every file, so per-file scans cost ~1–2s (vs ~8s for a cold CLI invocation per file). High-signal security findings become blocking; the rest are advisory.
|
|
374
389
|
|
|
375
390
|
- **On by default** (it's a registered LSP server) when the `opengrep` binary is available; pi-lens **auto-installs it on demand** — a single GitHub-release binary, **no login, token, or telemetry**. Disable with `--no-opengrep`.
|
|
376
|
-
- **Rules:** a repo `.opengrep.yml`/`.opengrep.yaml` (or a legacy `.semgrep.yml`/`.semgrep.yaml`, whose format Opengrep consumes natively) is used if present; otherwise it
|
|
391
|
+
- **Rules:** a repo `.opengrep.yml`/`.opengrep.yaml` (or a legacy `.semgrep.yml`/`.semgrep.yaml`, whose format Opengrep consumes natively) is used if present; otherwise it uses the registry rule pack pi-lens refreshed into its own cache (a bounded weekly background download, validated by `opengrep --validate` before it replaces the previous file; pi-lens ships no rules), and only while no pack has been fetched yet does it fall back to Opengrep's login-free `auto` Community ruleset. Offline with no pack, that fallback is reported as an unconfirmed scan, never a clean one (#4764).
|
|
377
392
|
|
|
378
393
|
This is the first adopter of pi-lens's **auxiliary-LSP capability** (`role:"auxiliary"` servers + `clients/dispatch/auxiliary-lsp.ts`) — the same path future cross-cutting scanners (spelling, secrets, …) plug into by registration.
|
|
379
394
|
|
package/docs/globalconfig.md
CHANGED
|
@@ -25,6 +25,7 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
|
|
|
25
25
|
| `--lens-guard` | `guard.enabled` | `false` |
|
|
26
26
|
| `--lens-checkout-guard` | `guard.sharedCheckout` | `false` |
|
|
27
27
|
| `--immediate-format` | `format.mode` (`"immediate"`) | `"deferred"` |
|
|
28
|
+
| `--lens-retain-injections` | `contextInjection.retain` | `false` |
|
|
28
29
|
| `--lens-turn-summary` | `turnSummary.enabled` | `false` |
|
|
29
30
|
| `--lens-actionable-warnings` | `actionableWarnings.enabled` | `false` |
|
|
30
31
|
| `--lens-actionable-warning-actions` | `actionableWarnings.includeLspCodeActions` | `false` |
|
|
@@ -51,15 +52,41 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
|
|
|
51
52
|
| `startup.mode` | `full` | `quick`, `full`, or `minimal`; `PI_LENS_STARTUP_MODE` wins |
|
|
52
53
|
| `startup.scans.enabled` | `true` | `true` or `false` |
|
|
53
54
|
|
|
54
|
-
|
|
55
|
-
`lsp_navigation`, `lens_diagnostic_mark`)
|
|
55
|
+
pi-lens registers five situational tools (the `ast_grep_*` family,
|
|
56
|
+
`lsp_navigation`, `lens_diagnostic_mark`) and a small loader,
|
|
56
57
|
`pi_lens_activate_tools`, that the model calls to activate the ones it needs.
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
does
|
|
58
|
+
`tools.lazy` decides whether the situational tools start inactive:
|
|
59
|
+
|
|
60
|
+
| `tools.lazy` | Situational tools |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| `true` (default) | Start inactive on every model. |
|
|
63
|
+
| `"auto"` | Start inactive only when the session's model keeps mid-conversation system messages (`compat.supportsMidConvoSystemMessages` is `true`). On any other model, including one that does not state the fact, every tool is active from the first turn. Before a model is known, the tools start inactive. |
|
|
64
|
+
| `false`, or `--no-lazy-tools` | Every tool is active for the whole session and pi-lens never changes the tool list. |
|
|
65
|
+
|
|
66
|
+
Why `true` is the default: a model without that fact gets every system message
|
|
67
|
+
folded into one prompt head, so each tool-list change rewrites the whole cached
|
|
68
|
+
prompt. Activations are rare, though. Over the window measured for #4687 the
|
|
69
|
+
loader ran about once per 3,329 requests, while carrying every situational
|
|
70
|
+
schema on every request costs more than the rewrites once activations are
|
|
71
|
+
rarer than about one per 1,000 requests. `"auto"` is there for a workload that
|
|
72
|
+
activates often on a folding model.
|
|
73
|
+
|
|
74
|
+
Under `"auto"`, pi-lens decides at session start and again only when you
|
|
75
|
+
switch models, never between turns of one model. A switch to a folding model
|
|
76
|
+
activates every enabled situational tool. A switch back deactivates only the
|
|
77
|
+
ones the conversation never activated or called. Any other value is reported
|
|
78
|
+
once as an ignored setting, and the default applies.
|
|
79
|
+
|
|
80
|
+
Precedence: `tools.<name>.enabled` (in either config file, or `--no-tool`)
|
|
81
|
+
filters first. A disabled tool is never registered, so it is absent under every
|
|
82
|
+
`tools.lazy` value and the loader refuses to activate it. `tools.lazy` then
|
|
83
|
+
applies only to the enabled situational tools. It is user-level only: a project
|
|
84
|
+
`.pi-lens.json` that sets it, `"auto"` included, is reported and ignored. The
|
|
85
|
+
CLI flag outranks the key.
|
|
86
|
+
|
|
87
|
+
The loader tool stays registered under every value and keeps describing itself
|
|
88
|
+
as activating inactive tools; when the tools it names are already active,
|
|
89
|
+
calling it does nothing.
|
|
63
90
|
|
|
64
91
|
Keys are positive (`"enabled": true` means the feature runs), so a `--no-*` flag corresponds to setting its key `false`. A `no-*` flag on the command line is a one-way switch: it can disable, never re-enable, so `--no-lsp` wins over `lsp.enabled: true` but nothing on the CLI overrides `lsp.enabled: false`. Set the key back to `true` to re-enable.
|
|
65
92
|
|
|
@@ -112,6 +139,8 @@ Hide the diagnostics widget by default, run formatting immediately after write/e
|
|
|
112
139
|
|
|
113
140
|
`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.
|
|
114
141
|
|
|
142
|
+
`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; 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.
|
|
143
|
+
|
|
115
144
|
`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.
|
|
116
145
|
|
|
117
146
|
`actionableWarnings.enabled` gates the turn_end report. `includeLspCodeActions` fetches LSP code actions for each warning (requires an active language server). `deltaOnly` (default `true`) limits the report to lines touched in the current turn. `autoFix.enabled` applies conservative LSP quickfixes at `agent_end`; `autoFix.maxFixes` caps the number applied per turn (default `5`, must be a non-negative whole number). `maxFixes: 0` keeps the report and applies nothing, which is a useful halfway step before enabling `autoFix` for real. Unlike the toggles in the table above there is no CLI counterpart, since it takes a number rather than being on or off.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
<important if="touching caches, stores, and project intelligence rules">
|
|
2
|
+
|
|
3
|
+
### Caches, stores, and project intelligence
|
|
4
|
+
|
|
5
|
+
- Behavior-gating durable stores use `clients/durable-store.ts`: lock, re-read,
|
|
6
|
+
merge the caller delta, atomically publish, refresh coupled mirrors before
|
|
7
|
+
releasing the lock. Best-effort derived caches declare their loss policy.
|
|
8
|
+
- Every cache states its freshness axes, bound, eviction axis, and invalidation
|
|
9
|
+
source. A bounded entry count does not excuse unbounded bytes, timers, WASM
|
|
10
|
+
objects, or persisted evidence.
|
|
11
|
+
- Workspace diagnostics cache mtime-drift hashing is limited by
|
|
12
|
+
`CONTENT_HASH_MAX_BYTES` in `clients/content-stamp.ts`; larger entries retain
|
|
13
|
+
strict mtime invalidation. Persistent reverify keeps zero mtime tolerance;
|
|
14
|
+
session-state restore keeps its 1 ms tolerance.
|
|
15
|
+
- Tree-sitter's `queryBatchCache` is invalidated by `clearWasmInput` when a
|
|
16
|
+
trapped query heals, because an in-flight batch may have cached a result that
|
|
17
|
+
omitted the healed rule (#3834).
|
|
18
|
+
- Async publication carries a generation or epoch and checks it before and
|
|
19
|
+
after awaited work. Graph snapshots are immutable by replacement.
|
|
20
|
+
- Review-graph, snapshot, reverse-dependency, word-index, and call-graph data
|
|
21
|
+
use path identities and explicit partial-coverage markers. A capped walk is
|
|
22
|
+
lower-bound evidence, never a clean zero.
|
|
23
|
+
- Tree-sitter uses the shared client and file-major project passes. Grammar
|
|
24
|
+
crashes are blocked before load; source overrides record package/version
|
|
25
|
+
provenance. Real grammar and rule tests use the warmed shared client.
|
|
26
|
+
- `module_report` and `symbol_search` are read-only orientation surfaces.
|
|
27
|
+
`read_symbol` and `read_enclosing` return bodies and record pi read coverage;
|
|
28
|
+
outlines do not claim body coverage. MCP adapters call `lens-engine.ts` only.
|
|
29
|
+
|
|
30
|
+
</important>
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
<important if="touching dispatch, runners, formatters, and installers rules">
|
|
2
|
+
|
|
3
|
+
### Dispatch, runners, formatters, and installers
|
|
4
|
+
|
|
5
|
+
- The analysed-state latch records a pipeline-owned target hash captured after
|
|
6
|
+
pi-lens writes and before LSP or dispatch awaits. `fileModified` also covers
|
|
7
|
+
side-effect files, so `postWriteStateHash` is the ownership discriminator;
|
|
8
|
+
an absent hash must not stamp the target with later disk bytes (#2499).
|
|
9
|
+
- The opaque prescan resolves its root once, through `opaquePrescanRoot`
|
|
10
|
+
(`clients/opaque-mutation-scan.ts`), and every consumer of that session root
|
|
11
|
+
asks the same owner: the baseline record and take, the head-move record and
|
|
12
|
+
take, and the root each held-primary send is scoped by. A
|
|
13
|
+
session whose cwd is not the coordinator's `projectRoot` — a concurrent
|
|
14
|
+
secondary session, which the host's session-start guard declines before any
|
|
15
|
+
`session_start` body runs — otherwise records its baseline and its HEAD under
|
|
16
|
+
one root and takes them under another, reporting `no-pending-snapshot` for a
|
|
17
|
+
command that did write. Scan evidence is scoped to the checkout it ran in: a
|
|
18
|
+
recognized write outside that root is kept (never cleared by a scan that
|
|
19
|
+
could not see it) and earns no authorship the scan cannot confirm.
|
|
20
|
+
- A bash command's writes are recovered from that session root AND from every
|
|
21
|
+
checkout the command ITSELF names — its `cd`/`pushd` target or a recognised
|
|
22
|
+
write operand — when that checkout is a linked worktree of the session's own
|
|
23
|
+
repository (`resolveOpaqueRecoveryRoots`, `sameCheckoutOtherRoot`). Both hooks
|
|
24
|
+
derive bounded root lists (`OPAQUE_RECOVERY_ROOT_CAP`) from the command text,
|
|
25
|
+
the session root, and the checkout each hook sees at its own instant, so a
|
|
26
|
+
worktree the command itself creates is admitted only at `tool_result` and its
|
|
27
|
+
missing baseline is reported as `partial-recognition-no-baseline`, while a
|
|
28
|
+
root both hooks admit still names one key for its record and its take; a
|
|
29
|
+
checkout of another repository, a checkout named past the cap, and a
|
|
30
|
+
git target under a non-checkout session root each leave one bounded
|
|
31
|
+
`opaque-recovery-root-refused` record per session. This is why a `cd` into a
|
|
32
|
+
sibling worktree no longer reads a clean `git status` in the wrong checkout as
|
|
33
|
+
"nothing changed". Relative operands resolve against the directory in effect
|
|
34
|
+
for their own segment (`scanShellWriteScopes`). That directory moves only for
|
|
35
|
+
an admitted form: `cd DIR` or `pushd DIR` whose one operand is a plain
|
|
36
|
+
path: bash's own word after quote removal, made only of admitted characters
|
|
37
|
+
(any quoted one, an escape bash also removes, an unquoted letter, digit or
|
|
38
|
+
`_./@%:,=+-`, and a leading `~` only as `~` or `~/`), starting with a
|
|
39
|
+
letter, digit, `_`, `.`, `/` or `~`; or a bare `popd` of a push the scan
|
|
40
|
+
admitted, entered at list start or after `&&`, `;`, a newline
|
|
41
|
+
or a backgrounded list, ended by `&&`, `;`, a newline or the end, and in no
|
|
42
|
+
pipeline or backgrounded list. A move entered after `&&` holds only to the end
|
|
43
|
+
of that `&&` chain, because it happened only if the left side succeeded. A
|
|
44
|
+
directory builtin in a pipeline or a backgrounded list leaves the directory
|
|
45
|
+
unchanged. Any other directory change, construct or shell-text builtin
|
|
46
|
+
returns the scan to the session root for the rest of the command.
|
|
47
|
+
- A recovered write is judged by the checkout that OWNS it, in both directions:
|
|
48
|
+
the ignore gate a synthetic bash-write dispatch passes asks the `.gitignore`
|
|
49
|
+
of the root that admitted the write (`_ownerRoot`), not the session root's, so
|
|
50
|
+
a linked worktree nested under a directory the session checkout ignores is
|
|
51
|
+
analysed instead of dropped silently (`.claude/worktrees/` in this
|
|
52
|
+
repository); and admission asks `analysis-root.ts`
|
|
53
|
+
(`canWriteAnalysisRoot(resolveAnalysisRoot(...))`) rather than re-deriving the
|
|
54
|
+
rule. Ownership is compared by REAL path, so a `cd` into a symlinked spelling
|
|
55
|
+
of a worktree keeps its authorship and its observed identity.
|
|
56
|
+
- `RUNNERS` declarations include file kinds. Runner selection is gated by file
|
|
57
|
+
kind and anchored at the file's language root, not by dispatch-root config or
|
|
58
|
+
declaration order. Runner children use `resolveToolCwd` with launcher markers.
|
|
59
|
+
- Automatic tests do not cross a Git checkout boundary, including through
|
|
60
|
+
filesystem aliases: `foreignGitRoot` (`clients/test-runner-client.ts`) gates
|
|
61
|
+
failed-first cache admission, retirement, every discovery path, and the
|
|
62
|
+
turn-end gate. Indeterminate ownership is not a foreign verdict, a deleted
|
|
63
|
+
target retires as `retired-missing`, and final rejections emit
|
|
64
|
+
`test-target-foreign-checkout`. Proven by
|
|
65
|
+
`tests/clients/test-runner-worktree-isolation.test.ts`.
|
|
66
|
+
- By design, a session whose cwd is a plain folder with no `.git` that holds several repositories, a submodule, or a nested linked worktree gets no automatic tests for the files inside them: any nested `.git` is a foreign checkout, and there is no per-project opt-in (maintainer decision, #3649/#3691). Run them explicitly.
|
|
67
|
+
- The one exception to that boundary is a linked worktree of the session's own repository (same git commondir, different top level, `resolveLinkedWorktreeOwner` in `clients/review-graph/git-identity.ts`, #3871): turn_end selects and runs its tests with that worktree's root as the project root (`clients/test-target-roots.ts`), so config, `node_modules` and the failed-first state are the worktree's own. A worktree root without its own runner install (no `node_modules/.bin`, venv or `vendor/bin`) is skipped with a counted `turn-end-test-root-skipped` row rather than run through `npx` or a bare interpreter; a reported location is rebased through `displayRoot` using the runner cwd first, then the dispatch root, only when that file exists, and otherwise remains as printed. A sibling worktree's file is still foreign to every other root. Python's ambient `VIRTUAL_ENV`, `CONDA_PREFIX`, or absolute `UV_PROJECT_ENVIRONMENT` is accepted for the session checkout, and for a linked worktree only when the environment root is inside that checkout; a skipped pytest row says that ambient environments were not borrowed when one is set. The edit worklist is the session's project worklist (#2504), so a session whose cwd is itself a linked worktree never sees an edit in the main checkout or a sibling and runs only its own tests. Each turn that edited files writes one `turn_end_test_selection` record to `latency.log` (candidates, selected, why not, and selected/candidates per owning root; first 8 roots, the rest in `rootsOmitted`; `selected` includes carried deferred targets, which no candidate bucket counts, so per-root `selected` can sum below it; one row of about 570 B per edit turn with candidates, bounded by log rotation only), so a turn with 0 tests is explained without the dbg lines the MCP route drops.
|
|
68
|
+
- Managed tools resolve through the registry and sanctioned availability seams.
|
|
69
|
+
Do not hand-roll install, PATH, or package-manager discovery. Use typed
|
|
70
|
+
`SpawnFailure.kind`; repair only `tool-not-found`.
|
|
71
|
+
- Windows LSP startup exit-code-1 failures are repairable only when the shared
|
|
72
|
+
command resolver finds no command or an npm shim target is absent; present
|
|
73
|
+
binaries that exit 1 remain runtime failures (#4263, #1199). The launch and
|
|
74
|
+
repair gate are pinned by `tests/clients/lsp/windows-startup-repair.test.ts`.
|
|
75
|
+
- Expected skips remain distinct from clean success and failure. Extend the
|
|
76
|
+
closed `RUNNER_SKIP_REASONS` taxonomy when policy intentionally defers work.
|
|
77
|
+
Preserve the skip reason through runner latency and model-facing delivery.
|
|
78
|
+
- `scripts/ci-verdict.mjs` ends every CLI path with `ci-verdict: exit <N> (<kind>)`;
|
|
79
|
+
read that final stdout line instead of `$?` after a pipe. `guard-bash` denies
|
|
80
|
+
the piped-status recurrence while allowing output-only pipes.
|
|
81
|
+
- A formatter is handed the file's identity, never the link that named it:
|
|
82
|
+
`realpathOrResolve` (`clients/path-utils.ts`) is the real path
|
|
83
|
+
of the nearest existing ancestor plus the missing tail, with no lexical `..`
|
|
84
|
+
collapse first. `formatFile` and `FormatService.formatFile` use it, so
|
|
85
|
+
`AGENTS.md -> CLAUDE.md` formats `CLAUDE.md` and Prettier's "is a symbolic
|
|
86
|
+
link" rejection never occurs. `FormatService.formatFile` also requires
|
|
87
|
+
`sessionRoot` and classifies the identity through `resolveAnalysisRoot`: an
|
|
88
|
+
`adopted` or `none` identity is refused, writes nothing, and records one
|
|
89
|
+
`adopted-root-writer-skipped` row (`writer: "format"`). The refusal is on
|
|
90
|
+
identity, not spelling, so a plain file outside every writable root (a
|
|
91
|
+
sibling package of a monorepo session cwd, say) is refused as well; a caller
|
|
92
|
+
that must format it passes that root as `sessionRoot`. Proven by
|
|
93
|
+
`tests/clients/format-service-symlink-identity.test.ts`.
|
|
94
|
+
- Formatter and autofix policy is config-first where the registry says so.
|
|
95
|
+
Formatting is strict by default. Autofix must carry per-diagnostic fixability
|
|
96
|
+
or a conservative capability allowlist.
|
|
97
|
+
- Analyzer and runner fallback filters must match the substituted surface's
|
|
98
|
+
contract. Empty output distinguishes clean, skipped, unavailable, errored,
|
|
99
|
+
inconclusive, and partial states.
|
|
100
|
+
- Every autonomous writer (pipeline autofix, immediate/deferred formatter, and
|
|
101
|
+
actionable-warning quickfix) resolves through `clients/tool-agreement.ts`.
|
|
102
|
+
Its declarative population assigns one evidence bucket and declines absent,
|
|
103
|
+
unreadable, unparseable, unsupported, or unregistered evidence; callers emit
|
|
104
|
+
bounded degradation records. Ktlint's standalone-CLI exception still
|
|
105
|
+
declines Gradle-owned projects without guessing a CLI version.
|
|
106
|
+
- Node tool agreement in `nodeAgreement` is established from the project's lockfile evidence in the deterministic order npm (`package-lock.json`) → pnpm (`pnpm-lock.yaml`, v9 `importers` and v6 top-level maps) → yarn (`yarn.lock`, v1 blocks and Berry `npm:` descriptors); the decision names the supplying lockfile, and missing, unreadable, unparseable, or shape-unsupported evidence declines.
|
|
107
|
+
- A whole-package fixer (`cargo clippy --fix`, `dart fix --apply`) rewrites
|
|
108
|
+
files pi's mutation queue does not hold, so it runs through
|
|
109
|
+
`runWithFixRestore` (`clients/fix-run-restore.ts`, #3598): hash the tool's
|
|
110
|
+
source files, capture agent mutations pi-lens observes during the run (the
|
|
111
|
+
tool_result seam and the mutation bridge), write them back after, one
|
|
112
|
+
degradation per run, and name any edit that cannot be restored. The restore
|
|
113
|
+
takes pi's queue entry for each sibling, one at a time (#3830). It starts
|
|
114
|
+
after the caller's scan of the tool's changes and is awaited only after the
|
|
115
|
+
target's hold is released, never inside it. The tool_result pipeline does not
|
|
116
|
+
await it (F's result must not wait on a sibling's holder; the loss notice is
|
|
117
|
+
queued as an advisory), the `agent_end` drain does, after the release: a queue entry is requested by something that holds no other
|
|
118
|
+
entry, except the multi-path LSP edit, which requests in ascending key order,
|
|
119
|
+
and nothing that holds an entry awaits the restore. Do not add a second
|
|
120
|
+
whole-package fixer without it, and do not await a queue entry while holding
|
|
121
|
+
another.
|
|
122
|
+
- A file's first write in a session blocks on the linter delta, not on every
|
|
123
|
+
linter error. The `tool_call` of the first classified write or edit
|
|
124
|
+
runs the file's inline linters (`PRE_EDIT_SEED_RUNNER_IDS`, tied to the
|
|
125
|
+
edit-scope census's LINTER lanes) over the bytes still on disk, under
|
|
126
|
+
`bounded()` with `PRE_EDIT_CAPTURE_BUDGET_MS` (500 ms), and installs their blocking
|
|
127
|
+
findings as `session.preEdit.<file>` beside the delta baseline. The capture
|
|
128
|
+
admits at most four active captures, aborts their process groups on abandonment
|
|
129
|
+
or session reset, and retains slots until teardown settles. It
|
|
130
|
+
only creates that record, and only while no baseline, tombstone or seed
|
|
131
|
+
exists, the bytes are the ones it read, and its session is current; each
|
|
132
|
+
dispatch only shrinks it (`classifyPreExisting`, identity plus line text,
|
|
133
|
+
one current finding per entry). A matched finding is reported as
|
|
134
|
+
pre-existing, never as a blocker, unless the inline record already holds
|
|
135
|
+
it. Language servers, type checkers, gated runners and scanners are never
|
|
136
|
+
seeded (maintainer scope, 2026-10-15). Collect-later linters and the MCP
|
|
137
|
+
route have no seed. Proven by
|
|
138
|
+
`tests/index-4483-first-write-seed-witness.test.ts`.
|
|
139
|
+
- `clients/dispatch/runners/runner-spawn-cwd-sweep.test.ts` is the population
|
|
140
|
+
guard for child cwd derivation. Add a reasoned migration row instead of a
|
|
141
|
+
pin-only update.
|
|
142
|
+
- Each real-bytes fixture under `tests/fixtures/runner-output/` records the
|
|
143
|
+
availability probe its runner sends (`availability`: the argv, the binary
|
|
144
|
+
that answered from its own banner, and the real exit status) and a real clean
|
|
145
|
+
run (`clean`; there is no prose alternative). The clean record is the
|
|
146
|
+
fixture's own invocation run in `tests/fixtures/runner-output-clean/<runner>`,
|
|
147
|
+
whose inputs are un-ignored by `.gitignore` on purpose. One gate,
|
|
148
|
+
`recordProblems` in `scripts/capture-runner-output.mjs`, refuses a record whose
|
|
149
|
+
version its own answer never printed, and a clean run whose argv is not this
|
|
150
|
+
fixture's; the capture and the census both call it.
|
|
151
|
+
`captured-real-output.test.ts` runs the REAL checker against that record
|
|
152
|
+
instead of mocking it, so a tool that rejects its own probe — helm 4 rejects
|
|
153
|
+
`--version` — reaches the replay; the clean bytes are what the matrix's clean
|
|
154
|
+
cell replays, in the clean workspace. `scripts/capture-runner-fixtures.mjs
|
|
155
|
+
--records-only` retrofits those records onto an existing fixture without
|
|
156
|
+
touching its work bytes, keyed on the fixture's own case.
|
|
157
|
+
Enforced by `tests/clients/dispatch/smoke-fixture-coverage.test.ts` and
|
|
158
|
+
`tests/clients/dispatch/tool-state-matrix.test.ts`.
|
|
159
|
+
- Every `parseToolRun` runner documents its nonzero-exit table; the documented
|
|
160
|
+
`ran` codes are pinned exactly so adding or removing one does not pass
|
|
161
|
+
silently, and each documented code needs an executable status fixture in the
|
|
162
|
+
runner's own test matrix (#3292).
|
|
163
|
+
|
|
164
|
+
</important>
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
<important if="touching git guard and host adapters rules">
|
|
2
|
+
|
|
3
|
+
### Git guard and host adapters
|
|
4
|
+
|
|
5
|
+
- Git command classification has one lexer and one guarded-verb matcher seam.
|
|
6
|
+
Unknown wrappers and indirect guarded verbs fail closed. Text-consumer
|
|
7
|
+
allowances recurse through command substitutions and execution contexts. A
|
|
8
|
+
substitution's output is read both empty and opaque (shape 61).
|
|
9
|
+
- The commit gate reads two states: the inline-blocker map's latch
|
|
10
|
+
(`RuntimeCoordinator`), then the persisted `turn-end-findings` record. A
|
|
11
|
+
collect-later runner's blocking findings join the map through
|
|
12
|
+
`clients/deferred-runner-blockers.ts`, never a second store: the turn-end
|
|
13
|
+
late-runner lane records them before the blocker replay (so the replay is
|
|
14
|
+
their one delivery and the composer persists them), and the gate judges
|
|
15
|
+
answers that settled but no turn end has drained, then refreshes the
|
|
16
|
+
persisted record (`syncGitGuardRecord`) as the inline path does at
|
|
17
|
+
`tool_result`. Both sites call one verdict, `judgeDeferredRunnerFindings`
|
|
18
|
+
(freshness, then policy), and the record's `sources` and `lines` come from
|
|
19
|
+
`clients/inline-blocker-fields.ts`, shared with the pipeline's writer. A run
|
|
20
|
+
still in flight does not gate, and an edit to the file while its re-check is in
|
|
21
|
+
flight clears the record until that answer settles (#3814). The gate and the
|
|
22
|
+
record's writers in `clients/git-guard.ts` and the turn-end composer read it
|
|
23
|
+
at any age. Each blocker section keeps the session that wrote it (top-level
|
|
24
|
+
`sessionId`, other owners in `carriedBlockers`; a record without that field
|
|
25
|
+
is one owner's), and a writer replaces only its own session's sections.
|
|
26
|
+
Another session's section leaves only for a file a dispatch checked
|
|
27
|
+
whole and found clean (`checkedWholeFile`), or whose file is gone. Its text
|
|
28
|
+
no file owns (a project lane's report: CVEs, secrets, cascade) leaves only
|
|
29
|
+
when its owner rewrites it, or at a turn end once `DEFAULT_MAX_AGE_MS` has
|
|
30
|
+
passed since its owner's own write (`blockerWrittenAt`, per partition; the
|
|
31
|
+
record's own timestamp moves with every writer). A record written before
|
|
32
|
+
this version has no stamp: the first turn end of another session that
|
|
33
|
+
carries it (a composer write or a settled turn end) writes one, and its
|
|
34
|
+
window starts there. Only a write logs what it drops. The gate judges a
|
|
35
|
+
record alone only when this session is its sole owner. A settled turn end
|
|
36
|
+
drops this session's sections and another session's expired text no file
|
|
37
|
+
owns, and retires a record that is this session's own, claims no blocker, or
|
|
38
|
+
holds no structured claim (the `--lens-guard`-off writer's), with one
|
|
39
|
+
`record_retired` row (#4725). A dispatch that never answered
|
|
40
|
+
(`pipeline_crash`, `pipeline_error`) is latched per file, apart from the
|
|
41
|
+
record's latch, and only that file's own returning dispatch clears it.
|
|
42
|
+
- The shared-checkout guard refuses unsafe worktree mutation when another live
|
|
43
|
+
session and uncommitted work are both proven. It never auto-stashes.
|
|
44
|
+
- `mcp/server.ts` talks to pi-lens through `clients/lens-engine.ts`. A mirrored
|
|
45
|
+
capability is one engine method plus one route. MCP transport remains
|
|
46
|
+
hand-rolled and dependency-free.
|
|
47
|
+
- Host SDK imports are type-only, except the one lazy, caught lookup of pi's
|
|
48
|
+
`withFileMutationQueue` in `index.ts` (#3506), admitted by count in
|
|
49
|
+
`tests/host-sdk-type-only.test.ts`; `clients/file-mutation-queue.ts` detects
|
|
50
|
+
and records a second SDK copy. Runtime dependencies belong in
|
|
51
|
+
`dependencies`.
|
|
52
|
+
|
|
53
|
+
</important>
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
<important if="touching language and configuration rules">
|
|
2
|
+
|
|
3
|
+
### Language and configuration
|
|
4
|
+
|
|
5
|
+
- `clients/language-registry.ts` is the identity source for language ids,
|
|
6
|
+
extensions, filenames, file kinds, LSP ids, and grammars. Consumers project
|
|
7
|
+
from it; they do not maintain parallel language tables.
|
|
8
|
+
- Agent-facing advisory text resolves names through `resolveLensToolName` with
|
|
9
|
+
the delivery host: pi uses `piName`, and MCP uses `mcpName` from
|
|
10
|
+
`TOOL_REGISTRY`. Known tools without a host mapping resolve to `undefined`,
|
|
11
|
+
so callers omit or rephrase them; pi-only rows require
|
|
12
|
+
`PI_ONLY_TOOL_REASONS`. Do not add a second name map or hard-code a pi tool
|
|
13
|
+
name in advisory output (#2535).
|
|
14
|
+
- `clients/config-core/` owns schema validation, normalization, merging,
|
|
15
|
+
provenance, deny precedence, merge strategies, trust-gated process specs,
|
|
16
|
+
and bounded migration records. Existing LSP, global, and project loaders
|
|
17
|
+
adopt it without adding another merge implementation.
|
|
18
|
+
- Canonical config is `.pi-lens.json` plus `~/.pi-lens/config.json`; locations,
|
|
19
|
+
legacy migrations, and namespaces live in the config-location/schema modules.
|
|
20
|
+
A new config key or environment flag needs a forcing function, stability tier,
|
|
21
|
+
diagnostic code, tests, and docs.
|
|
22
|
+
- `rules.<id>.ignorePaths` is an experimental, project-relative path denial
|
|
23
|
+
resolved by config-core with array-union semantics: global entries cannot be
|
|
24
|
+
cleared by project config. Ast-grep and tree-sitter apply it before scanning;
|
|
25
|
+
other runner output uses the shared rule-policy filter.
|
|
26
|
+
- `lens_diagnostics` has one model-facing diagnostic surface. `source` is
|
|
27
|
+
`session` or `lsp`; `scope` is `paths` or `workspace`; explicit paths always
|
|
28
|
+
win. Severity is a threshold. Retired compatibility names must not widen a
|
|
29
|
+
request into a workspace sweep.
|
|
30
|
+
|
|
31
|
+
</important>
|