@nifrajs/cli 4.0.0 → 5.0.0

package/src/command-catalog.ts

@@ -22,15 +22,22 @@ import { type Diagnostic, diagnostic, normalizeSeverity, toSarifLog } from "./di
 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"
 import type { RouteTypesReport } from "./route-types.ts"
 import type { SmokeReport } from "./smoke.ts"
 import type { StylexMigrationResult } from "./stylex-migrate.ts"
+import {
+  renderSyncManifestResults,
+  type SyncManifestResult,
+  syncManifestsOk,
+  syncServerManifests,
+} from "./sync-manifest.ts"
 import {
   collectProjectWorkGraph,
   type ProjectWorkGraphResult,
@@ -74,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> {
@@ -322,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
 }
@@ -384,6 +393,12 @@ interface TypesInput {
   readonly dir?: string | undefined
 }
 
+interface SchemasInput {
+  readonly write?: boolean | undefined
+  readonly json?: boolean | undefined
+  readonly dir?: string | undefined
+}
+
 interface SnapshotInput {
   readonly out?: string | undefined
   readonly json?: boolean | undefined
@@ -452,7 +467,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
 }
@@ -487,6 +502,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
@@ -498,6 +516,10 @@ interface SyncCommandOutput {
   readonly ok: true
   readonly results: readonly unknown[]
 }
+interface SyncManifestCommandOutput {
+  readonly ok: boolean
+  readonly results: readonly SyncManifestResult[]
+}
 
 interface SmokeCommandOutput extends SmokeReport {}
 
@@ -637,15 +659,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 }),
     }
@@ -771,6 +798,17 @@ const TYPES_SCHEMA = input<TypesInput>(
   },
 )
 
+const SCHEMAS_SCHEMA = input<SchemasInput>(
+  objectSchema({ write: { type: "boolean" }, json: { type: "boolean" }, dir: { type: "string" } }),
+  (value) => {
+    const raw = withDir(record(value))
+    return {
+      ...parseBooleanFlags(raw, ["write", "json"]),
+      ...(raw.dir === undefined ? {} : { dir: raw.dir }),
+    }
+  },
+)
+
 const SNAPSHOT_SCHEMA = input<SnapshotInput>(
   objectSchema({ out: { type: "string" }, json: { type: "boolean" }, dir: { type: "string" } }),
   (value) => {
@@ -934,9 +972,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[] {
@@ -1185,7 +1224,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",
@@ -1199,12 +1239,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"
       )
@@ -1254,7 +1329,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 }),
       }),
@@ -1282,10 +1357,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 {
@@ -1420,6 +1492,8 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
       splits: { type: "array" },
       moves: { type: "array" },
       rewritten: { type: "array" },
+      tooling: { type: "array" },
+      mode: { type: "string" },
     },
     required: ["ok", "write", "issues"],
   }),
@@ -1449,13 +1523,14 @@ 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(", ")})`,
         ),
         ...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.issues.map((issue) => `  ⚠ ${issue.file}: ${issue.reason}`),
         ...(out.write ? [] : ["  dry run: pass --write to apply"]),
       ]
@@ -1576,6 +1651,75 @@ 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: "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 })
+  },
+  render: (out) => {
+    const shown = out.entries.filter(
+      (entry) =>
+        entry.status !== "current" &&
+        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(", ")}`
+              : undefined)
+        return `  ${SCHEMA_STATUS_LINE[entry.status]} ${entry.file}:${entry.line} ${entry.schema}${detail === undefined ? "" : ` - ${detail}`}`
+      }),
+      ...(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.",
@@ -1600,18 +1744,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,
@@ -1628,21 +1770,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,
 }
 
@@ -1674,7 +1812,7 @@ const contractsSpec: CommandSpec<ContractsInput, ContractsCommandOutput> = {
   success: (out) => out.ok,
 }
 
-const syncManifestSpec: CommandSpec<SyncInput, SyncCommandOutput> = {
+const syncManifestSpec: CommandSpec<SyncInput, SyncManifestCommandOutput> = {
   name: "sync-manifest",
   summary: "Regenerate generated server-manifest route tables without a full build.",
   input: SYNC_SCHEMA,
@@ -1687,16 +1825,11 @@ const syncManifestSpec: CommandSpec<SyncInput, SyncCommandOutput> = {
   stability: "stable",
   argv: { flags: [{ name: "json", field: "json", type: "boolean" }] },
   async run(_value, ctx) {
-    return {
-      ok: true,
-      results: await (await import("./sync-manifest.ts")).syncServerManifests(ctx.cwd),
-    }
+    const results = await syncServerManifests(ctx.cwd)
+    return { ok: syncManifestsOk(results), results }
   },
-  render: (out) => [
-    out.results.length === 0
-      ? "nifra sync-manifest: no generated server-manifest.ts found under this directory."
-      : `✓ checked ${out.results.length} generated server manifest${out.results.length === 1 ? "" : "s"}`,
-  ],
+  render: (out) => renderSyncManifestResults(out.results),
+  success: (out) => out.ok,
 }
 
 const syncRoutesSpec: CommandSpec<SyncInput, SyncCommandOutput> = {
@@ -1875,6 +2008,7 @@ export const commandSpecs = Object.freeze([
   migrateSpec,
   targetSpec,
   typesSpec,
+  schemasSpec,
   snapshotSpec,
   diffSpec,
   contractsSpec,

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 }),
   })

package/src/contracts.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
+import { NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
 import {
   type ProjectEvidenceSnapshot,
   reflectedRoutesFromEvidence,
@@ -16,9 +17,18 @@ export interface ContractDigest {
 
 export interface ContractsLock {
   readonly version: 1
+  /** The {@link CONTRACT_DIGEST_FORMAT} that produced `routes`. Absent in a lock written before it was recorded. */
+  readonly digest?: number
   readonly routes: Readonly<Record<string, ContractDigest>>
 }
 
+/**
+ * Bumped whenever {@link digestRoute} hashes the same schema differently. The lock records it, so a
+ * format change reads as "re-snapshot" instead of as drift on every route. 2: properties named like
+ * annotation keywords are hashed (4.0.1).
+ */
+export const CONTRACT_DIGEST_FORMAT = 2
+
 export const DEFAULT_CONTRACTS_LOCK = "contracts.lock.json"
 const DIGEST = /^[a-f0-9]{64}$/
 
@@ -146,6 +156,7 @@ export async function buildContractsLock(
   )
   return {
     version: 1,
+    digest: CONTRACT_DIGEST_FORMAT,
     routes: Object.fromEntries(Object.entries(routes).sort(([a], [b]) => codeUnitOrder(a, b))),
   }
 }
@@ -160,6 +171,27 @@ async function loadBackend(cwd: string): Promise<unknown> {
   return loaded.backend
 }
 
+const INPUT_PARTS = ["body", "query", "headers", "cookies", "params"] as const
+
+/**
+ * A route that in-process auth guards, but through a hook that runs after its declared input is
+ * validated: an unauthenticated caller reaches the body parser and reads the validation issues.
+ * Gateway auth (declared provenance) never lets that caller in, and an explicit `validationOrder`
+ * is the author's choice.
+ */
+export function validatesBeforeAuthentication(route: ReflectedRoute): boolean {
+  const schema = route.schema
+  if (schema === undefined || schema.validationOrder !== undefined) return false
+  if (!INPUT_PARTS.some((part) => schema[part] !== undefined)) return false
+  const auth = (route.assurance ?? []).filter(
+    (evidence) =>
+      evidence.id === NIFRA_ASSURANCE.AUTHENTICATED &&
+      (evidence.provenance ?? (evidence.source === "declared" ? "declared" : "runtime")) ===
+        "runtime",
+  )
+  return auth.length > 0 && auth.every((evidence) => evidence.source !== "nifra.authenticate")
+}
+
 export async function snapshotContracts(
   cwd: string,
   out = DEFAULT_CONTRACTS_LOCK,
@@ -176,6 +208,9 @@ export function parseContractsLock(value: unknown): ContractsLock {
   const routesRecord = recordOf(routesValue)
   if (record.version !== 1 || routesRecord === undefined)
     throw new TypeError("contracts lock must have version 1 and routes")
+  const digest = record.digest
+  if (digest !== undefined && !(Number.isSafeInteger(digest) && Number(digest) > 0))
+    throw new TypeError("contracts lock digest must be a positive integer")
   const routes: Record<string, ContractDigest> = {}
   for (const [key, raw] of Object.entries(routesRecord)) {
     const item = recordOf(raw)
@@ -192,7 +227,7 @@ export function parseContractsLock(value: unknown): ContractsLock {
       throw new TypeError(`invalid contract ${key}`)
     routes[key] = { request, response }
   }
-  return { version: 1, routes }
+  return typeof digest === "number" ? { version: 1, digest, routes } : { version: 1, routes }
 }
 
 export async function checkContractsLock(
@@ -202,13 +237,30 @@ export async function checkContractsLock(
   present: boolean
   vacuous: boolean
   diagnostics: Array<{ route?: string; message: string }>
+  /** `METHOD /path` of every route the backend serves, read when the lock made the check load it. */
+  served?: readonly string[]
+  /** `METHOD /path` of each route {@link validatesBeforeAuthentication} names, read alongside `served`. */
+  inputBeforeAuth?: readonly string[]
 }> {
   const path = resolve(cwd, file)
   if (!existsSync(path)) return { present: false, vacuous: false, diagnostics: [] }
   const parsed = parseContractsLock(JSON.parse(await Bun.file(path).text()))
-  const current = await buildContractsLock(await loadBackend(cwd))
+  const evidence = snapshotProjectEvidence(await loadBackend(cwd))
+  const current = await buildContractsLock(undefined, evidence)
   const vacuous = await isVacuousLock(current)
+  const served = Object.keys(current.routes)
+  const inputBeforeAuth = reflectedRoutesFromEvidence(evidence)
+    .filter(validatesBeforeAuthentication)
+    .map((route) => `${route.method} ${route.path}`)
   const diagnostics: Array<{ route?: string; message: string }> = []
+  // Digests of two formats never compare, so this still fails; it just names the real cause.
+  if (parsed.digest !== undefined && parsed.digest !== CONTRACT_DIGEST_FORMAT) {
+    const newer = parsed.digest > CONTRACT_DIGEST_FORMAT
+    diagnostics.push({
+      message: `${file} was written with contract digest format ${parsed.digest}, but this nifra computes format ${CONTRACT_DIGEST_FORMAT}${newer ? " (a newer @nifrajs/cli wrote it; upgrade this one)" : ""}, so no route could be compared. Review the route schema changes since the lock was written, then run \`nifra contracts snapshot\` and commit the lock.`,
+    })
+    return { present: true, vacuous, diagnostics, served, inputBeforeAuth }
+  }
   const keys = new Set([...Object.keys(parsed.routes), ...Object.keys(current.routes)])
   for (const key of [...keys].sort()) {
     const before = parsed.routes[key]
@@ -225,5 +277,10 @@ export async function checkContractsLock(
       })
     }
   }
-  return { present: true, vacuous, diagnostics }
+  if (diagnostics.length > 0 && parsed.digest === undefined) {
+    diagnostics.push({
+      message: `${file} records no contract digest format. A lock written before nifra 4.0.1 hashed schemas differently, so a route reported above may not have changed. Review them, then run \`nifra contracts snapshot\` to record the format.`,
+    })
+  }
+  return { present: true, vacuous, diagnostics, served, inputBeforeAuth }
 }