@mh-alikhani/bunready 0.1.0

package/src/cli/run.ts

@@ -0,0 +1,98 @@
+import { newFindings, serializeBaseline } from "../config/baseline";
+import { formatError } from "../core/errors";
+import { type FileSystem, nodeFileSystem } from "../core/fs";
+import { TOOL_VERSION } from "../core/version";
+import { renderHumanReport } from "../report/human";
+import { renderJsonReport } from "../report/json";
+import { renderSarifReport } from "../report/sarif";
+import { exitCodeForFindings } from "../rules/severity";
+import { scanTarget } from "../scanner/scan";
+import { parseArgs } from "./args";
+import { helpText, RUN_WARNING, TOOL } from "./copy";
+import { type Io, systemIo } from "./io";
+import { colorEnabled, createTheme } from "./theme";
+
+export const EXIT_OK = 0;
+export const EXIT_BLOCKERS = 1;
+export const EXIT_USAGE = 2;
+
+export function version(): string {
+  return TOOL_VERSION;
+}
+
+/**
+ * The whole CLI, minus the process boundary.
+ *
+ * `run` takes argv and an Io seam and returns an exit code, which keeps the
+ * entry point at index.ts tiny and every behaviour reachable from tests.
+ */
+export async function run(
+  argv: readonly string[],
+  io: Io = systemIo(),
+  fs: FileSystem = nodeFileSystem(),
+): Promise<number> {
+  const theme = createTheme(colorEnabled(io.env, io.isTty));
+  const parsed = parseArgs(argv);
+
+  if (!parsed.ok) {
+    io.err(`${theme.red("error")} ${formatError(parsed.error)}`);
+    return EXIT_USAGE;
+  }
+
+  const options = parsed.value;
+
+  if (options.help) {
+    io.out(helpText(version()));
+    return EXIT_OK;
+  }
+
+  if (options.version) {
+    io.out(`${TOOL} ${version()}`);
+    return EXIT_OK;
+  }
+
+  if (options.run) {
+    io.err(`${theme.dim("!")} ${RUN_WARNING}`);
+  }
+
+  const scan = await scanTarget(options.target, {
+    fs,
+    run: options.run,
+    ...(options.runScript === undefined ? {} : { runScript: options.runScript }),
+    ...(options.config === undefined ? {} : { configPath: options.config }),
+    ...(options.scope === undefined ? {} : { scope: options.scope }),
+    ...(options.baseline === undefined ? {} : { baselinePath: options.baseline }),
+  });
+
+  if (!scan.ok) {
+    io.err(`${theme.red("error")} ${formatError(scan.error)}`);
+    return EXIT_USAGE;
+  }
+
+  const report = scan.value;
+
+  if (options.writeBaseline !== undefined) {
+    try {
+      await fs.writeTextFile(options.writeBaseline, serializeBaseline(report.findings));
+    } catch (error) {
+      io.err(
+        `${theme.red("error")} could not write ${options.writeBaseline}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return EXIT_USAGE;
+    }
+    io.err(
+      `${theme.dim("!")} wrote ${report.findings.length} finding(s) to ${options.writeBaseline}`,
+    );
+  }
+
+  if (options.json) {
+    io.out(renderJsonReport(report));
+  } else if (options.sarif) {
+    io.out(renderSarifReport(report));
+  } else {
+    io.out(renderHumanReport(report, theme));
+  }
+
+  const failing = newFindings(report.findings, report.baseline !== undefined);
+  return exitCodeForFindings(failing, report.failOn) === 0 ? EXIT_OK : EXIT_BLOCKERS;
+}

package/src/cli/theme.ts

@@ -0,0 +1,59 @@
+/**
+ * Colour handling.
+ *
+ * Two rules, both boring on purpose: `NO_COLOR` always wins when present (the
+ * no-color.org convention: presence, not value, disables colour), and colour is
+ * never emitted to something that is not a terminal.
+ */
+export interface Theme {
+  readonly enabled: boolean;
+  readonly bold: (text: string) => string;
+  readonly dim: (text: string) => string;
+  readonly red: (text: string) => string;
+  readonly green: (text: string) => string;
+  readonly yellow: (text: string) => string;
+  readonly cyan: (text: string) => string;
+}
+
+const identity = (text: string): string => text;
+
+export function colorEnabled(
+  env: Readonly<Record<string, string | undefined>>,
+  isTty: boolean,
+): boolean {
+  if (env.NO_COLOR !== undefined) {
+    return false;
+  }
+  if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0") {
+    return true;
+  }
+  return isTty;
+}
+
+export function createTheme(enabled: boolean): Theme {
+  if (!enabled) {
+    return {
+      enabled: false,
+      bold: identity,
+      dim: identity,
+      red: identity,
+      green: identity,
+      yellow: identity,
+      cyan: identity,
+    };
+  }
+
+  const wrap = (code: string) => {
+    return (text: string): string => `\u001B[${code}m${text}\u001B[0m`;
+  };
+
+  return {
+    enabled: true,
+    bold: wrap("1"),
+    dim: wrap("2"),
+    red: wrap("31"),
+    green: wrap("32"),
+    yellow: wrap("33"),
+    cyan: wrap("36"),
+  };
+}

package/src/config/baseline.ts

@@ -0,0 +1,116 @@
+import { defineError, type Result } from "../core/errors";
+import type { Finding } from "../report/types";
+
+/**
+ * Baseline / regression detection.
+ *
+ * A baseline records the findings you have already accepted, so CI can fail on
+ * what is *new* instead of on a repository's whole history. The fingerprint is
+ * deliberately coarse - rule, package and path, not the message - so rewriting
+ * a detail string does not resurrect a finding you have already triaged.
+ */
+export const BASELINE_SCHEMA_VERSION = 1;
+
+export interface Baseline {
+  readonly schemaVersion: number;
+  readonly findings: readonly string[];
+}
+
+export interface BaselineSummary {
+  readonly path: string;
+  readonly known: number;
+  readonly new: number;
+}
+
+export function fingerprint(finding: Finding): string {
+  return [finding.id, finding.package ?? "", finding.path ?? ""].join("|");
+}
+
+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`;
+}
+
+export function parseBaseline(text: string, source: string): Result<Baseline> {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    return {
+      ok: false,
+      error: defineError("E_PARSE", `${source} is not a valid baseline file`, {
+        hint: "regenerate it with `bunready <path> --write-baseline <file>`.",
+        cause: error,
+      }),
+    };
+  }
+
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return {
+      ok: false,
+      error: defineError("E_PARSE", `${source} must contain a JSON object`, {
+        hint: "regenerate it with `--write-baseline`.",
+      }),
+    };
+  }
+
+  const findings = (raw as { findings?: unknown }).findings;
+  if (!Array.isArray(findings)) {
+    return {
+      ok: false,
+      error: defineError("E_PARSE", `${source} has no findings array`, {
+        hint: "regenerate it with `--write-baseline`.",
+      }),
+    };
+  }
+
+  const schemaVersion = (raw as { schemaVersion?: unknown }).schemaVersion;
+  if (schemaVersion !== undefined && typeof schemaVersion !== "number") {
+    return {
+      ok: false,
+      error: defineError("E_PARSE", `${source} has a non-numeric schemaVersion`, {
+        hint: "regenerate it with `--write-baseline`.",
+      }),
+    };
+  }
+
+  return {
+    ok: true,
+    value: {
+      schemaVersion: typeof schemaVersion === "number" ? schemaVersion : BASELINE_SCHEMA_VERSION,
+      findings: findings.filter((entry): entry is string => typeof entry === "string"),
+    },
+  };
+}
+
+/** Mark each finding as new or already known, and count both. */
+export function applyBaseline(
+  findings: readonly Finding[],
+  baseline: Baseline,
+  baselinePath: string,
+): { readonly findings: readonly Finding[]; readonly summary: BaselineSummary } {
+  const known = new Set(baseline.findings);
+  let knownCount = 0;
+
+  const marked = findings.map((finding) => {
+    const isNew = !known.has(fingerprint(finding));
+    if (!isNew) {
+      knownCount += 1;
+    }
+    return { ...finding, isNew };
+  });
+
+  return {
+    findings: marked,
+    summary: { path: baselinePath, known: knownCount, new: marked.length - knownCount },
+  };
+}
+
+/** Only the findings a baseline should fail a build on. */
+export function newFindings(
+  findings: readonly Finding[],
+  hasBaseline: boolean,
+): readonly Finding[] {
+  return hasBaseline ? findings.filter((finding) => finding.isNew === true) : findings;
+}

package/src/config/config.ts

@@ -0,0 +1,113 @@
+import { defineError, type Result } from "../core/errors";
+import { SEVERITIES, type Severity } from "../rules/severity";
+
+/**
+ * `bunready.config.json`. Every knob here exists because a real repository
+ * needed to say "I know, and it is fine" without editing the tool's rules.
+ */
+export const CONFIG_FILENAME = "bunready.config.json";
+
+export interface RunConfig {
+  readonly script: string | undefined;
+  readonly maxCopyMegabytes: number;
+}
+
+export interface BunreadyConfig {
+  /** Finding ids to drop, e.g. `install/no-lockfile`. */
+  readonly ignore: readonly string[];
+  /** Package names to drop findings for, matched on the finding's package. */
+  readonly ignorePackages: readonly string[];
+  /** Packages never reported by the native-addon rule. */
+  readonly nativeAllowlist: readonly string[];
+  /** Substrings matched against source paths during the import scan. */
+  readonly excludePaths: readonly string[];
+  /** Lowest severity that makes the process exit non-zero. */
+  readonly failOn: Severity;
+  readonly run: RunConfig;
+}
+
+export const DEFAULT_CONFIG: BunreadyConfig = {
+  ignore: [],
+  ignorePackages: [],
+  nativeAllowlist: [],
+  excludePaths: [],
+  failOn: "blocker",
+  run: { script: undefined, maxCopyMegabytes: 250 },
+};
+
+export const DEFAULT_MAX_COPY_MEGABYTES = 250;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readStrings(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string")
+    : [];
+}
+
+function configError(source: string, detail: string, hint: string): Result<BunreadyConfig> {
+  return { ok: false, error: defineError("E_PARSE", `${source} ${detail}`, { hint }) };
+}
+
+export function parseConfig(text: string, source = CONFIG_FILENAME): Result<BunreadyConfig> {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    return {
+      ok: false,
+      error: defineError("E_PARSE", `${source} is not valid JSON`, {
+        hint: "fix the JSON syntax, or delete the file to use the defaults.",
+        cause: error,
+      }),
+    };
+  }
+
+  if (!isRecord(raw)) {
+    return configError(
+      source,
+      "must contain a JSON object",
+      "see docs/CONFIGURATION.md for the accepted keys.",
+    );
+  }
+
+  const failOnRaw = raw.failOn;
+  if (failOnRaw !== undefined && !(SEVERITIES as readonly unknown[]).includes(failOnRaw)) {
+    return configError(
+      source,
+      `has an unknown failOn value "${String(failOnRaw)}"`,
+      `use one of: ${SEVERITIES.join(", ")}.`,
+    );
+  }
+
+  const runRaw = isRecord(raw.run) ? raw.run : {};
+  const maxRaw = runRaw.maxCopyMegabytes;
+  if (
+    maxRaw !== undefined &&
+    (typeof maxRaw !== "number" || !Number.isFinite(maxRaw) || maxRaw <= 0)
+  ) {
+    return configError(
+      source,
+      "has an invalid run.maxCopyMegabytes",
+      "use a positive number of megabytes.",
+    );
+  }
+
+  return {
+    ok: true,
+    value: {
+      ignore: readStrings(raw.ignore),
+      ignorePackages: readStrings(raw.ignorePackages),
+      nativeAllowlist: readStrings(raw.nativeAllowlist),
+      excludePaths: readStrings(raw.excludePaths),
+      failOn: failOnRaw === undefined ? DEFAULT_CONFIG.failOn : (failOnRaw as Severity),
+      run: {
+        script:
+          typeof runRaw.script === "string" && runRaw.script !== "" ? runRaw.script : undefined,
+        maxCopyMegabytes: maxRaw === undefined ? DEFAULT_MAX_COPY_MEGABYTES : maxRaw,
+      },
+    },
+  };
+}

package/src/core/errors.ts

@@ -0,0 +1,59 @@
+/**
+ * Typed error model.
+ *
+ * bunready never throws across module boundaries. Every fallible operation
+ * returns a `Result`, and every failure carries enough context for the CLI to
+ * say what happened *and* what the user can do about it.
+ */
+
+/** Stable, machine-readable failure codes. Never reuse or renumber one. */
+export type ErrorCode = "E_USAGE" | "E_IO" | "E_PARSE" | "E_UNSUPPORTED" | "E_INTERNAL";
+
+/** A failure a caller can render, report, or recover from. */
+export interface BunreadyError {
+  readonly code: ErrorCode;
+  readonly message: string;
+  /** Concrete next step for the user. Optional in the type, preferred in practice. */
+  readonly hint?: string;
+  /** Original failure, kept for debugging. Never printed by default. */
+  readonly cause?: unknown;
+}
+
+export type Ok<T> = { readonly ok: true; readonly value: T };
+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;
+
+export function ok<T>(value: T): Ok<T> {
+  return { ok: true, value };
+}
+
+export function err<T = never>(error: BunreadyError): Result<T> {
+  return { ok: false, error };
+}
+
+export function isOk<T>(result: Result<T>): result is Ok<T> {
+  return result.ok;
+}
+
+export function isErr<T>(result: Result<T>): result is Err {
+  return !result.ok;
+}
+
+/** Build an error without ever assigning an explicit `undefined` optional field. */
+export function defineError(
+  code: ErrorCode,
+  message: string,
+  options: { readonly hint?: string; readonly cause?: unknown } = {},
+): BunreadyError {
+  const base: BunreadyError = { code, message };
+  const withHint = options.hint === undefined ? base : { ...base, hint: options.hint };
+  return options.cause === undefined ? withHint : { ...withHint, cause: options.cause };
+}
+
+/** One-line-first rendering used by the CLI. */
+export function formatError(error: BunreadyError): string {
+  const head = `${error.code}: ${error.message}`;
+  return error.hint === undefined ? head : `${head}\n  hint: ${error.hint}`;
+}

package/src/core/fs.ts

@@ -0,0 +1,72 @@
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { type BunreadyError, defineError } from "./errors";
+
+/**
+ * Result of one read attempt. "missing" and "error" are kept apart on purpose:
+ * a missing lockfile is normal and reportable, an unreadable one is a failure
+ * the user has to know about.
+ */
+export type ReadOutcome =
+  | { readonly kind: "text"; readonly text: string }
+  | { readonly kind: "missing" }
+  | { readonly kind: "error"; readonly error: BunreadyError };
+
+/** Minimal file seam, so scanners can be exercised without touching the disk. */
+export interface DirectoryEntry {
+  readonly name: string;
+  readonly isDirectory: boolean;
+}
+
+export interface FileSystem {
+  readonly readTextFile: (path: string) => Promise<ReadOutcome>;
+  readonly writeTextFile: (path: string, text: string) => Promise<void>;
+  readonly pathExists: (path: string) => Promise<boolean>;
+  readonly listDirectory: (path: string) => Promise<readonly DirectoryEntry[]>;
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function nodeFileSystem(): FileSystem {
+  return {
+    readTextFile: async (path) => {
+      try {
+        return { kind: "text", text: await readFile(path, "utf8") };
+      } catch (error) {
+        const code = (error as { code?: string }).code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+          return { kind: "missing" };
+        }
+        return {
+          kind: "error",
+          error: defineError("E_IO", `cannot read ${path}: ${describe(error)}`, {
+            hint: "check the file permissions, then run bunready again.",
+            cause: error,
+          }),
+        };
+      }
+    },
+    pathExists: async (path) => {
+      try {
+        await stat(path);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    writeTextFile: async (path, text) => {
+      await writeFile(path, text, "utf8");
+    },
+    listDirectory: async (path) => {
+      try {
+        const entries = await readdir(path, { withFileTypes: true });
+        return entries
+          .map((entry) => ({ name: entry.name, isDirectory: entry.isDirectory() }))
+          .sort((a, b) => a.name.localeCompare(b.name));
+      } catch {
+        return [];
+      }
+    },
+  };
+}

package/src/core/version.ts

@@ -0,0 +1,9 @@
+import packageJson from "../../package.json";
+
+/**
+ * Tool identity, in a module with no dependencies, so anything (CLI, scanner,
+ * report) can read it without importing the CLI and creating a cycle.
+ */
+export const TOOL_NAME = "bunready";
+
+export const TOOL_VERSION: string = packageJson.version;

package/src/report/human.ts

@@ -0,0 +1,100 @@
+import { verdictLine } from "../cli/copy";
+import type { Theme } from "../cli/theme";
+import type { Finding, ScanReport } from "./types";
+
+/**
+ * The human report.
+ *
+ * One finding per block, always the same shape: what, why, the evidence, the
+ * next step, the source. Colour is decoration - the severity word is always
+ * printed, so a monochrome log carries the same information.
+ */
+const LABEL_WIDTH = 7;
+
+function label(finding: Finding, theme: Theme): string {
+  switch (finding.severity) {
+    case "blocker":
+      return theme.red("blocker".padEnd(LABEL_WIDTH));
+    case "risk":
+      return theme.yellow("risk".padEnd(LABEL_WIDTH));
+    case "info":
+      return theme.cyan("info".padEnd(LABEL_WIDTH));
+  }
+}
+
+export function renderHumanReport(report: ScanReport, theme: Theme): string {
+  const lines: string[] = [];
+  const facts: string[] = [];
+
+  if (report.stats !== undefined) {
+    facts.push(`${report.stats.lockedPackages} locked packages`);
+    facts.push(`${report.stats.directDependencies + report.stats.devDependencies} direct`);
+    if (report.stats.duplicateVersions > 0) {
+      facts.push(`${report.stats.duplicateVersions} duplicated`);
+    }
+    if (report.stats.sourceFiles > 0) {
+      facts.push(`${report.stats.sourceFiles} source files`);
+    }
+    if (report.stats.lockfiles.length > 0) {
+      facts.push(
+        report.stats.lockfiles.map((path) => path.split(/[\\/]/).pop() ?? path).join(", "),
+      );
+    }
+  }
+
+  lines.push([theme.bold(`${report.tool} ${report.version}`), ...facts].join(theme.dim("  ·  ")));
+  lines.push(theme.dim(report.target));
+
+  if (report.targets !== undefined) {
+    lines.push(theme.dim(`${report.targets.length} scanned directories:`));
+    for (const target of report.targets) {
+      lines.push(
+        theme.dim(`  ${target.kind === "root" ? "." : target.relative}  ${target.verdict}`),
+      );
+    }
+  }
+
+  if (report.baseline !== undefined) {
+    lines.push(
+      theme.dim(
+        `baseline ${report.baseline.path}: ${report.baseline.known} known, ${report.baseline.new} new`,
+      ),
+    );
+  }
+
+  lines.push("");
+
+  if (report.findings.length === 0) {
+    lines.push("no findings");
+    lines.push("");
+  } else {
+    for (const finding of report.findings) {
+      lines.push(
+        `${label(finding, theme)} ${theme.bold(finding.title)}  ${theme.dim(`(${finding.id})`)}${
+          finding.isNew === true ? theme.dim("  new") : ""
+        }`,
+      );
+      if (report.targets !== undefined && finding.path !== undefined) {
+        lines.push(`  ${theme.dim("at:")} ${finding.path}`);
+      }
+      lines.push(`  ${finding.detail}`);
+      if (finding.evidence !== undefined) {
+        lines.push(`  ${theme.dim("evidence:")} ${finding.evidence}`);
+      }
+      if (finding.hint !== undefined) {
+        lines.push(`  ${theme.dim("next:")} ${finding.hint}`);
+      }
+      if (finding.source !== undefined) {
+        lines.push(`  ${theme.dim("source:")} ${finding.source}`);
+      }
+      lines.push("");
+    }
+  }
+
+  lines.push(
+    `${report.counts.blocker} blocker  ·  ${report.counts.risk} risk  ·  ${report.counts.info} info`,
+  );
+  lines.push(verdictLine(report.verdict, report.counts));
+
+  return lines.join("\n");
+}

package/src/report/json.ts

@@ -0,0 +1,11 @@
+import type { ScanReport } from "./types";
+
+/**
+ * The machine-readable report.
+ *
+ * Field names are the contract CI parses, so this stays a straight projection
+ * of `ScanReport`: nothing is added, renamed or reordered here.
+ */
+export function renderJsonReport(report: ScanReport): string {
+  return JSON.stringify(report, null, 2);
+}