@nifrajs/cli 2.10.0 → 2.12.0

package/src/doctor.ts

@@ -17,10 +17,12 @@
  * undeclared import there fails a clean `bun install --frozen-lockfile` build just the same.
  */
 import type { Dirent } from "node:fs"
-import { readdir, realpath, stat } from "node:fs/promises"
+import { lstat, readdir, realpath, stat } from "node:fs/promises"
 import { builtinModules } from "node:module"
 import { dirname, join, relative, sep } from "node:path"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
+import { collectPipelineReport, type PipelineReport } from "./pipeline-report.ts"
+import { type ResolvedTarget, resolveTarget } from "./port.ts"
 
 // Runtime-provided modules that are never an npm dependency: Node core (bare + `node:` form) and Bun's
 // own `bun` module. `node:`/`bun:`-prefixed specifiers are filtered in packageOf by prefix.
@@ -135,12 +137,47 @@ export interface DoctorResult {
    * Advisory (never folded into `ok`): while actively editing a linked package its dist is always
    * momentarily behind - the finding matters when a dev server starts against it. */
   readonly staleDists: readonly StaleDistFinding[]
+  /** Static production-readiness evidence for the selected deploy target. */
+  readonly readiness?: DoctorReadiness
+  /**
+   * Which bundler this app's `dev`/`build` phases run on, read statically, plus the config hazards
+   * that exist only because there are two. Absent when the directory is not a nifra app.
+   *
+   * Reported by doctor rather than only by `dev`/`build` because the answer governs how the rest of a
+   * project is read - which plugin slot is live, whether `conditions` reach the client bundle, which
+   * toolchain compiles a component - and asking for it should not require starting a server.
+   */
+  readonly pipeline?: PipelineReport
   /** Dependencies written by `--auto-fix` / MCP `autoFix:true`. */
   readonly fixed?: readonly DoctorAppliedFix[]
   /** Findings that were safe to report but not safe to write automatically. */
   readonly skippedFixes?: readonly DoctorSkippedFix[]
 }
 
+export type DoctorReadinessStatus = "configured" | "absent" | "not-applicable"
+
+export interface DoctorReadinessItem {
+  readonly id:
+    | "request-timeout"
+    | "admission"
+    | "request-id-tracing"
+    | "health-route"
+    | "log-redaction"
+    | "graceful-lifecycle"
+  readonly label: string
+  readonly status: DoctorReadinessStatus
+  readonly evidence?: string
+}
+
+export interface DoctorReadiness {
+  readonly target: string
+  readonly targetSource: ResolvedTarget["source"] | null
+  readonly strict: boolean
+  /** True when every applicable rule has static evidence. */
+  readonly ok: boolean
+  readonly items: readonly DoctorReadinessItem[]
+}
+
 export interface DuplicateInstallCopy {
   /** Installed version, or `unknown` when package metadata is incomplete. */
   readonly version: string
@@ -342,6 +379,66 @@ async function resolvedInstalledCopy(
   }
 }
 
+const MAX_LINKED_PACKAGES = 64
+const MAX_LINK_PROBES = 4_096
+
+/** Is `path` inside `root` (or `root` itself)? Both must already be real paths. */
+const isInside = (root: string, path: string): boolean =>
+  path === root || path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`)
+
+/**
+ * The repo boundary for a linked package: the nearest ancestor holding a `.git`, so the upward
+ * `node_modules` walk inside a sibling checkout stops where that checkout does instead of climbing
+ * into a shared parent directory. Falls back to the package directory itself.
+ */
+async function linkedRepoBoundary(packageRoot: string): Promise<string> {
+  let dir = packageRoot
+  for (let depth = 0; depth < 8; depth++) {
+    if (await pathExists(join(dir, ".git"))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return packageRoot
+}
+
+/**
+ * Dependency roots that are symlinks OUT of the scanned workspace - a sibling checkout linked in with
+ * `link:`/`file:`/`npm link`. Their own `node_modules` is a second physical install root, so a shared
+ * package (`@nifrajs/core`, React) resolves to a different directory there than it does here. That is
+ * a real duplicate: module identity is path-based, so registries, symbols, and hooks do not match
+ * across the two copies - the exact split that reads as "my types collapsed for no reason".
+ *
+ * One level deep and bounded: links inside a linked package are not followed.
+ */
+async function linkedPackageRoots(
+  importerRoots: readonly string[],
+  manifests: readonly Record<string, unknown>[],
+  scanRoot: string,
+): Promise<string[]> {
+  const realScanRoot = await realpath(scanRoot).catch(() => scanRoot)
+  const found = new Map<string, true>()
+  let probes = 0
+  for (const [index, importerRoot] of importerRoots.entries()) {
+    const pkg = manifests[index]
+    if (pkg === undefined) continue
+    const names = new Set<string>()
+    for (const field of DEPENDENCY_FIELDS) for (const name of depNames(pkg, field)) names.add(name)
+    for (const name of names) {
+      if (probes++ >= MAX_LINK_PROBES || found.size >= MAX_LINKED_PACKAGES) return [...found.keys()]
+      const candidate = join(importerRoot, "node_modules", ...name.split("/"))
+      // `lstat` first: on macOS `realpath` also rewrites symlinked ANCESTORS (`/tmp` ->
+      // `/private/tmp`), which would read as a link out of the workspace for every dependency.
+      const link = await lstat(candidate).catch(() => undefined)
+      if (link === undefined || !link.isSymbolicLink()) continue
+      const resolved = await realpath(candidate).catch(() => undefined)
+      if (resolved === undefined || isInside(realScanRoot, resolved)) continue
+      found.set(resolved, true)
+    }
+  }
+  return [...found.keys()]
+}
+
 const displayPath = (cwd: string, path: string): string => {
   const rel = relative(cwd, path)
   return rel === "" ? "." : rel
@@ -454,6 +551,28 @@ export async function collectDuplicateInstalls(
     if (copy !== undefined) record(name, copy, displayPath(cwd, scanRoot))
   }
 
+  // Sibling checkouts linked in (`link:`/`file:`/`npm link`) install their own copies. Their
+  // resolution is what the runtime and `tsc` actually use for code that crosses the link, so a split
+  // there is as real as one inside this workspace - and invisible to a scan bounded by the workspace.
+  const linkedRoots = await linkedPackageRoots(
+    [...importers.map((importer) => importer.root), scanRoot],
+    [...importers.map((importer) => importer.package), workspace?.package ?? rootPackage],
+    scanRoot,
+  )
+  for (const linkedRoot of linkedRoots) {
+    const linkedPackage = await readJson(join(linkedRoot, "package.json"))
+    const boundary = await linkedRepoBoundary(linkedRoot)
+    const linkedTargets = new Set([
+      ...targets,
+      ...(linkedPackage === undefined ? [] : duplicateTargets(linkedPackage)),
+    ])
+    for (const name of linkedTargets) {
+      if (linkedPackage?.name === name) continue
+      const copy = await resolvedInstalledCopy(linkedRoot, boundary, name)
+      if (copy !== undefined) record(name, copy, displayPath(cwd, linkedRoot))
+    }
+  }
+
   const findings: DuplicateInstallFinding[] = []
   for (const [name, copies] of [...byPackage.entries()].sort(([a], [b]) => a.localeCompare(b))) {
     if (copies.size < 2) continue
@@ -621,6 +740,110 @@ export async function collectStaleWorkspaceDists(
   return findings.sort((a, b) => a.package.localeCompare(b.package))
 }
 
+interface ReadinessSource {
+  readonly file: string
+  readonly code: string
+  readonly source: string
+}
+
+function sourceLineAt(source: string, index: number): number {
+  let line = 1
+  for (let i = 0; i < index && i < source.length; i++) if (source[i] === "\n") line++
+  return line
+}
+
+function readinessEvidence(
+  files: readonly ReadinessSource[],
+  pattern: RegExp,
+  source = "code",
+): string | undefined {
+  for (const file of files) {
+    const content = source === "source" ? file.source : file.code
+    const match = pattern.exec(content)
+    if (match !== null) return `${file.file}:${sourceLineAt(content, match.index)}`
+  }
+  return undefined
+}
+
+/** Read only source shapes used to report production readiness. Values and secrets are never loaded. */
+async function collectDoctorReadiness(
+  cwd: string,
+  opts: { readonly target?: string; readonly strict?: boolean },
+): Promise<DoctorReadiness> {
+  const resolved = await resolveTarget(cwd, opts.target)
+  const files: ReadinessSource[] = []
+  await walkSource(cwd, (file, source) => {
+    files.push({ file, source, code: codePositionMask(source) })
+  })
+  const edgeTarget = /^(?:cf-pages|vercel|workers|edge|static)$/.test(resolved?.target ?? "")
+  const configured = (
+    id: DoctorReadinessItem["id"],
+    label: string,
+    pattern: RegExp,
+    sourcePattern?: RegExp,
+  ): DoctorReadinessItem => {
+    const evidence = readinessEvidence(files, pattern)
+    const routeEvidence =
+      evidence === undefined && sourcePattern !== undefined
+        ? readinessEvidence(files, sourcePattern, "source")
+        : undefined
+    const found = evidence ?? routeEvidence
+    return found === undefined
+      ? { id, label, status: "absent" }
+      : { id, label, status: "configured", evidence: found }
+  }
+
+  const items: DoctorReadinessItem[] = [
+    configured(
+      "request-timeout",
+      "request timeout or budget",
+      /\b(?:requestTimeoutMs|createRequestBudget|admitDeadline)\s*[:(]/,
+    ),
+    // `admission: controller`, the shorthand `{ admission }` (trailing comma or closing brace), or
+    // the documented constructor call - shorthand is the idiomatic form when the controller is an
+    // import or module const.
+    configured(
+      "admission",
+      "capacity admission",
+      /\badmission\s*[:,}]|\bcreateAdmissionController\s*\(/,
+    ),
+    configured(
+      "request-id-tracing",
+      "request id or tracing middleware",
+      /\b(?:requestId|tracing)\s*\(/,
+    ),
+    configured(
+      "health-route",
+      "health route",
+      /\bhealthcheck\s*\(/,
+      // Conventional health paths: /health, /healthz (the k8s form healthcheck() is most often
+      // configured to serve), /health-check, and the underscore-prefixed variants, each also
+      // matching as a prefix (`/health/live`). `/healthy` etc. stay non-matches: the path must end
+      // (closing quote) or continue with a segment right after the recognized name.
+      /\.(?:get|head)\s*\(\s*["']\/_?health(?:z|-check)?(?:["']|\/)/,
+    ),
+    // Asserts "a redacting logger is INSTALLED", so only the call forms count: the redacting
+    // constructors, or @nifrajs/middleware's `logger()` structured request logger (which logs only
+    // method/path/status/duration - nothing redactable). A bare `logger:` property proves nothing:
+    // `logger: console` matches it and redacts nothing.
+    configured("log-redaction", "log redaction", /\b(?:jsonLogger|redactLogFields|logger)\s*\(/),
+    edgeTarget
+      ? { id: "graceful-lifecycle", label: "graceful lifecycle", status: "not-applicable" }
+      : configured(
+          "graceful-lifecycle",
+          "graceful lifecycle",
+          /\bgracefulSignals\s*:\s*true\b|\bonStop\s*\(/,
+        ),
+  ]
+  return {
+    target: resolved?.target ?? "unknown",
+    targetSource: resolved?.source ?? null,
+    strict: opts.strict === true,
+    ok: items.every((item) => item.status !== "absent"),
+    items,
+  }
+}
+
 function depRecord(
   pkg: Record<string, unknown>,
   field: string,
@@ -677,7 +900,10 @@ async function inferDependencyFix(
 }
 
 /** Run doctor against the project at `cwd`: diff source imports vs declared deps. */
-export async function collectDoctorResult(cwd: string): Promise<DoctorResult> {
+export async function collectDoctorResult(
+  cwd: string,
+  opts: { readonly target?: string; readonly strict?: boolean } = {},
+): Promise<DoctorResult> {
   const pkg = await readJson(join(cwd, "package.json"))
   if (pkg === undefined)
     return { ok: true, ran: false, findings: [], duplicateInstalls: [], staleDists: [] }
@@ -701,19 +927,31 @@ export async function collectDoctorResult(cwd: string): Promise<DoctorResult> {
   findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
   const duplicateInstalls = await collectDuplicateInstalls(cwd, pkg)
   const staleDists = await collectStaleWorkspaceDists(cwd, pkg)
+  const pipeline = await collectPipelineReport(cwd)
+  const pipelineErrors = pipeline.findings.filter((f) => f.severity === "error")
+  const readiness = await collectDoctorReadiness(cwd, opts)
   // `staleDists` is advisory (see DoctorResult): it never fails `ok`.
   return {
-    ok: findings.length === 0 && duplicateInstalls.length === 0,
+    ok:
+      findings.length === 0 &&
+      duplicateInstalls.length === 0 &&
+      pipelineErrors.length === 0 &&
+      (opts.strict !== true || readiness.ok),
     ran: true,
     findings,
     duplicateInstalls,
     staleDists,
+    readiness,
+    ...(pipeline.ran ? { pipeline } : {}),
   }
 }
 
 /** Safely add undeclared imports to package.json when the version can be inferred without network I/O. */
-export async function applyDoctorAutoFix(cwd: string): Promise<DoctorResult> {
-  const before = await collectDoctorResult(cwd)
+export async function applyDoctorAutoFix(
+  cwd: string,
+  opts: { readonly target?: string; readonly strict?: boolean } = {},
+): Promise<DoctorResult> {
+  const before = await collectDoctorResult(cwd, opts)
   if (!before.ran || before.findings.length === 0) return before
 
   const rootPackage = await readJson(join(cwd, "package.json"))
@@ -774,7 +1012,7 @@ export async function applyDoctorAutoFix(cwd: string): Promise<DoctorResult> {
     if (changed) await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
   }
 
-  const after = fixed.length > 0 ? await collectDoctorResult(cwd) : before
+  const after = fixed.length > 0 ? await collectDoctorResult(cwd, opts) : before
   return {
     ...after,
     ...(fixed.length > 0 ? { fixed } : {}),
@@ -785,9 +1023,16 @@ export async function applyDoctorAutoFix(cwd: string): Promise<DoctorResult> {
 /** Run doctor; print a report (`--json` for machine output) and return whether it passed. */
 export async function runDoctor(
   cwd: string,
-  opts: { readonly json?: boolean; readonly autoFix?: boolean } = {},
+  opts: {
+    readonly json?: boolean
+    readonly autoFix?: boolean
+    readonly strict?: boolean
+    readonly target?: string
+  } = {},
 ): Promise<boolean> {
-  const result = opts.autoFix ? await applyDoctorAutoFix(cwd) : await collectDoctorResult(cwd)
+  const result = opts.autoFix
+    ? await applyDoctorAutoFix(cwd, opts)
+    : await collectDoctorResult(cwd, opts)
   if (opts.json) {
     console.log(JSON.stringify(result, null, 2))
     return result.ok
@@ -811,6 +1056,20 @@ export async function runDoctor(
     }
     console.log("")
   }
+  // Printed before the findings and regardless of ok: which bundler owns this app is the frame the
+  // rest of the report is read in, not a footnote to it.
+  if (result.pipeline !== undefined) {
+    const p = result.pipeline
+    console.log(
+      p.pipeline === "unknown"
+        ? `• bundler: could not be read from ${p.configFile} - ${p.reason}\n`
+        : `• bundler: ${p.pipeline} (${p.reason})\n`,
+    )
+    for (const f of p.findings) {
+      console.log(`${f.severity === "error" ? "✗" : "⚠"} ${f.file}:${f.line ?? 0}  ${f.message}`)
+      console.log(`      fix: ${f.fix}\n`)
+    }
+  }
   // Advisory, printed regardless of ok: a stale linked dist doesn't fail doctor, but silently eating
   // it costs an hour of misdiagnosis when the dev server 500s inside the package.
   if (result.staleDists.length > 0) {
@@ -827,6 +1086,22 @@ export async function runDoctor(
     }
     console.log("")
   }
+  if (result.readiness !== undefined) {
+    const readiness = result.readiness
+    console.log(
+      `production readiness (${readiness.target}${readiness.targetSource === null ? "" : `, detected from ${readiness.targetSource}`}):\n`,
+    )
+    for (const item of readiness.items) {
+      const marker =
+        item.status === "configured" ? "✓" : item.status === "not-applicable" ? "-" : "✗"
+      const evidence = item.evidence === undefined ? "" : ` (${item.evidence})`
+      console.log(`  ${marker} ${item.label}: ${item.status}${evidence}`)
+    }
+    if (readiness.strict && !readiness.ok) {
+      console.log("\n  --strict: every applicable readiness rule must be configured")
+    }
+    console.log("")
+  }
   if (result.ok) {
     console.log(
       "✓ every imported package is declared and identity-sensitive installs are deduplicated",
@@ -869,6 +1144,9 @@ export async function runDoctor(
       "\n  Align dependency ranges and reinstall from the workspace root; doctor never deletes installs.",
     )
   }
+  if (result.readiness?.strict === true && result.readiness.ok === false) {
+    console.log("\n✗ production readiness is incomplete under --strict")
+  }
   if (byPkg.size > 0)
     console.log(
       "\nThese resolve at Bun runtime via hoisting/workspace but break `tsc` and a standalone install.",

package/src/examples.ts

@@ -23,6 +23,29 @@ export interface ScoredExample extends Example {
   readonly score: number
 }
 
+interface PreparedExample {
+  readonly example: Example
+  readonly labelTokens: ReadonlySet<string>
+  readonly codeLower: string
+}
+
+const preparedExamplesCache = new WeakMap<readonly Example[], readonly PreparedExample[]>()
+const prepareExamples = (examples: readonly Example[]): readonly PreparedExample[] => {
+  const cached = preparedExamplesCache.get(examples)
+  if (cached !== undefined) return cached
+  const prepared = examples.map((example) => ({
+    example,
+    labelTokens: new Set([
+      ...tokenize(example.slug),
+      ...tokenize(example.topic),
+      ...tokenize(example.name),
+    ]),
+    codeLower: example.code.toLowerCase(),
+  }))
+  preparedExamplesCache.set(examples, prepared)
+  return prepared
+}
+
 /** Score examples against the query: a term in the slug/topic/name (the curated, searchable labels)
  * is worth far more than a mention in the code body; body hits cap per term so one long snippet can't
  * outweigh a precisely-tagged one. */
@@ -34,13 +57,12 @@ export function searchExamples(
   const terms = queryTermGroups(query)
   if (terms.length === 0) return []
   const scored: ScoredExample[] = []
-  for (const ex of examples) {
-    const labelTokens = new Set([...tokenize(ex.slug), ...tokenize(ex.topic), ...tokenize(ex.name)])
-    const codeLower = ex.code.toLowerCase()
+  for (const prepared of prepareExamples(examples)) {
+    const ex = prepared.example
     let score = 0
     for (const term of terms) {
-      if (tokenSetHas(labelTokens, term)) score += 8
-      score += countBodyHits(codeLower, term, 5)
+      if (tokenSetHas(prepared.labelTokens, term)) score += 8
+      score += countBodyHits(prepared.codeLower, term, 5)
     }
     if (score > 0) scored.push({ ...ex, score })
   }
@@ -76,14 +98,20 @@ export function renderExamplesResult(
 
 /** Load the bundled example corpus. Resolves relative to this module so it works from `src/` (repo dev)
  * and `dist/` (published) alike - `docs/examples.json` sits at the package root next to both. */
-export async function loadExamplesCorpus(): Promise<Example[] | undefined> {
-  const url = new URL("../docs/examples.json", import.meta.url)
-  try {
-    const text = await Bun.file(url).text()
-    if (text.length === 0) return undefined
-    const parsed = JSON.parse(text) as Example[]
-    return Array.isArray(parsed) && parsed.length > 0 ? parsed : undefined
-  } catch {
-    return undefined
-  }
+let examplesCorpusPromise: Promise<Example[] | undefined> | undefined
+
+/** The published corpus is immutable, so keep one loaded array and its derived search fields. */
+export function loadExamplesCorpus(): Promise<Example[] | undefined> {
+  examplesCorpusPromise ??= (async () => {
+    const url = new URL("../docs/examples.json", import.meta.url)
+    try {
+      const text = await Bun.file(url).text()
+      if (text.length === 0) return undefined
+      const parsed = JSON.parse(text) as Example[]
+      return Array.isArray(parsed) && parsed.length > 0 ? parsed : undefined
+    } catch {
+      return undefined
+    }
+  })()
+  return examplesCorpusPromise
 }

package/src/fix-recipes.ts

@@ -0,0 +1,126 @@
+import { existsSync } from "node:fs"
+import { readFile, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import type { Diagnostic } from "./diagnostics.ts"
+import { resolveInsideProject } from "./project-path.ts"
+
+export interface FixRecipe {
+  readonly id: string
+  readonly description: string
+  apply(root: string, diagnostic: Diagnostic): Promise<readonly string[]>
+  readonly verify: string
+}
+
+const recipes = new Map<string, FixRecipe>()
+
+export function registerFixRecipe(recipe: FixRecipe): void {
+  if (recipes.has(recipe.id)) throw new Error(`duplicate fix recipe: ${recipe.id}`)
+  recipes.set(recipe.id, Object.freeze(recipe))
+}
+
+export function getFixRecipe(id: string): FixRecipe | undefined {
+  return recipes.get(id)
+}
+
+export function listFixRecipes(): readonly FixRecipe[] {
+  return Object.freeze([...recipes.values()])
+}
+
+registerFixRecipe({
+  id: "security.timing-safe-equal",
+  description: "Replace a direct secret comparison with a length check and timing-safe comparison.",
+  verify: "nifra check --lints-only",
+  async apply(root, diagnostic) {
+    if (diagnostic.file === undefined || diagnostic.line === undefined) return []
+    const path = await resolveInsideProject(root, diagnostic.file)
+    if (path === undefined) return []
+    const lines = (await readFile(path, "utf8")).split("\n")
+    const index = diagnostic.line - 1
+    const original = lines[index]
+    if (original === undefined || original.includes("@nifra-gate-reviewed")) return []
+    const comparison = /\b([A-Za-z_$][\w$]*)\s*(===|!==|==|!=)\s*([A-Za-z_$][\w$]*)/.exec(original)
+    if (comparison === null) return []
+    const left = comparison[1] as string
+    const operator = comparison[2] as string
+    const right = comparison[3] as string
+    const expression = `nifraTimingSafeEqual(${left}, ${right})`
+    const replacement = operator === "!==" || operator === "!=" ? `!${expression}` : expression
+    lines[index] = original.replace(comparison[0], replacement)
+    if (!lines.some((line) => line.includes("function nifraTimingSafeEqual"))) {
+      lines.unshift(
+        'import { timingSafeEqual } from "node:crypto"',
+        "",
+        "function nifraTimingSafeEqual(left: string, right: string): boolean {",
+        "  const leftBytes = Buffer.from(left)",
+        "  const rightBytes = Buffer.from(right)",
+        "  return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes)",
+        "}",
+        "",
+      )
+    }
+    await writeFile(path, lines.join("\n"), "utf8")
+    return [diagnostic.file]
+  },
+})
+
+registerFixRecipe({
+  id: "manifest.sync",
+  description: "Regenerate generated server manifests from the current route tree.",
+  verify: "nifra check --lints-only",
+  async apply(root) {
+    const { syncServerManifests } = await import("./sync-manifest.ts")
+    const results = await syncServerManifests(root)
+    return results.filter((result) => result.changed).map((result) => result.file)
+  },
+})
+
+registerFixRecipe({
+  id: "contracts.snapshot",
+  description: "Refresh the opt-in contract lock after reviewing an intentional route change.",
+  verify: "nifra contracts check",
+  async apply(root) {
+    const { snapshotContracts } = await import("./contracts.ts")
+    await snapshotContracts(root)
+    return ["contracts.lock.json"]
+  },
+})
+
+registerFixRecipe({
+  id: "workspace-dist.rebuild",
+  description: "Rebuild the workspace-linked package whose artifact is older than its source.",
+  verify: "nifra doctor --json",
+  async apply(root, diagnostic) {
+    const packageName = diagnostic.evidence?.[0]
+    if (packageName === undefined || !/^@?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)?$/.test(packageName))
+      return []
+    // The segment regex above admits "." and "..", which would resolve outside node_modules.
+    if (packageName.split("/").some((segment) => segment === "." || segment === "..")) return []
+    const packageDir = await resolveInsideProject(root, join("node_modules", packageName))
+    if (packageDir === undefined) return []
+    const packageJson = await resolveInsideProject(
+      root,
+      join("node_modules", packageName, "package.json"),
+    )
+    if (packageJson === undefined || !existsSync(packageJson)) return []
+    const proc = Bun.spawn(["bun", "run", "build"], {
+      cwd: packageDir,
+      stdout: "ignore",
+      stderr: "pipe",
+    })
+    const error = await new Response(proc.stderr).text()
+    const exitCode = await proc.exited
+    if (exitCode !== 0) throw new Error(error.trim() || `build failed for ${packageName}`)
+    return [diagnostic.evidence?.[1] ?? packageName]
+  },
+})
+
+export async function applyDiagnosticRecipe(
+  root: string,
+  diagnostic: Diagnostic,
+): Promise<readonly string[]> {
+  const recipeId = diagnostic.fix?.recipe
+  if (recipeId === undefined) return []
+  const recipe = getFixRecipe(recipeId)
+  if (recipe === undefined) return []
+  return recipe.apply(root, diagnostic)
+}