@nifrajs/cli 4.0.2 → 5.1.0

package/src/port.ts

@@ -310,9 +310,10 @@ export function scanFileForFeatures(file: string, content: string, state: ScanSt
 }
 
 // Mirror nifra check/doctor's ignore set: deps, build output, generated/per-runtime dist dirs, VCS.
-// PLUS *.config.* and obvious build scripts (build*.ts) - `port` scans request/app source, not tooling.
+// PLUS *.config.* and build scripts (build.ts, build-<target>.ts, build.<x>.ts) - `port` scans
+// request/app source, not tooling. A source file that merely starts with "build" is still source.
 const IGNORED =
-  /(^|\/)(node_modules|dist(-[a-z0-9]+)?|build|\.nifra|\.git|\.wrangler|coverage)\/|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)[^/]*\.config\.[cm]?[jt]sx?$|(^|\/)build[^/]*\.[cm]?[jt]sx?$/
+  /(^|\/)(node_modules|dist(-[a-z0-9]+)?|build|\.nifra|\.git|\.wrangler|coverage)\/|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)[^/]*\.config\.[cm]?[jt]sx?$|(^|\/)build(?:[-.][^/]*)?\.[cm]?[jt]sx?$/
 
 /** Walk the project's source (same surface as `nifra check`, minus config + build scripts). */
 async function walkPortSource(

package/src/project-facts.ts

@@ -7,8 +7,11 @@ import type {
 import type {
   ManifestDriftFinding,
   SourceFinding,
+  SqlFinding,
   StaticRouteFinding,
   TransitiveServerImportFinding,
+  TypedClientFinding,
+  UnresolvedRoutePathFinding,
 } from "./check-scan.ts"
 import type { DoctorResult } from "./doctor.ts"
 import type { TypeScriptSession } from "./internal/typescript-import.ts"
@@ -16,13 +19,15 @@ import type { PipelineReport } from "./pipeline-report.ts"
 import type { RulePack, SourceIndex } from "./rules/index.ts"
 
 export interface ProjectSourceFindings {
-  readonly fetches: readonly SourceFinding[]
+  readonly fetches: readonly TypedClientFinding[]
   /** Hand-rolled `new EventSource("/…")` / `new WebSocket("/…")` to the app's own streaming surface. */
-  readonly streams: readonly SourceFinding[]
+  readonly streams: readonly TypedClientFinding[]
   readonly untypedClients: readonly SourceFinding[]
   readonly removedImports: readonly SourceFinding[]
   readonly responseRoutes: readonly SourceFinding[]
-  readonly interpolatedSql: readonly SourceFinding[]
+  readonly interpolatedSql: readonly SqlFinding[]
+  /** Route registrations whose path is neither a literal nor a constant the scan resolves. */
+  readonly routePaths: readonly UnresolvedRoutePathFinding[]
 }
 
 export interface ProjectPackageFacts {
@@ -41,6 +46,10 @@ export interface ContractCheckFacts {
   readonly present: boolean
   readonly vacuous: boolean
   readonly diagnostics: readonly { readonly route?: string; readonly message: string }[]
+  /** `METHOD /path` of every route `backend/app.ts` serves; set only when the lock check loaded it. */
+  readonly served?: readonly string[]
+  /** `METHOD /path` of each authenticated route that validates its input before its auth hook runs. */
+  readonly inputBeforeAuth?: readonly string[]
   readonly error?: string
 }
 
@@ -50,6 +59,10 @@ export interface ProjectCheckFacts {
   readonly sqlCompilerAvailable: boolean
   /** Set when a project TypeScript install is present but outside the scanner adapter range. */
   readonly unsupportedTypeScriptVersion?: string
+  /** Why component modules could not be checked: the project's TypeScript has no compiler API. */
+  readonly componentCheckUnsupported?:
+    | { readonly version: string; readonly message: string }
+    | undefined
   /** Shared syntax/checker session for built-in rules; omitted from serialized check output. */
   readonly typescriptSession?: TypeScriptSession
   readonly checkConfigError?: string
@@ -87,6 +100,7 @@ export function freezeProjectFacts(seed: ProjectFactsSeed): ProjectFacts {
     removedImports: freezeFindings(seed.sourceFindings.removedImports),
     responseRoutes: freezeFindings(seed.sourceFindings.responseRoutes),
     interpolatedSql: freezeFindings(seed.sourceFindings.interpolatedSql),
+    routePaths: freezeFindings(seed.sourceFindings.routePaths),
   })
   const policies = Object.freeze({
     ...seed.policies,

package/src/project-path.ts

@@ -1,6 +1,45 @@
-import { realpath } from "node:fs/promises"
+import { lstatSync, readlinkSync, realpathSync } from "node:fs"
 import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path"
 
+const MAX_SYMLINKS = 40
+
+function errorCode(error: unknown): unknown {
+  return typeof error === "object" && error !== null ? Reflect.get(error, "code") : undefined
+}
+
+/**
+ * Where a write to `path` lands, canonicalized: the real path of its nearest existing ancestor plus
+ * the components still missing below it. A dangling symlink is followed to the path it names, since
+ * writing through it creates that path. `undefined` when the filesystem cannot say.
+ */
+export function writeTargetOf(path: string): string | undefined {
+  let probe = resolve(path)
+  const missing: string[] = []
+  let links = 0
+  for (;;) {
+    try {
+      return resolve(realpathSync(probe), ...[...missing].reverse())
+    } catch (error) {
+      if (errorCode(error) !== "ENOENT") return undefined
+    }
+    let link: string | undefined
+    try {
+      if (lstatSync(probe).isSymbolicLink()) link = readlinkSync(probe)
+    } catch (error) {
+      if (errorCode(error) !== "ENOENT") return undefined
+    }
+    if (link !== undefined) {
+      if (++links > MAX_SYMLINKS) return undefined
+      probe = resolve(dirname(probe), link)
+      continue
+    }
+    const parent = dirname(probe)
+    if (parent === probe) return undefined
+    missing.push(basename(probe))
+    probe = parent
+  }
+}
+
 function escapesRoot(root: string, candidate: string): boolean {
   const rel = relative(root, candidate)
   return rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)
@@ -17,18 +56,10 @@ export async function resolveInsideProject(
     const resolved = resolve(resolvedRoot, candidate)
     if (escapesRoot(resolvedRoot, resolved)) return undefined
 
-    const realRoot = await realpath(resolvedRoot)
-    let realCandidate: string
-    try {
-      realCandidate = await realpath(resolved)
-    } catch (error) {
-      if (!(error && typeof error === "object" && (error as { code?: string }).code === "ENOENT")) {
-        return undefined
-      }
-      const realParent = await realpath(dirname(resolved))
-      realCandidate = resolve(realParent, basename(resolved))
-    }
-    if (escapesRoot(realRoot, realCandidate)) return undefined
+    // The same canonicalizer on both sides: fs/promises expands Windows 8.3 names, realpathSync does not.
+    const realRoot = realpathSync(resolvedRoot)
+    const realCandidate = writeTargetOf(resolved)
+    if (realCandidate === undefined || escapesRoot(realRoot, realCandidate)) return undefined
     return resolved
   } catch {
     return undefined

package/src/recipes/5.0.0.ts

@@ -0,0 +1,35 @@
+import type { UpgradeRecipe } from "./index.ts"
+
+/**
+ * Upgrade recipe for Nifra 5.0.
+ *
+ * The runner pins the fixed group and lists every retired `@nifra-gate-reviewed` comment. It never
+ * writes the `nifra-expect` comment that replaces one: a reason it made up would silence a finding
+ * nobody reviewed. Every changed default below has a `nifra check` finding or a one-line way to keep
+ * the 4.x behavior, so the notes name both.
+ */
+export const recipe: UpgradeRecipe = {
+  version: "5.0.0",
+  pins: [
+    { match: "@nifrajs/", to: "5.0.0" },
+    { match: "create-nifra", to: "5.0.0" },
+    { match: "nifra", to: "5.0.0" },
+  ],
+  importMoves: [],
+  retiredMarkers: [
+    {
+      marker: "@nifra-gate-reviewed",
+      instead: "// nifra-expect <code>: <reason>, with the code nifra check reports there",
+    },
+  ],
+  notes: [
+    "`@nifra-gate-reviewed` silences nothing. After review, silence one finding with `// nifra-expect <code>: <reason>` on its line or anywhere in the comment block above it. The upgrade lists every old comment and the line it covered; it never writes a reason. Every security finding and every error needs the reason, so `// nifra-expect route-overlap` (NF-C024, NF-C025) without one no longer silences the overlap.",
+    "`nifra check` reports a secret comparison (NF-S002) as advisory only in browser code inside a nifra web app: a directory with `nifra.config.ts` or `backend/framework.ts`, or whose nearest package.json depends on `@nifrajs/web` or a `@nifrajs/web-*` adapter. The same comparison in `routes/` or `frontend/` of an API-only project, or of a package without a web dependency, fails the check.",
+    "A WebSocket handshake runs the route chain an HTTP `GET` registered at the same point runs: `authenticate()`, auth middleware, `derive` and `beforeHandle` added before `app.ws()` guard the socket and can refuse the handshake with the response they send an HTTP request. Register a socket before the guard to keep it public. `nifra routes --hooks` lists what each socket runs.",
+    '`createWebApp` serves the backend over HTTP only at an `apiPrefix` the app sets; without one it is loader-only (`ctx.api`) and a browser call to `/api` reaches page routing. `nifra check` reports a `backend/framework.ts` that sets none (NF-C035); run `nifra fix --code NF-C035` to add `export const apiPrefix = "/api"` and keep the 4.x mount, or export `""` to keep the backend loader-only. A hand-written `createWebApp` call passes `apiPrefix: "/api"` itself.',
+    "Root status pages (`_404.tsx`, `_<status>.tsx`) and `_error.tsx` render inside the layouts above them with their loader data, and a page rendered with layout data is `private, no-store`. A root status page that imports the root layout to wrap itself now renders it twice: `nifra check` reports it (NF-C034); remove the wrap. `export const inLayouts = false` renders a page the 4.x way and runs no layout loader for it.",
+    "A Response returned to more than one request is no longer shared: a body-less one is copied for each request before cookies and headers are written, and one whose body was already sent answers `500`. Build a Response per request, or return data and let the handler serialize it.",
+    "`invariants.executor` in `nifra.assurance.ts` is optional now that `invariants.setup` can provision the target, so code that reads the config's type handles a missing `executor`.",
+    "A layout's `meta` receives its own loader data as `data`, `null` when the layout has no loader; the page's data moved to `pageData`. A layout `meta` written against the page's data, such as a title template, reads `pageData` now: `({ pageData }) => ({ title: pageData.title })`. `nifra check` reports a layout with no loader whose `meta` reads `data` (NF-C040). A page's own `meta` is unchanged.",
+  ],
+}

package/src/recipes/index.ts

@@ -8,6 +8,7 @@ import { recipe as v1_8_0 } from "./1.8.0.ts"
 import { recipe as v2_0_0 } from "./2.0.0.ts"
 import { recipe as v3_0_0 } from "./3.0.0.ts"
 import { recipe as v4_0_0 } from "./4.0.0.ts"
+import { recipe as v5_0_0 } from "./5.0.0.ts"
 
 /** A pin rule: every dependency whose name starts with `match` is set to version `to`. */
 export interface PinRule {
@@ -30,11 +31,19 @@ export interface ImportMove {
   readonly to: string
 }
 
+/** A source comment a release stopped honoring. The runner lists each one; it never rewrites it. */
+export interface RetiredMarker {
+  readonly marker: string
+  /** What to write instead, printed beside each comment. */
+  readonly instead: string
+}
+
 export interface UpgradeRecipe {
   readonly version: string
   readonly pins: readonly PinRule[]
   readonly dependencyMoves?: readonly DependencyMove[]
   readonly importMoves: readonly ImportMove[]
+  readonly retiredMarkers?: readonly RetiredMarker[]
   /** Human notes printed after the plan - e.g. structural changes the runner deliberately can't do. */
   readonly notes?: readonly string[]
 }
@@ -44,6 +53,7 @@ const RECIPES: Record<string, UpgradeRecipe> = {
   [v2_0_0.version]: v2_0_0,
   [v3_0_0.version]: v3_0_0,
   [v4_0_0.version]: v4_0_0,
+  [v5_0_0.version]: v5_0_0,
 }
 
 export function getRecipe(version: string): UpgradeRecipe | undefined {

package/src/release-verification.ts

@@ -59,6 +59,11 @@ export interface ReleaseVerificationOptions {
    * runner swings too far run to run to gate a release on.
    */
   readonly sharedRunner?: boolean
+  /**
+   * Fail a gate whose script package.json does not declare, instead of reporting it `undeclared`.
+   * The repository's own gate runs every gate in its plan, so a renamed script cannot drop one.
+   */
+  readonly requireScripts?: boolean
   readonly runCommand?: (spec: ReleaseCommandSpec) => Promise<ReleaseCommandResult>
 }
 
@@ -213,6 +218,14 @@ const undeclaredGate = (gate: VerificationGateSpec, script: string): ReleaseGate
   remediation: `Declare a \`${script}\` script to run this gate.`,
 })
 
+const missingScriptGate = (gate: VerificationGateSpec, script: string): ReleaseGateResult => ({
+  id: gate.id,
+  status: "fail",
+  commands: gate.commands.map(commandLabel),
+  message: `\`${script}\` is not a script in package.json`,
+  remediation: `Declare the \`${script}\` script this gate runs, or rename the gate's command to the script that replaced it.`,
+})
+
 /** The first `bun run <script>` of a gate that the root package.json does not declare. */
 const undeclaredScript = (
   gate: VerificationGateSpec,
@@ -248,6 +261,12 @@ export async function collectReleaseVerification(
       }
       // The plan names the nifra repository's own scripts; a project without one has nothing to run.
       const missing = undeclaredScript(gate, scripts)
+      if (missing !== undefined && options.requireScripts === true) {
+        const result = missingScriptGate(gate, missing)
+        gates.push(result)
+        failedId = result.id
+        continue
+      }
       if (missing !== undefined) {
         gates.push(undeclaredGate(gate, missing))
         continue
@@ -315,6 +334,7 @@ if (import.meta.main) {
   const ok = await runReleaseVerification(process.cwd(), {
     mode,
     sharedRunner: process.argv.includes("--shared-runner"),
+    requireScripts: true,
     json: process.argv.includes("--json"),
   })
   if (!ok) process.exitCode = 1

package/src/replay.ts

@@ -1,4 +1,5 @@
-import { resolve, sep } from "node:path"
+import { realpath } from "node:fs/promises"
+import { isAbsolute, relative, resolve } from "node:path"
 import { type CompatibleReplayFile, parseCompatibleReplayFile } from "@nifrajs/core/replay"
 import { runHydrationAssurance } from "./assure-hydration.ts"
 import { checkContractsLock } from "./contracts.ts"
@@ -12,10 +13,20 @@ export interface ReplayResult {
   readonly replays?: readonly string[]
 }
 
+const within = (root: string, path: string): boolean => {
+  const rel = relative(root, path)
+  return !rel.startsWith("..") && !isAbsolute(rel)
+}
+
+const canonical = (path: string): Promise<string> => realpath(path).catch(() => path)
+
 /** Validate and dispatch one token-only replay while keeping the file inside the project root. */
 export async function runReplay(cwd: string, file: string): Promise<ReplayResult> {
-  const path = resolve(cwd, file)
-  if (path !== cwd && !path.startsWith(cwd + sep)) {
+  const root = resolve(cwd)
+  // Compared as real paths: the MCP host hands over an already-resolved file, which never starts
+  // with a root reached through a symlink, and a replay file that is itself a link must not lead out.
+  const path = await canonical(resolve(root, file))
+  if (!within(await canonical(root), path) && !within(root, path)) {
     throw new Error("replay file must stay inside the project root")
   }
   const replay = parseCompatibleReplayFile(JSON.parse(await Bun.file(path).text()))

package/src/review.ts

@@ -16,7 +16,7 @@ import type {
 import type { CheckResult } from "./check.ts"
 import type { CommandCtx, CommandSpec } from "./command-catalog.ts"
 import type { Diagnostic } from "./diagnostics.ts"
-import { toSarifLog } from "./diagnostics.ts"
+import { diagnosticCompatibilityOf, toSarifLog } from "./diagnostics.ts"
 import { RULE_CODES } from "./rules/codes.ts"
 import { LEGACY_RULE_CODES } from "./rules/legacy.ts"
 
@@ -110,7 +110,8 @@ const CHECK_SOURCES: Readonly<Record<ReviewCheckId, ReviewEvidenceSource>> = {
 
 const ALLOWED_FIXES = new Set<ReviewFixRecipeId>(["manifest.sync", "workspace-dist.rebuild"])
 
-const CHECK_CODES: Readonly<Record<string, ReviewCheckId>> = {
+/** The review check each built-in code reports under; a code missing here would read as configuration. */
+export const CHECK_CODES: Readonly<Record<string, ReviewCheckId>> = {
   "NF-C001": "typecheck",
   "NF-C002": "typed-client",
   "NF-C003": "typed-client",
@@ -134,18 +135,43 @@ const CHECK_CODES: Readonly<Record<string, ReviewCheckId>> = {
   "NF-C021": "route-boundary",
   "NF-C022": "route-boundary",
   "NF-C023": "route-boundary",
+  "NF-C024": "route-boundary",
+  "NF-C025": "route-boundary",
+  "NF-C026": "route-boundary",
+  "NF-C027": "route-boundary",
+  "NF-C028": "server-boundary",
+  "NF-C029": "security",
+  "NF-C030": "security",
+  "NF-C031": "security",
+  "NF-C032": "security",
+  "NF-C033": "security",
+  "NF-C034": "route-boundary",
+  "NF-C035": "route-boundary",
+  "NF-C036": "route-boundary",
+  "NF-C037": "configuration",
+  "NF-C038": "configuration",
+  "NF-C039": "contract-witness",
+  "NF-C040": "route-boundary",
+  "NF-C041": "route-boundary",
+  "NF-C042": "route-boundary",
   "NF-D001": "dependency",
+  "NF-D002": "dependency",
   "NF-A001": "route-assurance",
   "NF-H001": "hydration",
   "NF-H002": "hydration",
   "NF-H003": "hydration",
   "NF-H004": "hydration",
   "NF-K001": "contract-witness",
+  "NF-S001": "security",
+  "NF-S002": "security",
+  "NF-S003": "security",
+  "NF-S004": "security",
+  "NF-S005": "security",
+  "NF-S006": "security",
+  "NF-S007": "security",
+  "NF-S008": "security",
 }
 
-for (const code of ["NF-S001", "NF-S002", "NF-S003", "NF-S004", "NF-S005", "NF-S006", "NF-S007"])
-  (CHECK_CODES as Record<string, ReviewCheckId>)[code] = "security"
-
 const REVIEW_INPUT_SCHEMA = {
   type: "object",
   properties: {
@@ -432,8 +458,11 @@ async function diffScope(cwd: string, ref: string): Promise<ReviewScope> {
   if (!verified.ok) throw new ReviewInputError("invalid git ref")
   const commit = verified.stdout.trim()
   if (!/^[0-9a-f]{40,64}$/.test(commit)) throw new ReviewInputError("invalid git ref")
+  // `--relative` keeps tracked paths app-relative, like `ls-files` and every finding, when the app is a
+  // subdirectory of the repository; without it no finding in a changed tracked file is in scope.
   const changed = await runGit(cwd, [
     "diff",
+    "--relative",
     "--name-only",
     "-z",
     "--diff-filter=ACDMRTUXB",
@@ -613,17 +642,22 @@ async function composeCollectedReport(
   }
 
   const changedPaths = new Set(scope.changedPaths)
+  // A server-only chain is in scope when any file on it changed: a new import in a shared module
+  // reaches the browser through a route the diff never touched.
+  const inScope = (candidate: CandidateFinding): boolean =>
+    candidate.location === undefined ||
+    changedPaths.has(candidate.location.path) ||
+    (diagnosticCompatibilityOf(candidate.diagnostic)?.modules ?? []).some((module) => {
+      const path = normalizedLocation(cwd, module, undefined)?.path
+      return path !== undefined && changedPaths.has(path)
+    })
   const retainedByCheck = new Map<ReviewCheckId, CandidateFinding[]>()
   let totalOutOfScope = 0
   let typeErrorOutOfScope = false
   for (const id of CHECK_IDS) {
     const retained: CandidateFinding[] = []
     for (const candidate of candidatesByCheck.get(id) ?? []) {
-      if (
-        scope.kind === "diff" &&
-        candidate.location !== undefined &&
-        !changedPaths.has(candidate.location.path)
-      ) {
+      if (scope.kind === "diff" && !inScope(candidate)) {
         totalOutOfScope += 1
         if (id === "typecheck" && candidate.severity === "error") typeErrorOutOfScope = true
       } else retained.push(candidate)

package/src/rules/codes.ts

@@ -29,11 +29,22 @@ export const RULE_CODES = Object.freeze({
   "NF-C030": "Route data without an output schema",
   "NF-C031": "Sensitive field in an output schema",
   "NF-C032": "Credential in browser code",
+  "NF-C033": "Generated output schema out of date",
+  "NF-C034": "Root status page wraps the root layout itself",
+  "NF-C035": "Backend not served over HTTP",
+  "NF-C036": "Route path the static scan cannot read",
+  "NF-C037": "API-only declaration over a web app",
+  "NF-C038": "Retired root layout file",
+  "NF-C039": "Implemented contract operation the backend does not serve",
+  "NF-C040": "Layout meta reads data its layout never loads",
+  "NF-C041": "Server-only export in a route frontend file",
+  "NF-C042": "Layout loader refuses access without a gate",
   "NF-C020": "Island enhancer cleanup check",
   "NF-C021": "nano binding cleanup check",
   "NF-C022": "nano bindList key check",
   "NF-C023": "nano computed deps check",
   "NF-D001": "Doctor check",
+  "NF-D002": "Mixed nifra versions",
   "NF-A001": "Assurance bundle check",
   "NF-H001": "Hydration mismatch",
   "NF-H002": "Duplicate framework runtime",
@@ -47,6 +58,7 @@ export const RULE_CODES = Object.freeze({
   "NF-S005": "External redirect opt-out",
   "NF-S006": "Security escape hatch enabled",
   "NF-S007": "Secure cookie without a __Host-/__Secure- prefix",
+  "NF-S008": "Authenticated route validates input before authentication",
 } as const)
 
 /** Codes that no longer fire but remain reserved forever. */

package/src/rules/comment-markers.ts

@@ -1,5 +1,5 @@
 /**
- * Marker recognition for in-source escape hatches (`@nifra-gate-reviewed`, `nifra-expect …`).
+ * Marker recognition for in-source escape hatches (`nifra-expect <code>: <reason>`).
  *
  * A marker counts when it appears on the flagged line itself (trailing comment) or ANYWHERE in the
  * contiguous comment block directly above it - which is where a human naturally writes the
@@ -11,12 +11,27 @@
 // open/body/close lines, and the JSX comment form.
 const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*\/|\*|\{\/\*)/
 
+/** The trailing comment on a code line: from its first `//` or `/*` outside a string literal to the
+ * end, else `""`. A marker in a string the code passes is data, not a comment. */
+function trailingComment(text: string): string {
+  let quote: string | undefined
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i]
+    if (quote !== undefined) {
+      if (char === "\\") i++
+      else if (char === quote) quote = undefined
+    } else if (char === '"' || char === "'" || char === "`") quote = char
+    else if (char === "/" && (text[i + 1] === "/" || text[i + 1] === "*")) return text.slice(i)
+  }
+  return ""
+}
+
 export function commentBlockHasMarker(
   lines: readonly string[],
   line: number,
   marker: string,
 ): boolean {
-  if ((lines[line - 1] ?? "").includes(marker)) return true
+  if (trailingComment(lines[line - 1] ?? "").includes(marker)) return true
   for (let i = line - 2; i >= 0; i--) {
     const text = lines[i] ?? ""
     if (!COMMENT_LINE.test(text)) return false
@@ -26,37 +41,58 @@ export function commentBlockHasMarker(
 }
 
 /**
- * The justification a reason-carrying marker (`<marker>: <reason>`) supplies, or `undefined` when the
- * marker is absent or written with no reason after its colon. Searches the same trailing-comment /
- * comment-block-above region as {@link commentBlockHasMarker}, so a hatch that demands a written reason
- * can require this to be non-empty before it silences anything - an empty `<marker>:` never suppresses,
- * which is how "reason mandatory" is enforced without a second diagnostic.
+ * The 1-based line a marker comment on `line` applies to: `line` itself when code precedes the comment
+ * there, else the first line after its comment block, or `undefined` when a blank line ends the block.
  */
-export function commentBlockMarkerReason(
+export function markerTarget(lines: readonly string[], line: number): number | undefined {
+  if (!COMMENT_LINE.test(lines[line - 1] ?? "")) return line
+  for (let i = line; i < lines.length; i++) {
+    const text = lines[i] ?? ""
+    if (COMMENT_LINE.test(text)) continue
+    return text.trim() === "" ? undefined : i + 1
+  }
+  return undefined
+}
+
+/** What a finding adds when a `nifra-expect` comment names it but leaves out the reason it needs. */
+export const MISSING_EXPECTATION_REASON =
+  "the nifra-expect comment here gives no reason after its colon, so it does not silence this"
+
+/**
+ * A `nifra-expect <name>: <reason>` comment for the finding on `line`, where `<name>` is one of
+ * `names`: the finding's NF code, or a slug it also answers to. It counts in the same trailing-comment /
+ * comment-block-above region as {@link commentBlockHasMarker}. `undefined` when no such comment is
+ * there; `reason` is `undefined` when none follows the name's colon. A hatch that silences an error
+ * requires the reason, so an empty `nifra-expect NF-C006:` never suppresses one.
+ */
+export function commentBlockExpectation(
   lines: readonly string[],
   line: number,
-  marker: string,
-): string | undefined {
+  names: readonly string[],
+): { readonly reason: string | undefined } | undefined {
+  const escaped = names.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+  const pattern = new RegExp(`nifra-expect\\s+(?:${escaped.join("|")})(?![\\w-])(.*)`)
+  let found = false
   const reasonOn = (text: string): string | undefined => {
-    const at = text.indexOf(marker)
-    if (at < 0) return undefined
-    const rest = text.slice(at + marker.length)
-    const colon = rest.indexOf(":")
-    if (colon < 0) return undefined
+    const match = pattern.exec(text)
+    if (match === null) return undefined
+    found = true
+    const rest = (match[1] ?? "").trimStart()
+    if (!rest.startsWith(":")) return undefined
     // A block comment's `*/` closer is not part of the reason.
     const reason = rest
-      .slice(colon + 1)
+      .slice(1)
       .replace(/\*\/\s*$/, "")
       .trim()
     return reason.length > 0 ? reason : undefined
   }
-  const onLine = reasonOn(lines[line - 1] ?? "")
-  if (onLine !== undefined) return onLine
+  const onLine = reasonOn(trailingComment(lines[line - 1] ?? ""))
+  if (onLine !== undefined) return { reason: onLine }
   for (let i = line - 2; i >= 0; i--) {
     const text = lines[i] ?? ""
-    if (!COMMENT_LINE.test(text)) return undefined
+    if (!COMMENT_LINE.test(text)) break
     const reason = reasonOn(text)
-    if (reason !== undefined) return reason
+    if (reason !== undefined) return { reason }
   }
-  return undefined
+  return found ? { reason: undefined } : undefined
 }