@pyreon/cli 0.16.0 → 0.18.0

package/lib/types/index.d.ts

@@ -1,4 +1,4 @@
-import { AuditRisk, ProjectContext, ProjectContext as ProjectContext$1 } from "@pyreon/compiler";
+import { ProjectContext, ProjectContext as ProjectContext$1 } from "@pyreon/compiler";
 
 //#region src/context.d.ts
 interface ContextOptions {
@@ -7,48 +7,199 @@ interface ContextOptions {
 }
 declare function generateContext(options: ContextOptions): Promise<ProjectContext$1>;
 //#endregion
+//#region src/doctor/types.d.ts
+/**
+ * Unified `Finding` + `GateResult` types shared by every doctor gate.
+ *
+ * Each programmatic gate (`runDistributionGate`, `runDocClaimsGate`, ...)
+ * returns `GateResult`. The aggregator in `pyreon doctor` merges every
+ * gate's findings into a `DoctorReport` with per-category subscores + an
+ * overall 0-100 health score — that aggregation layer lands in the
+ * follow-up PR (this PR is foundation-only).
+ *
+ * Why a unified shape now (PR 1) instead of together with the aggregator
+ * (PR 2): the gates are independently usable today via standalone scripts
+ * (`bun run check-distribution`, etc.). Locking the shape early means the
+ * scripts and the future aggregator consume the same `Finding[]` — no
+ * shim layer.
+ *
+ * Mirrors the existing per-detector shapes (`IslandFinding`, `SsgFinding`,
+ * `TestAuditEntry`) but elevated to a cross-gate vocabulary. Categories
+ * map onto the five react.doctor-style buckets so the score formula has
+ * a clear assignment per gate without case-by-case classification.
+ */
+type FindingCategory = 'correctness' | 'performance' | 'architecture' | 'testing' | 'documentation';
+type Severity = 'error' | 'warning' | 'info';
+/**
+ * A single actionable diagnostic. Every doctor gate emits Findings in
+ * this shape. Aggregation by category + severity drives the health score.
+ */
+interface Finding {
+  /**
+   * Bucket the finding lands in for score aggregation. Each gate picks
+   * a default category for its emitted findings; an individual finding
+   * may override (e.g. a perf-flavored lint rule would still emit
+   * `category: 'performance'` even though the gate is `'lint'`).
+   */
+  category: FindingCategory;
+  /** Severity drives per-finding weight in the score formula. */
+  severity: Severity;
+  /**
+   * Stable code identifying the specific check. Format: `<gate>/<rule>`
+   * — e.g. `'audit-types/typed-but-unimplemented'`,
+   * `'distribution/missing-sideEffects'`, `'pyreon/for-missing-by'`.
+   * Used for filtering + cross-referencing in JSON output.
+   */
+  code: string;
+  /**
+   * Identifier of the gate that produced this finding. Useful for
+   * grouping in human output and `--skip <gate>` filtering. Examples:
+   * `'lint'`, `'audit-types'`, `'check-distribution'`, `'islands-audit'`.
+   */
+  gate: string;
+  /** One-paragraph human-readable explanation, including the fix path. */
+  message: string;
+  /** Where the finding surfaces. Optional for project-wide findings. */
+  location?: {
+    /** Absolute path */path: string; /** Path relative to the repo root for readable reporting */
+    relPath: string; /** 1-based line number */
+    line?: number | undefined; /** 1-based column number */
+    column?: number | undefined;
+  } | undefined;
+  /**
+   * Companion locations for cross-file findings (e.g. duplicate-island-
+   * name lists the second occurrence). Surfaces in human output below
+   * the primary location with an `↳` marker.
+   */
+  relatedLocations?: Array<{
+    path: string;
+    relPath: string;
+    line?: number | undefined;
+    column?: number | undefined;
+    label?: string | undefined;
+  }> | undefined;
+  /** Optional short fix hint shown under the message in human output. */
+  fix?: string | undefined;
+  /**
+   * `true` if `pyreon doctor --fix` can auto-resolve this. Currently
+   * limited to lint findings whose rule has an auto-fixer.
+   */
+  fixable?: boolean | undefined;
+}
+/**
+ * Result of running a single doctor gate. The aggregator collects N
+ * GateResults and computes the report.
+ */
+interface GateResult {
+  /** Gate identifier (matches Finding.gate) */
+  gate: string;
+  /**
+   * Default category for findings this gate produces. The aggregator
+   * uses this as the fallback when a Finding doesn't override
+   * `category` itself — but Finding.category is the source of truth
+   * for score attribution.
+   */
+  category: FindingCategory;
+  /** All findings produced by this gate. May be empty. */
+  findings: Finding[];
+  /** Per-gate metadata for the human + JSON reports. */
+  meta: {
+    /** Number of files / packages / records the gate scanned. */scanned?: number | undefined; /** Wall-clock duration in milliseconds. */
+    elapsedMs: number;
+    /**
+     * `true` if the gate was skipped (e.g. `--skip <gate>`, missing
+     * prerequisite tool, mode-incompatible). The aggregator excludes
+     * skipped gates from the score and surfaces them in a "skipped"
+     * footer.
+     */
+    skipped?: boolean | undefined;
+    /**
+     * Why the gate was skipped (only meaningful when `skipped: true`).
+     */
+    skipReason?: string | undefined;
+  };
+}
+/**
+ * Per-category subscore + raw counts. The aggregator builds one
+ * `CategoryScore` per `FindingCategory`, then averages them into the
+ * overall score. Categories with no findings AND no contributing gates
+ * (skipped or filtered out) get `included: false` and are excluded
+ * from the mean — keeping a perfect 100 for an unmeasured category
+ * would be misleading.
+ */
+interface CategoryScore {
+  category: FindingCategory;
+  /** 0-100 subscore for this bucket */
+  score: number;
+  errors: number;
+  warnings: number;
+  infos: number;
+  /** Letter grade derived from `score` (A/B/C/D/F) */
+  grade: Grade;
+  /** False if no gate covered this category — drop from mean */
+  included: boolean;
+}
+type Grade = 'A' | 'B' | 'C' | 'D' | 'F';
+/**
+ * Final aggregated report `pyreon doctor` produces. The renderer
+ * (text / json / gha) consumes this; gate orchestration is upstream.
+ */
+interface DoctorReport {
+  /** 0-100 weighted mean of included `categories[].score` */
+  score: number;
+  /** Letter grade for `score` */
+  grade: Grade;
+  /** Per-category breakdown (always 5 entries — `included` flags coverage) */
+  categories: CategoryScore[];
+  /** Every gate that ran (or was skipped, with `meta.skipped: true`) */
+  gates: GateResult[];
+  /** Flat list of all findings across gates, ordered by severity then category */
+  findings: Finding[];
+  /** Aggregate counts across all findings */
+  totals: {
+    errors: number;
+    warnings: number;
+    infos: number;
+  };
+  /** Top-level wall-clock — sum of gates' elapsedMs (parallel sum, not max) */
+  elapsedMs: number;
+  /** ISO timestamp of when the report was produced (for diffing across runs) */
+  timestamp: string;
+}
+//#endregion
+//#region src/doctor/orchestrator.d.ts
+type GateName = 'react-patterns' | 'pyreon-patterns' | 'lint' | 'distribution' | 'doc-claims' | 'audit-tests' | 'islands-audit' | 'ssg-audit' | 'audit-types' | 'bundle-budgets';
+//#endregion
 //#region src/doctor.d.ts
+type DoctorFormat = 'text' | 'json' | 'gha';
 interface DoctorOptions {
   fix: boolean;
+  /** Legacy boolean — interpreted as `format = 'json'` if true. */
   json: boolean;
   ci: boolean;
   cwd: string;
+  /** Explicit format override (wins over `json` boolean). */
+  format?: DoctorFormat | undefined;
+  /** Enable slow gates (audit-types, bundle-budgets). */
+  full?: boolean | undefined;
+  /** Run ONLY these gates. */
+  only?: GateName[] | undefined;
+  /** Skip these gates. */
+  skip?: GateName[] | undefined;
   /**
-   * When true, run the test-environment audit (mock-vnode pattern
-   * detection) and append the result to the doctor output. Default
-   * false — the audit is scoped to test files only and isn't part of
-   * the React-migration check pipeline, so we gate it to avoid noise
-   * in the typical "is my migration done?" call.
+   * @deprecated Prefer `--only audit-tests`. Both forms behave
+   * identically: include the test-environment audit gate in the
+   * report. Kept so existing CI scripts continue to work.
    */
   auditTests?: boolean | undefined;
-  /** Minimum risk level to include in the test-audit report. Default 'medium'. */
-  auditMinRisk?: AuditRisk | undefined;
-  /**
-   * When true, run the project-wide islands audit and append the result
-   * to the doctor output. Catches cross-file foot-guns (duplicate names,
-   * dead islands, registry drift, nested islands, never-with-registry)
-   * that PR G's per-file detector and PR B's auto-registry can't reach
-   * (manual `hydrateIslands({...})` for non-Vite consumers, library
-   * authors, multi-package projects). Default false.
-   */
+  /** Minimum risk for the test-environment audit. Default 'medium'. */
+  auditMinRisk?: 'high' | 'medium' | 'low' | undefined;
+  /** @deprecated Prefer `--only islands-audit`. */
   checkIslands?: boolean | undefined;
-  /**
-   * When true, run the project-wide SSG / ISR audit (M3.4) and append
-   * the result to the doctor output. Catches:
-   *  - `_404.tsx` not co-located with `_layout.tsx` (PR L5 carve-out)
-   *  - dynamic routes (`[id].tsx`) without `getStaticPaths` (PR A
-   *    silently skips them under `mode: 'ssg'`)
-   *  - `export const revalidate = X` where X isn't a numeric literal
-   *    (PR I's extractor silently drops non-literal forms)
-   *
-   * Like the islands audit, this is a "should review" signal — the exit
-   * code is unaffected (the build doesn't break) but CI can pipe
-   * `--check-ssg --json` and grep for findings.length > 0 to gate on
-   * it. Default false.
-   */
+  /** @deprecated Prefer `--only ssg-audit`. */
   checkSsg?: boolean | undefined;
 }
-declare function doctor(options: DoctorOptions): Promise<number>;
+declare const doctor: (options: DoctorOptions) => Promise<number>;
 //#endregion
-export { type ContextOptions, type DoctorOptions, type ProjectContext, doctor, generateContext };
+export { type ContextOptions, type DoctorOptions, type DoctorReport, type GateName, type ProjectContext, doctor, generateContext };
 //# sourceMappingURL=index2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/cli",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "CLI tools for Pyreon — doctor, generate, context",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/cli#readme",
   "bugs": {
@@ -46,7 +46,8 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/compiler": "^0.16.0"
+    "@pyreon/compiler": "^0.18.0",
+    "@pyreon/lint": "^0.18.0"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"

package/src/doctor/gates/audit-tests.ts

@@ -0,0 +1,70 @@
+/**
+ * audit-tests gate — wraps `@pyreon/compiler:auditTestEnvironment`.
+ *
+ * Catches mock-vnode test patterns (the PR #197 bug class — tests
+ * that hand-construct `{ type, props, children }` literals or use a
+ * `vnode()` helper instead of going through real `h()` from
+ * `@pyreon/core`). Three risk tiers (HIGH / MEDIUM / LOW) from the
+ * balance of mockVNodeLiteralCount + mockHelperCount +
+ * mockHelperCallCount + realHCallCount + importsH. The adapter
+ * maps tier → severity (high=error, medium=warning, low=info).
+ */
+
+import { auditTestEnvironment } from '@pyreon/compiler'
+import type { AuditRisk } from '@pyreon/compiler'
+
+import type { Finding, GateResult, Severity } from '../types'
+
+const SEVERITY_BY_RISK: Record<AuditRisk, Severity> = {
+  high: 'error',
+  medium: 'warning',
+  low: 'info',
+}
+
+export interface AuditTestsGateOptions {
+  cwd: string
+  /** Minimum risk to surface. Defaults to `'medium'`. */
+  minRisk?: AuditRisk
+}
+
+const RISK_RANK: Record<AuditRisk, number> = {
+  high: 3,
+  medium: 2,
+  low: 1,
+}
+
+export const runAuditTestsGate = async (
+  opts: AuditTestsGateOptions,
+): Promise<GateResult> => {
+  const start = Date.now()
+  const findings: Finding[] = []
+  const minRisk = opts.minRisk ?? 'medium'
+  const minRank = RISK_RANK[minRisk] ?? 0
+
+  const result = auditTestEnvironment(opts.cwd)
+
+  for (const entry of result.entries) {
+    const rank = RISK_RANK[entry.risk] ?? 0
+    if (rank < minRank) continue
+    const severity = SEVERITY_BY_RISK[entry.risk] ?? 'warning'
+
+    findings.push({
+      category: 'testing',
+      severity,
+      code: `audit-tests/mock-vnode-${entry.risk}`,
+      gate: 'audit-tests',
+      message: `Mock-vnode test pattern (risk: ${entry.risk}). Literals: ${entry.mockVNodeLiteralCount}, helper defs: ${entry.mockHelperCount}, helper calls: ${entry.mockHelperCallCount}, real h() calls: ${entry.realHCallCount}. ${entry.realHCallCount === 0 ? 'No real-h() coverage — every contract assertion is mock-only.' : 'Has real-h() coverage but mock-vnode patterns still dominate.'}`,
+      location: { path: entry.path, relPath: entry.relPath },
+    })
+  }
+
+  return {
+    gate: 'audit-tests',
+    category: 'testing',
+    findings,
+    meta: {
+      scanned: result.entries.length,
+      elapsedMs: Date.now() - start,
+    },
+  }
+}

package/src/doctor/gates/audit-types.ts

@@ -0,0 +1,146 @@
+/**
+ * audit-types gate — programmatic API.
+ *
+ * Catches typed-but-unimplemented public-interface fields. Walks every
+ * exported interface in each high-risk package and counts non-type
+ * references; fields with zero references are flagged HIGH. Catches the
+ * 0.14.0-class bug (`mode: "ssg"` typed but never read by runtime).
+ *
+ * **Implementation note (subprocess adapter).** This gate invokes the
+ * standalone `scripts/audit-types.ts` script via `--json --all` and
+ * parses the output. The script is 476 lines of mature AST-walking
+ * logic with its own test suite; rather than surgically extract it
+ * mid-shape, the adapter shape keeps PR 1 tractable and lets PR 2's
+ * aggregation layer consume the same `Finding[]` shape as the other
+ * gates. Adapter cost is ~50ms subprocess overhead — noise within the
+ * gate's 1-5s scan runtime. Full extraction is a deferred follow-up
+ * (the doctor aggregator doesn't care HOW the gate runs).
+ */
+
+import { execFileSync } from 'node:child_process'
+import { join } from 'node:path'
+import type { Finding, GateResult, Severity } from '../types'
+
+interface ScriptFieldFinding {
+  package: string
+  interface: string
+  field: string
+  declaredIn: string
+  declaredLine: number
+  refCount: number
+  severity: 'HIGH' | 'MEDIUM' | 'LOW' | 'OK'
+}
+
+interface ScriptAuditResult {
+  package: string
+  packageDir: string
+  findings: ScriptFieldFinding[]
+}
+
+const mapSeverity = (s: ScriptFieldFinding['severity']): Severity | null => {
+  switch (s) {
+    case 'HIGH':
+      return 'error'
+    case 'MEDIUM':
+      return 'warning'
+    case 'LOW':
+      return 'info'
+    case 'OK':
+      return null // suppress — field has references, not a finding
+  }
+}
+
+/**
+ * Pure parse-and-map function — public so tests can exercise the JSON
+ * → `Finding[]` translation without spawning a subprocess. Returns the
+ * findings plus the count of packages scanned. Exported as `_internal`
+ * (unstable API surface — may move when PR 2 lands the aggregator).
+ */
+export const _parseAuditTypesOutput = (
+  raw: string,
+  cwd: string,
+): { findings: Finding[]; scanned: number } => {
+  const results = JSON.parse(raw) as ScriptAuditResult[]
+  const findings: Finding[] = []
+  for (const r of results) {
+    for (const f of r.findings) {
+      const severity = mapSeverity(f.severity)
+      if (severity === null) continue
+
+      findings.push({
+        category: 'architecture',
+        severity,
+        code: `audit-types/typed-but-unimplemented-${f.severity.toLowerCase()}`,
+        gate: 'audit-types',
+        message: `${f.package}: \`${f.interface}.${f.field}\` is typed in the public API but has ${f.refCount} non-type reference(s) in the package — likely typed-but-unimplemented.`,
+        location: {
+          path: join(cwd, f.declaredIn),
+          relPath: f.declaredIn,
+          line: f.declaredLine,
+        },
+      })
+    }
+  }
+  return { findings, scanned: results.length }
+}
+
+export interface AuditTypesGateOptions {
+  /** Repository root directory */
+  cwd: string
+  /** Path to bun executable. Defaults to `'bun'`. */
+  bun?: string
+  /**
+   * Specific packages to audit. Defaults to `--all` (high-risk list
+   * baked into the script: zero, router, core, server, runtime-server,
+   * vite-plugin).
+   */
+  packages?: string[]
+}
+
+export const runAuditTypesGate = async (
+  opts: AuditTypesGateOptions,
+): Promise<GateResult> => {
+  const start = Date.now()
+  const findings: Finding[] = []
+  const scriptPath = join(opts.cwd, 'scripts/audit-types.ts')
+  const args = ['run', scriptPath, '--json']
+  if (opts.packages && opts.packages.length > 0) {
+    args.push(...opts.packages)
+  } else {
+    args.push('--all')
+  }
+
+  let scannedPackages = 0
+  try {
+    const out = execFileSync(opts.bun ?? 'bun', args, {
+      cwd: opts.cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: 16 * 1024 * 1024, // 16MB — audit can produce large output
+    })
+    const parsed = _parseAuditTypesOutput(out, opts.cwd)
+    findings.push(...parsed.findings)
+    scannedPackages = parsed.scanned
+  } catch (err) {
+    // Script failure — surface as a single ERROR finding so the
+    // gate doesn't silently skip. Captures "script not found",
+    // parse errors, exec errors, etc.
+    findings.push({
+      category: 'architecture',
+      severity: 'error',
+      code: 'audit-types/gate-failed',
+      gate: 'audit-types',
+      message: `audit-types gate failed to run: ${(err as Error).message}`,
+    })
+  }
+
+  return {
+    gate: 'audit-types',
+    category: 'architecture',
+    findings,
+    meta: {
+      scanned: scannedPackages,
+      elapsedMs: Date.now() - start,
+    },
+  }
+}

package/src/doctor/gates/bundle-budgets.ts

@@ -0,0 +1,187 @@
+/**
+ * bundle-budgets gate — programmatic API.
+ *
+ * Locks the gzipped main-entry size of every published `@pyreon/*`
+ * package against `scripts/bundle-budgets.json` (current + 25% headroom).
+ * Three classes of finding land here:
+ *
+ *   1. **violations** — package bundles past its budget (real regression).
+ *      Severity: `error`. Code: `bundle-budgets/over-budget`.
+ *   2. **missing** — package has no entry in `bundle-budgets.json` yet
+ *      (new published package — author needs to commit a budget).
+ *      Severity: `warning`. Code: `bundle-budgets/missing-budget`.
+ *   3. **failures** — the bundler couldn't measure a package (unresolved
+ *      transitive dep, build artifact issue). Severity: `error`. Code:
+ *      `bundle-budgets/bundle-failed`. Surfaced as a finding rather than
+ *      silently dropped — same lesson as PR #434.
+ *
+ * **Implementation note (subprocess adapter).** This gate invokes the
+ * standalone `scripts/check-bundle-budgets.ts` script via `--json` and
+ * parses the output. The script is 466 lines of bundler orchestration
+ * + AST-walking dep collection logic; extracting it surgically into a
+ * pure function carries too much risk for PR 1. The adapter shape lets
+ * the doctor aggregator consume the same `Finding[]` shape as the other
+ * gates; full extraction is a deferred follow-up (`pyreon doctor`
+ * doesn't care HOW the gate runs — only that it returns `GateResult`).
+ *
+ * The full-bundle measurement is the slowest gate (~15-30s against
+ * 50+ published packages). Doctor's default fast mode opts this gate
+ * OUT; `--full` enables it.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { join } from 'node:path'
+import type { Finding, GateResult } from '../types'
+
+interface ScriptViolation {
+  name: string
+  current: number
+  budget: number
+  overBy: number
+  overByPct: number
+}
+
+interface ScriptMissing {
+  name: string
+  current: number
+}
+
+interface ScriptFailure {
+  name: string
+  error: string
+}
+
+interface ScriptMeasured {
+  name: string
+  raw: number
+  gzip: number
+}
+
+interface ScriptOutput {
+  violations: ScriptViolation[]
+  missing: ScriptMissing[]
+  failures: ScriptFailure[]
+  measured: ScriptMeasured[]
+}
+
+const formatKB = (bytes: number): string => `${(bytes / 1024).toFixed(2)} KB`
+
+/**
+ * Pure parse-and-map function — public so tests can exercise the JSON
+ * → `Finding[]` translation without spawning a subprocess. Returns the
+ * findings plus the count of packages scanned (measured + failures).
+ * Exported as `_internal` (unstable API surface — may move when PR 2
+ * lands the aggregator).
+ */
+export const _parseBundleBudgetsOutput = (
+  raw: string,
+  cwd: string,
+): { findings: Finding[]; scanned: number } => {
+  const result = JSON.parse(raw) as ScriptOutput
+  const findings: Finding[] = []
+  const budgetsRelPath = 'scripts/bundle-budgets.json'
+  const budgetsPath = join(cwd, budgetsRelPath)
+
+  for (const v of result.violations) {
+    findings.push({
+      category: 'performance',
+      severity: 'error',
+      code: 'bundle-budgets/over-budget',
+      gate: 'bundle-budgets',
+      message: `${v.name}: ${formatKB(v.current)} > budget ${formatKB(v.budget)} (over by ${formatKB(v.overBy)}, +${v.overByPct.toFixed(1)}%). If growth is intentional, bump the value in scripts/bundle-budgets.json — the bump itself is the PR signal.`,
+      location: { path: budgetsPath, relPath: budgetsRelPath },
+      fix: `Run \`bun run check-bundle-budgets --update\` to regenerate budgets after intentional growth.`,
+    })
+  }
+
+  for (const m of result.missing) {
+    findings.push({
+      category: 'performance',
+      severity: 'warning',
+      code: 'bundle-budgets/missing-budget',
+      gate: 'bundle-budgets',
+      message: `${m.name}: ${formatKB(m.current)} (no budget entry). New published package?`,
+      location: { path: budgetsPath, relPath: budgetsRelPath },
+      fix: `Run \`bun run check-bundle-budgets --update\` and review the diff.`,
+    })
+  }
+
+  for (const f of result.failures) {
+    findings.push({
+      category: 'performance',
+      severity: 'error',
+      code: 'bundle-budgets/bundle-failed',
+      gate: 'bundle-budgets',
+      message: `${f.name}: bundle failed — ${f.error.split('\n')[0]}. Likely an unresolved third-party dep that the auto-external scan missed.`,
+    })
+  }
+
+  return {
+    findings,
+    scanned: result.measured.length + result.failures.length,
+  }
+}
+
+export interface BundleBudgetsGateOptions {
+  /** Repository root directory */
+  cwd: string
+  /** Path to bun executable. Defaults to `'bun'`. */
+  bun?: string
+}
+
+export const runBundleBudgetsGate = async (
+  opts: BundleBudgetsGateOptions,
+): Promise<GateResult> => {
+  const start = Date.now()
+  const findings: Finding[] = []
+  const scriptPath = join(opts.cwd, 'scripts/check-bundle-budgets.ts')
+
+  let scannedPackages = 0
+  try {
+    // The script always exits 1 when there are violations/missing/failures
+    // — but writes valid JSON to stdout regardless. Use a try/catch to
+    // capture stdout from the non-zero exit. `execFileSync` throws on
+    // non-zero, attaching `.stdout` to the error object.
+    let out: string
+    try {
+      out = execFileSync(opts.bun ?? 'bun', ['run', scriptPath, '--json'], {
+        cwd: opts.cwd,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        maxBuffer: 16 * 1024 * 1024,
+      })
+    } catch (err) {
+      const e = err as { stdout?: string | Buffer; message?: string }
+      if (e.stdout) {
+        out = typeof e.stdout === 'string' ? e.stdout : e.stdout.toString('utf8')
+      } else {
+        throw err
+      }
+    }
+
+    const parsed = _parseBundleBudgetsOutput(out, opts.cwd)
+    findings.push(...parsed.findings)
+    scannedPackages = parsed.scanned
+  } catch (err) {
+    // Script failure — surface as a single ERROR finding so the
+    // gate doesn't silently skip. Captures parse errors, script-not-
+    // found, missing bundle-budgets.json, etc.
+    findings.push({
+      category: 'performance',
+      severity: 'error',
+      code: 'bundle-budgets/gate-failed',
+      gate: 'bundle-budgets',
+      message: `bundle-budgets gate failed to run: ${(err as Error).message}`,
+    })
+  }
+
+  return {
+    gate: 'bundle-budgets',
+    category: 'performance',
+    findings,
+    meta: {
+      scanned: scannedPackages,
+      elapsedMs: Date.now() - start,
+    },
+  }
+}