🚚 Rename publint script to publish:publint and document prefix convention

publint validates the publishable artifact (dist/ vs package.json),
not the source. It should run only at publish time, in the CI publish
job, not on every commit.

- Rename check:publint -> publish:publint
- Remove from 'check' chain
- Add 'publish:publint' as a step in the CI publish job, right
  before 'npm publish'
- Introduce a 'publish:' script prefix for publish-time-only scripts
- Document the prefix convention (check:, fix:, test:, publish:)
  in project-specs.md (as a top-level subsection under Scripts)
  and in the README
- Add 'publint' and 'stricter' to cspell word list

A new script should pick the prefix that matches its lifecycle, not
invent a new one. The 'publish:' prefix has no 'npm run publish'
aggregator by design (publishing is CI-only).
This commit is contained in:
tmu committed 2026-09-04 18:01:01 +02:00
1 parent 24a3880aad
commit 01d1084e1f
6 files changed
+154 -8

No files matched your search

+49 -4
View File
@@ -157,14 +157,47 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
## 5. Scripts
### PREFIX CONVENTION
Script names 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. Aggregated by `npm run check`
(which runs all `check:*` scripts in order). Called from the
lefthook pre-commit hook on staged files, and from the CI build
job on the full project. Read-only; never modifies files.
- `fix:*` — mutating counterpart of a `check:*` script. There is
**no** `npm run fix` aggregator by design: fixes should be
intentional, not batched. Run individually.
- `test:*` — test scripts. `npm run test` is the canonical entry
point (`check:tsc` + unit tests); `test:unit` skips the typecheck
for fast local iteration; `test:ci` adds c8 coverage and is the
CI variant.
- `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 (see
§7). The `publish:` prefix still documents intent: this script
validates the _publishable artifact_ (e.g., `dist/`) rather than
the source.
A new script should pick the prefix that matches its lifecycle, not
invent a new one. If no existing prefix fits, that is a signal the
script does not belong in the standard pipeline.
### SETUP
- `use:git-commit-message`: Set up commit message template (if needed).
### TEST
- `test`: Run `tsc --noEmit` then `node --test --strip-types src/`.
- `test:unit`: Run unit tests with `node --test --strip-types src/`
- `test`: Run `check:tsc` then `node --test --strip-types "src/**/*.test.ts"`.
The glob is required because Node 26 does not auto-discover test
files in a bare directory argument (`node --test src/` is
interpreted as a module path on Node 26+).
- `test:unit`: Run unit tests with `node --test --strip-types "src/**/*.test.ts"`
(no preceding typecheck).
- `test:ci`: Run tests in CI mode with c8 coverage (text + lcov + html
reporters), uploading `coverage/` as an artifact.
@@ -216,6 +249,16 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
(There is no `fix` aggregator in the scripts; run the `fix:*` scripts
individually.)
### PUBLISH
- `publish:publint`: `publint` — runs the pack-and-lint flow against
the current project (uses `npm pack` to validate the actual
publishable artifact against `package.json`'s `files`, `exports`,
`main`, etc.). Requires a fresh `build` to have populated `dist/`.
Called by the CI `publish` job immediately before `npm publish`
(see §6). Not part of `npm run check` and not run on commit:
it validates publishing correctness, not source correctness.
### HOOKS
- Lefthook runs the relevant `check:*` scripts on staged files in
@@ -235,8 +278,10 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
- `publish` job: only on `refs/tags/*`, depends on `build`. Steps:
`actions/checkout@v4`, `actions/setup-node@v4` (with
`node-version-file: .node-version` and `registry-url`),
`npm ci`, `npm run build`, `npm publish --access public`
with `NODE_AUTH_TOKEN` from secrets.
`npm ci`, `npm run build`, `npm run publish:publint` (see
§5 for why this is `publish:` and not `check:`), and
`npm publish --access public` with `NODE_AUTH_TOKEN` from
secrets.
## 7. Versioning & Publishing