@nifrajs/cli 4.0.2 → 5.1.0

package/src/command-catalog.ts

@@ -17,14 +17,15 @@ import { cdnCheckSpec } from "./cdn-check.ts"
 import { type CheckResult, renderCheckReport } from "./check.ts"
 import type { ContractsLock } from "./contracts.ts"
 import { dbAuditSpec, dbQuerySpec, dbRoleSpec, dbSchemaSpec } from "./db-tool.ts"
-import { errorsSpec, logsSpec } from "./dev-feed-tool.ts"
+import { errorsSpec, explainSpec, logsSpec } from "./dev-feed-tool.ts"
 import { type Diagnostic, diagnostic, normalizeSeverity, toSarifLog } from "./diagnostics.ts"
 import type { DoctorResult } from "./doctor.ts"
 import { type I18nCheckOutput, i18nCheckPassed, renderI18nCheck } from "./i18n-check.ts"
 import type { VerificationLevelsResult } from "./levels-tool.ts"
-import type { LoadedApp } from "./load.ts"
+import type { AppLoader, IntrospectedApp } from "./load.ts"
 import type { ManifestEmitCommandResult } from "./manifest-tool.ts"
 import type { LayoutMigrationResult } from "./migrate-layout.ts"
+import type { OutputSchemaStatus, OutputSchemasReport } from "./output-schemas.ts"
 import { collectPortResult, type PortResult, renderReport } from "./port.ts"
 import type { ReplayResult } from "./replay.ts"
 import { reviewSpec } from "./review.ts"
@@ -80,8 +81,8 @@ export interface CommandCtx {
   readonly signal?: AbortSignal
   readonly progress?: (message: string) => void
   readonly cliVersion?: string
-  /** Adapter-provided cache for commands that need the loaded web app. */
-  readonly loadApp?: () => Promise<LoadedApp>
+  /** Adapter-provided cache for commands that need the loaded app. */
+  readonly loadApp?: AppLoader
 }
 
 export interface CommandSpec<Input, Output> {
@@ -328,6 +329,8 @@ interface RoutesInput {
   readonly json?: boolean | undefined
   readonly graph?: boolean | undefined
   readonly modes?: boolean | undefined
+  readonly hooks?: boolean | undefined
+  readonly since?: string | undefined
   readonly target?: string | undefined
   readonly dir?: string | undefined
 }
@@ -364,6 +367,8 @@ interface MigrateInput {
   readonly from?: "tailwind" | undefined
   readonly to?: "stylex" | undefined
   readonly write?: boolean | undefined
+  /** `migrate layout`: list the folders modules would leave in package.json zones instead. */
+  readonly zones?: boolean | undefined
   readonly json?: boolean | undefined
   readonly dir?: string | undefined
 }
@@ -390,6 +395,13 @@ interface TypesInput {
   readonly dir?: string | undefined
 }
 
+interface SchemasInput {
+  readonly write?: boolean | undefined
+  readonly check?: boolean | undefined
+  readonly json?: boolean | undefined
+  readonly dir?: string | undefined
+}
+
 interface SnapshotInput {
   readonly out?: string | undefined
   readonly json?: boolean | undefined
@@ -458,7 +470,7 @@ interface AssureCommandOutput {
 interface LevelsCommandOutput extends VerificationLevelsResult {}
 interface RoutesCommandOutput {
   readonly ok: boolean
-  readonly mode: "default" | "graph" | "modes"
+  readonly mode: "default" | "graph" | "modes" | "hooks"
   readonly data: unknown
   readonly text: string
 }
@@ -477,6 +489,8 @@ interface FixCommandOutput {
   /** Recipes that refused, with the reason. A recipe that cannot act says so here instead of
    * aborting the run or - worse - reporting nothing at all. */
   readonly failed: readonly { readonly code: string; readonly reason: string }[]
+  /** Findings whose recipe runs only when its code is named, because its change needs review. */
+  readonly skipped: readonly { readonly code: string; readonly reason: string }[]
   readonly diagnostics: readonly unknown[]
 }
 type MigrateCommandOutput =
@@ -493,6 +507,9 @@ interface DiffCommandOutput {
   readonly hasBreaking: boolean
   readonly changes: readonly unknown[]
 }
+interface RouteDiffCommandOutput extends DiffCommandOutput {
+  readonly text: string
+}
 interface ContractsCommandOutput {
   readonly ok: boolean
   readonly lock?: ContractsLock
@@ -647,15 +664,20 @@ const ROUTES_SCHEMA = input<RoutesInput>(
     json: { type: "boolean" },
     graph: { type: "boolean" },
     modes: { type: "boolean" },
+    hooks: { type: "boolean" },
+    since: { type: "string" },
     target: { type: "string" },
     dir: { type: "string" },
   }),
   (value) => {
     const raw = withDir(record(value))
-    if (raw.graph === true && raw.modes === true)
-      throw new TypeError("graph and modes cannot be combined")
+    if ([raw.graph, raw.modes, raw.hooks].filter((flag) => flag === true).length > 1)
+      throw new TypeError("graph, modes and hooks cannot be combined")
+    if (raw.since !== undefined && raw.hooks !== true)
+      throw new TypeError("since compares hook reports and needs hooks")
     return {
-      ...parseBooleanFlags(raw, ["json", "graph", "modes"]),
+      ...parseBooleanFlags(raw, ["json", "graph", "modes", "hooks"]),
+      since: optionalString(raw.since, "since"),
       target: optionalString(raw.target, "target"),
       ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     }
@@ -734,13 +756,14 @@ const MIGRATE_SCHEMA = input<MigrateInput>(
     from: { type: "string", enum: ["tailwind"] },
     to: { type: "string", enum: ["stylex"] },
     write: { type: "boolean" },
+    zones: { type: "boolean" },
     json: { type: "boolean" },
     dir: { type: "string" },
   }),
   (value) => {
     const raw = withDir(record(value))
     const flags = {
-      ...parseBooleanFlags(raw, ["write", "json"]),
+      ...parseBooleanFlags(raw, ["write", "zones", "json"]),
       ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     }
     const kind = optionalString(raw.kind, "kind")
@@ -749,6 +772,7 @@ const MIGRATE_SCHEMA = input<MigrateInput>(
         throw new TypeError("the migration must be `layout` (or --from tailwind --to stylex)")
       return { kind, ...flags }
     }
+    if (raw.zones === true) throw new TypeError("--zones applies to `migrate layout` only")
     const from = optionalString(raw.from, "from")
     const to = optionalString(raw.to, "to")
     if (from !== "tailwind") throw new TypeError("from must be tailwind")
@@ -781,6 +805,22 @@ const TYPES_SCHEMA = input<TypesInput>(
   },
 )
 
+const SCHEMAS_SCHEMA = input<SchemasInput>(
+  objectSchema({
+    write: { type: "boolean" },
+    check: { type: "boolean" },
+    json: { type: "boolean" },
+    dir: { type: "string" },
+  }),
+  (value) => {
+    const raw = withDir(record(value))
+    return {
+      ...parseBooleanFlags(raw, ["write", "check", "json"]),
+      ...(raw.dir === undefined ? {} : { dir: raw.dir }),
+    }
+  },
+)
+
 const SNAPSHOT_SCHEMA = input<SnapshotInput>(
   objectSchema({ out: { type: "string" }, json: { type: "boolean" }, dir: { type: "string" } }),
   (value) => {
@@ -944,9 +984,10 @@ const I18N_SCHEMA = input<I18nInput>(
   },
 )
 
-function loadAppFor(ctx: CommandCtx): Promise<LoadedApp> {
-  if (ctx.loadApp !== undefined) return ctx.loadApp()
-  return import("./load.ts").then(({ loadApp }) => loadApp(ctx.cwd))
+/** The app as the backend readers see it: an API-only app is its `backend/app.ts` alone. */
+function backendAppFor(ctx: CommandCtx): Promise<IntrospectedApp> {
+  if (ctx.loadApp !== undefined) return ctx.loadApp.backend()
+  return import("./load.ts").then(({ loadBackendApp }) => loadBackendApp(ctx.cwd))
 }
 
 function structuredDiagnostics(out: CheckCommandOutput): readonly Diagnostic[] {
@@ -1195,7 +1236,8 @@ const manifestSpec: CommandSpec<ManifestInput, ManifestEmitCommandResult | DiffC
 
 const routesSpec: CommandSpec<RoutesInput, RoutesCommandOutput> = {
   name: "routes",
-  summary: "List, graph, or target-check every page and API route the app serves.",
+  summary:
+    "List, graph, or target-check every page and API route the app serves, or the hooks each runs.",
   input: ROUTES_SCHEMA,
   output: output({
     type: "object",
@@ -1209,12 +1251,47 @@ const routesSpec: CommandSpec<RoutesInput, RoutesCommandOutput> = {
       { name: "json", field: "json", type: "boolean" },
       { name: "graph", field: "graph", type: "boolean" },
       { name: "modes", field: "modes", type: "boolean" },
+      { name: "hooks", field: "hooks", type: "boolean" },
+      { name: "since", field: "since", type: "string" },
       { name: "target", field: "target", type: "string" },
     ],
   },
   async run(value, ctx) {
-    const app = await loadAppFor(ctx)
+    if (value.hooks === true) {
+      const app = await backendAppFor(ctx)
+      const hooks = await import("./hooks-report.ts")
+      const report = await hooks.collectHookReport(app.backend)
+      if (value.since === undefined) {
+        return { ok: true, mode: "hooks", data: report, text: hooks.renderHookReport(report) }
+      }
+      const saved = hooks.parseHookReport(
+        await Bun.file(resolve(ctx.cwd, value.since))
+          .text()
+          .catch(() => ""),
+      )
+      if (saved === undefined) {
+        return {
+          ok: false,
+          mode: "hooks",
+          data: { report, error: `${value.since} is not a saved hook report` },
+          text: `[nifra] ${value.since} is not a saved hook report (write one with \`nifra routes --hooks --json\`)`,
+        }
+      }
+      const changes = hooks.diffHookReports(saved, report)
+      return {
+        ok: true,
+        mode: "hooks",
+        data: { report, changes },
+        text: hooks.renderHookDiff(changes),
+      }
+    }
+    const app = await backendAppFor(ctx)
     if (value.modes === true) {
+      if (app.framework === undefined) {
+        throw new Error(
+          `[nifra] routes --modes reads page routes, and ${ctx.cwd} is an API-only app (backend/app.ts, no web config)`,
+        )
+      }
       const { buildRouteManifest, renderRouteManifest } = await import(
         "@nifrajs/web/route-manifest"
       )
@@ -1264,7 +1341,7 @@ const contextSpec: CommandSpec<ContextInput, ContextCommandOutput> = {
   async run(value, ctx) {
     return {
       ok: true,
-      text: (await import("./introspect.ts")).describeProject(await loadAppFor(ctx), {
+      text: (await import("./introspect.ts")).describeProject(await backendAppFor(ctx), {
         ...(value.path === undefined ? {} : { path: value.path }),
         ...(value.kind === undefined ? {} : { kind: value.kind }),
       }),
@@ -1292,10 +1369,7 @@ const openApiSpec: CommandSpec<OpenApiInput, OpenApiCommandOutput> = {
     ],
   },
   async run(value, ctx) {
-    const app =
-      ctx.loadApp !== undefined
-        ? await ctx.loadApp()
-        : await import("./load.ts").then(({ loadBackendApp }) => loadBackendApp(ctx.cwd))
+    const app = await backendAppFor(ctx)
     const { renderOpenApiWithTypes } = await import("./openapi-tool.ts")
     const format = value.format ?? "json"
     return {
@@ -1356,6 +1430,7 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
       ok: { type: "boolean" },
       changed: { type: "array" },
       failed: { type: "array" },
+      skipped: { type: "array" },
       diagnostics: { type: "array" },
     },
     required: ["ok", "diagnostics"],
@@ -1370,25 +1445,37 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
   },
   async run(value, ctx) {
     const { collectCheckResult } = await import("./check.ts")
-    const { applyDiagnosticRecipe } = await import("./fix-recipes.ts")
+    const { applyDiagnosticRecipe, getFixRecipe } = await import("./fix-recipes.ts")
     const result = await collectCheckResult(ctx.cwd, {
       lintsOnly: true,
       ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
     })
     const changed: string[] = []
     const failed: { code: string; reason: string }[] = []
-    for (const diagnostic of result.structuredDiagnostics ?? [])
-      if (value.code === undefined || diagnostic.code === value.code)
-        // One recipe that cannot act must not cancel the others, and must not pass silently either:
-        // record why and keep going, so a run over many diagnostics still reports every outcome.
-        try {
-          changed.push(...(await applyDiagnosticRecipe(ctx.cwd, diagnostic)))
-        } catch (error) {
-          failed.push({
+    const skipped: { code: string; reason: string }[] = []
+    for (const diagnostic of result.structuredDiagnostics ?? []) {
+      if (value.code !== undefined && diagnostic.code !== value.code) continue
+      const recipe =
+        diagnostic.fix?.recipe === undefined ? undefined : getFixRecipe(diagnostic.fix.recipe)
+      if (value.code === undefined && recipe?.onlyWhenNamed === true) {
+        if (!skipped.some((entry) => entry.code === diagnostic.code))
+          skipped.push({
             code: diagnostic.code,
-            reason: error instanceof Error ? error.message : String(error),
+            reason: `${recipe.description} Review the finding, then run \`nifra fix --code ${diagnostic.code}\`.`,
           })
-        }
+        continue
+      }
+      // One recipe that cannot act must not cancel the others, and must not pass silently either:
+      // record why and keep going, so a run over many diagnostics still reports every outcome.
+      try {
+        changed.push(...(await applyDiagnosticRecipe(ctx.cwd, diagnostic)))
+      } catch (error) {
+        failed.push({
+          code: diagnostic.code,
+          reason: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
     const final = await collectCheckResult(ctx.cwd, {
       lintsOnly: true,
       ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
@@ -1397,6 +1484,7 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
       ok: final.ok,
       changed,
       failed,
+      skipped,
       diagnostics: final.structuredDiagnostics ?? final.diagnostics,
     }
   },
@@ -1404,6 +1492,7 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
     out.ok ? "✓ fixes applied" : "✖ unresolved diagnostics remain",
     ...out.changed.map((file) => `  changed ${file}`),
     ...out.failed.map((f) => `  could not fix ${f.code}: ${f.reason}`),
+    ...out.skipped.map((s) => `  needs review ${s.code}: ${s.reason}`),
     ...out.diagnostics.map((d) => `  ${String((d as { code?: unknown }).code ?? "diagnostic")}`),
   ],
   success: (out) => out.ok,
@@ -1430,6 +1519,9 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
       splits: { type: "array" },
       moves: { type: "array" },
       rewritten: { type: "array" },
+      tooling: { type: "array" },
+      followUps: { type: "array" },
+      mode: { type: "string" },
     },
     required: ["ok", "write", "issues"],
   }),
@@ -1441,6 +1533,7 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
       { name: "from", field: "from", type: "string" },
       { name: "to", field: "to", type: "string" },
       { name: "write", field: "write", type: "boolean" },
+      { name: "zones", field: "zones", type: "boolean" },
       { name: "json", field: "json", type: "boolean" },
       { name: "dir", field: "dir", type: "string" },
     ],
@@ -1450,7 +1543,8 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
     const write = value.write === undefined ? {} : { write: value.write }
     if (value.kind === "layout") {
       const { migrateLayout } = await import("./migrate-layout.ts")
-      return { kind: "layout" as const, ...(await migrateLayout(dir, write)) }
+      const options = { ...write, zones: value.zones === true }
+      return { kind: "layout" as const, ...(await migrateLayout(dir, options)) }
     }
     const { migrateTailwindToStylex } = await import("./stylex-migrate.ts")
     return migrateTailwindToStylex(dir, write)
@@ -1459,14 +1553,25 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
     if (out.kind === "layout") {
       return [
         out.ok
-          ? `✓ ${out.splits.length} route file${out.splits.length === 1 ? "" : "s"} split, ${out.moves.length} file${out.moves.length === 1 ? "" : "s"} moved`
+          ? `✓ ${out.mode === "api" ? "API-only app" : `${out.splits.length} route file${out.splits.length === 1 ? "" : "s"} split`}, ${out.moves.length} file${out.moves.length === 1 ? "" : "s"} moved`
           : `⚠ ${out.issues.length} issue${out.issues.length === 1 ? "" : "s"} need a decision; everything else is planned`,
         ...out.splits.map(
-          (split) => `  split ${split.file} → ${split.backend} (${split.moved.join(", ")})`,
+          (split) =>
+            `  split ${split.file} → ${split.backend} (${split.moved.join(", ")})${split.shared === undefined ? "" : `, shared data → ${split.shared}`}`,
         ),
         ...out.moves.map((move) => `  move  ${move.from} → ${move.to}`),
         ...out.rewritten.map((file) => `  edit  ${file} (imports)`),
+        ...out.tooling.map((edit) => `  edit  ${edit.file} (${edit.change})`),
+        ...out.schemas
+          .filter((entry) => entry.reason === undefined)
+          .map(
+            (entry) =>
+              `  draft ${entry.file} ${entry.schema} - review what it lets the browser see${entry.omitted === undefined ? "" : `; leaves out ${entry.omitted.join(", ")}`}${entry.open === undefined ? "" : `; admits any value at ${entry.open.join(", ")}, typed any or unknown`}`,
+          ),
         ...out.issues.map((issue) => `  ⚠ ${issue.file}: ${issue.reason}`),
+        ...out.followUps.map(
+          (step) => `  next  ${step.file}: ${step.reason} - \`${step.command}\``,
+        ),
         ...(out.write ? [] : ["  dry run: pass --write to apply"]),
       ]
     }
@@ -1586,6 +1691,90 @@ const typesSpec: CommandSpec<TypesInput, RouteTypesReport> = {
   success: (out) => out.ok,
 }
 
+const SCHEMA_STATUS_LINE: Readonly<Record<OutputSchemaStatus, string>> = {
+  missing: "+ would write",
+  generated: "+ wrote",
+  stale: "↻ stale",
+  regenerated: "↻ rewrote",
+  current: "✓ current",
+  declared: "· hand-written",
+  "no-data": "· no data",
+  unreadable: "⚠ unreadable",
+}
+
+const schemasSpec: CommandSpec<SchemasInput, OutputSchemasReport> = {
+  name: "schemas",
+  summary:
+    "Write a reviewable `loaderOutput`/`actionOutput` from the loader's or action's return type where a route has none (`--write`), keep generated ones current, and list returned fields a hand-written schema drops.",
+  input: SCHEMAS_SCHEMA,
+  output: output({
+    type: "object",
+    properties: {
+      ok: { type: "boolean" },
+      write: { type: "boolean" },
+      entries: { type: "array" },
+      written: { type: "array" },
+      warnings: { type: "array" },
+    },
+    required: ["ok", "write", "entries", "written", "warnings"],
+  }),
+  transports: ["cli"],
+  stability: "stable",
+  argv: {
+    flags: [
+      { name: "write", field: "write", type: "boolean" },
+      { name: "check", field: "check", type: "boolean" },
+      { name: "json", field: "json", type: "boolean" },
+      { name: "dir", field: "dir", type: "string" },
+    ],
+  },
+  async run(value, ctx) {
+    const { outputSchemas } = await import("./output-schemas.ts")
+    return outputSchemas(resolve(ctx.cwd, value.dir ?? "."), {
+      write: value.write === true,
+      check: value.check === true,
+    })
+  },
+  render: (out) => {
+    const shown = out.entries.filter(
+      (entry) =>
+        (entry.status !== "current" || entry.open !== undefined) &&
+        entry.status !== "no-data" &&
+        (entry.status !== "declared" || entry.dropped.length > 0),
+    )
+    const current = out.entries.filter((entry) => entry.status === "current").length
+    return [
+      ...out.warnings.map((warning) => `⚠ ${warning}`),
+      `${out.ok ? "✓" : "✖"} ${out.entries.length} output schema${out.entries.length === 1 ? "" : "s"} read, ${current} generated and current`,
+      ...shown.map((entry) => {
+        const detail =
+          entry.reason ??
+          (entry.edited === true
+            ? "edited by hand under its nifra:generated line"
+            : entry.dropped.length > 0
+              ? `drops ${entry.dropped.join(", ")}`
+              : entry.omitted !== undefined
+                ? `leaves out ${entry.omitted.join(", ")}`
+                : undefined)
+        const open =
+          entry.open === undefined
+            ? []
+            : [
+                `      admits any value at ${entry.open.join(", ")}: the type there is any or unknown, so the output guard drops nothing below it`,
+              ]
+        return [
+          `  ${SCHEMA_STATUS_LINE[entry.status]} ${entry.file}:${entry.line} ${entry.schema}${detail === undefined ? "" : ` - ${detail}`}`,
+          ...open,
+        ].join("\n")
+      }),
+      ...(out.write || !out.entries.some((e) => e.status === "missing" || e.status === "stale")
+        ? []
+        : ["  dry run: pass --write to apply"]),
+    ]
+  },
+  success: (out) => out.ok,
+}
+
 const snapshotSpec: CommandSpec<SnapshotInput, SnapshotCommandOutput> = {
   name: "snapshot",
   summary: "Write the backend API contract as a versioned JSON baseline.",
@@ -1610,18 +1799,16 @@ const snapshotSpec: CommandSpec<SnapshotInput, SnapshotCommandOutput> = {
   },
   async run(value, ctx) {
     const mod = await import("./diff-tool.ts")
-    const routes = await mod.snapshotBackend(ctx.cwd)
     const file = value.out ?? mod.DEFAULT_SNAPSHOT_FILE
-    const snapshot = { nifraSnapshot: 1 as const, routes }
-    await Bun.write(resolve(ctx.cwd, file), `${JSON.stringify(snapshot, null, 2)}\n`)
-    return { ok: true, file, routes: routes.length, snapshot }
+    const snapshot = await mod.writeSnapshot(ctx.cwd, file)
+    return { ok: true, file, routes: snapshot.routes.length, snapshot }
   },
   render: (out) => [
     `[nifra] wrote ${out.routes} route${out.routes === 1 ? "" : "s"} to ${out.file}`,
   ],
 }
 
-const diffSpec: CommandSpec<DiffInput, DiffCommandOutput> = {
+const diffSpec: CommandSpec<DiffInput, RouteDiffCommandOutput> = {
   name: "diff",
   summary: "Compare the current backend contract with a baseline and fail on breaking changes.",
   input: DIFF_SCHEMA,
@@ -1638,21 +1825,17 @@ const diffSpec: CommandSpec<DiffInput, DiffCommandOutput> = {
   stability: "stable",
   argv: { positionals: ["baseline"], flags: [{ name: "json", field: "json", type: "boolean" }] },
   async run(value, ctx) {
-    const mod = await import("./diff-tool.ts")
-    const baseline = value.baseline ?? mod.DEFAULT_SNAPSHOT_FILE
-    const file = await Bun.file(resolve(ctx.cwd, baseline)).text()
-    const before = mod.parseSnapshotFile(file, baseline)
-    const current = await mod.snapshotBackend(ctx.cwd)
-    const { diffRouteSnapshots } = await import("@nifrajs/core/diff")
-    const diff = diffRouteSnapshots(before.routes, current)
-    return { ok: !diff.hasBreaking, hasBreaking: diff.hasBreaking, changes: diff.changes }
+    const { diffAgainstBaseline, formatDiff } = await import("./diff-tool.ts")
+    const diff = await diffAgainstBaseline(ctx.cwd, value.baseline)
+    return {
+      ok: !diff.hasBreaking,
+      hasBreaking: diff.hasBreaking,
+      changes: diff.changes,
+      text: formatDiff(diff),
+    }
   },
-  render: (out) => [
-    out.ok ? "✓ no breaking changes" : "✖ breaking changes",
-    ...(out.changes as readonly { method: string; path: string; message: string }[]).map(
-      (c) => `${c.method} ${c.path}: ${c.message}`,
-    ),
-  ],
+  render: (out) => [out.text],
+  json: ({ ok, hasBreaking, changes }) => ({ ok, hasBreaking, changes }),
   success: (out) => out.ok,
 }
 
@@ -1880,6 +2063,7 @@ export const commandSpecs = Object.freeze([
   migrateSpec,
   targetSpec,
   typesSpec,
+  schemasSpec,
   snapshotSpec,
   diffSpec,
   contractsSpec,
@@ -1891,6 +2075,7 @@ export const commandSpecs = Object.freeze([
   portSpec,
   i18nSpec,
   errorsSpec,
+  explainSpec,
   logsSpec,
   cdnCheckSpec,
   dbSchemaSpec,

package/src/component-check.ts

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import {
+  isUnsupportedTypeScriptError,
+  type UnsupportedTypeScriptError,
+} from "./internal/typescript-import.ts"
+import type { SourceIndex } from "./rules/index.ts"
+
+type ComponentSource = typeof import("@nifrajs/web/server-components/source")
+
+export interface ComponentCheck {
+  readonly receipts: ReadonlySet<string>
+  /** Set when the project's TypeScript has no compiler API to read component modules with
+   * (TypeScript 7): no module gets a receipt, so the ordinary import rule judges each one. */
+  readonly unsupported: UnsupportedTypeScriptError | undefined
+}
+
+const COMPONENT_SERVER = /\.component\.server\.[cm]?[jt]sx?$/
+
+/** A source-only proof. nifra check never executes nifra.config.ts. */
+export async function componentCheckReceipts(
+  root: string,
+  source: SourceIndex,
+  load: () => Promise<ComponentSource> = () => import("@nifrajs/web/server-components/source"),
+): Promise<ComponentCheck> {
+  const receipts = new Set<string>()
+  const result: ComponentCheck = { receipts, unsupported: undefined }
+  if (!source.files.some((file) => COMPONENT_SERVER.test(file))) return result
+  const configFile = ["nifra.config.ts", "backend/framework.ts"].find((file) =>
+    existsSync(resolve(root, file)),
+  )
+  if (configFile === undefined) return result
+  let components: ComponentSource
+  try {
+    components = await load()
+  } catch (error) {
+    if (isUnsupportedTypeScriptError(error)) return { receipts, unsupported: error }
+    throw error
+  }
+  const pipeline = components.staticComponentPipeline(
+    readFileSync(resolve(root, configFile), "utf8"),
+    configFile,
+  )
+  if (typeof pipeline !== "object" || pipeline === null || Array.isArray(pipeline)) return result
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Static receipt inspection checks object shape before reading fields; the source scanner never executes configuration.
+  const options = pipeline as Record<string, unknown>
+  if (
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Static receipt inspection checks object shape before reading fields; the source scanner never executes configuration.
+    !["react", "vue", "svelte", "solid", "preact"].includes(options.adapter as string) ||
+    typeof options.entries !== "object" ||
+    options.entries === null ||
+    Array.isArray(options.entries)
+  )
+    return result
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Static receipt inspection checks object shape before reading fields; the source scanner never executes configuration.
+  const entries = options.entries as Record<string, unknown>
+  if (
+    typeof entries.client !== "string" ||
+    typeof entries.ssr !== "string" ||
+    (options.adapter === "react" && typeof entries.rsc !== "string") ||
+    Object.values(entries).some(
+      (file) => typeof file !== "string" || !existsSync(resolve(root, file)),
+    )
+  )
+    return result
+  for (const file of source.files) {
+    if (!COMPONENT_SERVER.test(file)) continue
+    const content = source.read(file)
+    if (content === undefined) continue
+    try {
+      components.compileComponentModule(content, resolve(root, file), root, "client")
+      receipts.add(file)
+      receipts.add(resolve(root, file))
+    } catch {
+      /* A module without a compilation receipt remains forbidden by the ordinary import rule. */
+    }
+  }
+  return result
+}

package/src/contract-proof.ts

@@ -1,14 +1,12 @@
-import { existsSync, realpathSync } from "node:fs"
-import { resolve, sep } from "node:path"
 import type { AssuranceFinding, AssuranceReport, AssuredRoute } from "@nifrajs/core/assurance"
 import type {
   AssuredCapabilityRoute,
   CapabilityAssuranceReport,
   CapabilityFinding,
 } from "@nifrajs/core/capabilities"
-import { diffRouteSnapshots, type RouteChange, type RoutesDiff } from "@nifrajs/core/diff"
+import type { RouteChange, RoutesDiff } from "@nifrajs/core/diff"
 import type { CheckResult } from "./check.ts"
-import { DEFAULT_SNAPSHOT_FILE, parseSnapshotFile, snapshotBackend } from "./diff-tool.ts"
+import { DEFAULT_SNAPSHOT_FILE, diffAgainstBaseline } from "./diff-tool.ts"
 import { collectProjectVerification } from "./verification.ts"
 
 const routeKey = (method: string, path: string): string => `${method.toUpperCase()}\n${path}`
@@ -59,15 +57,6 @@ export interface ContractProofOptions {
   readonly signal?: AbortSignal
 }
 
-function safeBaselinePath(cwd: string, baselinePath: string): string {
-  const root = resolve(cwd)
-  const target = resolve(root, baselinePath)
-  if (target !== root && !target.startsWith(`${root}${sep}`)) {
-    throw new Error("contract proof baseline must stay inside the project directory")
-  }
-  return target
-}
-
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
@@ -144,18 +133,7 @@ export async function collectContractProof(
   options: ContractProofOptions = {},
 ): Promise<ContractProofReport> {
   const baselinePath = options.baselinePath ?? DEFAULT_SNAPSHOT_FILE
-  const resolvedBaseline = safeBaselinePath(cwd, baselinePath)
-  if (!existsSync(resolvedBaseline)) {
-    throw new Error(`contract proof baseline not found: ${resolvedBaseline}`)
-  }
-  const realRoot = realpathSync(resolve(cwd))
-  const realBaseline = realpathSync(resolvedBaseline)
-  if (realBaseline !== realRoot && !realBaseline.startsWith(`${realRoot}${sep}`)) {
-    throw new Error("contract proof baseline must stay inside the project directory")
-  }
-  const baseline = parseSnapshotFile(await Bun.file(resolvedBaseline).text(), baselinePath)
-  const current = await snapshotBackend(cwd)
-  const diff = diffRouteSnapshots(baseline.routes, current)
+  const diff = await diffAgainstBaseline(cwd, baselinePath, { contain: true })
   const verification = await collectProjectVerification(cwd, {
     ...(options.signal === undefined ? {} : { signal: options.signal }),
   })