@nifrajs/cli 4.0.2 → 5.1.0

package/src/rules/zones.ts

@@ -8,21 +8,38 @@
  * anything but shared code. NF-C029 owns private environment reads in browser code.
  */
 import { existsSync, readFileSync, realpathSync } from "node:fs"
-import { dirname, isAbsolute, join, relative } from "node:path"
+import { isAbsolute, join, relative } from "node:path"
 import {
+  browserDenial,
   type Classification,
   createZoneClassifier,
   importAllowed,
   importRuleMessage,
   privateEnvReads,
   privateEnvReason,
+  specifierPackage,
   type ZoneClassifier,
+  ZoneConfigError,
 } from "@nifrajs/web/zones"
 import { CONFIG_FILE, FRAMEWORK_FILE } from "../app-files.ts"
-import { importSites, stripComments } from "../check-scan.ts"
+import { COMPONENT_FILE, importSites, stripComments } from "../check-scan.ts"
+import { appDirs, clientModuleRoot } from "../client-module.ts"
+import { componentCheckReceipts } from "../component-check.ts"
 import { type Diagnostic, diagnostic } from "../diagnostics.ts"
 import { codeUnitOrder } from "../internal/code-unit-order.ts"
+import { installedManifest } from "../internal/installed-package.ts"
+import {
+  createApiOnlyProbe,
+  createKindProbe,
+  createNifraProjectProbe,
+  createWebAppProbe,
+  hasWebConfig,
+  withApiKindHint,
+} from "../internal/nifra-project.ts"
+import { createSpecifierResolver } from "../internal/project-specifiers.ts"
+import { createSourceFacts } from "../internal/source-facts.ts"
 import type { CheckRule, RuleContext } from "./index.ts"
+import { loadRuleTypeScript } from "./typescript.ts"
 
 const ZONE_FOLDER = new Set(["routes", "frontend", "backend", "shared"])
 const FRONTEND = new Set(["route-frontend", "frontend"])
@@ -31,11 +48,35 @@ const BACKEND = new Set(["backend", "route-backend"])
 const BROWSER_CODE = new Set(["route-frontend", "frontend", "shared"])
 const CODE_FILE = /\.(?:[cm]?[jt]sx?|svelte|vue|mdx)$/
 
-/** The app a project file belongs to: the path before its first zone folder, or `undefined`. */
-function appOf(file: string): string | undefined {
+/**
+ * The app a project file belongs to: the path before its first zone folder, else the deepest app in
+ * `apps` that encloses it, since a folder `nifra.zones` declares or a `.frontend`-style suffix zones a
+ * file anywhere in its app. `undefined` for a file in no app.
+ */
+function appOf(file: string, apps: readonly string[]): string | undefined {
   const parts = file.split("/")
   const at = parts.findIndex((part, i) => i < parts.length - 1 && ZONE_FOLDER.has(part))
-  return at === -1 ? undefined : parts.slice(0, at).join("/")
+  if (at !== -1) return parts.slice(0, at).join("/")
+  let nearest: string | undefined
+  for (const app of apps) {
+    if (app !== "" && !file.startsWith(`${app}/`)) continue
+    if (nearest === undefined || app.length > nearest.length) nearest = app
+  }
+  return nearest
+}
+
+/**
+ * A file's text as the build compiles it. The source index holds a `.svelte`/`.vue` file as its script
+ * blocks only, for the parsers; its markup carries expressions the build compiles too, so a rule that
+ * reads components itself gets the whole file.
+ */
+export function buildText(ctx: RuleContext, file: string): string | undefined {
+  if (!COMPONENT_FILE.test(file)) return ctx.sources.read(file)
+  try {
+    return readFileSync(join(ctx.root, file), "utf8")
+  } catch {
+    return undefined
+  }
 }
 
 interface ZonedFile {
@@ -48,28 +89,62 @@ interface ZonedFile {
 export function zonedFiles(ctx: RuleContext): {
   readonly files: readonly ZonedFile[]
   readonly classifierFor: (app: string) => ZoneClassifier
+  /** Settings that cannot be applied (`nifra.zones`, `nifra.kind`); their apps' files are left out. */
+  readonly configErrors: ReadonlyArray<{ readonly file: string; readonly message: string }>
 } {
-  const classifiers = new Map<string, ZoneClassifier>()
-  const classifierFor = (app: string): ZoneClassifier => {
+  const classifiers = new Map<string, ZoneClassifier | ZoneConfigError>()
+  const load = (app: string): ZoneClassifier | ZoneConfigError => {
     let classifier = classifiers.get(app)
     if (classifier === undefined) {
       const appRoot = join(ctx.root, app)
-      classifier = createZoneClassifier({
-        appRoot,
-        generatedFiles: [join(appRoot, "server-manifest.ts")],
-      })
+      try {
+        classifier = createZoneClassifier({
+          appRoot,
+          generatedFiles: [join(appRoot, "server-manifest.ts")],
+        })
+      } catch (error) {
+        if (!(error instanceof ZoneConfigError)) throw error
+        classifier = error
+      }
       classifiers.set(app, classifier)
     }
     return classifier
   }
+  const classifierFor = (app: string): ZoneClassifier => {
+    const classifier = load(app)
+    if (classifier instanceof ZoneConfigError) throw classifier
+    return classifier
+  }
   const files: ZonedFile[] = []
+  const configErrors: Array<{ file: string; message: string }> = []
+  const reportOnce = (file: string, message: string): void => {
+    if (!configErrors.some((entry) => entry.message === message))
+      configErrors.push({ file, message })
+  }
+  // Another framework's app keeps folders named `routes/` too; nifra builds none of it.
+  const inNifraProject = createNifraProjectProbe(ctx.root)
+  const kindOf = createKindProbe(ctx.root)
+  const apiOnly = createApiOnlyProbe(ctx.root)
+  const apps = appDirs(ctx.sources.files)
   for (const file of ctx.sources.files) {
     if (!CODE_FILE.test(file)) continue
-    const app = appOf(file)
-    if (app === undefined) continue
-    files.push({ file, app, classification: classifierFor(app).classify(join(ctx.root, file)) })
+    const app = appOf(file, apps)
+    if (app === undefined || !inNifraProject(app)) continue
+    const declared = kindOf(app)
+    if (declared.invalid !== undefined) {
+      reportOnce(declared.manifest ?? "package.json", declared.invalid)
+      continue
+    }
+    // An API-only project has no browser, so nothing in it is zoned.
+    if (apiOnly(app)) continue
+    const classifier = load(app)
+    if (classifier instanceof ZoneConfigError) {
+      reportOnce(app === "" ? "package.json" : `${app}/package.json`, classifier.message)
+      continue
+    }
+    files.push({ file, app, classification: classifier.classify(join(ctx.root, file)) })
   }
-  return { files, classifierFor }
+  return { files, classifierFor, configErrors }
 }
 
 const real = (path: string): string => {
@@ -87,41 +162,131 @@ function display(root: string, file: string): string {
   return rel.startsWith("../") || isAbsolute(rel) ? file : rel
 }
 
-/** A relative import resolved against the importing file, or `undefined` when it does not resolve. */
-function resolveRelative(root: string, from: string, specifier: string): string | undefined {
-  if (!specifier.startsWith("./") && !specifier.startsWith("../")) return undefined
-  try {
-    // Relative specifiers only: a bare one would let the resolver reach for a global install.
-    return Bun.resolveSync(specifier, dirname(join(root, from)))
-  } catch {
-    return undefined
-  }
+// The unzoned files one check follows through, at most: each is a build refusal of its own.
+const MAX_UNZONED = 5000
+
+interface Importer {
+  readonly file: string
+  readonly app: string
+  /** `"error"` for a file in no zone, reached from code a build loads. */
+  readonly zone: Classification["zone"]
 }
 
 export const zoneImportRule: CheckRule = {
   code: "NF-C028",
   title: "Zone import check",
   async scan(ctx) {
-    const { files, classifierFor } = zonedFiles(ctx)
-    const findings: Diagnostic[] = []
-    for (const { file, app, classification: from } of files) {
-      if (from.zone === "error" || from.zone === "library" || from.zone === "generated") continue
+    const { files, classifierFor, configErrors } = zonedFiles(ctx)
+    const { receipts } = await componentCheckReceipts(ctx.root, ctx.sources)
+    const findings: Diagnostic[] = configErrors.map(({ file, message }) =>
+      diagnostic({
+        code: "NF-C028",
+        severity: "error",
+        file,
+        message,
+        verify: "nifra check",
+      }),
+    )
+    // Outside any web app, a finding may only mean the project serves no pages: say how to declare it.
+    const inWebApp = createWebAppProbe(ctx.root)
+    const resolveSpecifier = createSpecifierResolver()
+    // Without a compiler nothing proves an import erased, so every import stays an edge.
+    const { compiler } = await loadRuleTypeScript(ctx)
+    const facts =
+      compiler === undefined
+        ? undefined
+        : createSourceFacts(compiler, {
+            keepsTypeOnlyImports: (file) =>
+              resolveSpecifier.keepsTypeOnlyImports(isAbsolute(file) ? file : join(ctx.root, file)),
+          })
+    const queue: Importer[] = []
+    const queued = new Set<string>()
+    const follow = (importer: Importer): void => {
+      if (queued.has(importer.file) || queued.size >= MAX_UNZONED + files.length) return
+      queued.add(importer.file)
+      queue.push(importer)
+    }
+    for (const { file, app, classification } of files) {
+      const zone = classification.zone
+      if (zone !== "error" && zone !== "library" && zone !== "generated")
+        follow({ file, app, zone })
+    }
+    // The browser entry imports the app's `clientModule`, so the build classifies it like any file it
+    // loads, and loads what it imports.
+    for (const app of appDirs(ctx.sources.files)) {
+      const entry = clientModuleRoot(ctx.root, app, resolveSpecifier, compiler)
+      if (entry === undefined) continue
+      let classification: Classification
+      try {
+        classification = classifierFor(app).classify(entry.file)
+      } catch (error) {
+        if (error instanceof ZoneConfigError) continue
+        throw error
+      }
+      const name = display(ctx.root, entry.file)
+      const denial = browserDenial(classification)
+      if (denial !== undefined) {
+        findings.push(
+          diagnostic({
+            code: "NF-C028",
+            severity: "error",
+            file: entry.config,
+            line: entry.line,
+            message: `clientModule ${JSON.stringify(entry.specifier)} puts ${name} in the browser bundle: ${denial}`,
+            evidence: [`clientModule: ${entry.specifier}`, `zone: ${classification.zone}`],
+            verify: "nifra check",
+          }),
+        )
+      }
+      if (classification.zone === "error" && classification.package === undefined)
+        follow({ file: name, app, zone: "error" })
+    }
+
+    // An undeclared package is one fact, however many files import it.
+    const reportedPackages = new Set<string>()
+    // An array iterator reads the length on every step, so files `follow` appends are visited too.
+    for (const { file, app, zone: from } of queue) {
       const content = ctx.sources.read(file)
       if (content === undefined) continue
-      for (const { specifier, line } of importSites(content, file)) {
-        const target = resolveRelative(ctx.root, file, specifier)
-        if (target === undefined) continue
-        const to = classifierFor(app).classify(target)
-        const targetName = display(ctx.root, target)
+      for (const { specifier, line } of importSites(content, file, facts)) {
+        let target = resolveSpecifier(join(ctx.root, file), specifier)
+        let to: Classification
+        if (target === undefined) {
+          // An installed package is judged here only by the entry it names, when it gives each
+          // entry its own side; a package-wide side is NF-C004's in browser code.
+          const name = specifierPackage(specifier)
+          const manifest =
+            name === undefined ? undefined : installedManifest(join(ctx.root, file), name)
+          if (manifest === undefined) continue
+          to = classifierFor(app).classify(manifest, specifier)
+          if (to.entry === undefined) continue
+          target = manifest
+        } else to = classifierFor(app).classify(target, specifier)
+        const targetName = to.entry === undefined ? display(ctx.root, target) : specifier
+        if (
+          ["frontend", "route-frontend", "shared"].includes(from) &&
+          (receipts.has(target) || receipts.has(targetName))
+        )
+          continue
         let message: string
-        if (to.zone === "error") message = `${file} imports ${targetName}: ${to.reason}`
-        else if (
-          (SERVER.has(from.zone) && FRONTEND.has(to.zone)) ||
-          // Shared code reaching backend code is NF-C004's, reported there with the chain.
-          (from.zone === "shared" && !importAllowed(from.zone, to.zone) && !BACKEND.has(to.zone))
+        if (to.zone === "error") {
+          if (to.package !== undefined) {
+            if (reportedPackages.has(to.package)) continue
+            reportedPackages.add(to.package)
+          } else if (to.entry === undefined) {
+            // A file in no zone loads what it imports too: the build refuses each one it reaches.
+            follow({ file: targetName, app, zone: "error" })
+          }
+          message = `${file} imports ${targetName}: ${to.reason}`
+        } else if (
+          from !== "error" &&
+          ((SERVER.has(from) && FRONTEND.has(to.zone)) ||
+            // Shared code reaching backend code is NF-C004's, reported there with the chain.
+            (from === "shared" && !importAllowed(from, to.zone) && !BACKEND.has(to.zone)))
         ) {
-          message = importRuleMessage(file, from.zone, targetName, to.zone)
+          message = importRuleMessage(file, from, targetName, to.zone)
         } else continue
+        if (!inWebApp(app)) message = withApiKindHint(message)
         findings.push(
           diagnostic({
             code: "NF-C028",
@@ -129,7 +294,7 @@ export const zoneImportRule: CheckRule = {
             file,
             line,
             message,
-            evidence: [`import: ${specifier}`, `from zone: ${from.zone}`, `to zone: ${to.zone}`],
+            evidence: [`import: ${specifier}`, `from zone: ${from}`, `to zone: ${to.zone}`],
             verify: "nifra check",
           }),
         )
@@ -141,6 +306,31 @@ export const zoneImportRule: CheckRule = {
   },
 }
 
+/** NF-C037: `"nifra": { "kind": "api" }` governing a directory that holds web config. */
+export const apiKindRule: CheckRule = {
+  code: "NF-C037",
+  title: "API-only declaration over a web app",
+  async scan(ctx) {
+    const kindOf = createKindProbe(ctx.root)
+    const findings: Diagnostic[] = []
+    for (const app of appDirs(ctx.sources.files)) {
+      const declared = kindOf(app)
+      if (declared.kind !== "api" || !hasWebConfig(ctx.root, app)) continue
+      const where = app === "" ? "the project root" : `${app}/`
+      findings.push(
+        diagnostic({
+          code: "NF-C037",
+          severity: "error",
+          file: declared.manifest ?? "package.json",
+          message: `"nifra": { "kind": "api" } in ${declared.manifest ?? "package.json"} governs ${where}, which has web config (${app === "" ? "" : `${app}/`}${existsSync(join(ctx.root, app, FRAMEWORK_FILE)) ? FRAMEWORK_FILE : CONFIG_FILE}). An app that serves pages keeps its zone checks; remove "kind", or give the web app its own package.json`,
+          verify: "nifra check",
+        }),
+      )
+    }
+    return findings
+  },
+}
+
 const PREFIX_EXPORT =
   /\bexport\s+const\s+publicEnvPrefix\s*(?::\s*string\s*)?=\s*(?:"([^"\\\r\n]*)"|'([^'\\\r\n]*)')/
 
@@ -164,7 +354,7 @@ export const privateEnvRule: CheckRule = {
     const findings: Diagnostic[] = []
     for (const { file, app, classification } of files) {
       if (!BROWSER_CODE.has(classification.zone)) continue
-      const content = ctx.sources.read(file)
+      const content = buildText(ctx, file)
       if (content === undefined) continue
       let prefix = prefixes.get(app)
       if (prefix === undefined) {
@@ -192,4 +382,4 @@ export const privateEnvRule: CheckRule = {
   },
 }
 
-export const zoneRules = Object.freeze([zoneImportRule, privateEnvRule])
+export const zoneRules = Object.freeze([zoneImportRule, privateEnvRule, apiKindRule])

package/src/scaffold.ts

@@ -29,7 +29,7 @@ const EXT: Record<Framework, string> = {
   solid: "tsx",
   vue: "vue",
   svelte: "svelte",
-  vanilla: "ts",
+  vanilla: "tsx",
 }
 
 /** Derive the framework from a `clientModule` like `@nifrajs/web-react/client`. Defaults to react. */
@@ -93,7 +93,7 @@ export function routePathToFile(urlPath: string, ext: string): string {
 
 const ROUTE_CONTRACT = `A route is two files:
 - The page, \`routes/x.<ext>\` - ships to the browser: \`export default function Page({ data }: Route.ComponentProps)\` and \`export const meta = { title, meta: […] }\`. It never imports backend code.
-- Its backend half, \`routes/x.backend.ts\` - never reaches the browser: \`export const loaderOutput = t.object({…})\` with \`export async function loader({ params, api }: Route.LoaderArgs)\` (data for SSR - only what the schema declares is sent), \`actionOutput\` with \`action\` (the form POST), and \`hydrate\`, \`islandScripts\`, \`revalidate\`, \`middleware\`. Reach the backend through the typed \`api\`.
+- Its backend half, \`routes/x.backend.ts\` - never reaches the browser: \`export const loaderOutput = t.object({…})\` with \`export const loader: Route.Loader = async ({ params, api }) => …\` (data for SSR - only what the schema declares is sent, and \`Route.Loader\` type-checks what it returns against that schema), \`actionOutput\` with \`export const action: Route.Action\` (the form POST), and \`hydrate\`, \`islandScripts\`, \`revalidate\`, \`middleware\`. Reach the backend through the typed \`api\`.
 Both import \`type { Route } from "./+types/<name>"\`, which \`nifra dev\`, \`nifra build\`, \`nifra check\` and \`nifra types\` generate. Path params are typed on \`params\`.`
 
 interface RouteParam {
@@ -120,11 +120,13 @@ function backendStub(file: string, params: readonly RouteParam[], vanilla: boole
   const last = params.at(-1)
   const loader =
     last === undefined
-      ? `export async function loader(_args: Route.LoaderArgs) {
+      ? `// Route.Loader checks what it returns against loaderOutput.
+export const loader: Route.Loader = async () => {
   // Load through the typed backend client, \`api\` in these args; see nifra_example("loader").
   return { title: "TODO" }
 }`
-      : `export async function loader({ params }: Route.LoaderArgs) {
+      : `// Route.Loader checks what it returns against loaderOutput.
+export const loader: Route.Loader = async ({ params }) => {
   // Load by params.${last.name} through the typed backend client, \`api\` in these args; see nifra_example("loader").
   return { title: \`TODO: \${params.${last.name}${last.optional ? ' ?? ""' : ""}}\` }
 }`

package/src/sdk.ts

@@ -381,7 +381,10 @@ function pythonModelFields(
   if (properties === undefined) return "    pass"
   const required = schemaRequired(schema)
   const used = new Set<string>()
+  // A dataclass rejects a field without a default after one with a default, so required fields
+  // lead and each group keeps the schema's order.
   const fields: string[] = []
+  const optionalFields: string[] = []
   for (const [jsonName, property] of Object.entries(properties)) {
     let fieldName = pythonIdentifier(jsonName, "field")
     while (used.has(fieldName)) fieldName += "_"
@@ -396,11 +399,12 @@ function pythonModelFields(
     )
     const optional = !required.has(jsonName)
     if (optional && !type.includes("None")) type += " | None"
+    const group = optional ? optionalFields : fields
     if (fieldName === jsonName) {
-      fields.push(`    ${fieldName}: ${type}${optional ? " = None" : ""}`)
+      group.push(`    ${fieldName}: ${type}${optional ? " = None" : ""}`)
     } else {
       const metadata = `{"json_name": ${JSON.stringify(jsonName)}}`
-      fields.push(
+      group.push(
         "    " +
           fieldName +
           ": " +
@@ -413,6 +417,7 @@ function pythonModelFields(
       )
     }
   }
+  fields.push(...optionalFields)
   return fields.length === 0 ? "    pass" : fields.join("\n")
 }
 
@@ -430,9 +435,11 @@ function renderPythonModels(catalog: SchemaCatalog, tracker: OpaqueTracker): str
           pythonModelFields(schema, name, catalog, tracker),
       )
     } else {
+      // A `type` statement evaluates lazily, so an alias may name a model declared below it.
       rendered.push(
-        name +
-          ": TypeAlias = " +
+        "type " +
+          name +
+          " = " +
           pythonType(schema, name, catalog, tracker, "schema", `model ${name}`),
       )
     }
@@ -628,7 +635,7 @@ function pythonSdk(document: OpenAPIDocument, options: SdkRenderOptions): string
     "import urllib.parse",
     "import urllib.request",
     "from dataclasses import dataclass, field, fields, is_dataclass",
-    "from typing import Any, Generic, Literal, Mapping, Never, TypeAlias, TypeVar, get_args, get_origin, get_type_hints",
+    "from typing import Any, Generic, Literal, Mapping, Never, TypeAliasType, TypeVar, get_args, get_origin, get_type_hints",
     "",
     'T = TypeVar("T")',
     "",
@@ -639,6 +646,8 @@ function pythonSdk(document: OpenAPIDocument, options: SdkRenderOptions): string
     "        self.body = body",
     "",
     "def _decode(value: Any, target: Any) -> Any:",
+    "    if isinstance(target, TypeAliasType):",
+    "        return _decode(value, target.__value__)",
     "    if target is None or target is Any or target is object:",
     "        return value",
     "    origin = get_origin(target)",