🚚 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:
1 parent
24a3880aad
commit
01d1084e1f
6 files changed
+154
-8
No files matched your search
+49
-4
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user