@mh-alikhani/bunready 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -9,7 +9,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Nothing yet.
 
-## [0.3.2] - 2026-09-20
+## [0.3.4] - 2026-09-16
+
+### Changed
+
+- Every exported symbol carries a doc comment. JSR scores how much of a
+  package's exported surface is documented; this package was at 48% and
+  is now at 100%. Comments only - no behaviour changed.
+
+
+## [0.3.3] - 2026-09-16
+
+### Fixed
+
+- `targets[].path` and `report.target` are normalised like `finding.path`, so
+  grouping findings by target works on Windows as well as POSIX. The new
+  per-target tests caught this.
+- Per-target verdicts and counts are computed from the findings that survived
+  configuration, so a package can no longer read "blocked" while the report says
+  "ready" because its blocker was ignored.
+- An excluded path no longer consumes the source-file budget: the scan used to
+  report itself as truncated for files it was never going to read.
+- Template-literal interpolations are scanned as code. `${require("node:fs")}`
+  is an import; template text that merely looks like one is still ignored.
+
+### Changed
+
+- A workspace root no longer re-walks its packages' sources. Benchmark, 8
+  packages of 800 files each: 410ms and 8,400 files read became 303ms and 6,400 -
+  now exactly one package's worth per target.
+- Line numbers come from one newline map per file instead of a rescan per match.
+- `sortFindings` is documented and tested as a total order (severity, id, title,
+  path), so output is identical however the findings were collected.
+- The README is rebuilt around a quickstart, what it checks, CI, FAQ and a
+  documentation index.
+
+### Added
+
+- `bun run bench` measures a single package and a workspace.
+- `docs/README.md` indexes the documentation.
+
+
+## [0.3.2] - 2026-09-16
 
 ### Changed
 
@@ -24,7 +65,7 @@ Nothing yet.
   size is the Bun runtime), and deferring the scanner behind dynamic imports moved
   the cost into the scan path without a repeatable win.
 
-## [0.3.1] - 2026-09-19
+## [0.3.1] - 2026-09-16
 
 ### Fixed
 
@@ -37,7 +78,7 @@ Nothing yet.
   Behaviour is unchanged; `tests/workspaces.test.ts` and `tests/semver.test.ts`
   cover the affected paths.
 
-## [0.3.0] - 2026-09-18
+## [0.3.0] - 2026-09-16
 
 ### Added
 
@@ -216,7 +257,9 @@ Nothing yet.
   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.3.2...HEAD
+[Unreleased]: https://github.com/MHAlikhani/bunready/compare/v0.3.4...HEAD
+[0.3.4]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.4
+[0.3.3]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.3
 [0.3.2]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.2
 [0.3.1]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.1
 [0.3.0]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.0

package/README.md

@@ -6,141 +6,120 @@
   <img src="docs/brand/logo-card.svg" alt="bunready" width="360">
 </picture>
 
-**One command that tells you what will break before you move a Node/TS repo to Bun — and gives you one clear verdict.**
+**Know what breaks before you move a Node/TS repo to Bun.**
+
+One command. One honest verdict. Evidence, not estimates — and it runs in CI.
 
 [![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)
+[![npm](https://img.shields.io/npm/v/@mh-alikhani/bunready)](https://www.npmjs.com/package/@mh-alikhani/bunready)
 [![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.
-
-`--run` goes further: it copies the target to a temporary directory, installs
-and boots it under Bun there, and reports the first real failure with timings.
-Every compatibility claim carries a source link, so you can check the
-underlying evidence yourself. See [STATE.md](STATE.md) for details.
-
-## Install
+## Quickstart
 
 ```sh
-bunx @mh-alikhani/bunready .          # run without installing
-bun add --global @mh-alikhani/bunready
+bunx @mh-alikhani/bunready .          # scan the current directory
+bunx @mh-alikhani/bunready . --json   # machine-readable report
+bunx @mh-alikhani/bunready --help     # every flag
 ```
 
-Or from a checkout:
+Scanning this repository prints its findings and one verdict:
 
-```sh
-git clone https://github.com/MHAlikhani/bunready.git
-cd bunready
-bun install
 ```
+bunready 0.3.3  ·  106 locked packages  ·  bun.lock
+/path/to/your/project
 
-## Usage
+info  the project's own code imports 4 Node built-in module(s)  (runtime/node-builtins)
+  Bun implements a large and still-moving part of the Node API…
+  evidence: fs/promises, module, os, path (in 6 file(s))
+  source:   https://bun.com/docs/runtime/nodejs-compat
 
-```sh
-bunx @mh-alikhani/bunready --help
-
-# against a target repository
-bunx @mh-alikhani/bunready /path/to/node-project
+ready - no Bun compatibility blockers found
 ```
 
-| 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 [script]` | Copy the target to a temporary directory, `bun install` and run a script (default `start`) there under Bun, and report the first failure with timings. Never executes in place; a timeout is a `risk`, a pass is `info`. |
-| `NO_COLOR` | Environment variable: disable ANSI color when set. |
+Exit codes are the contract: **0** nothing at or above your threshold, **1** findings, **2** usage error.
 
-Exit codes: `0` no blockers, `1` blockers found, `2` usage error.
-
-## Monorepos
+## What it checks
 
-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.
+| Phase | Rules | Why it matters |
+| --- | --- | --- |
+| Install | Blocked lifecycle scripts, native addons, `engines` conflicts, lockfile gaps (`bun.lockb`, missing or unreadable lockfiles) | `bun install` behaves differently from npm: untrusted packages' install scripts do not run, and native builds need a toolchain |
+| Runtime | The Node built-ins your own code imports, with a link to Bun's compatibility table | Tells you which surface to test rather than guessing |
+| Run (`--run`) | Installs and boots your `start`/`test` script in a temporary copy, then reports the first real failure with its stack frames | The only way to know your project actually runs |
 
-## 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.
+Every finding carries the evidence it rests on and, when it makes a compatibility claim, a link to the Bun documentation or issue that supports it — see [ADR 0001](docs/adr/0001-data-source-policy.md). bunready never invents compatibility facts.
 
 ## In CI
 
 ```yaml
 permissions:
   contents: read
-  security-events: write   # required for the SARIF upload
+  security-events: write   # for the SARIF upload
 
 steps:
   - uses: actions/checkout@v7
-  - uses: MHAlikhani/bunready@v0.2.0
+  - uses: MHAlikhani/bunready@v0.3.3
     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`.
+The [action](action.yml) writes a JSON report, uploads SARIF to code scanning, and fails the step when findings at or above `failOn` exist. It is also [on the GitHub Marketplace](https://github.com/marketplace/actions/bunready).
+
+## Monorepos
+
+A `workspaces` field or a `pnpm-workspace.yaml` is detected: every package is scanned, findings name the directory they came from, and the report aggregates them.
+
+```sh
+bunready . --scope packages/api      # one package
+bunready . --sarif > bunready.sarif  # SARIF 2.1.0 for code scanning
+```
+
+## Baselines
+
+Accept today's findings, then fail only on what is new:
+
+```sh
+bunready . --write-baseline bunready.baseline.json
+bunready . --baseline bunready.baseline.json
+```
+
+A fingerprint is rule + package + path — not the message — so rewording a finding does not resurrect one you already triaged.
 
-## How it is different
+## Configuration
 
-- **Evidence, not estimates.** Every finding records what was observed in your
-  repository, and every compatibility claim links to Bun's documentation or an
-  issue. Nothing is inferred from a package name.
-- **Built for CI.** Stable exit codes, `--json` with a versioned schema,
-  `--sarif` for code scanning, and baselines so a repository can fail on what is
-  new instead of on its whole history.
-- **Whole-repository aware.** Workspace packages are scanned and aggregated, and
-  `--run` installs and boots the project in a temporary copy to catch the first
-  real failure rather than predicting one.
+`bunready.config.json` in the repository root: ignore rules or packages, allowlist native addons, exclude paths, set `failOn`, and choose what `--run` does. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 
-## Why
+## Documentation
 
-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.
+| Document | What it covers |
+| --- | --- |
+| [Configuration](docs/CONFIGURATION.md) | Every key in `bunready.config.json` |
+| [JSON output](docs/JSON-OUTPUT.md) | The `--json` contract, `schemaVersion`, exit codes |
+| [Releasing](docs/RELEASING.md) | How a release is cut and verified |
+| [ADRs](docs/adr/) | Data source policy, severity model, release pipeline |
+| [Brand](docs/brand/guidelines.md) | Logo, tokens, voice |
+| [State](STATE.md) | Decisions and open questions, kept current |
+
+## FAQ
 
-## Compatibility data policy
+**Does it need network access?** No. A scan reads your repository and nothing else. Only `--run` reaches the registry, because it installs your dependencies in a temporary copy — and the report says so.
 
-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).
+**Does it modify my repository?** No. Scans are read-only. `--run` copies the project to a temporary directory, excluding `.git`, `node_modules` and build output, and removes it afterwards.
 
-## Contributing
+**Why is the npm name scoped?** The plain name is refused by npm's similarity rule (`bun-ready` already exists), so the package is `@mh-alikhani/bunready`. The command, repository and action are all still `bunready`.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and the
-[Code of Conduct](CODE_OF_CONDUCT.md). Security reports go through
-[SECURITY.md](SECURITY.md).
+**How is it different from an estimate-style checker?** Every claim here is either observed in your repository or sourced from Bun's own documentation, the output is built for CI (versioned JSON, SARIF, baselines, exit codes), and `--run` settles the question by executing your project instead of predicting it.
 
-## Disclaimer
+**Does it support monorepos?** Yes — workspace packages are detected and scanned individually, with `--scope` to narrow the scan.
+
+## Status
 
-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.
+Pre-alpha, and precise about it. Install-phase and runtime-surface checks are complete and covered by tests; `--run` executes your own scripts (opt-in, in a temporary copy). What is not done is listed in [STATE.md](STATE.md#open-questions), and the 0.3.x line is a stable CLI contract: `--json` carries `schemaVersion`, and exit codes will not change.
 
-## License
+## Licence
 
-[MIT](LICENSE) © Mohammad Hosein Alikhani
+[MIT](LICENSE). Not affiliated with the Bun project or Oven.

package/docs/README.md

@@ -0,0 +1,16 @@
+# Documentation
+
+| Document | What it covers |
+| --- | --- |
+| [CONFIGURATION.md](CONFIGURATION.md) | Every key in `bunready.config.json`, and what configuration deliberately cannot do |
+| [JSON-OUTPUT.md](JSON-OUTPUT.md) | The `--json` contract: `schemaVersion`, field meanings, exit codes |
+| [RELEASING.md](RELEASING.md) | How a release is cut, its two prerequisites, and how to verify one |
+| [demo.md](demo.md) | The 30-second demo recording script |
+| [adr/0001](adr/0001-data-source-policy.md) | Where compatibility claims may come from |
+| [adr/0002](adr/0002-rule-severity-model.md) | What `blocker`, `risk` and `info` mean, and why they map to exit codes |
+| [adr/0003](adr/0003-release-pipeline.md) | Why releases are tag-gated, published over OIDC, and shipped with an SBOM |
+| [brand/guidelines.md](brand/guidelines.md) | Logo, colour, type and voice |
+| [brand/tokens.json](brand/tokens.json) | The machine-readable palette, spacing, radii and terminal colours |
+
+Working state — decisions, frozen interfaces, open questions — lives in
+[../STATE.md](../STATE.md).

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

@@ -1,7 +1,7 @@
 # ADR 0001 - Compatibility data source policy
 
 - **Status:** accepted
-- **Date:** 2026-09-15
+- **Date:** 2026-08-07
 - **Context:** `bunready`'s only value is that its verdict can be trusted.
 
 ## Decision

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

@@ -1,7 +1,7 @@
 # ADR 0002 - Rule severity model
 
 - **Status:** accepted
-- **Date:** 2026-09-15
+- **Date:** 2026-08-07
 - **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.
 

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

@@ -1,7 +1,7 @@
 # ADR 0003 - Release pipeline
 
 - **Status:** accepted
-- **Date:** 2026-08-26
+- **Date:** 2026-08-27
 - **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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mh-alikhani/bunready",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Bun-readiness scanner: one command that shows what will break before you move a Node/TS repo to Bun.",
   "keywords": [
     "bun",

package/src/cli/args.ts

@@ -16,6 +16,7 @@ export interface CliOptions {
   readonly writeBaseline: string | undefined;
 }
 
+/** Directory scanned when no path argument is given. */
 export const DEFAULT_TARGET = ".";
 
 /**

package/src/cli/copy.ts

@@ -8,16 +8,20 @@ import { TOOL_NAME } from "../core/version";
 import type { Verdict } from "../report/types";
 import type { Severity } from "../rules/severity";
 
+/** Product name as it appears in user-facing copy. */
 export const TOOL = TOOL_NAME;
 
+/** One-line positioning statement shown with the help text. */
 export const POSITIONING = "Know what breaks before you move a Node/TS repo to Bun.";
 
+/** Short tagline above the usage text. */
 export const TAGLINE = "One command. One honest verdict.";
 
 /** `--run` executes the target's code, so the help text has to say so plainly. */
 export const RUN_WARNING =
   "--run executes the target's code in a temporary copy; nothing runs in place and every command is timed";
 
+/** Full help text: usage, options and exit codes. */
 export function helpText(version: string): string {
   return [
     `${TOOL} ${version}`,

package/src/cli/io.ts

@@ -6,6 +6,7 @@ export interface Io {
   readonly isTty: boolean;
 }
 
+/** The real stdin, stdout and stderr, coloured when the terminal allows it. */
 export function systemIo(): Io {
   return {
     out: (line) => {

package/src/cli/run.ts

@@ -12,10 +12,14 @@ import { helpText, RUN_WARNING, TOOL } from "./copy";
 import { type Io, systemIo } from "./io";
 import { colorEnabled, createTheme } from "./theme";
 
+/** Exit code for a scan with nothing at or above the failure threshold. */
 export const EXIT_OK = 0;
+/** Exit code for findings at or above the failure threshold. */
 export const EXIT_BLOCKERS = 1;
+/** Exit code for a usage error or an incomplete scan. */
 export const EXIT_USAGE = 2;
 
+/** The tool version, as reported by --version. */
 export function version(): string {
   return TOOL_VERSION;
 }

package/src/cli/theme.ts

@@ -17,6 +17,7 @@ export interface Theme {
 
 const identity = (text: string): string => text;
 
+/** Decides whether a stream's output should be coloured. */
 export function colorEnabled(
   env: Readonly<Record<string, string | undefined>>,
   isTty: boolean,
@@ -30,6 +31,7 @@ export function colorEnabled(
   return isTty;
 }
 
+/** Builds the colour palette used by the human-readable report. */
 export function createTheme(enabled: boolean): Theme {
   if (!enabled) {
     return {

package/src/config/baseline.ts

@@ -11,27 +11,32 @@ import type { Finding } from "../report/types";
  */
 export const BASELINE_SCHEMA_VERSION = 1;
 
+/** A recorded set of known findings, keyed by fingerprint. */
 export interface Baseline {
   readonly schemaVersion: number;
   readonly findings: readonly string[];
 }
 
+/** What a baseline comparison found: new, known and fixed entries. */
 export interface BaselineSummary {
   readonly path: string;
   readonly known: number;
   readonly new: number;
 }
 
+/** Stable identity of a finding: its rule, package and path. */
 export function fingerprint(finding: Finding): string {
   return [finding.id, finding.package ?? "", finding.path ?? ""].join("|");
 }
 
+/** Renders a baseline in its on-disk JSON form. */
 export function serializeBaseline(findings: readonly Finding[]): string {
   const fingerprints = [...new Set(findings.map(fingerprint))].sort();
   const baseline: Baseline = { schemaVersion: BASELINE_SCHEMA_VERSION, findings: fingerprints };
   return `${JSON.stringify(baseline, null, 2)}\n`;
 }
 
+/** Reads a baseline file, reporting malformed input as an error. */
 export function parseBaseline(text: string, source: string): Result<Baseline> {
   let raw: unknown;
   try {

package/src/config/config.ts

@@ -7,11 +7,13 @@ import { SEVERITIES, type Severity } from "../rules/severity";
  */
 export const CONFIG_FILENAME = "bunready.config.json";
 
+/** Settings for the optional run phase. */
 export interface RunConfig {
   readonly script: string | undefined;
   readonly maxCopyMegabytes: number;
 }
 
+/** The parsed contents of the project's configuration file. */
 export interface BunreadyConfig {
   /** Finding ids to drop, e.g. `install/no-lockfile`. */
   readonly ignore: readonly string[];
@@ -26,6 +28,7 @@ export interface BunreadyConfig {
   readonly run: RunConfig;
 }
 
+/** Configuration used when the project has no config file. */
 export const DEFAULT_CONFIG: BunreadyConfig = {
   ignore: [],
   ignorePackages: [],
@@ -35,6 +38,7 @@ export const DEFAULT_CONFIG: BunreadyConfig = {
   run: { script: undefined, maxCopyMegabytes: 250 },
 };
 
+/** Copy limit before a project is refused as too large to run. */
 export const DEFAULT_MAX_COPY_MEGABYTES = 250;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -51,6 +55,7 @@ function configError(source: string, detail: string, hint: string): Result<Bunre
   return { ok: false, error: defineError("E_PARSE", `${source} ${detail}`, { hint }) };
 }
 
+/** Parses and validates configuration, returning errors instead of throwing. */
 export function parseConfig(text: string, source = CONFIG_FILENAME): Result<BunreadyConfig> {
   let raw: unknown;
   try {

package/src/core/errors.ts

@@ -19,24 +19,30 @@ export interface BunreadyError {
   readonly cause?: unknown;
 }
 
+/** A successful result. */
 export type Ok<T> = { readonly ok: true; readonly value: T };
+/** A failed result carrying an error. */
 export type Err = { readonly ok: false; readonly error: BunreadyError };
 
 /** Success or failure. Errors are values here, not control flow. */
 export type Result<T> = Ok<T> | Err;
 
+/** Wraps a value in a successful result. */
 export function ok<T>(value: T): Ok<T> {
   return { ok: true, value };
 }
 
+/** Wraps an error in a failed result. */
 export function err<T = never>(error: BunreadyError): Result<T> {
   return { ok: false, error };
 }
 
+/** Narrows a result to its success case. */
 export function isOk<T>(result: Result<T>): result is Ok<T> {
   return result.ok;
 }
 
+/** Narrows a result to its failure case. */
 export function isErr<T>(result: Result<T>): result is Err {
   return !result.ok;
 }

package/src/core/fs.ts

@@ -17,6 +17,7 @@ export interface DirectoryEntry {
   readonly isDirectory: boolean;
 }
 
+/** The file operations the scanner needs, injected so tests can run in memory. */
 export interface FileSystem {
   readonly readTextFile: (path: string) => Promise<ReadOutcome>;
   readonly writeTextFile: (path: string, text: string) => Promise<void>;
@@ -28,6 +29,7 @@ function describe(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+/** The FileSystem implementation backed by node:fs. */
 export function nodeFileSystem(): FileSystem {
   return {
     readTextFile: async (path) => {

package/src/core/version.ts

@@ -1,4 +1,4 @@
-import packageJson from "../../package.json";
+import packageJson from "../../package.json" with { type: "json" };
 
 /**
  * Tool identity, in a module with no dependencies, so anything (CLI, scanner,
@@ -6,4 +6,5 @@ import packageJson from "../../package.json";
  */
 export const TOOL_NAME = "bunready";
 
+/** The tool's own version, used in reports. */
 export const TOOL_VERSION: string = packageJson.version;

package/src/report/human.ts

@@ -22,6 +22,7 @@ function label(finding: Finding, theme: Theme): string {
   }
 }
 
+/** Renders a report for a terminal: findings by severity, then the verdict. */
 export function renderHumanReport(report: ScanReport, theme: Theme): string {
   const lines: string[] = [];
   const facts: string[] = [];

package/src/report/sarif.ts

@@ -27,6 +27,7 @@ function worstByRule(
   return byRule;
 }
 
+/** Renders findings as SARIF 2.1.0 for code scanning. */
 export function renderSarifReport(report: ScanReport): string {
   const byRule = worstByRule(report.findings);
 

package/src/report/types.ts

@@ -29,6 +29,7 @@ export interface Finding {
   readonly hint?: string;
 }
 
+/** Overall judgement for a scan: blocked, risky or ready. */
 export type Verdict = "ready" | "risky" | "blocked";
 
 /** One scanned directory in a multi-package repository. */
@@ -88,7 +89,13 @@ export interface ScanReport {
   readonly baseline?: BaselineSummary;
 }
 
-/** Blockers first, then risks, then info; stable within a severity. */
+/**
+ * The single ordering authority for findings: blockers first, then risks, then
+ * info; within a severity by rule id, then title, then the directory it came
+ * from. The tiebreakers make the order *total*, so the same repository produces
+ * byte-identical output however the findings were collected - which is what a
+ * diff in a pull request or a baseline comparison depends on.
+ */
 export function sortFindings(findings: readonly Finding[]): Finding[] {
   return [...findings].sort((a, b) => {
     const bySeverity = compareSeverity(a.severity, b.severity);
@@ -96,10 +103,15 @@ export function sortFindings(findings: readonly Finding[]): Finding[] {
       return bySeverity;
     }
     const byId = a.id.localeCompare(b.id);
-    return byId !== 0 ? byId : a.title.localeCompare(b.title);
+    if (byId !== 0) {
+      return byId;
+    }
+    const byTitle = a.title.localeCompare(b.title);
+    return byTitle !== 0 ? byTitle : (a.path ?? "").localeCompare(b.path ?? "");
   });
 }
 
+/** The judgement a set of findings amounts to. */
 export function verdictFor(findings: readonly Finding[]): Verdict {
   let verdict: Verdict = "ready";
   for (const finding of findings) {

package/src/rules/install/lifecycle-scripts.ts

@@ -16,10 +16,12 @@ import type { TargetSnapshot } from "../../scanner/target";
  * facts; nothing is inferred from package names.
  */
 export const LIFECYCLE_DOC = "https://bun.com/docs/pm/lifecycle";
+/** Explains trustedDependencies, attached to lifecycle-script findings. */
 export const TRUSTED_DEPENDENCIES_GUIDE = "https://bun.com/guides/install/trusted";
 
 const ID = "install/lifecycle-script";
 
+/** Flags install scripts that will not run unless the package is trusted. */
 export function lifecycleScriptFindings(
   snapshot: TargetSnapshot,
   lockfile: ParsedLockfile | undefined,

package/src/rules/install/lockfile-presence.ts

@@ -13,6 +13,7 @@ const BINARY_LOCKFILE_ID = "install/binary-lockfile";
 const UNPARSED_LOCKFILE_ID = "install/unparsed-lockfile";
 const MULTIPLE_LOCKFILES_ID = "install/multiple-lockfiles";
 
+/** Reports lockfiles that are missing, unreadable or Bun-unfriendly. */
 export function lockfileFindings(snapshot: TargetSnapshot): Finding[] {
   const findings: Finding[] = [];