@mh-alikhani/bunready 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] - 2026-09-09
+
+### Added
+
+- Repository hygiene baseline: `.gitignore`, `.gitattributes`, `.editorconfig`,
+  `LICENSE` (MIT), `README.md`, `CONTRIBUTING.md`, `SECURITY.md`,
+  `CODE_OF_CONDUCT.md`.
+- Git hooks via `simple-git-hooks`: `pre-commit` (Biome on staged files +
+  project typecheck) and `commit-msg` (commitlint, Conventional Commits).
+- Brand system under `docs/brand/`: design tokens, logo variants, favicon,
+  guidelines, and voice/copy reference.
+- Project scaffold: strict ESM `tsconfig.json`, Biome 2.x config, `bun:test`
+  suite, and the `src/{cli,core,rules,report}` layout.
+- CLI skeleton (`src/cli/`): argument parsing, `--help`, `--version`, `--json`,
+  `NO_COLOR` handling, and the documented exit-code contract
+  (`0` clean, `1` blockers, `2` usage error).
+- `src/core/errors.ts`: a `Result` type and an actionable error shape with a
+  `hint` field, so failures cross module boundaries as values rather than
+  thrown exceptions.
+- Architecture decision records `0001` (data source policy) and `0002` (rule
+  severity model).
+- **Scanning.** `bunready <path>` reads `package.json` and the lockfile and
+  prints a real report. The dependency graph is built from `bun.lock`,
+  `package-lock.json`, `yarn.lock` or `pnpm-lock.yaml`.
+- Hand-written lockfile parsers (`src/scanner/lockfile.ts`), covering Bun's JSONC
+  text lockfile, npm v1/v2/v3, Yarn v1 and Berry, and pnpm. A lockfile that
+  cannot be parsed is reported as a finding instead of silently yielding an
+  empty graph.
+- Install-phase rules (`src/rules/install/`): blocked lifecycle scripts
+  (`blocker`), native addons (`risk`), `engines` conflicts, and evidence gaps
+  such as a binary `bun.lockb` or a missing lockfile.
+- Vendored native-package dataset (`src/rules/data/native-packages.json`); every
+  entry carries a source link, and entries assert a property of the package
+  rather than a Bun compatibility claim.
+- Minimal semver range evaluation (`src/scanner/semver.ts`) for `engines`, which
+  reports "could not evaluate" instead of guessing.
+- Report renderers: a human report (`src/report/human.ts`) and `--json`
+  (`src/report/json.ts`), with `ScanReport.stats` for context behind a verdict.
+- Runtime-phase rule (`src/rules/runtime/`): the Node built-in modules the
+  repository's own code imports, reported as an inventory with a link to Bun's
+  compatibility table rather than as a verdict bunready cannot source.
+- Import scanning (`src/scanner/sources.ts`): a regex-based extractor that masks
+  strings and comments first, so a fixture containing import-shaped text is not
+  counted as an import. The walk skips `node_modules` and build output, and
+  reports when it hits its file cap.
+- `ScanReport.stats` now also carries the source-file count and the number of
+  Node built-ins found.
+- Continuous integration: `.github/workflows/ci.yml` runs lint, typecheck, tests
+  with coverage and a build on Ubuntu, macOS and Windows, against both the
+  current Bun release and the exact floor `engines.bun` claims.
+- `.github/workflows/security.yml`: gitleaks secret scanning, CodeQL code
+  scanning (`security-and-quality`) and `bun audit`, on pushes, pull requests and
+  a weekly schedule.
+- `.github/dependabot.yml`: weekly updates for dev dependencies and for GitHub
+  Actions, so the SHA pins stay current.
+- Live CI and security badges in the README.
+- Release pipeline (`.github/workflows/release.yml`): a `v*` tag asserts CI is
+  green on that exact commit, compiles and smoke-tests Linux, macOS and Windows
+  binaries, publishes to npm with provenance over OIDC, and attaches the
+  binaries, `SHA256SUMS` and a CycloneDX SBOM to the GitHub release.
+- `scripts/generate-sbom.ts` and `scripts/checksums.ts`, with the pure logic in
+  `scripts/lib/` so the artifact formats are tested rather than trusted.
+- `docs/RELEASING.md` (process and prerequisites) and
+  `docs/adr/0003-release-pipeline.md` (why OIDC, binaries and a tag gate).
+- `--run`: the target is copied to a temporary directory, dependencies are
+  installed there and its `start` (or `test`) script is booted with `bun run`.
+  The first real failure is captured with its stack frames. Nothing is executed
+  in place, every command is timed, and the copy is removed even when the run
+  fails.
+- `bunready.config.json` (`src/config/`): ignore findings by rule id or package,
+  allowlist native addons, exclude paths, raise or lower `failOn`, and choose the
+  script and copy limit `--run` uses. `--config` points elsewhere; a missing file
+  is an error rather than a silent default. See `docs/CONFIGURATION.md`.
+- `--json` now carries `schemaVersion` and `failOn`, so a CI job can pin the
+  contract and see which threshold produced the exit code.
+  See `docs/JSON-OUTPUT.md`.
+- `--sarif` writes SARIF 2.1.0 for code-scanning upload, generated from the same
+  findings as every other renderer.
+- `--run-script <name>` picks the script to boot, and `--run` refuses a target
+  larger than `run.maxCopyMegabytes` instead of silently skipping it.
+- Workspace support: `workspaces` in package.json or a `pnpm-workspace.yaml` is
+  detected, every package is scanned, the report aggregates them with a `targets`
+  list and a `path` on each finding, and `--scope` narrows a scan to the matching
+  packages. Globs are expanded with a small, documented matcher.
+- Baseline and regression detection: `--write-baseline` records the findings you
+  have accepted, `--baseline` compares against them, marks the rest `new` and
+  fails the run only for those. The fingerprint is rule + package + path.
+- `action.yml`: a composite GitHub Action that scans a repository, uploads the
+  SARIF report to code scanning and fails the step on findings at or above
+  `failOn`. `version: local` runs the action from source, which is how CI tests
+  it before the first publish.
+
+### Fixed
+
+- `.github/workflows/release.yml` was invalid YAML: a secrets expression had been
+  written as a literal `*` alias, and GitHub does not fail loudly for that - it
+  simply refuses to run the workflow. `ci.yml` now parses every workflow file on
+  each pull request so the class of break cannot reach `main` again.
+- `actions/checkout` to v7, `gitleaks/gitleaks-action` to v3, `github/codeql-action`
+  init and analyze to v4 (they must move together), `@commitlint/*` to 21 and
+  TypeScript to 7, with a regenerated lockfile.
+- `engines.bun` now declares `>=1.4.0`. The previous `>=1.2.0` claim was wrong:
+  the committed `bun.lock` is text lockfile format version 2, which Bun 1.2 and
+  1.3 reject with an unknown-lockfile-version error. The CI matrix caught it on
+  its first run.
+- Scanning bunready itself now exits `0`. The `install/lifecycle-script` finding
+  about `simple-git-hooks` was true, so the fix was to list it in
+  `trustedDependencies` rather than to weaken the rule.
+- Workspace glob expansion: `packages/*` and `packages/**` are expanded against
+  the correct parent directory, bounded in depth, and never walk `node_modules`.
+  `finding.path` is also normalised to forward slashes on every platform.
+
+### Changed
+
+- A scan now produces a verdict and an exit code.
+- `--run` executes the target's own script in a temporary copy instead of
+  reporting itself as unimplemented.
+- Paths in findings print with forward slashes, so output is identical on every
+  operating system.
+
+### Notes
+
+- `src/rules/data/node-runtime.json` ships an empty `gaps` list on purpose: each
+  entry would assert that a specific Node built-in is partial or missing in Bun,
+  and that claim needs a primary source. Until then the rule reports what the
+  repository imports and cites the compatibility table.
+
+[Unreleased]: https://github.com/MHAlikhani/bunready/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/MHAlikhani/bunready/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Hosein Alikhani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+<div align="center">
+
+<img src="docs/brand/logo.svg" alt="bunready" width="360">
+
+**One command that tells you what will break before you move a Node/TS repo to Bun — and gives you one clear verdict.**
+
+[![ci](https://github.com/MHAlikhani/bunready/actions/workflows/ci.yml/badge.svg)](https://github.com/MHAlikhani/bunready/actions/workflows/ci.yml)
+[![security](https://github.com/MHAlikhani/bunready/actions/workflows/security.yml/badge.svg)](https://github.com/MHAlikhani/bunready/actions/workflows/security.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![runtime](https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.4-black)](https://bun.sh)
+[![types](https://img.shields.io/badge/TypeScript-strict-3178c6)](tsconfig.json)
+[![status](https://img.shields.io/badge/status-pre--alpha-orange)](#status)
+
+[![npm](https://img.shields.io/npm/v/@mh-alikhani/bunready)](https://www.npmjs.com/package/@mh-alikhani/bunready)
+-->
+
+</div>
+
+---
+
+## Status
+
+Pre-alpha, and precise about it. `bunready <path>` reads `package.json`, any
+lockfile, and the repository's own imports, then prints a report with a verdict
+and an exit code CI can gate on.
+
+What it does not do yet: `--run` (executing the target's scripts under Bun) is
+accepted and reported as unimplemented, and no Node-runtime gap is claimed
+without a source. See [STATE.md](STATE.md) for what exists and what does not.
+
+## Install
+
+```sh
+bunx @mh-alikhani/bunready .          # run without installing
+bun add --global @mh-alikhani/bunready
+```
+
+Or from a checkout:
+
+```sh
+git clone https://github.com/MHAlikhani/bunready.git
+cd bunready
+bun install
+```
+
+## Usage
+
+```sh
+bunx @mh-alikhani/bunready --help
+
+# against a target repository
+bunx @mh-alikhani/bunready /path/to/node-project
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--help` | Print usage and exit. |
+| `--version` | Print the CLI version and exit. |
+| `--json` | Emit machine-readable JSON instead of the terminal report. |
+| `--run` | Planned: run the target's own scripts under Bun in a temporary copy. Not implemented yet; the flag says so before scanning. |
+| `NO_COLOR` | Environment variable: disable ANSI color when set. |
+
+Exit codes: `0` no blockers, `1` blockers found, `2` usage error.
+
+## Monorepos
+
+A `workspaces` field in `package.json`, or a `pnpm-workspace.yaml`, is detected
+automatically: the root and every package are scanned, and the report aggregates
+them with a `targets` list and a `path` on each finding. `--scope packages/api`
+narrows a scan to the matching packages.
+
+## Baselines
+
+```sh
+bunready . --write-baseline bunready.baseline.json   # accept today's findings
+bunready . --baseline bunready.baseline.json         # fail only on new ones
+```
+
+A baseline records rule, package and path - not the message - so rewording a
+finding does not resurrect it.
+
+## In CI
+
+```yaml
+permissions:
+  contents: read
+  security-events: write   # required for the SARIF upload
+
+steps:
+  - uses: actions/checkout@v7
+  - uses: MHAlikhani/bunready@v0.1.0
+    with:
+      path: .
+```
+
+The action writes a JSON report, uploads the SARIF report to code scanning and
+fails the step when findings at or above `failOn` exist. Inputs: `path`,
+`version` (`latest` or `local`), `sarif-file`, `json-file`, `upload`.
+
+## Why
+
+Moving a repo to Bun is usually a pile of small unknowns: which npm lifecycle
+scripts actually run, which APIs are partial, which packages are native, which
+test runner behaviours differ. bunready answers that with evidence and a single
+verdict instead of a checklist you have to interpret yourself.
+
+## Compatibility data policy
+
+Compatibility claims come only from public Bun documentation and issue tracker
+entries, shipped as versioned JSON with source links. We never invent
+compatibility facts. See [ADR 0001](docs/adr/0001-data-source-policy.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[Code of Conduct](CODE_OF_CONDUCT.md). Security reports go through
+[SECURITY.md](SECURITY.md).
+
+## Disclaimer
+
+bunready is an independent, community project. It is **not affiliated with,
+endorsed by, or sponsored by the Bun project, Oven**. "Bun" and
+the Bun logo are trademarks of their respective owners and are used here only
+for descriptive, nominative purposes. bunready ships no Bun code and no Bun
+branding.
+
+## License
+
+[MIT](LICENSE) © Mohammad Hosein Alikhani

package/action.yml

@@ -0,0 +1,89 @@
+name: bunready
+description: Report what will break when a Node or TypeScript repository moves to Bun, and upload the result to code scanning.
+author: MHAlikhani
+branding:
+  icon: check-circle
+  color: orange
+
+inputs:
+  path:
+    description: Repository to scan.
+    required: false
+    default: "."
+  version:
+    description: bunready version to run from npm, or "local" to use the source inside this action.
+    required: false
+    default: latest
+  sarif-file:
+    description: Where to write the SARIF report.
+    required: false
+    default: bunready.sarif
+  json-file:
+    description: Where to write the JSON report.
+    required: false
+    default: bunready.json
+  upload:
+    description: Upload the SARIF report to GitHub code scanning.
+    required: false
+    default: "true"
+
+outputs:
+  exit-code:
+    description: 0 when nothing at or above failOn was found, 1 otherwise.
+    value: ${{ steps.scan.outputs.exit-code }}
+  verdict:
+    description: ready, risky or blocked.
+    value: ${{ steps.scan.outputs.verdict }}
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Bun
+      uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+      with:
+        bun-version: latest
+
+    # The scan itself never fails the step: the SARIF report has to be uploaded
+    # before the exit code is honoured, or code scanning would never see the
+    # findings of a failing run.
+    - name: Scan
+      id: scan
+      shell: bash
+      env:
+        INPUT_VERSION: ${{ inputs.version }}
+        INPUT_PATH: ${{ inputs.path }}
+        INPUT_SARIF: ${{ inputs.sarif-file }}
+        INPUT_JSON: ${{ inputs.json-file }}
+      run: |
+        set -euo pipefail
+
+        if [ "${INPUT_VERSION}" = "local" ]; then
+          scan() { bun run "${GITHUB_ACTION_PATH}/src/cli/index.ts" "$@"; }
+        else
+          scan() { bunx --bun "@mh-alikhani/bunready@${INPUT_VERSION}" "$@"; }
+        fi
+
+        set +e
+        scan "${INPUT_PATH}" --json > "${INPUT_JSON}"
+        status=$?
+        set -e
+
+        verdict=$(node -e 'const fs=require("node:fs");process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1],"utf8")).verdict)' "${INPUT_JSON}")
+
+        printf 'exit-code=%s\n' "${status}" >> "${GITHUB_OUTPUT}"
+        printf 'verdict=%s\n' "${verdict}" >> "${GITHUB_OUTPUT}"
+        printf 'bunready: %s (exit %s)\n' "${verdict}" "${status}" >> "${GITHUB_STEP_SUMMARY}"
+
+        scan "${INPUT_PATH}" --sarif > "${INPUT_SARIF}"
+
+    - name: Upload SARIF
+      if: ${{ inputs.upload == 'true' }}
+      uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+      with:
+        sarif_file: ${{ inputs.sarif-file }}
+        category: bunready
+
+    - name: Fail when bunready reported findings at or above failOn
+      if: ${{ steps.scan.outputs.exit-code != '0' }}
+      shell: bash
+      run: exit 1

package/docs/CONFIGURATION.md

@@ -0,0 +1,44 @@
+# Configuration
+
+`bunready.config.json` in the scanned repository root. Every key is optional; the
+defaults are what you get when the file is absent. `--config <path>` points at a
+different file, and a path that does not exist is an error rather than a silent
+fallback.
+
+```json
+{
+  "ignore": ["install/no-lockfile"],
+  "ignorePackages": ["fsevents"],
+  "nativeAllowlist": ["sharp"],
+  "excludePaths": ["fixtures/"],
+  "failOn": "risk",
+  "run": { "script": "test", "maxCopyMegabytes": 100 }
+}
+```
+
+| Key | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `ignore` | string[] | `[]` | Drops findings by rule id, e.g. `install/no-lockfile`. |
+| `ignorePackages` | string[] | `[]` | Drops findings whose `package` field names one of these dependencies. |
+| `nativeAllowlist` | string[] | `[]` | Packages the native-addon rule never reports. |
+| `excludePaths` | string[] | `[]` | Substring match against source paths; a match skips the file in the import scan. |
+| `failOn` | `blocker` \| `risk` \| `info` | `blocker` | Lowest severity that makes the process exit `1`. |
+| `run.script` | string | first of `start`, `test` | Script booted by `--run`. |
+| `run.maxCopyMegabytes` | number | `250` | Refuses to copy a repository larger than this. Reported as a `risk`, never a silent skip. |
+
+## What configuration cannot do
+
+It cannot change what a rule *claims*. `ignore` and `ignorePackages` suppress a
+finding you have decided is acceptable; they do not rewrite the evidence, and the
+report still exits `0` only because you said so. That is the intended trade: the
+tool stays honest about the repository, and the repository stays honest about
+what it has accepted.
+
+`failOn` is echoed in the `--json` report as `failOn`, so a CI log always shows
+which threshold produced the exit code.
+
+## Precedence
+
+1. CLI flags (`--run-script`, `--config`)
+2. `bunready.config.json` in the target
+3. Built-in defaults

package/docs/JSON-OUTPUT.md

@@ -0,0 +1,50 @@
+# JSON output
+
+`bunready <path> --json` writes a `ScanReport` to stdout and nothing else, so it
+can be piped straight into `jq` or a CI step.
+
+```jsonc
+{
+  "schemaVersion": 1,          // bumped only for a breaking change
+  "failOn": "blocker",         // the threshold that decides the exit code
+  "tool": "bunready",
+  "version": "0.1.0",
+  "target": "/path/to/repo",
+  "verdict": "blocked",        // ready | risky | blocked
+  "counts": { "blocker": 1, "risk": 0, "info": 1 },
+  "findings": [
+    {
+      "id": "install/lifecycle-script",  // stable rule id
+      "severity": "blocker",             // blocker | risk | info
+      "title": "…",
+      "detail": "…",
+      "package": "sharp",                // present when the finding is about one dependency
+      "evidence": "…",                   // what was observed, never a guess
+      "hint": "…",                       // the next step
+      "source": "https://bun.com/docs/pm/lifecycle"  // required for compat claims
+    }
+  ],
+  "stats": { "…": "what the scan looked at" },
+  "run": { "script": "test", "exitCode": 0 }  // only with --run
+}
+```
+
+## Compatibility
+
+`schemaVersion` is the contract. A patch or minor release of bunready never
+changes the meaning of an existing field; a field may be added, and consumers
+should ignore unknown fields. A rename or removal bumps `schemaVersion`.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Nothing at or above `failOn`. |
+| `1` | At least one finding at or above `failOn`. |
+| `2` | Usage error, or the scan could not complete (no `--json` is written in this case). |
+
+## Machine-readable variants
+
+- `--json` - this document.
+- `--sarif` - SARIF 2.1.0 for code-scanning upload. The two are mutually
+  exclusive; passing both is a usage error rather than an ambiguous stream.

package/docs/RELEASING.md

@@ -0,0 +1,65 @@
+# Releasing
+
+Two things must be true before a release can happen, and one of them is not in
+this repository.
+
+## Prerequisites
+
+1. **CI is green on the commit you are tagging.** The release workflow checks
+   this itself and fails closed: it queries the `ci` workflow for a successful
+   run on exactly that SHA. If CI is red or has not run, there is no release.
+2. **Trusted publishing is configured on npmjs.com** (owner action, done once).
+   Open the `@mh-alikhani/bunready` package settings on npmjs.com, add a trusted publisher
+   pointing at this repository, the `release.yml` workflow file, and the `release`
+   environment if you use one. Without this, the publish job fails with an
+   authentication error — by design, because the alternative would be a
+   long-lived token in the repository.
+
+No `NPM_TOKEN` secret exists or is needed. Authentication is OIDC.
+
+## Cutting a release
+
+```sh
+# 1. Make sure main is where you want it, and CI is green
+gh run list --workflow ci.yml --limit 3
+
+# 2. Bump the version and move the changelog entry out of Unreleased
+#    (package.json + CHANGELOG.md), then land it through a pull request
+
+# 3. Tag the release commit and push the tag
+git tag -a v0.1.0 -m "bunready v0.1.0"
+git push origin v0.1.0
+```
+
+The tag is the release. `release.yml` then:
+
+| Step | What it does |
+| --- | --- |
+| `verify` | Refuses to continue unless `ci` succeeded on this SHA. |
+| `binaries` | Compiles and smoke-tests `bunready-linux-x64`, `bunready-darwin-arm64`, `bunready-windows-x64.exe`. |
+| `publish` | `npm publish --provenance --access public` over OIDC. |
+| `release` | Generates `bom.json` (CycloneDX) and `SHA256SUMS`, then attaches all five files to the GitHub release with generated notes. |
+
+## Verifying a release as a user
+
+```sh
+gh release download v0.1.0 --repo MHAlikhani/bunready
+sha256sum -c SHA256SUMS
+```
+
+`bom.json` lists every locked package with a `purl`, so the dependency set behind
+a published version can be read without cloning anything.
+
+## Versioning
+
+Semantic versioning. Until `1.0.0`, a minor bump means new rules, a patch bump
+means fixes to existing behaviour, and any change to the CLI contract (exit
+codes, `--json` fields) gets called out under `### Changed`.
+
+## What is deliberately missing
+
+- **Code signing.** macOS and Windows binaries are unsigned for `v0.1.0`; users
+  will see Gatekeeper and SmartScreen warnings. Signing needs certificates and a
+  budget decision, not just code.
+- **A coverage badge.** Auto-committing one would require write access to
+  protected `main`; see D23 in STATE.md.

package/docs/adr/0001-data-source-policy.md

@@ -0,0 +1,36 @@
+# ADR 0001 - Compatibility data source policy
+
+- **Status:** accepted
+- **Date:** 2026-09-15
+- **Context:** `bunready`'s only value is that its verdict can be trusted.
+
+## Decision
+
+Compatibility claims ship as versioned JSON in `src/rules/data/`, and every
+entry carries `source`, a link to the public Bun documentation or issue that
+establishes the claim. The dataset records the Bun version range it was
+validated against.
+
+Rules may also report **observed facts about the scanned repository** (a native
+addon is present, a lifecycle script exists, an import resolves to a Node
+built-in). Those need no external source: the evidence is the repo itself and is
+printed with the finding.
+
+If a claim has neither a source link nor repo evidence, it does not ship.
+
+## Consequences
+
+- The dataset is reviewable: a reviewer can open every link.
+- Adding a rule requires a source, which keeps rule authorship slow on purpose.
+- The dataset is versioned with the code; the report states which dataset
+  version produced the verdict, so an old verdict stays explainable.
+
+## Rejected alternatives
+
+- **Bundling an upstream compatibility list without links.** Unverifiable, ages
+  badly, and makes us the authority on someone else's runtime.
+- **Asking the network at scan time.** `bunready` must work offline and must
+  never phone home. Data is vendored, not fetched.
+- **Inferring compatibility from package metadata alone.** Would produce
+  confident-sounding guesses; the guardrail is "never invent compatibility
+  facts".

package/docs/adr/0002-rule-severity-model.md

@@ -0,0 +1,42 @@
+# ADR 0002 - Rule severity model
+
+- **Status:** accepted
+- **Date:** 2026-09-15
+- **Context:** The report has to be actionable, and CI has to be able to gate on
+  it, without turning a migration into a wall of red.
+
+## Decision
+
+Every finding carries exactly one severity:
+
+| Severity | Meaning | Exit code effect |
+| --- | --- | --- |
+| `blocker` | The target repo cannot run correctly on Bun until this is fixed. | Process exits `1`. |
+| `risk` | A real hazard that needs a human judgement call; may still be fine. | No effect. |
+| `info` | Context that helps the reader decide. | No effect. |
+
+Exit codes are fixed: `0` no blockers, `1` blockers found, `2` usage error or
+incomplete scan.
+
+Severity is decided by one question: **if the user does nothing, does this break
+at runtime or at install time?** Yes, and unavoidable -> `blocker`. Yes, but
+conditional on how the code is used -> `risk`. No -> `info`.
+
+Colour is presentation only. Every severity prints as a word, so `NO_COLOR`,
+monochrome terminals, and log files keep the full meaning.
+
+## Consequences
+
+- CI gating is a one-line rule (`exit != 0`) and cannot be accidentally
+  configured into a permanent failure by a `risk`.
+- `blocker` is a strong claim, so the bar for assigning it is deliberately high.
+- The severity of every rule must be justified against the single question above
+  in review.
+
+## Rejected alternatives
+
+- **A numeric score.** Implies precision the model does not have, and invites
+  threshold arguments instead of reading the findings.
+- **`error` / `warning`.** Borrows linter vocabulary without the run-time
+  meaning this tool is about.
+- **Letting `risk` fail CI.** Would make the tool unusable on any real repo.

package/docs/adr/0003-release-pipeline.md

@@ -0,0 +1,51 @@
+# ADR 0003 - Release pipeline
+
+- **Status:** accepted
+- **Date:** 2026-08-26
+- **Context:** bunready is a CLI that people will run on their own machines, so
+  "trust the release" has to be something a stranger can verify, not a promise.
+
+## Decision
+
+A release is a tag. Pushing `v*` starts `.github/workflows/release.yml`, which:
+
+1. **Asserts CI is green on the tagged commit.** A tag can point at anything, so
+   the pipeline queries the `ci` workflow for a successful run on exactly that
+   SHA and refuses to continue otherwise.
+2. **Publishes to npm with provenance** using OIDC (`id-token: write`) instead of
+   a long-lived `NPM_TOKEN`. npm signs a statement that the published bytes came
+   from this repository at this commit, verifiable on the registry.
+3. **Builds a compiled binary per platform** (`bun build --compile` for
+   linux-x64, darwin-arm64, windows-x64) and smoke-tests each one by running
+   `--version` before it is allowed to become an artifact. An unsigned binary
+   that does not run is not a release artifact.
+4. **Publishes an SBOM and checksums.** `dist/bom.json` is CycloneDX 1.5,
+   generated from `bun.lock` with bunready's own parser; `dist/SHA256SUMS` uses
+   the `sha256sum` format so verification needs no special tooling.
+
+Every action is pinned to a commit SHA. The only job with write access to the
+repository is the one attaching files to the release; only the publish job can
+mint an OIDC token.
+
+## Consequences
+
+- There is no npm token in this repository to leak or rotate.
+- The first release requires one manual step outside the repository: registering
+  the trusted publisher on npmjs.com (recorded as O10 in STATE.md). Until that is
+  done, the publish job fails closed rather than publishing anonymously.
+- Binaries are unsigned. Users on macOS and Windows will see the usual warnings;
+  code signing is deliberately out of scope for `v0.1.0`.
+- The SBOM inherits the lockfile parser's correctness. That is intentional: the
+  same parser produces the scanner's dependency graph, so a parser bug shows up
+  in both places instead of hiding in one.
+
+## Rejected alternatives
+
+- **Publish on every push to main.** No review point, and a bad commit becomes a
+  bad published version with no way back.
+- **A long-lived `NPM_TOKEN` secret.** Simplest to set up and the most valuable
+  thing in the repository to steal.
+- **Ship TypeScript only.** The `bin` needs a runtime with TypeScript support;
+  compiled binaries are what a user with no Bun installed can actually try.
+- **A hand-written Release notes file.** `--generate-notes` keeps the changelog
+  in the commits, where CI already enforces its shape.