@nifrajs/cli 2.11.0 → 2.12.1

package/src/replay.ts

@@ -0,0 +1,44 @@
+import { resolve, sep } from "node:path"
+import { type CompatibleReplayFile, parseCompatibleReplayFile } from "@nifrajs/core/replay"
+import { runHydrationAssurance } from "./assure-hydration.ts"
+import { checkContractsLock } from "./contracts.ts"
+
+export interface ReplayResult {
+  readonly ok: boolean
+  readonly replay: CompatibleReplayFile
+  readonly compatible?: boolean
+  readonly error?: string
+  readonly diagnostics?: readonly unknown[]
+  readonly replays?: readonly string[]
+}
+
+/** 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)) {
+    throw new Error("replay file must stay inside the project root")
+  }
+  const replay = parseCompatibleReplayFile(JSON.parse(await Bun.file(path).text()))
+  if ("gate" in replay && replay.gate === "hydration") {
+    const hydration = await runHydrationAssurance(cwd, {
+      seed: replay.seed,
+      ...(replay.case.startsWith("/") ? { routes: [replay.case] } : {}),
+    })
+    return {
+      ok: hydration.diagnostics.length === 0,
+      replay,
+      diagnostics: hydration.diagnostics,
+      ...(hydration.replays === undefined ? {} : { replays: hydration.replays }),
+    }
+  }
+  if ("gate" in replay && replay.gate === "contracts") {
+    const contracts = await checkContractsLock(cwd)
+    return {
+      ok: contracts.present && contracts.diagnostics.length === 0,
+      replay,
+      diagnostics: contracts.diagnostics,
+    }
+  }
+  if (!("gate" in replay)) return { ok: true, replay, compatible: true }
+  return { ok: false, replay, error: `no replay dispatcher for gate ${replay.gate}` }
+}

package/src/rules/codes.ts

@@ -0,0 +1,57 @@
+/** Built-in diagnostic code registry. Codes are append-only and reserved by the NF- prefix. */
+
+export const RULE_CODES = Object.freeze({
+  "NF-C001": "TypeScript contract check",
+  "NF-C002": "Typed client check",
+  "NF-C003": "Untyped client check",
+  "NF-C004": "Server-only import check",
+  "NF-C005": "Removed import check",
+  "NF-C006": "Interpolated SQL check",
+  "NF-C007": "Raw response route advisory",
+  "NF-C008": "Undeclared dependency check",
+  "NF-C009": "Duplicate install check",
+  "NF-C010": "Stale workspace build check",
+  "NF-C011": "Build pipeline check",
+  "NF-C012": "Server manifest drift check",
+  "NF-C013": "Trust manifest drift check",
+  "NF-C014": "Capability assurance check",
+  "NF-C015": "Assurance configuration check",
+  "NF-C016": "Check configuration check",
+  "NF-C017": "Rule pack validation",
+  "NF-C018": "Reserved client segment check",
+  "NF-C019": "Duplicate route registration check",
+  "NF-D001": "Doctor check",
+  "NF-A001": "Assurance bundle check",
+  "NF-H001": "Hydration mismatch",
+  "NF-H002": "Duplicate framework runtime",
+  "NF-H003": "Stale client build",
+  "NF-H004": "Hydration interaction",
+  "NF-K001": "Contract snapshot drift",
+  "NF-S001": "Fail-open gate",
+  "NF-S002": "Non-constant-time secret comparison",
+  "NF-S003": "Sensitive value in log call",
+  "NF-S004": "CORS origin predicate ignores the origin",
+  "NF-S005": "External redirect opt-out",
+  "NF-S006": "Security escape hatch enabled",
+  "NF-S007": "Secure cookie without a __Host-/__Secure- prefix",
+} as const)
+
+/** Codes that no longer fire but remain reserved forever. */
+export const RETIRED_CODES: ReadonlySet<string> = new Set()
+
+export type BuiltInCode = keyof typeof RULE_CODES
+
+export function isBuiltInCode(code: string): code is BuiltInCode {
+  return code in RULE_CODES || RETIRED_CODES.has(code)
+}
+
+export function assertUniqueRuleCodes(): void {
+  const codes = Object.keys(RULE_CODES)
+  if (new Set(codes).size !== codes.length)
+    throw new Error("diagnostic code registry contains duplicates")
+  for (const code of codes) {
+    if (!/^NF-[A-Z]\d{3}$/.test(code)) throw new Error(`invalid built-in diagnostic code: ${code}`)
+  }
+}
+
+assertUniqueRuleCodes()

package/src/rules/comment-markers.ts

@@ -0,0 +1,26 @@
+/**
+ * Marker recognition for in-source escape hatches (`@nifra-gate-reviewed`, `nifra-expect …`).
+ *
+ * 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
+ * multi-line justification the hatch asks for. A blank line or a code line ends the block, so a
+ * marker in an unrelated comment further up never leaks onto a finding below it.
+ */
+
+// Lines that continue a comment block when walking upward: line comments, block-comment
+// open/body/close lines, and the JSX comment form.
+const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*\/|\*|\{\/\*)/
+
+export function commentBlockHasMarker(
+  lines: readonly string[],
+  line: number,
+  marker: string,
+): boolean {
+  if ((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
+    if (text.includes(marker)) return true
+  }
+  return false
+}

package/src/rules/index.ts

@@ -0,0 +1,175 @@
+import type { Diagnostic } from "../diagnostics.ts"
+import { isBuiltInCode } from "./codes.ts"
+
+export interface SourceFile {
+  readonly file: string
+  readonly content: string
+}
+
+export interface SourceIndex {
+  readonly files: readonly string[]
+  read(file: string): string | undefined
+}
+
+export interface ProjectFacts {
+  readonly [key: string]: unknown
+}
+
+export interface RuleContext {
+  readonly root: string
+  readonly sources: SourceIndex
+  readonly project: ProjectFacts
+}
+
+export interface CheckRule {
+  readonly code: string
+  readonly title: string
+  scan(ctx: RuleContext): Promise<readonly Diagnostic[]>
+}
+
+export interface RulePack {
+  readonly name: string
+  readonly rules: readonly CheckRule[]
+}
+
+export function validateRulePacks(packs: readonly RulePack[] | undefined): readonly RulePack[] {
+  if (packs === undefined) return []
+  const names = new Set<string>()
+  const codes = new Set<string>()
+  const normalized: RulePack[] = []
+  for (const pack of packs) {
+    if (typeof pack?.name !== "string" || pack.name.trim() === "")
+      throw new Error("rule pack name must be a non-empty string")
+    if (names.has(pack.name)) throw new Error(`duplicate rule pack: ${pack.name}`)
+    names.add(pack.name)
+    if (!Array.isArray(pack.rules)) throw new Error(`rule pack ${pack.name} must contain rules`)
+    const rules: CheckRule[] = []
+    for (const rule of pack.rules) {
+      if (
+        typeof rule?.code !== "string" ||
+        typeof rule.title !== "string" ||
+        typeof rule.scan !== "function"
+      ) {
+        throw new Error(`rule pack ${pack.name} contains an invalid rule`)
+      }
+      if (rule.code.startsWith("NF-"))
+        throw new Error(`application rule pack code ${rule.code} uses the reserved NF- prefix`)
+      if (codes.has(rule.code)) throw new Error(`duplicate application rule code: ${rule.code}`)
+      codes.add(rule.code)
+      rules.push(rule)
+    }
+    normalized.push(Object.freeze({ name: pack.name, rules: Object.freeze(rules) }))
+  }
+  return Object.freeze(normalized)
+}
+
+export function parseRulePacks(value: unknown): readonly RulePack[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value)) throw new TypeError("rulePacks must be an array")
+  const packs: RulePack[] = []
+  for (const rawPack of value) {
+    if (typeof rawPack !== "object" || rawPack === null || Array.isArray(rawPack))
+      throw new TypeError("rule pack must be an object")
+    const packRecord = Object.fromEntries(Object.entries(rawPack))
+    const name = packRecord.name
+    const rawRules = packRecord.rules
+    if (typeof name !== "string" || !Array.isArray(rawRules))
+      throw new TypeError("rule pack requires a name and rules array")
+    const rules: CheckRule[] = []
+    for (const rawRule of rawRules) {
+      if (typeof rawRule !== "object" || rawRule === null || Array.isArray(rawRule))
+        throw new TypeError(`rule pack ${name} contains an invalid rule`)
+      const ruleRecord = Object.fromEntries(Object.entries(rawRule))
+      if (
+        typeof ruleRecord.code !== "string" ||
+        typeof ruleRecord.title !== "string" ||
+        typeof ruleRecord.scan !== "function"
+      ) {
+        throw new TypeError(`rule pack ${name} contains an invalid rule`)
+      }
+      const scan = ruleRecord.scan
+      rules.push({
+        code: ruleRecord.code,
+        title: ruleRecord.title,
+        scan: async (ctx) => {
+          const result: unknown = await Reflect.apply(scan, undefined, [ctx])
+          if (!Array.isArray(result))
+            throw new TypeError(`rule ${ruleRecord.code} did not return diagnostics`)
+          const findings: Diagnostic[] = []
+          for (const item of result) {
+            if (typeof item !== "object" || item === null || Array.isArray(item))
+              throw new TypeError(`rule ${ruleRecord.code} returned an invalid diagnostic`)
+            const finding = Object.fromEntries(Object.entries(item))
+            if (
+              typeof finding.code !== "string" ||
+              (finding.severity !== "error" &&
+                finding.severity !== "warn" &&
+                finding.severity !== "info") ||
+              typeof finding.message !== "string"
+            ) {
+              throw new TypeError(`rule ${ruleRecord.code} returned an invalid diagnostic`)
+            }
+            const code = finding.code
+            const severity = finding.severity
+            const message = finding.message
+            const rawFix =
+              typeof finding.fix === "object" && finding.fix !== null && !Array.isArray(finding.fix)
+                ? Object.fromEntries(Object.entries(finding.fix))
+                : undefined
+            findings.push({
+              code,
+              severity,
+              message,
+              ...(typeof finding.file === "string" ? { file: finding.file } : {}),
+              ...(typeof finding.line === "number" ? { line: finding.line } : {}),
+              ...(Array.isArray(finding.evidence)
+                ? {
+                    evidence: finding.evidence.filter(
+                      (item): item is string => typeof item === "string",
+                    ),
+                  }
+                : {}),
+              ...(typeof rawFix?.recipe === "string"
+                ? {
+                    fix: {
+                      recipe: rawFix.recipe,
+                      ...(typeof rawFix.command === "string" ? { command: rawFix.command } : {}),
+                    },
+                  }
+                : {}),
+              ...(typeof finding.verify === "string" ? { verify: finding.verify } : {}),
+            })
+          }
+          return findings
+        },
+      })
+    }
+    packs.push({ name, rules })
+  }
+  return validateRulePacks(packs)
+}
+
+export async function runRuleRegistry(
+  ctx: RuleContext,
+  builtIns: readonly CheckRule[],
+  packs: readonly RulePack[] = [],
+): Promise<Diagnostic[]> {
+  const rules = [...builtIns, ...validateRulePacks(packs).flatMap((pack) => pack.rules)]
+  const out: Diagnostic[] = []
+  for (const rule of rules) {
+    if (isBuiltInCode(rule.code) === false && rule.code.startsWith("NF-")) {
+      throw new Error(`application rule pack code ${rule.code} uses the reserved NF- prefix`)
+    }
+    const findings = await rule.scan(ctx)
+    out.push(...findings)
+  }
+  return out
+}
+
+export function sourceIndex(files: readonly SourceFile[]): SourceIndex {
+  const map = new Map(files.map((file) => [file.file, file.content]))
+  return Object.freeze({
+    files: Object.freeze(files.map((file) => file.file)),
+    read: (file: string) => map.get(file),
+  })
+}

package/src/rules/legacy.ts

@@ -0,0 +1,93 @@
+import type { CheckDiagnostic } from "../check.ts"
+import type { Diagnostic, Severity } from "../diagnostics.ts"
+import type { CheckRule, RuleContext } from "./index.ts"
+
+/** Legacy rule name → stable NF- code. Exported so `nifra.check.json` rule overrides can be keyed
+ * by either name and still hit both diagnostic views. */
+export const LEGACY_RULE_CODES: Readonly<Record<string, string>> = Object.freeze({
+  typecheck: "NF-C001",
+  "typed-client": "NF-C002",
+  "untyped-client": "NF-C003",
+  "server-only-import": "NF-C004",
+  "removed-import": "NF-C005",
+  "interpolated-sql": "NF-C006",
+  "response-route": "NF-C007",
+  "undeclared-dependency": "NF-C008",
+  "duplicate-install": "NF-C009",
+  "stale-workspace-dist": "NF-C010",
+  pipeline: "NF-C011",
+  "server-manifest-drift": "NF-C012",
+  "manifest-drift": "NF-C013",
+  "capability-assurance": "NF-C014",
+  "capability-config": "NF-C015",
+  "check-config": "NF-C016",
+  "contract-drift": "NF-K001",
+})
+
+const TITLES: Readonly<Record<string, string>> = Object.freeze({
+  typecheck: "TypeScript contract check",
+  "typed-client": "Typed client check",
+  "untyped-client": "Untyped client check",
+  "server-only-import": "Server-only import check",
+  "removed-import": "Removed import check",
+  "interpolated-sql": "Interpolated SQL check",
+  "response-route": "Raw response route advisory",
+  "undeclared-dependency": "Undeclared dependency check",
+  "duplicate-install": "Duplicate install check",
+  "stale-workspace-dist": "Stale workspace build check",
+  pipeline: "Build pipeline check",
+  "server-manifest-drift": "Server manifest drift check",
+  "manifest-drift": "Trust manifest drift check",
+  "capability-assurance": "Capability assurance check",
+  "capability-config": "Assurance configuration check",
+  "check-config": "Check configuration check",
+  "contract-drift": "Contract snapshot drift",
+})
+
+function recipeFor(finding: CheckDiagnostic): Diagnostic["fix"] {
+  if (finding.rule === "stale-workspace-dist")
+    return { recipe: "workspace-dist.rebuild", command: "nifra fix --code NF-C010" }
+  if (finding.rule === "server-manifest-drift")
+    return { recipe: "manifest.sync", command: "nifra sync-manifest" }
+  if (finding.rule === "contract-drift")
+    return { recipe: "contracts.snapshot", command: "nifra contracts snapshot" }
+  return undefined
+}
+
+function toDiagnostic(finding: CheckDiagnostic, code: string): Diagnostic {
+  const severity: Severity = finding.severity === "warning" ? "warn" : finding.severity
+  const evidence = finding.evidence ?? finding.chain
+  const fix = recipeFor(finding)
+  return Object.freeze({
+    code,
+    severity,
+    message: finding.message,
+    ...(finding.file === undefined ? {} : { file: finding.file }),
+    ...(finding.line === undefined ? {} : { line: finding.line }),
+    ...(evidence === undefined ? {} : { evidence }),
+    ...(fix === undefined ? {} : { fix }),
+    ...(finding.verify === undefined ? {} : { verify: finding.verify }),
+  })
+}
+
+function findingsFor(ctx: RuleContext, rule: string): Diagnostic[] {
+  const findings = ctx.project.legacyDiagnostics
+  if (!Array.isArray(findings)) return []
+  const code = LEGACY_RULE_CODES[rule]
+  if (code === undefined) return []
+  return findings
+    .filter((finding): finding is CheckDiagnostic => finding?.rule === rule)
+    .map((finding) => toDiagnostic(finding, code))
+}
+
+function makeRule(rule: string): CheckRule {
+  const code = LEGACY_RULE_CODES[rule]
+  const title = TITLES[rule]
+  if (code === undefined || title === undefined) throw new Error(`unknown legacy rule ${rule}`)
+  return Object.freeze({ code, title, scan: async (ctx: RuleContext) => findingsFor(ctx, rule) })
+}
+
+/** Stable registry adapters for the existing source scanners. */
+export const legacyRules: readonly CheckRule[] = Object.freeze(
+  Object.keys(LEGACY_RULE_CODES).map((name) => makeRule(name)),
+)

package/src/rules/routes.ts

@@ -0,0 +1,157 @@
+import { type Diagnostic, diagnostic } from "../diagnostics.ts"
+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).
+ *
+ * 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
+ * (case-insensitively), `subscribe`, `ws`, `index`, and `then`. A route whose path contains a
+ * static segment spelling one of these cannot be reached by DOT ACCESS - `api.delete.post` resolves
+ * the DELETE verb, not the path. The typed spelling is a call on the parent node
+ * (`api.api("delete").post()`, treaty.ts `CollisionEscape`), and the client type rejects the dot
+ * access with the same guidance - so the collision is a warning that teaches the escape spelling,
+ * not a blocking error: the route IS reachable, just not by the spelling its name suggests.
+ */
+const RESERVED_VERB_SEGMENTS: ReadonlySet<string> = new Set([
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options",
+])
+// Intercepted by exact match only (`key === "subscribe"` etc.), unlike the lowercased verbs.
+const RESERVED_EXACT_SEGMENTS: ReadonlySet<string> = new Set(["subscribe", "ws", "index", "then"])
+const RESERVED_READOUT =
+  "get/post/put/patch/delete/head/options (any casing), subscribe, ws, index, then"
+
+/** Opt-out pragma for a route deliberately served only to NON-typed-client consumers. */
+const RESERVED_SEGMENT_PRAGMA = "nifra-expect reserved-segment"
+
+interface StaticRouteFact {
+  readonly file: string
+  readonly line: number
+  readonly method: string
+  readonly path: string
+}
+
+/** 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 out: StaticRouteFact[] = []
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) continue
+    const record = item as Record<string, unknown>
+    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 })
+    }
+  }
+  return out
+}
+
+/**
+ * The typed escape spelling for a colliding segment, e.g. `/api/delete` + `delete` →
+ * `api("delete").post()` shown as the chain up to the collision. Best-effort readability: earlier
+ * segments render as dot access, the colliding one as the parent-node call.
+ */
+function routeEscapeHint(path: string, colliding: string): string {
+  const segments = path.split("/").filter((segment) => segment !== "")
+  const before = segments.slice(0, Math.max(segments.indexOf(colliding), 0))
+  return `${["api", ...before].join(".")}("${colliding}")`
+}
+
+/** The reserved key a static path segment collides with, or undefined. Params/wildcards never collide. */
+function reservedCollision(segment: string): string | undefined {
+  if (segment.startsWith(":") || segment.startsWith("*")) return undefined
+  if (RESERVED_EXACT_SEGMENTS.has(segment)) return segment
+  const lower = segment.toLowerCase()
+  return RESERVED_VERB_SEGMENTS.has(lower) ? lower : undefined
+}
+
+export const reservedSegmentRule: CheckRule = {
+  code: "NF-C018",
+  title: "Route segment collides with a reserved client proxy key",
+  async scan(ctx) {
+    const findings: Diagnostic[] = []
+    const linesByFile = new Map<string, readonly string[]>()
+    for (const route of routeFacts(ctx)) {
+      for (const segment of route.path.split("/")) {
+        if (segment === "") continue
+        const collision = reservedCollision(segment)
+        if (collision === undefined) continue
+        let lines = linesByFile.get(route.file)
+        if (lines === undefined) {
+          lines = (ctx.sources.read(route.file) ?? "").split("\n")
+          linesByFile.set(route.file, lines)
+        }
+        if (commentBlockHasMarker(lines, route.line, RESERVED_SEGMENT_PRAGMA)) continue
+        findings.push(
+          diagnostic({
+            code: "NF-C018",
+            severity: "warn",
+            file: route.file,
+            line: route.line,
+            message: `${route.method} ${route.path} - segment '${segment}' collides with the reserved client proxy key '${collision}' (reserved: ${RESERVED_READOUT}); dot access cannot reach it - call the parent node with the segment instead (\`${routeEscapeHint(route.path, segment)}\`), rename the segment, or mark an intentionally non-typed-client route with \`// ${RESERVED_SEGMENT_PRAGMA}\` above the registration`,
+            evidence: [`${route.method} ${route.path}`, `segment: ${segment}`],
+            verify: "nifra check --lints-only",
+          }),
+        )
+        break // one finding per route, even if several segments collide
+      }
+    }
+    return findings
+  },
+}
+
+/**
+ * NF-C019: the same method+path registered twice in one file - the later registration is dead or
+ * shadowing, and which one serves is a router implementation detail nobody should depend on.
+ * Scoped to a single file on purpose: two different apps in one repo (a monorepo with several
+ * backends) legitimately both register `GET /health`, and this scanner cannot tell app instances
+ * apart across files - so cross-file duplicates are NOT flagged rather than guessed at.
+ */
+export const duplicateRouteRule: CheckRule = {
+  code: "NF-C019",
+  title: "Duplicate route registration",
+  async scan(ctx) {
+    const findings: Diagnostic[] = []
+    const byFile = new Map<string, Map<string, StaticRouteFact>>()
+    for (const route of routeFacts(ctx)) {
+      let seen = byFile.get(route.file)
+      if (seen === undefined) {
+        seen = new Map()
+        byFile.set(route.file, seen)
+      }
+      const key = `${route.method} ${route.path}`
+      const first = seen.get(key)
+      if (first === undefined) {
+        seen.set(key, route)
+        continue
+      }
+      findings.push(
+        diagnostic({
+          code: "NF-C019",
+          severity: "error",
+          file: route.file,
+          line: route.line,
+          message: `${key} is registered twice in this file (first at line ${first.line}) - remove or rename one; which registration serves is undefined`,
+          evidence: [key, `first registration: line ${first.line}`],
+          verify: "nifra check --lints-only",
+        }),
+      )
+    }
+    return findings
+  },
+}
+
+export const routeRules = Object.freeze([reservedSegmentRule, duplicateRouteRule])