@nifrajs/cli 3.3.0 → 4.0.0

package/src/rules/nano.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"
 
 /**
  * The nano lane lints (`@nifrajs/web/nano`). nano is deliberately explicit - every reactive edge is a
@@ -38,8 +39,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
 }
@@ -165,7 +171,9 @@ export const nanoBindCleanupRule: CheckRule = {
   code: "NF-C021",
   title: "nano binding 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 [toolchainMissing("NF-C021")]
     const findings: Diagnostic[] = []
     for (const file of ctx.project.source.files) {
@@ -205,7 +213,9 @@ export const nanoListKeyRule: CheckRule = {
   code: "NF-C022",
   title: "nano bindList key 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 [toolchainMissing("NF-C022")]
     const findings: Diagnostic[] = []
     for (const file of ctx.project.source.files) {
@@ -246,7 +256,9 @@ export const nanoComputedDepsRule: CheckRule = {
   code: "NF-C023",
   title: "nano computed deps 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 [toolchainMissing("NF-C023")]
     const findings: Diagnostic[] = []
     for (const file of ctx.project.source.files) {

package/src/rules/pages.ts

@@ -0,0 +1,99 @@
+/**
+ * NF-C027: a page file whose URL sits under the backend's mount path.
+ *
+ * `backend/app.ts`'s backend is mounted at `apiPrefix` (default `/api`) ahead of page routing, and
+ * its 404 is final, so `routes/api/report.tsx` never renders - every request for it gets the
+ * backend's 404. `createWebApp` refuses such an app at startup and `nifra build` refuses to build
+ * it; this reports it earlier, without running app code (check's pre-`loadApp` invariant): the
+ * routes come from a scan of `routes/`, and `apiPrefix` is read only when backend/framework.ts
+ * declares it as a string literal.
+ *
+ * Mounts other than the backend's hold `app` objects no static read can see, so they are left to the
+ * startup and build checks.
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { discoverRoutes } from "@nifrajs/web/fs"
+import { shadowedPages } from "@nifrajs/web/route-manifest"
+import { BACKEND_APP_FILE, CONFIG_FILE, FRAMEWORK_FILE } from "../app-files.ts"
+import { stripComments } from "../check-scan.ts"
+import { type Diagnostic, diagnostic } from "../diagnostics.ts"
+import type { CheckRule } from "./index.ts"
+
+/** What a static read of a framework config says about `apiPrefix`. */
+export type StaticApiPrefix =
+  | { readonly kind: "default" }
+  | { readonly kind: "literal"; readonly value: string }
+  | { readonly kind: "unreadable" }
+
+const LITERAL_EXPORT =
+  /\bexport\s+const\s+apiPrefix\s*(?::\s*string\s*)?=\s*(?:"([^"\\\r\n]*)"|'([^'\\\r\n]*)')\s*(?:as\s+const\s*)?(?:;|\r?\n|$)/
+const MENTION = /\bapiPrefix\b/
+const BACKEND_EXPORT =
+  /\bexport\s+(?:const|let|var|function|class)\s+backend\b|\bexport\s*\{[^}]*\bbackend\b[^}]*\}/
+
+/** Read `apiPrefix` from a framework config's source without running it. Pure. */
+export function readStaticApiPrefix(source: string): StaticApiPrefix {
+  const code = stripComments(source)
+  const literal = LITERAL_EXPORT.exec(code)
+  if (literal !== null) return { kind: "literal", value: literal[1] ?? literal[2] ?? "" }
+  return MENTION.test(code) ? { kind: "unreadable" } : { kind: "default" }
+}
+
+const CONFIG_FILES = [FRAMEWORK_FILE, CONFIG_FILE] as const
+
+export const shadowedPageRule: CheckRule = {
+  code: "NF-C027",
+  title: "Page route under the backend mount",
+  async scan(ctx) {
+    const backendFile = join(ctx.root, BACKEND_APP_FILE)
+    const routesDir = join(ctx.root, "routes")
+    if (!existsSync(backendFile) || !existsSync(routesDir)) return []
+    if (!BACKEND_EXPORT.test(stripComments(readFileSync(backendFile, "utf8")))) return []
+
+    let apiPrefix = "/api"
+    // backend/framework.ts first: the generated server entry imports from it, and the build refuses
+    // a nifra.config.ts whose forwarded fields differ from it.
+    const configFile = CONFIG_FILES.find((file) => existsSync(join(ctx.root, file)))
+    if (configFile !== undefined) {
+      const read = readStaticApiPrefix(readFileSync(join(ctx.root, configFile), "utf8"))
+      if (read.kind === "unreadable") {
+        return [
+          diagnostic({
+            code: "NF-C027",
+            severity: "info",
+            file: configFile,
+            message: `apiPrefix in ${configFile} is not a string literal, so check cannot tell which page routes sit under the backend mount; createWebApp still refuses a page under it at startup, and nifra build at build time`,
+            verify: "nifra build",
+          }),
+        ]
+      }
+      if (read.kind === "literal") apiPrefix = read.value
+    }
+    if (apiPrefix === "") return []
+
+    let manifest: ReturnType<typeof discoverRoutes>
+    try {
+      manifest = discoverRoutes(routesDir)
+    } catch {
+      // A routes/ tree the manifest refuses fails dev and build with its own error.
+      return []
+    }
+    const findings: Diagnostic[] = []
+    for (const page of shadowedPages(manifest, [apiPrefix])) {
+      findings.push(
+        diagnostic({
+          code: "NF-C027",
+          severity: "error",
+          file: `routes/${page.file}`,
+          message: `routes/${page.file} serves ${page.pattern}, under the backend mounted at ${page.mount} - the backend answers every request there before page routing and its 404 is final, so this page can never render. Move the file out of ${page.mount}, serve the URL from backend/app.ts, or change the mount path with \`export const apiPrefix = "/backend"\` in backend/framework.ts`,
+          evidence: [`page: ${page.pattern}`, `mount: ${page.mount}`],
+          verify: "nifra check",
+        }),
+      )
+    }
+    return findings
+  },
+}
+
+export const pageRules = Object.freeze([shadowedPageRule])

package/src/rules/routes.ts

@@ -1,4 +1,6 @@
 import { RESERVED_KEY_READOUT, reservedKeyFor } from "@nifrajs/client"
+import { RoutePatternOverlapLimitError, routePatternOverlap } from "@nifrajs/core"
+import { expandOptionalParams, paramConstraint } from "@nifrajs/core/pattern"
 import { type Diagnostic, diagnostic } from "../diagnostics.ts"
 import { commentBlockHasMarker } from "./comment-markers.ts"
 import type { CheckRule, RuleContext } from "./index.ts"
@@ -23,6 +25,8 @@ import type { CheckRule, RuleContext } from "./index.ts"
 
 /** Opt-out pragma for a route deliberately served only to NON-typed-client consumers. */
 const RESERVED_SEGMENT_PRAGMA = "nifra-expect reserved-segment"
+const ROUTE_OVERLAP_PRAGMA = "nifra-expect route-overlap"
+const PARAM_MODIFIER_PRAGMA = "nifra-expect param-modifier"
 
 interface StaticRouteFact {
   readonly file: string
@@ -50,6 +54,17 @@ function routeFacts(ctx: RuleContext): StaticRouteFact[] {
   return out
 }
 
+/** One fact per registration site, so `all()` or `method([...])` reports its path once, not per method. */
+function pathSites(routes: readonly StaticRouteFact[]): StaticRouteFact[] {
+  const seen = new Set<string>()
+  return routes.filter((route) => {
+    const site = `${route.file}\n${route.line}\n${route.path}`
+    if (seen.has(site)) return false
+    seen.add(site)
+    return true
+  })
+}
+
 /**
  * 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
@@ -67,7 +82,7 @@ export const reservedSegmentRule: CheckRule = {
   async scan(ctx) {
     const findings: Diagnostic[] = []
     const linesByFile = new Map<string, readonly string[]>()
-    for (const route of routeFacts(ctx)) {
+    for (const route of pathSites(routeFacts(ctx))) {
       for (const segment of route.path.split("/")) {
         if (segment === "") continue
         const collision = reservedKeyFor(segment)
@@ -112,6 +127,9 @@ export const duplicateRouteRule: CheckRule = {
   async scan(ctx) {
     const findings: Diagnostic[] = []
     const byFile = new Map<string, Map<string, StaticRouteFact>>()
+    // Two calls that each register several methods collide once per shared method; that is one
+    // pair of lines to fix, so it is reported once.
+    const reported = new Set<string>()
     for (const route of routeFacts(ctx)) {
       let seen = byFile.get(route.file)
       if (seen === undefined) {
@@ -124,6 +142,9 @@ export const duplicateRouteRule: CheckRule = {
         seen.set(key, route)
         continue
       }
+      const pair = `${route.file}\n${route.line}\n${first.line}\n${route.path}`
+      if (reported.has(pair)) continue
+      reported.add(pair)
       findings.push(
         diagnostic({
           code: "NF-C019",
@@ -140,4 +161,162 @@ export const duplicateRouteRule: CheckRule = {
   },
 }
 
-export const routeRules = Object.freeze([reservedSegmentRule, duplicateRouteRule])
+/**
+ * NF-C024: two different same-method route patterns in one source file accept at least one of the
+ * same paths. This is deliberately file-scoped, like NF-C019: the static scanner cannot prove
+ * which application instance owns routes collected from different files in a monorepo.
+ */
+export const overlappingRouteRule: CheckRule = {
+  code: "NF-C024",
+  title: "Overlapping route registration",
+  async scan(ctx) {
+    const findings: Diagnostic[] = []
+    const linesByFile = new Map<string, readonly string[]>()
+    const byFile = new Map<string, StaticRouteFact[]>()
+    for (const route of routeFacts(ctx)) {
+      const routes = byFile.get(route.file)
+      if (routes === undefined) byFile.set(route.file, [route])
+      else routes.push(route)
+    }
+
+    // As in NF-C019: two multi-method calls overlap once per shared method, reported once.
+    const reported = new Set<string>()
+    for (const [file, routes] of byFile) {
+      const lines = (): readonly string[] => {
+        let value = linesByFile.get(file)
+        if (value === undefined) {
+          value = (ctx.project.source.read(file) ?? "").split("\n")
+          linesByFile.set(file, value)
+        }
+        return value
+      }
+
+      for (let laterIndex = 0; laterIndex < routes.length; laterIndex += 1) {
+        const later = routes[laterIndex]!
+        const laterKey = `${later.method} ${later.path}`
+        for (let earlierIndex = 0; earlierIndex < laterIndex; earlierIndex += 1) {
+          const earlier = routes[earlierIndex]!
+          if (earlier.method !== later.method || `${earlier.method} ${earlier.path}` === laterKey)
+            continue
+          if (commentBlockHasMarker(lines(), later.line, ROUTE_OVERLAP_PRAGMA)) continue
+          if (commentBlockHasMarker(lines(), earlier.line, ROUTE_OVERLAP_PRAGMA)) continue
+
+          let witness: string | undefined
+          try {
+            witness = routePatternOverlap(earlier.path, later.path)
+          } catch (error) {
+            if (error instanceof RoutePatternOverlapLimitError) {
+              findings.push(
+                diagnostic({
+                  code: "NF-C025",
+                  severity: "error",
+                  file: later.file,
+                  line: later.line,
+                  message: `${laterKey} could not be proven disjoint from ${earlier.method} ${earlier.path}; bounded route-overlap analysis exceeded its safety budget - simplify the patterns or add the ${ROUTE_OVERLAP_PRAGMA} comment only after manual review`,
+                  evidence: [
+                    `${earlier.method} ${earlier.path}`,
+                    `${later.method} ${later.path}`,
+                    `first registration: line ${earlier.line}`,
+                  ],
+                  verify: "nifra check --lints-only",
+                }),
+              )
+            }
+            // The primary route parser diagnostic owns malformed route patterns. A secondary lint
+            // must remain total and never turn an invalid route into a checker crash.
+            continue
+          }
+          if (witness === undefined) continue
+          const pair = `${file}\n${later.line}\n${later.path}\n${earlier.line}\n${earlier.path}`
+          if (reported.has(pair)) break
+          reported.add(pair)
+
+          findings.push(
+            diagnostic({
+              code: "NF-C024",
+              severity: "error",
+              file: later.file,
+              line: later.line,
+              message: `${laterKey} overlaps ${earlier.method} ${earlier.path} (first at line ${earlier.line}); witness path: ${witness} - make the patterns disjoint, order them intentionally with a pragma, or add the ${ROUTE_OVERLAP_PRAGMA} comment above either registration`,
+              evidence: [
+                `${earlier.method} ${earlier.path}`,
+                `${later.method} ${later.path}`,
+                `witness: ${witness}`,
+                `first registration: line ${earlier.line}`,
+              ],
+              verify: "nifra check --lints-only",
+            }),
+          )
+          break
+        }
+      }
+    }
+    return findings
+  },
+}
+
+/** A param name directly followed by a character other routers read as a modifier. */
+const PARAM_MODIFIER = /:[A-Za-z_][A-Za-z0-9_]*[?*+{(<]/g
+
+/**
+ * The first param in `path` whose modifier the router reads as literal text. A `{...}` group the
+ * router reads as a constraint (`:id{[0-9]+}`, `:ext{png|jpg}`) is syntax, so it is passed over.
+ */
+function literalModifier(path: string): string | undefined {
+  PARAM_MODIFIER.lastIndex = 0
+  for (let found = PARAM_MODIFIER.exec(path); found !== null; found = PARAM_MODIFIER.exec(path)) {
+    const text = found[0]
+    if (!text.endsWith("{")) return text
+    const constraint = paramConstraint(path.slice(PARAM_MODIFIER.lastIndex - 1))
+    if (constraint === undefined) return text
+    const end = PARAM_MODIFIER.lastIndex + constraint.source.length + 1
+    // A modifier after the constraint is literal text like any other (`:id{[0-9]+}?/posts`).
+    if ("?*+{(<".includes(path[end] ?? "/")) return path.slice(found.index, end + 1)
+    PARAM_MODIFIER.lastIndex = end
+  }
+  return undefined
+}
+
+/**
+ * NF-C026: a param followed by `?`, `*`, `+`, `{`, `(` or `<` that the router reads as literal text
+ * (`/users/:id?/posts`, `/users/:id{int}`). Only a trailing `?` run and a valid `{...}` are syntax.
+ */
+export const paramModifierRule: CheckRule = {
+  code: "NF-C026",
+  title: "Route param followed by an unsupported modifier",
+  async scan(ctx) {
+    const findings: Diagnostic[] = []
+    const linesByFile = new Map<string, readonly string[]>()
+    for (const route of pathSites(routeFacts(ctx))) {
+      const forms = expandOptionalParams(route.path)
+      const text = literalModifier(forms[forms.length - 1] ?? route.path)
+      if (text === undefined) continue
+      let lines = linesByFile.get(route.file)
+      if (lines === undefined) {
+        lines = (ctx.project.source.read(route.file) ?? "").split("\n")
+        linesByFile.set(route.file, lines)
+      }
+      if (commentBlockHasMarker(lines, route.line, PARAM_MODIFIER_PRAGMA)) continue
+      const character = text[text.length - 1]!
+      findings.push(
+        diagnostic({
+          code: "NF-C026",
+          severity: "warn",
+          file: route.file,
+          line: route.line,
+          message: `${route.method} ${route.path} - '${character}' after '${text.slice(0, -1)}' is matched as literal text, not as a param modifier${character === "?" ? "; a request path never contains '?', so this route cannot be reached" : ""}. Optional params are supported as the trailing whole segments of a path (\`/users/:id?\`, \`/d/:year?/:month?\`), and a constraint as one character class with an optional count (\`:id{[0-9]+}\`, \`:code{[A-Z]{2}}\`) or a list of two or more values (\`:ext{png|jpg}\`); for anything else register each path, or mark a deliberate literal with \`// ${PARAM_MODIFIER_PRAGMA}\` above the registration`,
+          evidence: [`${route.method} ${route.path}`, `literal: ${text}`],
+          verify: "nifra check --lints-only",
+        }),
+      )
+    }
+    return findings
+  },
+}
+
+export const routeRules = Object.freeze([
+  reservedSegmentRule,
+  duplicateRouteRule,
+  overlappingRouteRule,
+  paramModifierRule,
+])

package/src/rules/secrets.ts

@@ -0,0 +1,174 @@
+/**
+ * NF-C032: what looks like a credential in browser code or in `public/`, checked from source with the
+ * scanner every client build runs (`@nifrajs/web/zones`). The build also matches the values of the
+ * build environment's private variables in its output; that needs the build's environment, so it
+ * stays the build's.
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import {
+  publicScanFiles,
+  type SecretExemption,
+  type SecretScanFile,
+  scanForSecrets,
+} from "@nifrajs/web/zones"
+import { CONFIG_FILE } from "../app-files.ts"
+import { stripComments } 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 BROWSER_CODE = new Set(["route-frontend", "frontend", "shared"])
+
+const EXEMPTIONS_START = /\bexport\s+const\s+secretExemptions\b[^=]*=\s*\[/
+
+type Token = { readonly kind: "string" | "word" | "punct"; readonly value: string }
+
+/**
+ * The tokens of an array literal, from just after its `[` to the `]` that closes it. A string is one
+ * token, so a bracket or a colon inside one (`"routes/[lang]/index.tsx"`) is text, never syntax.
+ */
+function arrayTokens(src: string, from: number): Token[] {
+  const tokens: Token[] = []
+  let depth = 0
+  let i = from
+  while (i < src.length) {
+    const c = src[i] as string
+    if (c === '"' || c === "'" || c === "`") {
+      let value = ""
+      let j = i + 1
+      while (j < src.length && src[j] !== c) {
+        if (src[j] === "\\") {
+          value += src[j + 1] ?? ""
+          j += 2
+        } else value += src[j++]
+      }
+      tokens.push({ kind: "string", value })
+      i = j + 1
+    } else if (/[\w$]/.test(c)) {
+      let j = i
+      while (j < src.length && /[\w$]/.test(src[j] as string)) j++
+      tokens.push({ kind: "word", value: src.slice(i, j) })
+      i = j
+    } else {
+      if (c === "]" || c === "}" || c === ")") {
+        if (depth === 0) break
+        depth--
+      } else if (c === "[" || c === "{" || c === "(") depth++
+      if (!/\s/.test(c)) tokens.push({ kind: "punct", value: c })
+      i++
+    }
+  }
+  return tokens
+}
+
+const isPunct = (token: Token | undefined, value: string): boolean =>
+  token?.kind === "punct" && token.value === value
+
+/**
+ * The app's `secretExemptions`, read statically from `nifra.config.ts` (check never imports app code):
+ * an array literal of object literals with string fields, the form the build error suggests.
+ */
+export function readSecretExemptions(appRoot: string): SecretExemption[] {
+  const path = join(appRoot, CONFIG_FILE)
+  if (!existsSync(path)) return []
+  const text = stripComments(readFileSync(path, "utf8"))
+  const opened = EXEMPTIONS_START.exec(text)
+  if (opened === null) return []
+  const tokens = arrayTokens(text, opened.index + opened[0].length)
+  const exemptions: SecretExemption[] = []
+  let depth = 0
+  let fields: Record<string, string> | undefined
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i] as Token
+    if (token.kind === "punct" && "[{(".includes(token.value)) {
+      depth++
+      if (depth === 1 && token.value === "{") fields = {}
+    } else if (token.kind === "punct" && "]})".includes(token.value)) {
+      if (depth === 1 && fields !== undefined) {
+        const { rule, reason, file, env } = fields
+        if (rule !== undefined && reason !== undefined) {
+          exemptions.push({
+            rule: rule as SecretExemption["rule"],
+            reason,
+            ...(file === undefined ? {} : { file }),
+            ...(env === undefined ? {} : { env }),
+          })
+        }
+        fields = undefined
+      }
+      depth--
+    } else if (
+      depth === 1 &&
+      fields !== undefined &&
+      token.kind !== "punct" &&
+      isPunct(tokens[i + 1], ":") &&
+      tokens[i + 2]?.kind === "string" &&
+      (isPunct(tokens[i + 3], ",") || isPunct(tokens[i + 3], "}"))
+    ) {
+      fields[token.value] ??= (tokens[i + 2] as Token).value
+      i += 2
+    }
+  }
+  return exemptions
+}
+
+export const secretSourceRule: CheckRule = {
+  code: "NF-C032",
+  title: "Credential in browser code",
+  async scan(ctx) {
+    const { files } = zonedFiles(ctx)
+    const apps = new Map<string, SecretScanFile[]>()
+    for (const { file, app, classification } of files) {
+      if (!apps.has(app)) apps.set(app, [])
+      if (!BROWSER_CODE.has(classification.zone)) continue
+      const text = ctx.sources.read(file)
+      if (text === undefined) continue
+      const name = app === "" ? file : file.slice(app.length + 1)
+      apps.get(app)?.push({ name, text, firstParty: true })
+    }
+    const findings: Diagnostic[] = []
+    for (const [app, sources] of apps) {
+      const appRoot = join(ctx.root, app)
+      const publicDir = join(appRoot, "public")
+      try {
+        const found = scanForSecrets({
+          sources,
+          artifacts: existsSync(publicDir) ? publicScanFiles(publicDir, "public") : [],
+          exemptions: readSecretExemptions(appRoot),
+        })
+        for (const finding of found) {
+          const file = app === "" ? finding.file : `${app}/${finding.file}`
+          findings.push(
+            diagnostic({
+              code: "NF-C032",
+              severity: "error",
+              file,
+              line: finding.line,
+              message: `${file} carries what looks like a credential (${finding.what}), and it reaches the browser. Read it from the environment in a route's backend half or under backend/, and rotate it if it was ever committed`,
+              evidence: [`rule: ${finding.rule}`, `match: ${finding.preview}`],
+              verify: "nifra check",
+            }),
+          )
+        }
+      } catch (error) {
+        // A malformed exemption: the build refuses it with the same message.
+        findings.push(
+          diagnostic({
+            code: "NF-C032",
+            severity: "error",
+            file: join(app, CONFIG_FILE),
+            message: error instanceof Error ? error.message : String(error),
+            verify: "nifra check",
+          }),
+        )
+      }
+    }
+    return findings.sort(
+      (a, b) => codeUnitOrder(a.file ?? "", b.file ?? "") || (a.line ?? 0) - (b.line ?? 0),
+    )
+  },
+}
+
+export const secretRules = Object.freeze([secretSourceRule])