@mh-alikhani/bunready 0.1.0

package/docs/brand/favicon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="bunready">
+  <title>bunready</title>
+  <rect width="64" height="64" rx="15" fill="#171A1F"/>
+  <g fill="none" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M25 20 L41 32 L25 44" stroke="#FBFAF7" stroke-width="5.5"/>
+    <path d="M26 50.5 H41" stroke="#D9944F" stroke-width="5.5"/>
+  </g>
+</svg>

package/docs/brand/guidelines.md

@@ -0,0 +1,70 @@
+# bunready brand guidelines
+
+One page. If a rule is not here, the default is "quieter".
+
+## Positioning
+
+**bunready** — _Know what breaks before you move a Node/TS repo to Bun._
+One command. One honest verdict.
+
+## Voice
+
+Calm, precise, non-alarmist. State the fact, then the next step. Four rules:
+
+1. **Never alarm.** No `DANGER`, no `CRITICAL`, no exclamation marks.
+2. **Never be vague.** "2 native addons will not build" beats "some issues found".
+3. **Always give the next step.** Every error carries a `hint`.
+4. **Never claim what was not observed.** A finding needs repo evidence or a
+   source link; if there is neither, it does not ship. See
+   [ADR 0001](adr/0001-data-source-policy.md).
+
+Severity is a decision, not a feeling — see
+[ADR 0002](adr/0002-rule-severity-model.md). Colour never carries meaning on its
+own: every severity also prints as a word.
+
+## Logo
+
+| Asset | Use |
+| --- | --- |
+| `docs/brand/logo.svg` | Default lockup, light backgrounds. |
+| `docs/brand/logo-dark.svg` | Lockup on dark backgrounds. |
+| `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. |
+| `assets/og.png` | Social card, 1200x630, generated by `scripts/generate-og-image.ts`. |
+
+The mark is a terminal prompt — a caret and an underscore inside a rounded
+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.
+**Never:** recolour outside `tokens.json`, stretch, rotate, add effects,
+place the lockup on a busy photo, or crop the mark's rounded square.
+
+## Colour and type
+
+`docs/brand/tokens.json` is the single source of truth: palette (light/dark),
+severity colours, terminal ANSI-256 indexes, spacing, radii, type scale, fonts.
+Terminal output must be legible on light and dark schemes.
+
+## Exact copy
+
+`src/cli/copy.ts` is the source of truth for strings, so the guidelines and the
+binary cannot drift.
+
+| Surface | Copy |
+| --- | --- |
+| `--help` header | `bunready <version>` then the positioning line |
+| Usage error | `<code>: <message>` + `  hint: <next step>` (exit 2) |
+| Success (no blockers) | `ready - no Bun compatibility blockers found` |
+| Blocked | `blocked - N blocker(s) must be fixed before this repo runs on Bun` |
+| Risky | `risky - N risk(s) to review, no hard blockers` |
+| Not implemented yet | `the scanner engine is not implemented yet (phase 1 scaffold only)` |
+
+## Trademark hygiene
+
+bunready is an independent community project. It is **not affiliated with,
+endorsed by, or sponsored by** the Bun project or Oven. "Bun" and the Bun logo
+belong to their respective owners and are used only for descriptive, nominative
+purposes. bunready ships no Bun code and no Bun branding. Every public surface
+(README, `--help`, OG image) carries the disclaimer.

package/docs/brand/logo-dark.svg

@@ -0,0 +1,11 @@
+<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>
+  <g>
+    <rect x="34" y="34" width="52" height="52" rx="15" fill="none" stroke="#E0A268" stroke-width="3"/>
+    <path d="M53 49 L68 60 L53 71" fill="none" stroke="#F2F1EC" stroke-width="4.5" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M54 77 H68" fill="none" stroke="#F2F1EC" stroke-width="4.5" stroke-linecap="round"/>
+  </g>
+  <text 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" fill="#F2F1EC">bunready</text>
+</svg>

package/docs/brand/logo-mono.svg

@@ -0,0 +1,11 @@
+<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>
+  <g fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round">
+    <rect x="34" y="34" width="52" height="52" rx="15" stroke-width="3"/>
+    <path d="M53 49 L68 60 L53 71" stroke-width="4.5"/>
+    <path d="M54 77 H68" stroke-width="4.5"/>
+  </g>
+  <text 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" fill="currentColor">bunready</text>
+</svg>

package/docs/brand/logo.svg

@@ -0,0 +1,11 @@
+<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>
+  <g>
+    <rect x="34" y="34" width="52" height="52" rx="15" fill="none" stroke="#A85B2B" stroke-width="3"/>
+    <path d="M53 49 L68 60 L53 71" fill="none" stroke="#171A1F" stroke-width="4.5" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M54 77 H68" fill="none" stroke="#171A1F" stroke-width="4.5" stroke-linecap="round"/>
+  </g>
+  <text 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" fill="#171A1F">bunready</text>
+</svg>

package/docs/brand/mark.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="bunready mark">
+  <title>bunready mark</title>
+  <g fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round">
+    <rect x="6" y="6" width="52" height="52" rx="15" stroke-width="3"/>
+    <path d="M25 21 L40 32 L25 43" stroke-width="4.5"/>
+    <path d="M26 49 H40" stroke-width="4.5"/>
+  </g>
+</svg>

package/docs/brand/tokens.json

@@ -0,0 +1,74 @@
+{
+  "name": "bunready",
+  "version": "1.0.0",
+  "positioning": "Know what breaks before you move a Node/TS repo to Bun.",
+  "tagline": "One command. One honest verdict.",
+  "voice": ["calm", "precise", "non-alarmist", "specific"],
+  "color": {
+    "light": {
+      "bg": "#FBFAF7",
+      "surface": "#FFFFFF",
+      "border": "#E5E2DA",
+      "text": "#171A1F",
+      "muted": "#5C6470",
+      "accent": "#A85B2B",
+      "accentSoft": "#F3E4D7"
+    },
+    "dark": {
+      "bg": "#131519",
+      "surface": "#1A1D23",
+      "border": "#2A2F38",
+      "text": "#F2F1EC",
+      "muted": "#A2A9B4",
+      "accent": "#E0A268",
+      "accentSoft": "#3A2B1F"
+    }
+  },
+  "severity": {
+    "blocker": {
+      "light": "#B94A44",
+      "dark": "#E58079",
+      "label": "blocker",
+      "meaning": "Cannot run correctly on Bun until fixed. Fails CI."
+    },
+    "risk": {
+      "light": "#A9741A",
+      "dark": "#E0B463",
+      "label": "risk",
+      "meaning": "Real hazard needing a human judgement call. Does not fail CI."
+    },
+    "info": {
+      "light": "#5C6470",
+      "dark": "#A2A9B4",
+      "label": "info",
+      "meaning": "Context only. Does not fail CI."
+    }
+  },
+  "terminal": {
+    "ansi256": {
+      "blocker": 203,
+      "risk": 179,
+      "info": 245,
+      "accent": 173,
+      "muted": 245,
+      "border": 240
+    },
+    "note": "Terminal output must stay legible on light and dark themes; never rely on colour alone - every severity also carries a word."
+  },
+  "spacing": [2, 4, 8, 12, 16, 24, 32, 48, 64],
+  "radii": { "none": 0, "sm": 4, "md": 8, "lg": 14, "pill": 999 },
+  "typeScale": {
+    "sans": [12, 14, 16, 20, 26, 34, 46, 60],
+    "mono": [12, 13, 14, 16, 20],
+    "lineHeight": { "tight": 1.15, "normal": 1.5, "loose": 1.7 }
+  },
+  "fonts": {
+    "sans": "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
+    "mono": "ui-monospace, SFMono-Regular, 'Cascadia Mono', Menlo, Consolas, 'Liberation Mono', monospace"
+  },
+  "clearSpace": {
+    "rule": "clear space on every side = 0.5 x the mark height",
+    "minMarkPx": 24,
+    "minLockupWidthPx": 120
+  }
+}

package/docs/demo.md

@@ -0,0 +1,37 @@
+# 30-second demo
+
+The GIF this script produces is **not** committed here: it is recorded from the
+real binary, never mocked up. Until the scanner engine lands (phases 2-3) there
+is nothing honest to record, so this file is the shot list and the exact
+commands.
+
+## Preconditions
+
+```sh
+bun install
+bun run src/cli/index.ts --version   # prints: bunready 0.1.0
+```
+
+Recording: 1200x700, 30fps, ~14s of content cut to a 30s budget, no fake
+typing pauses. Terminal font 16px, dark theme with a light-theme counterpart
+shot, `NO_COLOR` shot last.
+
+## Shot list
+
+| # | Duration | Terminal command | What the viewer must see |
+| --- | --- | --- | --- |
+| 1 | 3s | `bunready --help` | The positioning line, the exit-code table, the disclaimer. |
+| 2 | 6s | `cd ~/code/some-node-service && bunready .` | The human table: findings grouped blocker / risk / info. |
+| 3 | 4s | same, scrolled to the verdict | The single verdict line and the non-zero exit code. |
+| 4 | 5s | `bunready . --json \| head -40` | The same findings as JSON, stable field names. |
+| 5 | 4s | `bunready --run .` | The **first** real failure and its stack trace. |
+| 6 | 3s | `NO_COLOR=1 bunready .` | Plain text, identical information, still a real verdict. |
+| 7 | 5s | `bunready . ; echo "exit=$?"` | The exit code CI depends on. |
+
+Total: 30s. No cuts inside a command; no invented output.
+
+## Target repo for the recording
+
+Pick a real repository with at least one native dependency and one blocked
+lifecycle script, so every severity is genuinely present. Record its commit SHA
+in the GIF description.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@mh-alikhani/bunready",
+  "version": "0.1.0",
+  "description": "Bun-readiness scanner: one command that shows what will break before you move a Node/TS repo to Bun.",
+  "keywords": [
+    "bun",
+    "migration",
+    "compatibility",
+    "scanner",
+    "cli",
+    "node",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Mohammad Hosein Alikhani",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "bunready": "./src/cli/index.ts"
+  },
+  "files": [
+    "src",
+    "docs",
+    "action.yml",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "trustedDependencies": [
+    "simple-git-hooks"
+  ],
+  "scripts": {
+    "bunready": "bun run src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "test": "bun test",
+    "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",
+    "prepare": "simple-git-hooks"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2",
+    "@commitlint/cli": "^21",
+    "@commitlint/config-conventional": "^21",
+    "@resvg/resvg-js": "^2",
+    "@types/bun": "^1",
+    "simple-git-hooks": "^2",
+    "typescript": "^7"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "bunx biome check --staged --no-errors-on-unmatched && bunx tsc --noEmit",
+    "commit-msg": "bunx commitlint --edit \"$1\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MHAlikhani/bunready.git"
+  },
+  "homepage": "https://github.com/MHAlikhani/bunready#readme",
+  "bugs": {
+    "url": "https://github.com/MHAlikhani/bunready/issues"
+  }
+}

package/src/cli/args.ts

@@ -0,0 +1,177 @@
+import { defineError, err, ok, type Result } from "../core/errors";
+
+/** Everything the CLI understands. */
+export interface CliOptions {
+  /** Repository to scan; `.` unless the user passed a path. */
+  readonly target: string;
+  readonly help: boolean;
+  readonly version: boolean;
+  readonly json: boolean;
+  readonly sarif: boolean;
+  readonly run: boolean;
+  readonly runScript: string | undefined;
+  readonly config: string | undefined;
+  readonly scope: string | undefined;
+  readonly baseline: string | undefined;
+  readonly writeBaseline: string | undefined;
+}
+
+export const DEFAULT_TARGET = ".";
+
+/**
+ * Parse argv (already stripped of `node`/`bun` and the script path).
+ *
+ * Usage problems are returned, not thrown: the caller decides the exit code and
+ * the message. `--` ends option parsing so a directory named `--json` stays
+ * addressable.
+ */
+export function parseArgs(argv: readonly string[]): Result<CliOptions> {
+  let target: string | undefined;
+  let help = false;
+  let version = false;
+  let json = false;
+  let sarif = false;
+  let run = false;
+  let runScript: string | undefined;
+  let config: string | undefined;
+  let scope: string | undefined;
+  let baseline: string | undefined;
+  let writeBaseline: string | undefined;
+  let positionalOnly = false;
+
+  const valueFor = (flag: string, index: number): Result<string> => {
+    const value = argv[index + 1];
+    if (value === undefined || value === "") {
+      return err(
+        defineError("E_USAGE", `${flag} needs a value`, {
+          hint: `write it as ${flag} <value>.`,
+        }),
+      );
+    }
+    return ok(value);
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? "";
+
+    if (positionalOnly) {
+      if (target !== undefined) {
+        return err(
+          defineError("E_USAGE", `unexpected extra argument "${arg}"`, {
+            hint: "bunready scans one repository at a time.",
+          }),
+        );
+      }
+      target = arg;
+      continue;
+    }
+
+    switch (arg) {
+      case "--":
+        positionalOnly = true;
+        break;
+      case "-h":
+      case "--help":
+        help = true;
+        break;
+      case "-v":
+      case "--version":
+        version = true;
+        break;
+      case "--json":
+        json = true;
+        break;
+      case "--sarif":
+        sarif = true;
+        break;
+      case "--run":
+        run = true;
+        break;
+      case "--run-script": {
+        const value = valueFor(arg, index);
+        if (!value.ok) {
+          return value;
+        }
+        runScript = value.value;
+        run = true;
+        index += 1;
+        break;
+      }
+      case "--config": {
+        const value = valueFor(arg, index);
+        if (!value.ok) {
+          return value;
+        }
+        config = value.value;
+        index += 1;
+        break;
+      }
+      case "--scope": {
+        const value = valueFor(arg, index);
+        if (!value.ok) {
+          return value;
+        }
+        scope = value.value;
+        index += 1;
+        break;
+      }
+      case "--baseline": {
+        const value = valueFor(arg, index);
+        if (!value.ok) {
+          return value;
+        }
+        baseline = value.value;
+        index += 1;
+        break;
+      }
+      case "--write-baseline": {
+        const value = valueFor(arg, index);
+        if (!value.ok) {
+          return value;
+        }
+        writeBaseline = value.value;
+        index += 1;
+        break;
+      }
+      default:
+        if (arg.startsWith("-") && arg !== "-") {
+          return err(
+            defineError("E_USAGE", `unknown option "${arg}"`, {
+              hint: "run `bunready --help` to see the supported options.",
+            }),
+          );
+        }
+        if (target !== undefined) {
+          return err(
+            defineError("E_USAGE", `unexpected extra argument "${arg}"`, {
+              hint: "bunready scans one repository at a time.",
+            }),
+          );
+        }
+        target = arg;
+        break;
+    }
+  }
+
+  if (json && sarif) {
+    return err(
+      defineError("E_USAGE", "--json and --sarif both write a machine-readable report to stdout", {
+        hint: "choose one of them.",
+      }),
+    );
+  }
+
+  return ok({
+    target: target ?? DEFAULT_TARGET,
+    help,
+    version,
+    json,
+    sarif,
+    run,
+    runScript,
+    config,
+    scope,
+    baseline,
+    writeBaseline,
+  });
+}

package/src/cli/copy.ts

@@ -0,0 +1,76 @@
+/**
+ * User-facing copy. This file is the single source of truth for what bunready
+ * says, so the brand guidelines and the binary cannot drift apart.
+ *
+ * Voice: calm, precise, non-alarmist. State the fact, then the next step.
+ */
+import { TOOL_NAME } from "../core/version";
+import type { Verdict } from "../report/types";
+import type { Severity } from "../rules/severity";
+
+export const TOOL = TOOL_NAME;
+
+export const POSITIONING = "Know what breaks before you move a Node/TS repo to Bun.";
+
+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";
+
+export function helpText(version: string): string {
+  return [
+    `${TOOL} ${version}`,
+    POSITIONING,
+    "",
+    "USAGE",
+    `  ${TOOL} [path] [options]`,
+    "",
+    "ARGUMENTS",
+    "  path            Repository to scan. Defaults to the current directory.",
+    "",
+    "OPTIONS",
+    "  -h, --help      Print this help and exit.",
+    "  -v, --version   Print the version and exit.",
+    "      --json      Emit a machine-readable report on stdout.",
+    "      --sarif     Emit SARIF 2.1.0 on stdout, for code-scanning upload.",
+    "      --run       Copy the repository to a temporary directory, install it and",
+    "                  run its start (or test) script under Bun, reporting the first",
+    "                  real failure. Executes code; off by default.",
+    "",
+    "      --config    Path to a bunready.config.json. Defaults to the file in the",
+    "                  scanned repository, if any.",
+    "      --scope     In a workspace, scan only packages matching this string.",
+    "      --baseline  Compare against a baseline and fail only on new findings.",
+    "      --write-baseline  Record the current findings as a baseline.",
+    "",
+    "EXIT CODES",
+    "  0   No blockers found.",
+    "  1   Blockers found.",
+    "  2   Usage error, or the scan could not complete.",
+    "",
+    "ENVIRONMENT",
+    "  NO_COLOR        Disable ANSI colour (presence is enough).",
+    "",
+    "Compatibility claims come only from public Bun documentation and issue",
+    "tracker entries, each shipped with a source link. bunready never invents",
+    "compatibility facts. Not affiliated with the Bun project or Oven.",
+    "",
+    "CONFIGURATION",
+    "  bunready.config.json in the scanned repository can ignore rule ids or",
+    "  packages, allowlist native addons, exclude paths and raise or lower",
+    "  failOn. See docs/CONFIGURATION.md.",
+  ].join("\n");
+}
+
+/** The single line a human reads first. Never alarmist, never vague. */
+export function verdictLine(verdict: Verdict, counts: Readonly<Record<Severity, number>>): string {
+  switch (verdict) {
+    case "blocked":
+      return `blocked - ${counts.blocker} blocker(s) must be fixed before this repo runs on Bun`;
+    case "risky":
+      return `risky - ${counts.risk} risk(s) to review, no hard blockers`;
+    case "ready":
+      return "ready - no Bun compatibility blockers found";
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { run } from "./run";
+
+// Exit through exitCode, not process.exit(): pending stdout writes must flush.
+process.exitCode = await run(process.argv.slice(2));

package/src/cli/io.ts

@@ -0,0 +1,20 @@
+/** Terminal seam: `run()` writes through this, never straight to `process`. */
+export interface Io {
+  readonly out: (line: string) => void;
+  readonly err: (line: string) => void;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly isTty: boolean;
+}
+
+export function systemIo(): Io {
+  return {
+    out: (line) => {
+      process.stdout.write(`${line}\n`);
+    },
+    err: (line) => {
+      process.stderr.write(`${line}\n`);
+    },
+    env: process.env,
+    isTty: process.stdout.isTTY === true,
+  };
+}