@mh-alikhani/bunready 0.3.2 → 0.3.4

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

@@ -3,7 +3,7 @@ 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";
+import nativeDataset from "../data/native-packages.json" with { type: "json" };
 
 /**
  * Native-addon detection, in evidence order:
@@ -23,6 +23,7 @@ export interface NativePackageEntry {
   readonly source: string;
 }
 
+/** The build-tool packages the native-addon rule recognises. */
 export const BUILD_TOOL_PACKAGES = [
   "node-gyp",
   "node-pre-gyp",
@@ -56,6 +57,7 @@ export function readDataset(raw: unknown = nativeDataset): NativePackageEntry[]
   return entries;
 }
 
+/** Flags native addons that need a compiler toolchain. */
 export function nativeAddonFindings(
   snapshot: TargetSnapshot,
   graph: DependencyGraph,

package/src/rules/run/index.ts

@@ -21,6 +21,7 @@ function megabytes(bytes: number): string {
   return `${Math.round(bytes / (1024 * 1024))} MB`;
 }
 
+/** Turns the outcome of a run into findings. */
 export function runFindings(
   outcome: RunOutcome,
   options: RunOptions = DEFAULT_RUN_OPTIONS,

package/src/rules/runtime/builtins.ts

@@ -1,6 +1,6 @@
 import type { Finding } from "../../report/types";
 import { classifySpecifier, type SourceScan } from "../../scanner/sources";
-import runtimeDataset from "../data/node-runtime.json";
+import runtimeDataset from "../data/node-runtime.json" with { type: "json" };
 
 /**
  * Runtime-phase rule: what Node surface the repository actually depends on.
@@ -17,6 +17,7 @@ const GAP_ID = "runtime/known-gap";
 const COVERAGE_ID = "runtime/scan-coverage";
 const MAX_LISTED_MODULES = 8;
 
+/** One row of the Node runtime gap dataset. */
 export interface RuntimeGapEntry {
   readonly name: string;
   readonly status: "partial" | "unimplemented";
@@ -24,11 +25,13 @@ export interface RuntimeGapEntry {
   readonly source: string;
 }
 
+/** The shipped dataset of Node runtime gaps, each with its source. */
 export interface RuntimeDataset {
   readonly compatibilityDocs: string | undefined;
   readonly gaps: readonly RuntimeGapEntry[];
 }
 
+/** A Node built-in the project imports, with where it is used. */
 export interface BuiltinUsage {
   readonly name: string;
   readonly files: readonly string[];
@@ -92,6 +95,7 @@ function normalise(name: string): string {
   return name.startsWith("node:") ? name.slice(5) : name;
 }
 
+/** Reports the Node built-ins the project's own code imports. */
 export function runtimeBuiltinFindings(
   scan: SourceScan,
   usages: readonly BuiltinUsage[],

package/src/rules/severity.ts

@@ -9,6 +9,7 @@
 
 export const SEVERITIES = ["blocker", "risk", "info"] as const;
 
+/** Severity levels, ordered from most to least serious. */
 export type Severity = (typeof SEVERITIES)[number];
 
 /** Lower rank sorts first: blockers surface above everything else. */
@@ -18,10 +19,12 @@ export const SEVERITY_RANK: Readonly<Record<Severity, number>> = {
   info: 2,
 };
 
+/** Orders severities for sorting, blockers first. */
 export function compareSeverity(a: Severity, b: Severity): number {
   return SEVERITY_RANK[a] - SEVERITY_RANK[b];
 }
 
+/** Counts findings per severity. */
 export function countBySeverity(
   severities: readonly Severity[],
 ): Readonly<Record<Severity, number>> {

package/src/scanner/execute.ts

@@ -23,8 +23,10 @@ export const COPY_EXCLUDES = [
   ".cache",
 ] as const;
 
+/** Script names the run phase is willing to execute, in order of preference. */
 export const RUNNABLE_SCRIPTS = ["start", "test"] as const;
 
+/** Exit status and captured output of one child process. */
 export interface ProcessResult {
   readonly code: number | null;
   readonly stdout: string;
@@ -33,15 +35,18 @@ export interface ProcessResult {
   readonly durationMs: number;
 }
 
+/** Options for a single command invocation. */
 export interface RunCommandOptions {
   readonly cwd: string;
   readonly timeoutMs: number;
 }
 
+/** Runs a command; injected so tests need not spawn processes. */
 export interface CommandRunner {
   readonly run: (command: readonly string[], options: RunCommandOptions) => Promise<ProcessResult>;
 }
 
+/** What the run phase needs: a scratch directory and a way to run commands. */
 export interface RunEnvironment {
   readonly runner: CommandRunner;
   readonly makeTempDir: () => Promise<string>;
@@ -50,11 +55,13 @@ export interface RunEnvironment {
   readonly measureTreeBytes: (path: string) => Promise<number>;
 }
 
+/** A failure observed while running the project's scripts. */
 export interface RunFailure {
   readonly message: string;
   readonly frames: readonly string[];
 }
 
+/** What the run phase ended up doing, successful or not. */
 export interface RunOutcome {
   readonly workDir: string;
   readonly script: string | undefined;
@@ -67,6 +74,7 @@ export interface RunOutcome {
   readonly copyTooLarge: boolean;
 }
 
+/** Limits and toggles for the run phase. */
 export interface RunOptions {
   readonly installTimeoutMs: number;
   readonly scriptTimeoutMs: number;
@@ -75,6 +83,7 @@ export interface RunOptions {
   readonly script?: string;
 }
 
+/** The default run settings. */
 export const DEFAULT_RUN_OPTIONS: RunOptions = {
   installTimeoutMs: 180_000,
   scriptTimeoutMs: 120_000,
@@ -116,6 +125,7 @@ export function firstFailure(output: string): RunFailure | undefined {
   return { message: (lines[hinted] ?? "").trim(), frames: [] };
 }
 
+/** Chooses the script to run, when the project defines a runnable one. */
 export function pickScript(manifest: Manifest, requested?: string): string | undefined {
   if (requested !== undefined) {
     return typeof manifest.scripts[requested] === "string" ? requested : undefined;
@@ -123,10 +133,12 @@ export function pickScript(manifest: Manifest, requested?: string): string | und
   return RUNNABLE_SCRIPTS.find((name) => typeof manifest.scripts[name] === "string");
 }
 
+/** Whether a path is left out of the temporary copy the run phase works in. */
 export function isExcludedFromCopy(path: string): boolean {
   return (COPY_EXCLUDES as readonly string[]).includes(basename(path));
 }
 
+/** The CommandRunner that spawns commands with Bun. */
 export function bunCommandRunner(): CommandRunner {
   return {
     run: async (command, options) => {
@@ -189,6 +201,7 @@ async function treeBytes(path: string): Promise<number> {
   return total;
 }
 
+/** The real run environment: working directory, temp directory and runner. */
 export function systemRunEnvironment(): RunEnvironment {
   return {
     runner: bunCommandRunner(),
@@ -250,6 +263,7 @@ async function perform(
   };
 }
 
+/** Copies the project, installs, runs the chosen script and reports what happened. */
 export async function executeProject(
   dir: string,
   manifest: Manifest,

package/src/scanner/graph.ts

@@ -14,6 +14,7 @@ export interface DependencyGraph {
   readonly duplicates: readonly DuplicateVersion[];
 }
 
+/** A dependency resolved to more than one version. */
 export interface DuplicateVersion {
   readonly name: string;
   readonly versions: readonly string[];

package/src/scanner/lockfile.ts

@@ -17,8 +17,10 @@ import { defineError, type Result } from "../core/errors";
 
 export const LOCKFILE_KINDS = ["bun", "npm", "yarn", "pnpm"] as const;
 
+/** The lockfile formats the scanner understands. */
 export type LockfileKind = (typeof LOCKFILE_KINDS)[number];
 
+/** Lockfile filenames, in the order they are preferred. */
 export const LOCKFILE_FILENAMES: Readonly<Record<LockfileKind, string>> = {
   bun: "bun.lock",
   npm: "package-lock.json",
@@ -26,6 +28,7 @@ export const LOCKFILE_FILENAMES: Readonly<Record<LockfileKind, string>> = {
   pnpm: "pnpm-lock.yaml",
 };
 
+/** One package as recorded by a lockfile. */
 export interface LockedPackage {
   readonly name: string;
   readonly version: string;
@@ -36,6 +39,7 @@ export interface LockedPackage {
   readonly installScript: boolean;
 }
 
+/** A parsed lockfile: its format, packages and direct dependencies. */
 export interface ParsedLockfile {
   readonly kind: LockfileKind;
   readonly lockfileVersion: string | undefined;
@@ -527,6 +531,7 @@ function parsePnpmLock(text: string, path: string): Result<ParsedLockfile> {
   return { ok: true, value: { kind: "pnpm", lockfileVersion, packages: sortPackages(collected) } };
 }
 
+/** Parses lockfile text into packages, or reports why it could not. */
 export function parseLockfile(
   kind: LockfileKind,
   text: string,

package/src/scanner/manifest.ts

@@ -68,6 +68,7 @@ function readTrustedDependencies(value: unknown): string[] {
   return [];
 }
 
+/** Reads package.json, reporting malformed JSON as an error. */
 export function parseManifest(text: string, source: string): Result<Manifest> {
   let parsed: unknown;
   try {

package/src/scanner/scan.ts

@@ -40,6 +40,7 @@ export function detectRuntime(): RuntimeInfo {
   return { bun: Bun.version, node: process.versions.node };
 }
 
+/** Options for scanning a target: configuration, runtime versions and paths. */
 export interface ScanOptions {
   readonly fs?: FileSystem;
   readonly runtime?: RuntimeInfo;
@@ -75,6 +76,7 @@ async function scanOne(
   configPath: string | undefined,
   skipConfigDiscovery: boolean,
   rootConfig: TargetSnapshot["config"],
+  extraExcludePaths: readonly string[] = [],
 ): Promise<Result<TargetResult>> {
   const target = await readTarget(dir, fs, configPath, skipConfigDiscovery);
   if (!target.ok) {
@@ -84,7 +86,9 @@ async function scanOne(
   // One configuration governs the whole scan; a package's own file is ignored.
   const snapshot: TargetSnapshot = { ...target.value, config: rootConfig };
   const graph = buildGraph(snapshot.manifest, snapshot.lockfiles[0]?.parsed);
-  const sources = await scanSources(dir, fs, { excludePaths: rootConfig.excludePaths });
+  const sources = await scanSources(dir, fs, {
+    excludePaths: [...rootConfig.excludePaths, ...extraExcludePaths],
+  });
   const usages = collectNodeBuiltins(sources);
 
   const findings = [
@@ -176,7 +180,20 @@ export async function scanTarget(
 
   const targets: TargetResult[] = [];
 
-  const rootScan = await scanOne(dir, ".", "root", fs, runtime, options.configPath, false, config);
+  // The root's walk skips the packages: each one is scanned as its own target,
+  // and descending into them from the root spent the file budget on files that
+  // were about to be read a second time.
+  const rootScan = await scanOne(
+    dir,
+    ".",
+    "root",
+    fs,
+    runtime,
+    options.configPath,
+    false,
+    config,
+    packages.map((pkg) => `${pkg.relative}/`),
+  );
   if (!rootScan.ok) {
     return { ok: false, error: rootScan.error };
   }
@@ -271,16 +288,23 @@ export async function scanTarget(
   );
   const counts = countBySeverity(findings.map((finding) => finding.severity));
 
+  // Per-target verdicts are computed from the findings that survived config
+  // filtering, so a package can never say "blocked" while the overall report
+  // says "ready" because the blocker was ignored.
   const scannedTargets: readonly ScannedTarget[] =
     targets.length > 1
-      ? targets.map((target) => ({
-          path: target.dir,
-          relative: target.relative,
-          kind: target.kind,
-          name: target.name,
-          verdict: verdictFor(target.findings),
-          counts: countBySeverity(target.findings.map((finding) => finding.severity)),
-        }))
+      ? targets.map((target) => {
+          const normalized = target.dir.replace(/\\/g, "/");
+          const own = findings.filter((finding) => finding.path === normalized);
+          return {
+            path: target.dir.replace(/\\/g, "/"),
+            relative: target.relative,
+            kind: target.kind,
+            name: target.name,
+            verdict: verdictFor(own),
+            counts: countBySeverity(own.map((finding) => finding.severity)),
+          };
+        })
       : [];
 
   const builtinNames = new Set(targets.flatMap((target) => target.builtinNames));
@@ -292,7 +316,7 @@ export async function scanTarget(
       failOn: config.failOn,
       tool: TOOL_NAME,
       version: TOOL_VERSION,
-      target: dir,
+      target: dir.replace(/\\/g, "/"),
       verdict: verdictFor(findings),
       counts,
       findings,

package/src/scanner/semver.ts

@@ -27,6 +27,7 @@ type Disjunction = readonly Conjunction[];
 
 const VERSION_PATTERN = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?$/;
 
+/** Parses a semantic version, ignoring any surrounding operator. */
 export function parseVersion(text: string): ParsedVersion | undefined {
   const cleaned = text.trim().replace(/^[=v]+/, "");
   const match = VERSION_PATTERN.exec(cleaned);
@@ -52,6 +53,7 @@ function writtenParts(text: string): number {
   );
 }
 
+/** Orders two parsed versions. */
 export function compareVersions(a: ParsedVersion, b: ParsedVersion): number {
   if (a.major !== b.major) {
     return a.major < b.major ? -1 : 1;
@@ -161,6 +163,7 @@ function comparatorsForToken(token: string): Comparator[] | undefined {
   return exact === undefined ? undefined : [{ operator: "=", version: exact }];
 }
 
+/** Parses a version range into its operator and version parts. */
 export function parseRange(range: string): Disjunction | undefined {
   const trimmed = range.trim();
   if (trimmed === "" || trimmed === "*" || trimmed === "latest") {
@@ -212,6 +215,7 @@ const COMPARATOR_TESTS: Readonly<Record<Operator, (order: number) => boolean>> =
   "=": (order) => order === 0,
 };
 
+/** Whether a version satisfies a range. */
 export function satisfies(candidate: string, range: string): boolean | undefined {
   const parsedRange = parseRange(range);
   const parsedVersion = parseVersion(candidate);

package/src/scanner/sources.ts

@@ -23,6 +23,7 @@ export const SOURCE_EXTENSIONS = [
   ".cjs",
 ] as const;
 
+/** Directories the source walk never descends into. */
 export const IGNORED_DIRECTORIES = [
   "node_modules",
   ".git",
@@ -38,21 +39,26 @@ export const IGNORED_DIRECTORIES = [
   ".cache",
 ] as const;
 
+/** Cap on how many source files are read per target. */
 export const MAX_SOURCE_FILES = 2000;
 
+/** How a module was imported: static import, dynamic import or require. */
 export type ImportKind = "esm" | "cjs" | "dynamic";
 
+/** One import found in a file: its specifier, kind and line. */
 export interface ImportRef {
   readonly specifier: string;
   readonly kind: ImportKind;
   readonly line: number;
 }
 
+/** A source file read during the scan. */
 export interface SourceFile {
   readonly path: string;
   readonly imports: readonly ImportRef[];
 }
 
+/** What the walk found: files, imports, and whether the cap truncated it. */
 export interface SourceScan {
   readonly files: readonly SourceFile[];
   readonly filesScanned: number;
@@ -86,51 +92,82 @@ const STATEMENT_PATTERNS: readonly { kind: ImportKind; pattern: RegExp }[] = [
  * Replace the contents of strings and comments with spaces, preserving every
  * offset and newline.
  *
- * Without this, a test fixture that contains the text `import cluster from
- * "node:cluster"` inside a string literal was counted as a real import. Masking
- * keeps offsets aligned, so specifiers are read from the original text at the
- * position the anchor matched.
+ * Template literals are the interesting case: the literal text is still text,
+ * but a \`\${ ... }\` interpolation is real code and may contain imports, so the
+ * expression is scanned while the surrounding literal stays masked. Without
+ * this, \`\${require("node:fs")}\` counted as nothing, and string fixtures that
+ * merely contained import-shaped text were counted as imports.
  */
 export function maskNonCode(text: string): string {
   const out: string[] = [];
-  type Mode = "code" | "single" | "double" | "template" | "line" | "block";
-  let mode: Mode = "code";
+  type Frame =
+    | { readonly kind: "code"; readonly depth: number }
+    | { readonly kind: "string"; readonly quote: string }
+    | { readonly kind: "template" }
+    | { readonly kind: "line" }
+    | { readonly kind: "block" };
+  const frames: Frame[] = [{ kind: "code", depth: 0 }];
   let index = 0;
 
   const blank = (char: string): string => (char === "\n" ? "\n" : " ");
+  const top = (): Frame => frames[frames.length - 1] ?? { kind: "code", depth: 0 };
 
   while (index < text.length) {
     const char = text[index] ?? "";
     const next = text[index + 1] ?? "";
+    const frame = top();
 
-    if (mode === "code") {
+    if (frame.kind === "code") {
       if (char === "/" && next === "/") {
-        mode = "line";
+        frames.push({ kind: "line" });
         out.push("  ");
         index += 2;
         continue;
       }
       if (char === "/" && next === "*") {
-        mode = "block";
+        frames.push({ kind: "block" });
         out.push("  ");
         index += 2;
         continue;
       }
-      if (char === "'") {
-        mode = "single";
-      } else if (char === '"') {
-        mode = "double";
-      } else if (char === "`") {
-        mode = "template";
+      if (char === '"' || char === "'") {
+        frames.push({ kind: "string", quote: char });
+        out.push(char);
+        index += 1;
+        continue;
+      }
+      if (char === "`") {
+        frames.push({ kind: "template" });
+        out.push(char);
+        index += 1;
+        continue;
+      }
+      if (char === "{") {
+        frames[frames.length - 1] = { kind: "code", depth: frame.depth + 1 };
+        out.push(char);
+        index += 1;
+        continue;
+      }
+      if (char === "}") {
+        const parent = frames[frames.length - 2];
+        if (frame.depth === 0 && parent?.kind === "template") {
+          // The interpolation ended: back inside the template literal.
+          frames.pop();
+        } else {
+          frames[frames.length - 1] = { kind: "code", depth: Math.max(0, frame.depth - 1) };
+        }
+        out.push(char);
+        index += 1;
+        continue;
       }
       out.push(char);
       index += 1;
       continue;
     }
 
-    if (mode === "line") {
+    if (frame.kind === "line") {
       if (char === "\n") {
-        mode = "code";
+        frames.pop();
         out.push("\n");
       } else {
         out.push(" ");
@@ -139,30 +176,53 @@ export function maskNonCode(text: string): string {
       continue;
     }
 
-    if (mode === "block") {
+    if (frame.kind === "block") {
       if (char === "*" && next === "/") {
-        mode = "code";
+        frames.pop();
+        out.push("  ");
+        index += 2;
+        continue;
+      }
+      out.push(blank(char));
+      index += 1;
+      continue;
+    }
+
+    if (frame.kind === "string") {
+      if (char === "\\") {
         out.push("  ");
         index += 2;
         continue;
       }
+      if (char === frame.quote) {
+        frames.pop();
+        out.push(char);
+        index += 1;
+        continue;
+      }
       out.push(blank(char));
       index += 1;
       continue;
     }
 
-    const quote = mode === "single" ? "'" : mode === "double" ? '"' : "`";
+    // Template body: masked, except that ${ opens a code frame again.
     if (char === "\\") {
       out.push("  ");
       index += 2;
       continue;
     }
-    if (char === quote) {
-      mode = "code";
+    if (char === "`") {
+      frames.pop();
       out.push(char);
       index += 1;
       continue;
     }
+    if (char === "$" && next === "{") {
+      frames.push({ kind: "code", depth: 0 });
+      out.push("${");
+      index += 2;
+      continue;
+    }
     out.push(blank(char));
     index += 1;
   }
@@ -200,19 +260,36 @@ function readQuoted(text: string, from: number): string | undefined {
   return value === "" ? undefined : value;
 }
 
-function lineOf(text: string, index: number): number {
-  let line = 1;
-  for (let cursor = 0; cursor < index && cursor < text.length; cursor += 1) {
-    if (text[cursor] === "\n") {
-      line += 1;
+/** Newline offsets for one file, computed once and searched per match. */
+function newlinePositions(text: string): number[] {
+  const positions: number[] = [];
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "\n") {
+      positions.push(index);
+    }
+  }
+  return positions;
+}
+
+/** 1-based line for an offset, by binary search over the newline positions. */
+function lineAt(positions: readonly number[], index: number): number {
+  let low = 0;
+  let high = positions.length;
+  while (low < high) {
+    const mid = (low + high) >> 1;
+    if ((positions[mid] ?? 0) < index) {
+      low = mid + 1;
+    } else {
+      high = mid;
     }
   }
-  return line;
+  return low + 1;
 }
 
 function collect(
   masked: string,
   original: string,
+  newlines: readonly number[],
   pattern: RegExp,
   kind: ImportKind,
   into: ImportRef[],
@@ -222,17 +299,18 @@ function collect(
     if (specifier === undefined) {
       continue;
     }
-    into.push({ specifier, kind, line: lineOf(original, match.index) });
+    into.push({ specifier, kind, line: lineAt(newlines, match.index) });
   }
 }
 
 /** Extract every import/require specifier in one file's text. */
 export function extractImports(text: string): ImportRef[] {
   const masked = maskNonCode(text);
+  const newlines = newlinePositions(text);
   const refs: ImportRef[] = [];
 
   for (const { kind, pattern } of STATEMENT_PATTERNS) {
-    collect(masked, text, pattern, kind, refs);
+    collect(masked, text, newlines, pattern, kind, refs);
   }
 
   const seen = new Set<string>();
@@ -261,8 +339,10 @@ export function nodeBuiltinNames(): Set<string> {
   return names;
 }
 
+/** The categories an import specifier can fall into. */
 export type SpecifierKind = "node-builtin" | "bun-builtin" | "relative" | "absolute" | "package";
 
+/** Classifies an import specifier. */
 export function classifySpecifier(
   specifier: string,
   builtins: ReadonlySet<string> = nodeBuiltinNames(),
@@ -294,6 +374,7 @@ function hasSourceExtension(name: string): boolean {
   return SOURCE_EXTENSIONS.some((extension) => lower.endsWith(extension));
 }
 
+/** Limits for the source walk. */
 export interface ScanSourcesOptions {
   readonly maxFiles?: number;
   /** Substrings matched against each file path; a match skips the file. */
@@ -365,14 +446,16 @@ export async function scanSources(
       if (!hasSourceExtension(entry.name)) {
         continue;
       }
-      if (candidates.length >= maxFiles) {
-        truncated = true;
-        continue;
-      }
       const path = join(current, entry.name).replace(/\\/g, "/");
+      // Excluded before the budget is spent: a file the caller asked us to skip
+      // must not be what makes the scan report itself as truncated.
       if (excludePaths.some((fragment) => path.includes(fragment))) {
         continue;
       }
+      if (candidates.length >= maxFiles) {
+        truncated = true;
+        continue;
+      }
       candidates.push(path);
     }