tmu/tiny-pattern-ts
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 16 Wiki Activity

🔥 Remove sort-package-json in favor of oxfmt's built-in sortPackageJson

Browse Source
This commit is contained in:
tmu committed 2026-09-03 20:58:17 +00:00
1 parent e45592ae00
commit 7349d0dec2
8 files changed
+102 -187
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

project-specs.md
+78 -73
View File
@@ -27,21 +27,21 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
- `eslint/sort-keys` — handler/case order is semantic, not alphabetical.
- `eslint/id-length` — `T`, `R`, `U`, `V` are standard TS generics.
- `import/no-named-export` — false positive on library entry re-exports.
For `*.test.ts` files additionally: `no-unused-expressions` (for
`expectTypeOf(...)` calls), `no-empty-file` (we have a single import
per test file in some cases), `import/no-nodejs-modules` (we use
`node:test`/`node:assert`/`node:fs` intentionally), `eslint/no-magic-numbers`
(literals in tests are fine).
For `*.test.ts` files additionally: `no-unused-expressions` (for
`expectTypeOf(...)` calls), `no-empty-file` (we have a single import
per test file in some cases), `import/no-nodejs-modules` (we use
`node:test`/`node:assert`/`node:fs` intentionally), `eslint/no-magic-numbers`
(literals in tests are fine).
- **Import sorting**: built into oxfmt (no separate plugin).
- **cspell**: Basic spelling configuration. Words dictionary in `cspell.json`
covers tooling names (`oxlint`, `oxfmt`, `oxc`, `nodenext`,
`oxfmtrc`, `oxlintrc`, `sortpackagerc`, `EDITMSG`, `typescriptteam`,
`oxfmtrc`, `oxlintrc`, `EDITMSG`, `typescriptteam`,
`gitmoji`, `dbaeumer`, `msvc`) and a few library names (`tslib`,
`typefest`, `lefthook`).
- **Lefthook**: Pre-commit checks (run in parallel, lefthook v2 schema).
Single source of truth for the underlying commands is in
`package.json#scripts`; the lefthook config only describes *what to
run on which files*. Hooks that should run on staged files
`package.json#scripts`; the lefthook config only describes _what to
run on which files_. Hooks that should run on staged files
(`oxlint`, `oxfmt`, `cspell`) set the `LEFTHOOK_FILES` env var to
the staged-files list via a `sh -c` wrapper, and the npm script
uses `${LEFTHOOK_FILES:-<default>}` to default to the full project
@@ -52,17 +52,14 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
`sh -c 'LEFTHOOK_FILES="$0" npm run check:oxfmt' {staged_files}`
- `pre-commit.commands.cspell`:
`sh -c 'LEFTHOOK_FILES="$0" npm run check:cspell' {staged_files}`
- `pre-commit.commands.sort-package-json`:
`npm run check:package` (no file args needed)
- `pre-commit.commands.typecheck`:
`npm run check:tsc` (no file args needed)
`outdated` is intentionally NOT a pre-commit check (it can flag
upstream patch releases that aren't actionable locally); it runs in
CI and via the explicit `lefthook run outdated` command.
`outdated` is intentionally NOT a pre-commit check (it can flag
upstream patch releases that aren't actionable locally); it runs in
CI and via the explicit `lefthook run outdated` command.
- **Additional Dev Dependencies**:
- lefthook
- sort-package-json
- check-outdated
- c8 (coverage for `node --test`)
- expect-type (type-level assertions in tests)
@@ -119,7 +116,7 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
- **.npmignore**: Ignore `node_modules/`, `coverage/`, `*.log`,
`*.tsbuildinfo`, `src/`, `.vscode/`, `.editorconfig`,
`.oxfmtrc.json`, `.oxlintrc.json`, `.node-version`, `cspell.json`,
`lefthook.yml`, `.sortpackagerc.json`, `commit-message-template`.
`lefthook.yml`, `commit-message-template`.
(Note: `dist/` is included via `package.json#files`, not by absence
from `.npmignore`.)
- **.oxfmtrc.json**: oxfmt configuration (Prettier-shaped).
@@ -171,27 +168,35 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
### CHECK
- `check`: Run all checks in order — `check:oxlint`, `check:oxfmt`,
`check:tsc`, `check:cspell`, `check:package`, `check:outdated`.
`check:tsc`, `check:cspell`, `check:outdated`.
- `check:oxlint`: `oxlint ${LEFTHOOK_FILES:-src}` — lints `src/`
by default; when invoked from the lefthook pre-commit hook with
`LEFTHOOK_FILES` set to the staged-files list, lints only those
files. This is the single source of truth for the oxlint command
and is shared between the manual `npm run check` and the pre-commit
hook.
- `check:oxfmt`: `oxfmt --check ${LEFTHOOK_FILES:-src}` — same
pattern as `check:oxlint` (whole `src/` by default, staged files
from lefthook).
hook. oxlint only understands JS/TS-family languages, so config
files (JSON/YAML/Markdown) are intentionally outside its scope;
they are checked only by oxfmt.
- `check:oxfmt`: `oxfmt --check ${LEFTHOOK_FILES:-.}` — formats the
whole project (`.`) by default, including JS/TS, JSON/JSONC,
YAML, Markdown, MDX and other supported file types. From lefthook
pre-commit, the `LEFTHOOK_FILES` env var scopes to the staged
files matching `*.{ts,tsx,js,jsx,mjs,cjs,json,jsonc,yaml,yml,md,mdx}`.
Built-in `sortPackageJson: true` keeps `package.json` keys
alphabetized (replaces the former `sort-package-json` tool).
Built-in import sorting (enabled via `sortImports: true`) replaces
any external import-sort plugin.
- `check:tsc`: `tsc --noEmit`.
- `check:cspell`: `cspell lint ${LEFTHOOK_FILES:-.}` — walks the
project root by default; from lefthook, only the staged files.
- `check:package`: `sort-package-json --check`.
- `check:outdated`: `check-outdated --ignore-pre-releases --ignore-packages @oxfmt/binding-*,@oxlint/binding-*`. The oxc native bindings are declared as `optionalDependencies` so the correct one is selected per platform automatically; the `*`-platform bindings show as "not installed" on the current platform and are explicitly ignored here.
### FIX
- `fix:oxlint`: `oxlint --fix src`.
- `fix:oxfmt`: `oxfmt src`.
- `fix:package`: `sort-package-json --write`.
- `fix:oxfmt`: `oxfmt ${LEFTHOOK_FILES:-.}` — same scoping as
`check:oxfmt` (whole project by default, staged files from
lefthook). Writes changes in place.
(There is no `fix` aggregator in the scripts; run the `fix:*` scripts
individually.)
@@ -223,11 +228,11 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
to main and before publishing.
- **Publishing to npm**: Only publish from CI on tagged commits.
- **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
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
@@ -263,16 +268,16 @@ typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starte
- **Source Directory**: All source code resides in `src/` and is
exported via `src/index.ts`.
- **Configuration**:
- `sideEffects: false` in `package.json` (set).
- ESM-only exports; `package.json#exports` field maps `.` to
`{"types": "./dist/index.d.ts", "import": "./dist/index.js"}`.
- Avoid top-level side effects in modules.
- Explicit re-exports in `index.ts` for best results.
- `sideEffects: false` in `package.json` (set).
- ESM-only exports; `package.json#exports` field maps `.` to
`{"types": "./dist/index.d.ts", "import": "./dist/index.js"}`.
- Avoid top-level side effects in modules.
- Explicit re-exports in `index.ts` for best results.
- Source structure (current):
- `src/index.ts` — public barrel.
- `src/match.ts` — `match(value).with(...).exhaustive() / .otherwise(...)` builder.
- `src/pattern.ts` — `P.literal`, `P.type`, `P.when`, `P.any`, `P.shape` constructors and the `Matcher<T>` interface.
- `src/index.test.ts` — runtime + type-level tests using `node --test` + `expect-type`.
- `src/index.ts` — public barrel.
- `src/match.ts` — `match(value).with(...).exhaustive() / .otherwise(...)` builder.
- `src/pattern.ts` — `P.literal`, `P.type`, `P.when`, `P.any`, `P.shape` constructors and the `Matcher<T>` interface.
- `src/index.test.ts` — runtime + type-level tests using `node --test` + `expect-type`.
- The human will implement the source code.
## 11. Included Templates from typescript-lib-starter-tiny
@@ -326,25 +331,25 @@ Resolves #...
- Project title and description
- Development
- Build: `npm run build`
- Test: `npm run test`, `npm run test:ci`
- Checks: `npm run check`, `npm run fix:oxfmt`, `npm run fix:oxlint`
- Build: `npm run build`
- Test: `npm run test`, `npm run test:ci`
- Checks: `npm run check`, `npm run fix:oxfmt`, `npm run fix:oxlint`
- Tooling section listing TypeScript 7, node --test, c8, oxlint, oxfmt,
cspell, sort-package-json, lefthook
cspell, lefthook
- Requirements: Node.js >= 26
- VSCode integration
- Debugging
- Running tests
- oxc.oxc-vscode provides oxlint and oxfmt in-editor
- Debugging
- Running tests
- oxc.oxc-vscode provides oxlint and oxfmt in-editor
- Workflows
- Version updates via `npm version`
- Publishing via GitHub Actions on tagged commits
- Version updates via `npm version`
- Publishing via GitHub Actions on tagged commits
- Contribution guidelines
- Commit signing (GPG)
- How to set up commit message template (`npm run use:git-commit-message`)
- Reference to commit-message-template
- Type-level tests use `expect-type`'s `expectTypeOf(...)` inside
`node --test` cases
- Commit signing (GPG)
- How to set up commit message template (`npm run use:git-commit-message`)
- Reference to commit-message-template
- Type-level tests use `expect-type`'s `expectTypeOf(...)` inside
`node --test` cases
## 12. Project Initialization & Commit Strategy
@@ -353,24 +358,24 @@ Resolves #...
- 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,
`:bug:` for fixes, `:fire:` for removals,
`:white_check_mark:` for tests, `:tada:` for initial commit).
- Example commit messages used in this project:
- `:tada: Initial commit with empty README`
- `:wrench: Track .vscode/settings.json for workspace settings`
- `:construction_worker: Added GitHub Actions workflow for CI/CD`
- `:test_tube: Added Vitest configuration with coverage` (later removed)
- `:sparkles: Scaffolded src/index.ts entry point for library code`
- `:wrench: Replace Vite/Vitest with TypeScript 7 and node --test`
- `:wrench: Replace ESLint and Prettier with oxlint and oxfmt`
- `:fire: Remove Vite scaffold leftovers`
- `:sparkles: Add initial pattern-matching API`
- `:white_check_mark: Add expect-type for type-level tests`
- `:wrench: Declare Node 26 as the supported runtime`
- `:bug: Use .ts extensions in imports for node --strip-types`
- `:wrench: Remove Prettier from editor formatter config`
- Prepend each commit message with a matching gitmoji (e.g.
`:sparkles:` for new features, `:wrench:` for config,
`:bug:` for fixes, `:fire:` for removals,
`:white_check_mark:` for tests, `:tada:` for initial commit).
- Example commit messages used in this project:
- `:tada: Initial commit with empty README`
- `:wrench: Track .vscode/settings.json for workspace settings`
- `:construction_worker: Added GitHub Actions workflow for CI/CD`
- `:test_tube: Added Vitest configuration with coverage` (later removed)
- `:sparkles: Scaffolded src/index.ts entry point for library code`
- `:wrench: Replace Vite/Vitest with TypeScript 7 and node --test`
- `:wrench: Replace ESLint and Prettier with oxlint and oxfmt`
- `:fire: Remove Vite scaffold leftovers`
- `:sparkles: Add initial pattern-matching API`
- `:white_check_mark: Add expect-type for type-level tests`
- `:wrench: Declare Node 26 as the supported runtime`
- `:bug: Use .ts extensions in imports for node --strip-types`
- `:wrench: Remove Prettier from editor formatter config`
- 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
@@ -434,10 +439,10 @@ Resolves #...
```
- `.vscode/extensions.json` recommends:
- `oxc.oxc-vscode` (oxlint + oxfmt, replaces eslint/prettier/vitest)
- `streetsidesoftware.code-spell-checker` (cspell)
- `typescriptteam.native-preview` (TypeScript 7 nightly support;
replaces the older `ms-vscode.vscode-typescript-next`)
- `oxc.oxc-vscode` (oxlint + oxfmt, replaces eslint/prettier/vitest)
- `streetsidesoftware.code-spell-checker` (cspell)
- `typescriptteam.native-preview` (TypeScript 7 nightly support;
replaces the older `ms-vscode.vscode-typescript-next`)
```json
{