From 78aa97d670d197097f76e70f57438cc4ca8c5790 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20M=C3=BCller?= Date: Thu, 10 Sep 2026 23:49:09 +0000 Subject: [PATCH] :memo: Correct the pi-lsp false-positive finding The TS1295/TS1287 errors were not an LSP misconfiguration: the server was still running from an earlier local test that had emptied package.json, and kept the corrupted project state alive. Driven with pi-lsp's exact handshake, tsc --lsp --stdio reads tsconfig.json correctly. Record the real caveat instead: no file watchers, so tsconfig.json/package.json edits can leave diagnostics stale until the server restarts. --- AGENTS.md | 2 +- backlog.tasks | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cf6c52a..68249ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ first-action facts. Do not restate evolving prose here — it will drift. - Project: F#-style pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim). - **While iterating:** `npm run test` (`check:tsc` + the unit suite) for fast feedback on the files you changed. -- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). +- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong. - **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run. - **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit. - **`npm run maintain` is NOT part of the feature loop.** Its scans are advisory, never a gate; run them only on an explicit maintenance / update-deps branch. diff --git a/backlog.tasks b/backlog.tasks index 64c4c61..da07e72 100644 --- a/backlog.tasks +++ b/backlog.tasks @@ -22,11 +22,11 @@ Setup: ☐ Fix the declaration emit (`.d.ts` post-step) or stop using relative `.ts` in the declaration surface ☐ Reconcile the README/CONTRIBUTING claim that `rewriteRelativeImportExtensions` yields "conventional ESM imports" ☐ Add a consumer-resolution test to the suite (durable guard; `attw` currently misses it) -☐ Document pi-lsp false-positive diagnostics - - `lsp_diagnostics` reports TS1295/TS1287 "CommonJS file under `verbatimModuleSyntax`" errors that `check:tsc` never produces — the server is not picking up the repo's `tsconfig.json` - - AGENTS.md only warns that empty LSP output is inconclusive, not that it can emit false errors - ☐ Add a line to AGENTS.md: ignore LSP errors that `check:tsc` does not reproduce - ☐ Or fix the LSP server configuration so it picks up `tsconfig.json` +✔ Document pi-lsp false-positive diagnostics @done + - `lsp_diagnostics` reported TS1295/TS1287 "CommonJS file under `verbatimModuleSyntax`" errors that `check:tsc` never produced + - root cause: an earlier local test emptied package.json; the still-running TS7 server (5 min idle timeout) kept the corrupted project state alive and reported it against the real files + ✔ No LSP misconfiguration to fix: driven with pi-lsp's exact handshake, tsc --lsp --stdio reads tsconfig.json correctly; hover resolves real inferred types and lsp_diagnostics is clean on a fresh server @done + ✔ Added the one real caveat to AGENTS.md: the server does not register file watchers, so tsconfig.json/package.json edits can leave diagnostics stale until it restarts @done ✔ Run packaging checks in CI `build` @done - `publish:publint` / `publish:attw` only run in the tag-triggered `publish` job, so a PR that breaks packaging stays green until release ✔ At minimum add `publish:publint` to the `build` job (offline, fast); `attw` needs a pack @done