tiny-pattern-ts/CONTRIBUTING.md

# Contributing

This document is for maintainers and contributors working on the project itself. End-user documentation is in [README.md](./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 below so agents and humans don't diverge.

## 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` resolves the `.ts` form at test time; `rewriteRelativeImportExtensions` emits `.js` in `dist/`. "Pre-fixing" an import to `.js` breaks the inner loop. (rationale: README § Tooling decisions)
- **A new `npm run` script must reuse an existing prefix** (`check:` / `fix:` / `test:` / `watch:` / `maintain:` / `publish:`). If none fits, that's a signal the script doesn't belong in the pipeline — not a reason to invent a new 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 these — see [AGENTS.md § Never do](./AGENTS.md#never-do). (rationale: README § Tooling decisions)
- **Don't put slow / network / whole-project scans in `check` or pre-commit.** Advisory scans are not correctness gates; they belong under `maintain:`. (see [Feedback tiers](#feedback-tiers) and [Script prefix convention](#script-prefix-convention))
- **There is no local `npm run publish`, and `publish:publint` / `publish:attw` don't go in `check`.** (see [Publishing workflow](#publishing-workflow))

## Commit messages

Gitmoji subject, imperative mood, 50/72 wrapping. The template is `commit-message-template`; run `npm run use:git-commit-message` once after cloning to register it as git's `commit.template`.

Examples from history: `: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 #...`.

## 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. Picking the right prefix documents the script's intended lifecycle:

- `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`; currently a single child (`watch:test`), and a future `watch:oxlint` / `watch:tsc` would run concurrently under that umbrella.
- `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. (see [Rules the tools don't enforce](#rules-the-tools-dont-enforce) and [Publishing workflow](#publishing-workflow))

A new script should pick the prefix that matches its lifecycle, not invent a new one. If no existing prefix fits, that's a signal the script doesn't belong in the standard pipeline.

Separately, some top-level scripts are **bare** (no prefix): the entry points that either run a single tool (`build`, `clean`) or aggregate a `prefix:*` family (`check`, `fix`, `test`, `watch`, `maintain`), plus `verify` — a cross-cutting convenience composing `check` + `test:unit` into one whole-project correctness gate. It deliberately uses `test:unit` rather than `test` because `check` already runs `check:tsc`, so the type checker runs exactly once. Bare commands are how you invoke a tier; the `prefix:*` scripts are what those tiers are made of.

## 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/PR             | `npm run check` + `npm run test:ci`                                   | ~30s+ |
| CI maintain (auto, non-blocking) | on push/PR             | `npm run maintain` — reports, never fails the build                   | ~10s  |
| CI publish (auto)                | on tag                 | `publish:publint` + `publish:attw`, then `npm publish`                | ~10s  |

### Why these splits?

- **`watch:*` is a manual tier, not a hook.** The developer starts it on demand (it has to be killed with Ctrl-C) and it runs in a dedicated terminal pane. It sits as the earliest tier in the feedback ladder, catching failures the moment a file is saved — before staging, before commit.
- **`check:tsc`, `check:oxlint`, `check:oxfmt`, `check:cspell`** are in pre-commit because they are fast (~0.2–0.5s each), fully offline, and naturally scope to staged files via the `LEFTHOOK_FILES` env var convention. They give instant feedback on what you typed.
- **`test` (and the `tsc` it includes) is in pre-push** because it runs the whole test suite across the whole project. The pre-commit `LEFTHOOK_FILES` convention doesn't apply to the test runner, so pre-commit isn't the right home. Pre-push runs after all commits are made but before the push leaves the machine, catching regressions that span multiple commits.

### Before pushing

Run `npm run verify` — the one-shot correctness gate in the table above. Run `npm run maintain` only on a maintenance / update-deps branch.

## Publishing workflow

Publishing is CI-only by policy. Local `npm publish` is not supported.

1. Develop and merge PRs to `main`.
2. CI runs `npm run check` + `npm run test:ci` on every push and PR — this is the authoritative gate.
3. After all intended changes are on `main`, bump the version locally:
    ```sh
    npm version <patch|minor|major>
    ```
4. Push the tag to GitHub:
    ```sh
    git push --follow-tags origin main
    ```
5. The `publish` CI job runs on the tag: `build` → `publish:publint` → `publish:attw` → `npm publish --access public`. The publish-tier checks must pass before the artifact is published.