@nifrajs/cli 3.5.0 → 4.0.0

package/src/route-types.ts

@@ -0,0 +1,133 @@
+/**
+ * `nifra types`: the generated `./+types/<route>` modules (see `@nifrajs/web/route-types`), plus the one
+ * tsconfig line that lets routes import them. `nifra dev`, `nifra build` and `nifra check` refresh them
+ * too, so a fresh checkout type-checks without running this by hand.
+ */
+import { existsSync, readFileSync, watch } from "node:fs"
+import { dirname, join, relative, resolve } from "node:path"
+import { ROUTE_TYPES_DIR, staleRouteTypes, writeRouteTypes } from "@nifrajs/web/route-types"
+import { stripComments } from "./check-scan.ts"
+
+export interface RouteTypesReport {
+  readonly ok: boolean
+  readonly check: boolean
+  /** Files written (or, with `check`, that would be). */
+  readonly written: readonly string[]
+  readonly removed: readonly string[]
+  /** With `check`: every generated file missing, out of date, or no longer generated. */
+  readonly stale: readonly string[]
+  /** Set when tsconfig does not merge `.nifra/types` in through `rootDirs`. */
+  readonly tsconfig?: string
+}
+
+const TSCONFIG_HINT = `add "rootDirs": [".", "./${ROUTE_TYPES_DIR}"] to compilerOptions in tsconfig.json, so a route can import ./+types/<name>`
+
+/** A tsconfig's JSONC as an object, following relative `extends`, or `undefined` when unreadable. */
+function readTsconfig(
+  path: string,
+  depth = 0,
+): { compilerOptions?: Record<string, unknown> } | undefined {
+  if (depth > 8 || !existsSync(path)) return undefined
+  try {
+    const text = stripComments(readFileSync(path, "utf8")).replace(/,(\s*[}\]])/g, "$1")
+    const config = JSON.parse(text) as {
+      extends?: unknown
+      compilerOptions?: Record<string, unknown>
+    }
+    if (config.compilerOptions?.rootDirs !== undefined || typeof config.extends !== "string") {
+      return config
+    }
+    if (!config.extends.startsWith(".")) return config
+    const base = config.extends.endsWith(".json") ? config.extends : `${config.extends}.json`
+    const parent = readTsconfig(resolve(dirname(path), base), depth + 1)
+    return { compilerOptions: { ...parent?.compilerOptions, ...config.compilerOptions } }
+  } catch {
+    return undefined
+  }
+}
+
+/** Why the app's tsconfig cannot resolve `./+types/<name>`, or `undefined` when it can. */
+export function routeTypesTsconfigIssue(appRoot: string): string | undefined {
+  const tsconfig = join(appRoot, "tsconfig.json")
+  if (!existsSync(tsconfig)) return undefined
+  const rootDirs = readTsconfig(tsconfig)?.compilerOptions?.rootDirs
+  const merged =
+    Array.isArray(rootDirs) &&
+    rootDirs.some(
+      (dir) =>
+        typeof dir === "string" && resolve(appRoot, dir) === resolve(appRoot, ROUTE_TYPES_DIR),
+    )
+  return merged ? undefined : TSCONFIG_HINT
+}
+
+const appRelative = (appRoot: string, paths: readonly string[]): string[] =>
+  paths.map((path) => relative(appRoot, path).replaceAll("\\", "/"))
+
+/** Generate (or, with `check`, verify) an app's route types. */
+export function routeTypes(
+  appRoot: string,
+  options: { readonly check?: boolean } = {},
+): RouteTypesReport {
+  const tsconfig = routeTypesTsconfigIssue(appRoot)
+  const extra = tsconfig === undefined ? {} : { tsconfig }
+  if (options.check === true) {
+    const stale = appRelative(appRoot, staleRouteTypes({ appRoot }))
+    return { ok: stale.length === 0, check: true, written: [], removed: [], stale, ...extra }
+  }
+  const { written, removed } = writeRouteTypes({ appRoot })
+  return {
+    ok: true,
+    check: false,
+    written: appRelative(appRoot, written),
+    removed: appRelative(appRoot, removed),
+    stale: [],
+    ...extra,
+  }
+}
+
+/**
+ * Refresh route types before a command that type-checks or bundles; quiet unless something changed.
+ * Never throws: a routes tree the generator cannot read is the command's own error to report.
+ */
+export function refreshRouteTypes(
+  appRoot: string,
+  log: (line: string) => void = console.log,
+): void {
+  if (!existsSync(join(appRoot, "routes"))) return
+  let report: RouteTypesReport
+  try {
+    report = routeTypes(appRoot)
+  } catch (error) {
+    log(`[nifra] route types: ${error instanceof Error ? error.message : String(error)}`)
+    return
+  }
+  const { written, removed, tsconfig } = report
+  if (written.length + removed.length > 0) {
+    log(
+      `[nifra] route types: ${written.length} written, ${removed.length} removed in ${ROUTE_TYPES_DIR}`,
+    )
+  }
+  if (tsconfig !== undefined) log(`[nifra] route types: ${tsconfig}`)
+}
+
+/**
+ * Keep route types current while `nifra dev` runs: they depend only on which route files exist, so a
+ * route added or removed (or `backend/app.ts` appearing) regenerates them. Returns the stop function.
+ */
+export function watchRouteTypes(appRoot: string): () => void {
+  const routes = join(appRoot, "routes")
+  if (!existsSync(routes)) return () => {}
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const schedule = (): void => {
+    clearTimeout(timer)
+    timer = setTimeout(() => refreshRouteTypes(appRoot), 50)
+  }
+  // Not persistent: the dev server's own shutdown must not wait on this watcher.
+  const watchers = [watch(routes, { recursive: true, persistent: false }, schedule)]
+  const backend = join(appRoot, "backend")
+  if (existsSync(backend)) watchers.push(watch(backend, { persistent: false }, schedule))
+  return () => {
+    clearTimeout(timer)
+    for (const watcher of watchers) watcher.close()
+  }
+}

package/src/rules/codes.ts

@@ -20,6 +20,15 @@ export const RULE_CODES = Object.freeze({
   "NF-C017": "Rule pack validation",
   "NF-C018": "Reserved client segment check",
   "NF-C019": "Duplicate route registration check",
+  "NF-C024": "Overlapping route registration check",
+  "NF-C025": "Route overlap analysis budget check",
+  "NF-C026": "Route param modifier check",
+  "NF-C027": "Page route under the backend mount",
+  "NF-C028": "Zone import check",
+  "NF-C029": "Private environment read in browser code",
+  "NF-C030": "Route data without an output schema",
+  "NF-C031": "Sensitive field in an output schema",
+  "NF-C032": "Credential in browser code",
   "NF-C020": "Island enhancer cleanup check",
   "NF-C021": "nano binding cleanup check",
   "NF-C022": "nano bindList key check",

package/src/rules/data-guard.ts

@@ -0,0 +1,230 @@
+/**
+ * NF-C030 and NF-C031: the data guard, checked from source.
+ *
+ * The server enforces both at runtime, on every request: data a loader or action returns without an
+ * output schema fails the request, and an output schema naming a sensitive field without
+ * `t.declassified` fails the route when it loads. These report what source alone shows, before a
+ * request ever does. NF-C030 is a warning because only running the loader proves it returns data.
+ */
+import { isSensitiveFieldName } from "@nifrajs/web/zones"
+import { codePositionMask } from "../check-scan.ts"
+import { type Diagnostic, diagnostic } from "../diagnostics.ts"
+import { codeUnitOrder } from "../internal/code-unit-order.ts"
+import type { CheckRule } from "./index.ts"
+import { zonedFiles } from "./zones.ts"
+
+const lineAt = (text: string, index: number): number => text.slice(0, index).split("\n").length
+
+const byPlace = (a: Diagnostic, b: Diagnostic): number =>
+  codeUnitOrder(a.file ?? "", b.file ?? "") || (a.line ?? 0) - (b.line ?? 0)
+
+const exported = (mask: string, name: string): RegExpExecArray | null =>
+  new RegExp(
+    `\\bexport\\s+(?:(?:async\\s+)?function\\s*\\*?\\s*|(?:const|let|var)\\s+)${name}\\b|\\bexport\\s*\\{[^}]*\\b${name}\\b[^}]*\\}`,
+  ).exec(mask)
+
+/** A return that hands the browser nothing: a bare return, a redirect, a status, a thrown signal. */
+const CONTROL_FLOW =
+  /^(?:;|$|null\b|undefined\b|redirect\s*\(|notFound\s*\(|gone\s*\(|statusPage\s*\(|new\s+Response\s*\(|Response\s*\.)/
+
+const closing = (mask: string, open: number): number => {
+  let depth = 0
+  for (let i = open; i < mask.length; i++) {
+    const c = mask[i]
+    if (c === "(" || c === "{" || c === "[") depth++
+    else if (c === ")" || c === "}" || c === "]") {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+  return mask.length
+}
+
+/**
+ * Whether the function exported as `name` may return data, read from its type-stripped source: an
+ * arrow's expression body, or a `return <value>` that is not a redirect or a status.
+ */
+function mayReturnData(js: string, name: string): boolean {
+  const mask = codePositionMask(js)
+  const found = exported(mask, name)
+  if (found === null || found[0].startsWith("export {") || found[0].startsWith("export{")) {
+    return true // declared elsewhere in the file and re-exported: assume it does
+  }
+  const params = mask.indexOf("(", found.index + found[0].length)
+  if (params === -1) return true
+  let at = closing(mask, params) + 1
+  while (/\s/.test(mask[at] ?? "")) at++
+  if (mask.startsWith("=>", at)) {
+    at += 2
+    while (/\s/.test(mask[at] ?? "")) at++
+    if (mask[at] !== "{") return !CONTROL_FLOW.test(js.slice(at, at + 40))
+  }
+  if (mask[at] !== "{") return true
+  const body = mask.slice(at, closing(mask, at))
+  for (const match of body.matchAll(/\breturn\b/g)) {
+    const from = at + match.index + "return".length
+    const rest = js.slice(from, from + 40).replace(/^[ \t]+/, "")
+    if (!CONTROL_FLOW.test(rest)) return true
+  }
+  return false
+}
+
+/** Where an expression starting at `start` ends: a `,`, `;` or closer at its own depth. */
+function expressionEnd(mask: string, start: number): number {
+  let depth = 0
+  for (let i = start; i < mask.length; i++) {
+    const c = mask[i]
+    if (c === "(" || c === "{" || c === "[") depth++
+    else if (c === ")" || c === "}" || c === "]") {
+      if (depth === 0) return i
+      depth--
+    } else if (depth === 0 && (c === "," || c === ";")) return i
+    else if (depth === 0 && c === "\n") {
+      const next = /\S/.exec(mask.slice(i))?.[0]
+      const prev = /\S(?=\s*$)/.exec(mask.slice(start, i))?.[0]
+      if (
+        next !== undefined &&
+        !".?:+-*/&|".includes(next) &&
+        !"=(,[{:?+-*/&|".includes(prev ?? "")
+      ) {
+        return i
+      }
+    }
+  }
+  return mask.length
+}
+
+/** Object keys inside `[start, end)` whose name is sensitive and whose value is not declassified. */
+function sensitiveKeys(
+  src: string,
+  mask: string,
+  start: number,
+  end: number,
+): Array<{ readonly key: string; readonly index: number }> {
+  const found: Array<{ key: string; index: number }> = []
+  for (
+    let colon = mask.indexOf(":", start);
+    colon !== -1 && colon < end;
+    colon = mask.indexOf(":", colon + 1)
+  ) {
+    let k = colon - 1
+    while (k >= start && /\s/.test(src[k] ?? "")) k--
+    let key: string
+    let keyStart: number
+    if (/[\w$]/.test(mask[k] ?? "")) {
+      keyStart = k
+      while (keyStart > start && /[\w$]/.test(mask[keyStart - 1] ?? "")) keyStart--
+      key = mask.slice(keyStart, k + 1)
+    } else if (src[k] === '"' || src[k] === "'") {
+      keyStart = src.lastIndexOf(src[k] as string, k - 1)
+      if (keyStart < start) continue
+      key = src.slice(keyStart + 1, k)
+    } else continue
+    let p = keyStart - 1
+    while (p >= start && /\s/.test(mask[p] ?? "")) p--
+    if (mask[p] !== "{" && mask[p] !== ",") continue
+    if (!isSensitiveFieldName(key)) continue
+    const value = src.slice(colon + 1, colon + 80).trimStart()
+    if (/^[\w$.]*declassified\s*\(/.test(value)) continue
+    found.push({ key, index: keyStart })
+  }
+  return found
+}
+
+export interface MissingOutputSchema {
+  readonly name: "loader" | "action"
+  readonly schema: "loaderOutput" | "actionOutput"
+  readonly line: number
+}
+
+let transpiler: Bun.Transpiler | undefined
+
+/** The loader and action a route's backend half exports, may return data from, and gives no schema. */
+export function missingOutputSchemas(content: string): MissingOutputSchema[] {
+  const mask = codePositionMask(content)
+  const missing: MissingOutputSchema[] = []
+  let js: string | undefined
+  for (const [name, schema] of [
+    ["loader", "loaderOutput"],
+    ["action", "actionOutput"],
+  ] as const) {
+    const fn = exported(mask, name)
+    if (fn === null || exported(mask, schema) !== null) continue
+    try {
+      transpiler ??= new Bun.Transpiler({ loader: "ts" })
+      js ??= transpiler.transformSync(content)
+    } catch {
+      js = content
+    }
+    if (mayReturnData(js, name)) missing.push({ name, schema, line: lineAt(content, fn.index) })
+  }
+  return missing
+}
+
+export const missingOutputRule: CheckRule = {
+  code: "NF-C030",
+  title: "Route data without an output schema",
+  async scan(ctx) {
+    const findings: Diagnostic[] = []
+    for (const { file, classification } of zonedFiles(ctx).files) {
+      if (classification.zone !== "route-backend") continue
+      const content = ctx.sources.read(file)
+      if (content === undefined) continue
+      for (const { name, schema, line } of missingOutputSchemas(content)) {
+        findings.push(
+          diagnostic({
+            code: "NF-C030",
+            severity: "warn",
+            file,
+            line,
+            message: `${file} exports a ${name} but no ${schema}. Data it returns fails the request: everything sent to the browser needs an output schema. Export one: export const ${schema} = t.object({ ... })`,
+            evidence: [`export: ${name}`, `missing: ${schema}`],
+            verify: "nifra check",
+          }),
+        )
+      }
+    }
+    return findings.sort(byPlace)
+  },
+}
+
+const OUTPUT_DECLARATION =
+  /\bexport\s+(?:const|let|var)\s+(?:loaderOutput|actionOutput)\b[^=]*=|\boutput\s*:/g
+
+export const sensitiveOutputRule: CheckRule = {
+  code: "NF-C031",
+  title: "Sensitive field in an output schema",
+  async scan(ctx) {
+    const findings: Diagnostic[] = []
+    for (const { file, classification } of zonedFiles(ctx).files) {
+      if (classification.zone !== "route-backend" && classification.zone !== "fn") continue
+      const content = ctx.sources.read(file)
+      if (content === undefined) continue
+      const mask = codePositionMask(content)
+      for (const declaration of mask.matchAll(OUTPUT_DECLARATION)) {
+        const start = declaration.index + declaration[0].length
+        for (const { key, index } of sensitiveKeys(
+          content,
+          mask,
+          start,
+          expressionEnd(mask, start),
+        )) {
+          findings.push(
+            diagnostic({
+              code: "NF-C031",
+              severity: "error",
+              file,
+              line: lineAt(content, index),
+              message: `${file} declares "${key}" in an output schema, a field name that usually holds a credential or personal identifier. Remove it, or wrap its schema in t.declassified("why it may reach the browser", ...)`,
+              evidence: [`field: ${key}`],
+              verify: "nifra check",
+            }),
+          )
+        }
+      }
+    }
+    return findings.sort(byPlace)
+  },
+}
+
+export const dataGuardRules = Object.freeze([missingOutputRule, sensitiveOutputRule])

package/src/rules/index.ts

@@ -1,6 +1,8 @@
 import type { Diagnostic } from "../diagnostics.ts"
+import type { TypeScriptSession } from "../internal/typescript-import.ts"
 import type { ProjectFacts } from "../project-facts.ts"
 import { isBuiltInCode } from "./codes.ts"
+import { releaseRuleTypeScript, retainRuleTypeScript } from "./typescript.ts"
 
 export type { ProjectFacts } from "../project-facts.ts"
 
@@ -18,6 +20,8 @@ export interface RuleContext {
   readonly root: string
   readonly sources: SourceIndex
   readonly project: ProjectFacts
+  /** One compiler session shared by every AST-backed rule in a check. */
+  readonly typescriptSession?: TypeScriptSession
 }
 
 export interface CheckRule {
@@ -155,12 +159,21 @@ export async function runRuleRegistry(
 ): 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 ownsTypeScriptSession =
+    ctx.typescriptSession === undefined &&
+    ctx.project.check.unsupportedTypeScriptVersion === undefined &&
+    rules.some((rule) => isBuiltInCode(rule.code) || rule.code.startsWith("NF-"))
+  if (ownsTypeScriptSession) retainRuleTypeScript(ctx)
+  try {
+    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)
     }
-    const findings = await rule.scan(ctx)
-    out.push(...findings)
+  } finally {
+    if (ownsTypeScriptSession) await releaseRuleTypeScript(ctx)
   }
   return out
 }

package/src/rules/islands.ts

@@ -1,7 +1,8 @@
 import type * as TSApi from "typescript"
 import { type Diagnostic, diagnostic } from "../diagnostics.ts"
-import { importProjectTypeScript } from "../internal/typescript-import.ts"
+import { scriptKindOf } from "../internal/script-kind.ts"
 import type { CheckRule, SourceIndex } from "./index.ts"
+import { loadRuleTypeScript } from "./typescript.ts"
 
 /**
  * NF-C020 - the island cleanup lint. An island enhancer (`@nifrajs/web/islands`) runs once and must
@@ -43,8 +44,13 @@ function parsedTree(
     files.set(file, null)
     return undefined
   }
-  const kind = /\.tsx?$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.JS
-  const tree = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, kind)
+  const tree = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    scriptKindOf(ts, file),
+  )
   files.set(file, { tree })
   return tree
 }
@@ -126,7 +132,9 @@ export const islandCleanupRule: CheckRule = {
   code: "NF-C020",
   title: "Island enhancer cleanup check",
   async scan(ctx) {
-    const ts = await importProjectTypeScript(ctx.root)
+    const loaded = await loadRuleTypeScript(ctx)
+    if (loaded.diagnostics !== undefined) return loaded.diagnostics
+    const ts = loaded.compiler
     if (ts === undefined) {
       return [
         diagnostic({