@nifrajs/cli 2.12.1 → 2.14.1

package/src/release-verification.ts

@@ -0,0 +1,377 @@
+/**
+ * The repository release verification gate.
+ *
+ * This module is intentionally independent from app loading. The root package scripts and the
+ * `nifra verify` command both call this runner, so the local and CI paths share one gate plan.
+ */
+
+import { mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join, relative, resolve, sep } from "node:path"
+
+export type ReleaseVerificationMode = "default" | "release"
+export type ReleaseGateStatus = "pass" | "fail" | "skipped"
+
+export interface ReleaseGateResult {
+  readonly id: string
+  readonly status: ReleaseGateStatus
+  readonly commands: readonly string[]
+  readonly exitCode?: number
+  readonly message?: string
+  readonly remediation: string
+}
+
+export interface ReleaseVerificationResult {
+  readonly ok: boolean
+  readonly mode: ReleaseVerificationMode
+  readonly gates: readonly ReleaseGateResult[]
+}
+
+export interface ReleaseCommandResult {
+  readonly exitCode: number
+  readonly stdout?: string
+  readonly stderr?: string
+}
+
+export interface ReleaseCommandSpec {
+  readonly args: readonly string[]
+  readonly cwd: string
+  readonly env: Record<string, string | undefined>
+}
+
+export interface ReleaseVerificationOptions {
+  readonly mode?: ReleaseVerificationMode
+  readonly runCommand?: (spec: ReleaseCommandSpec) => Promise<ReleaseCommandResult>
+}
+
+interface ReleaseGateSpec {
+  readonly id: string
+  readonly commands: readonly (readonly string[])[]
+  readonly remediation: string
+}
+
+const DEFAULT_GATES: readonly ReleaseGateSpec[] = [
+  {
+    id: "lint",
+    commands: [["run", "lint"]],
+    remediation: "Run `bun run lint` and fix the reported lint findings.",
+  },
+  {
+    id: "typecheck",
+    commands: [["run", "typecheck"]],
+    remediation: "Run `bun run typecheck` and fix the reported TypeScript errors.",
+  },
+  {
+    id: "tests",
+    commands: [["run", "test"]],
+    remediation: "Run `bun run test` and fix the first failing test.",
+  },
+  {
+    id: "docs",
+    commands: [["run", "check:docs"]],
+    remediation: "Run `bun run check:docs` and update the failing documentation example.",
+  },
+  {
+    id: "api-corpus",
+    commands: [["run", "check:api"]],
+    remediation: "Run `bun run gen:api` and review the generated API reference.",
+  },
+  {
+    id: "cards-corpus",
+    commands: [["run", "check:cards"]],
+    remediation: "Run `bun run gen:cards` and review the generated package cards.",
+  },
+  {
+    id: "node-outcome-corpus",
+    commands: [["run", "check:node-outcome"]],
+    remediation: "Run `bun run gen:node-outcome` and review the generated Node outcome contract.",
+  },
+  {
+    id: "sitemap",
+    commands: [["run", "check:sitemap"]],
+    remediation: "Run `bun run gen:sitemap` and review the generated sitemap.",
+  },
+  {
+    id: "public-boundary",
+    commands: [["run", "check:public-boundary"]],
+    remediation:
+      "Run `bun run check:public-boundary` and remove the reported public-boundary violation.",
+  },
+  {
+    id: "size",
+    commands: [["run", "check:size"]],
+    remediation:
+      "Run `bun run check:size` and either reduce the bundle or update the reviewed budget.",
+  },
+]
+
+const RELEASE_GATES: readonly ReleaseGateSpec[] = [
+  {
+    id: "build",
+    commands: [["run", "build"]],
+    remediation: "Run `bun run build` and fix the first package build failure.",
+  },
+  ...DEFAULT_GATES.slice(0, 3),
+  {
+    id: "coverage",
+    commands: [
+      ["run", "test:coverage"],
+      ["run", "check:coverage"],
+    ],
+    remediation:
+      "Run `bun run test:coverage` first, then `bun run check:coverage`, and fix the reported coverage regression.",
+  },
+  {
+    id: "corpus",
+    commands: [["run", "check:corpus"]],
+    remediation:
+      "Run `bun run gen:llms`, `bun run gen:api`, and `bun run gen:cards`, then rerun the corpus gate.",
+  },
+  DEFAULT_GATES[3] as ReleaseGateSpec,
+  {
+    id: "public-boundary",
+    commands: [["run", "check:public-boundary"]],
+    remediation:
+      "Run `bun run check:public-boundary` and remove the reported public-boundary violation.",
+  },
+  {
+    id: "size",
+    commands: [["run", "check:size"]],
+    remediation:
+      "Run `bun run check:size` and either reduce the bundle or update the reviewed budget.",
+  },
+  {
+    id: "core-performance",
+    commands: [["run", "check:core-performance"]],
+    remediation:
+      "Run `bun run check:core-performance` and investigate the measured performance regression.",
+  },
+  {
+    id: "publish",
+    commands: [["run", "check:publish"]],
+    remediation:
+      "Run `bun run check:publish` and fix the publish-consumer metadata or type-surface failure.",
+  },
+  {
+    id: "consumer",
+    commands: [["run", "check:consumers"]],
+    remediation: "Run `bun run check:consumers` and fix the isolated consumer failure.",
+  },
+  {
+    id: "cold-start",
+    commands: [["run", "check:cold-start"]],
+    remediation:
+      "Run `bun run check:cold-start` and fix the fresh scaffold install or build failure.",
+  },
+  {
+    id: "cross-runtime-deno",
+    commands: [
+      ["run", "test:deno"],
+      ["run", "check:deno-tarball"],
+    ],
+    remediation:
+      "Run `bun run test:deno` and `bun run check:deno-tarball`, then fix the first Deno compatibility failure.",
+  },
+  {
+    id: "cross-runtime-node",
+    commands: [["run", "test:node"]],
+    remediation: "Run `bun run test:node` and fix the Node runtime adapter failure.",
+  },
+  {
+    id: "pipeline-parity",
+    commands: [["run", "check:pipeline-parity"]],
+    remediation:
+      "Run `bun run check:pipeline-parity` and fix the development and production manifest drift.",
+  },
+]
+
+const runBunCommand = async (spec: ReleaseCommandSpec): Promise<ReleaseCommandResult> => {
+  const child = Bun.spawn([process.execPath, ...spec.args], {
+    cwd: spec.cwd,
+    env: spec.env,
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ])
+  return { exitCode, stdout, stderr }
+}
+
+const parsePackage = (path: string): Record<string, unknown> | undefined => {
+  try {
+    const value: unknown = JSON.parse(readFileSync(path, "utf8"))
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const workspacePatterns = (pkg: Record<string, unknown>): readonly string[] => {
+  const workspaces = pkg.workspaces
+  if (Array.isArray(workspaces))
+    return workspaces.filter((item): item is string => typeof item === "string")
+  if (workspaces !== null && typeof workspaces === "object") {
+    const packages = (workspaces as Record<string, unknown>).packages
+    if (Array.isArray(packages))
+      return packages.filter((item): item is string => typeof item === "string")
+  }
+  return []
+}
+
+const workspaceContains = async (
+  root: string,
+  patterns: readonly string[],
+  target: string,
+): Promise<boolean> => {
+  if (root === target) return patterns.length > 0
+  for (const pattern of patterns) {
+    const packagePattern = `${pattern.replace(/\/$/, "")}/package.json`
+    for await (const match of new Bun.Glob(packagePattern).scan({ cwd: root, dot: false })) {
+      if (match.split(/[\\/]/).includes("node_modules")) continue
+      const packageRoot = resolve(root, dirname(match))
+      const targetRelative = relative(packageRoot, target)
+      if (
+        targetRelative === "" ||
+        (!targetRelative.startsWith(`..${sep}`) && targetRelative !== "..")
+      )
+        return true
+    }
+  }
+  return false
+}
+
+/** Resolve the repository root even when the command starts in a workspace package. */
+export async function resolveVerificationRoot(start: string): Promise<string> {
+  const original = realpathSync(resolve(start))
+  let current = original
+  for (;;) {
+    const pkgPath = join(current, "package.json")
+    const pkg = parsePackage(pkgPath)
+    if (pkg !== undefined && (await workspaceContains(current, workspacePatterns(pkg), original))) {
+      return current
+    }
+    const parent = dirname(current)
+    if (parent === current) return original
+    current = parent
+  }
+}
+
+const gatePlan = (mode: ReleaseVerificationMode): readonly ReleaseGateSpec[] =>
+  mode === "release" ? RELEASE_GATES : DEFAULT_GATES
+
+const commandLabel = (args: readonly string[]): string => `bun ${args.join(" ")}`
+
+const runGate = async (
+  root: string,
+  gate: ReleaseGateSpec,
+  runCommand: (spec: ReleaseCommandSpec) => Promise<ReleaseCommandResult>,
+  fixtureRoot: string,
+): Promise<ReleaseGateResult> => {
+  let lastExitCode: number | undefined
+  for (const [index, args] of gate.commands.entries()) {
+    const fixture = mkdtempSync(join(fixtureRoot, `${gate.id}-${index}-`))
+    const result = await runCommand({
+      args,
+      cwd: root,
+      env: {
+        ...process.env,
+        TMPDIR: fixture,
+        NIFRA_VERIFY_GATE: gate.id,
+      },
+    })
+    lastExitCode = result.exitCode
+    if (result.exitCode !== 0) {
+      return {
+        id: gate.id,
+        status: "fail",
+        commands: gate.commands.map(commandLabel),
+        exitCode: result.exitCode,
+        message: `${commandLabel(args)} exited with code ${result.exitCode}`,
+        remediation: gate.remediation,
+      }
+    }
+  }
+  return {
+    id: gate.id,
+    status: "pass",
+    commands: gate.commands.map(commandLabel),
+    ...(lastExitCode === undefined ? {} : { exitCode: lastExitCode }),
+    remediation: gate.remediation,
+  }
+}
+
+const skippedGate = (gate: ReleaseGateSpec, failedId: string): ReleaseGateResult => ({
+  id: gate.id,
+  status: "skipped",
+  commands: gate.commands.map(commandLabel),
+  message: `not run because the ${failedId} gate failed`,
+  remediation: `Fix the ${failedId} gate first, then rerun verification.`,
+})
+
+/** Collect the same gate result rendered by the CLI and used by repository scripts. */
+export async function collectReleaseVerification(
+  start: string,
+  options: ReleaseVerificationOptions = {},
+): Promise<ReleaseVerificationResult> {
+  const mode = options.mode ?? "default"
+  const root = await resolveVerificationRoot(start)
+  const runCommand = options.runCommand ?? runBunCommand
+  const fixtureRoot = mkdtempSync(join(realpathSync(tmpdir()), "nifra-verify-"))
+  const gates: ReleaseGateResult[] = []
+  try {
+    let failedId: string | undefined
+    for (const gate of gatePlan(mode)) {
+      if (failedId !== undefined) {
+        gates.push(skippedGate(gate, failedId))
+        continue
+      }
+      const result = await runGate(root, gate, runCommand, fixtureRoot)
+      gates.push(result)
+      if (result.status === "fail") failedId = result.id
+    }
+  } finally {
+    rmSync(fixtureRoot, { recursive: true, force: true })
+  }
+  return {
+    ok: gates.every((gate) => gate.status === "pass"),
+    mode,
+    gates,
+  }
+}
+
+export function renderReleaseVerification(result: ReleaseVerificationResult): string {
+  const lines = [`nifra verify --${result.mode}`, ""]
+  for (const gate of result.gates) {
+    const marker = gate.status === "pass" ? "✓" : gate.status === "fail" ? "✗" : "-"
+    lines.push(`${marker} ${gate.id}: ${gate.status}`)
+    if (gate.message !== undefined) lines.push(`  ${gate.message}`)
+    if (gate.status !== "pass") lines.push(`  fix: ${gate.remediation}`)
+  }
+  lines.push("", result.ok ? "✓ verification passed" : "✗ verification failed")
+  return lines.join("\n")
+}
+
+/** Run verification and render either the human or machine interface. */
+export async function runReleaseVerification(
+  cwd: string,
+  options: ReleaseVerificationOptions & { readonly json?: boolean } = {},
+): Promise<boolean> {
+  const result = await collectReleaseVerification(cwd, options)
+  if (options.json) console.log(JSON.stringify(result, null, 2))
+  else console.log(renderReleaseVerification(result))
+  return result.ok
+}
+
+if (import.meta.main) {
+  const mode: ReleaseVerificationMode = process.argv.includes("--release") ? "release" : "default"
+  const ok = await runReleaseVerification(process.cwd(), {
+    mode,
+    json: process.argv.includes("--json"),
+  })
+  if (!ok) process.exitCode = 1
+}

package/src/rules/comment-markers.ts

@@ -24,3 +24,39 @@ export function commentBlockHasMarker(
   }
   return false
 }
+
+/**
+ * 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.
+ */
+export function commentBlockMarkerReason(
+  lines: readonly string[],
+  line: number,
+  marker: string,
+): string | undefined {
+  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
+    // A block comment's `*/` closer is not part of the reason.
+    const reason = rest
+      .slice(colon + 1)
+      .replace(/\*\/\s*$/, "")
+      .trim()
+    return reason.length > 0 ? reason : undefined
+  }
+  const onLine = reasonOn(lines[line - 1] ?? "")
+  if (onLine !== undefined) return onLine
+  for (let i = line - 2; i >= 0; i--) {
+    const text = lines[i] ?? ""
+    if (!COMMENT_LINE.test(text)) return undefined
+    const reason = reasonOn(text)
+    if (reason !== undefined) return reason
+  }
+  return undefined
+}

package/src/rules/index.ts

@@ -1,6 +1,9 @@
 import type { Diagnostic } from "../diagnostics.ts"
+import type { ProjectFacts } from "../project-facts.ts"
 import { isBuiltInCode } from "./codes.ts"
 
+export type { ProjectFacts } from "../project-facts.ts"
+
 export interface SourceFile {
   readonly file: string
   readonly content: string
@@ -11,10 +14,6 @@ export interface SourceIndex {
   read(file: string): string | undefined
 }
 
-export interface ProjectFacts {
-  readonly [key: string]: unknown
-}
-
 export interface RuleContext {
   readonly root: string
   readonly sources: SourceIndex

package/src/rules/routes.ts

@@ -3,8 +3,8 @@ import { commentBlockHasMarker } from "./comment-markers.ts"
 import type { CheckRule, RuleContext } from "./index.ts"
 
 /**
- * Route-table lints over the statically collected route registrations (`scanStaticRouteText` in
- * ../check.ts fills `ctx.project.staticRoutes` during the source walk - no second scan here).
+ * Route-table lints over the statically collected route registrations (`ProjectFacts.routes` is built
+ * once before the registry runs - no rule re-walks source).
  *
  * NF-C018 exists because the typed client's proxy intercepts a fixed set of property names before
  * path resolution (`resolveSegment` + the thenable guard in @nifrajs/client): the seven HTTP verbs
@@ -41,20 +41,19 @@ interface StaticRouteFact {
 
 /** Parse-don't-cast over the project fact: a malformed entry is dropped, never trusted. */
 function routeFacts(ctx: RuleContext): StaticRouteFact[] {
-  const raw = ctx.project.staticRoutes
-  if (!Array.isArray(raw)) return []
+  const raw: readonly unknown[] = ctx.project.routes
   const out: StaticRouteFact[] = []
   for (const item of raw) {
-    if (typeof item !== "object" || item === null) continue
-    const record = item as Record<string, unknown>
+    if (typeof item !== "object" || item === null || Array.isArray(item)) continue
+    const record = Object.fromEntries(Object.entries(item))
     if (
-      typeof record.file === "string" &&
-      typeof record.line === "number" &&
-      typeof record.method === "string" &&
-      typeof record.path === "string"
-    ) {
-      out.push({ file: record.file, line: record.line, method: record.method, path: record.path })
-    }
+      typeof record.file !== "string" ||
+      typeof record.line !== "number" ||
+      typeof record.method !== "string" ||
+      typeof record.path !== "string"
+    )
+      continue
+    out.push({ file: record.file, line: record.line, method: record.method, path: record.path })
   }
   return out
 }
@@ -91,7 +90,7 @@ export const reservedSegmentRule: CheckRule = {
         if (collision === undefined) continue
         let lines = linesByFile.get(route.file)
         if (lines === undefined) {
-          lines = (ctx.sources.read(route.file) ?? "").split("\n")
+          lines = (ctx.project.source.read(route.file) ?? "").split("\n")
           linesByFile.set(route.file, lines)
         }
         if (commentBlockHasMarker(lines, route.line, RESERVED_SEGMENT_PRAGMA)) continue

package/src/rules/security.ts

@@ -108,8 +108,8 @@ export const secretComparisonRule: CheckRule = {
     const ts = await importProjectTypeScript(ctx.root)
     if (ts === undefined) return didNotRun("NF-S002", "Non-constant-time secret comparison scan")
     const findings: Diagnostic[] = []
-    for (const file of ctx.sources.files) {
-      const parsed = parsedFile(ts, ctx.sources, file)
+    for (const file of ctx.project.source.files) {
+      const parsed = parsedFile(ts, ctx.project.source, file)
       if (parsed === undefined) continue
       const { tree, lines } = parsed
       const visit = (node: TSApi.Node): void => {
@@ -169,8 +169,8 @@ export const piiLogRule: CheckRule = {
     const ts = await importProjectTypeScript(ctx.root)
     if (ts === undefined) return didNotRun("NF-S003", "Sensitive-value-in-log scan")
     const findings: Diagnostic[] = []
-    for (const file of ctx.sources.files) {
-      const parsed = parsedFile(ts, ctx.sources, file)
+    for (const file of ctx.project.source.files) {
+      const parsed = parsedFile(ts, ctx.project.source, file)
       if (parsed === undefined) continue
       const { tree, lines } = parsed
       const visit = (node: TSApi.Node): void => {
@@ -217,8 +217,8 @@ export const failOpenGateRule: CheckRule = {
     const ts = await importProjectTypeScript(ctx.root)
     if (ts === undefined) return didNotRun("NF-S001", "Fail-open gate scan")
     const findings: Diagnostic[] = []
-    for (const file of ctx.sources.files) {
-      const parsed = parsedFile(ts, ctx.sources, file)
+    for (const file of ctx.project.source.files) {
+      const parsed = parsedFile(ts, ctx.project.source, file)
       if (parsed === undefined) continue
       const { tree, lines } = parsed
       const visit = (node: TSApi.Node): void => {
@@ -284,8 +284,8 @@ export const corsOriginPredicateRule: CheckRule = {
     const ts = await importProjectTypeScript(ctx.root)
     if (ts === undefined) return didNotRun("NF-S004", "CORS origin predicate scan")
     const findings: Diagnostic[] = []
-    for (const file of ctx.sources.files) {
-      const parsed = parsedFile(ts, ctx.sources, file)
+    for (const file of ctx.project.source.files) {
+      const parsed = parsedFile(ts, ctx.project.source, file)
       if (parsed === undefined) continue
       const { tree, lines } = parsed
       const visit = (node: TSApi.Node): void => {
@@ -345,8 +345,8 @@ export const externalRedirectRule: CheckRule = {
     const ts = await importProjectTypeScript(ctx.root)
     if (ts === undefined) return didNotRun("NF-S005", "External redirect opt-out scan")
     const findings: Diagnostic[] = []
-    for (const file of ctx.sources.files) {
-      const parsed = parsedFile(ts, ctx.sources, file)
+    for (const file of ctx.project.source.files) {
+      const parsed = parsedFile(ts, ctx.project.source, file)
       if (parsed === undefined) continue
       const { tree, lines } = parsed
       const visit = (node: TSApi.Node): void => {
@@ -402,8 +402,8 @@ export const assuranceEscapeHatchRule: CheckRule = {
     const ts = await importProjectTypeScript(ctx.root)
     if (ts === undefined) return didNotRun("NF-S006", "Security escape hatch scan")
     const findings: Diagnostic[] = []
-    for (const file of ctx.sources.files) {
-      const parsed = parsedFile(ts, ctx.sources, file)
+    for (const file of ctx.project.source.files) {
+      const parsed = parsedFile(ts, ctx.project.source, file)
       if (parsed === undefined) continue
       const { tree, lines } = parsed
       const visit = (node: TSApi.Node): void => {
@@ -445,8 +445,8 @@ export const unprefixedSecureCookieRule: CheckRule = {
     const ts = await importProjectTypeScript(ctx.root)
     if (ts === undefined) return didNotRun("NF-S007", "Secure cookie prefix scan")
     const findings: Diagnostic[] = []
-    for (const file of ctx.sources.files) {
-      const parsed = parsedFile(ts, ctx.sources, file)
+    for (const file of ctx.project.source.files) {
+      const parsed = parsedFile(ts, ctx.project.source, file)
       if (parsed === undefined) continue
       const { tree } = parsed
       const visit = (node: TSApi.Node): void => {