@mh-alikhani/bunready 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -9,6 +9,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Nothing yet.
 
+## [0.2.0] - 2026-09-16
+
+### Added
+
+- **Sourced runtime gap dataset.** `src/rules/data/node-runtime.json` now carries
+  18 entries read from Bun's own Node.js compatibility table (17 `partial`,
+  1 `unimplemented`), each with the table as its primary source. A repository
+  importing a `partial` module gets a `risk`; an `unimplemented` one
+  (currently `node:sea`) is a `blocker`, because it breaks on import with no
+  user action.
+- **Real-project smoke script.** `bun run smoke` downloads the Next.js
+  hello-world example, the NestJS starter and turborepo's basic monorepo and
+  prints each scan's verdict, so a release is validated against real
+  repositories before it ships.
+- Decisions D41–D43 in `STATE.md` (optional-dependency severity, `node:`
+  prefix classification, the smoke script).
+
+### Fixed
+
+- **Optional dependencies no longer produce blockers.** A skipped install
+  script on an *optional* package (the `fsevents` false positive on the NestJS
+  starter) is now a `risk`: the installer tolerates an absent optional package
+  by design, so a skipped script cannot break the install itself.
+- **`node:`-prefixed imports are always classified as Node built-ins**, even
+  when the runtime's own `builtinModules` list lags behind Node (e.g.
+  `node:sea` is missing from Bun's list).
+- README no longer claims `--run` is unimplemented.
+
 ## [0.1.0] - 2026-09-09
 
 ### Added

package/README.md

@@ -1,6 +1,10 @@
 <div align="center">
 
-<img src="docs/brand/logo.svg" alt="bunready" width="360">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/brand/logo-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="docs/brand/logo.svg">
+  <img src="docs/brand/logo-auto.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.**
 
@@ -24,9 +28,10 @@ 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.
+`--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
 
@@ -57,7 +62,7 @@ bunx @mh-alikhani/bunready /path/to/node-project
 | `--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. |
+| `--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: `0` no blockers, `1` blockers found, `2` usage error.
@@ -88,7 +93,7 @@ permissions:
 
 steps:
   - uses: actions/checkout@v7
-  - uses: MHAlikhani/bunready@v0.1.0
+  - uses: MHAlikhani/bunready@v0.2.0
     with:
       path: .
 ```
@@ -97,6 +102,18 @@ 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`.
 
+## How it is different
+
+- **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.
+
 ## Why
 
 Moving a repo to Bun is usually a pile of small unknowns: which npm lifecycle

package/docs/brand/guidelines.md

@@ -28,6 +28,7 @@ own: every severity also prints as a word.
 | --- | --- |
 | `docs/brand/logo.svg` | Default lockup, light backgrounds. |
 | `docs/brand/logo-dark.svg` | Lockup on dark backgrounds. |
+| `docs/brand/logo-auto.svg` | Theme-aware lockup: follows `prefers-color-scheme` itself. Used where `<picture>` is stripped, and as the README fallback. |
 | `docs/brand/logo-mono.svg` | Single-colour lockup; inherits `currentColor`. |
 | `docs/brand/mark.svg` | Mark alone; inherits `currentColor`. |
 | `docs/brand/favicon.svg` | Favicon: mark on ink, tuned for 16px. |
@@ -38,6 +39,7 @@ square: "you are about to run something".
 
 **Clear space:** 0.5 x the mark height on all four sides. Nothing enters it.
 **Minimum sizes:** mark 24px; lockup 120px wide.
+**Colour scheme:** every lockup must stay legible on both `#FBFAF7` and `#131519`. Where the host supports it, serve `logo.svg` / `logo-dark.svg` through `<picture>` with `prefers-color-scheme`; otherwise serve `logo-auto.svg`, which switches itself. Never ship the light lockup into a dark-only context.
 **Never:** recolour outside `tokens.json`, stretch, rotate, add effects,
 place the lockup on a busy photo, or crop the mark's rounded square.
 

package/docs/brand/logo-auto.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 340 120" width="340" height="120" role="img" aria-label="bunready">
+  <title>bunready</title>
+  <!--
+    One lockup that follows the reader's colour scheme. The light palette is
+    baked into the shapes so that a sanitizer which strips <style> (some
+    registries do) still renders a legible mark; the media query only overrides
+    for dark. Prefer .svg light/dark pairs with <picture> when the host supports
+    it, and this file when it does not.
+  -->
+  <style>
+    .ring { stroke: #a85b2b; }
+    .glyph { stroke: #171a1f; }
+    .wordmark { fill: #171a1f; }
+    @media (prefers-color-scheme: dark) {
+      .ring { stroke: #e0a268; }
+      .glyph { stroke: #f2f1ec; }
+      .wordmark { fill: #f2f1ec; }
+    }
+  </style>
+  <g fill="none" stroke-linecap="round" stroke-linejoin="round">
+    <rect class="ring" x="34" y="34" width="52" height="52" rx="15" stroke-width="3"/>
+    <path class="glyph" d="M53 49 L68 60 L53 71" stroke-width="4.5"/>
+    <path class="glyph" d="M54 77 H68" stroke-width="4.5"/>
+  </g>
+  <text class="wordmark" x="108" y="76"
+        font-family="ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
+        font-size="42" font-weight="620" letter-spacing="-1">bunready</text>
+</svg>

package/package.json

@@ -1,15 +1,27 @@
 {
   "name": "@mh-alikhani/bunready",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Bun-readiness scanner: one command that shows what will break before you move a Node/TS repo to Bun.",
   "keywords": [
     "bun",
+    "bun-readiness",
+    "node",
+    "nodejs",
+    "typescript",
     "migration",
     "compatibility",
-    "scanner",
     "cli",
-    "node",
-    "typescript"
+    "scanner",
+    "static-analysis",
+    "monorepo",
+    "workspaces",
+    "lockfile",
+    "sarif",
+    "ci",
+    "code-quality",
+    "developer-tools",
+    "devtools",
+    "dependency-analysis"
   ],
   "license": "MIT",
   "author": "Mohammad Hosein Alikhani",
@@ -45,6 +57,7 @@
     "build": "bun build ./src/cli/index.ts --target=bun --outdir=dist",
     "check": "bun run typecheck && bun run lint && bun run test",
     "og": "bun run scripts/generate-og-image.ts",
+    "smoke": "bun run scripts/smoke-real.ts",
     "prepare": "simple-git-hooks"
   },
   "devDependencies": {

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

@@ -1,6 +1,115 @@
 {
-  "datasetVersion": "2026-09-15.1",
+  "datasetVersion": "2026-09-16.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": []
+  "note": "Runtime compatibility data. Every entry below was read from Bun's own Node.js compatibility table (the `source` URL); see docs/adr/0001-data-source-policy.md. `status: partial` means part of the module's surface is missing; `status: unimplemented` means importing/using it fails outright.",
+  "gaps": [
+    {
+      "name": "sea",
+      "status": "unimplemented",
+      "note": "Single-executable applications are not implemented in Bun; Bun documents `bun build --compile` as the replacement.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "async_hooks",
+      "status": "partial",
+      "note": "AsyncLocalStorage and AsyncResource work; createHook and related are stubs with async ids always 0, and context does not propagate into MessagePort/BroadcastChannel/Worker events.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "child_process",
+      "status": "partial",
+      "note": "IPC handles net/dgram sockets but not http server sockets; 'advanced' serialization only works between Bun processes; channel.ref()/unref() are missing.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "cluster",
+      "status": "partial",
+      "note": "net/dgram sharing works as in Node; HTTP load-balancing across processes works only on Linux via SO_REUSEPORT and is not battle-tested.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "crypto",
+      "status": "partial",
+      "note": "BoringSSL-backed: ed448, x448, rsa-pss, dsa, dh, ML-KEM-512, secp256k1 and several ciphers are unavailable; encapsulate/decapsulate are missing; setEngine() throws and setFips() is a no-op.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "diagnostics_channel",
+      "status": "partial",
+      "note": "channel(), subscribe(), tracingChannel() and the http/http2/dgram channels work; boundedChannel() and several built-in channels are missing, and subscribers do not keep a Channel alive.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "domain",
+      "status": "partial",
+      "note": "Only synchronous errors are caught in run()/bind() or by emitters added with add(); asynchronous errors are not routed to the domain.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "https",
+      "status": "partial",
+      "note": "request, get, Agent and globalAgent are implemented with pooling; https.Server is http.Server with TLS options and lacks getPeerCertificate(), getCipher(), setSecureContext(), SNICallback and handshakeTimeout.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "inspector",
+      "status": "partial",
+      "note": "Session supports Profiler, Runtime.enable and NodeTracing; Debugger commands are forwarded but results are not returned; Runtime.evaluate and HeapProfiler are unimplemented and there is no Network domain.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "module",
+      "status": "partial",
+      "note": "Module#load(), registerHooks, findPackageJSON, stripTypeScriptTypes and source-map support APIs are missing; some methods are no-ops.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "perf_hooks",
+      "status": "partial",
+      "note": "monitorEventLoopDelay, createHistogram, timerify and PerformanceObserver are implemented; gc/dns/resource entries are never emitted and eventLoopUtilization() returns zeros.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "process",
+      "status": "partial",
+      "note": "process.binding is only partially available; setting process.title is a no-op on macOS/Linux; several methods return empty arrays; sourceMapsEnabled and addUncaughtExceptionCaptureCallback are missing.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "repl",
+      "status": "partial",
+      "note": "Mostly implemented via bun --interactive; there are no result previews and tab-completion skips let/const/class bindings.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "test",
+      "status": "partial",
+      "note": "The in-process API works under bun test; run() is limited and reporters, snapshots, coverage, --test-only and the CLI runner mode are missing.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "tls",
+      "status": "partial",
+      "note": "pskCallback, OCSP stapling and cross-process session resumption are missing; renegotiate() always fails because the TLS layer is BoringSSL.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "v8",
+      "status": "partial",
+      "note": "Heap snapshots/statistics and GCProfiler are implemented; serialize/deserialize use JSC's wire format; queryObjects, CPU/heap profiles, Serializer/Deserializer and promiseHooks are missing.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "wasi",
+      "status": "partial",
+      "note": "args, env, preopens, wasiImport and start() work; getImportObject(), initialize() and sock_accept are missing and several options are ignored.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    },
+    {
+      "name": "worker_threads",
+      "status": "partial",
+      "note": "resourceLimits and trackUnmanagedFds are ignored; some execArgv flags are only partly applied; moveMessagePortToContext and locks are missing.",
+      "source": "https://bun.com/docs/runtime/nodejs-compat"
+    }
+  ]
 }

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

@@ -25,11 +25,16 @@ export function lifecycleScriptFindings(
   lockfile: ParsedLockfile | undefined,
 ): Finding[] {
   const trusted = new Set(snapshot.manifest.trustedDependencies);
-  const evidence = new Map<string, string>();
+  const evidence = new Map<string, { where: string; optional: boolean }>();
 
   for (const pkg of lockfile?.packages ?? []) {
     if (pkg.installScript) {
-      evidence.set(pkg.name, `the lockfile marks ${pkg.name} as requiring a build step`);
+      evidence.set(pkg.name, {
+        where: `the lockfile marks ${pkg.name} as requiring a build step`,
+        // An optional dependency is tolerated absent by design, so a skipped
+        // install script can never break the install itself (e.g. fsevents).
+        optional: pkg.optional,
+      });
     }
   }
 
@@ -38,12 +43,12 @@ export function lifecycleScriptFindings(
       continue;
     }
     const scripts = probe.installScripts.map((name) => `"${name}"`).join(", ");
-    evidence.set(probe.name, `${probe.path} declares ${scripts}`);
+    evidence.set(probe.name, { where: `${probe.path} declares ${scripts}`, optional: false });
   }
 
   return [...evidence.entries()]
     .sort((a, b) => a[0].localeCompare(b[0]))
-    .map(([name, where]) => {
+    .map(([name, { where, optional }]) => {
       if (trusted.has(name)) {
         return {
           id: ID,
@@ -55,6 +60,19 @@ export function lifecycleScriptFindings(
           evidence: where,
         };
       }
+      if (optional) {
+        return {
+          id: ID,
+          severity: "risk" as const,
+          title: `${name} is an optional dependency whose install script will not run`,
+          package: name,
+          detail:
+            "Bun installs dependencies without running their lifecycle scripts unless the package is listed in trustedDependencies. Because this package is optional, the install still succeeds without it - but if it does install on this platform and needs its build step, it will be broken.",
+          evidence: where,
+          hint: `check whether ${name} is actually used on this platform; if it is, add it to trustedDependencies in package.json and reinstall.`,
+          source: LIFECYCLE_DOC,
+        };
+      }
       return {
         id: ID,
         severity: "blocker" as const,

package/src/rules/runtime/builtins.ts

@@ -121,9 +121,11 @@ export function runtimeBuiltinFindings(
     if (usage === undefined) {
       continue;
     }
+    // A `partial` module usually still runs; an `unimplemented` module breaks
+    // on import with no user action, which is the blocker bar (D2).
     findings.push({
       id: GAP_ID,
-      severity: "risk",
+      severity: gap.status === "unimplemented" ? "blocker" : "risk",
       title: `${gap.name} is ${gap.status} in Bun and this project imports it`,
       detail: gap.note,
       evidence: `${usage.files.length} file(s), first at ${usage.files[0] ?? "unknown"}`,

package/src/scanner/sources.ts

@@ -270,7 +270,9 @@ export function classifySpecifier(
   if (specifier.startsWith("bun:")) {
     return "bun-builtin";
   }
-  if (builtins.has(specifier)) {
+  // A `node:` prefix is unambiguous even when the runtime's own module list
+  // lags behind Node (e.g. node:sea is absent from Bun's builtinModules).
+  if (specifier.startsWith("node:") || builtins.has(specifier)) {
     return "node-builtin";
   }
   if (