tiny-pattern-ts/README.md

# tiny-pattern-ts

Pattern matching for TypeScript/ESM environments (F#-style, not regex).

## Development

- **Build:** `npm run build`
- **Test:** `npm run test`, `npm run test:ci`
- **Watch:** `npm run watch` (re-runs tests on file save; the earliest feedback tier)
- **Checks:** `npm run check`, `npm run fix`
- **Maintenance (advisory):** `npm run maintain` — `knip` + `check-outdated`; run on a maintenance / update-deps branch, not part of the feature loop
- **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`

### Tooling

- **TypeScript 7** — type checker and build (`tsc`).
- **node --test** + `--experimental-strip-types` — test runner (Node 22.6+, flag dropped on Node 24).
- **c8** — code coverage for `test:ci`.
- **oxlint** — Rust-based linter. Type-aware rules are enabled via `options.typeAware: true` in `.oxlintrc.json` (powered by `oxlint-tsgolint`).
- **oxlint-tsgolint** — type-aware linting via typescript-go (declarative via `.oxlintrc.json`, no CLI flag). Catches unsafe type assertions, unnecessary type parameters, and other type-system issues that regular oxlint can't see. Source-level `oxlint-disable` directives are used to silence known false positives (e.g., `expectTypeOf()` in test files).
- **oxfmt** — Rust-based formatter (Prettier-compatible). Formats JS/TS, JSON/JSONC, YAML, Markdown, MDX, and more; built-in `package.json` key sorting replaces `sort-package-json`.
- **cspell** — spell checking.
- **knip** — finds unused dependencies, exports, and files. Scoped via `--include dependencies,exports,files` to skip the noisy `types` category (which produces false positives for libraries whose exported types are part of the public API).
- **publint** — validates `package.json` for ESM publishing correctness. Runs on publish only (in CI), not as part of `npm run check`.
- **@arethetypeswrong/cli** (`attw`) — validates `.d.ts` declarations against multiple module-resolution scenarios. Runs on publish only with `--profile esm-only` (the package is intentionally ESM-only).
- **lefthook** — git pre-commit hooks.

### Tooling decisions

The choice and configuration of each tool above is the result of deliberate trade-offs, not defaults. The non-obvious ones:

- **`tsconfig.json` extends `@tsconfig/strictest` + `@tsconfig/node26`**; `tsconfig.build.json` extends it to add the emit-only options (`declaration`, `sourceMap`, `outDir`, `target: es2024`, `rewriteRelativeImportExtensions: true`) and to exclude test files. This separation lets the editor and CI type-check from one config while the build emits from the other.
- **Source imports use `.ts` extensions** so `node --strip-types` resolves them at test time. `rewriteRelativeImportExtensions: true` in `tsconfig.build.json` rewrites them to `.js` in the emitted `dist/*` output, so consumers see conventional ESM imports.
- **Type-aware oxlint is enabled declaratively** via `options.typeAware: true` in `.oxlintrc.json` (powered by `oxlint-tsgolint`). The script commands stay clean — no CLI flag — and type-aware mode is a property of the config, not the invocation.
- **Source-level `oxlint-disable` directives** are used for known type-aware false positives (see `src/pattern.ts`, `src/match.ts`, `src/index.test.ts`). The disable lives next to the code it silences, not in `.oxlintrc.json`, so the trade-off is visible to anyone reading the source.
- **`knip --include dependencies,exports,files`** intentionally omits the `types` category, which produces systematic false positives for libraries whose exported types are part of the public API. The targeted scope keeps the signal high without config-file boilerplate.
- **`attw --profile esm-only`** is semantically correct: this package is intentionally ESM-only (no CommonJS shim), so CJS resolution scenarios are out of scope by design, not a bug.
- **The `publish:` prefix has no local aggregator.** `publint` and `attw` validate the _publishable artifact_ (`dist/`), not the source, and require a fresh build. They run only in the CI `publish` job immediately before `npm publish` — there is intentionally no `npm run publish`.
- **`check:tsc` runs first** in the `npm run check` chain so a type error short-circuits the rest (faster feedback than letting oxlint/oxfmt run and then failing on tsc at the end).
- **The `check:` / `maintain:` split is correctness gates vs. advisory scans.** `npm run check` is the fast, offline, whole-project correctness ladder (`tsc → oxlint → oxfmt → cspell`) and can run anywhere, including the agent loop. `knip` (~4s, whole project) and `check-outdated` (~6.5s, queries the npm registry) are advisory, not correctness — a stale dependency or an unused export must not fail a feature PR — so they moved to `npm run maintain`, kept out of pre-commit, and run in CI as a **non-blocking** job (see `.github/workflows/ci.yml`). Note `check-outdated` exits non-zero whenever any dep is outdated, which is exactly why it must not gate merges.
- **The pre-commit hook sets the `LEFTHOOK_FILES` env var** to the staged-files list, and the affected scripts use `${LEFTHOOK_FILES:-<default>}` to default to the whole project when invoked manually. This keeps `package.json#scripts` as the single source of truth for the underlying commands — `lefthook.yml` only describes _what to run on which files_.
- **`tslib` and `type-fest` are deliberately not used.** `tslib` is a runtime helper for old ES3/ES5 targets (the project targets ES2024); `type-fest` was never imported. knip caught both.

### Requirements

- Node.js >= 26 (engines field; pinned via `.node-version`).

## VSCode integration

- Recommended extensions: see `.vscode/extensions.json` (oxc, cspell).
- TypeScript 7 is used via the `typescriptteam.native-preview` extension.
- oxc extension provides oxlint squiggles and oxfmt format-on-save.

## Workflows

- Version updates via `npm version`.
- Publishing via GitHub Actions on tagged commits (see `.github/workflows/ci.yml`); the `publish` job runs `publish:publint` and `publish:attw` before `npm publish`.

## Script prefix convention

Script names follow a prefix convention that signals _when_ they run:

- `check:*` — read-only verification. Aggregated by `npm run check`. Used in pre-commit hooks and CI's build job.
- `fix:*` — mutating counterpart of `check:*`. Aggregated by `npm run fix`. Use after `npm run check` to auto-resolve issues.
- `test:*` — test scripts. `npm run test` runs the full suite; `test:unit` / `test:ci` are scope-specific variants.
- `maintain:*` — advisory repo-maintenance scans (dead code, dependency freshness). Aggregated by `npm run maintain`. Whole-project and/or network-bound, so **not** correctness gates: run on a maintenance branch, and in CI as a non-blocking job that reports without failing.
- `publish:*` — runs only at publish time, in the CI `publish` job (immediately before `npm publish`). There is no local `npm run publish` script — publishing is CI-only by policy.

## Contributing

For maintainer and contributor docs — the script prefix convention, the feedback-tier system, the rules the tools don't enforce, and the publishing workflow — see [CONTRIBUTING.md](./CONTRIBUTING.md). AI coding agents: your entry point is [AGENTS.md](./AGENTS.md), which points back to CONTRIBUTING.md.

- Commit signing (GPG).
- Set up commit message template: `npm run use:git-commit-message`.
- See `commit-message-template`.
- Type-only tests use `expect-type`'s `expectTypeOf(...)` inside `node --test` cases.