@nifrajs/cli 2.11.0 → 2.12.0

package/src/assure.ts

@@ -1,9 +1,59 @@
 /** `nifra assure` - evaluate a project's reflected routes against `nifra.assurance.ts`. */
 
 import { existsSync } from "node:fs"
-import { resolve } from "node:path"
+import { join, resolve } from "node:path"
 import { pathToFileURL } from "node:url"
 import type { AssuranceConfig, AssuranceReport } from "@nifrajs/core/assurance"
+import type { Diagnostic } from "./diagnostics.ts"
+
+export interface AssureSink {
+  record(bundle: AssureBundle): Promise<void>
+}
+
+export interface GateResult {
+  readonly gate:
+    | "check"
+    | "doctor"
+    | "render"
+    | "hydration"
+    | "contracts"
+    | "size"
+    | "tests"
+    | string
+  readonly status: "pass" | "fail" | "skip"
+  readonly skipReason?: string
+  readonly durationMs: number
+  readonly diagnostics: readonly Diagnostic[]
+  readonly replay?: string
+}
+
+export interface AssureBundle {
+  readonly version: 1
+  readonly createdAt: string
+  readonly commit: string
+  readonly gates: readonly GateResult[]
+  readonly verdict: "green" | "red"
+}
+
+export interface MemoryAssureSink extends AssureSink {
+  readonly bundles: readonly AssureBundle[]
+  clear(): void
+}
+
+export function createMemoryAssureSink(): MemoryAssureSink {
+  const bundles: AssureBundle[] = []
+  return {
+    record: async (bundle) => {
+      bundles.push(bundle)
+    },
+    get bundles() {
+      return Object.freeze([...bundles])
+    },
+    clear: () => {
+      bundles.length = 0
+    },
+  }
+}
 
 export const DEFAULT_ASSURANCE_CONFIG = "nifra.assurance.ts"
 
@@ -77,11 +127,275 @@ export async function collectAssuranceReport(
 
 export async function runAssurance(
   cwd: string,
-  options: { readonly json?: boolean; readonly config?: string } = {},
+  options: {
+    readonly json?: boolean
+    readonly config?: string
+    readonly bundle?: boolean
+    readonly strict?: boolean
+    readonly out?: string
+    readonly hydration?: boolean
+    readonly interact?: boolean
+  } = {},
 ): Promise<boolean> {
+  if (options.bundle === true) {
+    const bundle = await collectAssureBundle(cwd, options)
+    const serialized = JSON.stringify(bundle, null, 2)
+    if (options.out !== undefined) await Bun.write(resolve(cwd, options.out), `${serialized}\n`)
+    else console.log(serialized)
+    return bundle.verdict === "green"
+  }
   const report = await collectAssuranceReport(cwd, options.config)
   console.log(
     options.json === true ? JSON.stringify(report, null, 2) : formatAssuranceReport(report),
   )
   return report.ok
 }
+
+function elapsed(start: number): number {
+  return Math.max(0, Math.round(performance.now() - start))
+}
+
+async function gitCommit(cwd: string): Promise<string> {
+  try {
+    const proc = Bun.spawn(["git", "rev-parse", "HEAD"], { cwd, stdout: "pipe", stderr: "ignore" })
+    const text = (await new Response(proc.stdout).text()).trim()
+    await proc.exited
+    return text || "unknown"
+  } catch {
+    return "unknown"
+  }
+}
+
+function diagnosticFromMessage(
+  code: string,
+  message: string,
+  severity: "error" | "warn" | "info" = "error",
+): Diagnostic {
+  return Object.freeze({ code, severity, message })
+}
+
+function statusFor(diagnostics: readonly Diagnostic[], strict: boolean): "pass" | "fail" {
+  return diagnostics.some(
+    (item) => item.severity === "error" || (strict && item.severity === "warn"),
+  )
+    ? "fail"
+    : "pass"
+}
+
+export async function collectAssureBundle(
+  cwd: string,
+  options: {
+    readonly config?: string
+    readonly strict?: boolean
+    readonly hydration?: boolean
+    readonly interact?: boolean
+  } = {},
+): Promise<AssureBundle> {
+  const strict = options.strict === true
+  const gates: GateResult[] = []
+  let assuranceConfig: AssuranceConfig | undefined
+  let assuranceConfigError: unknown
+  try {
+    assuranceConfig = await loadAssuranceConfig(cwd, options.config)
+  } catch (error) {
+    assuranceConfigError = error
+  }
+  const addGate = async (
+    gate: GateResult["gate"],
+    run: () => Promise<{ diagnostics: Diagnostic[]; skipReason?: string; replay?: string }>,
+  ): Promise<void> => {
+    const start = performance.now()
+    try {
+      const result = await run()
+      gates.push({
+        gate,
+        status: result.skipReason === undefined ? statusFor(result.diagnostics, strict) : "skip",
+        ...(result.skipReason === undefined ? {} : { skipReason: result.skipReason }),
+        durationMs: elapsed(start),
+        diagnostics: Object.freeze(result.diagnostics),
+        ...(result.replay === undefined ? {} : { replay: result.replay }),
+      })
+    } catch (error) {
+      gates.push({
+        gate,
+        status: "fail",
+        durationMs: elapsed(start),
+        diagnostics: [
+          diagnosticFromMessage(
+            gate === "contracts" ? "NF-K001" : gate === "hydration" ? "NF-H001" : "NF-A001",
+            error instanceof Error ? error.message : String(error),
+          ),
+        ],
+      })
+    }
+  }
+
+  await addGate("check", async () => {
+    const { collectProjectVerification } = await import("./verification.ts")
+    const verification = await collectProjectVerification(cwd, {
+      ...(options.config !== undefined ? { config: options.config } : {}),
+      preloaded:
+        assuranceConfig !== undefined
+          ? { config: assuranceConfig }
+          : { error: assuranceConfigError },
+    })
+    const result = await verification.check()
+    const diagnostics = (result.structuredDiagnostics ?? []).map((item) => item)
+    return { diagnostics }
+  })
+
+  await addGate("doctor", async () => {
+    const { collectDoctorResult } = await import("./doctor.ts")
+    const result = await collectDoctorResult(cwd)
+    const diagnostics: Diagnostic[] = []
+    for (const finding of result.findings) {
+      diagnostics.push(
+        diagnosticFromMessage(
+          "NF-D001",
+          `imports ${finding.package} which is not declared`,
+          "error",
+        ),
+      )
+    }
+    for (const finding of result.duplicateInstalls) {
+      diagnostics.push(
+        diagnosticFromMessage("NF-D001", `${finding.package} resolves to duplicate installs`),
+      )
+    }
+    return { diagnostics }
+  })
+
+  await addGate("contracts", async () => {
+    const { checkContractsLock } = await import("./contracts.ts")
+    const path = resolve(cwd, "contracts.lock.json")
+    if (!existsSync(path)) return { diagnostics: [], skipReason: "no contract lock configured" }
+    const result = await checkContractsLock(cwd)
+    return {
+      diagnostics: result.diagnostics.map((item) =>
+        diagnosticFromMessage("NF-K001", item.message, "error"),
+      ),
+    }
+  })
+
+  await addGate("render", async () => {
+    if (!existsSync(join(cwd, "nifra.config.ts")) && !existsSync(join(cwd, "framework.ts")))
+      return { diagnostics: [], skipReason: "no client render target configured" }
+    const { renderPages } = await import("./mcp-render.ts")
+    const result = await renderPages(cwd, [{ path: "/" }])
+    if ("error" in result)
+      return {
+        diagnostics: [diagnosticFromMessage("NF-A001", "SSR render gate failed", "error")],
+      }
+    const pages = Array.isArray(result.results) ? result.results : []
+    const failure = pages.find(
+      (page): page is { status?: unknown } =>
+        typeof page === "object" &&
+        page !== null &&
+        Number((page as { status?: unknown }).status) >= 500,
+    )
+    return failure === undefined
+      ? { diagnostics: [] }
+      : { diagnostics: [diagnosticFromMessage("NF-A001", "SSR render returned a server error")] }
+  })
+  await addGate("size", async () => {
+    const budget = assuranceConfig?.size
+    if (
+      budget === undefined ||
+      (budget.maxBytes === undefined && budget.maxGzipBytes === undefined)
+    )
+      return { diagnostics: [], skipReason: "no size budget configured" }
+    const outDir = resolve(cwd, budget.outDir ?? "dist")
+    if (!existsSync(outDir))
+      return {
+        diagnostics: [diagnosticFromMessage("NF-A001", "size gate output directory is missing")],
+      }
+    const files: string[] = []
+    for await (const file of new Bun.Glob("**/*").scan({ cwd: outDir, onlyFiles: true }))
+      files.push(join(outDir, file))
+    let bytes = 0
+    let gzipBytes = 0
+    for (const file of files) {
+      const data = await Bun.file(file).bytes()
+      bytes += data.byteLength
+      gzipBytes += Bun.gzipSync(data).byteLength
+    }
+    const overRaw = budget.maxBytes !== undefined && bytes > budget.maxBytes
+    const overGzip = budget.maxGzipBytes !== undefined && gzipBytes > budget.maxGzipBytes
+    return {
+      diagnostics:
+        overRaw || overGzip
+          ? [
+              diagnosticFromMessage(
+                "NF-A001",
+                `output exceeds configured size budget (${bytes} bytes, ${gzipBytes} gzip bytes)`,
+              ),
+            ]
+          : [],
+    }
+  })
+  if (options.hydration === true) {
+    await addGate("hydration", async () => {
+      const { runHydrationAssurance } = await import("./assure-hydration.ts")
+      const result = await runHydrationAssurance(cwd, { interact: options.interact === true })
+      return {
+        diagnostics: [...result.diagnostics],
+        ...(result.skipReason === undefined ? {} : { skipReason: result.skipReason }),
+        ...(result.replays?.[0] === undefined ? {} : { replay: result.replays[0] }),
+      }
+    })
+  } else {
+    await addGate("hydration", async () => ({
+      diagnostics: [],
+      skipReason: "pass --hydration to run the hydration gate",
+    }))
+  }
+  const workloads = assuranceConfig?.idempotency ?? []
+  const testGateStart = performance.now()
+  if (workloads.length === 0) {
+    gates.push({
+      gate: "tests",
+      status: "skip",
+      skipReason: "no idempotency workloads configured",
+      durationMs: elapsed(testGateStart),
+      diagnostics: [],
+    })
+  } else {
+    const { proveIdempotency } = await import("@nifrajs/testing")
+    const diagnostics: Diagnostic[] = []
+    for (const workload of workloads) {
+      const proof = await proveIdempotency({ run: workload.run })
+      for (const divergence of proof.divergences) {
+        diagnostics.push(
+          diagnosticFromMessage(
+            "NF-A001",
+            `${workload.name} diverged at step ${divergence.step} field ${divergence.field}`,
+            "error",
+          ),
+        )
+      }
+    }
+    gates.push({
+      gate: "tests",
+      status: statusFor(diagnostics, strict),
+      durationMs: elapsed(testGateStart),
+      diagnostics,
+    })
+  }
+  const bundle: AssureBundle = Object.freeze({
+    version: 1,
+    createdAt: new Date().toISOString(),
+    commit: await gitCommit(cwd),
+    gates: Object.freeze(gates),
+    verdict: gates.some((gate) => gate.status === "fail") ? "red" : "green",
+  })
+  const sink = assuranceConfig?.assureSink
+  if (
+    typeof sink === "object" &&
+    sink !== null &&
+    "record" in sink &&
+    typeof sink.record === "function"
+  ) {
+    await sink.record(bundle)
+  }
+  return bundle
+}

package/src/capabilities-tool.ts

@@ -48,6 +48,30 @@ function specifierMatches(pattern: string, specifier: string): boolean {
   return pattern.endsWith("/*") ? specifier.startsWith(pattern.slice(0, -1)) : specifier === pattern
 }
 
+const SPECIFIER_EXTENSION = /\.(?:[cm]?[jt]sx?)$/
+
+/** Reduce a specifier to the name a human would recognise: `./services/mail.ts` and `../mail/index.ts`
+ * both stem to `mail`, which is what makes a written-vs-actual mismatch suggestible. */
+function specifierStem(specifier: string): string {
+  const segments = specifier
+    .replace(SPECIFIER_EXTENSION, "")
+    .split("/")
+    .filter((segment) => segment !== "" && segment !== "." && segment !== "..")
+  const last = segments.at(-1)
+  if (last === undefined) return specifier
+  return last === "index" ? (segments.at(-2) ?? last) : last
+}
+
+const suggestionSuffix = (suggestions: readonly string[]): string =>
+  suggestions.length === 0 ? "" : ` - did you mean ${suggestions.map((s) => `"${s}"`).join(", ")}?`
+
+function nearestSpecifiers(pattern: string, candidates: Iterable<string>): string[] {
+  const stem = specifierStem(pattern.endsWith("/*") ? pattern.slice(0, -2) : pattern)
+  const near = new Set<string>()
+  for (const candidate of candidates) if (specifierStem(candidate) === stem) near.add(candidate)
+  return [...near].sort().slice(0, 3)
+}
+
 const routeKey = (method: string, path: string): string => `${method.toUpperCase()}\n${path}`
 
 export interface CapabilityImportViolation {
@@ -63,6 +87,20 @@ export interface CapabilityProjectReport {
   readonly report: CapabilityAssuranceReport
   readonly violations: readonly CapabilityImportViolation[]
   readonly truncations: readonly CapabilityProvenanceTruncation[]
+  readonly unmatchedSeams: readonly CapabilityUnmatchedSeam[]
+}
+
+/**
+ * A provenance rule that names something the project does not contain. Seam specifiers are matched
+ * as written, so `"./services/mail.ts"` against `import "./services/mail"` silently governs nothing -
+ * the effect stays invisible to assurance and every route using it still passes.
+ */
+export interface CapabilityUnmatchedSeam {
+  readonly kind: "import" | "route-module"
+  /** The specifier (import rule) or project-relative module path (routeModules entry) as written. */
+  readonly value: string
+  /** Closest specifiers/modules actually present, when one is recognisable. */
+  readonly suggestions: readonly string[]
 }
 
 export interface CapabilityProvenanceTruncation {
@@ -264,9 +302,40 @@ export async function collectCapabilityProjectReport(
     violations.push(...walked.violations)
     truncations.push(...walked.truncations)
   }
+
+  // A seam rule that matches nothing is a policy typo, not a passing project: the effect it was
+  // written to govern keeps executing, unwatched, and every route touching it still reports clean.
+  // Checked against every scanned source (not just route-reachable ones) so a seam used by a job or
+  // a script is not reported as missing.
+  const scannedSpecifiers = new Set<string>()
+  for (const content of sources.values())
+    for (const specifier of scanEffectImports(content)) scannedSpecifiers.add(specifier)
+  const unmatchedSeams: CapabilityUnmatchedSeam[] = []
+  for (const rule of policy.provenance.imports) {
+    if (rule.optional === true) continue
+    if ([...scannedSpecifiers].some((specifier) => specifierMatches(rule.specifier, specifier)))
+      continue
+    unmatchedSeams.push({
+      kind: "import",
+      value: rule.specifier,
+      suggestions: Object.freeze(nearestSpecifiers(rule.specifier, scannedSpecifiers)),
+    })
+  }
+  for (const association of policy.provenance.routeModules ?? []) {
+    for (const module of association.modules) {
+      const normalized = module.replaceAll("\\", "/")
+      if (sources.has(normalized) || existsSync(join(cwd, normalized))) continue
+      unmatchedSeams.push({
+        kind: "route-module",
+        value: module,
+        suggestions: Object.freeze(nearestSpecifiers(module, sources.keys())),
+      })
+    }
+  }
+
   const evaluated = evaluateCapabilityAssurance(source, policy, { routes: evidenceRoutes })
   const report: CapabilityAssuranceReport =
-    violations.length === 0 && truncations.length === 0
+    violations.length === 0 && truncations.length === 0 && unmatchedSeams.length === 0
       ? evaluated
       : Object.freeze({
           ...evaluated,
@@ -285,12 +354,22 @@ export async function collectCapabilityProjectReport(
               path: truncation.path,
               message: `${truncation.method} ${truncation.path} capability provenance hit the ${truncation.reason === "depth-limit" ? "import-depth" : "module-count"} safety limit via ${truncation.chain.join(" → ")}; assurance cannot prove the remaining graph`,
             })),
+            ...unmatchedSeams.map((seam) => ({
+              code: "unmatched-provenance-seam" as const,
+              method: "*",
+              path: "*",
+              message:
+                seam.kind === "import"
+                  ? `capabilities.provenance.imports "${seam.value}" matched no import in this project, so the effect it declares is ungoverned - specifiers are compared exactly (or as a trailing /* prefix), not resolved${suggestionSuffix(seam.suggestions)}`
+                  : `capabilities.provenance.routeModules "${seam.value}" is not a file in this project, so the routes it associates stay uncovered${suggestionSuffix(seam.suggestions)}`,
+            })),
           ]),
         })
   return Object.freeze({
     report,
     violations: Object.freeze(violations),
     truncations: Object.freeze(truncations),
+    unmatchedSeams: Object.freeze(unmatchedSeams),
   })
 }