@nifrajs/cli 3.3.0 → 4.0.0

package/src/web-app-options.ts

@@ -0,0 +1,57 @@
+/**
+ * The `createWebApp` options a CLI-run app takes from its framework config and `backend/app.ts`,
+ * built in one place. `nifra dev`, the static prerender, `nifra mcp`'s render tool and the
+ * hydration gate each construct the app themselves, and the generated server entry constructs it in
+ * production; when each call site picked its own subset, the app they served drifted from the one
+ * that ships.
+ */
+import { inProcessClient } from "@nifrajs/client"
+import type { CreateWebAppOptions } from "@nifrajs/web"
+import { FRAMEWORK_WEB_OPTIONS, type FrameworkWebOption, type NifraFramework } from "./load.ts"
+
+type FrameworkWebAppOptions = Pick<
+  CreateWebAppOptions,
+  "use" | "api" | "apiPrefix" | "apiStrip" | "mounts" | "csp" | "nonce"
+>
+
+/** `use`, the backend as `api`, and every forwarded framework field the config sets. */
+export function frameworkWebAppOptions(
+  fw: NifraFramework,
+  backend: unknown,
+): FrameworkWebAppOptions {
+  const options: Record<string, unknown> = {}
+  if (fw.use !== undefined) options.use = fw.use
+  if (backend !== undefined) options.api = inProcessClient(backend as never)
+  for (const name of FRAMEWORK_WEB_OPTIONS) {
+    if (fw[name] !== undefined) options[name] = fw[name]
+  }
+  return options as FrameworkWebAppOptions
+}
+
+/**
+ * The mount paths the app will serve ahead of page routing, read from the config alone (no app is
+ * built): each `mounts` entry, plus the backend at `apiPrefix` when `backend/app.ts` exports one. A
+ * mount added inside `use` is not visible here; `createWebApp` checks its own mount table at
+ * startup.
+ */
+export function frameworkMountPaths(fw: NifraFramework, hasBackend: boolean): string[] {
+  const paths: string[] = []
+  for (const mount of fw.mounts ?? []) {
+    if (typeof mount?.path === "string") paths.push(mount.path)
+  }
+  const apiPrefix = fw.apiPrefix ?? "/api"
+  if (hasBackend && apiPrefix !== "") paths.push(apiPrefix)
+  return paths
+}
+
+/** The generated server entry's imports for the forwarded fields the config sets, all from the
+ * edge-safe framework module. */
+export function frameworkOptionImports(
+  fw: NifraFramework,
+  frameworkFile: string,
+): { optionImports?: Partial<Record<FrameworkWebOption, string>> } {
+  const imports: Partial<Record<FrameworkWebOption, string>> = {}
+  for (const name of FRAMEWORK_WEB_OPTIONS)
+    if (fw[name] !== undefined) imports[name] = frameworkFile
+  return Object.keys(imports).length === 0 ? {} : { optionImports: imports }
+}

package/src/work-graph.ts

@@ -9,9 +9,16 @@
 import { existsSync } from "node:fs"
 import { readFile, stat } from "node:fs/promises"
 import { basename, resolve } from "node:path"
-import { type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
+import {
+  type ProjectEvidenceSnapshot,
+  reflectedRoutesFromEvidence,
+  snapshotProjectEvidence,
+} from "@nifrajs/core/evidence"
+import type { ReflectedRoute } from "@nifrajs/core/reflection"
 import { Glob } from "bun"
+import { BACKEND_APP_FILE, CONFIG_FILE, FRAMEWORK_FILE } from "./app-files.ts"
 import { digestRoute } from "./contracts.ts"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
 
 export type WorkGraphNodeKind =
   | "route"
@@ -52,6 +59,8 @@ export interface WorkGraphSourceFile {
 
 export interface WorkGraphBuildInput {
   readonly source: unknown
+  /** Reuse a canonical route-evidence pass when the caller already has one. */
+  readonly evidence?: ProjectEvidenceSnapshot
   readonly files?: readonly WorkGraphSourceFile[]
   readonly freshness?: BuildFreshness
 }
@@ -126,8 +135,11 @@ export interface ProjectWorkGraphResult {
   readonly evidence: EvidenceBundle
 }
 
-const SOURCE_GLOB = new Glob("**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json}")
+// Framework component, content, and style files are app source too: an edit to one makes a build stale.
+const SOURCE_GLOB = new Glob("**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json,svelte,vue,mdx,css}")
 const IGNORED = /(^|\/)(node_modules|dist|build|\.nifra|\.git|\.wrangler|coverage)\//
+const APP_SOURCE_DIR = /^(?:routes|frontend|backend|shared)\//
+const BACKEND_SOURCE_DIR = /^(?:backend|shared)\//
 const MANIFEST_NAMES = new Set([
   "server-manifest.ts",
   "nifra-manifest.json",
@@ -169,13 +181,13 @@ export function evaluateBuildFreshness(input: {
 
 export async function inspectBuildFreshness(cwd: string): Promise<BuildFreshness> {
   const sourcePaths: string[] = []
-  for (const name of ["backend.ts", "framework.ts", "nifra.config.ts"]) {
+  for (const name of [BACKEND_APP_FILE, FRAMEWORK_FILE, CONFIG_FILE]) {
     const path = resolve(cwd, name)
     if (existsSync(path)) sourcePaths.push(path)
   }
   for await (const rawPath of SOURCE_GLOB.scan({ cwd, dot: false })) {
     const path = rawPath.replaceAll("\\", "/")
-    if (!IGNORED.test(path) && path.startsWith("routes/")) sourcePaths.push(resolve(cwd, path))
+    if (!IGNORED.test(path) && APP_SOURCE_DIR.test(path)) sourcePaths.push(resolve(cwd, path))
   }
   const sourceTimes = await fileTimes(sourcePaths)
   for (const buildDirName of ["dist", "build"]) {
@@ -208,8 +220,8 @@ export async function collectProjectWorkGraph(
 ): Promise<ProjectWorkGraphResult> {
   const freshness = await inspectBuildFreshness(cwd)
   if (!freshness.ok) throw new StaleBuildError(freshness)
-  const backendPath = resolve(cwd, "backend.ts")
-  if (!existsSync(backendPath)) throw new Error(`[nifra] no backend.ts in ${cwd}`)
+  const backendPath = resolve(cwd, BACKEND_APP_FILE)
+  if (!existsSync(backendPath)) throw new Error(`[nifra] no ${BACKEND_APP_FILE} in ${cwd}`)
   const loadedValue: unknown = await import(`${backendPath}?nifra-work-graph=${Date.now()}`)
   const loaded = recordOf(loadedValue)
   if (loaded?.backend === undefined)
@@ -224,7 +236,8 @@ export async function buildProjectWorkGraph(
 ): Promise<ProjectWorkGraphResult> {
   const freshness = input.freshness ?? { ok: true }
   if (!freshness.ok) throw new StaleBuildError(freshness)
-  const graph = await buildWorkGraph(input)
+  const projectEvidence = input.evidence ?? snapshotProjectEvidence(input.source)
+  const graph = await buildWorkGraph({ ...input, evidence: projectEvidence })
   const impact = queryImpact(graph, options.changedFiles ?? [])
   const plan = planProofs(graph, impact, options.minLevel ?? 1)
   const evidence = createEvidenceBundle(graph, impact, plan)
@@ -232,7 +245,9 @@ export async function buildProjectWorkGraph(
 }
 
 export async function buildWorkGraph(input: WorkGraphBuildInput): Promise<WorkGraph> {
-  const routes = reflectRoutes(input.source)
+  const routes = reflectedRoutesFromEvidence(
+    input.evidence ?? snapshotProjectEvidence(input.source),
+  )
   const files = input.files ?? []
   const nodes = new Map<string, WorkGraphNode>()
   const edges: WorkGraphEdge[] = []
@@ -280,8 +295,8 @@ export async function buildWorkGraph(input: WorkGraphBuildInput): Promise<WorkGr
     })
     for (const file of routeFiles)
       addEdge({ from: `file:${file}`, to: routeId, relation: "implements" })
-    if (routeFiles.length === 0 && sourceFiles.some((file) => file.path === "backend.ts"))
-      addEdge({ from: "file:backend.ts", to: routeId, relation: "implements" })
+    if (routeFiles.length === 0 && sourceFiles.some((file) => file.path === BACKEND_APP_FILE))
+      addEdge({ from: `file:${BACKEND_APP_FILE}`, to: routeId, relation: "implements" })
     for (const [name, schema] of Object.entries(route.schema ?? {})) {
       if (schema === undefined || name === "errors") continue
       const schemaId = `schema:${routeKey}:${name}`
@@ -324,9 +339,9 @@ export async function buildWorkGraph(input: WorkGraphBuildInput): Promise<WorkGr
     for (const file of manifestFiles)
       addEdge({ from: `manifest:${file.path}`, to: routeId, relation: "describes" })
   }
-  const sortedNodes = [...nodes.values()].sort((a, b) => a.id.localeCompare(b.id))
+  const sortedNodes = [...nodes.values()].sort((a, b) => codeUnitOrder(a.id, b.id))
   const sortedEdges = edges.sort((a, b) =>
-    `${a.from}\n${a.to}\n${a.relation}`.localeCompare(`${b.from}\n${b.to}\n${b.relation}`),
+    codeUnitOrder(`${a.from}\n${a.to}\n${a.relation}`, `${b.from}\n${b.to}\n${b.relation}`),
   )
   const digest = await digestJson({ nodes: sortedNodes, edges: sortedEdges })
   return Object.freeze({
@@ -343,7 +358,9 @@ export function queryImpact(graph: WorkGraph, changedFiles: readonly string[]):
     ...new Set(changedFiles.map((file) => file.replace(/^\.\//, "").replaceAll("\\", "/"))),
   ]
   const seeds = new Set<string>()
+  const unmodeled: string[] = []
   for (const file of normalized) {
+    let seeded = false
     for (const node of graph.nodes) {
       if (
         (node.kind === "file" || node.kind === "test" || node.kind === "manifest") &&
@@ -351,11 +368,18 @@ export function queryImpact(graph: WorkGraph, changedFiles: readonly string[]):
           node.id === `test:${file}` ||
           node.id === `manifest:${file}` ||
           node.files.includes(file))
-      )
+      ) {
         seeds.add(node.id)
+        seeded = true
+      }
     }
+    // An app file the graph does not model (deleted, or a type it does not read) has an unknown
+    // reach, so it stands for itself and impacts every route rather than proving nothing.
+    if (!seeded && APP_SOURCE_DIR.test(file)) unmodeled.push(file)
   }
-  if (normalized.includes("backend.ts"))
+  for (const file of unmodeled) seeds.add(`file:${file}`)
+  // Any backend or shared module can reach every handler through backend/app.ts.
+  if (unmodeled.length > 0 || normalized.some((file) => BACKEND_SOURCE_DIR.test(file)))
     for (const node of graph.nodes) if (node.kind === "route") seeds.add(node.id)
   const impacted = new Set(seeds)
   const queue = [...seeds]
@@ -434,7 +458,7 @@ export function createEvidenceBundle(
   plan: ProofPlan,
   proofs: readonly ProofEvidence[] = [],
 ): EvidenceBundle {
-  const evidence = [...proofs].sort((a, b) => a.id.localeCompare(b.id))
+  const evidence = [...proofs].sort((a, b) => codeUnitOrder(a.id, b.id))
   // Levels are not cumulative (assure does not typecheck), so every planned step needs its own
   // passing proof; a higher-level pass never subsumes a lower one.
   const done =
@@ -571,7 +595,7 @@ function filesForRoute(
   const matches = files
     .filter(
       (file) =>
-        file.path === "backend.ts" ||
+        file.path === BACKEND_APP_FILE ||
         (file.path.startsWith("routes/") && file.content.includes(route.path)),
     )
     .map((file) => file.path)