@mh-alikhani/bunready 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Nothing yet.
 
+## [0.3.4] - 2026-09-16
+
+### Changed
+
+- Every exported symbol carries a doc comment. JSR scores how much of a
+  package's exported surface is documented; this package was at 48% and
+  is now at 100%. Comments only - no behaviour changed.
+
+
 ## [0.3.3] - 2026-09-16
 
 ### Fixed
@@ -248,8 +257,8 @@ Nothing yet.
   and that claim needs a primary source. Until then the rule reports what the
   repository imports and cites the compatibility table.
 
-[Unreleased]: https://github.com/MHAlikhani/bunready/compare/v0.3.3...HEAD
-[0.3.3]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.3
+[Unreleased]: https://github.com/MHAlikhani/bunready/compare/v0.3.4...HEAD
+[0.3.4]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.4
 [0.3.3]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.3
 [0.3.2]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.2
 [0.3.1]: https://github.com/MHAlikhani/bunready/releases/tag/v0.3.1

package/README.md

@@ -30,7 +30,7 @@ bunx @mh-alikhani/bunready --help     # every flag
 Scanning this repository prints its findings and one verdict:
 
 ```
-bunready 0.3.2  ·  106 locked packages  ·  bun.lock
+bunready 0.3.3  ·  106 locked packages  ·  bun.lock
 /path/to/your/project
 
 info  the project's own code imports 4 Node built-in module(s)  (runtime/node-builtins)
@@ -62,7 +62,7 @@ permissions:
 
 steps:
   - uses: actions/checkout@v7
-  - uses: MHAlikhani/bunready@v0.3.2
+  - uses: MHAlikhani/bunready@v0.3.3
     with:
       path: .
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mh-alikhani/bunready",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Bun-readiness scanner: one command that shows what will break before you move a Node/TS repo to Bun.",
   "keywords": [
     "bun",

package/src/cli/args.ts

@@ -16,6 +16,7 @@ export interface CliOptions {
   readonly writeBaseline: string | undefined;
 }
 
+/** Directory scanned when no path argument is given. */
 export const DEFAULT_TARGET = ".";
 
 /**

package/src/cli/copy.ts

@@ -8,16 +8,20 @@ import { TOOL_NAME } from "../core/version";
 import type { Verdict } from "../report/types";
 import type { Severity } from "../rules/severity";
 
+/** Product name as it appears in user-facing copy. */
 export const TOOL = TOOL_NAME;
 
+/** One-line positioning statement shown with the help text. */
 export const POSITIONING = "Know what breaks before you move a Node/TS repo to Bun.";
 
+/** Short tagline above the usage text. */
 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";
 
+/** Full help text: usage, options and exit codes. */
 export function helpText(version: string): string {
   return [
     `${TOOL} ${version}`,

package/src/cli/io.ts

@@ -6,6 +6,7 @@ export interface Io {
   readonly isTty: boolean;
 }
 
+/** The real stdin, stdout and stderr, coloured when the terminal allows it. */
 export function systemIo(): Io {
   return {
     out: (line) => {

package/src/cli/run.ts

@@ -12,10 +12,14 @@ import { helpText, RUN_WARNING, TOOL } from "./copy";
 import { type Io, systemIo } from "./io";
 import { colorEnabled, createTheme } from "./theme";
 
+/** Exit code for a scan with nothing at or above the failure threshold. */
 export const EXIT_OK = 0;
+/** Exit code for findings at or above the failure threshold. */
 export const EXIT_BLOCKERS = 1;
+/** Exit code for a usage error or an incomplete scan. */
 export const EXIT_USAGE = 2;
 
+/** The tool version, as reported by --version. */
 export function version(): string {
   return TOOL_VERSION;
 }

package/src/cli/theme.ts

@@ -17,6 +17,7 @@ export interface Theme {
 
 const identity = (text: string): string => text;
 
+/** Decides whether a stream's output should be coloured. */
 export function colorEnabled(
   env: Readonly<Record<string, string | undefined>>,
   isTty: boolean,
@@ -30,6 +31,7 @@ export function colorEnabled(
   return isTty;
 }
 
+/** Builds the colour palette used by the human-readable report. */
 export function createTheme(enabled: boolean): Theme {
   if (!enabled) {
     return {

package/src/config/baseline.ts

@@ -11,27 +11,32 @@ import type { Finding } from "../report/types";
  */
 export const BASELINE_SCHEMA_VERSION = 1;
 
+/** A recorded set of known findings, keyed by fingerprint. */
 export interface Baseline {
   readonly schemaVersion: number;
   readonly findings: readonly string[];
 }
 
+/** What a baseline comparison found: new, known and fixed entries. */
 export interface BaselineSummary {
   readonly path: string;
   readonly known: number;
   readonly new: number;
 }
 
+/** Stable identity of a finding: its rule, package and path. */
 export function fingerprint(finding: Finding): string {
   return [finding.id, finding.package ?? "", finding.path ?? ""].join("|");
 }
 
+/** Renders a baseline in its on-disk JSON form. */
 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`;
 }
 
+/** Reads a baseline file, reporting malformed input as an error. */
 export function parseBaseline(text: string, source: string): Result<Baseline> {
   let raw: unknown;
   try {

package/src/config/config.ts

@@ -7,11 +7,13 @@ import { SEVERITIES, type Severity } from "../rules/severity";
  */
 export const CONFIG_FILENAME = "bunready.config.json";
 
+/** Settings for the optional run phase. */
 export interface RunConfig {
   readonly script: string | undefined;
   readonly maxCopyMegabytes: number;
 }
 
+/** The parsed contents of the project's configuration file. */
 export interface BunreadyConfig {
   /** Finding ids to drop, e.g. `install/no-lockfile`. */
   readonly ignore: readonly string[];
@@ -26,6 +28,7 @@ export interface BunreadyConfig {
   readonly run: RunConfig;
 }
 
+/** Configuration used when the project has no config file. */
 export const DEFAULT_CONFIG: BunreadyConfig = {
   ignore: [],
   ignorePackages: [],
@@ -35,6 +38,7 @@ export const DEFAULT_CONFIG: BunreadyConfig = {
   run: { script: undefined, maxCopyMegabytes: 250 },
 };
 
+/** Copy limit before a project is refused as too large to run. */
 export const DEFAULT_MAX_COPY_MEGABYTES = 250;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -51,6 +55,7 @@ function configError(source: string, detail: string, hint: string): Result<Bunre
   return { ok: false, error: defineError("E_PARSE", `${source} ${detail}`, { hint }) };
 }
 
+/** Parses and validates configuration, returning errors instead of throwing. */
 export function parseConfig(text: string, source = CONFIG_FILENAME): Result<BunreadyConfig> {
   let raw: unknown;
   try {

package/src/core/errors.ts

@@ -19,24 +19,30 @@ export interface BunreadyError {
   readonly cause?: unknown;
 }
 
+/** A successful result. */
 export type Ok<T> = { readonly ok: true; readonly value: T };
+/** A failed result carrying an error. */
 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;
 
+/** Wraps a value in a successful result. */
 export function ok<T>(value: T): Ok<T> {
   return { ok: true, value };
 }
 
+/** Wraps an error in a failed result. */
 export function err<T = never>(error: BunreadyError): Result<T> {
   return { ok: false, error };
 }
 
+/** Narrows a result to its success case. */
 export function isOk<T>(result: Result<T>): result is Ok<T> {
   return result.ok;
 }
 
+/** Narrows a result to its failure case. */
 export function isErr<T>(result: Result<T>): result is Err {
   return !result.ok;
 }

package/src/core/fs.ts

@@ -17,6 +17,7 @@ export interface DirectoryEntry {
   readonly isDirectory: boolean;
 }
 
+/** The file operations the scanner needs, injected so tests can run in memory. */
 export interface FileSystem {
   readonly readTextFile: (path: string) => Promise<ReadOutcome>;
   readonly writeTextFile: (path: string, text: string) => Promise<void>;
@@ -28,6 +29,7 @@ function describe(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+/** The FileSystem implementation backed by node:fs. */
 export function nodeFileSystem(): FileSystem {
   return {
     readTextFile: async (path) => {

package/src/core/version.ts

@@ -1,4 +1,4 @@
-import packageJson from "../../package.json";
+import packageJson from "../../package.json" with { type: "json" };
 
 /**
  * Tool identity, in a module with no dependencies, so anything (CLI, scanner,
@@ -6,4 +6,5 @@ import packageJson from "../../package.json";
  */
 export const TOOL_NAME = "bunready";
 
+/** The tool's own version, used in reports. */
 export const TOOL_VERSION: string = packageJson.version;

package/src/report/human.ts

@@ -22,6 +22,7 @@ function label(finding: Finding, theme: Theme): string {
   }
 }
 
+/** Renders a report for a terminal: findings by severity, then the verdict. */
 export function renderHumanReport(report: ScanReport, theme: Theme): string {
   const lines: string[] = [];
   const facts: string[] = [];

package/src/report/sarif.ts

@@ -27,6 +27,7 @@ function worstByRule(
   return byRule;
 }
 
+/** Renders findings as SARIF 2.1.0 for code scanning. */
 export function renderSarifReport(report: ScanReport): string {
   const byRule = worstByRule(report.findings);
 

package/src/report/types.ts

@@ -29,6 +29,7 @@ export interface Finding {
   readonly hint?: string;
 }
 
+/** Overall judgement for a scan: blocked, risky or ready. */
 export type Verdict = "ready" | "risky" | "blocked";
 
 /** One scanned directory in a multi-package repository. */
@@ -110,6 +111,7 @@ export function sortFindings(findings: readonly Finding[]): Finding[] {
   });
 }
 
+/** The judgement a set of findings amounts to. */
 export function verdictFor(findings: readonly Finding[]): Verdict {
   let verdict: Verdict = "ready";
   for (const finding of findings) {

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

@@ -16,10 +16,12 @@ import type { TargetSnapshot } from "../../scanner/target";
  * facts; nothing is inferred from package names.
  */
 export const LIFECYCLE_DOC = "https://bun.com/docs/pm/lifecycle";
+/** Explains trustedDependencies, attached to lifecycle-script findings. */
 export const TRUSTED_DEPENDENCIES_GUIDE = "https://bun.com/guides/install/trusted";
 
 const ID = "install/lifecycle-script";
 
+/** Flags install scripts that will not run unless the package is trusted. */
 export function lifecycleScriptFindings(
   snapshot: TargetSnapshot,
   lockfile: ParsedLockfile | undefined,

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

@@ -13,6 +13,7 @@ const BINARY_LOCKFILE_ID = "install/binary-lockfile";
 const UNPARSED_LOCKFILE_ID = "install/unparsed-lockfile";
 const MULTIPLE_LOCKFILES_ID = "install/multiple-lockfiles";
 
+/** Reports lockfiles that are missing, unreadable or Bun-unfriendly. */
 export function lockfileFindings(snapshot: TargetSnapshot): Finding[] {
   const findings: Finding[] = [];
 

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;

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;
@@ -333,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(),
@@ -366,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. */

package/src/scanner/target.ts

@@ -25,18 +25,21 @@ export interface PackageEvidence {
   readonly installScripts: readonly string[];
 }
 
+/** A lockfile that was found and parsed. */
 export interface LoadedLockfile {
   readonly kind: LockfileKind;
   readonly path: string;
   readonly parsed: ParsedLockfile;
 }
 
+/** A lockfile that was found but could not be parsed. */
 export interface UnparsedLockfile {
   readonly kind: LockfileKind;
   readonly path: string;
   readonly message: string;
 }
 
+/** Everything read from one target directory: manifest, lockfiles, sources and config. */
 export interface TargetSnapshot {
   readonly dir: string;
   readonly manifestPath: string;
@@ -116,6 +119,7 @@ async function probeInstalledPackage(
   };
 }
 
+/** Reads a directory's manifest, lockfiles, sources and configuration. */
 export async function readTarget(
   dir: string,
   fs: FileSystem = nodeFileSystem(),

package/src/scanner/workspaces.ts

@@ -23,11 +23,13 @@ export const WORKSPACE_EXCLUDES = [
 
 const MAX_DEPTH = 3;
 
+/** A workspace package: its directory and its manifest. */
 export interface WorkspacePackage {
   /** Directory relative to the workspace root, using forward slashes. */
   readonly relative: string;
 }
 
+/** Reads the workspace globs from package.json or pnpm-workspace.yaml. */
 export function workspacePatterns(manifest: Manifest, pnpmWorkspace: string | undefined): string[] {
   if (manifest.workspaces.length > 0) {
     return [...manifest.workspaces]
@@ -145,6 +147,7 @@ function stripTrailingSlashes(value: string): string {
   return value.slice(0, end);
 }
 
+/** Resolves workspace patterns to the packages they match. */
 export async function findWorkspacePackages(
   root: string,
   patterns: readonly string[],
@@ -177,6 +180,7 @@ export async function findWorkspacePackages(
   return [...found.values()].sort((a, b) => a.relative.localeCompare(b.relative));
 }
 
+/** Filename of the pnpm workspace file. */
 export const PNPM_WORKSPACE_FILENAME = "pnpm-workspace.yaml";
 
 /** Read and parse `pnpm-workspace.yaml`, if it is there. */