@fantastic.dev/repo-gates 0.2.1-bootstrap.0

package/dist/index.d.ts

@@ -0,0 +1,796 @@
+import { Ctx, GateSpec, RepoGatesConfig } from './config.js';
+export { CONFIG_FILENAMES, DEFAULT_CONFIG, findConfigFile, loadConfig, loadContext, mergeConfig } from './config.js';
+export { Boundary, BoundaryEslintConfig, BoundaryPattern, boundariesToEslintConfigs } from './eslint-boundaries.js';
+
+/**
+ * Quiet, manifest-driven gate runner (the `check:all` engine).
+ *
+ * Resolves its gate manifest from the consumer's {@link RepoGatesConfig}
+ * filtered against the repo's package.json: required gates in the selected
+ * manifest are mandatory (a missing one fails the run); conditional gates run
+ * only when defined. A consumer may deliberately replace the default manifest
+ * — for example, with a coverage-backed test gate instead of a plain test run.
+ *
+ * Output contract ("quiet"):
+ *   - one aligned `<status> <gate> (N.Ns)` line per gate
+ *   - a one-line tally on success
+ *   - on failure: the failing gate names plus parsed failure signatures
+ *     from the captured output — never the full log
+ *   - opts.verbose streams every gate's full output instead
+ *   - opts.bail stops at the first failing gate
+ */
+
+/**
+ * Resolve the manifest: every required gate (whether or not the repo defines
+ * it — a missing required gate must fail loudly, not silently narrow the
+ * manifest) plus each conditional gate the repo's package.json defines.
+ */
+declare function resolveGates(scripts: Record<string, string>, gates: readonly GateSpec[]): string[];
+/** The resolved manifest for a repo — the single source of truth that the
+ *  CI-parity gate consumes. */
+declare function gatesForRepo(ctx: Ctx): string[];
+declare function formatGateLine(status: "ok" | "fail", gate: string, seconds: number, width: number): string;
+/**
+ * Pull the failure-relevant lines out of a gate's captured output: known
+ * failure signatures (tsc/eslint/vitest errors, prettier style
+ * complaints, budget-ratchet violations) when present, otherwise the tail
+ * of the output.
+ */
+declare function extractFailureSignatures(output: string): string[];
+/**
+ * Ratchet gates announce a one-line headline metric by printing a
+ * `SCORE: <text>` line; this pulls those out of a gate's captured output so
+ * the success summary can show them (binary gates emit nothing). Quiet mode
+ * only — verbose streams the gate output directly.
+ */
+declare function extractScores(output: string): string[];
+/** Render the success `Scores:` block from collected score strings of the
+ *  form `<label> — <value>`, aligned by label. Empty input → no block. */
+declare function formatScoresBlock(scores: string[]): string[];
+type GateResult = {
+    gate: string;
+    ok: boolean;
+    seconds: number;
+    output: string;
+};
+type CheckAllOptions = {
+    verbose?: boolean;
+    bail?: boolean;
+};
+/** Run every gate in the manifest. Returns the process exit code. */
+declare function runCheckAll(ctx: Ctx, opts?: CheckAllOptions): number;
+
+/**
+ * CI <-> `check:all` parity drift detector.
+ *
+ * Parses every gate workflow under `.github/workflows` (basename starting
+ * with `ciParity.workflowPrefix`) and fails when a gate-script invocation
+ * in a CI `run:` step is not transitively reachable from the gate
+ * manifest — i.e. when CI enforces something `check:all` does not exercise
+ * locally.
+ *
+ * Per-repo escape hatches live in `ciParity.configPath`:
+ *
+ *   { "aliases": { "check:coverage:ci": "check:coverage" },
+ *     "ciOnly": ["test:e2e"] }
+ *
+ *   - `aliases` maps a CI-side script name onto a gate-reachable
+ *     equivalent (same gate, different reporter/preamble).
+ *   - `ciOnly` allowlists scripts that are intentionally CI-only (heavy
+ *     e2e / setup / summaries with no local equivalent).
+ */
+
+type ParityConfig = {
+    aliases: Record<string, string>;
+    ciOnly: ReadonlySet<string>;
+};
+declare function loadParityConfig(configPath: string): ParityConfig;
+/** Build the matcher for the configured runner, e.g. runner "pnpm run"
+ *  matches `pnpm run <name>` and captures `<name>`. A bare invocation
+ *  without the runner keyword (e.g. `pnpm install`) is intentionally not
+ *  matched. */
+declare function makeRunTargetRe(runner: string): RegExp;
+declare function extractRunTargets(command: string, runner: string): string[];
+/**
+ * Everything reachable from the gate manifest: the manifest itself, the
+ * configured entry points (check:all / verify), and the transitive
+ * closure of runner references in script bodies.
+ */
+declare function computeReachable(scripts: Record<string, string>, gates: readonly string[], entryGates: readonly string[], runner: string): Set<string>;
+type CiInvocation = {
+    workflow: string;
+    job: string;
+    step: number;
+    script: string;
+};
+declare function extractCiInvocations(filePath: string, repoRoot: string, runner: string): CiInvocation[];
+/** Gate workflows only — release/deploy orchestration is intentionally
+ *  out-of-band from the per-PR gate. */
+declare function listCiWorkflows(dir: string, prefix: string): string[];
+type ParityFailure = CiInvocation & {
+    canonical: string;
+    reason: string;
+};
+declare function evaluateParity(invocations: CiInvocation[], reachable: ReadonlySet<string>, config: ParityConfig, rootGate: string): ParityFailure[];
+declare function checkParity(ctx: Ctx): {
+    invocations: CiInvocation[];
+    reachable: Set<string>;
+    failures: ParityFailure[];
+};
+/** Run the parity check. Returns the process exit code. */
+declare function runCiParity(ctx: Ctx): number;
+
+/**
+ * Per-file line-count guard (ratchet).
+ *
+ *   - Files NOT listed in the budgets file must be ≤ config.fileSize.threshold.
+ *   - Files listed in the budgets file must be ≤ their frozen budget (the
+ *     file's line count when it was grandfathered in). The ratchet only
+ *     goes DOWN: refactor and lower a budget, never raise it.
+ *
+ * `--init` writes the current over-threshold files as the grandfather
+ * baseline so a repo adopting the gate is green on day one.
+ */
+
+type BudgetsFile = {
+    _comment?: string;
+    budgets: Record<string, number>;
+};
+type SizeFailure = {
+    path: string;
+    lines: number;
+    budget: number;
+    reason: string;
+};
+declare function loadBudgets$2(budgetsPath: string): Record<string, number>;
+/** Every scanned source file with its repo-relative posix path + line count. */
+declare function collectFiles(ctx: Ctx): {
+    rel: string;
+    lines: number;
+}[];
+declare function scan$3(ctx: Ctx): {
+    failures: SizeFailure[];
+    staleBudgetEntries: string[];
+};
+/** Compute the grandfather baseline: every file currently over threshold,
+ *  frozen at its present line count. */
+declare function seedBudgets$1(ctx: Ctx): Record<string, number>;
+declare function writeSeed$3(ctx: Ctx): {
+    path: string;
+    count: number;
+};
+/** The scanned file with the least headroom to its budget/threshold — the
+ *  one closest to failing the ratchet. */
+declare function tightest(ctx: Ctx): {
+    path: string;
+    lines: number;
+    budget: number;
+    headroom: number;
+} | undefined;
+/** Run the guard. Returns the process exit code. */
+declare function runFileSizes(ctx: Ctx, init?: boolean): number;
+
+type fileSizes_BudgetsFile = BudgetsFile;
+type fileSizes_SizeFailure = SizeFailure;
+declare const fileSizes_collectFiles: typeof collectFiles;
+declare const fileSizes_runFileSizes: typeof runFileSizes;
+declare const fileSizes_tightest: typeof tightest;
+declare namespace fileSizes {
+  export { type fileSizes_BudgetsFile as BudgetsFile, type fileSizes_SizeFailure as SizeFailure, fileSizes_collectFiles as collectFiles, loadBudgets$2 as loadBudgets, fileSizes_runFileSizes as runFileSizes, scan$3 as scan, seedBudgets$1 as seedBudgets, fileSizes_tightest as tightest, writeSeed$3 as writeSeed };
+}
+
+/**
+ * Debt-marker scanner (ratchet).
+ *
+ * Flags any TODO / FIXME / HACK / XXX (config.debt.markerTokens) that is
+ * not paired with a tracker reference on the same line (a Linear-style
+ * `ABC-123`, a `#123` issue ref, or a URL — config.debt.trackerPatterns).
+ *
+ * Untracked markers must be removed, paired with a tracker id, or — as an
+ * escape hatch — grandfathered in the allowlist (`path:line` entries).
+ * The ratchet only goes down. `--init` seeds the allowlist with every
+ * current untracked marker so adoption is green on day one.
+ */
+
+type AllowlistFile$2 = {
+    _comment?: string;
+    allowlist: string[];
+};
+type Marker = {
+    path: string;
+    line: number;
+    marker: string;
+    text: string;
+};
+type AllowlistEntry$1 = {
+    path: string;
+    line: number;
+};
+declare function parseAllowlist$2(allowlistPath: string): {
+    entries: AllowlistEntry$1[];
+    raw: string[];
+};
+declare function scan$2(ctx: Ctx): {
+    untracked: Marker[];
+    staleAllowlistEntries: string[];
+};
+declare function seedAllowlist$2(ctx: Ctx): string[];
+declare function writeSeed$2(ctx: Ctx): {
+    path: string;
+    count: number;
+};
+/** Run the guard. Returns the process exit code. */
+declare function runDebtMarkers(ctx: Ctx, init?: boolean): number;
+
+type debtMarkers_Marker = Marker;
+declare const debtMarkers_runDebtMarkers: typeof runDebtMarkers;
+declare namespace debtMarkers {
+  export { type AllowlistFile$2 as AllowlistFile, type debtMarkers_Marker as Marker, parseAllowlist$2 as parseAllowlist, debtMarkers_runDebtMarkers as runDebtMarkers, scan$2 as scan, seedAllowlist$2 as seedAllowlist, writeSeed$2 as writeSeed };
+}
+
+/**
+ * Circular-import detector (ratchet).
+ *
+ * Walks `scanRoots` (same universe as the debt-marker/file-size guards),
+ * extracts each file's *relative* import/require specifiers, and resolves
+ * them to files on disk. A directed graph of that resolved edge set is
+ * reduced to its non-trivial strongly-connected components (Tarjan) — each
+ * one is a group of files that import each other in a cycle.
+ *
+ * Scope: only relative specifiers (`./x`, `../x`) are resolved, so this
+ * finds cycles *within* a scanned tree, not cross-package cycles reached
+ * through a bare workspace-package specifier (e.g. `@acme/a` importing back
+ * into `@acme/b` which imports `@acme/a`) — that needs package-graph
+ * resolution this tool doesn't have.
+ *
+ * Extraction is a regex over raw source text, not a syntax-aware parse — the
+ * same tradeoff `check-debt` makes for marker tokens. A specifier-shaped
+ * string inside a comment or a string literal (`const hint = 'from "./a"'`)
+ * can produce a false edge. A real parser would close this, at the cost of a
+ * TS/JS parser dependency this package otherwise has none of; not worth it
+ * for the rare false positive, which — like any regex-based gate — is fixed
+ * by allowlisting the resulting cycle.
+ *
+ * Like `check-debt`, new cycles fail the gate; existing ones are
+ * grandfathered into an allowlist (`path, path, …` signatures) that can
+ * only shrink. `--init` seeds it from the current tree.
+ */
+
+type AllowlistFile$1 = {
+    _comment?: string;
+    allowlist: string[];
+};
+type Cycle = {
+    files: string[];
+};
+/** Extract every relative import/require specifier from a source file:
+ *  `import … from "./x"`, `require("./x")`, `import("./x")`, and the
+ *  bare side-effect form `import "./x"` (no `from`). */
+declare function extractRelativeSpecifiers(source: string): string[];
+/** Resolve a relative specifier from `fromFile` to a real file on disk,
+ *  trying each source extension and an `/index.<ext>` fallback — mirrors
+ *  Node/TS module resolution closely enough for local relative imports. */
+declare function resolveSpecifier(fromFile: string, spec: string, sourceExtensions: readonly string[]): string | undefined;
+/** Tarjan's SCC algorithm, iterative to avoid recursion-depth limits on
+ *  large graphs. Returns every strongly-connected component of size > 1
+ *  (a genuine cycle — a lone node is never its own SCC here since the
+ *  graph has no self-loops from this extractor). */
+declare function findCycles(graph: ReadonlyMap<string, ReadonlySet<string>>): string[][];
+declare function buildGraph(ctx: Ctx): Map<string, Set<string>>;
+declare function parseAllowlist$1(allowlistPath: string): string[];
+declare function scan$1(ctx: Ctx): {
+    untracked: Cycle[];
+    staleAllowlistEntries: string[];
+};
+declare function seedAllowlist$1(ctx: Ctx): string[];
+declare function writeSeed$1(ctx: Ctx): {
+    path: string;
+    count: number;
+};
+/** Run the guard. Returns the process exit code. */
+declare function runCircularImports(ctx: Ctx, init?: boolean): number;
+
+type circularImports_Cycle = Cycle;
+declare const circularImports_buildGraph: typeof buildGraph;
+declare const circularImports_extractRelativeSpecifiers: typeof extractRelativeSpecifiers;
+declare const circularImports_findCycles: typeof findCycles;
+declare const circularImports_resolveSpecifier: typeof resolveSpecifier;
+declare const circularImports_runCircularImports: typeof runCircularImports;
+declare namespace circularImports {
+  export { type AllowlistFile$1 as AllowlistFile, type circularImports_Cycle as Cycle, circularImports_buildGraph as buildGraph, circularImports_extractRelativeSpecifiers as extractRelativeSpecifiers, circularImports_findCycles as findCycles, parseAllowlist$1 as parseAllowlist, circularImports_resolveSpecifier as resolveSpecifier, circularImports_runCircularImports as runCircularImports, scan$1 as scan, seedAllowlist$1 as seedAllowlist, writeSeed$1 as writeSeed };
+}
+
+/**
+ * Secret-shaped-string scanner (ratchet).
+ *
+ * A lightweight, dependency-free static scan for well-known credential
+ * shapes (AWS/GitHub/Slack/Stripe/npm/Google API keys, PEM private-key
+ * headers, userinfo-in-URL credentials — `config.secrets.patterns`) across
+ * every **git-tracked** file in the repo, not just `scanRoots` — a leaked
+ * secret is exactly as bad in a root `.env.example` or a YAML config as it
+ * is in `src/`.
+ *
+ * This is NOT a substitute for a dedicated secret-scanning tool (gitleaks,
+ * trufflehog): no entropy analysis, no git-history scan (only the current
+ * tracked tree), and only the shapes above. It exists to catch an
+ * accidental commit of a live token during normal review, not to be a
+ * complete secrets program.
+ *
+ * A finding is reported as a path:line plus a redacted fingerprint
+ * (`sha256` prefix) — the matched text itself is never printed. Like
+ * `check-debt`, untracked findings fail the gate; existing ones are
+ * grandfathered into an allowlist (`path:line` entries) that can only
+ * shrink. `--init` seeds it from the current tree — review that seed
+ * carefully, since it silences whatever it captures.
+ */
+
+type AllowlistFile = {
+    _comment?: string;
+    allowlist: string[];
+};
+type Finding = {
+    path: string;
+    line: number;
+    pattern: string;
+    fingerprint: string;
+};
+type AllowlistEntry = {
+    path: string;
+    line: number;
+};
+declare function parseAllowlist(allowlistPath: string): {
+    entries: AllowlistEntry[];
+    raw: string[];
+};
+/** Every git-tracked file, repo-relative, forward-slashed. Empty on any
+ *  git failure (e.g. not a git repo) rather than throwing — callers decide
+ *  whether that's fatal. */
+declare function listTrackedFiles(repoRoot: string): string[];
+declare function scan(ctx: Ctx): {
+    untracked: Finding[];
+    staleAllowlistEntries: string[];
+};
+declare function seedAllowlist(ctx: Ctx): string[];
+declare function writeSeed(ctx: Ctx): {
+    path: string;
+    count: number;
+};
+/** Run the guard. Returns the process exit code. */
+declare function runSecrets(ctx: Ctx, init?: boolean): number;
+
+type secrets_AllowlistFile = AllowlistFile;
+type secrets_Finding = Finding;
+declare const secrets_listTrackedFiles: typeof listTrackedFiles;
+declare const secrets_parseAllowlist: typeof parseAllowlist;
+declare const secrets_runSecrets: typeof runSecrets;
+declare const secrets_scan: typeof scan;
+declare const secrets_seedAllowlist: typeof seedAllowlist;
+declare const secrets_writeSeed: typeof writeSeed;
+declare namespace secrets {
+  export { type secrets_AllowlistFile as AllowlistFile, type secrets_Finding as Finding, secrets_listTrackedFiles as listTrackedFiles, secrets_parseAllowlist as parseAllowlist, secrets_runSecrets as runSecrets, secrets_scan as scan, secrets_seedAllowlist as seedAllowlist, secrets_writeSeed as writeSeed };
+}
+
+/**
+ * Coverage guard (ratchet) for a vitest monorepo — PER-PACKAGE floors.
+ *
+ * Runs the repo's `test:coverage` script (each package emits its own
+ * `coverage/coverage-summary.json` via vitest's json-summary reporter),
+ * then holds EACH package to its own floor. A single repo-wide aggregate
+ * is deliberately avoided: line-weighting lets big well-covered packages
+ * mask regressions in smaller ones, and one floor forces a false uniform
+ * standard on packages with very different achievable coverage.
+ *
+ * Floors live in config.coverage.budgetsPath as
+ *   { "default": {functions,lines}, "packages": { "<dir>": {functions,lines} } }
+ * where `<dir>` is the repo-relative package directory (e.g. "apps/web").
+ * A package with no explicit entry must meet `default`. Floors only
+ * ratchet UP. `--init` seeds every package's floor just below its current
+ * number (keeping the existing `default`, or 80/80 on first seed).
+ */
+
+type Floor = {
+    functions: number;
+    lines: number;
+};
+type Budgets$1 = {
+    default: Floor;
+    packages: Record<string, Floor>;
+};
+type Counts = {
+    covered: number;
+    total: number;
+};
+type PkgCoverage = {
+    pkg: string;
+    totals: Floor;
+};
+type PkgFailure = {
+    pkg: string;
+    metric: "functions" | "lines";
+    actual: number;
+    floor: number;
+    isNew: boolean;
+};
+declare const DEFAULT_MIN: Floor;
+declare function loadBudgets$1(raw: string, source?: string): Budgets$1;
+/** Expand a repo-relative glob whose only wildcard is `*` matching a
+ *  single path segment (e.g. `packages/*​/coverage/coverage-summary.json`). */
+declare function expandGlob(repoRoot: string, glob: string): string[];
+declare function readSummaryCounts(path: string): {
+    functions: Counts;
+    lines: Counts;
+} | undefined;
+declare function pct(counts: Counts): number;
+/** The package directory a coverage summary belongs to, e.g.
+ *  `apps/web/coverage/coverage-summary.json` → `apps/web`. */
+declare function pkgKey(repoRoot: string, summaryPath: string): string;
+/** Per-package coverage percentages, one row per matched summary. */
+declare function collectPerPackage(ctx: Ctx): PkgCoverage[];
+declare function checkPerPackage(perPkg: PkgCoverage[], budgets: Budgets$1): {
+    failures: PkgFailure[];
+    newPkgs: string[];
+    stale: string[];
+};
+/** A floor 0.5pt below the measured value, to absorb run-to-run noise. */
+declare function seedFloor(pct_: number): number;
+declare function seedBudgets(perPkg: PkgCoverage[], keepDefault: Floor): Budgets$1;
+declare function lowest(perPkg: PkgCoverage[]): {
+    pkg: string;
+    lines: number;
+} | undefined;
+/** The `check:all` headline for coverage: the lowest package + how many meet
+ *  their floor. `undefined` when there are no packages. */
+declare function coverageScore(perPkg: PkgCoverage[]): string | undefined;
+/** Run the coverage guard. Returns the process exit code. `init` seeds the
+ *  floors; `skipRun` reads already-produced summaries without re-running. */
+declare function runCoverage(ctx: Ctx, opts?: {
+    init?: boolean;
+    skipRun?: boolean;
+}): number;
+
+type coverage_Counts = Counts;
+declare const coverage_DEFAULT_MIN: typeof DEFAULT_MIN;
+type coverage_Floor = Floor;
+type coverage_PkgCoverage = PkgCoverage;
+type coverage_PkgFailure = PkgFailure;
+declare const coverage_checkPerPackage: typeof checkPerPackage;
+declare const coverage_collectPerPackage: typeof collectPerPackage;
+declare const coverage_coverageScore: typeof coverageScore;
+declare const coverage_expandGlob: typeof expandGlob;
+declare const coverage_lowest: typeof lowest;
+declare const coverage_pct: typeof pct;
+declare const coverage_pkgKey: typeof pkgKey;
+declare const coverage_readSummaryCounts: typeof readSummaryCounts;
+declare const coverage_runCoverage: typeof runCoverage;
+declare const coverage_seedBudgets: typeof seedBudgets;
+declare const coverage_seedFloor: typeof seedFloor;
+declare namespace coverage {
+  export { type Budgets$1 as Budgets, type coverage_Counts as Counts, coverage_DEFAULT_MIN as DEFAULT_MIN, type coverage_Floor as Floor, type coverage_PkgCoverage as PkgCoverage, type coverage_PkgFailure as PkgFailure, coverage_checkPerPackage as checkPerPackage, coverage_collectPerPackage as collectPerPackage, coverage_coverageScore as coverageScore, coverage_expandGlob as expandGlob, loadBudgets$1 as loadBudgets, coverage_lowest as lowest, coverage_pct as pct, coverage_pkgKey as pkgKey, coverage_readSummaryCounts as readSummaryCounts, coverage_runCoverage as runCoverage, coverage_seedBudgets as seedBudgets, coverage_seedFloor as seedFloor };
+}
+
+/**
+ * Bundle-size guard (ratchet).
+ *
+ * For each configured target it builds the target (turbo, cached), scans
+ * its dist dir, and enforces a ratchet per bucket (js/css/…):
+ *   - totals.raw / totals.gzip — total bytes per bucket
+ *   - largest.gzip            — the single largest chunk per bucket
+ *     (catches one chunk ballooning even when the total stays flat).
+ *
+ * The ratchet only goes DOWN: code-split / trim deps, then lower the
+ * budget. `--init` re-baselines from a fresh build (measured + headroom).
+ *
+ * Each target's dist dir is REMOVED before the build. A build tool empties
+ * its own output dir, but a cache hit skips the tool entirely and restores
+ * cached outputs *into* whatever is already there — restore is additive,
+ * because the cache cannot know which foreign files are safe to delete. Two
+ * builds' hash-suffixed chunks then coexist and every one of them is counted.
+ * Cleaning first makes restore exact and keeps the cache: the measurement
+ * becomes a function of the build rather than of the directory's history.
+ * Especially valuable for the Cloudflare worker target, where the bundle
+ * has a HARD size limit — this fails the PR instead of the prod deploy.
+ */
+
+type BucketDef = Record<string, string[]>;
+type BucketSize = {
+    raw: number;
+    gzip: number;
+    largest: number;
+};
+type Measurement = {
+    buckets: Record<string, BucketSize>;
+    /** `dir` is the slash-separated path from distDir to the file's directory
+     *  (`""` at the top level). `name` stays the bare basename so existing
+     *  consumers are unaffected. */
+    files: {
+        name: string;
+        dir: string;
+        bucket: string;
+        raw: number;
+        gzip: number;
+    }[];
+};
+type TargetBudget = {
+    totals: {
+        raw: Record<string, number>;
+        gzip: Record<string, number>;
+    };
+    largest: {
+        gzip: Record<string, number>;
+    };
+};
+type Budgets = Record<string, TargetBudget>;
+type Failure$1 = {
+    target: string;
+    metric: string;
+    bucket: string;
+    actual: number;
+    budget: number;
+};
+declare function measure(distDir: string, buckets: BucketDef): Measurement;
+/** A dist dir must sit strictly inside the repo. `cleanDist` deletes
+ *  recursively, so a config typo — or a symlink on the path — that resolved to
+ *  the repo root or above would take the working tree with it.
+ *
+ *  Returns the symlink-resolved path, which is the one that was actually
+ *  checked; deleting anything else would defeat the point of checking. */
+declare function assertSafeDistDir(distDir: string, repoRoot: string): string;
+/** Remove a target's dist dir so the build writes into an empty directory.
+ *  Missing is fine — that is the state we are trying to reach. */
+declare function cleanDist(distDir: string, repoRoot: string): void;
+/** Strip a content hash so two builds of the same chunk share a name:
+ *  `ProjectArea-DWbILnNi.js` and `ProjectArea-LeWXd_sH.js` both become
+ *  `ProjectArea.js`, while `react-markdown.js` and `use-debounce.js` are
+ *  left exactly as they are. */
+declare function logicalChunkName(name: string): string;
+type DuplicateChunk = {
+    bucket: string;
+    /** Directory-qualified, so `dist/esm/index.js` and `dist/cjs/index.js` — the
+     *  normal shape of a dual-format library build — are not mistaken for one
+     *  chunk emitted twice.
+     *
+     *  This is a deliberate trade, and it costs real detection. Pollution whose
+     *  two copies land in DIFFERENT directories now escapes: a build id in the
+     *  output path (`.next/static/<buildId>/`), a renamed assets dir, a hashed
+     *  directory name, or one copy at the top level and one under `assets/`.
+     *  Basename grouping caught those and this does not.
+     *
+     *  There is no local signal separating the two cases — `esm/x-AAAA.js` +
+     *  `cjs/x-BBBB.js` and `build1/x-AAAA.js` + `build2/x-BBBB.js` are the same
+     *  shape. The trade goes this way because the failure modes are not
+     *  symmetric: a false positive REFUSES a clean dist and tells the operator to
+     *  remove it and re-run, which reproduces the refusal forever, while a false
+     *  negative loses one backstop. `cleanDist` is the actual defence against
+     *  layered output; this only catches a dist someone else laid out. */
+    logical: string;
+    files: {
+        name: string;
+        raw: number;
+    }[];
+};
+declare function findDuplicateChunks(m: Measurement): DuplicateChunk[];
+declare function loadBudgets(raw: string, source?: string): Budgets;
+declare function diff(target: string, m: Measurement, budget: TargetBudget): Failure$1[];
+declare function seedBudget(m: Measurement): TargetBudget;
+declare function fmtBytes(n: number): string;
+/** Seams for the two effects the guard performs before it can measure.
+ *  Exposed so tests can assert the ORDER: cleaning after the build would
+ *  delete the outputs, and cleaning is only useful before one. */
+type BundleSizeDeps = {
+    clean: (distDir: string, repoRoot: string) => void;
+    build: (ctx: Ctx) => number;
+};
+/** Run the bundle-size guard. Returns the process exit code. */
+declare function runBundleSize(ctx: Ctx, init?: boolean, deps?: BundleSizeDeps): number;
+
+type bundleSize_BucketSize = BucketSize;
+type bundleSize_Budgets = Budgets;
+type bundleSize_BundleSizeDeps = BundleSizeDeps;
+type bundleSize_DuplicateChunk = DuplicateChunk;
+type bundleSize_Measurement = Measurement;
+type bundleSize_TargetBudget = TargetBudget;
+declare const bundleSize_assertSafeDistDir: typeof assertSafeDistDir;
+declare const bundleSize_cleanDist: typeof cleanDist;
+declare const bundleSize_diff: typeof diff;
+declare const bundleSize_findDuplicateChunks: typeof findDuplicateChunks;
+declare const bundleSize_fmtBytes: typeof fmtBytes;
+declare const bundleSize_loadBudgets: typeof loadBudgets;
+declare const bundleSize_logicalChunkName: typeof logicalChunkName;
+declare const bundleSize_measure: typeof measure;
+declare const bundleSize_runBundleSize: typeof runBundleSize;
+declare const bundleSize_seedBudget: typeof seedBudget;
+declare namespace bundleSize {
+  export { type bundleSize_BucketSize as BucketSize, type bundleSize_Budgets as Budgets, type bundleSize_BundleSizeDeps as BundleSizeDeps, type bundleSize_DuplicateChunk as DuplicateChunk, type Failure$1 as Failure, type bundleSize_Measurement as Measurement, type bundleSize_TargetBudget as TargetBudget, bundleSize_assertSafeDistDir as assertSafeDistDir, bundleSize_cleanDist as cleanDist, bundleSize_diff as diff, bundleSize_findDuplicateChunks as findDuplicateChunks, bundleSize_fmtBytes as fmtBytes, bundleSize_loadBudgets as loadBudgets, bundleSize_logicalChunkName as logicalChunkName, bundleSize_measure as measure, bundleSize_runBundleSize as runBundleSize, bundleSize_seedBudget as seedBudget };
+}
+
+/**
+ * Agent-doc validator (check:agents).
+ *
+ * Fails when an agent doc (AGENTS.md / CLAUDE.md) drifts out of sync with the
+ * repo: any package-manager script it references in a fenced bash block must
+ * exist in package.json's scripts, and any backticked path-shaped token must
+ * resolve on disk (or be listed in `agents.knownMissingPaths`).
+ */
+
+type Failure = {
+    file: string;
+    kind: string;
+    detail: string;
+};
+declare function extractFencedBashBlocks(markdown: string): string[];
+/** Script names referenced via the package manager in bash blocks. Handles
+ *  both `<pm> run <name>` (explicit) and bare `<pm> <name>` (skipping the
+ *  configured builtin subcommands like install/exec). */
+declare function extractScriptRefs(blocks: string[], runnerCommand: string, ignoredSubcommands: readonly string[]): Set<string>;
+/** Backtick-quoted tokens that look like a repo path (contain `/` or a known
+ *  doc/config extension). URLs, scoped packages, globs, placeholders skipped. */
+declare function extractBacktickedPaths(markdown: string): string[];
+declare function validateAgents(ctx: Ctx): Failure[];
+/** Run the agent-doc validator. Returns the process exit code. */
+declare function runValidateAgents(ctx: Ctx): number;
+
+type validateAgents$1_Failure = Failure;
+declare const validateAgents$1_extractBacktickedPaths: typeof extractBacktickedPaths;
+declare const validateAgents$1_extractFencedBashBlocks: typeof extractFencedBashBlocks;
+declare const validateAgents$1_extractScriptRefs: typeof extractScriptRefs;
+declare const validateAgents$1_runValidateAgents: typeof runValidateAgents;
+declare const validateAgents$1_validateAgents: typeof validateAgents;
+declare namespace validateAgents$1 {
+  export { type validateAgents$1_Failure as Failure, validateAgents$1_extractBacktickedPaths as extractBacktickedPaths, validateAgents$1_extractFencedBashBlocks as extractFencedBashBlocks, validateAgents$1_extractScriptRefs as extractScriptRefs, validateAgents$1_runValidateAgents as runValidateAgents, validateAgents$1_validateAgents as validateAgents };
+}
+
+/**
+ * Docs-coverage gate: block a PR that changes a user-facing surface but
+ * adds no docs for it.
+ *
+ * WHAT COUNTS AS A SURFACE is `config.docsCoverage` (empty `surfaces` ⇒
+ * no-op). A PR passes when either: no surface changed (nothing to gate); a
+ * surface changed AND docs changed too; or the author opted out with an
+ * escape hatch line `docs: n/a - <reason>` in the PR body. Otherwise it
+ * fails closed.
+ *
+ * This is inherently a *pull-request* gate (a PR body, a base/head diff) —
+ * it reads the changed-file list from the GitHub REST API using
+ * `GITHUB_REPOSITORY` / `PR_NUMBER` / `GITHUB_TOKEN` / `PR_BODY`. Unlike
+ * every other gate here, it deliberately does NOT hard-fail when those are
+ * absent: a repo may wire `check:docs-coverage` into the local `check:all`
+ * manifest (so it's part of the same battery as everything else), and a
+ * local run or a plain `push` CI job has no PR to evaluate — that's a soft
+ * no-op, not a failure. It only enforces when actually invoked with PR
+ * context, e.g. a `pull_request`-triggered CI job (see the
+ * `monorepo-turborepo.yml` example's comment on wiring this up).
+ *
+ * Zero npm dependencies: Node built-ins + global fetch.
+ */
+
+type DocsCoverageConfig = RepoGatesConfig["docsCoverage"];
+/** Convert a glob to an anchored RegExp. `*` matches within a path segment;
+ *  `**` matches across segments (and `**​/` also matches zero directories). */
+declare function globToRegExp(glob: string): RegExp;
+declare function matchesAny(path: string, globs: readonly string[] | undefined): boolean;
+type ChangedFile = {
+    filename: string;
+    status: string;
+};
+/** Does a file (with its GitHub status) trigger the given surface rule? */
+declare function fileTriggersSurface(file: ChangedFile, surface: DocsCoverageConfig["surfaces"][number]): boolean;
+type TriggeredSurface = {
+    file: string;
+    label: string;
+};
+/** Surfaces a PR touched that need docs. */
+declare function triggeredSurfaces(files: readonly ChangedFile[], config: DocsCoverageConfig): TriggeredSurface[];
+/** Did the PR add or update any docs (present, not excluded, under docsGlobs)? */
+declare function hasDocsChange(files: readonly ChangedFile[], config: DocsCoverageConfig): boolean;
+/** Remove fenced code so an escape-hatch example in a code block is not
+ *  read as a real opt-out. */
+declare function stripFencedCode(markdown: string | undefined): string;
+type EscapeHatch = {
+    present: false;
+} | {
+    present: true;
+    reason: string;
+};
+/** The `docs: n/a - <reason>` opt-out, if present. Tolerates `n/a` or `na`,
+ *  an optional leading list/quote marker, and any dash/colon before the
+ *  reason. */
+declare function escapeHatch(body: string | undefined): EscapeHatch;
+type Verdict = {
+    status: "skip";
+} | {
+    status: "pass";
+    triggered: TriggeredSurface[];
+} | {
+    status: "waived";
+    triggered: TriggeredSurface[];
+    reason: string;
+} | {
+    status: "fail";
+    triggered: TriggeredSurface[];
+};
+/** The gate verdict.
+ *    skip    — no surface changed; nothing to gate.
+ *    pass    — a surface changed and docs changed too.
+ *    waived  — a surface changed, no docs, but an escape hatch opted out.
+ *    fail    — a surface changed, no docs, no escape hatch. */
+declare function evaluate(files: readonly ChangedFile[], body: string | undefined, config: DocsCoverageConfig): Verdict;
+/** Percent-encode the characters a GitHub Actions workflow command treats
+ *  specially (`%`, `\r`, `\n`) so a multi-line message isn't mangled or
+ *  truncated. See https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands */
+declare function escapeWorkflowCommand(message: string): string;
+declare function fetchChangedFiles(opts: {
+    repo: string;
+    number: string;
+    token: string;
+}): Promise<ChangedFile[]>;
+/** Run the gate. Returns the process exit code. */
+declare function runDocsCoverage(ctx: Ctx): Promise<number>;
+declare function readDocsCoverageConfig(path: string): DocsCoverageConfig;
+
+type docsCoverage_ChangedFile = ChangedFile;
+type docsCoverage_DocsCoverageConfig = DocsCoverageConfig;
+type docsCoverage_EscapeHatch = EscapeHatch;
+type docsCoverage_TriggeredSurface = TriggeredSurface;
+type docsCoverage_Verdict = Verdict;
+declare const docsCoverage_escapeHatch: typeof escapeHatch;
+declare const docsCoverage_escapeWorkflowCommand: typeof escapeWorkflowCommand;
+declare const docsCoverage_evaluate: typeof evaluate;
+declare const docsCoverage_fetchChangedFiles: typeof fetchChangedFiles;
+declare const docsCoverage_fileTriggersSurface: typeof fileTriggersSurface;
+declare const docsCoverage_globToRegExp: typeof globToRegExp;
+declare const docsCoverage_hasDocsChange: typeof hasDocsChange;
+declare const docsCoverage_matchesAny: typeof matchesAny;
+declare const docsCoverage_readDocsCoverageConfig: typeof readDocsCoverageConfig;
+declare const docsCoverage_runDocsCoverage: typeof runDocsCoverage;
+declare const docsCoverage_stripFencedCode: typeof stripFencedCode;
+declare const docsCoverage_triggeredSurfaces: typeof triggeredSurfaces;
+declare namespace docsCoverage {
+  export { type docsCoverage_ChangedFile as ChangedFile, type docsCoverage_DocsCoverageConfig as DocsCoverageConfig, type docsCoverage_EscapeHatch as EscapeHatch, type docsCoverage_TriggeredSurface as TriggeredSurface, type docsCoverage_Verdict as Verdict, docsCoverage_escapeHatch as escapeHatch, docsCoverage_escapeWorkflowCommand as escapeWorkflowCommand, docsCoverage_evaluate as evaluate, docsCoverage_fetchChangedFiles as fetchChangedFiles, docsCoverage_fileTriggersSurface as fileTriggersSurface, docsCoverage_globToRegExp as globToRegExp, docsCoverage_hasDocsChange as hasDocsChange, docsCoverage_matchesAny as matchesAny, docsCoverage_readDocsCoverageConfig as readDocsCoverageConfig, docsCoverage_runDocsCoverage as runDocsCoverage, docsCoverage_stripFencedCode as stripFencedCode, docsCoverage_triggeredSurfaces as triggeredSurfaces };
+}
+
+/**
+ * Non-gating CI dashboards (report:test-timing, report:quality-metrics).
+ *
+ * These enforce nothing — each ratchet gate already fails the build on its
+ * own. They render the current state into `$GITHUB_STEP_SUMMARY` (and stdout)
+ * so reviewers see it at a glance. Missing inputs degrade to a "—" row rather
+ * than failing.
+ */
+
+type TestCase = {
+    name: string;
+    classname: string;
+    file: string;
+    timeSeconds: number;
+};
+type TimingReport = {
+    totalSeconds: number;
+    totalTests: number;
+    cases: TestCase[];
+};
+declare function parseJUnit(xml: string): TestCase[];
+declare function collectTiming(ctx: Ctx): {
+    report: TimingReport;
+    files: number;
+};
+declare function formatTiming(report: TimingReport, topN: number): string;
+/** A consolidated table of the ratchet gates' current headline metrics. */
+declare function formatQualityMetrics(ctx: Ctx): string;
+declare function emitSummary(markdown: string): void;
+declare function runTestTiming(ctx: Ctx): number;
+declare function runQualityMetrics(ctx: Ctx): number;
+
+type report_TestCase = TestCase;
+type report_TimingReport = TimingReport;
+declare const report_collectTiming: typeof collectTiming;
+declare const report_emitSummary: typeof emitSummary;
+declare const report_formatQualityMetrics: typeof formatQualityMetrics;
+declare const report_formatTiming: typeof formatTiming;
+declare const report_parseJUnit: typeof parseJUnit;
+declare const report_runQualityMetrics: typeof runQualityMetrics;
+declare const report_runTestTiming: typeof runTestTiming;
+declare namespace report {
+  export { type report_TestCase as TestCase, type report_TimingReport as TimingReport, report_collectTiming as collectTiming, report_emitSummary as emitSummary, report_formatQualityMetrics as formatQualityMetrics, report_formatTiming as formatTiming, report_parseJUnit as parseJUnit, report_runQualityMetrics as runQualityMetrics, report_runTestTiming as runTestTiming };
+}
+
+export { type CheckAllOptions, type CiInvocation, Ctx, type GateResult, GateSpec, type ParityConfig, type ParityFailure, RepoGatesConfig, bundleSize, checkParity, circularImports, computeReachable, coverage, debtMarkers, docsCoverage, evaluateParity, extractCiInvocations, extractFailureSignatures, extractRunTargets, extractScores, fileSizes, formatGateLine, formatScoresBlock, gatesForRepo, listCiWorkflows, loadParityConfig, makeRunTargetRe, report, resolveGates, runCheckAll, runCiParity, secrets, validateAgents$1 as validateAgents };