react-native-doctor-ci 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,736 @@
+/**
+ * Tool version, kept in a leaf module so reporters can embed it without
+ * importing the package entry point (which would create an import cycle).
+ * @packageDocumentation
+ */
+/**
+ * The rn-doctor tool version. Kept in sync with package.json by release-it.
+ */
+declare const VERSION = "0.0.0";
+
+/**
+ * Core types for the enrichment engine.
+ * @packageDocumentation
+ */
+/**
+ * A value that may be known or unknown, with a reason if not.
+ * Used to represent partial/failed lookups without lying about them.
+ *
+ * @typeParam T - The value type when known.
+ */
+type Signal<T> = {
+    readonly known: true;
+    readonly value: T;
+    readonly source: string;
+} | {
+    readonly known: false;
+    readonly reason: UnknownReason;
+};
+/**
+ * Reasons a signal could not be resolved.
+ * Distinguishes between durable (expected, won't retry) and transient (might retry).
+ */
+type UnknownReason = "not-in-directory" | "no-repo-url" | "no-github-token" | "github-rate-limited" | "github-error" | "npm-not-found" | "npm-lookup-failed" | "npm-search-no-match";
+/**
+ * New Architecture support tier, as determined by RN Directory and codegen hints.
+ */
+type NewArchTier = "supported" | "unsupported" | "passWithNote" | "unknown";
+/**
+ * Reason(s) a package is classified as React Native native.
+ */
+type RnNativeReason = "directory-listed" | "peer-dependency" | "native-files-hint";
+/**
+ * A warning about data loss or degradation during enrichment.
+ * Per-dependency when narrowly scoped; run-level when absent `.dependency`.
+ */
+interface EnrichmentWarning {
+    readonly dependency?: string;
+    readonly source: "npm" | "directory" | "github" | "cache" | "git" | "workspaces";
+    readonly message: string;
+}
+/**
+ * Enriched metadata for a single dependency, gathered from npm, RN Directory, and GitHub.
+ * Carries raw signals; Phase 2's policy engine turns these into pass/warn/error verdicts.
+ */
+interface EnrichedDependency {
+    readonly name: string;
+    readonly warnings: readonly EnrichmentWarning[];
+    readonly npm: {
+        readonly found: boolean;
+        readonly latestVersion: string | null;
+        readonly deprecated: Signal<{
+            readonly deprecated: boolean;
+            readonly message: string | null;
+        }>;
+        readonly hasCodegenConfig: Signal<boolean>;
+        readonly hasReactNativePeerDep: Signal<boolean>;
+        readonly hasNativeDirsHint: Signal<boolean>;
+        readonly repositoryUrl: string | null;
+    };
+    readonly directory: {
+        readonly listed: boolean;
+        readonly unmaintained: boolean;
+        readonly newArchitectureRaw: "new-arch-only" | "supported" | "unsupported" | "untested" | null;
+        readonly githubUrl: string | null;
+        readonly lastPublishedAt: string | null;
+        readonly githubArchived: boolean | null;
+        readonly githubPushedAt: string | null;
+        readonly matchingScoreModifiers: readonly string[];
+    };
+    readonly github: {
+        readonly archived: Signal<boolean>;
+        readonly pushedAt: Signal<string>;
+        readonly repoUrl: string | null;
+        readonly source: "github-api" | "directory-fallback" | null;
+    };
+    readonly isRnNative: boolean;
+    readonly rnNativeReasons: readonly RnNativeReason[];
+    readonly newArch: {
+        readonly tier: NewArchTier;
+        readonly evidence: {
+            readonly directoryVerdict: string | null;
+            readonly hasCodegenConfig: boolean | null;
+        };
+    };
+    readonly lastPublish: Signal<{
+        readonly date: string;
+    }>;
+}
+/**
+ * Enrichment result: the enriched dependencies plus run-level warnings.
+ */
+interface EnrichmentResult {
+    readonly dependencies: readonly EnrichedDependency[];
+    readonly warnings: readonly EnrichmentWarning[];
+}
+/**
+ * Options for the enrichment run.
+ */
+interface EnrichmentOptions {
+    readonly noCache?: boolean;
+    readonly githubToken?: string;
+    readonly concurrency?: number;
+    readonly cacheDir?: string;
+}
+
+/**
+ * Enrichment engine orchestrator.
+ * Coordinates data gathering from npm, RN Directory, and GitHub.
+ * @packageDocumentation
+ */
+
+/**
+ * Enrich multiple dependencies from npm, RN Directory, and GitHub.
+ */
+declare function enrichDependencies(names: readonly string[], options?: EnrichmentOptions): Promise<EnrichmentResult>;
+
+/**
+ * Policy engine: turns enriched dependency records into findings.
+ *
+ * Pure and deterministic — no I/O, no clock reads unless the caller omits
+ * `options.now`. Reporters (Phase 3) consume the `Finding[]` output.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Identifier of a policy rule; also the `rule` field on emitted findings.
+ */
+type RuleId = "newArchitecture" | "newArchUnknown" | "lastPublish" | "githubArchived" | "npmDeprecated" | "directoryUnmaintained";
+/**
+ * Severity a rule can be configured to fire at. `off` disables the rule.
+ */
+type RuleSeverity = "error" | "warn" | "off";
+/**
+ * Staleness thresholds for the `lastPublish` rule, in months since the
+ * latest npm publish. `errorMonths` should be greater than `warnMonths`.
+ */
+interface LastPublishThresholds {
+    readonly warnMonths: number;
+    readonly errorMonths: number;
+}
+/**
+ * Which dependencies the policy applies to: only those detected as React
+ * Native native modules, or every dependency.
+ */
+type PolicyScope = "rn-native-only" | "all-deps";
+/**
+ * One allowlist entry: suppresses findings for `package` until `expires`.
+ * An expired entry escalates the findings it used to suppress to `error`.
+ */
+interface AllowEntry {
+    /** Exact npm package name the entry applies to. */
+    readonly package: string;
+    /** Why the package is allowed (shown in reports). */
+    readonly reason: string | null;
+    /** `YYYY-MM-DD` (inclusive, UTC). `null` means the entry never expires. */
+    readonly expires: string | null;
+}
+/**
+ * Per-rule severity configuration.
+ */
+interface PolicyRules {
+    /** How to treat a package the RN Directory marks New-Architecture-unsupported. */
+    readonly newArchitecture: RuleSeverity;
+    /** How to treat a package whose New Architecture support cannot be determined. */
+    readonly newArchUnknown: RuleSeverity;
+    /** Staleness thresholds for the latest npm publish, or `off`. */
+    readonly lastPublish: LastPublishThresholds | "off";
+    /** How to treat a package whose GitHub repository is archived. */
+    readonly githubArchived: RuleSeverity;
+    /** How to treat a package deprecated on npm. */
+    readonly npmDeprecated: RuleSeverity;
+    /** How to treat a package the RN Directory flags as unmaintained. */
+    readonly directoryUnmaintained: RuleSeverity;
+}
+/**
+ * A complete policy: rule severities, scope, and the allowlist.
+ */
+interface Policy {
+    readonly rules: PolicyRules;
+    readonly scope: PolicyScope;
+    readonly allow: readonly AllowEntry[];
+}
+/**
+ * The default policy, used when no `.rn-doctor.yml` is present.
+ * Matches the documented sample: hard failures for clearly-dead signals,
+ * warnings where data is merely missing (honest, not alarmist).
+ */
+declare const DEFAULT_POLICY: Policy;
+/**
+ * Severity of an emitted finding. `note` is informational — it never fails
+ * the run and is not subject to allowlisting.
+ */
+type FindingSeverity = "error" | "warn" | "note";
+/**
+ * A single policy violation (or informational note) for one dependency.
+ */
+interface Finding {
+    /** npm package name the finding is about. */
+    readonly package: string;
+    /** The rule that produced the finding. */
+    readonly rule: RuleId;
+    /** Effective severity after allowlist processing. */
+    readonly severity: FindingSeverity;
+    /** Human-readable verdict + reason + what to do about it. */
+    readonly message: string;
+    /** Link to the evidence backing the verdict, when one exists. */
+    readonly evidenceUrl: string | null;
+    /**
+     * Set when an active allowlist entry suppresses this finding. Suppressed
+     * findings keep their severity for display but must not fail the run.
+     */
+    readonly suppressedBy: {
+        readonly reason: string | null;
+        readonly expires: string | null;
+    } | null;
+}
+/**
+ * Options for {@link evaluatePolicy}.
+ */
+interface EvaluateOptions {
+    /** Clock used for staleness and allowlist expiry. Defaults to `new Date()`. */
+    readonly now?: Date;
+}
+/**
+ * Evaluate a policy against enriched dependencies and produce findings.
+ *
+ * @remarks
+ * Pure: same inputs (including `options.now`) always yield the same output,
+ * in a stable order (input dependency order, then a fixed rule order).
+ *
+ * Allowlist semantics: an **active** entry keeps the finding visible but sets
+ * {@link Finding.suppressedBy} (reporters must not fail the run on suppressed
+ * findings); an **expired** entry escalates the finding to `error` and says
+ * so in the message. `note` findings are informational and unaffected.
+ *
+ * @param dependencies - Enriched records from the enrichment engine.
+ * @param policy - The effective policy (see {@link DEFAULT_POLICY}).
+ * @param options - Evaluation options; inject `now` for deterministic output.
+ * @returns All findings, unfiltered — including suppressed ones.
+ */
+declare function evaluatePolicy(dependencies: readonly EnrichedDependency[], policy: Policy, options?: EvaluateOptions): readonly Finding[];
+
+/**
+ * `.rn-doctor.yml` loading and validation.
+ *
+ * Parses the policy file with `yaml`, validates the untyped result with
+ * explicit type guards (typo protection: unknown keys and bad values are
+ * rejected with actionable messages), and merges partial user config over
+ * {@link DEFAULT_POLICY}.
+ *
+ * @packageDocumentation
+ */
+
+/** The policy file name looked up in the working directory by default. */
+declare const DEFAULT_POLICY_FILENAME = ".rn-doctor.yml";
+/**
+ * A policy file could not be read or is invalid. Maps to exit code 2
+ * (tool failure) in the CLI — a broken policy must never silently pass.
+ */
+declare class PolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse and validate policy YAML text into a complete {@link Policy}.
+ *
+ * Absent keys fall back to {@link DEFAULT_POLICY}; unknown keys and invalid
+ * values throw {@link PolicyError} with the offending key named.
+ *
+ * @param yamlText - Raw contents of a `.rn-doctor.yml` file.
+ * @param filePath - Optional path used to contextualize error messages.
+ * @returns The validated policy, merged over the defaults.
+ */
+declare function parsePolicy(yamlText: string, filePath?: string): Policy;
+/**
+ * Load the effective policy from disk.
+ *
+ * @remarks
+ * - With an explicit `path`: the file must exist — a missing file is a
+ *   {@link PolicyError} (a CI run pointing at a typo'd path must not
+ *   silently fall back to defaults).
+ * - Without a `path`: looks for `.rn-doctor.yml` in `cwd`; if absent,
+ *   returns {@link DEFAULT_POLICY}.
+ *
+ * @param path - Optional explicit policy file path.
+ * @param cwd - Directory searched for the default file. Defaults to `process.cwd()`.
+ * @returns The validated effective policy.
+ */
+declare function loadPolicy(path?: string, cwd?: string): Promise<Policy>;
+
+/**
+ * Shared reporter surface: the report shape every renderer consumes, the
+ * finding summary, and the exit-code contract.
+ * @packageDocumentation
+ */
+
+/**
+ * A policy finding located in a specific manifest file. The CLI decorates
+ * pure policy findings with their manifest path at report-assembly time; the
+ * policy engine itself stays manifest-blind.
+ */
+interface ReportFinding extends Finding {
+    /**
+     * Manifest path relative to the run cwd, POSIX separators — `package.json`
+     * for single-manifest runs, e.g. `packages/a/package.json` under
+     * `--workspaces`.
+     */
+    readonly file: string;
+}
+/**
+ * Everything a reporter needs to render one rn-doctor run.
+ */
+interface Report {
+    /** Findings from the policy engine, grouped by manifest in its stable output order. */
+    readonly findings: readonly ReportFinding[];
+    /** Run-level and per-dependency enrichment warnings (degraded data, etc.). */
+    readonly warnings: readonly EnrichmentWarning[];
+    /** How many (manifest, dependency) pairs were checked across all scanned manifests. */
+    readonly checkedCount: number;
+    /**
+     * How many manifests were scanned. Omitted (equivalent to 1) outside
+     * `--workspaces`; the pretty reporter mentions it only when above 1.
+     */
+    readonly manifestCount?: number;
+}
+/**
+ * Decorate pure policy findings with the manifest they belong to.
+ *
+ * @param findings - Findings from {@link evaluatePolicy}.
+ * @param file - Manifest path relative to the run cwd, POSIX separators.
+ */
+declare function locateFindings(findings: readonly Finding[], file: string): readonly ReportFinding[];
+/**
+ * Counts of findings by effect. Suppressed findings are counted only under
+ * `suppressed` — they keep their severity for display but have no effect on
+ * the run outcome.
+ */
+interface FindingSummary {
+    readonly errors: number;
+    readonly warnings: number;
+    readonly notes: number;
+    readonly suppressed: number;
+}
+/**
+ * Summarize findings for the pretty footer and the JSON document.
+ */
+declare function summarize(findings: readonly Finding[]): FindingSummary;
+/**
+ * The stable exit-code contract for policy outcomes.
+ *
+ * @remarks
+ * Returns `1` iff any finding is an unsuppressed `error`; warnings, notes,
+ * and allowlist-suppressed findings never fail the run. Exit code `2`
+ * (tool failure) is decided by the CLI, not here — a report that rendered
+ * at all is not a tool failure.
+ */
+declare function computeExitCode(findings: readonly Finding[]): 0 | 1;
+
+/**
+ * JSON reporter: a machine-readable document with a stable key order, safe
+ * to snapshot and to diff across runs.
+ * @packageDocumentation
+ */
+
+/**
+ * Render the report as a stable-ordered JSON document.
+ *
+ * @remarks
+ * Key order is fixed by construction (every object is rebuilt field by
+ * field), and the document contains no timestamps or environment-dependent
+ * values, so identical inputs always serialize identically. The `version`
+ * field is the document format version, bumped only on breaking shape
+ * changes — additive fields (like `file`, added for `--workspaces`) do not
+ * bump it.
+ *
+ * @param report - The report to render.
+ * @returns Pretty-printed JSON, terminated with a newline.
+ */
+declare function renderJson(report: Report): string;
+
+/**
+ * SARIF 2.1.0 reporter, for GitHub code scanning and other SARIF consumers.
+ * The output validates against the OASIS SARIF 2.1.0 schema (enforced by the
+ * acceptance suite).
+ * @packageDocumentation
+ */
+
+/**
+ * Options for {@link renderSarif}.
+ */
+interface SarifOptions {
+    /**
+     * Resolve a package's 1-based declaration line in the manifest at `file`
+     * (the finding's cwd-relative manifest path), or `null` when unknown. When
+     * omitted (or when it returns `null`), results still carry the manifest
+     * artifact location, just without a region.
+     */
+    readonly lineOf?: (file: string, packageName: string) => number | null;
+}
+/**
+ * Render the report as a SARIF 2.1.0 log with a single run.
+ *
+ * @remarks
+ * Severity maps `error` → `"error"`, `warn` → `"warning"`, `note` → `"note"`.
+ * Allowlist-suppressed findings are emitted with a `suppressions` entry
+ * (`kind: "external"`, `status: "accepted"`) so SARIF consumers exclude them
+ * from gating, mirroring the CLI exit-code contract. Enrichment warnings are
+ * carried as tool execution notifications on the invocation.
+ *
+ * @param report - The report to render.
+ * @param options - Line resolution for annotating package.json regions.
+ * @returns Pretty-printed SARIF JSON, terminated with a newline.
+ */
+declare function renderSarif(report: Report, options?: SarifOptions): string;
+
+/**
+ * Human-readable terminal reporter: one block per finding (verdict, reason,
+ * evidence link), enrichment warnings, and a summary footer.
+ * @packageDocumentation
+ */
+
+/**
+ * Options for {@link renderPretty}.
+ */
+interface PrettyOptions {
+    /**
+     * Enable ANSI colors. The CLI passes `stdout.isTTY && !NO_COLOR`; tests
+     * pass `false` for stable snapshots.
+     */
+    readonly color: boolean;
+}
+/**
+ * Render the report for human eyes.
+ *
+ * @remarks
+ * When the findings span more than one manifest (a `--workspaces` run), each
+ * group is introduced by its manifest path; single-manifest output is
+ * unchanged.
+ *
+ * @param report - The report to render.
+ * @param options - Color toggling; content is identical either way.
+ * @returns The full report text, terminated with a newline.
+ */
+declare function renderPretty(report: Report, options: PrettyOptions): string;
+
+/**
+ * GitHub Actions annotation reporter: emits workflow commands
+ * (`::error file=package.json,line=N::message`) so findings appear inline on
+ * the PR diff.
+ * @packageDocumentation
+ */
+
+/**
+ * Render the report as GitHub Actions workflow commands, one per finding.
+ *
+ * @remarks
+ * Each command targets the finding's manifest (`package.json`, or e.g.
+ * `packages/a/package.json` under `--workspaces`) with the dependency's
+ * declaration line when `lineOf` resolves one (omitting `line=` otherwise),
+ * so annotations land inline on the PR diff. Suppressed findings keep an
+ * annotation (as a `notice` including the allow reason) so policy debt stays
+ * visible without failing checks.
+ *
+ * @param report - The report to render.
+ * @param lineOf - Resolve a package's 1-based declaration line in the
+ * manifest at `file` (the finding's cwd-relative path), or `null`.
+ * @returns Newline-terminated workflow commands; empty string when there are
+ * no findings.
+ */
+declare function renderAnnotations(report: Report, lineOf: (file: string, packageName: string) => number | null): string;
+
+/**
+ * package.json reading and dependency-line resolution for the CLI and the
+ * GitHub-annotation reporter.
+ *
+ * The enrichment engine itself stays manifest-agnostic (it takes plain
+ * package names); everything in this module is CLI-side plumbing.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A project manifest could not be read or parsed. Maps to exit code 2
+ * (tool failure) in the CLI.
+ */
+declare class ManifestError extends Error {
+    constructor(message: string);
+}
+/**
+ * One dependency declaration from a `dependencies` section: the package name
+ * and its raw version spec string, exactly as authored.
+ */
+interface DependencyEntry {
+    readonly name: string;
+    /** The raw spec (`"^1.2.0"`, `"npm:foo@2"`, …) — never parsed as semver. */
+    readonly spec: string;
+}
+/**
+ * A loaded package.json: the raw text (for line resolution) and the
+ * dependency names to check, in the order they are authored.
+ */
+interface ProjectManifest {
+    /** Absolute path the manifest was read from. */
+    readonly path: string;
+    /** The raw file text, used to resolve dependency line numbers. */
+    readonly text: string;
+    /** Names from the `dependencies` section, in authored order. */
+    readonly dependencies: readonly string[];
+    /** Name/spec pairs from the `dependencies` section, in authored order. */
+    readonly entries: readonly DependencyEntry[];
+}
+/**
+ * Extract name/spec pairs from the `dependencies` section of a parsed
+ * package.json value, preserving authored order. Returns an empty list when
+ * the section is absent; throws {@link ManifestError} when the section or a
+ * spec value has the wrong shape.
+ *
+ * @param parsed - The JSON-parsed manifest.
+ * @param where - Human-readable location used in error messages.
+ */
+declare function listDependencyEntries(parsed: unknown, where?: string): readonly DependencyEntry[];
+/**
+ * Extract the names of the `dependencies` section from a parsed package.json
+ * value, preserving authored order. Returns an empty list when the section is
+ * absent; throws {@link ManifestError} when it is present but not an object.
+ *
+ * @param parsed - The JSON-parsed manifest.
+ * @param where - Human-readable location used in error messages.
+ */
+declare function listDependencies(parsed: unknown, where?: string): readonly string[];
+/**
+ * Parse raw manifest text (e.g. a blob read from git) into dependency
+ * entries. BOM-tolerant like {@link readPackageJson}.
+ *
+ * @param text - The raw manifest text.
+ * @param where - Human-readable location used in error messages.
+ * @throws ManifestError when the text is not valid JSON or has a malformed
+ * `dependencies` section.
+ */
+declare function entriesFromManifestText(text: string, where: string): readonly DependencyEntry[];
+/**
+ * Read and parse the manifest at an exact path.
+ *
+ * @param path - Absolute path of the package.json to read.
+ * @param missingMessage - Error message when the file does not exist; defaults
+ * to a plain "not found" pointing at `path`.
+ * @returns The manifest text and its dependency entries.
+ * @throws ManifestError when the file is missing or not valid JSON — the CLI
+ * turns this into exit code 2 with the message shown as-is.
+ */
+declare function readManifestAt(path: string, missingMessage?: string): Promise<ProjectManifest>;
+/**
+ * Read and parse `<cwd>/package.json`.
+ *
+ * @param cwd - Directory containing the manifest.
+ * @returns The manifest text and its dependency names.
+ * @throws ManifestError when the file is missing or not valid JSON — the CLI
+ * turns this into exit code 2 with the message shown as-is.
+ */
+declare function readPackageJson(cwd: string): Promise<ProjectManifest>;
+/**
+ * Resolve the 1-based line number where `name` is declared inside the
+ * top-level `dependencies` object of a package.json text.
+ *
+ * @remarks
+ * Scans the raw text with a minimal JSON walker (string- and escape-aware,
+ * tracking object depth), so a key with the same name under `devDependencies`,
+ * `scripts`, or a nested object can never false-match. Returns `null` when the
+ * name is not declared in `dependencies` — annotations then omit the line.
+ *
+ * @param text - The raw package.json text (not re-serialized — the real file).
+ * @param name - The exact dependency name to locate.
+ */
+declare function findDependencyLine(text: string, name: string): number | null;
+
+/**
+ * Pure `--changed-only` semantics: which dependencies of the current manifest
+ * were added or changed relative to the base manifest. No git knowledge here —
+ * the CLI composes this with the blob reads from `git.ts`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Names to check under `--changed-only`: additions (name absent at base) and
+ * changes (raw spec string differs — upgrades, downgrades, and protocol
+ * changes like an `npm:` alias all count; re-checking is always safe).
+ * Removed and unchanged dependencies are skipped.
+ *
+ * @param base - Entries at the base commit, or `null` when the manifest did
+ * not exist there — every current dependency then counts as added.
+ * @param current - Entries in the working-tree manifest.
+ * @returns Names in `current` authored order.
+ */
+declare function diffDependencies(base: readonly DependencyEntry[] | null, current: readonly DependencyEntry[]): readonly string[];
+
+/**
+ * Git plumbing for `--changed-only`: resolve the diff base (merge-base of HEAD
+ * and the base ref) and read manifest blobs at that commit.
+ *
+ * This is the only module in the codebase that touches `child_process`; the
+ * process runner is injectable so everything above it is testable without a
+ * real repository.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A git invocation failed in a way rn-doctor cannot recover from. Maps to
+ * exit code 2 (tool failure) in the CLI; the message says what to do.
+ */
+declare class GitError extends Error {
+    constructor(message: string);
+}
+/** Result of one git invocation. */
+interface GitRunResult {
+    /** Process exit code (0 = success). */
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Injectable git process runner. Resolves with the exit code rather than
+ * rejecting on nonzero exit — callers classify failures themselves. Throws
+ * {@link GitError} only when git cannot be spawned at all.
+ */
+type GitRunner = (args: readonly string[], cwd: string) => Promise<GitRunResult>;
+/**
+ * The real runner: spawns the `git` binary via `execFile` (args array, no
+ * shell, so refs and Windows paths need no quoting).
+ */
+declare function createGitRunner(): GitRunner;
+/**
+ * Resolve the commit to diff against: `merge-base(HEAD, baseRef)`.
+ *
+ * @remarks
+ * The merge-base (not the base tip) reproduces GitHub's three-dot PR diff:
+ * dependency changes that landed on the base branch after the PR diverged are
+ * never attributed to the PR. On the base branch itself the merge-base is HEAD,
+ * so `--changed-only` correctly reports zero changes.
+ *
+ * @param git - The process runner.
+ * @param cwd - Directory to run git in (the project root being checked).
+ * @param baseRef - The base ref, e.g. `origin/main`.
+ * @returns The merge-base commit SHA.
+ * @throws GitError with an actionable message when the cwd is not a repo, the
+ * ref does not exist, or the histories share no common ancestor.
+ */
+declare function resolveBaseCommit(git: GitRunner, cwd: string, baseRef: string): Promise<string>;
+/**
+ * Read the contents of a file as it existed at `commit`, or `null` when the
+ * path did not exist at that commit (e.g. a manifest created since the base).
+ *
+ * @remarks
+ * Uses the `git show <commit>:./<path>` form: the `./` prefix makes git
+ * resolve the path relative to `cwd`, so no repository-root discovery is
+ * needed even when the project sits in a subdirectory of the repo. A UTF-8
+ * BOM is stripped, mirroring {@link readPackageJson}.
+ *
+ * @param git - The process runner.
+ * @param cwd - Directory to run git in.
+ * @param commit - The commit SHA (from {@link resolveBaseCommit}).
+ * @param relPath - Path relative to `cwd`; separators are normalized to `/`.
+ * @throws GitError for any failure other than "path absent at that commit".
+ */
+declare function readFileAtCommit(git: GitRunner, cwd: string, commit: string, relPath: string): Promise<string | null>;
+
+/**
+ * Workspace discovery for `--workspaces`: find every workspace package.json
+ * declared by the root manifest, so the CLI can scan and report them as one
+ * grouped run.
+ *
+ * Supports both workspace conventions:
+ * - `pnpm-workspace.yaml` `packages:` globs (takes precedence — pnpm itself
+ *   ignores the package.json field), parsed with the existing `yaml` dep;
+ * - root package.json `"workspaces"` (an array, or `{ packages: [...] }`).
+ *
+ * Glob expansion is hand-rolled on purpose (zero-dependency bias): literal
+ * paths, `*` as a full or partial segment, `**`, and leading-`!` exclusions
+ * cover what real-world workspace fields use.
+ *
+ * @packageDocumentation
+ */
+/**
+ * `--workspaces` was requested but no workspace configuration exists or it is
+ * malformed. Maps to exit code 2 (tool failure) in the CLI.
+ */
+declare class WorkspaceError extends Error {
+    constructor(message: string);
+}
+/** One discovered manifest location. */
+interface WorkspaceDir {
+    /** Absolute directory containing a package.json. */
+    readonly dir: string;
+    /**
+     * Manifest path relative to the root cwd, POSIX separators — e.g.
+     * `packages/a/package.json`. The root manifest is `package.json`.
+     */
+    readonly manifestRelPath: string;
+}
+/**
+ * Expand workspace glob patterns to absolute directories under `rootDir`,
+ * deduplicated and sorted by relative path. Leading-`!` patterns exclude
+ * directories matched by earlier inclusions (pnpm-workspace.yaml commonly
+ * carries e.g. `!**\/test/**`).
+ *
+ * @remarks Supported syntax: literal paths, `*` as a full or partial path
+ * segment, and `**` (any depth). `node_modules` and dot-directories are never
+ * traversed. Anything fancier (braces, extglobs) simply matches nothing —
+ * the CLI warns when a configuration yields zero workspaces.
+ */
+declare function expandWorkspacePatterns(rootDir: string, patterns: readonly string[]): Promise<readonly string[]>;
+/**
+ * Discover the manifests of a workspace root: the root package.json first,
+ * then every configured workspace directory that actually contains a
+ * package.json, sorted by relative path.
+ *
+ * @param rootDir - The workspace root (the CLI cwd).
+ * @param rootManifestParsed - The JSON-parsed root package.json (already
+ * loaded by the CLI), used for its `workspaces` field.
+ * @returns Zero workspace matches yield just the root entry — the CLI warns
+ * but proceeds.
+ * @throws WorkspaceError when neither `pnpm-workspace.yaml` `packages:` nor a
+ * package.json `workspaces` field exists, or either is malformed.
+ */
+declare function discoverWorkspaces(rootDir: string, rootManifestParsed: unknown): Promise<readonly WorkspaceDir[]>;
+
+export { type AllowEntry, DEFAULT_POLICY, DEFAULT_POLICY_FILENAME, type DependencyEntry, type EnrichedDependency, type EnrichmentOptions, type EnrichmentResult, type EnrichmentWarning, type EvaluateOptions, type Finding, type FindingSeverity, type FindingSummary, GitError, type GitRunResult, type GitRunner, type LastPublishThresholds, ManifestError, type NewArchTier, type Policy, PolicyError, type PolicyRules, type PolicyScope, type PrettyOptions, type ProjectManifest, type Report, type ReportFinding, type RnNativeReason, type RuleId, type RuleSeverity, type SarifOptions, type Signal, type UnknownReason, VERSION, type WorkspaceDir, WorkspaceError, computeExitCode, createGitRunner, diffDependencies, discoverWorkspaces, enrichDependencies, entriesFromManifestText, evaluatePolicy, expandWorkspacePatterns, findDependencyLine, listDependencies, listDependencyEntries, loadPolicy, locateFindings, parsePolicy, readFileAtCommit, readManifestAt, readPackageJson, renderAnnotations, renderJson, renderPretty, renderSarif, resolveBaseCommit, summarize };