NPM Package Expert

The Quality Gate (run after every meaningful change)

Work through these steps in order. Do not skip steps, and do not move to the next step until the current one passes.

Step 1 — Lint

# Typically one of:
pnpm run lint     # or npm run lint / yarn lint

Fix all reported errors. For warnings, use judgment — fix anything that represents a real issue, not just stylistic noise.

Step 2 — Format

pnpm run format   # or equivalent

Formatting should be non-negotiable. If there is no format script, check for a .prettierrc / .eslintrc and run the formatter directly.

Step 3 — Tests

pnpm test         # or npm test

All existing tests must pass before you continue.

If you added new functionality, add tests for it now — before building. Tests belong in the same iteration as the code they cover, not as a follow-up. Place tests co-located with the module (.test.ts / .spec.ts) or in a __tests__/ directory, matching whatever convention is already in use.

A good test covers:

• The happy path
• At least one edge case or error path
• Any boundary conditions that are non-obvious

Re-run tests after adding new ones to confirm they all pass.

Step 4 — Build

pnpm run build    # or npm run build

The build must succeed cleanly. Fix any compilation or bundling errors before proceeding. Check that the dist/ (or equivalent output) looks correct and that no test files, source maps, or internal utilities leaked into it.

Step 5 — Version & Changelog

Only bump the version when you are preparing a release. Do not bump the version on every commit — only when the user is ready to publish.

Versioning rules (Semantic Versioning — semver.org):

Update these files together as a single commit:

1. CHANGELOG.md — Add an entry at the top (see format below)
2. package.json — Bump version
3. Any other files that embed the version (e.g., a src/version.ts)

CHANGELOG.md format (Keep a Changelog):

## [1.2.0] - 2026-03-18

### Added

- New `--watch` flag for live reloading

### Fixed

- Resolved edge case where config path was not resolved on Windows

### Changed

- `init` command now prompts for GitHub token interactively

Use sections: Added, Changed, Deprecated, Removed, Fixed, Security. Keep entries human-readable and user-facing — describe the impact, not the implementation.

Step 6 — Diff Review

Before committing, run a mental (and tool-assisted) pass over the full diff:

git diff          # unstaged
git diff --staged # staged

Ask yourself:

• DRY: Is any logic duplicated that could be extracted into a shared utility?
• Simplicity: Is there a shorter, clearer way to express this?
• Correctness: Are there off-by-one errors, unhandled null/undefined, missing await?
• Side effects: Does anything touch global state, the filesystem, or network unexpectedly?
• Dead code: Are there unused imports, variables, or commented-out blocks?

If you spot issues, fix them now and go back to Step 1.

Step 7 — Final Verification

Run tests and build one more time to confirm the cleaned-up code still works:

pnpm test && pnpm run build

If both pass, you are ready to commit.

Step 8 — Commit

Use Conventional Commits format:

<type>(<scope>): <short description>

[optional body]

[optional footer — e.g. BREAKING CHANGE: ...]

Types: feat, fix, chore, docs, refactor, test, build, ci, perf

Examples:

feat(cli): add --dry-run flag to init command
fix(config): resolve path on Windows when HOME contains spaces