@nifrajs/cli 3.3.0 → 3.5.0

package/src/check-scan.ts

@@ -470,6 +470,42 @@ export function scanFetchText(
   return out
 }
 
+// `new EventSource(` / `new WebSocket(` - a hand-rolled subscription to this app's own streaming
+// surface. `new` is required so a local binding named `WebSocket` (a wrapper, a mock) stays quiet;
+// The word boundary excludes member calls and identifiers such as `renew WebSocket(`; `new` keeps
+// local wrapper bindings quiet while still matching the platform constructors.
+const STREAM_CONSTRUCT = /(?<![\w$])new\s+(?:EventSource|WebSocket)\s*\(/g
+
+/** Scan one file's text for hand-rolled own-API `EventSource`/`WebSocket` constructions. Pure +
+ * line-accurate. Same contract as {@link scanFetchText}: only a relative-path first argument
+ * (`"/…"` not `"//…"`, no scheme) is this app's API, so absolute `ws(s)://` / `http(s)://` URLs
+ * stay quiet exactly like absolute fetch URLs do. `externalMounts` and the relative-URL rule behave
+ * identically. A relative `new WebSocket("/…")` throws in browsers (the WS constructor needs an
+ * absolute URL), so a hit is either broken or bypassing `api.*.ws()` - either way the typed call
+ * (`api.*.subscribe()` for `app.sse()` routes, `api.*.ws()` for `app.ws()` routes) is the fix, and
+ * it keeps the compiler catching drift. */
+export function scanStreamText(
+  file: string,
+  content: string,
+  externalMounts: readonly string[] = [],
+): SourceFinding[] {
+  const out: SourceFinding[] = []
+  const lines = content.split("\n")
+  const code = codePositionMask(content)
+  STREAM_CONSTRUCT.lastIndex = 0
+  for (let m = STREAM_CONSTRUCT.exec(code); m !== null; m = STREAM_CONSTRUCT.exec(code)) {
+    const argument = firstArgumentIndex(content, m.index + m[0].length)
+    const quote = content[argument]
+    if (quote !== "'" && quote !== '"' && quote !== "`") continue
+    if (content[argument + 1] !== "/" || content[argument + 2] === "/") continue
+    if (externalMounts.length > 0 && matchesExternalMount(content, argument + 1, externalMounts))
+      continue
+    const line = lineAt(content, m.index)
+    out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() })
+  }
+  return out
+}
+
 /** Statically collect simple Nifra route registrations from source, without importing app code. */
 export function scanStaticRouteText(
   file: string,

package/src/check.ts

@@ -26,11 +26,13 @@ import {
   collectCheckDiagnostics,
   type RuleOverride,
 } from "./check-diagnostics.ts"
+import { checkContractsLock, DEFAULT_CONTRACTS_LOCK } from "./contracts.ts"
+import { type Diagnostic, normalizeSeverity, toSarifLog } from "./diagnostics.ts"
 import { createSourceFacts } from "./internal/source-facts.ts"
 import { importProjectTypeScript, type TypeScriptApi } from "./internal/typescript-import.ts"
 // Type-only: `pipeline-report.ts` imports this module's source scanners, so a value import here would
 // close a cycle. Doctor is what actually runs the collector (see the `pipeline` rule below).
-import type { ProjectFactsSeed } from "./project-facts.ts"
+import type { ContractCheckFacts, ProjectFactsSeed } from "./project-facts.ts"
 import { RULE_CODES } from "./rules/codes.ts"
 import { sourceIndex } from "./rules/index.ts"
 
@@ -59,6 +61,7 @@ import {
   scanResponseRoutes,
   scanServerManifestDrift,
   scanStaticRouteText,
+  scanStreamText,
   scanUntypedClient,
   type TransitiveServerImportFinding,
   walkSource,
@@ -230,10 +233,30 @@ interface CheckCollectionOptions {
 
 interface ProjectScan {
   readonly facts: ProjectFactsSeed
-  readonly typecheck: TypecheckResult
-  readonly sqlCompiler: TypeScriptApi | undefined
-  readonly checkConfigError?: string
-  readonly checkConfigWarnings: readonly string[]
+}
+
+async function collectContractFacts(cwd: string): Promise<ContractCheckFacts> {
+  const hasBackend = existsSync(join(cwd, "backend.ts"))
+  const hasLock = existsSync(join(cwd, DEFAULT_CONTRACTS_LOCK))
+  if (!hasBackend && !hasLock) return { present: false, vacuous: false, diagnostics: [] }
+  try {
+    const result = await checkContractsLock(cwd)
+    return {
+      present: result.present,
+      vacuous: result.vacuous,
+      diagnostics: result.diagnostics,
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message === "contract source not configured") {
+      return { present: false, vacuous: false, diagnostics: [] }
+    }
+    return {
+      present: hasLock,
+      vacuous: false,
+      diagnostics: [],
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
 }
 
 /** Build the rule input from one source walk and the other check-wide scans. */
@@ -242,6 +265,7 @@ async function buildProjectScan(
   opts: Pick<CheckCollectionOptions, "lintsOnly" | "signal" | "loadTypeScript">,
 ): Promise<ProjectScan> {
   const fetches: SourceFinding[] = []
+  const streams: SourceFinding[] = []
   const staticRoutes: StaticRouteFinding[] = []
   const untypedClients: SourceFinding[] = []
   const removedImports: SourceFinding[] = []
@@ -259,13 +283,14 @@ async function buildProjectScan(
   const sourceFacts = sqlCompiler === undefined ? undefined : createSourceFacts(sqlCompiler)
   const sqlImports = sqlCompiler === undefined ? undefined : createProjectSqlImports(cwd)
 
-  const [typecheckResult, _, doctor, manifestDrift] = await Promise.all([
+  const [typecheckResult, _, doctor, manifestDrift, contracts] = await Promise.all([
     opts.lintsOnly
       ? Promise.resolve<TypecheckResult>({ ran: false, ok: true, note: "lints-only mode" })
       : typecheck(cwd, opts.signal),
     walkSource(cwd, (rel, content) => {
       sourceFiles.push({ file: rel, content })
       fetches.push(...scanFetchText(rel, content, checkConfig.externalMounts))
+      streams.push(...scanStreamText(rel, content, checkConfig.externalMounts))
       staticRoutes.push(...scanStaticRouteText(rel, content, sourceFacts))
       untypedClients.push(...scanUntypedClient(rel, content))
       removedImports.push(...scanRemovedImports(rel, content))
@@ -276,6 +301,7 @@ async function buildProjectScan(
     }),
     import("./doctor.ts").then((m) => m.collectDoctorResult(cwd)),
     scanServerManifestDrift(cwd),
+    collectContractFacts(cwd),
   ])
 
   const resolveModule: ModuleResolver = (fromFile, specifier) => {
@@ -307,14 +333,24 @@ async function buildProjectScan(
     packages: { doctor, manifestDrift },
     ...(doctor.pipeline === undefined ? {} : { pipeline: doctor.pipeline }),
     policies: { checkConfig, rulePacks: [] },
-    sourceFindings: { fetches, untypedClients, removedImports, responseRoutes, interpolatedSql },
+    check: {
+      typecheck: typecheckResult,
+      sqlCompilerAvailable: sqlCompiler !== undefined,
+      ...(checkConfigError === undefined ? {} : { checkConfigError }),
+      checkConfigWarnings,
+      contracts,
+    },
+    sourceFindings: {
+      fetches,
+      streams,
+      untypedClients,
+      removedImports,
+      responseRoutes,
+      interpolatedSql,
+    },
   }
   return {
     facts,
-    typecheck: typecheckResult,
-    sqlCompiler,
-    ...(checkConfigError === undefined ? {} : { checkConfigError }),
-    checkConfigWarnings,
   }
 }
 
@@ -334,7 +370,7 @@ export async function collectCheckResult(
  * its rule code, so a finding that can flip the exit code is never invisible in the default output. */
 const REPORT_SECTIONS = [
   ["typecheck", "typecheck"],
-  ["typed-client", "hand-rolled fetch() to your own API"],
+  ["typed-client", "hand-rolled fetch()/EventSource/WebSocket to your own API"],
   ["untyped-client", 'client("…") missing its <typeof app> type argument'],
   ["server-only-import", "server-only import in a route module"],
   ["interpolated-sql", "SQL built by interpolating a value into the statement"],
@@ -468,12 +504,29 @@ export async function runCheck(
     readonly json?: boolean
     readonly lintsOnly?: boolean
     readonly structured?: boolean
+    readonly sarif?: boolean
   } = {},
 ): Promise<boolean> {
   // The check view over the one project verification: the same collector `assure` and `levels` read.
   const { collectProjectVerification } = await import("./verification.ts")
   const verification = await collectProjectVerification(cwd, { lintsOnly: opts.lintsOnly ?? false })
   const result = await verification.check()
+  if (opts.sarif) {
+    const diagnostics: readonly Diagnostic[] =
+      result.structuredDiagnostics ??
+      result.diagnostics.map((value) => ({
+        code: value.code ?? value.rule,
+        severity: normalizeSeverity(value.severity),
+        message: value.message,
+        ...(value.file === undefined ? {} : { file: value.file }),
+        ...(value.line === undefined ? {} : { line: value.line }),
+        ...(value.evidence === undefined ? {} : { evidence: value.evidence }),
+        ...(value.fix === undefined ? {} : { fix: { recipe: value.fix } }),
+        ...(value.verify === undefined ? {} : { verify: value.verify }),
+      }))
+    console.log(JSON.stringify(toSarifLog(diagnostics), null, 2))
+    return result.ok
+  }
   if (opts.json) {
     console.log(
       JSON.stringify(

package/src/cli.ts

@@ -15,6 +15,7 @@ import { fileURLToPath } from "node:url"
 import { inProcessClient } from "@nifrajs/client"
 import {
   type CreateWebAppOptions,
+  type CssLoadingMode,
   createWebApp,
   DEFAULT_DEV_PORT,
   type RenderAdapter,
@@ -128,9 +129,11 @@ Usage:
                                          self-host on a VPS so any remote agent can learn nifra. Default :8787.
   nifra learn   [<step>]                 Print the guided build-an-app path (the human view of nifra_learn):
                                          no arg for the step index, a number for one step's goal/do/verify.
-  nifra check   [--json] [--lints-only]  Gate: typecheck + lints (hand-rolled fetch(), untyped client("…"),
+  nifra check   [--json] [--sarif] [--lints-only]
+                                         Gate: typecheck + lints (hand-rolled fetch(), untyped client("…"),
                                          server-only imports in routes/). Run as "done"; --json for agents;
-                                         --lints-only skips tsc for a near-instant inner-loop pass.
+                                         --sarif emits the same stable diagnostics as SARIF 2.1.0 for external
+                                         review tools; --lints-only skips tsc for a near-instant inner-loop pass.
   nifra verify   [--release] [--json]    Run the shared repository verification gate. --release runs the
                                          full build, test, coverage, corpus, consumer, and cross-runtime gate.
   nifra fix     [--code <NF-code>]       Apply a registered diagnostic recipe, then print the remaining
@@ -216,7 +219,7 @@ set in the process environment is never overwritten by a file.
 ${renderCommandCatalogHelp()}`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "3.3.0"
+const CLI_VERSION = "3.5.0"
 
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v: unknown): RenderAdapter => v as RenderAdapter
@@ -562,20 +565,46 @@ async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Pro
   if (flags.vite && flags.bun) {
     throw new Error("[nifra] `nifra build` takes `--vite` or `--bun`, not both.")
   }
+  const { framework: fw } = app
+  const cssCodeSplitRequested = fw.cssCodeSplit === false
+  const hasBunTransforms =
+    app.resolvedPlugins.clientPlugins.length > 0 || app.resolvedPlugins.serverPlugins.length > 0
+  if (cssCodeSplitRequested && flags.bun) {
+    throw new Error(
+      "[nifra] `cssCodeSplit: false` is a Vite-only production option, but `nifra build --bun` was requested. " +
+        "Drop `--bun` (Nifra will select Vite automatically) or remove the aggregate CSS setting.",
+    )
+  }
+  if (cssCodeSplitRequested && hasBunTransforms) {
+    throw new Error(
+      "[nifra] `cssCodeSplit: false` requires the Vite production pipeline, but this app also declares " +
+        "Bun client/server plugins. Use `--vite` with Vite equivalents, or remove the aggregate CSS setting; " +
+        "switching pipelines would silently drop the Bun transforms.",
+    )
+  }
   // Which bundler builds this app. Default is Bun; an app whose ONLY transforms are `vitePlugins` gets
   // Vite instead, because the Bun build cannot run them and would silently omit the work. `--vite`/`--bun`
   // force it, and the one forced combination that would drop transforms throws.
-  const decision = chooseBuildPipeline(
+  let decision = chooseBuildPipeline(
     app.resolvedPlugins,
     flags.vite ? "vite" : flags.bun ? "bun" : undefined,
   )
+  if (cssCodeSplitRequested && decision.pipeline === "bun") {
+    // With no Bun transforms, aggregate CSS is a Vite-only request that can be honored safely by
+    // selecting the same pipeline the user would otherwise have to force explicitly.
+    decision = {
+      pipeline: "vite",
+      why: "auto",
+      reason: "auto: this app requested Vite's aggregate CSS output (`cssCodeSplit: false`)",
+    }
+  }
   const useVite = decision.pipeline === "vite"
   // Same deploy-dir output - buildTargetVite delegates to the same orchestrator as buildTarget - so only
   // the bundler and the plugin FORMAT (Vite plugins, not Bun) differ.
   const buildTarget = useVite
     ? (await import("@nifrajs/web/build-vite")).buildTargetVite
     : (await import("@nifrajs/web/build")).buildTarget
-  const { framework: fw, routesDir, outDir, cwd, backend } = app
+  const { routesDir, outDir, cwd, backend } = app
   // The server entry must import the adapter from `framework.ts` (edge-safe), not the loaded config.
   // `loadApp` guarantees one of them exists; prefer framework.ts so a multi-target app's Vite-plugin
   // config never reaches the edge bundle (see load.ts module header).
@@ -611,6 +640,8 @@ async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Pro
     ...(fw.define ? { define: fw.define } : {}),
     ...(fw.publicDir !== undefined ? { publicDir: fw.publicDir } : {}),
     ...(fw.publicEnvPrefix !== undefined ? { publicEnvPrefix: fw.publicEnvPrefix } : {}),
+    ...(fw.cssCodeSplit !== undefined ? { cssCodeSplit: fw.cssCodeSplit } : {}),
+    ...(fw.cssLoading !== undefined ? { cssLoading: fw.cssLoading } : {}),
     // The static target needs a built app to drive prerendering - only build it when targeting static.
     ...(target === "static" ? { prerenderApp: await buildPrerenderApp(app) } : {}),
   })
@@ -647,6 +678,7 @@ async function buildPrerenderApp(
       ...(client.routes ? { routePreload: client.routes } : {}),
       ...(client.css ? { styles: client.css } : {}),
       ...(client.routeStyles ? { routeStyles: client.routeStyles } : {}),
+      ...(client.cssLoading !== undefined ? { cssLoading: client.cssLoading } : {}),
       ...apiOf(backend),
     })
 }
@@ -656,6 +688,7 @@ interface BuiltManifest {
   readonly routes?: Readonly<Record<string, readonly string[]>>
   readonly css?: readonly string[]
   readonly routeStyles?: Readonly<Record<string, readonly string[]>>
+  readonly cssLoading?: CssLoadingMode
 }
 
 async function start(app: LoadedApp, flags: Flags): Promise<void> {
@@ -836,14 +869,27 @@ async function main(): Promise<void> {
       } else {
         console.log(catalogSpec.render(output, input).join("\n"))
       }
-      if (catalogSpec.success !== undefined && !catalogSpec.success(output, input))
+      if (catalogSpec.exitCode !== undefined) {
+        process.exitCode = catalogSpec.exitCode(output, input)
+      } else if (catalogSpec.success !== undefined && !catalogSpec.success(output, input)) {
         process.exitCode = 1
+      }
     } catch (err) {
       // A thrown error is nifra's own reporting path, not a silent abort: clear the sentinel so the
       // hint stays reserved for the case where the process died inside the app import.
       markReflecting(undefined)
       console.error(formatCliError(err))
-      process.exitCode = 1
+      const candidate =
+        typeof err === "object" && err !== null && "exitCode" in err
+          ? (err as { readonly exitCode?: unknown }).exitCode
+          : undefined
+      process.exitCode =
+        typeof candidate === "number" &&
+        Number.isInteger(candidate) &&
+        candidate >= 0 &&
+        candidate <= 255
+          ? candidate
+          : 1
     }
     return
   }

package/src/command-catalog.ts

@@ -15,12 +15,14 @@ import type {
 } from "./capabilities-tool.ts"
 import { type CheckResult, renderCheckReport } from "./check.ts"
 import type { ContractsLock } from "./contracts.ts"
+import { type Diagnostic, diagnostic, normalizeSeverity, toSarifLog } from "./diagnostics.ts"
 import type { DoctorResult } from "./doctor.ts"
 import type { VerificationLevelsResult } from "./levels-tool.ts"
 import type { LoadedApp } from "./load.ts"
 import type { ManifestEmitCommandResult } from "./manifest-tool.ts"
 import { collectPortResult, type PortResult, renderReport } from "./port.ts"
 import type { ReplayResult } from "./replay.ts"
+import { reviewSpec } from "./review.ts"
 import type { StylexMigrationResult } from "./stylex-migrate.ts"
 import {
   collectProjectWorkGraph,
@@ -80,6 +82,8 @@ export interface CommandSpec<Input, Output> {
   readonly run: (input: Input, ctx: CommandCtx) => Promise<Output>
   readonly render: (out: Output, input?: Input) => readonly string[]
   readonly success?: (out: Output, input: Input) => boolean
+  /** Optional command-specific process status. Legacy commands retain the boolean fallback. */
+  readonly exitCode?: (out: Output, input: Input) => number
   /** JSON-compatible view. Defaults to the raw command result. */
   readonly json?: (out: Output, input: Input) => unknown
 }
@@ -240,6 +244,7 @@ function parseBooleanFlags(
 interface CheckInput {
   readonly lintsOnly?: boolean | undefined
   readonly json?: boolean | undefined
+  readonly sarif?: boolean | undefined
   readonly maxDiagnostics?: number | undefined
   readonly dir?: string | undefined
 }
@@ -429,6 +434,7 @@ const CHECK_SCHEMA = input<CheckInput>(
   objectSchema({
     lintsOnly: { type: "boolean" },
     json: { type: "boolean" },
+    sarif: { type: "boolean" },
     maxDiagnostics: { type: "integer", minimum: 1 },
     dir: { type: "string" },
   }),
@@ -438,7 +444,7 @@ const CHECK_SCHEMA = input<CheckInput>(
     if (maxDiagnostics !== undefined && (!Number.isInteger(maxDiagnostics) || maxDiagnostics < 1))
       throw new TypeError("maxDiagnostics must be a positive integer")
     return {
-      ...parseBooleanFlags(raw, ["lintsOnly", "json"]),
+      ...parseBooleanFlags(raw, ["lintsOnly", "json", "sarif"]),
       ...(maxDiagnostics === undefined ? {} : { maxDiagnostics }),
       ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     } as CheckInput
@@ -789,10 +795,25 @@ function loadAppFor(ctx: CommandCtx): Promise<LoadedApp> {
   return import("./load.ts").then(({ loadApp }) => loadApp(ctx.cwd))
 }
 
-function checkJson(out: CheckCommandOutput): unknown {
-  return out.structuredDiagnostics === undefined
-    ? out
-    : { ...out, diagnostics: out.structuredDiagnostics }
+function structuredDiagnostics(out: CheckCommandOutput): readonly Diagnostic[] {
+  if (out.structuredDiagnostics !== undefined) return out.structuredDiagnostics
+  return out.diagnostics.map((value) =>
+    diagnostic({
+      code: value.code ?? value.rule,
+      severity: normalizeSeverity(value.severity),
+      message: value.message,
+      ...(value.file === undefined ? {} : { file: value.file }),
+      ...(value.line === undefined ? {} : { line: value.line }),
+      ...(value.evidence === undefined ? {} : { evidence: value.evidence }),
+      ...(value.fix === undefined ? {} : { fix: { recipe: value.fix } }),
+      ...(value.verify === undefined ? {} : { verify: value.verify }),
+    }),
+  )
+}
+
+function checkJson(out: CheckCommandOutput, input?: CheckInput): unknown {
+  if (input?.sarif === true) return toSarifLog(structuredDiagnostics(out))
+  return { ...out, diagnostics: structuredDiagnostics(out) }
 }
 
 const checkSpec: CommandSpec<CheckInput, CheckCommandOutput> = {
@@ -810,6 +831,7 @@ const checkSpec: CommandSpec<CheckInput, CheckCommandOutput> = {
     flags: [
       { name: "lints-only", field: "lintsOnly", type: "boolean" },
       { name: "json", field: "json", type: "boolean" },
+      { name: "sarif", field: "sarif", type: "boolean" },
     ],
   },
   async run(value, ctx) {
@@ -822,9 +844,12 @@ const checkSpec: CommandSpec<CheckInput, CheckCommandOutput> = {
       })
     ).check()
   },
-  render: (out) => renderCheckReport(out),
+  render: (out, input) =>
+    input?.sarif === true
+      ? JSON.stringify(checkJson(out, input), null, 2).split("\n")
+      : renderCheckReport(out),
   success: (out) => out.ok,
-  json: (out) => checkJson(out),
+  json: (out, input) => checkJson(out, input),
 }
 
 const assureSpec: CommandSpec<AssureInput, AssureCommandOutput> = {
@@ -1512,6 +1537,7 @@ const portSpec: CommandSpec<PortInput, PortResult> = {
 
 export const commandSpecs = Object.freeze([
   checkSpec,
+  reviewSpec,
   assureSpec,
   levelsSpec,
   capabilitiesSpec,

package/src/contracts.ts

@@ -1,6 +1,11 @@
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
-import { type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
+import {
+  type ProjectEvidenceSnapshot,
+  reflectedRoutesFromEvidence,
+  snapshotProjectEvidence,
+} from "@nifrajs/core/evidence"
+import type { ReflectedRoute } from "@nifrajs/core/reflection"
 
 export interface ContractDigest {
   readonly request: string
@@ -85,10 +90,14 @@ export async function isVacuousLock(lock: ContractsLock): Promise<boolean> {
   return digests.every((d) => d.request === empty && d.response === empty)
 }
 
-export async function buildContractsLock(source: unknown): Promise<ContractsLock> {
+export async function buildContractsLock(
+  source: unknown,
+  evidence?: ProjectEvidenceSnapshot,
+): Promise<ContractsLock> {
+  const reflected = reflectedRoutesFromEvidence(evidence ?? snapshotProjectEvidence(source))
   const routes = Object.fromEntries(
     await Promise.all(
-      reflectRoutes(source).map(
+      reflected.map(
         async (route) => [`${route.method} ${route.path}`, await digestRoute(route)] as const,
       ),
     ),

package/src/diagnostics.ts

@@ -7,6 +7,32 @@ export interface DiagnosticFix {
   readonly command?: string
 }
 
+/**
+ * The richer compatibility view used by the original `nifra check` renderer. It is deliberately
+ * kept out of the enumerable diagnostic shape: SARIF, MCP structured output, and JSON consumers get
+ * the small stable diagnostic contract, while the legacy text view can still explain an exact edit.
+ */
+export interface DiagnosticCompatibility {
+  /** The pre-registry rule name used by the human/legacy check result. */
+  readonly rule: string
+  /** The old human-facing fix text, when the rule had one. */
+  readonly fix?: string
+  /** A richer legacy suggestion (diff, command, or manual steps). */
+  readonly suggestion?: DiagnosticSuggestion
+  /** The import path evidence used by the legacy server-only-import view. */
+  readonly chain?: readonly string[]
+  /** Preserve the old optional `CheckDiagnostic.code` field exactly where it existed. */
+  readonly includeCode?: boolean
+}
+
+export interface DiagnosticSuggestion {
+  readonly kind: "edit" | "command" | "manual"
+  readonly title: string
+  readonly diff?: string
+  readonly command?: readonly string[]
+  readonly steps?: readonly string[]
+}
+
 export interface Diagnostic {
   /** Stable forever. Never renumber or reuse. */
   readonly code: string
@@ -21,6 +47,159 @@ export interface Diagnostic {
   readonly verify?: string
 }
 
+const DIAGNOSTIC_COMPATIBILITY = Symbol("nifra.diagnosticCompatibility")
+
+/** Attach legacy-only rendering metadata without widening the serialized diagnostic protocol. */
+export function diagnosticWithCompatibility(
+  value: Diagnostic,
+  compatibility: DiagnosticCompatibility,
+): Diagnostic {
+  const result = { ...value }
+  Object.defineProperty(result, DIAGNOSTIC_COMPATIBILITY, {
+    value: Object.freeze({
+      ...compatibility,
+      ...(compatibility.chain === undefined
+        ? {}
+        : { chain: Object.freeze([...compatibility.chain]) }),
+    }),
+    enumerable: false,
+  })
+  return Object.freeze(result)
+}
+
+/** Read legacy-only rendering metadata. Undefined means the diagnostic has no compatibility view. */
+export function diagnosticCompatibilityOf(value: Diagnostic): DiagnosticCompatibility | undefined {
+  return (
+    value as Diagnostic & {
+      readonly [DIAGNOSTIC_COMPATIBILITY]?: DiagnosticCompatibility
+    }
+  )[DIAGNOSTIC_COMPATIBILITY]
+}
+
+/** The subset of SARIF 2.1.0 emitted by {@link toSarifLog}. */
+export interface SarifLog {
+  readonly $schema: "https://json.schemastore.org/sarif-2.1.0.json"
+  readonly version: "2.1.0"
+  readonly runs: readonly SarifRun[]
+}
+
+export interface SarifRun {
+  readonly tool: {
+    readonly driver: {
+      readonly name: string
+      readonly version?: string
+      readonly rules: readonly SarifRule[]
+    }
+  }
+  readonly results: readonly SarifResult[]
+}
+
+export interface SarifRule {
+  readonly id: string
+  readonly shortDescription: { readonly text: string }
+}
+
+export interface SarifResult {
+  readonly ruleId: string
+  readonly level: "error" | "warning" | "note"
+  readonly message: { readonly text: string }
+  readonly locations?: readonly SarifLocation[]
+  readonly properties?: Readonly<Record<string, string | readonly string[]>>
+}
+
+export interface SarifLocation {
+  readonly physicalLocation: {
+    readonly artifactLocation: {
+      readonly uri: string
+      readonly uriBaseId?: string
+    }
+    readonly region?: { readonly startLine: number }
+  }
+}
+
+export interface SarifProjectionOptions {
+  /** Name shown by external review tools in the SARIF run metadata. Defaults to `nifra`. */
+  readonly toolName?: string
+  /** Optional CLI/framework version shown by external review tools. */
+  readonly toolVersion?: string
+  /** Base URI identifier for relative diagnostic file paths. */
+  readonly uriBaseId?: string
+}
+
+function sarifLevel(severity: Severity): SarifResult["level"] {
+  return severity === "error" ? "error" : severity === "warn" ? "warning" : "note"
+}
+
+function sarifProperties(
+  value: Diagnostic,
+): Readonly<Record<string, string | readonly string[]>> | undefined {
+  const properties: Record<string, string | readonly string[]> = {}
+  if (value.evidence !== undefined && value.evidence.length > 0)
+    properties["nifra.evidence"] = [...value.evidence]
+  if (value.verify !== undefined) properties["nifra.verify"] = value.verify
+  if (value.fix !== undefined) {
+    properties["nifra.fix.recipe"] = value.fix.recipe
+    if (value.fix.command !== undefined) properties["nifra.fix.command"] = value.fix.command
+  }
+  return Object.keys(properties).length === 0 ? undefined : properties
+}
+
+/**
+ * Project stable Nifra diagnostics into SARIF for code-host and external review surfaces.
+ *
+ * This is deliberately a pure projection: it does not run checks, read files, or reinterpret policy.
+ * Relative file names remain relative so callers can choose the review tool's checkout base through
+ * {@link SarifProjectionOptions.uriBaseId}.
+ */
+export function toSarifLog(
+  diagnostics: readonly Diagnostic[],
+  options: SarifProjectionOptions = {},
+): SarifLog {
+  const rules = new Map<string, SarifRule>()
+  const results: SarifResult[] = []
+  for (const value of diagnostics) {
+    if (!rules.has(value.code)) {
+      rules.set(value.code, {
+        id: value.code,
+        shortDescription: { text: value.message },
+      })
+    }
+    const location =
+      value.file === undefined
+        ? undefined
+        : {
+            physicalLocation: {
+              artifactLocation: {
+                uri: value.file.replaceAll("\\", "/"),
+                ...(options.uriBaseId === undefined ? {} : { uriBaseId: options.uriBaseId }),
+              },
+              ...(value.line !== undefined && Number.isInteger(value.line) && value.line >= 1
+                ? { region: { startLine: value.line } }
+                : {}),
+            },
+          }
+    const properties = sarifProperties(value)
+    results.push({
+      ruleId: value.code,
+      level: sarifLevel(value.severity),
+      message: { text: value.message },
+      ...(location === undefined ? {} : { locations: [location] }),
+      ...(properties === undefined ? {} : { properties }),
+    })
+  }
+
+  const driver = {
+    name: options.toolName ?? "nifra",
+    ...(options.toolVersion === undefined ? {} : { version: options.toolVersion }),
+    rules: [...rules.values()],
+  }
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [{ tool: { driver }, results }],
+  }
+}
+
 export const diagnostic = (value: Diagnostic): Diagnostic => Object.freeze(value)
 
 export function severityFails(severity: Severity, strict = false): boolean {