tiny-pattern-ts/backlog.tasks

Tasks

Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.

---

Setup:
✔ Establish release CI workflow: post-tag checks + npm publish after release tag push => pi --session 01a06e72-e61e-7327-b3e9-3e11749a523f @high @done (9/11/2026, 12:37:35 AM)
☐ Add gitea release page in CI @high
☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @high
✔ Make the pi-lsp install reproducible @done
    - `.pi/npm/.gitignore` is `*` / `!.gitignore`, so only `.gitignore` is committed; `.pi/npm/package.json` and `package-lock.json` are untracked
    - the README insists `@spences10/pi-lsp` is "pinned to 0.0.46", but the lockfile that pins the transitive tree does not survive a fresh clone
    ✔ Resolved by design, no change: `.pi/settings.json` is the shared committed declaration (`npm:@spences10/pi-lsp@0.0.46`), and `.pi/npm/` is a gitignored install cache pi recreates on a trusted startup (settings.md: trusting a project allows pi to "install missing project packages"). The .gitignore is intentional; the exact pin lives in the committed settings file. README clarified @done
✔ Gate the emit path in `npm run verify` @done
    - `verify = check + test:unit`; `check:tsc` uses the root config (`noEmit: true`), so `tsconfig.build.json` is only exercised by `build`
    - a broken build config (bad `rootDir`, emit-option typo) passes `verify` and only fails in CI
    ✔ Confirmed no change: `verify` is the local quick source-correctness check; the emit path is gated by CI's `build` job (`npm run build`), so adding `build` locally only adds inner-loop friction @done
✔ Fix `.ts` extensions in emitted `.d.ts` @done
    - emitted JS rewrites `./pattern.ts` → `./pattern.js`, but `dist/*.d.ts` still imports `"./pattern.ts"` / `"./match.ts"`
    - resolves under TS7, but a portability risk for older resolvers/bundlers; `attw` does not catch it
    - HANDOVER (setup-phase review, unfixed — emit work deferred out of that session):
        - verified current state: `tsconfig.build.json` has `rewriteRelativeImportExtensions: true`; it rewrites the JS (dist/match.js → `./pattern.js`) but NOT the declarations (dist/index.d.ts, dist/match.d.ts keep `.ts`)
        - `npm run build` + `publish:publint` + `publish:attw` + a packed-consumer `tsc -p` all pass today, so this is a portability/robustness fix, not a broken-build fix — don't expect a red gate to confirm it works
        - the durable proof is a consumer-resolution typecheck that asserts types still flow (a deliberately-wrong assignment must error), not just exit 0 — TS7 resolution silently tolerates the `.ts` form, so a green run alone proves nothing
        - two directions: (a) post-process the `.d.ts` imports to `.js` in the build, or (b) stop emitting relative `.ts` on the declaration surface (e.g. build-only source or an internal barrel). Either way reconcile the README/CONTRIBUTING sentence claiming the option yields "conventional ESM imports" for consumers
    - resolution: no code change. TypeScript >= 5.0 resolves the `.ts` specifier in shipped declarations in `node10`/`node16`/`nodenext`/`bundler` (verified across TS 4.7–7.0 with a consumer `@ts-expect-error` type guard). TS <= 4.9 rejects it, but also cannot parse the `<const L extends …>` already emitted in `dist/pattern.d.ts` (const type parameters, a TS 5.0 feature), so no consumer that can use the package is affected; the effective floor is now documented in README § Requirements
    ✘ Post-process the declaration emit to `.js`, or restructure to avoid relative `.ts` on the declaration surface @cancelled
    ✔ Reconcile the README/CONTRIBUTING claim that `rewriteRelativeImportExtensions` yields "conventional ESM imports"; document the TS >= 5.0 floor @done
    ✘ Add a consumer-resolution test (moot without a fix; `attw` still misses this class of issue) @cancelled
✔ Resolve sourcemap sources for consumers @done
    - `dist/*.map` `sources` are `../src/*.ts`, but `src` is not in `files`, so debuggers get missing sources
    - HANDOVER (setup-phase review, unfixed — emit work deferred out of that session):
        - verified: every `dist/*.map` (js and d.ts) has `sources: ["../src/<file>.ts"]`, and `package.json#files` ships only `dist`, `CHANGELOG.md`, `README.md`, `LICENSE` — so those paths point at files the consumer never receives
        - decide between shipping `src` in `files` (keeps go-to-definition working, slightly larger tarball) or dropping `sourceMap`/`declarationMap` from `tsconfig.build.json` (smaller, no broken references). Shipping `src` is usually the better library DX
        - overlaps the `.d.ts` item above: both are emit-surface changes, so doing them in one branch/commit avoids rebuilding that config twice
    - resolution: `inlineSources: true` embeds `sourcesContent` in `dist/*.js.map`, so debuggers resolve the original TS even though `files` ships only `dist`; `declarationMap` is dropped because a `.d.ts.map` cannot embed source and would dangle against unshipped `src`
    ✔ Resolved by `inlineSources` + dropping `declarationMap` (not by shipping `src`, nor by disabling both maps) @done
✔ 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
✔ Publish the exact artifact CI tested @done
    - `publish: needs: build`, then re-runs `npm ci` + `build` from scratch, discarding the tested output
    - tag push pays a double build and the two builds could differ
    ✔ Persist `dist/` as an artifact in `build` and consume it in `publish` @done
✔ Confirm pre-push gate strength @done
    - pre-push runs `npm test` (`check:tsc` + tests), not full `check`; the staged-file oxlint/oxfmt/cspell checks live in pre-commit, whole-project correctness in CI
    ✔ Confirmed intended: pre-push is a local quick check, not a gate — CI on Gitea is the authoritative whole-project gate and checks the pushed commits' content; dirty working-tree files are out of scope by design @done
✔ Clean stale `coverage/` in `npm run clean` @done
    ✔ `npm run clean` only removes `dist`; add `coverage` (both are gitignored but bloat the working tree) @done
✔ Drop redundant `main`/`types` top-level fields @done
    ✔ `exports` is the source of truth; `main`/`types` are redundant (harmless, but publint/ATTW prefer `exports`) @done
✔ Silence the knip `@runwisp/pubv` false positive @done
    - `pubv` is a CLI invoked by `release.sh`, not imported, so knip flags it as an unused devDependency and advisory output stays permanently red
    ✔ Add a knip `ignoreDependencies` entry @done

✔ Sweep doc/formatter drift before v1.0 @done
    ✔ README says `--experimental-strip-types`; scripts use `--strip-types` @done
    ✔ `.vscode/settings.json` bundles `[markdown]`/`[yaml]` oxfmt formatters separately from `.oxfmtrc.json`'s `ignorePatterns` — align @done
✔ Document branching model @done
    ✔ Describe branching model: when to branch, base branch, naming @done
    ✔ Clarify release workflow: who pushes `main`, CI as post-merge gate, drop PR usage @done (9/8/2026, 2:54:32 PM)
✔ Evaluate connecting the agent to lsp typescript server @done
    - might be more difficult with TS7, since LSP Server has changed from 6
    - but since vscode is running TS7, maybe it is possible to connect to the TS7 LSP server of vscode
    - LSP servers in general?
    - maybe skills?
    → resolved: adopted @spences10/pi-lsp@0.0.46 as a project-local pi extension (`.pi/settings.json`). It auto-detects the repo's TypeScript 7 (no `lib/tsserver.js`) and spawns `tsc --lsp --stdio` — the same tsgo binary VS Code's native-preview uses. Read-only: hover / definition / references / symbols / diagnostics. No skill; skills don't own persistent processes.

✔ Adopt a `setup:` prefix for one-time clone configuration @done
    ✔ Register `use:git-commit-message` as its first member (and retire `use:` — it is in no prefix list) @done
    ✔ Create an umbrella 'setup' task that runs all setup tasks - currently one @done

v1.0:
☐ API surface is stable and fully typed
    ☐ Finalize public exports in `src/index.ts`
    ☐ Document all exported types and functions
    ☐ Add JSDoc for public APIs
☐ Test coverage meets threshold
    ☐ Achieve 100% branch coverage on `src/pattern.ts`
    ☐ Achieve 100% branch coverage on `src/match.ts`
    ☐ Achieve 100% branch coverage on `src/index.ts`
✔ `dist/` output is clean @done
    ✔ Verify `.d.ts` declarations match public exports @done
    ✔ Ensure `.js` files use `.js` extensions (not `.ts`) @done

Bugs:

Enhancements:

Documentation:
☐ Add usage examples to README.md
☐ Create `examples/` directory with runnable snippets
☐ Add comparison section vs. other TS pattern-matching libs
☐ Write migration guide for users coming from discriminated unions
☐ Create backlog tasks for implementation

Maintenance:
☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low
    ☐ Add a minimal dir-listing webserver to the gitea docker setup (e.g. caddy `file_server browse` reusing the existing reverse proxy, or any single-binary static server, lipanski/docker-static-website)
    ☐ CI writes each run's `coverage/` into a shared volume keyed by project + tag (e.g. `/coverage/tiny-pattern-ts/<tag>/`)
    ☐ Browse to `…/coverage/<repo>/<tag>/index.html` in the browser; drop the `actions/upload-artifact` coverage step in favour of the shared-dir layout
    → design: no deploy step in CI; the webserver just exposes the shared directory (decided over Gitea Pages / Codecov — neither confirmed available/ wanted)
✔ Set up lefthook pre-commit hook @done (9/8/2026, 10:52:56 AM)
✔ Configure tsconfig strictest + node26 profiles @done (9/8/2026, 10:08:37 AM)
✔ Add check:tsc as first tier in `npm run check` @done (9/8/2026, 10:08:37 AM)
✔ Pin Node.js >= 26 via `.node-version` @done (9/8/2026, 10:08:38 AM)