@nifrajs/web 5.0.0 → 5.2.0

package/src/zones.ts

@@ -11,7 +11,15 @@
  */
 import { closeSync, existsSync, openSync, readFileSync, readSync, realpathSync } from "node:fs"
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
+import {
+  type EntryOwnership,
+  type EnvironmentDeclaration,
+  entryKey,
+  entryOwnership,
+  parseEnvironment,
+} from "./internal/package-entries.ts"
 import { SERVER_FN_MODULE } from "./internal/server-boundary.ts"
+import { withoutQuery } from "./internal/without-query.ts"
 
 export type Zone =
   /** A page or special file under `routes/` - the frontend half of a route. */
@@ -39,12 +47,16 @@ export type Classification =
       readonly declared?: PackageEnvironment
       /** A third-party file's path inside `node_modules`: `drizzle-orm/node-postgres/index.js`. */
       readonly modulePath?: string
+      /** The export subpath (`"./react"`) whose own declared side decided this import. */
+      readonly entry?: string
     }
   | {
       readonly zone: "error"
       readonly reason: string
       /** The undeclared package this error is about: every file in it shares the one fix. */
       readonly package?: string
+      /** The export subpath the import named, when the package's map gives it no side. */
+      readonly entry?: string
     }
 
 export type PackageEnvironment = "frontend" | "backend" | "shared" | "library"
@@ -151,11 +163,14 @@ export interface ZoneConfig {
    * longest prefix over a shorter one, and a package's own declaration over all of them.
    */
   readonly packages?: Readonly<Record<string, PackageEnvironment>>
-  /** App-relative folders holding backend code, beside `backend/` (`"migrations"`). */
+  /**
+   * App-relative folders or files holding backend code, beside `backend/` (`"migrations"`). A path
+   * listed inside another one's folder overrides it: the most specific entry wins.
+   */
   readonly backend?: readonly string[]
-  /** App-relative folders holding frontend code, beside `frontend/`. */
+  /** App-relative folders or files holding frontend code, beside `frontend/`. */
   readonly frontend?: readonly string[]
-  /** App-relative folders holding code both sides import, beside `shared/`. */
+  /** App-relative folders or files holding code both sides import, beside `shared/`. */
   readonly shared?: readonly string[]
 }
 
@@ -189,9 +204,10 @@ const recordOf = (value: unknown): Readonly<Record<string, unknown>> | undefined
     : undefined
 
 /**
- * Validate a `zones` setting. `source` names where it came from in the error. Folders are plain
- * app-relative paths (a trailing `/**` is accepted and dropped); any other glob is refused, so a
- * pattern can never match less than its author meant without saying so.
+ * Validate a `zones` setting. `source` names where it came from in the error. Folders and files are
+ * plain app-relative paths (a trailing `/**` is accepted and dropped); any other glob is refused, so
+ * a pattern can never match less than its author meant without saying so. One path under two sides
+ * is refused; a path nested in another's folder is not, since the most specific one decides.
  */
 export function parseZoneConfig(value: unknown, source: string): ZoneConfig {
   const fail = (message: string): never => {
@@ -228,7 +244,7 @@ export function parseZoneConfig(value: unknown, source: string): ZoneConfig {
     if (raw === undefined) continue
     const entries: readonly unknown[] = Array.isArray(raw)
       ? raw
-      : fail(`"${side}" must be an array of app-relative folders`)
+      : fail(`"${side}" must be an array of app-relative folders or files`)
     const folders: string[] = []
     for (const entry of entries) {
       const folder = (typeof entry === "string" ? entry : fail(`"${side}" must hold strings`))
@@ -238,18 +254,15 @@ export function parseZoneConfig(value: unknown, source: string): ZoneConfig {
         .replace(/\/+$/, "")
       const top = folder.split("/")[0] ?? ""
       if (folder === "" || folder.startsWith("/") || /^[a-z]:/i.test(folder))
-        fail(`"${side}" entry "${entry}" must be a folder relative to the app`)
+        fail(`"${side}" entry "${entry}" must be a folder or file relative to the app`)
       if (folder.split("/").includes("..")) fail(`"${side}" entry "${entry}" may not contain ".."`)
       if (/[*?[\]{}!]/.test(folder))
-        fail(`"${side}" entry "${entry}" must be a plain folder path (a trailing "/**" is allowed)`)
+        fail(`"${side}" entry "${entry}" must be a plain path (a trailing "/**" is allowed)`)
       if (RESERVED_FOLDERS.has(top) || top.startsWith(".nifra"))
         fail(`"${side}" entry "${entry}" is inside ${top}/, which already has its own rules`)
-      for (const [other, otherSide] of owner) {
-        const nested =
-          other === folder || other.startsWith(`${folder}/`) || folder.startsWith(`${other}/`)
-        if (nested && otherSide !== side)
-          fail(`"${folder}" (${side}) overlaps "${other}" (${otherSide}); a folder has one side`)
-      }
+      const other = owner.get(folder)
+      if (other !== undefined && other !== side)
+        fail(`"${folder}" is listed as both ${other} and ${side}; a path has one side`)
       owner.set(folder, side)
       folders.push(folder)
     }
@@ -301,8 +314,16 @@ const suggestedPattern = (name: string): string =>
 
 export interface ZoneClassifier {
   readonly appRoot: string
-  /** Classify a file by its absolute (or appRoot-relative) path. Results are cached per path. */
-  classify(file: string): Classification
+  /**
+   * Classify a file by its absolute (or appRoot-relative) path. Results are cached per path.
+   *
+   * With `specifier`, the import as written that resolved to `file`: when it names a package that
+   * gives each export entry its own side (`"nifra": { "environment": { ".": "backend", "./react":
+   * "frontend" } }`), the entry it names decides, since two entries may share one file. A specifier
+   * naming an entry the map leaves out is an error. The resolved file must belong to that entry, as
+   * the package's own imports reach it; one only other entries reach is judged by its path.
+   */
+  classify(file: string, specifier?: string): Classification
 }
 
 const toPosix = (path: string): string => path.replaceAll("\\", "/")
@@ -356,7 +377,19 @@ function nodeModulesPackage(path: string): string | undefined {
 interface PackageInfo {
   readonly dir: string
   readonly name: string | undefined
-  readonly environment: string | undefined
+  readonly declaration: EnvironmentDeclaration
+  readonly manifest: Readonly<Record<string, unknown>>
+}
+
+const DECLARATION_FILE = /\.d\.[cm]?ts$/
+
+/** The one side a file reached by several mapped entries takes: what each entry's importers may import. */
+function ownersSide(owners: ReadonlySet<PackageEnvironment>): PackageEnvironment {
+  const [only] = owners
+  if (owners.size === 1 && only !== undefined) return only
+  return owners.has("library") || (owners.has("frontend") && owners.has("backend"))
+    ? "library"
+    : "shared"
 }
 
 /**
@@ -374,11 +407,12 @@ export function createZoneClassifier(options: ZoneClassifierOptions): ZoneClassi
   const configuredFolders: Array<readonly [string, "backend" | "frontend" | "shared"]> = []
   for (const side of FOLDER_SIDES)
     for (const folder of zones[side] ?? []) configuredFolders.push([folder, side])
-  const folderSide = (rel: string): "backend" | "frontend" | "shared" | undefined => {
-    for (const [folder, side] of configuredFolders)
-      if (rel === folder || rel.startsWith(`${folder}/`)) return side
-    return undefined
-  }
+  // Longest first, so the most specific entry covering a file decides its side.
+  configuredFolders.sort(([a], [b]) => b.length - a.length)
+  const configuredPath = (
+    rel: string,
+  ): readonly [string, "backend" | "frontend" | "shared"] | undefined =>
+    configuredFolders.find(([folder]) => rel === folder || rel.startsWith(`${folder}/`))
   const cache = new Map<string, Classification>()
   const packages = new Map<string, PackageInfo | null>()
 
@@ -395,17 +429,17 @@ export function createZoneClassifier(options: ZoneClassifierOptions): ZoneClassi
       seen.push(current)
       const manifest = join(current, "package.json")
       if (existsSync(manifest)) {
-        let parsed: { name?: unknown; nifra?: { environment?: unknown } } = {}
+        let parsed: Readonly<Record<string, unknown>> = {}
         try {
-          parsed = JSON.parse(readFileSync(manifest, "utf8")) as typeof parsed
+          parsed = recordOf(JSON.parse(readFileSync(manifest, "utf8"))) ?? {}
         } catch {
           // An unreadable manifest declares nothing; the caller reports the missing declaration.
         }
         const info: PackageInfo = {
           dir: current,
           name: typeof parsed.name === "string" ? parsed.name : undefined,
-          environment:
-            typeof parsed.nifra?.environment === "string" ? parsed.nifra.environment : undefined,
+          declaration: parseEnvironment(recordOf(parsed.nifra)?.environment),
+          manifest: parsed,
         }
         for (const visited of seen) packages.set(visited, info)
         return info
@@ -419,15 +453,96 @@ export function createZoneClassifier(options: ZoneClassifierOptions): ZoneClassi
     }
   }
 
+  const ownerships = new Map<string, EntryOwnership>()
+  const ownershipOf = (
+    info: PackageInfo,
+    entries: Readonly<Record<string, PackageEnvironment>>,
+  ): EntryOwnership => {
+    let found = ownerships.get(info.dir)
+    if (found === undefined) {
+      found = entryOwnership(info.dir, info.manifest, entries)
+      ownerships.set(info.dir, found)
+    }
+    return found
+  }
+
+  /** The package `file` is part of, when that package is not the app: installed, or a workspace sibling. */
+  const packageOf = (file: string): PackageInfo | undefined => {
+    const thirdParty = nodeModulesPackage(file)
+    if (thirdParty !== undefined) {
+      const at = file.lastIndexOf("/node_modules/") + "/node_modules/".length
+      return packageFor(file.slice(0, at + thirdParty.length))
+    }
+    return isInside(file, appRoot) ? undefined : packageFor(toPosix(dirname(file)))
+  }
+
+  /** What a side declared for `file` (by its package, an entry of it, or the app) makes it. */
+  const declaredAs = (
+    file: string,
+    info: PackageInfo | undefined,
+    side: PackageEnvironment,
+    entry?: string,
+  ): Classification => {
+    const thirdParty = nodeModulesPackage(file)
+    const named = entry === undefined || info?.name === undefined ? {} : { packageName: info.name }
+    const decided = entry === undefined ? {} : { entry }
+    if (thirdParty !== undefined) {
+      return {
+        zone: "library",
+        packageName: thirdParty,
+        modulePath: file.slice(file.lastIndexOf("/node_modules/") + "/node_modules/".length),
+        declared: side,
+        ...decided,
+      }
+    }
+    if (side !== "library") return { zone: side, ...named, ...decided }
+    return {
+      zone: "library",
+      ...(info?.name ? { packageName: info.name } : {}),
+      declared: "library",
+      ...decided,
+    }
+  }
+
+  /** A file of a package that declares a side per entry, judged by the entries that reach it. */
+  const byOwners = (
+    file: string,
+    info: PackageInfo,
+    entries: Readonly<Record<string, PackageEnvironment>>,
+  ): Classification => {
+    const ownership = ownershipOf(info, entries)
+    const owners = ownership.owners.get(file)
+    if (owners !== undefined) return declaredAs(file, info, ownersSide(owners))
+    const shown = nodeModulesPackage(file) === undefined ? file : file.slice(info.dir.length + 1)
+    const left =
+      ownership.unmapped.length === 0
+        ? ""
+        : ` (the map leaves out ${ownership.unmapped.map((key) => `"${key}"`).join(", ")})`
+    return {
+      zone: "error",
+      reason: `"${shown}" is in package "${info.name ?? info.dir}", whose "nifra.environment" gives each entry its own side, and no mapped entry reaches this file${left}. Import the package through a mapped entry`,
+    }
+  }
+
+  const invalidDeclaration = (info: PackageInfo, problem: string): Classification => {
+    const reason = `${info.dir}/package.json "nifra.environment": ${problem}`
+    return info.name === undefined
+      ? { zone: "error", reason }
+      : { zone: "error", reason, package: info.name }
+  }
+
   const classifyUncached = (file: string): Classification => {
     if (generated.has(file)) return { zone: "generated" }
     const thirdParty = nodeModulesPackage(file)
     if (thirdParty !== undefined) {
-      const info = packageFor(toPosix(dirname(file)))
+      const info = packageOf(file)
+      const declaration = info?.declaration ?? { kind: "none" }
+      if (info !== undefined && declaration.kind === "invalid")
+        return invalidDeclaration(info, declaration.problem)
+      if (info !== undefined && declaration.kind === "entries")
+        return byOwners(file, info, declaration.entries)
       const declared =
-        info?.environment !== undefined && PACKAGE_ENVIRONMENTS.has(info.environment)
-          ? (info.environment as PackageEnvironment)
-          : mappedSide(zones.packages, thirdParty)
+        declaration.kind === "package" ? declaration.side : mappedSide(zones.packages, thirdParty)
       return {
         zone: "library",
         packageName: thirdParty,
@@ -472,13 +587,20 @@ export function createZoneClassifier(options: ZoneClassifierOptions): ZoneClassi
         if (suffix === "shared") return { zone: "shared" }
         return { zone: "route-frontend" }
       }
-      const folder = ZONE_FOLDERS[top] ?? folderSide(rel)
+      const configured = ZONE_FOLDERS[top] === undefined ? configuredPath(rel) : undefined
+      const folder = ZONE_FOLDERS[top] ?? configured?.[1]
       if (folder !== undefined) {
         if (suffix === undefined || suffix === folder) return { zone: folder }
         if (suffix === "fn" && folder === "backend") return { zone: "fn" }
+        const where =
+          configured === undefined
+            ? `sits in ${top}/`
+            : configured[0] === rel
+              ? `is listed as ${folder} in "nifra.zones"`
+              : `sits in ${configured[0]}/, which "nifra.zones" lists as ${folder},`
         return {
           zone: "error",
-          reason: `"${rel}" sits in ${top}/ but its ".${suffix}" suffix says otherwise. A file belongs to one side: move it, or drop the suffix`,
+          reason: `"${rel}" ${where} but its ".${suffix}" suffix says otherwise. A file belongs to one side: move it, or drop the suffix`,
         }
       }
       if (suffix !== undefined) return { zone: suffix === "fn" ? "fn" : suffix }
@@ -486,19 +608,14 @@ export function createZoneClassifier(options: ZoneClassifierOptions): ZoneClassi
     }
     // First-party code outside the app: a workspace package, or a relative import out of the app.
     const info = packageFor(toPosix(dirname(file)))
+    const declaration = info?.declaration ?? { kind: "none" }
+    if (info !== undefined && declaration.kind === "invalid")
+      return invalidDeclaration(info, declaration.problem)
+    if (info !== undefined && declaration.kind === "entries")
+      return byOwners(file, info, declaration.entries)
     const environment =
-      info?.environment !== undefined && PACKAGE_ENVIRONMENTS.has(info.environment)
-        ? info.environment
-        : mappedSide(zones.packages, info?.name)
-    if (environment !== undefined) {
-      return environment === "library"
-        ? {
-            zone: "library",
-            ...(info?.name ? { packageName: info.name } : {}),
-            declared: "library",
-          }
-        : { zone: environment as Zone }
-    }
+      declaration.kind === "package" ? declaration.side : mappedSide(zones.packages, info?.name)
+    if (environment !== undefined) return declaredAs(file, info, environment)
     const declare = `"nifra": { "environment": "frontend" | "backend" | "shared" | "library" }`
     if (info?.name === undefined) {
       return {
@@ -514,16 +631,57 @@ export function createZoneClassifier(options: ZoneClassifierOptions): ZoneClassi
     }
   }
 
+  const byPath = (file: string): Classification => {
+    const cached = cache.get(file)
+    if (cached !== undefined) return cached
+    const result = classifyUncached(file)
+    cache.set(file, result)
+    return result
+  }
+
+  // Keyed by file and subpath: two entries may share one file and declare different sides.
+  const imports = new Map<string, Classification>()
+  const byImport = (file: string, specifier: string): Classification => {
+    const name = specifierPackage(specifier)
+    const info = name === undefined ? undefined : packageOf(file)
+    if (name === undefined || info?.name !== name || info.declaration.kind !== "entries")
+      return byPath(file)
+    const subpath = entrySubpath(specifier, name)
+    const cacheKey = `${file}\0${subpath}`
+    const cached = imports.get(cacheKey)
+    if (cached !== undefined) return cached
+    const { entries } = info.declaration
+    const key = entryKey(entries, subpath)
+    const side = key === undefined ? undefined : entries[key]
+    let result: Classification
+    if (side === undefined) {
+      const mapped = Object.keys(entries)
+        .map((entry) => `"${entry}"`)
+        .join(", ")
+      result = {
+        zone: "error",
+        reason: `"${specifier}" names the "${subpath}" entry of package "${name}", whose "nifra.environment" map gives it no side (it maps ${mapped}). Map the entry, or import one that is mapped`,
+        entry: subpath,
+      }
+    } else {
+      // The resolver's pick must belong to the named entry; a file only other entries reach (an alias
+      // pointed at it) is judged by its path. A declaration file is types only and erased.
+      const owners = ownershipOf(info, entries).owners.get(file)
+      result =
+        owners !== undefined && !owners.has(side) && !DECLARATION_FILE.test(file)
+          ? byPath(file)
+          : declaredAs(file, info, side, subpath)
+    }
+    imports.set(cacheKey, result)
+    return result
+  }
+
   return {
     appRoot,
-    classify(input: string): Classification {
+    classify(input: string, specifier?: string): Classification {
       const absolute = isAbsolute(input) ? input : resolve(appRoot, input)
       const file = realFile(absolute)
-      const cached = cache.get(file)
-      if (cached !== undefined) return cached
-      const result = classifyUncached(file)
-      cache.set(file, result)
-      return result
+      return specifier === undefined ? byPath(file) : byImport(file, specifier)
     },
   }
 }
@@ -554,6 +712,27 @@ export function specifierPackage(specifier: string): string | undefined {
   return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]
 }
 
+/** The export subpath (`"."`, `"./react"`) a bare specifier of package `name` names. */
+const entrySubpath = (specifier: string, name: string): string =>
+  `.${withoutQuery(specifier.slice(name.length))}`
+
+/**
+ * The side a package's `"nifra": { "environment": ... }` value gives the bare import `specifier` of it:
+ * the package-wide string, or the side of the entry it names - the map's exact subpath, else its most
+ * specific `*` pattern. `undefined` when it gives none, as a map that leaves the entry out does.
+ */
+export function declaredSide(
+  environment: unknown,
+  specifier: string,
+): PackageEnvironment | undefined {
+  const declaration = parseEnvironment(environment)
+  if (declaration.kind === "package") return declaration.side
+  const name = specifierPackage(specifier)
+  if (declaration.kind !== "entries" || name === undefined) return undefined
+  const key = entryKey(declaration.entries, entrySubpath(specifier, name))
+  return key === undefined ? undefined : declaration.entries[key]
+}
+
 /**
  * Why a classified file may not ship to a browser, or `undefined` when it may. A `drizzle-orm` driver
  * entry is recognized by the import as written (`specifier`) or by the file's path in the package.
@@ -564,13 +743,19 @@ export function browserDenial(
 ): string | undefined {
   if (classification.zone === "error") return classification.reason
   if (!BROWSER_ZONES.has(classification.zone)) {
+    if (classification.entry !== undefined)
+      return `package "${classification.packageName}" declares its "${classification.entry}" entry ${classification.zone}-only`
     return classification.zone === "route-backend"
       ? "it is a route's backend half, which runs on the server only"
       : "it is backend code"
   }
   if (classification.zone !== "library") return undefined
   const name = classification.packageName
-  if (classification.declared === "backend") return `package "${name}" declares itself backend-only`
+  if (classification.declared === "backend") {
+    return classification.entry === undefined
+      ? `package "${name}" declares itself backend-only`
+      : `package "${name}" declares its "${classification.entry}" entry backend-only`
+  }
   if (name !== undefined && SERVER_PACKAGES.includes(name)) {
     return `package "${name}" is server code (a driver, server SDK or credential helper)`
   }