@mh-alikhani/bunready 0.1.0

package/src/report/sarif.ts

@@ -0,0 +1,73 @@
+import { compareSeverity, type Severity } from "../rules/severity";
+import type { Finding, ScanReport } from "./types";
+
+/**
+ * SARIF 2.1.0 output, so the same findings can be uploaded to GitHub code
+ * scanning (or any SARIF consumer) without a second implementation of the rules.
+ */
+const LEVELS: Readonly<Record<Severity, string>> = {
+  blocker: "error",
+  risk: "warning",
+  info: "note",
+};
+
+const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+const INFORMATION_URI = "https://github.com/MHAlikhani/bunready";
+
+function worstByRule(
+  findings: readonly Finding[],
+): Map<string, { severity: Severity; sample: Finding }> {
+  const byRule = new Map<string, { severity: Severity; sample: Finding }>();
+  for (const finding of findings) {
+    const existing = byRule.get(finding.id);
+    if (existing === undefined || compareSeverity(finding.severity, existing.severity) < 0) {
+      byRule.set(finding.id, { severity: finding.severity, sample: finding });
+    }
+  }
+  return byRule;
+}
+
+export function renderSarifReport(report: ScanReport): string {
+  const byRule = worstByRule(report.findings);
+
+  const rules = [...byRule.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([id, entry]) => ({
+      id,
+      name: id.replace(/[^A-Za-z0-9]+/g, "-"),
+      shortDescription: { text: entry.sample.title },
+      fullDescription: { text: entry.sample.detail },
+      defaultConfiguration: { level: LEVELS[entry.severity] },
+      ...(entry.sample.source === undefined ? {} : { helpUri: entry.sample.source }),
+    }));
+
+  const results = report.findings.map((finding) => ({
+    ruleId: finding.id,
+    level: LEVELS[finding.severity],
+    message: { text: `${finding.title}. ${finding.detail}` },
+    locations: [{ physicalLocation: { artifactLocation: { uri: finding.path ?? report.target } } }],
+    partialFingerprints: { bunreadyFinding: `${finding.id}:${finding.title}` },
+  }));
+
+  return JSON.stringify(
+    {
+      $schema: SARIF_SCHEMA,
+      version: "2.1.0",
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: report.tool,
+              version: report.version,
+              informationUri: INFORMATION_URI,
+              rules,
+            },
+          },
+          results,
+        },
+      ],
+    },
+    null,
+    2,
+  );
+}

package/src/report/types.ts

@@ -0,0 +1,114 @@
+import { compareSeverity, type Severity } from "../rules/severity";
+
+/** The `--json` contract version. Bumped only for a breaking field change. */
+export const SCHEMA_VERSION = 1;
+
+/**
+ * A single thing bunready can say about a target repo.
+ *
+ * Every finding must be traceable to evidence: either something observed in the
+ * scanned repository (`evidence`) or a public Bun documentation / issue entry
+ * (`source`). A finding with neither should not ship.
+ */
+export interface Finding {
+  /** Stable rule id, namespaced by phase, e.g. `install/native-addon`. */
+  readonly id: string;
+  readonly severity: Severity;
+  readonly title: string;
+  readonly detail: string;
+  /** The dependency this finding is about, when there is one. */
+  readonly package?: string;
+  /** The scanned directory this finding came from; set when more than one was scanned. */
+  readonly path?: string;
+  /** Present when a baseline was applied: false means it was already accepted. */
+  readonly isNew?: boolean;
+  /** Observed proof from the scanned repo, e.g. the offending dependency. */
+  readonly evidence?: string;
+  /** Link to the Bun doc or issue backing the compatibility claim. */
+  readonly source?: string;
+  readonly hint?: string;
+}
+
+export type Verdict = "ready" | "risky" | "blocked";
+
+/** One scanned directory in a multi-package repository. */
+export interface ScannedTarget {
+  readonly path: string;
+  readonly relative: string;
+  readonly kind: "root" | "workspace";
+  readonly name: string | undefined;
+  readonly verdict: Verdict;
+  readonly counts: Readonly<Record<Severity, number>>;
+}
+
+/** What a baseline did, when one was applied. */
+export interface BaselineSummary {
+  readonly path: string;
+  readonly known: number;
+  readonly new: number;
+}
+
+/** What `--run` actually did, so a run result can be read without the log. */
+export interface RunSummary {
+  readonly script: string | undefined;
+  readonly installExitCode: number | null;
+  readonly exitCode: number | null;
+  readonly timedOut: boolean;
+  readonly durationMs: number | undefined;
+  readonly firstFailure: string | undefined;
+}
+
+/** What the scan looked at, so a verdict can be read in proportion. */
+export interface ScanStats {
+  readonly directDependencies: number;
+  readonly devDependencies: number;
+  readonly lockedPackages: number;
+  readonly duplicateVersions: number;
+  readonly lockfiles: readonly string[];
+  readonly sourceFiles: number;
+  readonly nodeBuiltins: number;
+}
+
+/** The machine-readable shape emitted by `--json`. */
+export interface ScanReport {
+  /** Bumped when a field is renamed or removed. CI can pin on it. */
+  readonly schemaVersion: number;
+  /** Lowest severity that makes this report fail; the exit code follows it. */
+  readonly failOn: Severity;
+  readonly tool: string;
+  readonly version: string;
+  readonly target: string;
+  readonly verdict: Verdict;
+  readonly counts: Readonly<Record<Severity, number>>;
+  readonly findings: readonly Finding[];
+  readonly stats?: ScanStats;
+  readonly run?: RunSummary;
+  /** Present only when more than one directory was scanned. */
+  readonly targets?: readonly ScannedTarget[];
+  readonly baseline?: BaselineSummary;
+}
+
+/** Blockers first, then risks, then info; stable within a severity. */
+export function sortFindings(findings: readonly Finding[]): Finding[] {
+  return [...findings].sort((a, b) => {
+    const bySeverity = compareSeverity(a.severity, b.severity);
+    if (bySeverity !== 0) {
+      return bySeverity;
+    }
+    const byId = a.id.localeCompare(b.id);
+    return byId !== 0 ? byId : a.title.localeCompare(b.title);
+  });
+}
+
+export function verdictFor(findings: readonly Finding[]): Verdict {
+  let verdict: Verdict = "ready";
+  for (const finding of findings) {
+    if (finding.severity === "blocker") {
+      return "blocked";
+    }
+    if (finding.severity === "risk") {
+      verdict = "risky";
+    }
+  }
+  return verdict;
+}

package/src/rules/data/native-packages.json

@@ -0,0 +1,81 @@
+{
+  "datasetVersion": "2026-09-15.1",
+  "note": "Packages that are known to ship a native addon or to download a platform binary at install time. Each entry asserts a property of the PACKAGE (visible in its own published metadata), not a Bun compatibility claim. bunready never asserts that one of these will fail on Bun; it reports the build step so the user can check their own platform. Entries are only added with a source link, per docs/adr/0001-data-source-policy.md.",
+  "packages": [
+    {
+      "name": "better-sqlite3",
+      "reason": "Native addon built with node-gyp; needs a matching prebuild or a working C++ toolchain.",
+      "source": "https://www.npmjs.com/package/better-sqlite3"
+    },
+    {
+      "name": "sharp",
+      "reason": "Ships prebuilt libvips binaries per platform and rebuilds from source when no prebuild matches.",
+      "source": "https://www.npmjs.com/package/sharp"
+    },
+    {
+      "name": "canvas",
+      "reason": "Native addon built with node-gyp against system cairo/pango libraries.",
+      "source": "https://www.npmjs.com/package/canvas"
+    },
+    {
+      "name": "bcrypt",
+      "reason": "Native addon built with node-gyp; the prebuild is platform specific.",
+      "source": "https://www.npmjs.com/package/bcrypt"
+    },
+    {
+      "name": "sqlite3",
+      "reason": "Native addon built with node-gyp, with a prebuild download step.",
+      "source": "https://www.npmjs.com/package/sqlite3"
+    },
+    {
+      "name": "node-sass",
+      "reason": "Native addon with a binary download step; deprecated upstream in favour of dart-sass.",
+      "source": "https://www.npmjs.com/package/node-sass"
+    },
+    {
+      "name": "argon2",
+      "reason": "Native addon built with node-gyp.",
+      "source": "https://www.npmjs.com/package/argon2"
+    },
+    {
+      "name": "leveldown",
+      "reason": "Native LevelDB binding built with node-gyp.",
+      "source": "https://www.npmjs.com/package/leveldown"
+    },
+    {
+      "name": "zeromq",
+      "reason": "Native addon with a bundled build step for libzmq.",
+      "source": "https://www.npmjs.com/package/zeromq"
+    },
+    {
+      "name": "isolated-vm",
+      "reason": "Native addon built with node-gyp.",
+      "source": "https://www.npmjs.com/package/isolated-vm"
+    },
+    {
+      "name": "node-pty",
+      "reason": "Native addon built with node-gyp or fetched as a prebuild.",
+      "source": "https://www.npmjs.com/package/node-pty"
+    },
+    {
+      "name": "bufferutil",
+      "reason": "Optional native addon with a node-gyp fallback build.",
+      "source": "https://www.npmjs.com/package/bufferutil"
+    },
+    {
+      "name": "utf-8-validate",
+      "reason": "Optional native addon with a node-gyp fallback build.",
+      "source": "https://www.npmjs.com/package/utf-8-validate"
+    },
+    {
+      "name": "puppeteer",
+      "reason": "Downloads a Chromium build in a postinstall script.",
+      "source": "https://www.npmjs.com/package/puppeteer"
+    },
+    {
+      "name": "@prisma/client",
+      "reason": "Runs a postinstall that generates and downloads query engine binaries.",
+      "source": "https://www.npmjs.com/package/@prisma/client"
+    }
+  ]
+}

package/src/rules/data/node-runtime.json

@@ -0,0 +1,6 @@
+{
+  "datasetVersion": "2026-09-15.1",
+  "compatibilityDocs": "https://bun.com/docs/runtime/nodejs-compat",
+  "note": "Runtime compatibility data. `gaps` is intentionally EMPTY: every entry here asserts that a specific Node built-in is partial or missing, and that claim needs a primary source that was read, not remembered. Bun's own position is that a package working in Node.js and failing in Bun is a bug in Bun, so a module is only listed once a specific issue or documentation entry establishes the gap. Until then bunready reports what the repository imports and points at the compatibility table instead of guessing.",
+  "gaps": []
+}

package/src/rules/install/engines.ts

@@ -0,0 +1,74 @@
+import type { Finding } from "../../report/types";
+import type { Manifest } from "../../scanner/manifest";
+import { satisfies } from "../../scanner/semver";
+
+/** The runtime the scan is running under, injected so tests are deterministic. */
+export interface RuntimeInfo {
+  readonly bun: string;
+  readonly node: string;
+}
+
+/**
+ * `engines` conflicts.
+ *
+ * A declared Bun range that the running Bun does not satisfy is a blocker: the
+ * project states it needs a different runtime, and no amount of user patience
+ * changes that. A declared Node range that Bun's Node compatibility layer does
+ * not satisfy is a risk, because Bun's compatibility work often covers an
+ * older range than the project asks for, and only the project's own tests can
+ * settle it. A range we cannot parse is reported as info, never as a failure.
+ */
+export function enginesFindings(manifest: Manifest, runtime: RuntimeInfo): Finding[] {
+  const findings: Finding[] = [];
+
+  const bunRange = manifest.engines.bun;
+  if (bunRange !== undefined) {
+    const satisfied = satisfies(runtime.bun, bunRange);
+    if (satisfied === false) {
+      findings.push({
+        id: "install/engines-bun",
+        severity: "blocker",
+        title: `this project requires Bun ${bunRange}`,
+        detail: "The running Bun does not satisfy the range this project declares in package.json.",
+        evidence: `engines.bun = "${bunRange}", running Bun ${runtime.bun}`,
+        hint: `switch to a Bun version matching ${bunRange} before running this project.`,
+      });
+    } else if (satisfied === undefined) {
+      findings.push({
+        id: "install/engines-bun",
+        severity: "info",
+        title: "could not evaluate the declared Bun range",
+        detail:
+          "bunready evaluates a subset of semver (comparators, caret, tilde, x-ranges, hyphen ranges, `||`). This range uses syntax outside that subset, so it was reported instead of judged.",
+        evidence: `engines.bun = "${bunRange}", running Bun ${runtime.bun}`,
+      });
+    }
+  }
+
+  const nodeRange = manifest.engines.node;
+  if (nodeRange !== undefined) {
+    const satisfied = satisfies(runtime.node, nodeRange);
+    if (satisfied === false) {
+      findings.push({
+        id: "install/engines-node",
+        severity: "risk",
+        title: `this project declares Node ${nodeRange}`,
+        detail:
+          "Bun reports a different Node compatibility version, so any code path that depends on Node-version-specific behaviour should be exercised before the move.",
+        evidence: `engines.node = "${nodeRange}", Bun reports Node ${runtime.node}`,
+        hint: "check the project's own test suite under Bun; a Node range alone does not decide Bun compatibility.",
+      });
+    } else if (satisfied === undefined) {
+      findings.push({
+        id: "install/engines-node",
+        severity: "info",
+        title: "could not evaluate the declared Node range",
+        detail:
+          "bunready evaluates a subset of semver and this range falls outside it, so it was reported instead of judged.",
+        evidence: `engines.node = "${nodeRange}", Bun reports Node ${runtime.node}`,
+      });
+    }
+  }
+
+  return findings;
+}

package/src/rules/install/index.ts

@@ -0,0 +1,27 @@
+import { type Finding, sortFindings } from "../../report/types";
+import type { DependencyGraph } from "../../scanner/graph";
+import type { TargetSnapshot } from "../../scanner/target";
+import { enginesFindings, type RuntimeInfo } from "./engines";
+import { lifecycleScriptFindings } from "./lifecycle-scripts";
+import { lockfileFindings } from "./lockfile-presence";
+import { nativeAddonFindings } from "./native-addon";
+
+/**
+ * Every install-phase rule. Runtime-phase rules (Node built-ins Bun does not
+ * implement, the curated list of packages known to misbehave at runtime) are a
+ * separate phase and are deliberately absent.
+ */
+export function installFindings(
+  snapshot: TargetSnapshot,
+  graph: DependencyGraph,
+  runtime: RuntimeInfo,
+): Finding[] {
+  const primaryLockfile = snapshot.lockfiles[0]?.parsed;
+
+  return sortFindings([
+    ...lockfileFindings(snapshot),
+    ...nativeAddonFindings(snapshot, graph, primaryLockfile),
+    ...lifecycleScriptFindings(snapshot, primaryLockfile),
+    ...enginesFindings(snapshot.manifest, runtime),
+  ]);
+}

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

@@ -0,0 +1,70 @@
+import type { Finding } from "../../report/types";
+import type { ParsedLockfile } from "../../scanner/lockfile";
+import type { TargetSnapshot } from "../../scanner/target";
+
+/**
+ * The highest-value rule in the install phase.
+ *
+ * `bun install` does not run lifecycle scripts for packages that are not listed
+ * in `trustedDependencies`. That is a real, observable behaviour change when
+ * moving off npm, and when a dependency's install step is what builds a native
+ * addon or downloads a binary, skipping it leaves the package broken. The user
+ * cannot fix it by "doing nothing", so it is a blocker.
+ *
+ * Evidence comes from the lockfile (npm's `hasInstallScript`, pnpm's
+ * `requiresBuild`) or from an installed copy's own manifest. Both are observed
+ * facts; nothing is inferred from package names.
+ */
+export const LIFECYCLE_DOC = "https://bun.com/docs/pm/lifecycle";
+export const TRUSTED_DEPENDENCIES_GUIDE = "https://bun.com/guides/install/trusted";
+
+const ID = "install/lifecycle-script";
+
+export function lifecycleScriptFindings(
+  snapshot: TargetSnapshot,
+  lockfile: ParsedLockfile | undefined,
+): Finding[] {
+  const trusted = new Set(snapshot.manifest.trustedDependencies);
+  const evidence = new Map<string, string>();
+
+  for (const pkg of lockfile?.packages ?? []) {
+    if (pkg.installScript) {
+      evidence.set(pkg.name, `the lockfile marks ${pkg.name} as requiring a build step`);
+    }
+  }
+
+  for (const probe of snapshot.packageEvidence) {
+    if (probe.installScripts.length === 0) {
+      continue;
+    }
+    const scripts = probe.installScripts.map((name) => `"${name}"`).join(", ");
+    evidence.set(probe.name, `${probe.path} declares ${scripts}`);
+  }
+
+  return [...evidence.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([name, where]) => {
+      if (trusted.has(name)) {
+        return {
+          id: ID,
+          severity: "info" as const,
+          title: `${name} runs an install script and is trusted`,
+          package: name,
+          detail:
+            "Bun will run this package's install script because it is listed in trustedDependencies.",
+          evidence: where,
+        };
+      }
+      return {
+        id: ID,
+        severity: "blocker" as const,
+        title: `${name} installs nothing: its install script will not run`,
+        package: name,
+        detail:
+          "Bun installs dependencies without running their lifecycle scripts unless the package is listed in trustedDependencies. If this package builds a native addon or downloads a binary during install, that step is skipped.",
+        evidence: where,
+        hint: `add "${name}" to trustedDependencies in package.json, then reinstall.`,
+        source: LIFECYCLE_DOC,
+      };
+    });
+}

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

@@ -0,0 +1,68 @@
+import type { Finding } from "../../report/types";
+import type { TargetSnapshot } from "../../scanner/target";
+
+/**
+ * What the scan could and could not see.
+ *
+ * These findings describe the evidence base itself. A scan that could not read
+ * the lockfile must say so, because "no dependency problems found" would
+ * otherwise be indistinguishable from "we only looked at one package.json".
+ */
+const NO_LOCKFILE_ID = "install/no-lockfile";
+const BINARY_LOCKFILE_ID = "install/binary-lockfile";
+const UNPARSED_LOCKFILE_ID = "install/unparsed-lockfile";
+const MULTIPLE_LOCKFILES_ID = "install/multiple-lockfiles";
+
+export function lockfileFindings(snapshot: TargetSnapshot): Finding[] {
+  const findings: Finding[] = [];
+
+  if (snapshot.lockfiles.length === 0 && snapshot.binaryBunLock === undefined) {
+    findings.push({
+      id: NO_LOCKFILE_ID,
+      severity: "info",
+      title: "no lockfile found",
+      detail:
+        "Without a lockfile the dependency graph covers only the packages named in package.json, so transitive install-phase problems cannot be seen.",
+      evidence: `looked for bun.lock, package-lock.json, yarn.lock and pnpm-lock.yaml in ${snapshot.dir}`,
+      hint: "commit a lockfile so the move to Bun installs the same versions you tested.",
+    });
+  }
+
+  if (snapshot.binaryBunLock !== undefined) {
+    findings.push({
+      id: BINARY_LOCKFILE_ID,
+      severity: "risk",
+      title: "bun.lockb is a binary lockfile",
+      detail:
+        "bunready reads the text lockfile format only. The contents of bun.lockb are not guessed at, so this scan cannot see your transitive dependencies.",
+      evidence: `${snapshot.binaryBunLock} exists`,
+      hint: "regenerate the lockfile with `bun install` on Bun 1.2 or newer to produce the text format bun.lock.",
+    });
+  }
+
+  if (snapshot.lockfiles.length > 1) {
+    const names = snapshot.lockfiles.map((entry) => entry.path).join(", ");
+    findings.push({
+      id: MULTIPLE_LOCKFILES_ID,
+      severity: "info",
+      title: "more than one lockfile is present",
+      detail:
+        "The graph was built from the highest-priority lockfile in the repository; the others were ignored.",
+      evidence: names,
+      hint: "remove the lockfiles belonging to the package manager you are actually leaving behind.",
+    });
+  }
+
+  for (const unparsed of snapshot.unparsedLockfiles) {
+    findings.push({
+      id: UNPARSED_LOCKFILE_ID,
+      severity: "risk",
+      title: `${unparsed.path} could not be read`,
+      detail: unparsed.message,
+      evidence: `${unparsed.kind} lockfile at ${unparsed.path}`,
+      hint: "regenerate the lockfile with the package manager that produced it, then scan again.",
+    });
+  }
+
+  return findings;
+}

package/src/rules/install/native-addon.ts

@@ -0,0 +1,126 @@
+import type { Finding } from "../../report/types";
+import type { DependencyGraph } from "../../scanner/graph";
+import { knownPackageNames } from "../../scanner/graph";
+import type { ParsedLockfile } from "../../scanner/lockfile";
+import type { TargetSnapshot } from "../../scanner/target";
+import nativeDataset from "../data/native-packages.json";
+
+/**
+ * Native-addon detection, in evidence order:
+ *   1. the package is in our curated list (a property of the package, with a
+ *      source link), 2. the target's own manifest pulls in a build tool, 3. an
+ *      installed copy declares `gypfile`.
+ *
+ * All three produce `risk`, never `blocker`: plenty of these packages ship a
+ * prebuilt binary for the common platforms, so "will not work on Bun" would be
+ * a claim bunready cannot back. The hard failure lives in the lifecycle rule,
+ * where a skipped install script is observable.
+ */
+
+export interface NativePackageEntry {
+  readonly name: string;
+  readonly reason: string;
+  readonly source: string;
+}
+
+export const BUILD_TOOL_PACKAGES = [
+  "node-gyp",
+  "node-pre-gyp",
+  "prebuild-install",
+  "node-gyp-build",
+  "cmake-js",
+] as const;
+
+const NATIVE_ADDON_ID = "install/native-addon";
+const BUILD_TOOL_ID = "install/native-build-tools";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Validate the vendored dataset instead of trusting the import blindly. */
+export function readDataset(raw: unknown = nativeDataset): NativePackageEntry[] {
+  if (!isRecord(raw) || !Array.isArray(raw.packages)) {
+    return [];
+  }
+  const entries: NativePackageEntry[] = [];
+  for (const candidate of raw.packages) {
+    if (!isRecord(candidate)) {
+      continue;
+    }
+    const { name, reason, source } = candidate;
+    if (typeof name === "string" && typeof reason === "string" && typeof source === "string") {
+      entries.push({ name, reason, source });
+    }
+  }
+  return entries;
+}
+
+export function nativeAddonFindings(
+  snapshot: TargetSnapshot,
+  graph: DependencyGraph,
+  lockfile: ParsedLockfile | undefined,
+): Finding[] {
+  const findings = new Map<string, Finding>();
+  const known = knownPackageNames(graph, lockfile);
+  const direct = new Set([...graph.direct, ...graph.dev, ...graph.optional]);
+  const allowed = new Set(snapshot.config.nativeAllowlist);
+
+  for (const entry of readDataset()) {
+    if (!known.has(entry.name) || allowed.has(entry.name)) {
+      continue;
+    }
+    findings.set(entry.name, {
+      id: NATIVE_ADDON_ID,
+      severity: "risk",
+      title: `${entry.name} ships a native addon`,
+      detail: entry.reason,
+      package: entry.name,
+      evidence: direct.has(entry.name) ? "declared in package.json" : "present in the lockfile",
+      source: entry.source,
+      hint: "check that a prebuilt binary exists for your platform, otherwise this one needs a working C/C++ toolchain.",
+    });
+  }
+
+  for (const evidence of snapshot.packageEvidence) {
+    if (!evidence.gypfile || findings.has(evidence.name)) {
+      continue;
+    }
+    findings.set(evidence.name, {
+      id: NATIVE_ADDON_ID,
+      severity: "risk",
+      title: `${evidence.name} builds a native addon on install`,
+      detail:
+        "The installed copy of this package sets `gypfile`, so it compiles a native addon rather than shipping one.",
+      package: evidence.name,
+      evidence: `${evidence.path} sets "gypfile": true`,
+      hint: "this needs a C/C++ toolchain and a Python interpreter available at install time.",
+    });
+  }
+
+  const declaredTools = BUILD_TOOL_PACKAGES.filter((tool) => {
+    if (allowed.has(tool)) {
+      return false;
+    }
+    if (direct.has(tool)) {
+      return true;
+    }
+    return Object.values(snapshot.manifest.scripts).some((script) => script.includes(tool));
+  });
+
+  const result = [...findings.values()];
+  if (declaredTools.length > 0) {
+    result.push({
+      id: BUILD_TOOL_ID,
+      severity: "risk",
+      title: "the project builds native code with node-gyp tooling",
+      detail: `Resolving these build tools is a prerequisite for every native dependency to install: ${declaredTools.join(", ")}.`,
+      evidence: direct.has(declaredTools[0] ?? "")
+        ? `declared as a dependency: ${declaredTools.join(", ")}`
+        : `referenced by a package.json script: ${declaredTools.join(", ")}`,
+      hint: "install the toolchain you already rely on, or switch the dependency to a package that ships prebuilds.",
+    });
+  }
+
+  return result;
+}