🚀 Release 0.8.0

🔀 Merge fix/union-valued-discriminant into main
✅ Cover property-union autocomplete and rejection
2026-09-23 17:42:32 +00:00 · 2026-09-23 17:37:37 +00:00 · 2026-09-23 16:32:16 +00:00 · 2026-09-23 16:32:09 +00:00 · 2026-09-23 16:04:00 +00:00 · 2026-09-23 15:27:05 +00:00
53 changed files with 11654 additions and 526 deletions
@@ -1,37 +0,0 @@
 // .eslintrc.cjs
 module.exports = {
    root: true,
    parser: '@typescript-eslint/parser',
    plugins: [
        '@typescript-eslint',
        'import',
        'unused-imports',
        'simple-import-sort',
    ],
    extends: [
        'eslint:recommended',
        'plugin:@typescript-eslint/recommended',
        'plugin:@typescript-eslint/strict-type-checked',
        'plugin:@typescript-eslint/stylistic-type-checked',
        'plugin:import/recommended',
        'plugin:import/typescript',
        'plugin:prettier/recommended',
    ],
    env: {
        es2022: true,
        node: true,
        browser: true,
    },
    rules: {
        'prettier/prettier': 'error',
        'import/order': 'off',
        'simple-import-sort/imports': 'error',
        'simple-import-sort/exports': 'error',
        'unused-imports/no-unused-imports': 'error',
        '@typescript-eslint/no-unused-vars': [
            'error',
            { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
        ],
    },
    ignorePatterns: ['dist', 'node_modules', 'public'],
 };
@@ -0,0 +1,208 @@
 name: CI
 on:
    push:
        branches: [main]
        # Releases are tag pushes (`scripts/release.sh` tags bare `x.y.z`). A
        # `branches` filter alone matches no tag ref, so without this both the
        # tag-gated `publish` job and the coverage publish step never fire.
        tags: ["*"]
    pull_request:
        branches: [main]
    workflow_dispatch: {}
 jobs:
    # Cheap gate that collapses the release double-run. `scripts/release.sh`
    # pushes `main` and the tag seconds apart, and the tag points at exactly
    # the HEAD commit that push delivers — so the branch run would verify the
    # identical tree the tag run verifies anyway (plus `publish`). When a push
    # to `main` is headed by a release commit (`:rocket: Release x.y.z`, the
    # single commit release.sh creates), the full CI is skipped here and the
    # tag run becomes the authoritative one for that SHA. All other pushes —
    # PRs, tags, ordinary `main` merges — see `skip=false` and run as before.
    #
    # Coupling: the pattern below MUST stay in sync with the release commit
    # message in `scripts/release.sh`. Failure mode if the tag push ever fails
    # after `main` accepted the release commit: no CI fires; fix by re-running
    # `git push --tags`.
    release-gate:
        runs-on: ubuntu-latest
        outputs:
            skip: ${{ steps.decide.outputs.skip }}
        steps:
            - uses: actions/checkout@v4
            - id: decide
              env:
                  REF: ${{ gitea.ref }}
              run: |
                  # Keyed on the ref, not just the message: a tag run checks out
                  # the same release commit, and `publish` needs its `build`.
                  if [ "${REF}" = "refs/heads/main" ] &&
                      git log -1 --format=%s | grep -qE '^:rocket: Release [0-9]+\.[0-9]+\.[0-9]+$'; then
                      echo 'Release commit on main — the tag run covers this SHA; skipping full CI.'
                      echo 'skip=true' >>"${GITHUB_OUTPUT}"
                  else
                      echo 'skip=false' >>"${GITHUB_OUTPUT}"
                  fi
    build:
        needs: release-gate
        if: needs.release-gate.outputs.skip != 'true'
        runs-on: ubuntu-latest
        # `image` extends the runner's default job image (catthehacker/act)
        # with Node 26 pre-planted in the tool cache layout, so setup-node's
        # version probe hits and never downloads (see docker/Dockerfile). The
        # tag MUST equal the exact version pinned in `.node-version`; the bump
        # ritual is documented in CONTRIBUTING.md § CI runner image. The volume
        # bind-mounts the shared pages tree so the
        # coverage step below can write into it; the runner whitelists this
        # path via `container.valid_volumes` (docker-space `setup/gitea.sh`).
        container:
            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
            volumes:
                - /data/gitea-pages:/data/gitea-pages
        steps:
            - uses: actions/checkout@v4
            # Fail fast when the job container is not the baked image: a stale
            # tag on the runner (`forcePull=false` in its pull log) silently
            # reintroduces the per-job download. Cheap, and it names the
            # invariant.
            - name: Assert the baked tool cache is present
              run: |
                  test -f "/opt/hostedtoolcache/node/$(tr -d '[:space:]' < .node-version)/x64.complete"
            - uses: actions/setup-node@v4
              with:
                  node-version-file: .node-version
                  cache: "npm"
            - run: npm ci
            - run: npm run build
            - run: npm run check
            - run: npm run test:ci
            # Publish this tag's coverage to the self-hosted pages server,
            # served read-only at
            # https://pages.e1nsnull.de/<owner>/<repo>/<tag>/coverage/. Wipe only
            # this tag's `coverage/`, so sibling docs/landing trees and older
            # tags survive; pruning stale tags is a manual chore. The
            # precompress pass emits `.br` / `.gz` / `.zst` sidecars next to
            # every text asset, so `static-web-server` can serve the precompressed
            # variant and keep the original as fallback.
            - name: Publish coverage to the pages server
              if: startsWith(gitea.ref, 'refs/tags/')
              env:
                  REPO: ${{ github.repository }}
                  REF: ${{ gitea.ref }}
              run: |
                  TAG="${REF#refs/tags/}"
                  DEST="/data/gitea-pages/${REPO}/${TAG}/coverage"
                  rm -rf "${DEST}"
                  mkdir -p "${DEST}"
                  cp -R coverage/. "${DEST}/"
                  node --strip-types scripts/precompress.ts "${DEST}"
                  echo "Coverage: https://pages.e1nsnull.de/${REPO}/${TAG}/coverage/"
            # Fast, offline packaging gate. `attw` stays in `publish` (it needs
            # a pack + full resolution matrix); `publint` packs too but is cheap
            # enough to run on every push so a packaging break fails here, not
            # at release time.
            - run: npm run publish:publint
            # Persist the exact dist/ that `check`, `test:ci` and `publint` were
            # run against, so `publish` ships those bytes instead of rebuilding
            # (which could in principle differ and would pay the build twice).
            - uses: actions/upload-artifact@v4
              with:
                  name: dist
                  path: dist/
    # Advisory scans (dead code, dependency freshness). Non-blocking: surfaced in
    # the Actions tab for visibility, but must never gate a merge — so
    # continue-on-error and intentionally NOT in `publish`'s `needs`.
    maintain:
        needs: release-gate
        if: needs.release-gate.outputs.skip != 'true'
        runs-on: ubuntu-latest
        continue-on-error: true
        # Same baked image as `build` — without it this job re-downloads Node
        # per run (see docker/Dockerfile).
        container:
            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
        steps:
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
              with:
                  node-version-file: .node-version
                  cache: "npm"
            - run: npm ci
            - run: npm run maintain
    publish:
        if: startsWith(gitea.ref, 'refs/tags/')
        needs: build
        runs-on: ubuntu-latest
        # Same baked image as `build` — setup-node still owns the registry-url
        # `.npmrc` rewrite here; only the Node download is skipped.
        container:
            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
        # The release page is created with the run's automatic Gitea token
        # (`github.token`), so it needs `contents: write`.
        permissions:
            contents: write
        # The npm token is optional: `secrets` is not an allowed context in a
        # step `if` (see GitHub's context-availability table), so it is lifted
        # into job-level `env`, where an unset secret arrives as the empty
        # string and skips the publish rather than attempting an unauthenticated
        # one. Set NPM_TOKEN in the Gitea repo: Settings → Actions → Secrets.
        env:
            NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        steps:
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
              with:
                  node-version-file: .node-version
                  # Same lockfile/key as `build`, and tag runs can read caches
                  # saved on `main` — without this, every release pays a cold
                  # `npm ci` despite the warm shared npm cache.
                  cache: "npm"
                  registry-url: "https://registry.npmjs.org/"
            - run: npm ci
            # Consume the dist/ that `build` produced and gated, instead of
            # rebuilding here — `publish` must ship the tested artifact.
            - uses: actions/download-artifact@v4
              with:
                  name: dist
                  path: dist/
            - run: npm run publish:publint
            - run: npm run publish:attw
            # The Gitea release page is created *before* `npm publish` on
            # purpose: a broken page then fails CI without burning an npm
            # version. The page is cheap to retry, a published version is not.
            # The body is the matching Keep-a-Changelog section; an unknown tag
            # makes the extractor exit non-zero, so the page can never go up
            # empty.
            - name: Extract release notes from CHANGELOG.md
              env:
                  TAG_REF: ${{ gitea.ref }}
              run: ./scripts/release-notes.sh "${TAG_REF#refs/tags/}" > release-notes.md
            - name: Create the Gitea release
              id: gitea_release
              uses: https://gitea.com/actions/gitea-release-action@v1
              with:
                  body_path: release-notes.md
            - name: Publish to npm
              id: npm_publish
              if: env.NPM_TOKEN != ''
              run: npm publish --access public
              env:
                  NODE_AUTH_TOKEN: ${{ env.NPM_TOKEN }}
            # All-or-nothing: the tag is only released once *both* the release
            # page and the npm package are up. A skipped npm publish (NPM_TOKEN
            # unset) has no `success` outcome, so `always()` reaches this check
            # even after a failure and turns the skipped half into an explicit
            # red job instead of a silently green one.
            - name: Require both releases
              if: always()
              run: |
                  GITEA="${{ steps.gitea_release.outcome }}"
                  NPM="${{ steps.npm_publish.outcome }}"
                  if [ "${GITEA}" != success ] || [ "${NPM}" != success ]; then
                      echo "::error::incomplete release — gitea=${GITEA:-skipped} npm=${NPM:-skipped}"
                      exit 1
                  fi
@@ -1,24 +1,15 @@
 # Logs
 logs
 *.log
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 lerna-debug.log*
 node_modules
 dist
-dist-ssr
+coverage
 *.log
 *.tsbuildinfo
 *.local
 # Editor directories and files
 .vscode/*
 !.vscode/extensions.json
 !.vscode/settings.json
 !.vscode/tasks.json
 !.vscode/launch.json
 .idea
 .DS_Store
 *.suo
 *.ntvs*
 *.njsproj
 *.sln
 *.sw?
@@ -0,0 +1 @@
 26.8.2
@@ -0,0 +1,5 @@
 # Turn the `engines` field from a warning into a gate. By default a Node
 # version mismatch is only reported as a notice, so an install run under an
 # unpinned Node still succeeds and silently rewrites package-lock.json using
 # that older npm's resolution rules. Refuse the install instead.
 engine-strict=true
@@ -0,0 +1,19 @@
 {
    "$schema": "./node_modules/oxfmt/configuration_schema.json",
    "semi": true,
    "singleQuote": false,
    "trailingComma": "all",
    "printWidth": 80,
    "tabWidth": 4,
    "endOfLine": "lf",
    "arrowParens": "always",
    "sortPackageJson": true,
    "sortImports": true,
    "ignorePatterns": [
        "dist",
        "coverage",
        "node_modules",
        "package-lock.json",
        "*.tsbuildinfo"
    ]
 }
@@ -0,0 +1,56 @@
 {
    "$schema": "./node_modules/oxlint/configuration_schema.json",
    "plugins": ["typescript", "unicorn", "oxc", "import"],
    "categories": {
        "correctness": "error",
        "suspicious": "error",
        "perf": "warn",
        "style": "warn",
        "restriction": "error",
        "nursery": "off"
    },
    "rules": {
        "eslint/no-undefined": "off",
        "eslint/sort-keys": "off",
        "eslint/id-length": "off",
        "eslint/capitalized-comments": "off",
        "eslint/no-ternary": "off",
        "import/no-named-export": "off",
        "eslint/one-var": "off",
        "import/group-exports": "off",
        "import/exports-last": "off",
        "eslint/sort-imports": "off",
        "import/consistent-type-specifier-style": "off",
        "unicorn/prefer-export-from": "off",
        "typescript/method-signature-style": "off",
        "typescript/promise-function-async": "off"
    },
    "options": { "typeAware": true },
    "env": { "builtin": true, "es2024": true, "node": true },
    "overrides": [
        {
            "files": ["**/*.test.ts"],
            "rules": {
                "no-unused-expressions": "off",
                "no-empty-file": "off",
                "import/no-nodejs-modules": "off",
                "eslint/no-magic-numbers": "off",
                "unicorn/no-null": "off",
                "typescript/no-floating-promises": "off"
            }
        },
        {
            "files": ["scripts/**/*.ts"],
            "rules": {
                "import/no-nodejs-modules": "off"
            }
        },
        {
            "files": ["src/util/__tests__/**"],
            "rules": {
                "import/no-nodejs-modules": "off"
            }
        }
    ],
    "ignorePatterns": ["dist", "node_modules", "coverage"]
 }
@@ -0,0 +1,2 @@
 *
 !.gitignore
@@ -0,0 +1,3 @@
 {
    "packages": ["npm:@spences10/pi-lsp@0.0.46"]
 }
@@ -0,0 +1,10 @@
 {
    "recommendations": [
        "connor4312.nodejs-testing",
        "oxc.oxc-vscode",
        "streetsidesoftware.code-spell-checker",
        "typescriptteam.native-preview",
        "sandy081.todotasks",
        "EditorConfig.EditorConfig"
    ]
 }
@@ -0,0 +1,15 @@
 {
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Debug current test file",
            "runtimeExecutable": "node",
            "runtimeArgs": ["--test", "--strip-types"],
            "args": ["${file}"],
            "cwd": "${workspaceFolder}",
            "console": "integratedTerminal"
        }
    ]
 }
@@ -0,0 +1,50 @@
 {
    "nodejs-testing.extensions": [
        {
            "extensions": ["mjs", "cjs", "js"],
            "parameters": []
        },
        {
            "extensions": ["ts"],
            "parameters": ["--strip-types"]
        }
    ],
    "[typescript]": {
        "editor.defaultFormatter": "oxc.oxc-vscode",
        "editor.formatOnSave": true
    },
    "[typescriptreact]": {
        "editor.defaultFormatter": "oxc.oxc-vscode",
        "editor.formatOnSave": true
    },
    "[javascript]": {
        "editor.defaultFormatter": "oxc.oxc-vscode",
        "editor.formatOnSave": true
    },
    "[javascriptreact]": {
        "editor.defaultFormatter": "oxc.oxc-vscode",
        "editor.formatOnSave": true
    },
    "[json]": {
        "editor.defaultFormatter": "oxc.oxc-vscode",
        "editor.formatOnSave": true
    },
    "[jsonc]": {
        "editor.defaultFormatter": "oxc.oxc-vscode",
        "editor.formatOnSave": true
    },
    "[markdown]": {
        "editor.defaultFormatter": "oxc.oxc-vscode",
        "editor.formatOnSave": true
    },
    "[mdx]": {
        "editor.defaultFormatter": "oxc.oxc-vscode",
        "editor.formatOnSave": true
    },
    "[yaml]": {
        "editor.defaultFormatter": "oxc.oxc-vscode",
        "editor.formatOnSave": true
    },
    "editor.defaultFormatter": "oxc.oxc-vscode",
    "editor.formatOnSave": true
 }
@@ -0,0 +1,71 @@
 # AGENTS.md
 Machine entry point for AI coding agents working in this repo. The authoritative
 guidance for humans lives in [CONTRIBUTING.md](./CONTRIBUTING.md) and
 [README.md](./README.md); this file only points at it and states the stable
 first-action facts. Do not restate evolving prose here — it will drift.
 ## First action
 - 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)`. **When you are looking for a symbol, reach for the LSP before `rg`/`grep`** — `lsp_references` / `lsp_find_symbol` / `lsp_definition` / `lsp_document_symbols` are semantic and cross-file, so they see shadowing, imports and overloads that a text search cannot; use `lsp_hover` to read inferred types on generic-heavy code. Use `rg` for what the LSP cannot see — doc prose, string literals, config, task lists, file discovery — and reconcile the two sets before editing (symbols from the LSP, strings and prose from `rg`). 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.
 - **Document decisions where the next maintainer will look:** rationale, rejected alternatives and known issues go in `development/<category>.md` (see [development/README.md](./development/README.md)); the actionable rule stays in [CONTRIBUTING.md](./CONTRIBUTING.md) and links to it. Write each fact once — never copy the rule into `development/` or the reason into `CONTRIBUTING.md` — and change both in the same commit when a rule changes.
 - **`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.
    ```sh
    npm run test    # while iterating (fast feedback)
    npm run verify  # definition of done: whole-project correctness, one shot
    ```
 ## Never do
 Don't silence the type system to force a green run. As an agent these are forbidden:
 - `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error`
 - `// oxlint-disable` / `// oxlint-disable-next-line`
 - editing `.oxlintrc.json` to silence a finding (e.g. turning `typescript/no-floating-promises` off)
 - `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions)
 Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. Suppressions — a source `oxlint-disable` **or** a `.oxlintrc.json` entry — are a **human** last resort, not a tool for you. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it.
 The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C <skipped-sha>`.
 Never start a long-lived / blocking process such as `npm run watch`. It runs until a human stops it with Ctrl-C, so in an agent turn it hangs forever and floods the context with continuous output. Reach for a one-shot command instead — `npm run test` (or `npm run check`) — to get feedback.
 ## Backlog
 `backlog.tasks` uses the vscode-todotasks format (not Markdown). A line ending in `:` is a project; every other line is a task. Status glyphs: `☐` open, `✔` done, `✘` cancelled; subtasks nest by indentation. Inline `@tags` carry metadata — `@done` / `@cancelled` mark completion, `@critical` / `@high` / `@low` / `@today` set priority. The `(…)` timestamp after `@done` is editor-generated: omit it when checking off by hand.
 **Required coupling:** a `✔` line _must_ also carry `@done`, and a `✘` line _must_ carry `@cancelled`. The `sandy081.todotasks` extension treats the glyph as the completion signal, then unconditionally searches for the matching tag to decorate; a bare `✔`/`✘` with no tag makes it compute an illegal `Range` (negative character offset) that throws and kills all highlighting/decoration for the document. A `☐` may stand alone. So check off by hand as `✔ … @done` (optionally `@done (timestamp)`), never a lone `✔`.
 ### Working on tasks
 Every task — with or without subtasks — goes through the complete branching model:
 - Create the branch with `npm run create:branch -- <prefix>/<desc>`, inferring the prefix from the task content (`feature/…` / `fix/…` / `chore/…`) — do not hand-write `git switch -c`, the command enforces the clean-tree / current-`main` / green-baseline precondition. Work with commits (each subtask gets one or more), then present a concise handover for the user to review. Use this fixed shape:
    ```md
    ## Handover — <branch>
    **Implemented:** <what was built, and how>
    **Judgement calls:** <where the task was unclear, and what you assumed>
    **Known problems:** <open issues, caveats, follow-ups>
    ```
    Once the user has no further objections, merge back: `npm run create:finish` (on the branch — it merges `--no-ff`, runs `npm run verify`, and deletes the branch). The branching model is documented in [CONTRIBUTING.md § Branching model](./CONTRIBUTING.md#branching-model).
 Follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven) throughout.
 ## Read these
 - [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) — the constraints the linters don't catch; CI/review bounce these. **The most important section.**
 - [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven) — write the `expectTypeOf` (type) before the `assert` (red); the types are the feature.
 - [CONTRIBUTING.md § Script prefix convention](./CONTRIBUTING.md#script-prefix-convention) — adding an `npm run` script? reuse an existing prefix or it doesn't belong.
 - [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages) — gitmoji + imperative + 50/72.
 - [CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers) — what runs when and at what cost (`watch` / pre-commit / pre-push / `check` / `verify` / `fix` / `maintain` / CI).
 - [development/](./development/README.md) — the decisions, rejected alternatives and known issues behind the rules; the “why” that CONTRIBUTING.md links to. Read the relevant file before changing an area.
 - [development/tooling.md](./development/tooling.md) — the rationale behind each tool choice; read before changing tooling.
 - [package.json `#scripts`](./package.json) — the source of truth for every command (the `LEFTHOOK_FILES` convention scopes them to staged files vs. the whole project).
@@ -0,0 +1,114 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0/).
 ## [Unreleased]
 ## [0.8.0] - 2026-09-23
 - reject a universe that mixes a literal with a broad type (e.g.
  `"a" | \`x-${number}\``), which the finite-literal gate let through
 - narrow the tagged-union matcher's handler parameters for a union-valued or
  optional discriminant, and its fallback to the unhandled tags, instead of
  passing `never`
 ## [0.7.1] - 2026-09-23
 - upgrade dependencies
 ## [0.7.0] - 2026-09-23
 - reject broad universes (`string`, `number`, template literals) and
  value/stringification collisions (`true | "true"`, `1 | "1"`) at the factory
 - type handler parameters by the matched member, so a
  standalone `"true"` universe is typed `"true"` rather than `true`
 ## [0.6.0] - 2026-09-22
 - add `getTaggedUnionMatcher` / `getTaggedUnionMatcherW` for discriminated unions
 - rename the primitive matcher to primitive-union: `getMatcher` /
  `getMatcherW` → `getPrimitiveUnionMatcher` / `getPrimitiveUnionMatcherW`, and
  `src/primitive.ts` / `src/primitive.test.ts` → `src/primitive-union.*`
 ## [0.5.0] - 2026-09-21
 - reject a fallback when the handler map already covers the universe
 - allow boolean, null and undefined in the matcher universe
 ## [0.4.0] - 2026-09-20
 - move the `_` fallback out of handlers
 ## [0.3.0] - 2026-09-18
 - condensed primitive matcher factories down to 2 from formerly 4
 - house shared test helpers under `src/util/__tests__/`
 ## [0.2.0] - 2026-09-16
 - allow ternaries and lowercase comments in oxlint
 - switch `src/primitive.ts` prose from block comments to line comments
 - remove the template's `match`/`P` example modules and their documentation, and point `src/index.ts` at the primitive matchers
 ## [0.1.8] - 2026-09-16
 - upgrade dependencies
 - ignore `@types/node` in `maintain:outdated` (misleading `latest` dist-tag)
 - require extremely concise prose in `development/`
 ## [0.1.7] - 2026-09-16
 - require a short summary under `[Unreleased]` in the changelog before a branch is finished
 - let `create:branch` start from a `main` that is ahead of its upstream, so a finished merge no longer blocks the next branch until it is pushed
 ## [0.1.6] - 2026-09-15
 - restructure the documentation: README.md for users, CONTRIBUTING.md for contributors, and development/ for the decisions, rejected alternatives and known issues
 - document the decisions and known issues for CI, tooling, testing, publishing and the workflow
 ## [0.1.5] - 2026-09-15
 - improve CI configuration
 ## [0.1.4] - 2026-09-14
 - fix CI to node from custom image
 - upgrade dependencies
 ## [0.1.3] - 2026-09-14
 - change to custom image for CI
 ## [0.1.2] - 2026-09-14
 - upgrade dependencies
 ## [0.1.1] - 2026-09-14
 - upgrade dependencies
 ## [0.1.0] - 2026-09-14
 - basic setup
 [Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.0...main
 [0.8.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.1...0.8.0
 [0.7.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.0...0.7.1
 [0.7.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.6.0...0.7.0
 [0.6.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.5.0...0.6.0
 [0.5.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.4.0...0.5.0
 [0.4.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.3.0...0.4.0
 [0.3.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.2.0...0.3.0
 [0.2.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.8...0.2.0
 [0.1.8]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.7...0.1.8
 [0.1.7]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.6...0.1.7
 [0.1.6]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.5...0.1.6
 [0.1.5]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.4...0.1.5
 [0.1.4]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.3...0.1.4
 [0.1.3]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.2...0.1.3
 [0.1.2]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.1...0.1.2
 [0.1.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.0...0.1.1
 [0.1.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/20308c5a6d8cccfb09b02ac2ebebd8055e91cd11...0.1.0
@@ -0,0 +1,242 @@
 # Contributing
 This document is for maintainers and contributors working on the project
 itself. End-user documentation is in [README.md](./README.md). The reasons
 behind the rules here — the decisions, rejected alternatives, and known issues —
 live in [development/](./development/README.md). The machine entry point for AI
 coding agents is [AGENTS.md](./AGENTS.md); keep this file as the prose home for
 the rules so agents and humans don't diverge.
 ## Setup
 1. Clone the repository.
 2. Install Node.js >= 26 — see [.node-version](./.node-version); the exact pinned
   version is what CI and the runner image use.
 3. `npm ci`.
 4. `npm run setup` — the one-time clone configuration (currently registers the
   commit-message template).
 ## Development commands
 - **Build:** `npm run build`
 - **Test:** `npm run test`, `npm run test:ci`
 - **Watch:** `npm run watch` - re-runs tests on file save, humans only
 - **Checks:** `npm run check`, `npm run fix`
 - **Verify:** `npm run verify` — the definition of done
 - **Maintenance:** `npm run maintain` — advisory only
 - **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`
 ## Feedback tiers
 The tools are organized into a feedback ladder. Each tier catches different
 things at different costs; the rule of thumb is "earlier tiers fire more often,
 faster tiers catch less, slower tiers are more thorough":
 | Tier                             | When                    | What it runs                                                                                                                                            | Time  |
 | -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
 | `npm run watch`                  | manual                  | `watch:test` — re-runs tests on file save                                                                                                               | ~0.1s |
 | Pre-commit (auto)                | on stage                | tsc + oxlint + oxfmt + cspell (staged files only)                                                                                                       | ~1.3s |
 | Pre-push (auto)                  | on push                 | `npm test` (full tsc + unit tests)                                                                                                                      | ~3.5s |
 | `npm run check`                  | manual                  | Correctness gates: tsc + oxlint + oxfmt + cspell (whole project)                                                                                        | ~3s   |
 | `npm run verify`                 | manual                  | Definition of done: `npm run check` + unit tests, one shot                                                                                              | ~6s   |
 | `npm run fix`                    | manual                  | Auto-resolve fixable issues (lint, format)                                                                                                              | ~3s   |
 | `npm run maintain`               | manual / CI (advisory)  | `maintain:knip` + `maintain:outdated` (whole-project + network scans)                                                                                   | ~10s  |
 | CI build (auto)                  | on push to `main` / tag | `build` job (build + correctness + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml)                                                | ~30s+ |
 | CI maintain (auto, non-blocking) | on push to `main`       | `npm run maintain` — reports, never fails the build                                                                                                     | ~10s  |
 | CI publish (auto)                | on tag                  | packaging checks + `publish:publint` / `publish:attw`, then the Gitea release page and `npm publish` (skipped, and the job failed, without `NPM_TOKEN`) | ~15s  |
 Before pushing, run `npm run verify` — the one-shot correctness gate. Run
 `npm run maintain` only on a maintenance / update-deps branch. Why the splits
 are where they are: [development/workflow.md § Feedback tiers](./development/workflow.md#feedback-tiers).
 ## Testing discipline (type-driven)
 For this library the types _are_ the feature, so development is **type-driven**:
 the compile-time expectation is written before the runtime assertion, and both
 before the implementation. The loop is **type → red → green → refactor**:
 1. **Type** — write the compile-time expectation first
   (`expectTypeOf(...).toEqualTypeOf<…>()`) and let `npm run check:tsc` fail on
   the _type_. The type error is the spec you want to hit before the runtime
   logic exists.
 2. **Red** — add the matching runtime assertion (`assert.*`) so
   `npm run test:unit` now fails on behavior.
 3. **Green** — implement in `src/*.ts` until both the type check and the test
   pass.
 4. **Refactor** — with the type system and the tests as the safety net, then
   `npm run verify` as the definition-of-done gate.
 Every test pairs an `expectTypeOf(...)` with an `assert.*`; keep them together
 — including the expectations inside handler bodies, which pair with an
 assertion on the value dispatch passed, not only the type it inferred (see
 [development/testing.md § Handler arguments](./development/testing.md#handler-arguments)).
 The autocomplete tests (`src/util/__tests__/lsp-completion.test.ts` for the
 helper, `src/primitive-union.test.ts` for the matcher's popup) are the
 exception —
 the language server, not the type system, is the oracle (see
 [development/testing.md § Autocomplete](./development/testing.md#autocomplete)).
 Each test body follows **AAA (Arrange–Act–Assert)** with labeled blocks
 separated by a blank line: `// Arrange` sets up the inputs (e.g. the matcher
 factory), `// Act` exercises the subject once from them (not a second
 throwaway call), `// Assert` holds every check — type expectations first,
 runtime assertions last; an empty block drops its label (see
 [development/testing.md § AAA ordering](./development/testing.md#aaa-ordering)).
 Type-first is enforced structurally: `npm test` runs `check:tsc` before the
 test runner, so a wrong type can never be papered over by a passing assertion.
 Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the
 types, never suppress the checks you can't make pass. Full rationale:
 [development/testing.md](./development/testing.md).
 ## Code style and formatting
 `oxfmt` is the formatter and `oxlint` is the linter (with type-aware rules).
 `npm run fix` resolves the fixable issues; `npm run check` verifies without
 writing. Suppressions must be fixed at the root — do not add `oxlint-disable`
 directives or `as` casts to force a green run (see
 [AGENTS.md § Never do](./AGENTS.md#never-do)).
 Suggested VSCode extensions are in
 [.vscode/extensions.json](./.vscode/extensions.json); the project's formatter
 and linter are wired up there. Toolchain decisions:
 [development/tooling.md](./development/tooling.md).
 ## Commit messages
 Gitmoji subject, imperative mood, 50/72 wrapping. The template is
 [commit-message-template](./commit-message-template); `npm run setup`
 (or `npm run setup:git-commit-message`) registers it as git's
 `commit.template`. Examples and rationale:
 [development/workflow.md § Commit messages](./development/workflow.md#commit-messages).
 ## Script prefix convention
 Script names in `package.json` use a prefix that signals _when_ the script is
 intended to run. A `<prefix>:<name>` script is implicitly aggregated by a
 `<prefix>` script (if one exists) and run by the corresponding lefthook hook or
 CI step. Pick the prefix that matches the script's lifecycle:
 - `create:*` — front doors of the repo's own workflow; these mutate git state
  rather than the source. `create:branch` opens a unit of work, `create:finish`
  closes the branch half, `create:release` closes the release half
  (maintainer-only). No bare `create` aggregator on purpose.
 - `check:*` — read-only verification; never modifies files. Aggregated by
  `npm run check`.
 - `fix:*` — mutating counterpart of a `check:*` script. Aggregated by
  `npm run fix`; the diff is the review surface.
 - `test:*` — test scripts. `test` is the canonical entry point (`check:tsc` +
  unit tests); `test:unit` skips the typecheck for fast local iteration;
  `test:ci` adds c8 coverage.
 - `watch:*` — long-running watchers for the manual inner dev loop. Aggregated by
  `watch`.
 - `maintain:*` — advisory repo-maintenance scans: read-only, but whole-project
  and/or network-bound, so never a correctness gate. Aggregated by
  `npm run maintain`.
 - `publish:*` — validates the _publishable artifact_ (e.g. `dist/`) rather than
  the source, so it needs a fresh build.
 - `setup:*` — one-time configuration of a fresh clone; mutates the local
  environment rather than the repo source, so it is never part of a hook or CI
  step. Aggregated by `npm run setup`, run once after cloning.
 A new script must reuse an existing prefix. If none fits, that's a signal the
 script doesn't belong in the pipeline — not a reason to invent a new prefix. If
 it genuinely does belong, add the prefix to this list in the same commit as its
 first member; an undocumented prefix becomes invisible and quietly accrues
 members. Why `create:` exists, the rejected names, and the design of the bare
 scripts: [development/workflow.md § Script prefix convention](./development/workflow.md#script-prefix-convention).
 ## Rules the tools don't enforce
 CI and review will bounce these even though `npm run check` and the linters
 don't catch them. They're the high-frequency things a contributor (or an agent)
 reaches for by default:
 - **Source imports use `.ts` extensions, never `.js`.** `node --strip-types`
  only resolves the `.ts` form at test time; "pre-fixing" an import to `.js`
  breaks the inner loop. (why:
  [development/tooling.md](./development/tooling.md#source-imports-use-ts-extensions))
 - **A new `npm run` script must reuse an existing prefix.** See
  [Script prefix convention](#script-prefix-convention).
 - **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The
  trade-off must sit next to the code it silences. This is a _human_ last-resort
  convention; agents must not add one, nor edit `.oxlintrc.json` to silence a
  finding (e.g. `typescript/no-floating-promises`) — see
  [AGENTS.md § Never do](./AGENTS.md#never-do). (why:
  [development/tooling.md](./development/tooling.md#oxlint-disable-directives-live-next-to-the-code))
 - **Don't put slow / network / whole-project scans in `check` or pre-commit.**
  Advisory scans are not correctness gates; they belong under `maintain:`. (why:
  [development/workflow.md](./development/workflow.md#feedback-tiers))
 - **New work starts with `npm run create:branch`, never a hand-written
  `git switch -c` / `git checkout -b`.** The command carries the branch
  precondition; branching around it skips the clean-tree, current-`main` and
  green-baseline checks, and the skip is invisible until a failure can no longer
  be attributed. (why:
  [development/workflow.md](./development/workflow.md#branching-model))
 - **Work is merged back with `npm run create:finish`, never a hand-written
  `git merge`.** The command carries the merge-side preconditions (clean tree,
  current `main`, a `feature/`/`fix/`/`chore/` branch) and runs `npm run verify`
  after the merge, so a merge cannot land unverified. (why:
  [development/workflow.md](./development/workflow.md#branching-model))
 - **There is no local `npm run publish`, and `publish:publint` / `publish:attw`
  don't go in `check`.** (why:
  [development/publishing.md](./development/publishing.md#ci-only-publishing))
 - **A branch ends with a changelog note:** before `npm run create:finish`,
  summarize the work under `[Unreleased]` in [CHANGELOG.md](./CHANGELOG.md).
  (why:
  [development/workflow.md](./development/workflow.md#changelog-notes))
 - **A decision or its rationale belongs in `development/`, not here.** This file
  holds the actionable rule; `development/<category>.md` holds why, the rejected
  alternatives and the known issues. When you change a rule, update its category
  file in the same commit and cross-link the two. (why:
  [development/README.md](./development/README.md))
 - **Prose in `development/` is extremely concise.** When adding or changing a
  decision, write fragments if needed — sacrifice grammar for concision. (why:
  [development/README.md § Decision blocks](./development/README.md#decision-blocks))
 ## Branching model
 **GitHub Flow (single-developer).** Every change — feature, fix, refactor —
 branches off `main` and is merged back via a local commit. There is no pull
 request workflow on Gitea yet.
 - **Base branch:** `main`
 - **Branch naming:** `feature/<desc>` / `fix/<desc>` / `chore/<desc>`
 - **Starting work:** `npm run create:branch -- <prefix>/<desc>`. It refuses,
  without changing anything, unless the working tree is clean, no
  merge/rebase/cherry-pick is in progress, `main` is not behind its upstream
  (a local merge not yet pushed is fine — the push belongs to `create:release`),
  and `npm run test` is green on `main`. The prefix is _your_ call, inferred from
  the task; the script validates it rather than guessing it.
 - **Merging:** `npm run create:finish` (on the branch). It re-asserts the same
  preconditions, merges `--no-ff`, runs `npm run verify`, and deletes the branch
  only after the merge is green. The push is left to `create:release`, so the
  merge stays local and reviewable.
 - CI runs on every push to `main` — see [Feedback tiers](#feedback-tiers) and
  [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml).
 - **Releases are NOT triggered by pushes.** Only the maintainer triggers a
  release; see [Publishing](#publishing).
 Full rationale, including the front-door decisions:
 [development/workflow.md § Branching model](./development/workflow.md#branching-model).
 ## Submitting changes
 There is no pull request workflow on Gitea yet, so a contribution is submitted
 as a branch that is merged locally:
 1. `npm run create:branch -- <prefix>/<desc>`.
 2. Commit your work (one or more commits, per the tests and style rules above).
 3. `npm run verify` — the definition of done.
 4. Add a changelog note under `[Unreleased]` (see
   [Rules the tools don't enforce](#rules-the-tools-dont-enforce)).
 5. `npm run create:finish` to merge the branch into `main` and verify the
   result.
 6. Present a handover for review. Once there are no further objections, the
   maintainer pushes.
 When the project is promoted to GitHub, this step becomes a normal pull request
 against `main`.
 ## Publishing
 Publishing is maintainer-only and CI-only. See
 [development/publishing.md](./development/publishing.md).
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2025 tmu
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -1 +1,52 @@
 # tiny-pattern-ts
 Pattern matching for TypeScript/ESM environments (F#-style, not regex).
 ## Description
 `tiny-pattern-ts` brings F#-style pattern matching to TypeScript. Patterns are
 ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
 composes the way any other guard does. It is deliberately not a regex engine and
 not a macro: there is no transpiler and no DSL to learn, and the type-level
 contract is the feature — see [development/library.md](./development/library.md)
 for the design decisions and [Caveats](#caveats) for the limits.
 ## Requirements
 - **Node.js >= 26** (`engines` field; pinned via `.node-version`).
 - **TypeScript >= 5.0** to consume the published declarations. The emitted `.d.ts`
  use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers;
  both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
 - The package is **ESM-only** (no CommonJS shim).
 ## API
 Yet to be implemented
 ## Caveats
 - **Only finite universes are supported.** The factory must be given a finite
  union of literals; `string`, `number` and template literals are rejected. This
  is what lets the exhaustive overload be proven, so the runtime `dispatch`
  throw stays unreachable through the typed API.
 - **A value and its stringification must not both be present.** Object keys
  stringify, so a universe containing both a member and the string it
  stringifies to — `1 | "1"`, `true | "true"`, `null | "null"` — is rejected at
  the factory. Either form alone is fine, and one value's string form may
  coexist with a _different_ value's bare form (`"true" | false`).
 - **`symbol` and `bigint` are not supported.** A `symbol` brand is a
  compile-time phantom with nothing to match at runtime, and a `bigint` is not a
  valid property key; neither satisfies the matcher's universe constraint.
 - **`NaN` and `-0` cannot be matched specifically.** They have no literal type,
  so both stay part of `number`.
 ## License
 MIT © 2025 tmu. See [LICENSE](./LICENSE).
 ## Contributing
 Contributions are documented in [CONTRIBUTING.md](./CONTRIBUTING.md); the
 reasons behind the project's decisions, rejected alternatives, and known issues
 live in [development/](./development/README.md). AI coding agents start at
 [AGENTS.md](./AGENTS.md).
@@ -0,0 +1,46 @@
 Tasks
 Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.
 ---
 Setup:
 ☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @low
 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/primitive-union.ts`
    ☐ Achieve 100% branch coverage on `src/index.ts`
 Matcher:
 ✔ when using a union type as a property, the current behavior of tagged union matcher is @done
    to pass never to handler parameters
    → new matcher function needed or can be fixed in tagged union matcher
    ✔ optional discriminant (`{ type?: "x" }`) is the same hole: the boolean/nullish change now admits the `undefined` tag, so the factory accepts the key, but `Extract<T, Record<K, V>>` still passes `never` to both the `x` and `undefined` handlers @done
 Documentation:
 ☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
    → previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
    → previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
 ☐ Create `examples/` directory with runnable snippets
 ☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
 ☐ Write migration guide for users coming from discriminated unions
 ☐ Create backlog tasks for implementation
 ☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API
 Maintenance:
 ☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low
    ☐ Explore serving coverage for non-tag pushes (e.g. `main/coverage`, PR previews) @low
    → design: no deploy step in CI; the webserver just exposes the shared directory (decided over Gitea Pages / Codecov — neither confirmed available/ wanted)
 ☐ serve docs over self hosted server @low
    ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving docs (reuse existing reverse proxy)
    ☐ CI writes docs to a shared volume keyed by project + tag (e.g. `/docs/tiny-pattern-ts/<tag>/`)
    ☐ Browse to `…/docs/<repo>/<tag>/index.html` in the browser
 ☐ serve landing page over self hosted server @low
    ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving landing page (reuse existing reverse proxy)
    ☐ CI writes landing page to a shared volume keyed by project + tag (e.g. `/landing/tiny-pattern-ts/<tag>/`)
    ☐ Browse to `…/tiny-pattern-ts/index.html` in the browser
@@ -0,0 +1,23 @@
 # If applied, this commit will... (Max 50 char)
 # Explain why this change is being made (Max 72 Char) [WHAT and WHY vs HOW]
 # Provide links or keys to any relevant tickets, articles or other resources
 Resolves #...
 # --- COMMIT END ---
 # Remember to
 # Use the imperative mood in the subject line
 # Capitalize the subject line
 # Do not end the subject line with a period
 # Separate subject from body with a blank line
 # Use the body to explain what and why vs. how
 # Can use multiple lines with "-" for bullet points in body
@@ -1,6 +1,51 @@
 {
    "version": "0.2",
    "language": "en",
-    "words": ["tslib", "typefest", "lefthook"],
+    "words": [
-    "ignorePaths": ["dist", "node_modules", "public", "coverage", "*.svg"]
+        "lefthook",
        "oxlint",
        "oxfmt",
        "oxc",
        "nodenext",
        "oxfmtrc",
        "oxlintrc",
        "EDITMSG",
        "typescriptteam",
        "gitmoji",
        "dbaeumer",
        "msvc",
        "publint",
        "attw",
        "arethetypeswrong",
        "knip",
        "tsgolint",
        "tsgo",
        "tsserver",
        "gitea",
        "lipanski",
        "pubv",
        "knope",
        "runwisp",
        "glab",
        "hostedtoolcache",
        "nodebase",
        "frontends",
        "catthehacker",
        "nsnull",
        "dedup",
        "dedupe",
        "repoint",
        "postversion",
        "prebuild",
        "Zilla",
        "kacl",
        "bestikk",
        "silverwind",
        "idris",
        "todotasks",
        "connor",
        "injective",
        "injectivity"
    ],
    "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }
@@ -0,0 +1,81 @@
 # Development documentation
 Why this project works the way it does: the decisions, what was rejected, and
 the shortcomings and known issues we carry. Written for maintainers and
 contributors.
 The actionable rules — setup, running, testing, submitting — live in
 [CONTRIBUTING.md](../CONTRIBUTING.md). **Each fact is written once**: the rule
 there, the reason here; neither restates the other, and where a fact is useful
 in both they link. Read the relevant file before changing an area, and when a
 rule changes update its rationale here in the same commit.
 User-facing documentation is [README.md](../README.md). `docs/` is deliberately
 unused: that name is reserved for the future user documentation site, and
 deploying it is out of scope. These files are not part of that site.
 ## Layout
 One file per category:
 | File                             | Covers                                                                  |
 | -------------------------------- | ----------------------------------------------------------------------- |
 | [library.md](./library.md)       | Public API design, the type-level contract, and its limitations         |
 | [workflow.md](./workflow.md)     | Branching and merging, script prefixes, feedback tiers, commit messages |
 | [tooling.md](./tooling.md)       | Toolchain choices and configuration, editor setup                       |
 | [testing.md](./testing.md)       | Test strategy and type-driven development                               |
 | [ci.md](./ci.md)                 | CI pipeline, runner image, coverage serving                             |
 | [publishing.md](./publishing.md) | Release and npm publishing                                              |
 We start with one file per category so each area stays small enough to hold in
 mind; a category that outgrows it becomes a folder with an index, and the links
 in CONTRIBUTING.md and README.md point at the category, not a single decision.
 ## Decision blocks
 Record every non-obvious choice as a block in the relevant category file:
 ```md
 ## Runner image
 #### Decision (2026-09)
 Bake Node into the CI job image at the setup-node tool-cache layout instead
 of downloading per job.
 #### Why
 - ...
 #### Rejected
 - Gitea Pages / per-job download
 - force-pull
 #### Known issue
 - a Dockerfile-only change re-pushed under an unchanged tag is invisible to the runner
    - recover with `docker rmi <image>`
 ```
 - The date is the month the decision was made, not when the file was edited —
  the anchor for "current" versus "was current once".
 - `Rejected` stops the project re-litigating the same alternatives; an empty one
  usually means they were never written down.
 - `Known issue` is where shortcomings live. A caveat not tied to one decision
  goes under a `## Known issues` section at the end of the file.
 - Replace a superseded decision in place rather than archiving it; git history
  is the archive.
 - Terse is the point: humans skim and agents imitate the style already in the
  file, so verbosity compounds edit over edit. Grammar loses to density here on
  purpose.
 ## Adding to these docs
 1. Pick the category: `library`, `workflow`, `tooling`, `testing`, `ci`,
   `publishing`.
 2. Add or update a decision block; keep existing text unless the decision
   changed.
 3. If an actionable rule changes, update
   [CONTRIBUTING.md](../CONTRIBUTING.md) in the same commit and cross-link.
   Never change a rule there without updating its rationale here.
@@ -0,0 +1,136 @@
 # CI
 [.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml) is the source of truth for
 the job graph; this file records why it is shaped the way it is.
 ## Pipeline
 - **`build`** (push to `main` / tag) — build + correctness + packaging.
 - **`maintain`** (push to `main`, non-blocking) — `npm run maintain`; reports,
  never fails the build.
 - **`publish`** (tag) — packaging checks + `publish:publint` / `publish:attw`,
  then the Gitea release page and `npm publish` (see
  [publishing.md](./publishing.md)).
 - **`release-gate`** — on a `:rocket: Release x.y.z` commit it skips
  `build`/`maintain`, because `create:release` pushes the tag for the same commit
  right after and the tag run is authoritative. It uses no Node and stays on the
  default image.
 ## Runner image
 #### Decision (2026-09)
 `build` / `maintain` / `publish` run in `gitea.e1nsnull.de/tmu/act-ci:<version>`
 ([docker/Dockerfile](../docker/Dockerfile)): the default act image with Node
 overlaid at the exact `/opt/hostedtoolcache` layout `actions/setup-node` probes.
 #### Why
 - No job pays the ~50 MB Node fetch, because the probe hits the baked entry.
 - The tag must equal the exact [.node-version](../.node-version) pin, and the
  image is rebuilt only as part of a Node bump — there is no other trigger.
 - Building needs a docker daemon and registry credentials, so it belongs to no
  feedback tier. That is why it is **not** an `npm run` script: no
  [prefix](./workflow.md#script-prefix-convention) fits, and that is the signal.
 #### Rejected
 - Downloading Node in every job — the ~50 MB fetch was the original problem.
 - Caching Proxy (Squid or similar) — adds complexity to global setup
 - Mounting the tool cache - No invalidation will fill the cache with stale versions
 ## Bumping Node
 Bumping Node is one coordinated change, committed as a unit:
 1. Edit [.node-version](../.node-version) to the exact `x.y.z` — floats like `26`
   resolve to the latest patch at runtime and bust the baked entry, so
   [scripts/runner-image.sh](../scripts/runner-image.sh) refuses them.
 2. `docker login gitea.e1nsnull.de` (user + package/access token), then
   `./scripts/runner-image.sh --push`, which reads the version and pushes
   `<IMAGE_REPO>:<version>`.
 3. Repoint the three `container.image` tags in
   [.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml) to that version.
 Skipping step 2 fails CI at image pull; skipping step 3 silently reverts to the
 per-job download.
 ## Image invariants
 For the `setup-node` probe to hit, two things must hold — both easy to break:
 ### The `x64.complete` marker
 #### Decision (2026-09)
 Bake a `<version>/<arch>.complete` marker next to the Node directory.
 #### Why
 - `actions/tool-cache` accepts a cached tool only when
  `<version>/<arch>.complete` exists beside it (`tc.find()` checks). A bare
  `node/<version>/x64/` is ignored and the download happens anyway. See the
  comment in [docker/Dockerfile](../docker/Dockerfile).
 ### Tag freshness, with force-pull deliberately off
 #### Decision (2026-09)
 Leave `act_runner`'s `force_pull` disabled.
 #### Why
 - The tag encodes only the Node version, and the image is rebuilt only when that
  changes — so the normal flow always yields a new tag and the runner pulls it.
 - Forcing a pull re-pulls the image on every job for no benefit.
 #### Rejected
 - Enabling `force_pull`: it is acceptable to miss a runner-side image change,
  and a `Dockerfile`-only change is not worth a per-job pull.
 #### Known issue
 - A `Dockerfile`-only change (like the marker above) re-pushed under an
  unchanged tag is invisible to the runner, which keeps the old image while the
  registry shows the new digest. Remove the stale tag on the runner host
  (`docker rmi gitea.e1nsnull.de/tmu/act-ci:<version>`); do not reach for
  force-pull.
 ## Coverage serving
 #### Decision (2026-09)
 Serve CI coverage from a shared directory on the runner, with no deploy step in
 CI.
 #### Why
 - The webserver exposes the shared directory and the Gitea docker setup reuses
  the existing reverse proxy — no upload artifact, no external service.
 - Coverage is written to a shared volume keyed by project and tag (for example
  `/docs/tiny-pattern-ts/<tag>/`).
 #### Rejected
 - Gitea Pages and Codecov: neither was confirmed available or wanted.
 #### Known issue
 - Coverage is served for tag pushes only; non-tag pushes (for example
  `main/coverage`) are tracked separately.
 [scripts/precompress.ts](../scripts/precompress.ts) emits `.br` / `.gz` / `.zst`
 sidecars next to text assets. The Gitea pages service (`static-web-server` with
 `SERVER_COMPRESSION_STATIC=true`) serves the sidecar matching `Accept-Encoding`
 and falls back to the original.
 #### Decision (2026-09)
 Precompress into sidecars rather than per request.
 #### Why
 - The assets are static and change only on deploy, so the work is paid once.
 - Images, fonts and archives are already compressed; a sidecar would only grow
  them, so only text extensions are emitted.
@@ -0,0 +1,275 @@
 # Library design
 The type-level design of the public API and the limitations it carries. The
 user-facing reference is [README § API](../README.md#api).
 The matchers are implemented in `src/primitive-union.ts` (`getPrimitiveUnionMatcher` /
 `getPrimitiveUnionMatcherW`) and `src/tagged-union.ts` (`getTaggedUnionMatcher` /
 `getTaggedUnionMatcherW`), re-exported from `src/index.ts`; the rest of the
 library is placeholder code.
 ## Matcher shape
 #### Decision (2026-09)
 A factory takes the universe and returns a builder; the builder takes a handler
 map and an optional fallback:
 ```ts
 const matcher = getPrimitiveUnionMatcher<"a" | "b">()({ a: (s) => …, b: (s) => … });
 const fallback = getPrimitiveUnionMatcher<"a" | "b" | "c">()({ a: (s) => … }, (s) => …);
 ```
 Exhaustive or fallback is decided **at the call site**, by whether the second
 argument is present. The fallback's parameter is the remainder
 `Exclude<T, keyof Handled>`. Only the return-strictness axis remains, so there
 are two factories:
 - `getPrimitiveUnionMatcher` — one common `R`; the fallback must fit it;
 - `getPrimitiveUnionMatcherW` — the union `PatternReturns<Handled> | R`.
 Each factory is two overloads whose order is load-bearing:
 1. `Handlers<T, R>` — the exhaustive form, and the contextual type of the
   handler-map popup;
 2. `Handled extends Exact<Partial<Handlers<T, R>>, Handled>` intersected with
   `MustBePartial<T, Handled>`, plus `Fallback<T, Handled, R>` — a partial
   handler map plus the fallback, rejected when the map already covers `T`.
 #### Why
 - **The fallback is an argument, not a property.** TypeScript fixes a property's
  contextual type before it infers its sibling keys, so `_: (s) => …` in the
  handler map can only see all of `T`, never `Exclude<T, keyof Handled>`. A later
  argument is contextually typed from inference on an earlier one, so the split
  is what makes the remainder expressible.
 - **The redundant-fallback guard is an F-bounded constraint.** A map that
  already covers `T` plus a fallback is rejected by folding
  `MustBePartial<T, Handled>` into `Handled`'s own constraint. The guard is
  checked _after_ `Handled` is inferred, so the contextual pass that types the
  handler callbacks survives. The obvious conditional
  `Exclude<T, keyof Handled> extends never ? …` in the fallback's parameter
  type is evaluated while `Handled` is still its constraint and rejects every
  partial map whose callbacks are context-sensitive.
 - **Overload order keeps both messages.** #1 supplies the contextual type
  (`a, b, c`); #2 accepts a partial map once a fallback is present, so its popup
  is optional (`a?, b?, c?`). A gap without a fallback is reported against #1.
 - **`R` needs an inference site.** `R` inside the `Exact<…>` constraint is not
  one, so `handlers: Handled & Partial<Handlers<T, R>>` re-adds it; without that
  `R` collapses to `unknown` when the handler params are inferred.
 - **`Exact` restores the excess-property check.** TypeScript skips it for a
  generic constraint, so without `Exact` the handler map accepts keys outside
  `T`.
 - Two factories, not four: the fallback is an argument, not a separate API.
 #### Rejected
 - **Single-object `_`** (the former shape). `_` sees only all of `T`; the
  remainder is not expressible there, and an exhaustive map plus `_` was
  accepted.
 - **Curried handlers-first** — `(handlers)(fallback)`. Rejected: two calls for
  the common case. It is not needed for the redundant-fallback guard, which the
  F-bounded constraint already provides (see Why).
 - **`this` / HKT self-reference.** `this` is post-construction (method bodies,
  return positions); a parameter's contextual type is pre-construction.
  `keyof this` in an interface method is the interface, not the literal.
 - **Variance / `const` type parameters / `NoInfer` / `unique symbol` brands /
  defaulted type-param guards.** None change inference or evaluation order;
  `in`/`out` on the handler map broke contextual typing outright. `NoInfer`
  specifically leaks into the emitted `.d.ts`, raising the consumer floor to
  TypeScript 5.4 (README promises `>= 5.0`).
 - **Union merge**, **overload merge with only the exhaustive arm last**,
  **inferred universe**, **conditional `RequireKeys`**, **cases-first curried** —
  decided against while the API was single-object; their reasons (reported
  near-miss member, no `_` in the exhaustive popup, `NoInfer`/floor, `keyof P`
  counts optional keys, not pipe-friendly) hold where they still apply.
 #### Known issue
 - `PatternReturns` must be
  `ReturnType<Extract<ValueOf<P>, (...args: never[]) => unknown>>` so it survives
  the closed, partly-optional `P` constraints.
 - `Parameters<typeof factory>[0]` resolves only the **last** overload, so it is
  not a sound "rejected" oracle for a factory. Factory-negative tests use
  `@ts-expect-error` call sites (the test file only — the general ban stands).
 ## Shared internals
 #### Decision (2026-09)
 `src/matcher-shared.ts` holds the universe-agnostic pieces both matchers use:
 `UnaryFn`, `PatternReturns`, `RedundantFallback`, `HandlerMap`, the shared
 `Matchable` universe, the `PatternKey` key projection and its `Member` inverse,
 and the `Stringified` / `Collisions` / `UnsupportedReason` / `UnsupportedUniverse`
 / `UniverseGate` universe gate.
 #### Why
 - `RedundantFallback`'s property name is the diagnostic, so one definition
  keeps the two matchers' message from drifting; the other pieces appear
  verbatim in both public signatures or are the same projection over each
  matcher's universe.
 - **`Matchable` is one definition, not two.** The primitive-union matcher's
  universe and the tagged-union matcher's allowed `Tag` values are the same set,
  so aliasing them keeps the two matchers from drifting apart on what they
  accept (`symbol`/`bigint` rejected once).
 #### Rejected
 - **A generic `Matcher<Universe>` over the interface pair, `Handlers`,
  `Fallback` and `MustBePartial`.** Each is built from its own universe
  (`Tags`/`MapTaggedUnion` vs the primitive values); abstracting over the
  F-bounded `Handled` constraint that makes the remainder work risks the
  contextual typing it exists to preserve. `Matchable`, the `PatternKey` /
  `Member` projection and the `UniverseGate` are the pieces both universes
  genuinely share.
 ## Supported universes
 #### Decision (2026-09)
 A universe must be a **finite union of literals** with **no
 value/stringification collision**. Broad types (`string`, `number`, a template
 literal) and `"true" | true` / `1 | "1"` are rejected; the factory intersects
 `UniverseGate<T>` (the `UnsupportedUniverse<Reason>` diagnostic) into the
 handler and fallback parameters. `Member<T, K>` replaces the `PatternParam<K>`
 inversion: the handler parameter is the member(s) of `T` whose `PatternKey` is
 `K`, so a standalone `"true"` is `"true"`, not `true`.
 #### Why
 - **`PatternKey` is not injective.** `"true"` and `true` (and `1` / `"1"`)
  share a runtime key, so `PatternParam<K>` cannot recover the member.
  `Member<T, K>` inverts against `T`, which is exact.
 - **Broad types cannot be proven exhaustive.** An index-like map lets a partial
  object satisfy the exhaustive overload and reaches the `dispatch` throw.
  Rejecting at the boundary avoids threading an open/closed branch through
  `Handlers`, `Fallback` and `MustBePartial`.
 - **The finite-literal predicate is `IsLiteral<PatternKey<T>> extends true`.**
  `IsLiteral` is `boolean` for a union that mixes a literal with a broad type
  (`"a" | \`x-${number}\``), so `extends false`would treat the mix as
 supported;`extends true` is the check that rejects it.
 - **Collisions are rejected, not merged.** `Member<T, K>` would be sound (the
  handler gets the union), but the API is one handler per member; rejecting
  keeps `Member` a singleton and the remainder exact.
 - **The collision predicate is type-checkable.** `Collisions<T> =
 Extract<T, Stringified<T>>` catches numeric collisions too.
 - **The gate is an intersection, not a branch,** so `R` inference and the popup
  survive; a conditional parameter type would not.
 #### Rejected
 - **Open universes with a required fallback** (`fix/open-universe-*`): sound,
  but left the collision hole and added an `IsLiteral` /
  `OpenUniverseNeedsFallback` branch through every handler type. Findings, kept
  so they are not re-run: `{}` satisfies an index signature (and `Exact` misses
  it); an index signature dominates contextual typing; `R` infers only from a
  non-self-referential parameter type (`{ [K in keyof H]: … R … }` gives
  `unknown`); an F-bounded guard referencing `keyof Handled` in `Handled`'s own
  constraint sees the constraint, not the map; all handlers share one `R` (only
  the fallback widens it); `IsLiteral` is the finite-literal predicate.
 - **`Member<T, K>` without the gate:** sound, but a colliding handler gets a
  union and `1 | "1"` stays one runtime key.
 - **A round-trip injectivity gate** (`IsEqual<T, PatternParam<PatternKey<T>>>`):
  over-rejects standalone `"true"` / `"false"` / `"null"` / `"undefined"`.
 - **A case-list / ts-pattern builder:** removes the collision class but drops
  the object map (footprint, popup) and reimplements an existing library.
 - **Normalize numeric keys to strings:** makes `PatternKey` injective but
  changes "numeric keys stay numbers" and defeats the numeric dispatch fast
  path.
 #### Known issue
 - A multi-collision universe lists every collision in the diagnostic.
 - The `dispatch` throw is unreachable through the typed API; the throw tests
  widen the factory to `Function` to reach it.
 ## Tagged-union matcher
 #### Decision (2026-09)
 `getTaggedUnionMatcher` / `getTaggedUnionMatcherW` mirror the primitive-union pair
 with one extra curried step for the discriminant key:
 ```ts
 type Shape =
    | { kind: "circle"; radius: number }
    | { kind: "square"; side: number };
 const area = getTaggedUnionMatcher<Shape>()("kind")({
    circle: (s) => Math.PI * s.radius ** 2,
    square: (s) => s.side ** 2,
 });
 const fallback = getTaggedUnionMatcher<Shape>()("kind")(
    { circle: (s) => … },
    (s) => …, // s: { kind: "square"; side: number }
 );
 ```
 The key is a separate call because `K` is inferred from its literal argument and
 `T` is fixed by the first factory; one call could not infer both.
 `Discriminated<T>` restricts the key to properties whose values are tags.
 #### Why
 - **Same fallback/remainder machinery as the primitive-union matcher.** `HandledTags`
  recovers the tag values the map handled (`Member<Tags, keyof Handled>`) and
  `Narrowed<T, K, Exclude<Tags, …>>` is the fallback's parameter; the
  redundant-fallback guard is the same F-bounded constraint. Only the "universe"
  changes — `T`'s members instead of primitive values.
 - **`T extends object`, not `Record<PropertyKey, unknown>`.** An `interface` has
  no implicit index signature, so the `Record` constraint would reject
  interface-based unions. The runtime reads the tag off `object` with one
  assertion, the tagged twin of the primitive-union dispatch's `shape as string | number`.
 - **`Narrowed` distributes over `T`, narrowing `K` to the tag.** A member whose
  `K` cannot take the tag drops out; a duplicated tag yields a union of members
  instead of dropping one. `T[K] extends V` returns the exact member (a
  discriminated union's declared interface) untouched, so the mapped form only
  handles a property that is itself a union.
 - **A union-valued or optional discriminant is supported.** A single shape whose
  property is a union (`{ color: "red" | "green" | "blue" }`) is narrowed per
  handler instead of being passed `never`. Matching a defined tag on an optional
  property (`{ type?: "x" }`) proves the key is present, so it becomes required
  (`{ type: "x" }`); the `undefined` tag narrows it to `{ type?: never }` under
  `exactOptionalPropertyTypes` (absence) or `{ type?: undefined }` when the
  property explicitly admits `undefined`.
 - **A `boolean` / `null` / `undefined` tag goes through the shared
  `PatternKey` / `Member` projection.** `Discriminated` admits those tags
  (they are in `Tag`), but they cannot key a mapped type, so the handler map is
  keyed by the stringified form (`true` → `"true"`) and `Member` inverts it
  against the tag set to recover the member. This is the same projection the
  primitive-union matcher uses over its universe, which is why it lives in
  `matcher-shared.ts`.
 #### Known issue
 - A member's tag must be unique across the union; two members with the same tag
  collapse to a union under one handler. A tag colliding with its
  stringification (`true | "true"`) is rejected by the universe gate — see
  § Supported universes.
 ## Primitive universe
 #### Decision (2026-09)
 The universe (`Matchable`) is `string | number | boolean | null | undefined`,
 with `boolean` admitted as `true | false`.
 `boolean`/`null`/`undefined` are not property keys, so handler-map keys are a
 projection (`PatternKey`: each member stringified) and `Member` inverts it
 against the universe, so callbacks receive the real member (`true`, not
 `"true"`; the standalone string `"true"` stays `"true"`). The popup offers
 `true`, `false`, `null`, `undefined` by name (verified over LSP). The same
 projection is shared with the tagged-union matcher; see § Tagged-union matcher.
 The supported universes are constrained as described in § Supported universes.
 #### Why
 - Runtime dispatch indexes with the raw `shape`; `handlers[true]` coerces to
  `"true"` at runtime exactly as `String` would. The `shape as string | number`
  assertion only placates `TS2538` and buys the number fast path (an explicit
  `String()` defeats V8's numeric-key path: measured ~2× on number-keyed
  dispatch).
 - `symbol`/`bigint`/`NaN`/`-0` are rejected, and a member colliding with its
  stringification is rejected by the gate: user-facing, stated once in
  [README § Caveats](../README.md#caveats).
@@ -0,0 +1,131 @@
 # Publishing
 Publishing is CI-only: local `npm publish` is not supported, and the maintainer
 triggers releases from `main`. The mechanics are in
 [scripts/release.sh](../scripts/release.sh) and
 [scripts/release-notes.sh](../scripts/release-notes.sh); the job graph is
 [.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml).
 ## Release steps
 1. All intended changes are merged to `main` and passing CI.
 2. The maintainer runs `npm run create:release`. VS Code opens
   [CHANGELOG.md](../CHANGELOG.md) to finalize the `[Unreleased]` notes; because
   pubv refuses a dirty tree, the edit is committed first (then folded into the
   release commit), and pubv suggests a version from those notes to confirm or
   edit.
 3. `scripts/release.sh` creates one release commit (graduated changelog +
   `package.json` bump, amended together), tags it, and pushes.
 4. CI fires on both pushes. `publish` runs on the tag (build + publish checks +
   release page + `npm publish`), while `release-gate` recognizes the release
   commit and skips `build`/`maintain`: the tag verifies the identical SHA, so no
   work is duplicated. The publish checks pass before the artifact is published,
   and the release page is created from the matching Keep-a-Changelog section
   _before_ `npm publish`, so a broken page fails CI without consuming a version
   and `npm publish` stays the last step.
 ## CI-only publishing
 #### Decision (2026-09)
 Releases are cut by CI from `main`; there is no local `npm publish` and no
 `publish:*` script in the `check` chain.
 #### Why
 - The tag is the artifact marker: CI verifies the exact commit it points at, so
  a local publish could ship something the tag does not describe.
 - `publish:publint` / `publish:attw` validate the _publishable artifact_, which
  needs a fresh build; they are not source-correctness checks and do not belong
  in `check`.
 ## The release commit is assembled from two tools
 #### Decision (2026-09)
 `create:release` uses `pubv` for the changelog graduation and bump heuristic,
 then `npm version` for the `package.json` + lockfile bump, amended into a single
 release commit.
 #### Why
 - We want hand-written Keep-a-Changelog notes, an `[Unreleased]` ->
  `## [x.y.z] - DATE` graduation, and a tag on the exact commit that gets
  published — and no single tool did both the graduation and the `package.json`
  bump.
 - Split by strength: `pubv` (tiny, changelog-driven) owns preflight, the
  interactive major/minor/patch heuristic, and graduating and committing
  `CHANGELOG.md` (no tag, no push); `npm version` syncs `package.json` + the
  lockfile; `--amend` folds them into one commit; the tag is created _after_ the
  amend so it is never orphaned.
 - The notes are finalized _before_ pubv because its bump heuristic reads the
  `[Unreleased]` body — editing afterwards would inform the changelog only, not
  the version. The staging commit that satisfies pubv's clean-tree check is
  folded back into the single release commit.
 #### Rejected
 - The conventional-commits family: the history is gitmoji, not Conventional, and
  the notes are hand-written (see
  [workflow.md § Commit messages](./workflow.md#commit-messages)).
 - `changesets` / `rtk`: config plus a heavier flow that fights the CI-only
  publish.
 - `knope` / `kacl` / `bestikk`: changelog-only (no `package.json` bump) and
  5-year / 2-year / brand-new maintenance.
 - `pubv` alone: it never writes `package.json`.
 - `versions` (silverwind): good Gitea support, but pairing it with a hand-rolled
  promote became a ~180-line script, which this ~30-line version replaces.
 ## The version has one source of truth
 #### Decision (2026-09)
 The version is derived from the graduated `## [x.y.z]` heading in
 [CHANGELOG.md](../CHANGELOG.md) and written to `package.json` +
 `package-lock.json` by `npm version`.
 #### Why
 - `release.sh` reads the version from the changelog, so the changelog is the
  input and `package.json` the derived copy — one direction, no drift.
 #### Rejected
 - A `## Version` line in the README: it makes `release.sh` responsible for a
  third file.
 - Linking `package.json` from the README: it invites a hand-maintained duplicate
  the link does not keep in sync.
 ## Release notes are extracted from the changelog
 #### Decision (2026-09)
 `scripts/release-notes.sh <tag>` prints the Keep-a-Changelog section for the tag
 and exits non-zero when it is missing.
 #### Why
 - CI reuses the release body from the same file that drove the version, so the
  page and the changelog cannot disagree.
 - Failing on a missing section means a release can never publish an empty body.
  A leading `v` is tolerated so both `v1.2.3` and `1.2.3` match `## [1.2.3]`.
 ## Token gates
 #### Decision (2026-09)
 The Gitea release page uses the run's automatic token (`github.token`).
 `npm publish` is gated on `NPM_TOKEN`, lifted into job-level `env`. A final
 `always()` step fails the job unless both halves reported `success`.
 #### Why
 - The automatic token needs only `contents: write`, so the release page needs no
  secret gate.
 - `secrets` is not allowed in a step `if`, so `NPM_TOKEN` must be lifted into
  job-level `env`; an unset secret then skips the publish instead of attempting
  an unauthenticated one.
 - A tag is all-or-nothing: without the `always()` guard a skipped or failed npm
  half would leave the job silently green. The guard turns it red.
 Set `NPM_TOKEN` (npm publish rights) under Settings -> Actions -> Secrets.
@@ -0,0 +1,213 @@
 # Testing
 For this library the types _are_ the feature, so a runtime-only test loop would
 verify the wrong thing. The commands are in
 [CONTRIBUTING.md](../CONTRIBUTING.md); this file records why the loop is shaped
 the way it is.
 ## Type-driven development
 The rules — the loop and the pairing rule — are in
 [CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
 What follows is why and what was rejected.
 #### Decision (2026-09)
 The compile-time expectation is written before the runtime assertion, and both
 before the implementation.
 #### Why
 - A runtime-only test can pass while the type is wrong, so a type-level library
  would ship a broken feature its tests bless.
 - The type error is a more precise spec than a failing assertion, because it
  states the exact expected type before the logic exists.
 #### Rejected
 - Runtime-first (classic red/green): it verifies the value, not the contract,
  and the contract is the product.
 - Testing the type only: it would not catch handler dispatch or the `_`
  fallback (see `src/primitive-union.test.ts`).
 The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are
 in
 [CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
 `c8` uses V8 coverage, so the `--strip-types` source is instrumented without a
 build step, and the runner relies on the `.ts` import-extension convention (see
 [tooling.md](./tooling.md#source-imports-use-ts-extensions)).
 ## Handler arguments
 #### Decision (2026-09)
 A handler's `expectTypeOf(shape)` is always paired with an assertion on the
 argument `dispatch` actually passed: `assert.equal` where the handler runs for
 one shape, `assert.ok(s === … || s === …)` over the set a `_` fallback accepts
 (`assert` is imported as `strict`, so each comparison is `Object.is`). Where a
 test should also prove that the _exact_ value reached the handler unchanged,
 the fallback returns the shape verbatim and the call site asserts it.
 #### Why
 - The parameter's type is what the compiler inferred from the pattern; the
  argument is what the runtime passed. Only the second can drift, and the keys
  whose property name differs from their value (`true`, `null`, `1`) are
  exactly where it can — see [library.md](./library.md).
 - `String(shape)` at the call site keeps every type expectation and every
  return-value assertion green; the argument assertions fail (10 of the 33
  tests). Without them the suite never looks at the passed argument.
 - Returning the shape verbatim costs a widening pattern nothing: the remainder
  type joins the union of handler returns in place of a marker literal, so the
  test still shows the widening it is named for.
 #### Rejected
 - A recorded `unknown[]` of every fallback call compared with `deepEqual`:
  strong, but it couples the assertion to call order, and the sink sits three
  blocks away from the value it observes.
 - `typeof` checks: they cannot separate `2` from its key text `"2"`, which is
  the drift a fallback with a numeric remainder can hit.
 - One expected value asserted inline in a fallback: its argument is a _set_ of
  shapes, so only the disjunction holds on every call.
 ## AAA ordering
 The rule is in
 [CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
 #### Decision (2026-09)
 Test bodies read arrange → act → assert: inputs (the factory) set up first, the
 subject exercised once from them, all checks last — types then runtime. The
 blocks are labeled with `// Arrange` / `// Act` / `// Assert` comments and
 separated by a blank line; an empty block drops its label.
 #### Why
 - Interleaved setup/checks hide what runs vs. what is observed; the eye
  re-reads the block to find the seams.
 - A factory built mid-test invites a second throwaway call of the subject;
  arranging it once makes the positive construction and the negative
  `Parameters<…>` check share one source of truth.
 - Labels make the seams explicit, not inferred — grep-able and reviewable
  without reading the statements.
 #### Rejected
 - Unlabeled ordering (bare blank lines): the seams still have to be found by
  reading; the labels cost nothing.
 ## Test helpers
 The rule is enforced by `import/no-relative-parent-imports`; this section records
 why the mechanism is shaped like this.
 #### Decision (2026-09)
 A shared test helper — code that scattered `*.test.ts` files import to do their
 testing — lives under `src/util/__tests__/` and is addressed by the
 `#test-utils/…` self-reference (`package.json#imports`:
 `"#test-utils/*": "./src/util/__tests__/*"`), never by a relative path:
 ```ts
 import { LspSession } from "#test-utils/lsp-completion.ts";
 ```
 #### Why
 - The lint rule bans upward (`../`) imports, and a cross-cutting helper can
  always be placed above _some_ scattered consumer, wherever it goes. Name
  beats path: a `#test-utils/…` specifier has no direction, so the rule never
  fires and file moves only touch the one mapping in `package.json`.
 - `#…` is Node's reserved prefix for _private_ subpath imports: publishing
  `package.json` leaks nothing and resolves nothing for consumers.
 - `__tests__` as the folder name is not about tests living there; it is the
  directory pattern `tsconfig.build.json` already excludes, so a helper can
  never be emitted into `dist/` and shipped by accident.
 - Node's own resolver handles `#…` under `--strip-types`, and `tsc` resolves it
  via the same `imports` field — one mechanism for runtime and type gate, no
  loader needed.
 - The helper uses `node:` builtins (it drives a language server), so
  `import/no-nodejs-modules` is off for `src/util/__tests__/**` in
  `.oxlintrc.json` — the same exception the `scripts/**` scope carries.
 - Helpers carry no library coupling: their tests probe in-memory documents
  whose contextual types are written inline, so only the helper's own contract
  (marker handling, position, label extraction) is under test. A test that
  asserts a _matcher's_ popup belongs with the matcher.
 #### Rejected
 - A helper beside the tests (`src/util/test.ts`, flat `src/`): composes only
  while `src/` stays flat; the first nested test reaching it reintroduces the
  banned upward import.
 - Bare `~/…` specifier: not valid in `imports` (keys must start with `#`) —
  resolution fails at runtime with `ERR_MODULE_NOT_FOUND`. A `#~/…` “home”
  shorthand was dropped in review; `#test-utils/…` states what it is.
 - tsconfig `paths` alias: resolves for `tsc` but not for plain
  `node --test --strip-types` (no loader hook), breaking the fast tier.
 - Turning `import/no-relative-parent-imports` off for test files: the rule
  still guards non-test helpers importing each other, and the exemption is
  only needed for the one specifier the mapping already solves cleanly.
 ## Autocomplete
 #### Decision (2026-09)
 Completion is verified by driving the repo's own language server
 (`tsc --lsp --stdio`, the same server pi's LSP extension talks to) through
 the test helper `#test-utils/lsp-completion.ts`
 (`src/util/__tests__/lsp-completion.ts`), not through the type system:
 ```sh
 node --strip-types src/util/__tests__/lsp-completion.ts <file> [<marker>]
 ```
 The script prints the labels the server offers at a `/*COMPLETE*/` marker inside
 `<file>` (the marker is stripped before the document is sent). Its `LspSession`
 is imported by `src/util/__tests__/lsp-completion.test.ts` — which tests the
 helper itself against inline documents, never the library's code — and by
 `src/primitive-union.test.ts`, where the same probe asserts the matcher's popup;
 the CLI is for manual inspection.
 #### Why
 - Completion is a contextual-type property: it depends on which overload
  signature TypeScript picks for the object literal, and no type-level assertion
  observes that.
 - `Parameters<typeof factory>[0]` resolves only the _last_ overload, so it is
  not the popup's contextual type either — see
  [library.md § Matcher shape](./library.md#matcher-shape).
 - The server is the only ground truth; the script reproduces what the editor
  shows.
 #### Rejected
 - **`expect-type` would not work**: there is no operator for “the popup offers
  these labels”. `toExtend` / `toEqualTypeOf` test assignability and cannot say
  which overload supplied the contextual type.
 - **Checking by hand in the editor**: not reproducible in review or by an agent.
 - **`@ts-expect-error` at a completion position**: it asserts the absence of a
  compile error, not the presence of specific labels.
 #### Known issue
 - Each test spawns its own `tsc` server so the tests share no state and pass in
  any order; the file is an integration test (~1.6 s) that needs `node_modules`.
  `didOpen` is handled in order before the completion request, so no settle
  delay is needed.
 - The server answers some requests with a string id (`client/registerCapability`);
  the client must tolerate `string | number` ids or the server stalls.
 - `LspSession.close()` sends `shutdown` and then closes stdin instead of
  sending `exit`. The TS 7 Go server's `handleExit` returns `io.EOF`, cancelling
  the background context while a watch update is still in flight, and logs a
  bare `context canceled` before exiting 1; EOF on stdin exits 0 with no output.
  The kill stays as a fallback for a server that does not exit.
 ## Known issues
 - The type-aware linter misidentifies `expectTypeOf()` as a floating promise.
  It is a known false positive, so `typescript/no-floating-promises` is off for
  `**/*.test.ts` in the `.oxlintrc.json` override rather than repeated as a
  file-level header (see
  [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).
@@ -0,0 +1,345 @@
 # Tooling
 Every tool below was chosen and configured deliberately. The commands a
 contributor runs are in [CONTRIBUTING.md](../CONTRIBUTING.md) and the versions
 in [package.json](../package.json).
 ## Tool inventory
 - **TypeScript 7** — type checker and build (`tsc`).
 - **node --test** + `--strip-types` — test runner.
 - **c8** — coverage for `test:ci`.
 - **oxlint** — Rust linter, type-aware via **oxlint-tsgolint** (typescript-go).
 - **oxfmt** — Rust formatter (Prettier-compatible) for JS/TS, JSON/JSONC, YAML,
  Markdown, MDX, and more; its `package.json` key sorting replaces
  `sort-package-json`.
 - **cspell** — spell checking.
 - **knip** — unused dependencies, exports, and files.
 - **check-outdated** — dependencies behind the registry; exits non-zero when any
  is outdated.
 - **publint** — validates `package.json` for ESM publishing.
 - **@arethetypeswrong/cli** (`attw`) — validates `.d.ts` against module-resolution
  scenarios.
 - **lefthook** — git hooks.
 - **@spences10/pi-lsp** — read-only LSP code intelligence for AI agents
  (project-local `.pi/settings.json`); talks to this repo's TypeScript 7 via
  `tsc --lsp --stdio`.
 - **vscode-languageserver-protocol** — LSP client and protocol types for the
  autocomplete test helper (`src/util/__tests__/lsp-completion.ts`).
 When each runs is in
 [CONTRIBUTING.md § Feedback tiers](../CONTRIBUTING.md#feedback-tiers).
 ## TypeScript and build
 ### One type-check config, one emit config
 #### Decision (2026-09)
 `tsconfig.json` extends `@tsconfig/strictest` + `@tsconfig/node26`.
 `tsconfig.build.json` adds the emit-only options (`declaration`, `sourceMap`,
 `inlineSources`, `outDir`, `target: es2024`,
 `rewriteRelativeImportExtensions: true`) and excludes test files.
 #### Why
 - The editor and CI type-check from one config while the build emits from the
  other, so a test file cannot leak into `dist/`.
 - `inlineSources` embeds the original TypeScript in `dist/*.js.map`, so
  debuggers map into `src/` without it being shipped.
 - `declarationMap` stays off: a `.d.ts.map` cannot embed source and would
  dangle.
 ### The build starts from an empty `dist/`
 #### Decision (2026-09)
 `npm run build` runs a `prebuild` hook that empties `dist/`.
 #### Why
 - `tsc` does not prune orphaned emit output — dropping `declarationMap` left
  stale `*.d.ts.map` files — so reproducibility needs an empty `dist/`.
 - `prebuild` removes only `dist`; the manual `clean` resets `dist` + `coverage`,
  so a local coverage report survives a build.
 ### Source imports use `.ts` extensions
 #### Decision (2026-09)
 Source imports use `.ts`, never `.js`.
 #### Why
 - `node --strip-types` resolves the `.ts` form at test time.
 - `rewriteRelativeImportExtensions` rewrites them to `.js` in the emitted
  JavaScript.
 - The emitted `.d.ts` keep the `.ts` specifier, which TypeScript >= 5.0 resolves
  (see [README § Requirements](../README.md#requirements)), so no
  post-processing step is needed.
 #### Rejected
 - "Pre-fixing" an import to `.js`: it breaks the inner `node --strip-types`
  loop.
 ## Linting and formatting
 ### Type-aware oxlint is a config property
 #### Decision (2026-09)
 Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
 (powered by `oxlint-tsgolint`).
 #### Why
 - The script commands stay clean — no CLI flag.
 - A config property cannot be forgotten on one call site.
 #### Rejected
 - A CLI flag in the `check:oxlint` / `fix:oxlint` scripts: it puts the mode in
  two places and invites them to drift.
 ### `oxlint-disable` directives live next to the code
 #### Decision (2026-09)
 A type-aware rule that false-positives **at one site** is silenced with a
 source-level `oxlint-disable` directive (see `src/primitive-union.ts`). A rule that is
 wrong for a whole **file class** is turned off in a `.oxlintrc.json` `overrides`
 entry instead — e.g. `typescript/no-floating-promises` (synchronous
 `expectTypeOf` reads as an unhandled promise) and `unicorn/no-null` (intentional
 `null` inputs) for `**/*.test.ts`. The same exemption is not repeated as a
 file-level header in every affected file.
 #### Why
 - A one-site disable sits next to the code it silences, visible to anyone
  reading the source, and the rule stays on everywhere else.
 - A file-class rule is a property of the file class, not of one line; the
  override states it once, where the rest of the file-class config lives.
 #### Rejected
 - A project-wide disable in `.oxlintrc.json` for a one-site false positive: it
  hides the exemption from the reader of the affected code and switches the rule
  off repo-wide for a one-site problem.
 - A repeated file-level `oxlint-disable` header for a file-class false positive:
  the copies drift and scatter one config decision across the tree.
 #### Known issue
 - Both placements are _human_ last resorts. AI agents must neither add a source
  disable nor edit `.oxlintrc.json`; they fix the type at its root (see
  [AGENTS.md § Never do](../AGENTS.md#never-do)).
 ### Unwanted stylistic rules are turned off in the config
 #### Decision (2026-09)
 A stylistic rule the project rejects is `"off"` in the `.oxlintrc.json` `rules`
 map, not silenced at a use site. Current entries: `eslint/capitalized-comments`
 (comments may start lowercase) and `eslint/no-ternary` (ternaries are allowed),
 joining the oxfmt-superseded rules already off.
 #### Why
 - The rule is wrong for the whole project, not mis-firing at one site, so there
  is no line to annotate.
 - Keeping the two mechanisms separate keeps a source-level `oxlint-disable`
  meaningful: it marks a lone exception.
 #### Rejected
 - A source-level `oxlint-disable` per use: the same exemption repeated at every
  site, and oxfmt can move the site.
 ### `check:tsc` runs first
 #### Decision (2026-09)
 `check:tsc` runs first in the `npm run check` chain.
 #### Why
 - A type error short-circuits the rest, which is faster than running
  oxlint/oxfmt and failing on `tsc` at the end.
 ### `.editorconfig` is a fallback, not a gate
 #### Decision (2026-09)
 `.editorconfig` exists for editor compatibility; where both apply,
 `.oxfmtrc.json` is authoritative.
 #### Why
 - `.editorconfig` covers the files oxfmt does not format: shell scripts,
  dotfiles, `LICENSE`, the commit-message template, and git's `COMMIT_EDITMSG`
  buffer.
 - oxfmt is the formatter; the overlapping keys only keep non-oxfmt editors close
  to the formatted result, so they cannot disagree with the checker.
 ## Static analysis and packaging
 ### `knip` omits the `types` category
 #### Decision (2026-09)
 `knip --include dependencies,exports,files` omits the `types` category.
 #### Why
 - `types` produces systematic false positives for libraries whose exported types
  are part of the public API.
 - The narrower scope keeps the signal high without config-file boilerplate.
 ### `knip` lists `src/index.ts` as an entry
 #### Decision (2026-09)
 `knip.json` declares `"entry": ["src/index.ts", "scripts/*.ts"]`.
 #### Why
 - Supplying `entry` **replaces** knip's default entry detection, which otherwise
  derives the public entry from `package.json` `exports`. Adding `scripts/*.ts`
  there therefore dropped the library entry, so knip resolved the package through
  its `dist/index.js` output and reported the unreferenced source entry file
  `src/index.ts` as an unused file.
 - Naming the source entry restores the link between the public API and the
  source graph without pointing knip at build output.
 #### Rejected
 - `paths` mapping `dist/index.*` back to `src/index.ts`: more config to model a
  relation the explicit entry states directly, and it would break whenever the
  build layout changes.
 ### `maintain:outdated` ignores `@types/node`
 #### Decision (2026-09)
 Pass `--ignore-packages @types/node`.
 #### Why
 - DT pins `@types/node`'s `latest` dist-tag to LTS (22.x); current-line types
  ride other tags. Scan sees latest < installed — permanent "reverted", exit
  1, zero signal. `--ignore-pre-releases` no help: 22.20.3 is stable.
 #### Rejected
 - `--types major,minor,patch`: hides real reverted reports elsewhere.
 - `@types/node@26.*`: tag stays wrong across majors; un-pin per bump = ritual.
 #### Known issue
 - A genuinely behind `@types/node` goes unreported; match it to
  `.node-version` by hand.
 ### `attw` targets ESM-only
 #### Decision (2026-09)
 `attw --profile esm-only` is used.
 #### Why
 - The package is intentionally ESM-only (no CommonJS shim), so CJS resolution
  scenarios are out of scope by design, not a bug.
 ### `tslib` is deliberately not used
 #### Decision (2026-09)
 `tslib` is not a dependency.
 #### Why
 - `tslib` is a runtime helper for old ES3/ES5 targets; this project targets
  ES2024.
 ## Git hooks and script wiring
 ### `LEFTHOOK_FILES` scopes commands to staged files
 #### Decision (2026-09)
 The pre-commit hook sets `LEFTHOOK_FILES` to the staged-files list, and the
 affected scripts use `${LEFTHOOK_FILES:-<default>}` to default to the whole
 project.
 #### Why
 - It keeps `package.json#scripts` the single source of truth; `lefthook.yml`
  only says what to run on which files.
 - The same script works by hand (whole project) and staged (scoped), so there is
  no second command to maintain.
 ## Language server tooling
 ### `vscode-languageserver-protocol` backs the autocomplete helper
 #### Decision (2026-09)
 The autocomplete helper (`src/util/__tests__/lsp-completion.ts`) drives
 `tsc --lsp --stdio` through `vscode-languageserver-protocol`'s
 `createMessageConnection` and its typed request / notification objects, instead
 of a hand-rolled JSON-RPC client.
 #### Why
 - Framing, `Content-Length` parsing, the pending-request map and server-request
  dispatch are protocol plumbing the helper only reimplemented; the official
  client owns them and tolerates the server's `string | number` ids.
 - `InitializeRequest`, `CompletionRequest`, `DidOpenTextDocumentNotification`,
  … carry their parameter and result types, so `CompletionList` / `CompletionItem`
  replace the helper's ad-hoc shape guards.
 - The `./node` entry re-exports `vscode-jsonrpc/node`, so one devDependency
  supplies both the transport and the protocol types. It is test-only and never
  ships (`files` publishes `dist/` only).
 #### Rejected
 - `vscode-languageclient`: the editor-side client with a full feature registry
  — far more than a test helper needs.
 - Generic JSON-RPC (`jsonrpc-lite`, `jayson`): still no LSP types, so they
  replace framing only and leave the typed protocol surface unimplemented.
 - Keeping the hand-rolled client: the low-level shape is the maintenance cost
  the helper exists to remove, and it must be re-audited against the server.
 ## Editor and agent tooling
 ### VSCode integration
 - Recommended extensions are in
  [.vscode/extensions.json](../.vscode/extensions.json) (oxc, cspell, TypeScript
  native-preview, EditorConfig, todo-tasks).
 - TypeScript 7 runs via the `typescriptteam.native-preview` extension.
 - The oxc extension provides oxlint squiggles and oxfmt format-on-save;
  `.vscode/settings.json` pins it per language so a local `[language]` formatter
  setting cannot override the project's choice.
 ### `@spences10/pi-lsp` is pinned and read-only
 #### Decision (2026-09)
 `@spences10/pi-lsp` is pinned to `0.0.46` and used read-only.
 #### Why
 - It inspects `node_modules/typescript`, sees major >= 7 with no
  `lib/tsserver.js` (true of the `typescript-go` / `tsgo` port), and spawns the
  repo's own `tsc --lsp --stdio` — no `typescript-language-server` dependency is
  needed.
 - Earlier releases (`<= 0.0.10`) hard-wire to `typescript-language-server
 --stdio` and are TS6-only.
 - It is _intermediate_ agent feedback (hover, references, definition, symbols,
  diagnostics), with no rename / code-action / apply-edit surface, and is never a
  gate — `npm run check` / `verify` are.
 - `.pi/settings.json` is the committed declaration; `.pi/npm/` is a gitignored
  install cache that pi recreates on a trusted startup (running `npm install`
  for any missing project package), so it is deliberately not tracked.
@@ -0,0 +1,173 @@
 # Workflow
 How work moves through the repository. The rules are in
 [CONTRIBUTING.md](../CONTRIBUTING.md); this file records why they are shaped the
 way they are.
 ## Branching model
 The model is GitHub Flow (single-developer); the steps are in
 [CONTRIBUTING.md § Branching model](../CONTRIBUTING.md#branching-model). Context
 behind it: Gitea has no collaborative review UI in use, so it is the lab, and
 the project moves to GitHub once it is tested and ready.
 #### Decision (2026-09)
 Work is opened and closed by `create:branch` / `create:finish`, not by prose
 plus hand-written `git`.
 #### Why
 - The preconditions were prose, and prose rots: a rule nobody checks is a
  suggestion. A script asserts, then acts, so the branch or merge only exists if
  the assertions passed.
 - Type-driven work is only trustworthy if the baseline was green before the
  first edit. Cheap checks run first and `npm run test` last, so the expensive
  gate is not paid on an ineligible tree.
 - The merge half owns the post-merge `npm run verify`, so a merge cannot land
  unverified. The push stays with `create:release` so the merge is reviewed
  locally first; `main` is therefore routinely ahead of its upstream between a
  merge and the release that ships it. `create:branch` requires only that `main`
  is not _behind_ — matching `create:finish`, which tolerates the local merge and
  fast-forwards over a remote one — rather than an exact match.
 - Every failure is non-mutating except the baseline test, which runs on `main`
  after switching there: a red `main` restores the branch you started on, and a
  merge conflict aborts back to the feature branch rather than stranding a
  half-merged `main`.
 #### Rejected
 - Hand-written `git switch -c` / `git merge`: same rules, no enforcement.
 - Reusing `pubv`'s preflight for `create:branch`: release-shaped, third-party,
  and it would pay for a build and pack a new branch has no use for.
 - Leaving the merge to reviewer judgment: that judgment moved earlier, to the
  handover review before `create:finish`, rather than living in a command anyone
  can run from a dirty tree.
 - Fast-forward instead of `--no-ff`: `--no-ff` keeps each unit of work visible
  in `git log`.
 - Pushing from `create:finish` to keep `main` level with its upstream: it would
  trade the local review the push waits for for a network side effect, and a
  failed push would leave the merge landed but unpublished.
 ## Changelog notes
 The rule is in
 [CONTRIBUTING.md § Rules the tools don't enforce](../CONTRIBUTING.md#rules-the-tools-dont-enforce).
 #### Decision (2026-09)
 A merged branch carries its own summary under `[Unreleased]` in
 [CHANGELOG.md](../CHANGELOG.md), added before `create:finish`;
 `create:release` graduates it into the tagged section (see
 [publishing.md](./publishing.md)).
 #### Why
 - `create:release` derives the bump heuristic from the `[Unreleased]` body, so
  the notes must exist before release day.
 - The contributor has fresh context; at release day the intent of a branch is
  only its diff.
 - Gitmoji subjects are signposts, not semantic keys, so notes cannot be derived
  from the history.
 #### Rejected
 - Generating notes from subjects at release time: subjects carry no parseable
  type/scope (see § Commit messages).
 - The maintainer writing one summary during `create:release`: reconstruction
  after the fact.
 - Enforcing it in `create:finish`: the front doors assert git state, not
  content — and _notable_ is exactly the judgment a tool cannot make.
 ## Script prefix convention
 The prefix taxonomy is the rule, and it lives in
 [CONTRIBUTING.md § Script prefix convention](../CONTRIBUTING.md#script-prefix-convention).
 The design behind it: bare scripts are the tier entry points — a single tool
 (`build`, `clean`) or an aggregator of a `prefix:*` family (`check`, `fix`,
 `test`, `watch`, `maintain`, `setup`) — while `verify` composes `check` +
 `test:unit` into the whole-project gate (it uses `test:unit`, not `test`,
 because `check` already runs `check:tsc`).
 #### Decision (2026-09)
 `create:` is the prefix for workflow front doors, with no bare `create`
 aggregator.
 #### Why
 - Both members create something real: a branch, a release.
 - It joined both lists in [CONTRIBUTING.md](../CONTRIBUTING.md) alongside its
  first members, so it could not go invisible the way the retired `use:` prefix
  did.
 - `publish:*` already set the precedent for a prefix without an aggregator.
 #### Rejected
 - `run:` / `perform:`: they mean only "do the named thing", so every script fits
  and the taxonomy collapses.
 - `git:`: names the tool, not the lifecycle moment, and implies passthrough
  aliases.
 - `start:`: describes the branch half, not the release.
 - `cut:`: idiomatic but needs VCS slang to decode.
 - `flow:`: overloaded in a type-level matching library.
 - The existing families: `check:*` is read-only (CI would run a state-mutating
  command), `fix:*` reviews as a diff not a branch, `maintain:*` is advisory and
  never a gate.
 ## Feedback tiers
 The table and invocation rules are in
 [CONTRIBUTING.md § Feedback tiers](../CONTRIBUTING.md#feedback-tiers); this
 section explains the split.
 #### Decision (2026-09)
 Fast, offline, staged-file checks sit in pre-commit; whole-project test runs in
 pre-push and `verify`; slow or network-bound scans under `maintain`.
 #### Why
 - `watch:*` runs until killed, in its own pane, so it is the earliest tier,
  firing on save before staging or commit.
 - `check:tsc` / `check:oxlint` / `check:oxfmt` / `check:cspell` are fast
  (~0.2–0.5s each), offline, and scope to staged files via `LEFTHOOK_FILES`, so
  pre-commit gives instant feedback on what you typed.
 - `test` (and its `tsc`) runs the whole suite over the whole project, and the
  staged-file convention does not apply to the test runner, so it belongs in
  pre-push, after the commits exist but before the push leaves the machine.
 #### Rejected
 - `maintain:*` in `check` or pre-commit: advisory, whole-project and
  network-bound scans are not correctness gates and would slow the fast tier.
 - Treating a green pre-commit as the definition of done: it sees only staged
  files, hence `npm run verify`.
 - A separate `git push` hook for `verify`: the pre-push test tier already covers
  it.
 ## Commit messages
 The convention is in
 [CONTRIBUTING.md § Commit messages](../CONTRIBUTING.md#commit-messages).
 Examples: `:sparkles: Add watch tier with watch:test child`,
 `:recycle: Move type-aware config to .oxlintrc.json; use source-level disable
 directives`, `:memo: Restore unique maintainer content as CONTRIBUTING.md`. The
 body explains what and why, not how; link issues with `Resolves #...`.
 #### Decision (2026-09)
 Gitmoji subjects, imperative mood, wrapped 50/72, not Conventional Commits.
 #### Why
 - The history is gitmoji and predates any commit-lint tooling; switching would
  rewrite the convention for no gain.
 - The body carries the reasoning a reviewer needs; the subject is a signpost,
  not a semantic key.
 #### Rejected
 - Conventional Commits: the release flow uses hand-written Keep-a-Changelog
  notes, not generated ones, so the prefix has no automation value here (see
  [publishing.md](./publishing.md)).
@@ -0,0 +1,51 @@
 # CI job image for the Gitea act_runner: the runner's default job image with
 # Node pre-planted where actions/setup-node looks first.
 #
 # Why this layout: setup-node ignores `node` on PATH; its only fast path is a
 # probe of /opt/hostedtoolcache/node/<version>/<arch>. Without an entry there
 # it downloads the ~50 MB distribution on EVERY job (the runner's job
 # containers are ephemeral, so its tool cache never survives a job). The
 # official node images keep exactly the layout setup-node expects under
 # /usr/local, so this layer is a pure file overlay — no scripts, no env.
 #
 # Why not a host bind of /opt/hostedtoolcache: binds never self-prune. Docker
 # images are content-addressed: the base layers dedupe against the act image
 # the host already has, and `docker image prune` / re-pulls are the cleanup
 # story.
 #
 # NODE_VERSION must match `.node-version` exactly. setup-node resolves a float
 # like `26` to the latest known patch at runtime, so a bump silently busts the
 # baked entry; `.node-version` is pinned to x.y.z and scripts/runner-image.sh
 # guards the coupling. Rebuild + repoint `container.image` in
 # .gitea/workflows/ci.yml on every bump.
 #
 # The extra `nodebase` stage is load-bearing: `COPY --from=` resolves its value
 # as a *stage name* at parse time, before build args exist, so
 # `COPY --from=node:${NODE_VERSION}` collapses to the invalid `node:` on
 # frontends that do not expand args there. ARGs declared before the first FROM
 # *are* expanded in FROM, so routing through a named stage works everywhere.
 # Global scope: only visible to FROM lines, but that is exactly where we need it.
 ARG NODE_VERSION=26.8.2
 FROM node:${NODE_VERSION} AS nodebase
 FROM catthehacker/ubuntu:act-latest
 # ARGs do not cross stage boundaries; redeclare (with the same default, so a
 # bare `docker build -f docker/Dockerfile .` still works) for the paths below.
 # Keep this default in sync with the global one above.
 ARG NODE_VERSION=26.8.2
 # node image: bin/ + lib/ under /usr/local → tool cache: bin/ + lib/ under <ver>/x64.
 COPY --from=nodebase /usr/local /opt/hostedtoolcache/node/${NODE_VERSION}/x64
 # actions/tool-cache only accepts a cached tool when the sibling marker file
 # "<version>/<arch>.complete" exists — tc.find() checks it and falls back to
 # downloading otherwise, however complete the directory is. The marker is what
 # tc.cacheDir() writes after *it* installs a tool, so a pre-baked entry has to
 # reproduce it explicitly.
 RUN touch "/opt/hostedtoolcache/node/${NODE_VERSION}/x64.complete"
 # Fail the build (not CI) if the overlay or the version arg were wrong.
 # Shell form on purpose: exec form (`RUN [...]`) does not expand ARG values.
 RUN "/opt/hostedtoolcache/node/${NODE_VERSION}/x64/bin/node" --version
@@ -0,0 +1,5 @@
 {
    "$schema": "./node_modules/knip/schema.json",
    "entry": ["src/index.ts", "scripts/*.ts"],
    "ignoreDependencies": ["@runwisp/pubv"]
 }
@@ -1,55 +1,21 @@
-# EXAMPLE USAGE:
+min_version: 2.0.0
-#
+
-#   Refer for explanation to following link:
+pre-commit:
-#   https://lefthook.dev/configuration/
+    parallel: true
 #
 # pre-push:
 #   jobs:
 #     - name: packages audit
 #       tags:
 #         - frontend
 #         - security
 #       run: yarn audit
 #
 #     - name: gems audit
 #       tags:
 #         - backend
 #         - security
 #       run: bundle audit
 #
 # pre-commit:
 #   parallel: true
 #   jobs:
 #     - run: yarn eslint {staged_files}
 #       glob: "*.{js,ts,jsx,tsx}"
 #
 #     - name: rubocop
 #       glob: "*.rb"
 #       exclude:
 #         - config/application.rb
 #         - config/routes.rb
 #       run: bundle exec rubocop --force-exclusion {all_files}
 #
 #     - name: govet
 #       files: git ls-files -m
 #       glob: "*.go"
 #       run: go vet {files}
 #
 #     - script: "hello.js"
 #       runner: node
 #
 #     - script: "hello.go"
 #       runner: go run
    commands:
        oxlint:
            glob: "*.{ts,tsx,js,jsx,mjs,cjs}"
            run: sh -c 'LEFTHOOK_FILES="$*" npm run check:oxlint' sh {staged_files}
        oxfmt:
            glob: "*.{ts,tsx,js,jsx,mjs,cjs,json,jsonc,yaml,yml,md,mdx}"
            run: sh -c 'LEFTHOOK_FILES="$*" npm run check:oxfmt' sh {staged_files}
        cspell:
            run: sh -c 'LEFTHOOK_FILES="$*" npm run check:cspell' sh {staged_files}
        typecheck:
            run: npm run check:tsc
-    spell:
+
-      run: npm run check:cspell
+pre-push:
-    sort:
+    parallel: false
-      run: npm run check:package
+    commands:
-    lint:
+        test:
-      run: npm run check:eslint
+            run: npm test
    format:
      run: npm run check:prettier
    outdated:
      run: npm run check:outdated
@@ -1,15 +1,99 @@
 {
    "name": "tiny-pattern-ts",
-  "private": true,
+    "version": "0.8.0",
-  "version": "0.0.0",
+    "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
    "keywords": [
        "adt",
        "algebraic-data-types",
        "match",
        "pattern",
        "pattern-matching",
        "typescript"
    ],
    "homepage": "https://gitea.e1nsnull.de/tmu/tiny-pattern-ts#readme",
    "bugs": {
        "url": "https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/issues"
    },
    "license": "MIT",
    "repository": {
        "type": "git",
        "url": "git+https://gitea.e1nsnull.de/tmu/tiny-pattern-ts.git"
    },
    "files": [
        "dist",
        "CHANGELOG.md",
        "README.md",
        "LICENSE"
    ],
    "type": "module",
    "sideEffects": false,
    "imports": {
        "#test-utils/*": "./src/util/__tests__/*"
    },
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
            "import": "./dist/index.js"
        }
    },
    "publishConfig": {
        "access": "public"
    },
    "scripts": {
-    "dev": "vite",
+        "build": "tsc -p tsconfig.build.json",
-    "build": "tsc && vite build",
+        "prebuild": "rm -rf dist",
-    "preview": "vite preview"
+        "check": "npm run check:tsc && npm run check:oxlint && npm run check:oxfmt && npm run check:cspell",
        "check:cspell": "cspell lint ${LEFTHOOK_FILES:-.}",
        "check:oxfmt": "oxfmt --check ${LEFTHOOK_FILES:-.}",
        "check:oxlint": "oxlint ${LEFTHOOK_FILES:-src scripts}",
        "check:tsc": "tsc",
        "clean": "rm -rf dist coverage",
        "fix": "npm run fix:oxlint && npm run fix:oxfmt",
        "fix:oxfmt": "oxfmt ${LEFTHOOK_FILES:-.}",
        "fix:oxlint": "oxlint --fix src scripts",
        "create:branch": "./scripts/branch.sh",
        "create:finish": "./scripts/finish.sh",
        "create:release": "./scripts/release.sh",
        "maintain": "npm run maintain:knip; npm run maintain:outdated",
        "maintain:knip": "knip --include dependencies,exports,files",
        "maintain:outdated": "check-outdated --ignore-pre-releases --ignore-packages @types/node",
        "test": "npm run check:tsc && node --test --strip-types \"src/**/*.test.ts\"",
        "test:ci": "c8 --reporter=text --reporter=lcov --reporter=html node --test --strip-types \"src/**/*.test.ts\"",
        "test:unit": "node --test --strip-types \"src/**/*.test.ts\"",
        "verify": "npm run check && npm run test:unit",
        "watch": "npm run watch:test",
        "watch:test": "node --test --watch --strip-types \"src/**/*.test.ts\"",
        "publish:attw": "attw . --pack --profile esm-only",
        "publish:publint": "publint",
        "setup": "npm run setup:git-commit-message",
        "setup:git-commit-message": "git config commit.template commit-message-template"
    },
    "dependencies": {
        "type-fest": "^5.9.0"
    },
    "devDependencies": {
-    "typescript": "~5.7.2",
+        "@arethetypeswrong/cli": "^0.18.5",
-    "vite": "^6.3.1"
+        "@runwisp/pubv": "^1.5.1",
        "@tsconfig/node26": "^26.0.1",
        "@tsconfig/strictest": "^2.0.8",
        "@types/node": "^26.6.1",
        "c8": "^12.0.0",
        "check-outdated": "^3.0.0",
        "cspell": "^10.3.2",
        "expect-type": "1.4.0",
        "knip": "^6.34.0",
        "lefthook": "^2.1.12",
        "oxfmt": "^0.70.0",
        "oxlint": "^1.83.0",
        "oxlint-tsgolint": "^7.0.2001",
        "publint": "^0.3.24",
        "typescript": "^7.0.2",
        "vscode-languageserver-protocol": "^3.18.3"
    },
    "engines": {
        "node": ">=26"
    },
    "allowScripts": {
        "lefthook@2.1.14": true
    }
 }
@@ -1,295 +0,0 @@
 # Project Specifications for TypeScript NPM Module
 - name of package: tiny-pattern-ts
 ## 0. References
 typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starter-tiny/
 ## 1. Development Environment
 - **TypeScript**: Use strictest rules (via npm package "@tsconfig/strictest", additional strictures)
 - **EditorConfig**: Use `.editorconfig` from typescript-lib-starter-tiny
 - **Prettier**: For code formatting, integrated with ESLint
 - **ESLint**: Strictest type-checked rules, integrated with Prettier
 - **Import Sorting**: Via Prettier or ESLint
 - **cspell**: Basic spelling configuration
 - **Lefthook**: Pre-commit checks for:
   - Type checking
   - Spelling
   - Package sorting
   - Linting
   - Formatting
   - Outdated Packages
 - **Additional Dev Dependencies**:
   - lefthook
   - sort-package-json
   - check-outdated
 ## 2. Build & Test
 - **Build Tool**: Vite (ESM only, no CJS)
 - **Testing**: Vitest
 - **TypeScript Build Output**: `dist` directory
 - **Additional Runtime Dependencies**:
   - tslib
   - type-fest
 ## 3. Project Structure & Files
 - __.gitignore__: Ignore `dist`, `node_modules`, and other common files
 - **.npmignore**: Ignore `src` and other non-dist files
 - **LICENSE**: MIT
 - **README.md**: Scaffolded
 - **commit-message-template**: From typescript-lib-starter-tiny
 - **Target Environments**: Browser and latest LTS Node.js
 - **No React, No CJS, ESM only**
 ## 4. Automation & Quality
 - **Version Automation**: Use standard `npm version` for versioning
 - **Unused Dependency Check**: Use `check-outdated` with config
 - **No commitlint, no conventional commits**
 ## 5. Scripts (Clustered as in typescript-lib-starter-tiny, named similarly)
 ### SETUP
 - `use:git-commit-message`: Set up commit message template (if needed)
 ### TEST
 - `test`: Run typecheck and all tests
 - `test:unit`: Run unit tests with Vitest
 - `test:ci`: Run tests in CI mode (with coverage, fail-fast)
 ### BUILD
 - `build`: Build the project using Vite
 ### CLEAN
 - `clean`: Clean build output
 - `clean:build`: Remove dist directory
 ### CHECK
 - `check`: Run all checks (lint, spell, typecheck, import/package sort, outdated)
 - `check:eslint`: Run ESLint
 - `check:prettier`: Check formatting with Prettier
 - `check:cspell`: Run cspell
 - `check:tsc`: TypeScript typecheck (no emit)
 - `check:package`: Check package.json sort
 - `check:outdated`: Check for unused/outdated dependencies
 ### FIX
 - `fix`: Run all fixers (eslint, prettier, package sort)
 - `fix:eslint`: Auto-fix ESLint issues
 - `fix:prettier`: Auto-fix formatting with Prettier
 - `fix:package`: Auto-fix package.json sort
 ### HOOKS
 - Lefthook will run relevant scripts on staged files for pre-commit (typecheck, lint, spell, sort, format, check:outdated)
 ---
 ## 6. Repository & CI/CD
 - **Repository**: Hosted on GitHub
 - **Build Pipeline**: Use GitHub Actions for CI/CD
   - On push and pull request: run build, lint, typecheck, test:ci, spell, check:outdated
   - On release (tagged commit): publish to npm
 ## 7. Versioning & Publishing
 - **Version Update**: Use `npm version` to bump version after merging to main and before publishing
 - **Publishing to npm**: Only publish from CI on tagged commits (e.g., after version bump and release notes)
 - **Recommended Workflow**:
   1. Develop and merge PRs to main
   2. Run all checks via CI
   3. Bump version with `npm version <patch|minor|major>`
   4. Push tag to GitHub
   5. CI builds and publishes to npm on tag
 ## 8. NPM Keywords
 - pattern-matching
 - pattern
 - match
 - algebraic-data-types
 - adt
 - typescript
 > The library is for pattern matching (not regex), similar to F#'s pattern matching, for TypeScript/ESM environments.
 ## 9. Code Coverage
 - **Configuration**:
 ```ts
 import { defineConfig } from 'vitest/config';
 export default defineConfig({
  test: {
    coverage: {
      reporter: ['text', 'html', 'lcov'],
      include: ['src/**/*.ts'],
      exclude: ['src/**/*.test.ts', 'test/**'],
    },
  },
 });
 ```
 - Coverage reports: text summary, HTML, and lcov formats
 - Add coverage thresholds if desired
 - **CI**: Ensure coverage is generated and optionally uploaded as an artifact or checked for minimum thresholds
 ## 10. Source Structure & Tree Shaking
 - **Source Directory**: All source code resides in `src/` and is exported via `src/index.ts`.
 - **Configuration**:
   - Ensure `sideEffects: false` in `package.json`
   - Use ESM-only exports
   - Avoid top-level side effects in modules
   - Prefer explicit exports in `index.ts` for best results
 - the human will implement the source code
 ## 11. Included Templates from typescript-lib-starter-tiny
 ### .editorconfig
 ```plaintext
 # Editor configuration, see http://editorconfig.org
 root = true
 [*]
 charset = utf-8
 indent_style = space
 indent_size = 4
 insert_final_newline = true
 max_line_length = 80
 trim_trailing_whitespace = true
 quote_type = double
 [*.md]
 max_line_length = 0
 trim_trailing_whitespace = false
 [COMMIT_EDITMSG]
 max_line_length = 0
 ```
 ### commit-message-template
 ```plaintext
 # If applied, this commit will... (Max 50 char)
 # Explain why this change is being made (Max 72 Char) [WHAT and WHY vs HOW]
 # Provide links or keys to any relevant tickets, articles or other resources
 Resolves #...
 # --- COMMIT END ---
 # Remember to
 #    Use the imperative mood in the subject line
 #    Capitalize the subject line
 #    Do not end the subject line with a period
 #    Separate subject from body with a blank line
 #    Use the body to explain what and why vs. how
 #    Can use multiple lines with "-" for bullet points in body
 ```
 ### README.md Structure (to scaffold)
 - Project title and description
 - Development
  - Build: `npm run build`
  - Test: `npm run test`, `npm run test:ci`
  - Checks: `npm run check`, `npm run fix`
 - VSCode integration
  - Debugging
  - Running tests
 - Document workflows like 
   - Version updates
   - Changelog automation
   - Publishing
 - Contribution guidelines
  - Commit signing (GPG)
  - How to set up commit message template
  - Reference to commit-message-template
 ## 12. Project Initialization & Commit Strategy
 - Start by initilizing git with a main branch
 - Initial commit: add an empty README.md
 - create a feature branch: `feature/setup`
 - For each technology or tool added (and its configuration), create a separate commit:
  - Prepend each commit message with a matching gitmoji (e.g., :sparkles: for new features, :wrench: for config, etc.)
  - Example commit messages:
    - :tada: Initial commit with empty README
    - :sparkles: Configured Vite (Vite-specific setup)
    - :sparkles: Configured TypeScript (may be merged with Vite if dependent)
    - :wrench: Configured ESLint
    - :wrench: Configured Prettier
    - ...and so on for each technology/tool
 - Each commit should include only the relevant files and configuration for that technology/tool
 - This approach ensures a clean, understandable project history and makes it easy to review or revert specific setup steps
 ## 13. Changelog Automation
 - Use a tool like standard-version or changesets to automate changelog generation from commit messages or PRs.
 - Ensure changelog is updated as part of the release process.
 ## 14. Publishing Public
 - Configure npm publishing to be public by default.
 - Add `"publishConfig": { "access": "public" }` to package.json.
 - Ensure CI/CD pipeline publishes with public access.
 ## 15. VSCode Integration
 - Add a `.vscode/settings.json` with the following content:
 ```json
 {
    "typescript.tsdk": "node_modules/typescript/lib",
    "[typescript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
    },
    "[json]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
    },
    "[mdx]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
    },
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true,
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
    }
 }
 ```
 - Add `.vscode/extensions.json` with recommended extensions:
  - `esbenp.prettier-vscode` (Prettier)
  - `dbaeumer.vscode-eslint` (ESLint)
  - `streetsidesoftware.code-spell-checker` (cspell)
  - `vitest.explorer` (for test integration)
  - `ms-vscode.vscode-typescript-next` (for latest TS features, optional)
 - Add `.vscode/tasks.json` for common tasks (optional):
  - Build, test, lint, typecheck, format, spell, check:outdated
 - Ensure VSCode uses workspace TypeScript version and Prettier for formatting
@@ -1 +0,0 @@
 <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>
@@ -0,0 +1,124 @@
 #!/bin/sh
 set -eu
 # Branch front-door. Run as `npm run create:branch -- <prefix>/<desc>`.
 #
 # Asserts the branch preconditions — clean tree, no in-progress operation,
 # current `main`, green baseline — and only then creates the branch, so the
 # expensive `npm run test` is not paid on a tree that was never eligible.
 #
 # Why the front door exists, the rejected prefix names, and the `create:`
 # decision: development/workflow.md § Branching model and § Script prefix
 # convention.
 BASE="main"
 PREFIXES="feature fix chore"
 NAME="${1:-}"
 if [ -z "${NAME}" ]; then
    echo "usage: npm run create:branch -- <prefix>/<desc>    (prefix: ${PREFIXES})" >&2
    exit 2
 fi
 git rev-parse --is-inside-work-tree >/dev/null 2>&1 || {
    echo "error: not inside a git work tree." >&2
    exit 1
 }
 MATCH=0
 for p in ${PREFIXES}; do
    case "${NAME}" in
    "${p}/"*) MATCH=1 ;;
    esac
 done
 if [ "${MATCH}" -ne 1 ]; then
    echo "error: '${NAME}' must start with one of: ${PREFIXES}." >&2
    echo "       the prefix is inferred from the task, not defaulted here." >&2
    exit 1
 fi
 git check-ref-format --branch "${NAME}" >/dev/null 2>&1 || {
    echo "error: '${NAME}' is not a valid branch name." >&2
    exit 1
 }
 git show-ref --verify --quiet "refs/heads/${NAME}" && {
    echo "error: branch '${NAME}' already exists; switch to it instead." >&2
    exit 1
 }
 START_REF=$(git symbolic-ref --quiet --short HEAD || true)
 if [ -z "${START_REF}" ]; then
    echo "error: detached HEAD; switch to a branch first." >&2
    exit 1
 fi
 STATE_ROOT=$(git rev-parse --absolute-git-dir)
 for state in MERGE_HEAD rebase-merge rebase-apply CHERRY_PICK_HEAD BISECT_LOG; do
    [ -e "${STATE_ROOT}/${state}" ] && {
        echo "error: a '${state}' operation is in progress; finish or abort it first." >&2
        exit 1
    }
 done
 # `--porcelain` is deliberately stricter than `git diff --quiet`: it also reports
 # untracked files, which would otherwise ride silently onto the new branch.
 DIRTY=$(git status --porcelain)
 if [ -n "${DIRTY}" ]; then
    echo "error: working tree is not clean:" >&2
    echo "${DIRTY}" | sed 's/^/         /' >&2
    exit 1
 fi
 git show-ref --verify --quiet "refs/heads/${BASE}" || {
    echo "error: no local '${BASE}' to branch from." >&2
    exit 1
 }
 # Derive the remote rather than hardcoding it: `main` tracks `origin` (ssh)
 # here; a hardcoded name would check currency against a ref that may not
 # exist on a differently configured clone.
 # `--quiet` echoes the unresolved `main@{upstream}` literal to stdout on
 # failure, so it cannot be paired with a `$(...) || fallback`; the non-quiet
 # form prints nothing on failure and the fallback runs.
 UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name "${BASE}@{upstream}" 2>/dev/null) || UPSTREAM=""
 if [ -n "${UPSTREAM}" ]; then
    git fetch --quiet "${UPSTREAM%/*}" "${UPSTREAM#*/}" || {
        echo "error: '${UPSTREAM}' check failed: could not reach '${UPSTREAM%/*}'." >&2
        echo "       refusing to branch on a possibly stale '${BASE}'." >&2
        exit 1
    }
    # Only *behind* is a problem. `create:finish` deliberately leaves the local
    # merge on '${BASE}' until `create:release` pushes it, so being ahead is the
    # normal state between a merge and the release that ships it; branching from
    # those commits is intended. Missing remote commits is not.
    BEHIND=$(git rev-list --count "${BASE}..${UPSTREAM}")
    if [ "${BEHIND}" -ne 0 ]; then
        echo "error: '${BASE}' is behind '${UPSTREAM}' (by ${BEHIND})." >&2
        echo "       update it: git switch ${BASE} && git pull --ff-only" >&2
        exit 1
    fi
 else
    echo "warning: '${BASE}' has no upstream; freshness against the remote is unchecked." >&2
 fi
 restore() {
    git switch --quiet "${START_REF}" 2>/dev/null || true
 }
 trap 'restore' EXIT HUP INT TERM
 if [ "${START_REF}" != "${BASE}" ]; then
    git switch --quiet "${BASE}"
 fi
 echo "Baseline: npm run test"
 if ! npm run --silent test; then
    echo "error: baseline is red on '${BASE}'; fix that first so later failures stay attributable." >&2
    exit 1
 fi
 git switch --quiet --no-track -c "${NAME}"
 trap - EXIT HUP INT TERM
 # push.default=upstream is set here, so an inherited upstream would make a bare
 # `git push` target main. Branching local-from-local does not set one anyway;
 # --no-track says so out loud.
 echo "Created ${NAME} from ${BASE} $(git rev-parse --short "${BASE}")."
@@ -0,0 +1,121 @@
 #!/bin/sh
 set -eu
 # Feature-finish front door. Run as `npm run create:finish`.
 #
 # Mirror image of `create:branch`: asserts the merge-side preconditions, merges
 # the current `feature/`/`fix/`/`chore/` branch into `main` with `--no-ff`,
 # proves the result with `npm run verify`, and only then deletes the branch. The
 # push is owned by `create:release`, so the merge stays local and reviewable.
 # On a conflict it aborts and returns to the feature branch.
 #
 # Rationale and the rejected alternatives: development/workflow.md § Branching
 # model.
 BASE="main"
 PREFIXES="feature fix chore"
 git rev-parse --is-inside-work-tree >/dev/null 2>&1 || {
    echo "error: not inside a git work tree." >&2
    exit 1
 }
 STATE_ROOT=$(git rev-parse --absolute-git-dir)
 for state in MERGE_HEAD rebase-merge rebase-apply CHERRY_PICK_HEAD BISECT_LOG; do
    [ -e "${STATE_ROOT}/${state}" ] && {
        echo "error: a '${state}' operation is in progress; finish or abort it first." >&2
        exit 1
    }
 done
 # `--porcelain` is deliberately stricter than `git diff --quiet`: it also
 # reports untracked files, which would otherwise not be part of the merge and
 # silently outlive the branch deletion.
 DIRTY=$(git status --porcelain)
 if [ -n "${DIRTY}" ]; then
    echo "error: working tree is not clean:" >&2
    echo "${DIRTY}" | sed 's/^/         /' >&2
    exit 1
 fi
 START_REF=$(git symbolic-ref --quiet --short HEAD || true)
 if [ -z "${START_REF}" ]; then
    echo "error: detached HEAD; switch to the branch you want to finish." >&2
    exit 1
 fi
 if [ "${START_REF}" = "${BASE}" ]; then
    echo "error: already on '${BASE}'; switch to the branch to finish." >&2
    exit 1
 fi
 MATCH=0
 for p in ${PREFIXES}; do
    case "${START_REF}" in
    "${p}/"*) MATCH=1 ;;
    esac
 done
 if [ "${MATCH}" -ne 1 ]; then
    echo "error: '${START_REF}' must start with one of: ${PREFIXES}." >&2
    echo "       refusing to merge a branch that is not a unit of work." >&2
    exit 1
 fi
 git show-ref --verify --quiet "refs/heads/${BASE}" || {
    echo "error: no local '${BASE}' to merge into." >&2
    exit 1
 }
 # Derive the remote rather than hardcoding it: this repo has `origin` (ssh) and
 # `origin_https`, and `main` tracks the latter — `git fetch origin main` would
 # check currency against a ref that is never updated here.
 # `--quiet` echoes the unresolved `main@{upstream}` literal to stdout on
 # failure, so it cannot be paired with a `$(...) || fallback`; the non-quiet
 # form prints nothing on failure and the fallback runs.
 UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name "${BASE}@{upstream}" 2>/dev/null) || UPSTREAM=""
 BEHIND=0
 if [ -n "${UPSTREAM}" ]; then
    git fetch --quiet "${UPSTREAM%/*}" "${UPSTREAM#*/}" || {
        echo "error: '${UPSTREAM}' check failed: could not reach '${UPSTREAM%/*}'." >&2
        echo "       refusing to merge onto a possibly stale '${BASE}'." >&2
        exit 1
    }
    BEHIND=$(git rev-list --count "${BASE}..${UPSTREAM}")
    AHEAD=$(git rev-list --count "${UPSTREAM}..${BASE}")
    if [ "${AHEAD}" -ne 0 ] && [ "${BEHIND}" -ne 0 ]; then
        echo "error: '${BASE}' has diverged from '${UPSTREAM}' (ahead ${AHEAD}, behind ${BEHIND})." >&2
        echo "       reconcile '${BASE}' with '${UPSTREAM}' before finishing." >&2
        exit 1
    fi
 else
    echo "warning: '${BASE}' has no upstream; freshness against the remote is unchecked." >&2
 fi
 echo "Finishing into ${BASE}:"
 git --no-pager log --oneline --no-decorate "${BASE}..${START_REF}" | sed 's/^/  /'
 git switch --quiet "${BASE}"
 if [ "${BEHIND}" -ne 0 ]; then
    echo "Fast-forwarding ${BASE} to ${UPSTREAM} (${BEHIND} commit(s))."
    git merge --quiet --ff-only "${UPSTREAM}"
 fi
 if ! git merge --quiet --no-ff -m ":twisted_rightwards_arrows: Merge ${START_REF} into ${BASE}" "${START_REF}"; then
    echo "error: merge of '${START_REF}' failed; aborting and returning to it." >&2
    git merge --abort 2>/dev/null || true
    git switch --quiet "${START_REF}"
    exit 1
 fi
 echo "Verify: npm run verify"
 if ! npm run --silent verify; then
    echo "error: 'npm run verify' is red after the merge." >&2
    echo "       the merge is local and not yet pushed; fix it on '${BASE}' and commit," >&2
    echo "       then drop the now-merged branch with 'git branch -d ${START_REF}'." >&2
    exit 1
 fi
 git branch --delete "${START_REF}" >/dev/null
 echo "Merged ${START_REF} into ${BASE} and deleted the branch."
 echo "Next: npm run create:release (or git push, for a merge with no release)."
@@ -0,0 +1,147 @@
 import fs from "node:fs";
 import path from "node:path";
 import zlib from "node:zlib";
 /**
 * Emit precompressed `.br` / `.gz` / `.zst` sidecars next to every text asset
 * under the given directories, keeping the originals. The Gitea pages service
 * (`static-web-server` with `SERVER_COMPRESSION_STATIC=true`) serves the sidecar
 * matching `Accept-Encoding` and falls back to the original for the rest.
 *
 * Usage: node --strip-types scripts/precompress.ts <dir> [<dir>...]
 *
 * Why sidecars rather than per-request compression: development/ci.md § Coverage
 * serving.
 */
 /**
 * Only extensions worth compressing. Images, fonts and archives are already
 * compressed, so a sidecar would only make them bigger.
 */
 const TEXT_EXTENSIONS: ReadonlySet<string> = new Set([
    ".css",
    ".htm",
    ".html",
    ".info",
    ".js",
    ".json",
    ".map",
    ".md",
    ".mjs",
    ".svg",
    ".txt",
    ".xml",
    ".yaml",
    ".yml",
 ]);
 const GZIP_LEVEL = 9;
 const ZSTD_LEVEL = 19;
 const INITIAL_COUNT = 0;
 /** `process.argv` is `[node, script, ...args]`; drop the first two entries. */
 const ARGV_PREFIX_LENGTH = 2;
 const FAILURE_EXIT_CODE = 1;
 interface Encoder {
    readonly suffix: string;
    readonly encode: (input: Buffer) => Buffer;
 }
 const ENCODERS: readonly Encoder[] = [
    {
        suffix: ".br",
        encode: (input) =>
            zlib.brotliCompressSync(input, {
                params: {
                    [zlib.constants.BROTLI_PARAM_QUALITY]:
                        zlib.constants.BROTLI_MAX_QUALITY,
                },
            }),
    },
    {
        suffix: ".gz",
        encode: (input) => zlib.gzipSync(input, { level: GZIP_LEVEL }),
    },
    {
        suffix: ".zst",
        encode: (input) =>
            zlib.zstdCompressSync(input, {
                params: {
                    [zlib.constants.ZSTD_c_compressionLevel]: ZSTD_LEVEL,
                },
            }),
    },
 ];
 interface Totals {
    assets: number;
    sidecars: number;
    savedBytes: number;
 }
 /** Depth-first list of every regular file under `directory`, recursively. */
 const listFiles = (directory: string): string[] => {
    const files: string[] = [];
    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
        const entryPath = path.join(directory, entry.name);
        if (entry.isDirectory()) {
            files.push(...listFiles(entryPath));
        } else if (entry.isFile()) {
            files.push(entryPath);
        }
    }
    return files;
 };
 const writeSidecar = (
    target: string,
    input: Buffer,
    encoder: Encoder,
 ): number => {
    const compressed = encoder.encode(input);
    if (compressed.byteLength < input.byteLength) {
        fs.writeFileSync(target, compressed);
        return input.byteLength - compressed.byteLength;
    }
    // Drop a stale sidecar: it would still win at the server.
    fs.rmSync(target, { force: true });
    return INITIAL_COUNT;
 };
 const precompress = (file: string, totals: Totals): void => {
    if (!TEXT_EXTENSIONS.has(path.extname(file).toLowerCase())) {
        return;
    }
    totals.assets += 1;
    const input = fs.readFileSync(file);
    for (const encoder of ENCODERS) {
        const saved = writeSidecar(`${file}${encoder.suffix}`, input, encoder);
        if (saved > INITIAL_COUNT) {
            totals.sidecars += 1;
            totals.savedBytes += saved;
        }
    }
 };
 const main = (directories: readonly string[]): void => {
    if (directories.length === INITIAL_COUNT) {
        process.stderr.write("usage: precompress.ts <dir> [<dir>...]\n");
        process.exitCode = FAILURE_EXIT_CODE;
        return;
    }
    const totals: Totals = {
        assets: INITIAL_COUNT,
        sidecars: INITIAL_COUNT,
        savedBytes: INITIAL_COUNT,
    };
    for (const directory of directories) {
        for (const file of listFiles(directory)) {
            precompress(file, totals);
        }
    }
    process.stdout.write(
        `precompressed ${totals.assets} text assets into ${totals.sidecars} sidecars (saved ${totals.savedBytes} bytes)\n`,
    );
 };
 main(process.argv.slice(ARGV_PREFIX_LENGTH));
@@ -0,0 +1,66 @@
 #!/bin/sh
 set -eu
 # Print the Keep-a-Changelog section for a release tag, so CI can use it as the
 # body of the Gitea release page without re-implementing CHANGELOG parsing.
 #
 # Run as `scripts/release-notes.sh <tag>`. A leading `v` is tolerated so both
 # `v1.2.3` and `1.2.3` match the `## [1.2.3]` heading. Prints to stdout and
 # exits non-zero when the tag has no section, so a release can never publish
 # with an empty body.
 #
 # Why: development/publishing.md § Release notes are extracted from the changelog.
 TAG="${1:-}"
 CHANGELOG="${CHANGELOG:-CHANGELOG.md}"
 if [ -z "${TAG}" ]; then
    echo "Error: usage: $0 <tag>" >&2
    exit 1
 fi
 if [ ! -f "${CHANGELOG}" ]; then
    echo "Error: ${CHANGELOG} not found." >&2
    exit 1
 fi
 # `v1.2.3` and `1.2.3` are the same release; the heading only ever uses the
 # bare version.
 VERSION="${TAG#v}"
 awk -v version="${VERSION}" '
    # A new section ends the one we are printing (or is the one we want).
    /^## \[/ {
        if (found) exit
        heading = $0
        sub(/^## \[/, "", heading)
        sub(/\].*$/, "", heading)
        if (heading == version) found = 1
        next
    }
    # Link-reference definitions live at the bottom of the file and are never
    # part of the section body. Stopping here keeps the last release notes
    # from picking them up (there is no following heading to stop at).
    /^\[[^]]+\]:/ { exit }
    found {
        if ($0 ~ /^[[:space:]]*$/) {
            # Buffer blank lines so trailing ones at the end of the section
            # are dropped instead of leaking into the release body.
            if (started) pending = pending $0 "\n"
        } else {
            printf "%s%s\n", pending, $0
            pending = ""
            started = 1
        }
    }
    END {
        if (!found) {
            printf "Error: no CHANGELOG section for [%s].\n", version > "/dev/stderr"
            exit 1
        }
    }
 ' "${CHANGELOG}"
@@ -0,0 +1,102 @@
 #!/bin/sh
 set -eu
 # Release front-door. Run as `npm run create:release`.
 #
 # Graduates the [Unreleased] changelog notes, bumps package.json + the lockfile,
 # and commits then tags the exact SHA that CI publishes. The notes are finalized
 # in VS Code before pubv because pubv's bump heuristic reads the [Unreleased]
 # body.
 #
 # Tooling rationale, the rejected alternatives, and the version source of truth:
 # development/publishing.md.
 CHANGELOG="CHANGELOG.md"
 BASE="main"
 if ! command -v code >/dev/null 2>&1; then
    echo "Error: 'code' (VS Code CLI) not found; install it or remove the editor step." >&2
    exit 1
 fi
 # Releases are cut from `main` (see CONTRIBUTING § Publishing workflow). Make
 # that explicit rather than relying on pubv's default-branch check, so the
 # error names `main` even when the remote's default is configured differently.
 CURRENT=$(git symbolic-ref --quiet --short HEAD || true)
 if [ "${CURRENT}" != "${BASE}" ]; then
    echo "Error: releases are cut from '${BASE}', but HEAD is '${CURRENT:-detached}'." >&2
    exit 1
 fi
 # pubv decides the "default branch" by reading the *local*
 # `refs/remotes/origin/HEAD`, not by asking the remote, and `git fetch` never
 # updates that ref. After a default-branch change — or a clone from when the
 # default was different — it goes stale and pubv warns/fails because the
 # current branch (main) does not match it, even though main *is* the remote
 # default. Refresh it from the remote first, so pubv's branch preflight
 # compares against reality. (Without a network this fails, but so would the
 # push pubv is about to do, so it is a real error rather than one to swallow.)
 if ! git remote set-head origin --auto >/dev/null 2>&1; then
    echo "Error: could not refresh origin/HEAD; check connectivity to origin." >&2
    exit 1
 fi
 # The [Unreleased] body drives pubv's bump heuristic, so finalize it first.
 echo "Opening ${CHANGELOG} in VS Code to finalize the release notes..."
 code --wait "${CHANGELOG}"
 # pubv refuses a dirty tree (its "continue with a dirty tree?" prompt defaults
 # to No), so a changed changelog must be committed before it runs. That commit
 # is staging only — the fold below rewrites it into the single release commit.
 NOTES_MSG=":memo: Finalize release notes"
 if [ -n "$(git status --porcelain -- "${CHANGELOG}")" ]; then
    echo "Committing finalized release notes..."
    git add "${CHANGELOG}"
    git commit -m "${NOTES_MSG}"
 fi
 echo "Running pubv..."
 pubv --no-tag --no-push --tag-prefix=none
 echo "Reading version from ${CHANGELOG}..."
 VERSION=$(
    sed -nE 's/^## \[([0-9]+\.[0-9]+\.[0-9]+)\].*/\1/p' "${CHANGELOG}" |
        head -n 1
 )
 if [ -z "${VERSION}" ]; then
    echo "Error: Could not determine release version from ${CHANGELOG}." >&2
    exit 1
 fi
 echo "Release version: ${VERSION}"
 echo "Updating package.json and package-lock.json..."
 npm version "${VERSION}" --no-git-tag-version
 # If pubv's graduation commit sits on top of our staging notes commit, drop it
 # back into the index so the amend below rewrites the notes commit into the one
 # release commit. A message check, not a flag, so a re-run after pubv aborted
 # still folds a notes commit left behind by the earlier attempt.
 if [ "$(git log -1 --format=%s HEAD~1 2>/dev/null || true)" = "${NOTES_MSG}" ]; then
    git reset --soft HEAD~1
 fi
 echo "Amending release commit..."
 git add package.json package-lock.json "${CHANGELOG}"
 # The exact message format is load-bearing: the `release-gate` job in
 # .gitea/workflows/ci.yml recognizes `:rocket: Release x.y.z` on main and
 # skips the full CI run, since the tag push immediately after verifies the
 # identical SHA (and publishes). Keep the two in sync.
 git commit --amend -m ":rocket: Release ${VERSION}"
 echo "Creating tag ${VERSION}..."
 git tag "${VERSION}"
 echo "Pushing release..."
 git push
 git push --tags
 echo "Release ${VERSION} completed."
@@ -0,0 +1,36 @@
 #!/usr/bin/env bash
 set -euo pipefail
 # Build (and optionally push) the CI job image from docker/Dockerfile.
 # Run wherever docker + registry credentials live (the runner host, or any
 # machine that can reach the registry). The registry/repo below MUST match
 # the `container.image` references in .gitea/workflows/ci.yml — the runner
 # pulls the image by name.
 #
 # Usage: scripts/runner-image.sh [--push]
 #
 # Why the image is baked, its two invariants, and the coordinated Node-bump
 # steps: development/ci.md.
 IMAGE_REPO="gitea.e1nsnull.de/tmu/act-ci"
 NODE_VERSION="$(tr -d '[:space:]' < .node-version)"
 if [[ ! "${NODE_VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
    echo "error: .node-version must be pinned to an exact x.y.z, got '${NODE_VERSION}'." >&2
    echo "       setup-node resolves floats like '26' to the latest patch at runtime," >&2
    echo "       which silently busts the tool-cache entry baked into the image." >&2
    exit 1
 fi
 IMAGE="${IMAGE_REPO}:${NODE_VERSION}"
 # --pull: refresh the act base layer so the derivative does not float on an
 # aging default image forever (layer dedup keeps this cheap).
 docker build --pull --build-arg "NODE_VERSION=${NODE_VERSION}" -t "${IMAGE}" -f docker/Dockerfile .
 if [[ "${1:-}" == "--push" ]]; then
    docker push "${IMAGE}"
 fi
 echo "built ${IMAGE}"
 echo "reminder: bump container.image in .gitea/workflows/ci.yml to this tag"
@@ -0,0 +1,8 @@
 export {
    getPrimitiveUnionMatcher,
    getPrimitiveUnionMatcherW,
 } from "./primitive-union.ts";
 export {
    getTaggedUnionMatcher,
    getTaggedUnionMatcherW,
 } from "./tagged-union.ts";
@@ -0,0 +1,101 @@
 import type { IsLiteral, IsNever, ValueOf } from "type-fest";
 // The primitive-union and tagged-union matchers differ in their universe, but the
 // handler/fallback plumbing is identical; these are the shared pieces. The
 // boundary is deliberate: `Handlers`, `Fallback` and `MustBePartial` stay with
 // each matcher because they are built from its universe. See development/library.md.
 // A handler: one universe member in, one return value out.
 export type UnaryFn<T, R> = (shape: T) => R;
 // The primitive universe a matcher can discriminate. The primitive-union matcher
 // uses it directly; the tagged-union matcher uses it as the set of allowed
 // discriminant (`Tag`) values. `boolean` is admitted as the pair `true | false`;
 // see README § Caveats for the unsupported members.
 export type Matchable = string | number | boolean | null | undefined;
 // `boolean`, `null` and `undefined` cannot be property keys, so a mapped type
 // over a universe that includes one keys each such member by its
 // stringification. `Member` inverts that projection against the universe, so a
 // handler callback still receives the *real* member (`true`, not `"true"`).
 // Both matchers use the projection: the primitive-union matcher over its
 // universe, the tagged-union matcher over a discriminant property's values. See
 // README § Caveats for the limits.
 export type PatternKey<T> = T extends boolean
    ? T extends true
        ? "true"
        : "false"
    : T extends null
      ? "null"
      : T extends undefined
        ? "undefined"
        : T;
 // The member(s) of `T` whose `PatternKey` is `K`: the universe-keyed inverse of
 // `PatternKey`. The key alone cannot recover the member (`"true"` and `true`
 // share it), so the handler parameter is derived from `T` instead. For a
 // supported (injective) universe the result is a single member.
 export type Member<
    T extends Matchable,
    K extends PropertyKey,
 > = T extends Matchable ? (PatternKey<T> extends K ? T : never) : never;
 // The property key a `Matchable` member takes at runtime: booleans, `null` and
 // `undefined` stringify, and a numeric literal becomes its decimal string.
 export type Stringified<T> = T extends boolean
    ? T extends true
        ? "true"
        : "false"
    : T extends null
      ? "null"
      : T extends undefined
        ? "undefined"
        : T extends number
          ? `${T}`
          : never;
 // The members of `T` that are also the stringification of another member, so
 // `PatternKey` cannot invert them. `never` means the universe is injective.
 export type Collisions<T> = Extract<T, Stringified<T>>;
 // Why `T` is not a supported universe, or `never` when it is. A supported
 // universe is a finite union of literals with no value/stringification
 // collision: only then can `PatternKey` be inverted unambiguously.
 export type UnsupportedReason<T extends Matchable> =
    IsLiteral<PatternKey<T>> extends true
        ? [Collisions<T>] extends [never]
            ? never
            : `a value and its stringification collide. Value is "${Collisions<T> & string}"`
        : "broad types like string, number and template literals are not supported";
 // The diagnostic for an unsupported universe. Extends `HandlerMap` so the
 // implementation's `handlers: HandlerMap` stays assignable when the gate is
 // intersected into a parameter; the property name is the message.
 export type UnsupportedUniverse<Reason extends string> = HandlerMap &
    Readonly<Record<`unsupported universe: ${Reason}`, never>>;
 // `unknown` for a supported universe (an intersection no-op), the diagnostic
 // otherwise. Intersecting rather than branching keeps `R` inference intact.
 export type UniverseGate<T extends Matchable> =
    IsNever<UnsupportedReason<T>> extends true
        ? unknown
        : UnsupportedUniverse<UnsupportedReason<T>>;
 // `Extract` drops optional handlers (`undefined`) so `PatternReturns` also works
 // when `P`'s constraint has optional keys.
 export type PatternReturns<P> = ReturnType<
    Extract<ValueOf<P>, (...args: never[]) => unknown>
 >;
 // The diagnostic raised when a fallback is supplied for an already-exhaustive
 // handler map. Each matcher's `MustBePartial` folds it into `Handled`'s
 // constraint so the guard is checked after inference.
 export interface RedundantFallback {
    readonly "every case is already handled, so the fallback is redundant": never;
 }
 // The runtime dispatch map the handler maps and fallback erase to.
 export type HandlerMap = Record<
    string | number,
    UnaryFn<never, unknown> | undefined
 >;
@@ -0,0 +1,104 @@
 import type { Exact } from "type-fest";
 import type {
    HandlerMap,
    Matchable,
    Member,
    PatternKey,
    PatternReturns,
    RedundantFallback,
    UnaryFn,
    UniverseGate,
 } from "./matcher-shared.ts";
 type Handlers<T extends Matchable, R> = {
    [K in PatternKey<T>]: UnaryFn<Member<T, K>, R>;
 };
 // The fallback is a *second argument*, not a property of the handler map,
 // because its parameter is the remainder `Exclude<T, Member<T, keyof Handled>>` and TypeScript
 // fixes a property's contextual type before it infers its sibling keys. A later
 // argument, by contrast, is contextually typed from inference on an earlier
 // one, so the split is what makes the remainder expressible at all.
 // See development/library.md.
 type Fallback<T extends Matchable, Handled, R> = UnaryFn<
    Exclude<T, Member<T, keyof Handled>>,
    R
 >;
 // A fallback is redundant once the handler map covers `T`. The guard is folded
 // into `Handled`'s own (self-referential) constraint so it is checked *after*
 // inference; a conditional in the fallback's parameter type is evaluated while
 // `Handled` is still its constraint and would reject context-sensitive partial
 // maps. That placement also fixes where the diagnostic lands: the constraint
 // failure is reported on the argument that inferred `Handled` (the handler
 // map), so the required property is spelled as the message instead of relying
 // on its position. See development/library.md.
 type MustBePartial<T extends Matchable, Handled> =
    PatternKey<T> extends keyof Handled ? RedundantFallback : unknown;
 // TypeScript does not apply the excess-property check to a generic constraint,
 // so `Exact` restores it for the generic forms: a handler map can otherwise
 // carry keys outside `T`.
 // Strict returns: one common `R`. Overload order is load-bearing:
 //   #1 Handlers (first) -> the exhaustive form and the autocomplete popup
 //   #2 Fallback (last)  -> accepts a partial handler map plus a fallback
 interface PrimitiveUnionMatcherStrict<T extends Matchable> {
    <R>(handlers: Handlers<T, R> & UniverseGate<T>): UnaryFn<T, R>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, R>>, Handled> &
            MustBePartial<T, Handled>,
    >(
        handlers: Handled & Partial<Handlers<T, R>> & UniverseGate<T>,
        fallback: Fallback<T, Handled, R> & UniverseGate<T>,
    ): UnaryFn<T, R>;
 }
 // Widened returns: the union of every handler's return type. `P` is inferred
 // from the whole handler map, whose closed constraint supplies the
 // contextual/autocomplete type.
 interface PrimitiveUnionMatcherWidening<T extends Matchable> {
    <P extends Exact<Handlers<T, unknown>, P>>(
        handlers: P & UniverseGate<T>,
    ): UnaryFn<T, PatternReturns<P>>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, unknown>>, Handled> &
            MustBePartial<T, Handled>,
    >(
        handlers: Handled & UniverseGate<T>,
        fallback: Fallback<T, Handled, R> & UniverseGate<T>,
    ): UnaryFn<T, PatternReturns<Handled> | R>;
 }
 const dispatch =
    (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
    (shape: Matchable): unknown =>
        // `handlers[true]` already coerces to the `"true"` property at runtime,
        // identical to `handlers[String(shape)]`, so indexing with `shape`
        // directly is sound: `shape` is a facade-checked universe member and
        // `PatternKey` only ever produces valid property keys. The assertion is
        // needed solely because TypeScript forbids indexing with
        // `boolean`/`null`/`undefined` (TS2538); it buys the number fast path.
        (
            handlers[
                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
                shape as string | number
            ] ??
            fallback ??
            (() => {
                throw new Error(`Unhandled shape: ${String(shape)}`);
            })
        )(
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            shape as never,
        );
 export const getPrimitiveUnionMatcher = <
    T extends Matchable,
 >(): PrimitiveUnionMatcherStrict<T> => dispatch;
 export const getPrimitiveUnionMatcherW = <
    T extends Matchable,
 >(): PrimitiveUnionMatcherWidening<T> => dispatch;
@@ -1,96 +0,0 @@
 :root {
  font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
  line-height: 1.5;
  font-weight: 400;
  color-scheme: light dark;
  color: rgba(255, 255, 255, 0.87);
  background-color: #242424;
  font-synthesis: none;
  text-rendering: optimizeLegibility;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
 }
 a {
  font-weight: 500;
  color: #646cff;
  text-decoration: inherit;
 }
 a:hover {
  color: #535bf2;
 }
 body {
  margin: 0;
  display: flex;
  place-items: center;
  min-width: 320px;
  min-height: 100vh;
 }
 h1 {
  font-size: 3.2em;
  line-height: 1.1;
 }
 #app {
  max-width: 1280px;
  margin: 0 auto;
  padding: 2rem;
  text-align: center;
 }
 .logo {
  height: 6em;
  padding: 1.5em;
  will-change: filter;
  transition: filter 300ms;
 }
 .logo:hover {
  filter: drop-shadow(0 0 2em #646cffaa);
 }
 .logo.vanilla:hover {
  filter: drop-shadow(0 0 2em #3178c6aa);
 }
 .card {
  padding: 2em;
 }
 .read-the-docs {
  color: #888;
 }
 button {
  border-radius: 8px;
  border: 1px solid transparent;
  padding: 0.6em 1.2em;
  font-size: 1em;
  font-weight: 500;
  font-family: inherit;
  background-color: #1a1a1a;
  cursor: pointer;
  transition: border-color 0.25s;
 }
 button:hover {
  border-color: #646cff;
 }
 button:focus,
 button:focus-visible {
  outline: 4px auto -webkit-focus-ring-color;
 }
@media (prefers-color-scheme: light) {
  :root {
    color: #213547;
    background-color: #ffffff;
  }
  a:hover {
    color: #747bff;
  }
  button {
    background-color: #f9f9f9;
  }
 }
@@ -0,0 +1,161 @@
 import type { Exact, SetRequired, UnknownRecord } from "type-fest";
 import type {
    HandlerMap,
    Matchable,
    Member,
    PatternKey,
    PatternReturns,
    RedundantFallback,
    UnaryFn,
    UniverseGate,
 } from "./matcher-shared.ts";
 // A tagged union is discriminated by one property whose values are the tags (a
 // `Matchable`). `string` and `number` tags key a handler map directly;
 // `boolean`, `null` and `undefined` are admitted too but are not property keys,
 // so they go through the `PatternKey` projection. `symbol` has no literal syntax
 // to write a handler under, and `bigint` is not a property key.
 // The discriminant values of `T` under `K`. `Extract` keeps the finite literal
 // tags and leaves a widened `string`/`number` as itself; a broad tag is then
 // rejected by the universe gate.
 type Tags<T extends object, K extends keyof T> = Extract<T[K], Matchable>;
 // The keys of `T` that can act as a discriminant. `getTaggedUnionMatcher<T>()`
 // accepts only these, so the factory rejects a key whose values are not tags.
 type Discriminated<T extends object> = {
    [K in keyof T]: T[K] extends Matchable ? K : never;
 }[keyof T];
 // The member(s) of `T` narrowed to the tag(s) `V`. Distributes over `T`, so a
 // duplicated tag maps to a union of members rather than silently dropping one.
 // A member whose `K` cannot take `V` drops out; the rest have `K` narrowed to
 // `Extract<T[K], V>`. `T[K] extends V` keeps an exact member (a discriminated
 // union's declared interface) untouched, so only a property that is itself a
 // union — or optional — goes through the mapped form. `SetRequired` makes `K`
 // required unless `V` admits `undefined`: a defined tag yields `{ type: "x" }`,
 // while the `undefined` tag keeps `{ type?: never }` (absence) or
 // `{ type?: undefined }` when the property admits an explicit `undefined`.
 // Keyed by `PatternKey`, so `boolean`/`null`/`undefined` tags can key a mapped
 // type; `Member` inverts the projection against the tag set to recover the tag.
 type Narrowed<T extends object, K extends keyof T, V> = T extends object
    ? [Extract<T[K], V>] extends [never]
        ? never
        : T[K] extends V
          ? T
          : undefined extends V
            ? { [P in keyof T]: P extends K ? Extract<T[P], V> : T[P] }
            : SetRequired<
                  { [P in keyof T]: P extends K ? Extract<T[P], V> : T[P] },
                  K
              >
    : never;
 type MapTaggedUnion<T extends object, K extends keyof T> = {
    [P in PatternKey<Tags<T, K>>]: Narrowed<T, K, Member<Tags<T, K>, P>>;
 };
 type Handlers<T extends object, K extends keyof T, R> = {
    [P in PatternKey<Tags<T, K>>]: UnaryFn<MapTaggedUnion<T, K>[P], R>;
 };
 // The tag values whose `PatternKey` is handled.
 type HandledTags<T extends object, K extends keyof T, Handled> = Member<
    Tags<T, K>,
    keyof Handled
 >;
 // The fallback is a *second argument*, not a property of the handler map, so
 // its parameter can be the remainder the map left uncovered: the members
 // narrowed to the tags the map did not handle. See development/library.md.
 type Fallback<T extends object, K extends keyof T, Handled, R> = UnaryFn<
    Narrowed<T, K, Exclude<Tags<T, K>, HandledTags<T, K, Handled>>>,
    R
 >;
 // A fallback is redundant once the handler map covers every tag of `T`. Folded
 // into `Handled`'s own (self-referential) constraint so it is checked *after*
 // inference; see the primitive-union matcher for why a conditional in the fallback's
 // parameter is evaluated too early.
 type MustBePartial<T extends object, K extends keyof T, Handled> =
    PatternKey<Tags<T, K>> extends keyof Handled ? RedundantFallback : unknown;
 // TypeScript does not apply the excess-property check to a generic constraint,
 // so `Exact` restores it for the generic forms.
 // Strict returns: one common `R`. Overload order is load-bearing:
 //   #1 Handlers (first) -> the exhaustive form and the autocomplete popup
 //   #2 Fallback (last)  -> accepts a partial handler map plus a fallback
 interface TaggedUnionMatcherStrict<T extends object, K extends keyof T> {
    <R>(handlers: Handlers<T, K, R> & UniverseGate<Tags<T, K>>): UnaryFn<T, R>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, K, R>>, Handled> &
            MustBePartial<T, K, Handled>,
    >(
        handlers: Handled &
            Partial<Handlers<T, K, R>> &
            UniverseGate<Tags<T, K>>,
        fallback: Fallback<T, K, Handled, R> & UniverseGate<Tags<T, K>>,
    ): UnaryFn<T, R>;
 }
 // Widened returns: the union of every handler's return type. `P` is inferred
 // from the whole handler map, whose closed constraint supplies the
 // contextual/autocomplete type.
 interface TaggedUnionMatcherWidening<T extends object, K extends keyof T> {
    <P extends Exact<Handlers<T, K, unknown>, P>>(
        handlers: P & UniverseGate<Tags<T, K>>,
    ): UnaryFn<T, PatternReturns<P>>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, K, unknown>>, Handled> &
            MustBePartial<T, K, Handled>,
    >(
        handlers: Handled & UniverseGate<Tags<T, K>>,
        fallback: Fallback<T, K, Handled, R> & UniverseGate<Tags<T, K>>,
    ): UnaryFn<T, PatternReturns<Handled> | R>;
 }
 // The key-taking step of the curried factory. Naming it lets the factory return
 // `dispatch` directly, the tacit twin of the primitive-union factory's bare
 // `=> dispatch`.
 type TaggedUnionMatcherFactory<T extends object> = <K extends Discriminated<T>>(
    k: K,
 ) => TaggedUnionMatcherStrict<T, K>;
 type TaggedUnionMatcherWideningFactory<T extends object> = <
    K extends Discriminated<T>,
 >(
    k: K,
 ) => TaggedUnionMatcherWidening<T, K>;
 const dispatch =
    (k: PropertyKey) =>
    (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
    (shape: object): unknown => {
        // `object` carries no index signature, so the read needs the assertion;
        // the factory admits only keys whose values are tags, and the map keys
        // them by `PatternKey`, so the result is narrowed to the map's key space.
        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
        const tag = (shape as UnknownRecord)[k] as string | number;
        return (
            handlers[tag] ??
            fallback ??
            (() => {
                throw new Error(`Unhandled tag: ${String(tag)}`);
            })
        )(
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            shape as never,
        );
    };
 export const getTaggedUnionMatcher = <
    T extends object,
 >(): TaggedUnionMatcherFactory<T> => dispatch;
 export const getTaggedUnionMatcherW = <
    T extends object,
 >(): TaggedUnionMatcherWideningFactory<T> => dispatch;
@@ -1 +0,0 @@
 <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="32" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path fill="#007ACC" d="M0 128v128h256V0H0z"></path><path fill="#FFF" d="m56.612 128.85l-.081 10.483h33.32v94.68h23.568v-94.68h33.321v-10.28c0-5.69-.122-10.444-.284-10.566c-.122-.162-20.4-.244-44.983-.203l-44.74.122l-.121 10.443Zm149.955-10.742c6.501 1.625 11.459 4.51 16.01 9.224c2.357 2.52 5.851 7.111 6.136 8.208c.08.325-11.053 7.802-17.798 11.988c-.244.162-1.22-.894-2.317-2.52c-3.291-4.795-6.745-6.867-12.028-7.233c-7.76-.528-12.759 3.535-12.718 10.321c0 1.992.284 3.17 1.097 4.795c1.707 3.536 4.876 5.649 14.832 9.956c18.326 7.883 26.168 13.084 31.045 20.48c5.445 8.249 6.664 21.415 2.966 31.208c-4.063 10.646-14.14 17.879-28.323 20.276c-4.388.772-14.79.65-19.504-.203c-10.28-1.828-20.033-6.908-26.047-13.572c-2.357-2.6-6.949-9.387-6.664-9.874c.122-.163 1.178-.813 2.356-1.504c1.138-.65 5.446-3.129 9.509-5.485l7.355-4.267l1.544 2.276c2.154 3.29 6.867 7.801 9.712 9.305c8.167 4.307 19.383 3.698 24.909-1.26c2.357-2.153 3.332-4.388 3.332-7.68c0-2.966-.366-4.266-1.91-6.501c-1.99-2.845-6.054-5.242-17.595-10.24c-13.206-5.69-18.895-9.224-24.096-14.832c-3.007-3.25-5.852-8.452-7.03-12.8c-.975-3.617-1.22-12.678-.447-16.335c2.723-12.76 12.353-21.659 26.25-24.3c4.51-.853 14.994-.528 19.424.569Z"></path></svg>
@@ -0,0 +1,147 @@
 import { strict as assert } from "node:assert";
 import path from "node:path";
 import { test } from "node:test";
 import { expectTypeOf } from "expect-type";
 import {
    type CompletionResult,
    type CompletionTarget,
    LspSession,
 } from "#test-utils/lsp-completion.ts";
 const REPO_ROOT = path.resolve(import.meta.dirname, "../../..");
 // The `#test-utils/*` self-reference (package.json#imports) is the one route
 // scattered test files take to reach test helpers; this pins that it resolves
 // and types without starting a language server
 // (development/testing.md § Test helpers).
 test("test-helper home: `#test-utils/…` resolves to the helper and types it", () => {
    // Arrange
    const target: CompletionTarget = {
        file: "src/util/__tests__/lsp-completion.ts",
        source: "",
    };
    // Assert — no session is constructed: the constructor spawns `tsc --lsp`,
    // so only the resolved values and their types are checked here.
    expectTypeOf(LspSession).toBeConstructibleWith("repo-root");
    expectTypeOf<CompletionResult>().toMatchTypeOf<{
        labels: readonly string[];
    }>();
    assert.equal(typeof LspSession, "function");
    assert.equal(target.file, "src/util/__tests__/lsp-completion.ts");
 });
 // The helper drives a language server, so its contract is asserted against the
 // server. Every document below is probed from memory and carries its
 // contextual type inline, so the helper is tested without the library's code.
 const probe = (source: string, marker?: string): Promise<CompletionResult> => {
    const session = new LspSession(REPO_ROOT);
    const target: CompletionTarget =
        marker === undefined
            ? { file: "src/__probe.ts", source }
            : { file: "src/__probe.ts", source, marker };
    return session.completionLabelsAt(target).finally(() => session.close());
 };
 const HANDLERS = [
    "type Handlers = { a: () => number; b: () => number; _?: () => number };",
    "declare const apply: (handlers: Handlers) => Handlers;",
 ];
 test("helper: a fresh object literal completes with its contextual keys", () => {
    // Arrange
    const source = [
        ...HANDLERS,
        "const done = apply({",
        "    /*COMPLETE*/",
        "});",
        "export { done };",
    ].join("\n");
    // Act
    const probed = probe(source);
    // Assert — the position is the marker's, which the helper strips
    expectTypeOf(probed).toEqualTypeOf<Promise<CompletionResult>>();
    return probed.then((result) => {
        assert.deepEqual(result.position, { line: 3, character: 4 });
        assert.deepEqual([...result.labels], ["_?", "a", "b"]);
    });
 });
 test("helper: a handled key drops out of the popup", () => {
    // Arrange
    const source = [
        ...HANDLERS,
        "const done = apply({",
        "    b: () => 1,",
        "    /*COMPLETE*/",
        "});",
        "export { done };",
    ].join("\n");
    // Act
    const probed = probe(source);
    // Assert
    expectTypeOf<CompletionResult["labels"]>().toEqualTypeOf<
        readonly string[]
    >();
    return probed.then((result) => {
        assert.deepEqual([...result.labels], ["_?", "a"]);
    });
 });
 test("helper: a custom marker is located at the line start", () => {
    // Arrange
    const source = [
        "type Handlers = { a: () => number; _?: () => number };",
        "declare const apply: (handlers: Handlers) => Handlers;",
        "const done = apply({",
        "@@@",
        "});",
        "export { done };",
    ].join("\n");
    // Act
    const probed = probe(source, "@@@");
    // Assert
    expectTypeOf(probed).resolves.toEqualTypeOf<CompletionResult>();
    return probed.then((result) => {
        assert.deepEqual(result.position, { line: 3, character: 0 });
        assert.deepEqual([...result.labels], ["_?", "a"]);
    });
 });
 test("helper: labels are read from the server, not from a pattern literal", () => {
    // Arrange
    const source = [
        'const text = "x";',
        "const upper = text./*COMPLETE*/;",
        "export { upper };",
    ].join("\n");
    // Act
    const probed = probe(source);
    // Assert
    expectTypeOf(probed).resolves.toHaveProperty("labels");
    return probed.then((result) => {
        assert.ok(result.labels.includes("toUpperCase"));
    });
 });
 test("helper: a source without the marker rejects", () => {
    // Arrange
    const source = "const text = 1;\nexport { text };\n";
    // Act
    const probed = probe(source);
    // Assert
    expectTypeOf(probed).resolves.toEqualTypeOf<CompletionResult>();
    return assert.rejects(probed, /marker not found/);
 });
@@ -0,0 +1,254 @@
 // oxlint-disable no-magic-numbers unicorn/no-null - tolerable here, this is a helper
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { pathToFileURL } from "node:url";
 import {
    type CompletionItem,
    type CompletionList,
    CompletionRequest,
    ConfigurationRequest,
    createMessageConnection,
    DidOpenTextDocumentNotification,
    InitializedNotification,
    InitializeRequest,
    type MessageConnection,
    ShutdownRequest,
    StreamMessageReader,
    StreamMessageWriter,
 } from "vscode-languageserver-protocol/node";
 /**
 * Print the completion labels TypeScript's language server offers at a marker
 * inside a source file.
 *
 * Usage: node --strip-types src/util/__tests__/lsp-completion.ts <file> [<marker>]
 *
 * The marker (default `DEFAULT_MARKER`, a `COMPLETE` block comment) is stripped
 * from the source before it is sent; the request position is where the marker
 * stood. Point it at a scratch file whose expected type is a matcher pattern to
 * inspect the popup.
 *
 * `LspSession` exposes the same probe to the test suite, so completion is
 * asserted against the server rather than the type system.
 *
 * Why a script and not a type assertion: completion is a contextual-type
 * property that `expect-type` cannot observe, and `Parameters<…>` resolves only
 * a single overload. The server is the only ground truth. See
 * development/testing.md § Autocomplete.
 */
 const DEFAULT_MARKER = "/*COMPLETE*/";
 const ARGV_PREFIX_LENGTH = 2;
 const EXIT_DELAY_MS = 200;
 const FAILURE_EXIT_CODE = 1;
 const USAGE = "usage: lsp-completion.ts <file> [<marker>]";
 export interface Position {
    readonly line: number;
    readonly character: number;
 }
 /** A document to probe: `source` carries `marker`, which is stripped. */
 export interface CompletionTarget {
    /** Path relative to the session's repo root; drives URI and resolution. */
    readonly file: string;
    readonly source: string;
    readonly marker?: string;
 }
 export interface CompletionResult {
    readonly position: Position;
    readonly labels: readonly string[];
 }
 const completionLabels = (
    result: CompletionItem[] | CompletionList | null,
 ): readonly string[] => {
    if (result === null) {
        return [];
    }
    const items = Array.isArray(result) ? result : result.items;
    return items
        .map((item) => item.label)
        .toSorted((left, right) => left.localeCompare(right));
 };
 const markerPosition = (source: string, marker: string): Position => {
    const index = source.indexOf(marker);
    if (index === -1) {
        throw new Error(`marker not found: ${marker}`);
    }
    const lines = source.slice(0, index).split("\n");
    const lineIndex = lines.length - 1;
    const line = lines[lineIndex];
    return { line: lineIndex, character: line === undefined ? 0 : line.length };
 };
 /**
 * One language server, initialized on first use, shared across probes. Callers
 * own the lifecycle and must `close()` it.
 */
 export class LspSession {
    readonly #child: ChildProcessWithoutNullStreams;
    readonly #connection: MessageConnection;
    readonly #repoRoot: string;
    #ready: Promise<void> | undefined;
    public constructor(repoRoot: string) {
        this.#repoRoot = repoRoot;
        this.#child = spawn(
            path.join(repoRoot, "node_modules", ".bin", "tsc"),
            ["--lsp", "--stdio"],
            { cwd: repoRoot },
        );
        this.#child.stderr.on("data", (chunk: Buffer) => {
            process.stderr.write(chunk);
        });
        this.#connection = createMessageConnection(
            new StreamMessageReader(this.#child.stdout),
            new StreamMessageWriter(this.#child.stdin),
        );
        // Server -> client requests the server waits on: answer so it proceeds.
        // `workspace/configuration` wants one reply per requested item; a
        // catch-all covers the rest (e.g. `client/registerCapability`).
        this.#connection.onRequest(ConfigurationRequest.type, ({ items }) =>
            items.map(() => null),
        );
        this.#connection.onRequest(() => null);
        this.#connection.listen();
    }
    public completionLabelsAt(
        target: CompletionTarget,
    ): Promise<CompletionResult> {
        return this.#ensureInitialized()
            .then(() => this.#open(target))
            .then(({ uri, position }) =>
                this.#connection
                    .sendRequest(CompletionRequest.type, {
                        textDocument: { uri },
                        position,
                        context: { triggerKind: 1 },
                    })
                    .then((result) => ({
                        position,
                        labels: completionLabels(result),
                    })),
            );
    }
    /** `shutdown` + close stdin, then kill the server; safe after a failed probe. */
    public close(): Promise<void> {
        return (
            this.#connection
                .sendRequest(ShutdownRequest.type)
                // The TS 7 Go server logs a bare `context canceled` to stderr
                // when it handles `exit`; EOF on stdin shuts it down cleanly
                // (exit 0, no output) instead.
                .then(() => {
                    this.#child.stdin.end();
                })
                .then(() => delay(EXIT_DELAY_MS))
                .finally(() => {
                    this.#connection.dispose();
                    this.#child.kill();
                })
        );
    }
    #ensureInitialized(): Promise<void> {
        this.#ready ??= this.#initialize();
        return this.#ready;
    }
    #initialize(): Promise<void> {
        return this.#connection
            .sendRequest(InitializeRequest.type, {
                processId: process.pid,
                rootUri: pathToFileURL(this.#repoRoot).href,
                workspaceFolders: [
                    { uri: pathToFileURL(this.#repoRoot).href, name: "repo" },
                ],
                capabilities: {
                    textDocument: {
                        completion: {
                            completionItem: { snippetSupport: false },
                        },
                        publishDiagnostics: {},
                    },
                },
            })
            .then(() =>
                this.#connection.sendNotification(
                    InitializedNotification.type,
                    {},
                ),
            );
    }
    #open(target: CompletionTarget): Promise<{
        readonly uri: string;
        readonly position: Position;
    }> {
        const absolute = path.resolve(this.#repoRoot, target.file);
        const marker = target.marker ?? DEFAULT_MARKER;
        const position = markerPosition(target.source, marker);
        const text = target.source.replace(marker, "");
        const uri = pathToFileURL(absolute).href;
        // The server handles `didOpen` in order before the completion request,
        // so no settle delay is needed.
        return this.#connection
            .sendNotification(DidOpenTextDocumentNotification.type, {
                textDocument: {
                    uri,
                    languageId: "typescript",
                    version: 1,
                    text,
                },
            })
            .then(() => ({ uri, position }));
    }
 }
 const main = (args: readonly string[]): Promise<void> => {
    const [file, markerArgument] = args;
    if (file === undefined) {
        process.stderr.write(`${USAGE}\n`);
        process.exitCode = FAILURE_EXIT_CODE;
        return Promise.resolve();
    }
    const repoRoot = path.resolve(import.meta.dirname, "../../..");
    const absolute = path.resolve(repoRoot, file);
    const source = fs.readFileSync(absolute, "utf8");
    const session = new LspSession(repoRoot);
    return session
        .completionLabelsAt({
            file,
            source,
            marker: markerArgument ?? DEFAULT_MARKER,
        })
        .then(({ position, labels }) => {
            process.stdout.write(
                `\n[${file}] completions @ ${position.line}:${position.character}:\n${labels.join(", ")}\n`,
            );
        })
        .finally(() => session.close());
 };
 const isEntryPoint = (): boolean => {
    const [entry] = process.argv.slice(1, 2);
    return entry !== undefined && import.meta.url === pathToFileURL(entry).href;
 };
 if (isEntryPoint()) {
    main(process.argv.slice(ARGV_PREFIX_LENGTH)).catch((error: unknown) => {
        process.stderr.write(
            `${error instanceof Error ? error.message : String(error)}\n`,
        );
        process.exitCode = FAILURE_EXIT_CODE;
    });
 }
@@ -1 +0,0 @@
 /// <reference types="vite/client" />
@@ -0,0 +1,15 @@
 {
    "extends": "./tsconfig.json",
    "compilerOptions": {
        "noEmit": false,
        "target": "es2024",
        "declaration": true,
        "sourceMap": true,
        "inlineSources": true,
        "outDir": "dist",
        "rewriteRelativeImportExtensions": true,
        "rootDir": "src"
    },
    "include": ["src"],
    "exclude": ["src/**/*.test.ts", "src/**/__tests__/**"]
 }
@@ -1,24 +1,12 @@
 {
    "extends": [
        "@tsconfig/node26/tsconfig.json",
        "@tsconfig/strictest/tsconfig.json"
    ],
    "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,
    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "moduleDetection": "force",
        "noEmit": true,
-
+        "allowImportingTsExtensions": true,
-    /* Linting */
+        "verbatimModuleSyntax": true
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedSideEffectImports": true
    },
-  "include": ["src"]
+    "include": ["src", "scripts"]
 }
		`@@ -1 +0,0 @@`
			<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>