Skip to content

Latest commit

 

History

History
282 lines (218 loc) · 11.3 KB

development-and-release.md

File metadata and controls

282 lines (218 loc) · 11.3 KB

Development and release guide

This guide covers the local development workflow and the release process for Breakcheck's npm packages.

Breakcheck requires Node.js 22 or newer. Use the repository root for all commands unless a command says otherwise.

Set up the repository

git clone https://github.com/cleaver/breakcheck.git
cd breakcheck
npm ci

npm ci installs the versions recorded in package-lock.json. Use npm install when intentionally changing dependencies; commit the resulting package-lock.json with the manifest changes.

Build and test

The root build uses TypeScript project references and builds the packages in dependency order. It also copies the core view assets and restores the executable bit on the CLI entrypoint.

npm run build

The main development commands are:

Command Purpose
npm test Run the unit and component test suite once.
npm run test:coverage Run unit tests and enforce global plus focused coverage thresholds over all production TypeScript in packages/*/src.
npm run typecheck Typecheck production sources and core/CLI test sources without emitting files. Run after a build so workspace declarations are current.
npm run test:watch Run Vitest in watch mode while developing.
npm run test:cli-bin Build the CLI and invoke its compiled executable with native Node.
npm run test:integration Build the project, start the before/after fixture servers, run snapshots and comparisons, and verify the viewer.
npm run test:packaging Pack the core and CLI workspaces, install them in a temporary consumer with no tsx, and exercise the installed CLI, core import, snapshots, comparisons, and viewer.

Coverage includes source files even when no test imports them. It excludes test files, fixture servers, declarations, and generated output. The current global floors are 62% statements, 68% branches, 75% functions, and 62% lines. The check, route validation, baseline update, and site lifecycle modules also have focused 90% line and 80% branch floors. Integration and packaging checks remain separate end-to-end checks and do not contribute to the Vitest coverage totals.

The CLI smoke, integration, and packaging scripts also have :built variants (test:cli-bin:built, test:integration:built, and test:packaging:built). CI uses these after one build per Node matrix job; the regular scripts keep building for standalone local runs.

The integration test owns the fixture-server lifecycle. It starts the before-version server, takes a snapshot, replaces it with the after-version server, takes another snapshot, and then checks both filtered and unfiltered comparisons. Temporary data and processes are cleaned up when the test exits.

For manual fixture debugging, the same servers can be started with a chosen port:

BREAKCHECK_TEST_PORT=4173 npm run test-server:before
# Stop it, then:
BREAKCHECK_TEST_PORT=4173 npm run test-server:after

For CLI development, tsx is intentionally used only by the development scripts; it is not required by consumers of the published package:

npm run dev:cli -- --help
npm run dev:debug -- --help

Before opening a pull request, run the high-value checks used by CI:

npm ci
npm run build
npm run typecheck
npm run test:coverage
npm run test:cli-bin
npm run test:integration
npm run test:packaging
npm audit

CI runs build, typecheck, CLI smoke, integration, and packaging checks on Node.js 22 and 24 for pushes to main and pull requests targeting main. Node 22 also runs the coverage suite and uploads its HTML and JSON reports. A failed integration or packaging run retains command output, snapshots, comparisons, and check reports when BREAKCHECK_DIAGNOSTICS_DIR is set; CI uploads these diagnostics from each Node version on failure. To retain them locally, set that variable to a directory before running npm run test:integration or npm run test:packaging.

The repository also provides optional just recipes for the release workflow. just is not an npm dependency; the npm scripts above remain the canonical development and CI interface.

To test the current unpublished packages from another local project, build fresh tarballs in the Breakcheck checkout:

just local-pack

Then, from the consumer project, install those tarballs without changing its package.json or lockfile:

just -f /path/to/breakcheck/justfile local-install
npx --no-install breakcheck --version

local-pack cleans and recreates .local-breakcheck-packages on every run. Both public packages are packed because the CLI depends on the core package. Use local-install /path/to/consumer when invoking the recipe from the Breakcheck checkout instead. Run npm install or npm ci in the consumer to restore its registry-installed dependencies afterward.

just prerelease

just prerelease checks that the root, core, and CLI release versions match, checks that the CLI dependency on @cleaver/breakcheck-core targets the current core release, requires a clean checkout and npm authentication, confirms that neither publishable package already has that version on npm, runs the complete build, test, audit, and packaging checks, and stops before publishing. On success it prints the exact npm publish commands.

just release runs the same preflight and then publishes core followed by the CLI. Run it from an interactive terminal: npm retains the terminal's input and output, so OTP prompts work normally. If npm needs browser-based login, run npm login first; the recipe does not automate authentication. If the second publish fails after core has been published, inspect the registry and publish only the remaining package rather than rerunning the full preflight.

Prepare a release

Only these workspaces are normally published:

  • @cleaver/breakcheck-core: the programmatic API
  • @cleaver/breakcheck: the breakcheck CLI

Do not use npm publish --workspaces because it would also select the breakcheck-server workspace.

Create a release branch from an up-to-date main, and make the version change in a pull request. Keep the root private package, core package, and CLI package versions synchronized. The server workspace has its own version and is not normally changed for a CLI/core release. Merge the approved version pull request before publishing.

For example, for a patch release:

release_version=0.2.3
npm pkg set version="$release_version"
npm pkg set version="$release_version" --workspace=@cleaver/breakcheck-core
npm pkg set version="$release_version" --workspace=@cleaver/breakcheck
npm install --package-lock-only --ignore-scripts

The equivalent repository helper is:

just bump-version 0.2.3

It updates the root, core, and CLI release versions, updates the core dependency ranges used by the CLI and server workspaces, and refreshes the lockfile. It does not commit, tag, or publish anything.

Review all four files after the update:

node -e 'for (const file of ["package.json", "packages/core/package.json", "packages/cli/package.json", "packages/server/package.json"]) { const packageData = require(`./${file}`); console.log(`${file}: ${packageData.name}@${packageData.version}`); }'
git diff --check

For a minor or major core release, update the CLI and server dependency ranges for @cleaver/breakcheck-core at the same time. Publish core first so that the range required by the CLI is available when npm resolves its dependencies.

Use semantic versioning when choosing the release number. In the 0.x series, a minor version may contain breaking changes; document those changes in the relevant README files.

Validate the release candidate

After the version pull request is merged, update the local checkout and run the complete checks from main before publishing:

git checkout main
git pull --ff-only
npm ci
npm run build
npm run typecheck
npm test
npm run test:coverage
npm run test:cli-bin
npm run test:integration
npm run test:packaging
npm pack --dry-run --workspace=@cleaver/breakcheck-core
npm pack --dry-run --workspace=@cleaver/breakcheck

The core package must contain its compiled JavaScript and declarations, view templates, and public assets. The CLI package must contain an executable dist/index.js with a #!/usr/bin/env node shebang. The packaging test checks the core package contents and verifies that the installed CLI does not need a consumer tsx dependency, a breakcheck-core symlink, or NODE_OPTIONS. The CLI smoke test checks the executable bit; the two npm pack --dry-run commands let you inspect the final file lists.

Confirm the npm account before publishing:

npm whoami
npm view @cleaver/breakcheck-core version
npm view @cleaver/breakcheck version

The publishing account needs permission to publish the @cleaver scope. If the account uses two-factor authentication for publishing, npm will prompt for the one-time password.

Publish

Publish the core package first, then the CLI package:

npm publish --workspace=@cleaver/breakcheck-core --access public
npm view @cleaver/breakcheck-core version

npm publish --workspace=@cleaver/breakcheck --access public
npm view @cleaver/breakcheck version

npm package versions are immutable. If a package has already been published at a version, do not try to republish it; fix the issue in a new patch version.

Verify from a fresh consumer

After publishing, verify the exact version in a directory outside the repository. npx --no-install is important here: it proves the executable comes from the installed package rather than being downloaded or resolved from a development dependency.

consumer_dir=$(mktemp -d)
trap 'rm -rf "$consumer_dir"' EXIT
cd "$consumer_dir"
npm init -y
npm install --save-dev @cleaver/breakcheck@0.2.3
npx --no-install breakcheck --help
npx --no-install breakcheck --version

The version command must print the published CLI version. For the complete snapshot → compare → view check, run the packaging test locally before the release; it uses a temporary local fixture site and exercises the same installed-package path.

Finish the release

Once the published package has passed fresh-consumer verification, create and push a repository tag for the published version, for example:

git tag v0.2.3
git push origin v0.2.3

Optionally create a GitHub release from that tag with the user-facing changes and upgrade notes.

Keep the release version, npm versions, git tag, and release notes aligned.