@nifrajs/cli 3.5.0 → 4.0.2

package/src/rules/legacy.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
+import { reservedKeyFor } from "@nifrajs/client"
 import type { AssuranceConfig, AssuranceReport } from "@nifrajs/core/assurance"
 import { type ProjectEvidenceSnapshot, snapshotProjectEvidence } from "@nifrajs/core/evidence"
 import { SINGLE_COPY_REGISTER_SPECIFIER } from "@nifrajs/core/single-copy"
@@ -7,6 +8,7 @@ import type { CapabilityProjectReport } from "../capabilities-tool.ts"
 import type { SourceFinding, StaticRouteFinding } from "../check-scan.ts"
 import {
   IDENT,
+  movedExportSites,
   parseSimpleFetchCall,
   REMOVED_IMPORTS,
   SIMPLE_REWRITE_METHODS,
@@ -19,6 +21,8 @@ import {
   diagnosticWithCompatibility,
 } from "../diagnostics.ts"
 import type { DuplicateInstallFinding } from "../doctor.ts"
+import { codeUnitOrder } from "../internal/code-unit-order.ts"
+import { unsupportedTypeScriptDiagnostic } from "../internal/typescript-import.ts"
 import type { CheckRule, RuleContext } from "./index.ts"
 
 /** Legacy rule name → stable NF- code. Exported so `nifra.check.json` rule overrides can be keyed
@@ -89,7 +93,7 @@ const FETCH_HINT =
 const STREAM_HINT =
   "hand-rolled EventSource/WebSocket to your own API - subscribe through client<typeof app> (`.subscribe()` for `app.sse()` routes, `.ws()` for `app.ws()` routes) so the compiler catches drift"
 const SERVER_IMPORT_HINT =
-  "server-only import in a route module (bundled for the browser) - reach it via c.db / ctx.api inside a loader, never a top-level import"
+  "server-only code in browser code (a route's frontend half, frontend/ or shared/) - reach it from the route's backend half (x.backend.ts) or a *.fn.ts server function; a dynamic import() is bundled too"
 const RESPONSE_ROUTE_HINT =
   "route handler returns a raw Response - the typed client infers `data: never`, so drift detection is lost for this route. Return a plain object (it's serialized for you); for a stream use a typed SSE route (`app.sse(...)`), which keeps typed events; or, if a raw Response is intended (file/redirect), add `{ response: t.… }` or a `// nifra-expect raw-response` comment to mark it and silence this"
 const PIPELINE_DOC_HINT =
@@ -121,6 +125,8 @@ interface LegacyFields {
   readonly evidence?: readonly string[]
   readonly chain?: readonly string[]
   readonly fix?: string
+  /** A recipe for this one finding, when the rule's findings are not all mechanically fixable. */
+  readonly recipe?: Diagnostic["fix"]
   readonly suggestion?: DiagnosticSuggestion
   readonly verify?: string
   readonly includeCode?: boolean
@@ -141,7 +147,7 @@ function legacyDiagnostic(rule: string, fields: LegacyFields): Diagnostic {
   const code = LEGACY_RULE_CODES[rule]
   if (code === undefined) throw new Error(`unknown legacy rule ${rule}`)
   const evidence = fields.evidence ?? fields.chain
-  const fix = canonicalRecipe(rule)
+  const fix = fields.recipe ?? canonicalRecipe(rule)
   const canonical: Diagnostic = {
     code,
     severity: fields.severity === "warning" ? "warn" : fields.severity,
@@ -163,7 +169,7 @@ function legacyDiagnostic(rule: string, fields: LegacyFields): Diagnostic {
 }
 
 const bySite = (a: SourceFinding, b: SourceFinding): number =>
-  a.file.localeCompare(b.file) || a.line - b.line
+  codeUnitOrder(a.file, b.file) || a.line - b.line
 
 function oneLineDiff(file: string, line: number, before: string, after: string): string {
   return `--- ${file}:${line}\n+++ ${file}:${line}\n@@\n-${before}\n+${after}`
@@ -198,7 +204,10 @@ function typedClientCall(method: string, path: string): string {
   if (segs.length === 0) chain += ".index"
   else {
     for (const seg of segs) {
-      chain += IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`
+      // The proxy answers a reserved name (`post`, `index`, `then`...) itself, so that segment is
+      // appended by a call instead of a property read.
+      if (reservedKeyFor(seg) !== undefined) chain += `(${JSON.stringify(seg)})`
+      else chain += IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`
     }
   }
   return `${chain}.${method.toLowerCase()}()`
@@ -285,12 +294,13 @@ function serverImportSuggestion(
       : undefined
   return {
     kind: "manual",
-    title: "Move server-only code behind the route server boundary",
+    title: "Move server-only code behind the route's backend half",
     steps: [
       ...(chainStep === undefined ? [] : [chainStep]),
-      `Remove the top-level \`import … from "${specifier}"\` from this route module (it's bundled for the browser).`,
-      "Access backend/data work through the route `loader`/`action` context (`api`, `env`, or project server context).",
-      `If a direct module import is unavoidable, lazy-load it (\`await import("${specifier}")\`) inside the server-only loader/action path.`,
+      `Remove the import of "${specifier}" from this module: it is browser code, bundled for the browser.`,
+      "Do the backend work in the route's backend half (`x.backend.ts` - its `loader` or `action`) and pass the result as loader data, or call a server function (`*.fn.ts`).",
+      "Code both sides need belongs in `shared/`, which may import only shared code and third-party packages.",
+      "A dynamic `import()` does not keep code off the client: the build bundles its target as a lazy chunk.",
     ],
   }
 }
@@ -398,7 +408,7 @@ const typedClientRule: CheckRule = {
       }),
     )
     return [...fetchFindings, ...streamFindings].sort(
-      (a, b) => (a.file ?? "").localeCompare(b.file ?? "") || (a.line ?? 0) - (b.line ?? 0),
+      (a, b) => codeUnitOrder(a.file ?? "", b.file ?? "") || (a.line ?? 0) - (b.line ?? 0),
     )
   },
 }
@@ -408,6 +418,18 @@ const removedImportRule: CheckRule = {
   title: TITLES["removed-import"]!,
   async scan(ctx) {
     return [...ctx.project.sourceFindings.removedImports].sort(bySite).map((finding) => {
+      const moved = movedExportSites(finding.snippet)[0]
+      if (moved !== undefined) {
+        const names = moved.moved.map((binding) => `\`${binding.split(/\s+/)[0]}\``).join(", ")
+        return legacyDiagnostic("removed-import", {
+          severity: "error",
+          file: finding.file,
+          line: finding.line,
+          message: `${finding.snippet} - ${names} moved from "${moved.from}" to "${moved.to}"`,
+          fix: `import ${names} from "${moved.to}" - \`nifra fix --code NF-C005\` rewrites it`,
+          recipe: { recipe: "imports.moved-export", command: "nifra fix --code NF-C005" },
+        })
+      }
       const entry = REMOVED_IMPORTS.find(
         (candidate) =>
           finding.snippet.includes(`"${candidate.specifier}`) ||
@@ -467,7 +489,9 @@ const interpolatedSqlRule: CheckRule = {
   title: TITLES["interpolated-sql"]!,
   async scan(ctx) {
     const findings: Diagnostic[] = []
-    if (!ctx.project.check.sqlCompilerAvailable) {
+    if (ctx.project.check.unsupportedTypeScriptVersion !== undefined) {
+      findings.push(unsupportedTypeScriptDiagnostic(ctx.project.check.unsupportedTypeScriptVersion))
+    } else if (!ctx.project.check.sqlCompilerAvailable) {
       findings.push(
         legacyDiagnostic("interpolated-sql", {
           severity: "warning",
@@ -528,7 +552,7 @@ const responseRouteRule: CheckRule = {
 function copyLines(finding: DuplicateInstallFinding): string[] {
   return finding.copies.map(
     (copy) =>
-      `${finding.package}@${copy.version} at ${copy.absolutePath ?? copy.path} - pulled in by ${copy.importers.join(", ")}`,
+      `${finding.package}@${copy.version} at ${copy.absolutePath ?? copy.path} - pulled in by ${copy.importers.join(", ")}${copy.links === undefined ? "" : ` through the symlink ${copy.links.join(", ")}`}`,
   )
 }
 
@@ -547,6 +571,9 @@ function duplicateSuggestion(finding: DuplicateInstallFinding): DiagnosticSugges
     ].join("\n"),
     steps: [
       ...lines.map((line) => `Copy: ${line}`),
+      ...(finding.provenance === undefined
+        ? []
+        : [`Planted links: ${finding.provenance} Try this before the fixes below.`]),
       "Fix 1 - deduplicate: align workspace dependency and peer ranges on one compatible version, remove stale nested installs, and reinstall from the workspace root so every importer resolves one physical copy.",
       `Fix 2 - declare single-copy: apply the package.json and bunfig.toml config printed above; nifra then rewrites every duplicate to this app's copy.${finding.cause === "version-skew" ? " A declaration only covers same-version duplicates, so fix 1's range alignment must land first." : ""}`,
       "Re-run `nifra check`; the gate stays failing until one fix lands.",
@@ -596,16 +623,6 @@ const doctorRules: readonly CheckRule[] = Object.freeze([
           }),
         )
       }
-      for (const finding of doctor.deduplicatedInstalls ?? []) {
-        const paths = finding.copies.map((copy) => copy.path).join("; ")
-        findings.push(
-          legacyDiagnostic("duplicate-install", {
-            severity: "warning",
-            message: `${finding.package} is installed at ${finding.copies.length} paths (${paths}) and is declared single-copy - nifra resolves every duplicate to this app's copy`,
-            fix: finding.remediation,
-          }),
-        )
-      }
       return findings
     },
   },
@@ -732,6 +749,11 @@ const capabilityAssuranceRule: CheckRule = {
         finding.code === "unmatched-provenance-seam"
           ? "Write the seam exactly as the code imports it, or delete the rule."
           : undefined
+      const mountFix =
+        finding.code === "opaque-mount-undeclared"
+          ? 'merge() a nifra server() instead of mounting it, or add { opaque: "<why it cannot be analyzed>" } to the mount.'
+          : undefined
+      const ownFix = seamFix ?? mountFix
       findings.push(
         legacyDiagnostic("capability-assurance", {
           severity: "error",
@@ -740,30 +762,40 @@ const capabilityAssuranceRule: CheckRule = {
               ? {}
               : { chain: truncation.chain }
             : { file: violation.module, chain: violation.chain }),
-          message: `${finding.message}${seamFix === undefined ? ` - ${CAPABILITY_HINT}` : ""}`,
-          fix: seamFix ?? CAPABILITY_HINT,
+          message: `${finding.message}${ownFix === undefined ? ` - ${CAPABILITY_HINT}` : ""}`,
+          fix: ownFix ?? CAPABILITY_HINT,
           suggestion:
-            seamFix === undefined
+            mountFix !== undefined
               ? {
                   kind: "manual",
-                  title: "Restore declared effect provenance",
+                  title: "Analyze the mounted routes, or state why they cannot be",
                   steps: [
-                    "Route effectful work through an import listed in capabilities.provenance.imports.",
-                    "Declare the exact capability token on the route; do not widen unrelated routes in the same file.",
-                    "For domain writes, add the adapter the capability definition requires: `schema.idempotency` for the `request` tier, `.use(durableCommand({ journal }))` from @nifrajs/middleware for the `durable` tier.",
-                    "Run `nifra capabilities snapshot` only after assurance passes, then review the lockfile diff.",
+                    "If the child is a nifra server() you own, merge() it so its routes join the analyzed app.",
+                    'If its effects live in code nifra cannot follow (a handler closure from another package), add { opaque: "<reason>" } to the mount.',
+                    "A declared opaque mount is listed as a known gap on every run; it no longer fails assurance.",
                   ],
                 }
-              : {
-                  kind: "manual",
-                  title: "Point the provenance rule at a module that exists",
-                  steps: [
-                    "Copy the specifier from the import statement itself - it is matched as written, with no extension or index resolution.",
-                    "Use a trailing `/*` when the seam is a directory of modules (`@myorg/db/*`).",
-                    "For a routeModules entry, give the project-relative path of the file that implements the route.",
-                    "Delete the rule if the seam it governed is gone; leaving it in place proves nothing.",
-                  ],
-                },
+              : seamFix === undefined
+                ? {
+                    kind: "manual",
+                    title: "Restore declared effect provenance",
+                    steps: [
+                      "Route effectful work through an import listed in capabilities.provenance.imports.",
+                      "Declare the exact capability token on the route; do not widen unrelated routes in the same file.",
+                      "For domain writes, add the adapter the capability definition requires: `schema.idempotency` for the `request` tier, `.use(durableCommand({ journal }))` from @nifrajs/middleware for the `durable` tier.",
+                      "Run `nifra capabilities snapshot` only after assurance passes, then review the lockfile diff.",
+                    ],
+                  }
+                : {
+                    kind: "manual",
+                    title: "Point the provenance rule at a module that exists",
+                    steps: [
+                      "Copy the specifier from the import statement itself - it is matched as written, with no extension or index resolution.",
+                      "Use a trailing `/*` when the seam is a directory of modules (`@myorg/db/*`).",
+                      "For a routeModules entry, give the project-relative path of the file that implements the route.",
+                      "Delete the rule if the seam it governed is gone; leaving it in place proves nothing.",
+                    ],
+                  },
         }),
       )
     }

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,
+])