@nifrajs/web 5.0.0 → 5.2.0

package/src/internal/codegen.ts

@@ -5,9 +5,12 @@ import {
   ACTION_GLOBAL,
   BOUNDARY_GLOBAL,
   COMPONENT_GLOBAL,
+  COPY_CHUNKS_GLOBAL,
+  COPY_REALM,
   DATA_GLOBAL,
   HANDOVER_ID,
   LAYOUT_DATA_GLOBAL,
+  LOCALES_GLOBAL,
   ROOT_ATTRIBUTE,
   ROUTE_GLOBAL,
 } from "../render-seam.ts"
@@ -23,6 +26,7 @@ const HANDOVER_GLOBALS = [
   BOUNDARY_GLOBAL,
   COMPONENT_GLOBAL,
   PRERENDERED_GLOBAL,
+  LOCALES_GLOBAL,
 ]
 export interface GenerateClientEntryOptions {
   /**
@@ -39,6 +43,9 @@ export interface GenerateClientEntryOptions {
   /** Turn a route/layout source file (relative to the routes dir) into an import specifier. */
   readonly resolve: (file: string) => string
   readonly serverComponents?: boolean
+  /** The build moved copy tables into per-locale chunks: the handover carries the chunk URLs, and a
+   * navigation loads the copy of the URL it goes to beside the route's code. */
+  readonly copyChunks?: boolean
 }
 
 /**
@@ -222,7 +229,7 @@ export function generateClientEntry(
     // routeId → the ids and `handle` exports `useMatches` reports (layouts, then the page).
     `const layoutIdsOf = ${jsValueLiteral(layoutIdsOf)}`,
     "const matchChains = {}",
-    "const loadModule = async (id) => {",
+    `const ${options.copyChunks === true ? "loadRoute" : "loadModule"} = async (id) => {`,
     "  if (chains[id]) return",
     "  const mods = await loaders[id]()",
     // For an error route the `_error` module is appended LAST: wrap the page (now second-to-last) in
@@ -260,6 +267,17 @@ export function generateClientEntry(
     "  routeHooks[id] = { clientLoader: page.clientLoader, clientAction: page.clientAction, boundaries }",
     "  if (page.ssr === false) holds[id] = [...chains[id].slice(0, -1), page.HydrateFallback ?? (() => null)]",
     "}",
+    ...(options.copyChunks === true
+      ? [
+          `const copyRealm = () => globalThis[Symbol.for(${jsStringLiteral(COPY_REALM)})]`,
+          // A second prepare covers a copy definition the route's own code brought in.
+          "const loadModule = async (id, path) => {",
+          "  if (path === undefined) return loadRoute(id)",
+          "  await Promise.all([loadRoute(id), copyRealm()?.prepare(path)])",
+          "  await copyRealm()?.prepare(path)",
+          "}",
+        ]
+      : []),
     // The server hands page state over as one inert JSON script; lift it onto the globals the
     // router, the deferred mapper and the adapters read, before any of them runs. Only the LAST
     // matching <script> counts, and only known keys: page HTML (sanitized user content) can carry an
@@ -268,7 +286,7 @@ export function generateClientEntry(
     "const handover = handovers[handovers.length - 1]",
     "if (handover !== undefined) {",
     '  const state = JSON.parse(handover.textContent || "{}")',
-    `  for (const key of ${jsValueLiteral(HANDOVER_GLOBALS)}) {`,
+    `  for (const key of ${jsValueLiteral(options.copyChunks === true ? [...HANDOVER_GLOBALS, COPY_CHUNKS_GLOBAL] : HANDOVER_GLOBALS)}) {`,
     "    if (Object.prototype.hasOwnProperty.call(state, key)) Reflect.set(window, key, state[key])",
     "  }",
     "}",
@@ -383,7 +401,7 @@ export function generateClientEntry(
     // page URL), so a soft-nav re-resolves the SAME absolute canonical/og:url - no head drift.
     "      const nonce = currentDocumentNonce()",
     "      const args = { data: s.data, pageData: s.data, params: s.params, origin: location.origin, ...(nonce === undefined ? {} : { nonce }) }",
-    "      applyHead(mergeHeads(resolveChainMeta(metas[s.routeId] ?? [undefined], s.layoutData, args)))",
+    "      applyHead(mergeHeads(resolveChainMeta(metas[s.routeId] ?? [undefined], s.layoutData, args)), s.path)",
     "    }",
     "  })",
     "}).catch((error) => console.error('[nifra/web] hydration failed:', error))",
@@ -453,6 +471,9 @@ export interface GenerateServerManifestOptions {
   readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined
   /** How framework-owned stylesheet links should activate before the generated client mounts. */
   readonly cssLoading?: CssLoadingMode
+  /** Locale key -> copy chunk URL (`buildClient`'s `BuildManifest.copyChunks`) - baked as
+   * `export const copyChunks` when the client build split copy tables, for `createWebApp`. */
+  readonly copyChunks?: Readonly<Record<string, string>> | undefined
   /** Emit **lazy** per-route loaders (`() => import("./routes/x")`, a static specifier) instead of
    * eager `import * as`, so a bundler with code-splitting emits one chunk per route - loaded on the
    * first request to it, not all at boot (smaller cold-start parse). Default `false` (eager). Both
@@ -500,6 +521,7 @@ export function generateServerManifest(
     styles,
     routeStyles,
     cssLoading: requestedCssLoading,
+    copyChunks,
     lazy = false,
   } = options
   // A missing entry would bake `clientEntry = undefined` and the build would still succeed, leaving
@@ -541,6 +563,11 @@ export function generateServerManifest(
   const stylesLine = `export const styles = ${jsValueLiteral(styles ?? [])}`
   const routeStylesLine = `export const routeStyles = ${jsValueLiteral(routeStyles ?? {})}`
   const cssLoadingLine = `export const cssLoading = ${jsStringLiteral(cssLoading)}`
+  // Only a build that split copy tables has the line; its server entry is the one that imports it.
+  const copyChunksLines =
+    copyChunks === undefined || Object.keys(copyChunks).length === 0
+      ? []
+      : [`export const copyChunks = ${jsValueLiteral(copyChunks)}`]
   if (lazy) {
     // Lazy: `() => import("./routes/x")` per route (static specifier → one chunk per route under a
     // code-splitting bundler, loaded on first request). The map keys are the route-relative paths
@@ -558,6 +585,7 @@ export function generateServerManifest(
       stylesLine,
       routeStylesLine,
       cssLoadingLine,
+      ...copyChunksLines,
       `export const manifest = buildManifest(Object.keys(loaders), ${LAZY_IMPORTER})`,
     ].join("\n")}\n`
   }
@@ -577,6 +605,7 @@ export function generateServerManifest(
     stylesLine,
     routeStylesLine,
     cssLoadingLine,
+    ...copyChunksLines,
     `export const manifest = buildManifest(Object.keys(modules), ${EAGER_IMPORTER})`,
   ].join("\n")}\n`
 }

package/src/internal/copy-split.ts

@@ -0,0 +1,220 @@
+/**
+ * Copy tables (`@nifrajs/i18n/copy`) in a production client build. Each table a module declares is
+ * replaced by its chunk id, and its values move into one chunk per locale, so a page's JavaScript carries
+ * the copy of the locale it renders in and none of the others. The server bundle keeps every table whole.
+ *
+ * The tables are found by `@nifrajs/i18n/extract` with the app's own TypeScript, both resolved from the
+ * app root: `@nifrajs/web` depends on neither. An app with no `defineCopy` pays one source scan.
+ */
+import { createHash } from "node:crypto"
+import { type Dirent, readdirSync, readFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { join, resolve as resolvePath } from "node:path"
+import { pathToFileURL } from "node:url"
+import type { BunPlugin } from "bun"
+import type * as TS from "typescript"
+import { addSourceTransform, normalizeFilePath } from "../plugins/kit.ts"
+import { isTypeScriptCompiler } from "./typescript-api.ts"
+
+const COPY_MODULE = "@nifrajs/i18n/copy"
+const EXTRACT_MODULE = "@nifrajs/i18n/extract"
+const SCRIPT = /\.[cm]?[jt]sx?$/
+const REWRITABLE = /\.m?[jt]sx?(\?|$)/
+const DEPENDENCY = /[\\/]node_modules[\\/]/
+const MAX_DEPTH = 32
+
+/** The part of `@nifrajs/i18n/extract` the build reads. */
+interface TableSite {
+  readonly id: string
+  readonly values?: Readonly<Record<string, unknown>>
+  readonly definition: { readonly file: string; readonly name: string }
+}
+interface Scanner {
+  tables(file: string): readonly TableSite[]
+  definition(ref: TableSite["definition"]): { readonly locales?: unknown } | undefined
+  rewrite(file: string): string | undefined
+}
+interface SplitTable {
+  readonly id: string
+  readonly values: Readonly<Record<string, unknown>>
+  readonly locales: unknown
+}
+interface Extract {
+  createCopyScanner(
+    ts: typeof TS,
+    host: {
+      readonly root: string
+      read(file: string): string | undefined
+      resolve(specifier: string, from: string): string | undefined
+    },
+  ): Scanner
+  copyChunks(tables: Iterable<SplitTable>): ReadonlyMap<string, unknown>
+}
+
+const isExtract = (value: unknown): value is Extract =>
+  typeof value === "object" &&
+  value !== null &&
+  "createCopyScanner" in value &&
+  typeof value.createCopyScanner === "function" &&
+  "copyChunks" in value &&
+  typeof value.copyChunks === "function"
+
+/** A chunk file the build wrote. */
+export interface CopyChunkFile {
+  /** The file name, served under the build's public path. */
+  readonly name: string
+  readonly text: string
+}
+
+export interface CopySplit {
+  /** The client build's plugin, registered after every other one. */
+  readonly plugin: BunPlugin
+  /** A module with its tables replaced by chunk ids, or `undefined` when it has none to split. */
+  rewrite(file: string, source: string): string | undefined
+  /** One chunk per locale for the tables this build split, and each one's URL by locale key. */
+  chunks(publicPath: string): {
+    readonly urls: Readonly<Record<string, string>>
+    readonly files: readonly CopyChunkFile[]
+  }
+}
+
+const readText = (file: string): string | undefined => {
+  try {
+    return readFileSync(file, "utf8")
+  } catch {
+    return undefined
+  }
+}
+
+/** Whether a module under `dir` imports the copy module: the only way an app defines copy tables. */
+function definesCopy(dir: string, skip: ReadonlySet<string>, depth = 0): boolean {
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return false
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".") || entry.name === "node_modules") continue
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (depth < MAX_DEPTH && !skip.has(path) && definesCopy(path, skip, depth + 1)) return true
+    } else if (entry.isFile() && SCRIPT.test(entry.name)) {
+      if (readText(path)?.includes(COPY_MODULE) === true) return true
+    }
+  }
+  return false
+}
+
+const loaderOf = (path: string): "js" | "jsx" | "ts" | "tsx" => {
+  if (path.endsWith("x")) return path.endsWith(".tsx") ? "tsx" : "jsx"
+  return /\.m?ts$/.test(path) ? "ts" : "js"
+}
+
+/**
+ * The copy split for an app, or `undefined` when it defines no copy tables. An app that does, but whose
+ * TypeScript has no compiler API, builds with its tables whole, with a warning.
+ */
+export async function loadCopySplit(
+  root: string,
+  options: { readonly skip?: readonly string[]; readonly warn?: (message: string) => void } = {},
+): Promise<CopySplit | undefined> {
+  const appRoot = resolvePath(root)
+  const require = createRequire(join(appRoot, "package.json"))
+  let extractPath: string
+  try {
+    extractPath = require.resolve(EXTRACT_MODULE)
+  } catch {
+    return undefined
+  }
+  if (!definesCopy(appRoot, new Set((options.skip ?? []).map((dir) => resolvePath(dir))))) {
+    return undefined
+  }
+  const warn = options.warn ?? console.warn
+  let ts: unknown
+  try {
+    ts = require("typescript")
+  } catch {
+    ts = undefined
+  }
+  if (!isTypeScriptCompiler(ts)) {
+    warn(
+      "[nifra/web] copy tables ship every locale in the client bundle: splitting them by locale reads the source with the TypeScript compiler API, and the app's TypeScript has none (TypeScript 7 ships none; install typescript@^6 as a dev dependency).",
+    )
+    return undefined
+  }
+  const extract: unknown = await import(pathToFileURL(extractPath).href)
+  if (!isExtract(extract)) {
+    warn(
+      `[nifra/web] copy tables ship every locale in the client bundle: ${EXTRACT_MODULE} at ${extractPath} predates the client split; update @nifrajs/i18n.`,
+    )
+    return undefined
+  }
+  const scanner = extract.createCopyScanner(ts, {
+    root: appRoot.replaceAll("\\", "/"),
+    read: readText,
+    resolve: (specifier, from) => {
+      try {
+        return createRequire(from).resolve(specifier)
+      } catch {
+        return undefined
+      }
+    },
+  })
+
+  const split = new Map<string, readonly SplitTable[]>()
+  const rewrite = (file: string, source: string): string | undefined => {
+    const path = normalizeFilePath(file)
+    // The scanner reads the file off disk: text another transform changed first is left alone, since
+    // its tables' positions are no longer the file's.
+    if (!REWRITABLE.test(path) || DEPENDENCY.test(path) || readText(path) !== source) {
+      return undefined
+    }
+    const out = scanner.rewrite(path)
+    if (out === undefined) return undefined
+    split.set(
+      path,
+      scanner.tables(path).flatMap((site) => {
+        const locales =
+          site.values === undefined ? undefined : scanner.definition(site.definition)?.locales
+        return site.values === undefined || locales === undefined
+          ? []
+          : [{ id: site.id, values: site.values, locales }]
+      }),
+    )
+    return out
+  }
+
+  return {
+    plugin: {
+      name: "nifra-copy-split",
+      setup(build) {
+        addSourceTransform(build, rewrite)
+        build.onLoad({ filter: REWRITABLE }, async (args) => {
+          if (args.namespace !== "file") return undefined
+          const path = normalizeFilePath(args.path)
+          const contents = rewrite(path, await Bun.file(path).text())
+          return contents === undefined ? undefined : { contents, loader: loaderOf(path) }
+        })
+      },
+    },
+    rewrite,
+    chunks(publicPath) {
+      // Sorted, so a chunk's bytes, and so its name, do not depend on the order modules loaded in.
+      const tables = [...split.values()].flat().sort((a, b) => (a.id < b.id ? -1 : 1))
+      const urls: Record<string, string> = {}
+      const files: CopyChunkFile[] = []
+      if (tables.length === 0) return { urls, files }
+      const chunks = [...extract.copyChunks(tables)].sort(([a], [b]) => (a < b ? -1 : 1))
+      for (const [locale, chunk] of chunks) {
+        // A JSON string parses faster than the same object as a literal.
+        const text = `export default JSON.parse(${JSON.stringify(JSON.stringify(chunk))})\n`
+        const hash = createHash("sha256").update(text).digest("hex").slice(0, 12)
+        const name = `copy-${locale.replace(/[^A-Za-z0-9-]/g, "_")}-${hash}.js`
+        urls[locale] = `${publicPath}${name}`
+        files.push({ name, text })
+      }
+      return { urls, files }
+    },
+  }
+}

package/src/internal/package-entries.ts

@@ -0,0 +1,331 @@
+/**
+ * Per-entry package sides: `"nifra": { "environment": { ".": "backend", "./react": "frontend" } }`.
+ *
+ * An import names an entry, and that entry's side decides it. A path names no entry, so a file is owned
+ * by every mapped entry that reaches it inside the package: the entry's targets under any export
+ * condition, followed through relative imports. A stage that sees only paths decides by those owners;
+ * which entry an import may name is decided where the import is written, from its specifier.
+ */
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs"
+import { dirname, extname, join, relative } from "node:path"
+import type { PackageEnvironment } from "../zones.ts"
+import { type Token, tokenize } from "./private-env.ts"
+import { withoutQuery } from "./without-query.ts"
+
+export type EnvironmentDeclaration =
+  | { readonly kind: "none" }
+  | { readonly kind: "package"; readonly side: PackageEnvironment }
+  | { readonly kind: "entries"; readonly entries: Readonly<Record<string, PackageEnvironment>> }
+  | { readonly kind: "invalid"; readonly problem: string }
+
+const SIDES: ReadonlySet<string> = new Set(["frontend", "backend", "shared", "library"])
+const isSide = (value: unknown): value is PackageEnvironment =>
+  typeof value === "string" && SIDES.has(value)
+
+/** A manifest's `nifra.environment`. A string naming no side declares nothing, as it always has. */
+export function parseEnvironment(value: unknown): EnvironmentDeclaration {
+  if (isSide(value)) return { kind: "package", side: value }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return { kind: "none" }
+  const entries: Record<string, PackageEnvironment> = {}
+  for (const [key, side] of Object.entries(value)) {
+    if (key !== "." && !key.startsWith("./"))
+      return {
+        kind: "invalid",
+        problem: `key "${key}" must be "." or a subpath starting with "./"`,
+      }
+    if (key.indexOf("*") !== key.lastIndexOf("*"))
+      return { kind: "invalid", problem: `key "${key}" may hold one "*"` }
+    if (!isSide(side))
+      return {
+        kind: "invalid",
+        problem: `"${key}" must be one of frontend, backend, shared, library`,
+      }
+    entries[key] = side
+  }
+  return Object.keys(entries).length === 0
+    ? {
+        kind: "invalid",
+        problem: 'maps no entry; give each export subpath (".", "./react") a side',
+      }
+    : { kind: "entries", entries }
+}
+
+/**
+ * The mapped key that decides `subpath`: the exact key, else the `*` pattern with the longest prefix,
+ * then the longest key, where `*` matches at least one character - as Node matches `exports`.
+ */
+export function entryKey(
+  entries: Readonly<Record<string, PackageEnvironment>>,
+  subpath: string,
+): string | undefined {
+  if (Object.hasOwn(entries, subpath)) return subpath
+  let best: string | undefined
+  for (const key of Object.keys(entries)) {
+    const star = key.indexOf("*")
+    if (star === -1 || subpath.length < key.length) continue
+    if (!subpath.startsWith(key.slice(0, star)) || !subpath.endsWith(key.slice(star + 1))) continue
+    const bestStar = best?.indexOf("*") ?? -1
+    if (best === undefined || star > bestStar || (star === bestStar && key.length > best.length))
+      best = key
+  }
+  return best
+}
+
+export interface EntryOwnership {
+  /** Each file a mapped entry reaches, by real path, with the sides of every entry that reaches it. */
+  readonly owners: ReadonlyMap<string, ReadonlySet<PackageEnvironment>>
+  /** Export subpaths the map gives no side. */
+  readonly unmapped: readonly string[]
+}
+
+const isFile = (path: string): boolean =>
+  statSync(path, { throwIfNoEntry: false })?.isFile() ?? false
+
+const real = (path: string): string => {
+  try {
+    return realpathSync.native(path).replaceAll("\\", "/")
+  } catch {
+    return path.replaceAll("\\", "/")
+  }
+}
+
+const SCRIPT = /\.(?:[cm]?[jt]sx?|svelte|vue)$/
+const STYLESHEET = /\.(?:css|scss|sass|less|styl)$/
+const DECLARATION = /\.d\.[cm]?ts$/
+const PROBE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".json"]
+/** A TypeScript source imports its sibling by the extension it compiles to. */
+const SOURCE_TWINS: Readonly<Record<string, readonly string[]>> = {
+  ".js": [".ts", ".tsx"],
+  ".jsx": [".tsx"],
+  ".mjs": [".mts"],
+  ".cjs": [".cts"],
+}
+
+function probe(base: string): string | undefined {
+  if (isFile(base)) return base
+  const extension = extname(base)
+  for (const twin of SOURCE_TWINS[extension] ?? []) {
+    const candidate = `${base.slice(0, -extension.length)}${twin}`
+    if (isFile(candidate)) return candidate
+  }
+  for (const candidate of PROBE_EXTENSIONS.map((ext) => `${base}${ext}`)) {
+    if (isFile(candidate)) return candidate
+  }
+  for (const candidate of PROBE_EXTENSIONS.map((ext) => join(base, `index${ext}`))) {
+    if (isFile(candidate)) return candidate
+  }
+  return undefined
+}
+
+const CLAUSE_PUNCT: ReadonlySet<string> = new Set(["{", "}", ",", "*"])
+const isPunct = (token: Token | undefined, value: string): boolean =>
+  token?.kind === "punct" && token.value === value
+const isId = (token: Token | undefined, value: string): boolean =>
+  token?.kind === "id" && token.value === value
+
+/**
+ * Whether the `import`/`export` clause ending at the `from` token `at` binds only types: `import type`,
+ * `export type`, or a `{ }` list whose every specifier is `type`. Such an edge grants no ownership - a
+ * backend file a frontend entry merely types against stays backend. `import { type A }` survives as
+ * `import {}` under Vite with `verbatimModuleSyntax`; dropping it then fails closed, since the guard
+ * judges that load by the file's remaining owners.
+ */
+function typeOnlyClause(tokens: readonly Token[], at: number): boolean {
+  let start = at - 1
+  for (; start >= 0; start--) {
+    const token = tokens[start]
+    if (isId(token, "import") || isId(token, "export")) break
+    if (token?.kind !== "id" && !(token?.kind === "punct" && CLAUSE_PUNCT.has(token.value)))
+      return false
+  }
+  if (start < 0) return false
+  const clause = tokens.slice(start + 1, at)
+  // `import type from "./x"` and `import type, { a } from` bind a default import named `type`.
+  if (isId(clause[0], "type")) return clause.length > 1 && !isPunct(clause[1], ",")
+  if (!isPunct(clause[0], "{") || !isPunct(clause.at(-1), "}")) return false
+  const specifiers: Token[][] = [[]]
+  for (const token of clause.slice(1, -1)) {
+    if (isPunct(token, ",")) specifiers.push([])
+    else specifiers.at(-1)?.push(token)
+  }
+  const named = specifiers.filter((specifier) => specifier.length > 0)
+  // `{ type as x }` imports a value named `type`; `{ type A }` and `{ type A as B }` import types.
+  return (
+    named.length > 0 &&
+    named.every(
+      (specifier) =>
+        isId(specifier[0], "type") &&
+        (specifier.length === 2 || (specifier.length === 4 && isId(specifier[2], "as"))),
+    )
+  )
+}
+
+/** The relative specifiers a module loads: imports, re-exports, `import()`s, `require`s and
+ * `new URL()`s (a worker or an asset beside it). A clause binding only types loads nothing. */
+function relativeImports(code: string): string[] {
+  const tokens = tokenize(code)
+  const found: string[] = []
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]
+    if (token?.kind !== "id") continue
+    const previous = tokens[i - 1]
+    if (previous?.kind === "punct" && previous.value === ".") continue
+    let next = tokens[i + 1]
+    const call = next?.kind === "punct" && next.value === "("
+    const url = token.value === "URL" && previous?.kind === "id" && previous.value === "new"
+    if (token.value === "require" || url || (token.value === "import" && call)) {
+      if (!call) continue
+      next = tokens[i + 2]
+    } else if (token.value !== "from" && token.value !== "import") continue
+    if (next?.kind !== "string" || !/^\.\.?\//.test(next.value)) continue
+    if (token.value === "from" && typeOnlyClause(tokens, i)) continue
+    found.push(next.value)
+  }
+  return found
+}
+
+/** What a stylesheet pulls in beside it: `@import`s and `url()`s that name no scheme or root. */
+function stylesheetImports(code: string): string[] {
+  const text = code.replace(/\/\*[\s\S]*?\*\//g, "")
+  const found: string[] = []
+  for (const match of text.matchAll(
+    /@import\s+(?:url\(\s*)?["']?([^"'()\s;]+)|url\(\s*["']?([^"'()\s]+)/g,
+  )) {
+    const reference = match[1] ?? match[2] ?? ""
+    if (reference !== "" && !/^(?:[a-z][\w+.-]*:|\/|#|~)/i.test(reference)) found.push(reference)
+  }
+  return found
+}
+
+/** Every string target of an export value, under every condition. */
+function targetsOf(value: unknown): string[] {
+  if (typeof value === "string") return value.startsWith("./") ? [value] : []
+  if (Array.isArray(value)) return value.flatMap(targetsOf)
+  if (typeof value === "object" && value !== null) return Object.values(value).flatMap(targetsOf)
+  return []
+}
+
+/** `exports` as subpath entries; without it, the root is `main`/`module`/`browser` and any file a subpath. */
+function exportEntries(
+  manifest: Readonly<Record<string, unknown>>,
+  entries: Readonly<Record<string, PackageEnvironment>>,
+): Array<readonly [string, readonly string[]]> {
+  const exports = manifest.exports
+  if (exports === undefined || exports === null) {
+    const roots = [manifest.main, manifest.module, manifest.browser]
+      .filter((root): root is string => typeof root === "string")
+      .map((root) => (root.startsWith("./") ? root : `./${root}`))
+    return [
+      [".", roots.length > 0 ? roots : ["./index.js"]],
+      ...Object.keys(entries)
+        .filter((key) => key !== ".")
+        .map((key) => [key, [key]] as const),
+    ]
+  }
+  if (typeof exports !== "object" || Array.isArray(exports)) return [[".", targetsOf(exports)]]
+  const keys = Object.keys(exports)
+  if (keys.length === 0 || !keys.every((key) => key.startsWith(".")))
+    return [[".", targetsOf(exports)]]
+  return Object.entries(exports).map(([key, value]) => [key, targetsOf(value)] as const)
+}
+
+/** Every file under `dir`, outside `node_modules`. */
+function filesUnder(dir: string): string[] {
+  let names: string[]
+  try {
+    names = readdirSync(dir, { recursive: true, encoding: "utf8" })
+  } catch {
+    return []
+  }
+  return names
+    .filter((name) => !/(?:^|[\\/])node_modules(?:[\\/]|$)/.test(name))
+    .map((name) => join(dir, name))
+    .filter(isFile)
+}
+
+/** Which mapped entries reach each file of the package at `dir` (a real path). */
+export function entryOwnership(
+  dir: string,
+  manifest: Readonly<Record<string, unknown>>,
+  entries: Readonly<Record<string, PackageEnvironment>>,
+): EntryOwnership {
+  const owners = new Map<string, Set<PackageEnvironment>>()
+  const unmapped = new Set<string>()
+  const queue: Array<readonly [string, PackageEnvironment]> = []
+  const reach = (path: string, side: PackageEnvironment): void => {
+    const file = real(path)
+    if (!file.startsWith(`${dir}/`) || file.slice(dir.length).includes("/node_modules/")) return
+    const sides = owners.get(file) ?? new Set<PackageEnvironment>()
+    if (sides.has(side)) return
+    sides.add(side)
+    owners.set(file, sides)
+    queue.push([file, side])
+  }
+  const sideOf = (subpath: string, exportKey = subpath): PackageEnvironment | undefined => {
+    const key = entryKey(entries, subpath)
+    if (key === undefined) unmapped.add(exportKey)
+    return key === undefined ? undefined : entries[key]
+  }
+  for (const [key, targets] of exportEntries(manifest, entries)) {
+    const star = key.indexOf("*")
+    if (star === -1) {
+      const side = sideOf(key)
+      if (side === undefined) continue
+      for (const target of targets) {
+        const file = target.includes("*") ? undefined : probe(join(dir, target))
+        if (file !== undefined) reach(file, side)
+      }
+      continue
+    }
+    // A pattern entry: each file a target pattern matches is the subpath its `*` spells.
+    for (const target of targets) {
+      const at = target.indexOf("*")
+      if (at === -1) continue
+      const prefix = target.slice(0, at)
+      const suffix = target.slice(at + 1)
+      for (const file of filesUnder(join(dir, prefix.slice(0, prefix.lastIndexOf("/") + 1)))) {
+        const path = `./${relative(dir, file).replaceAll("\\", "/")}`
+        if (path.length <= prefix.length + suffix.length) continue
+        if (!path.startsWith(prefix) || !path.endsWith(suffix)) continue
+        const matched = path.slice(prefix.length, path.length - suffix.length)
+        const side = sideOf(`${key.slice(0, star)}${matched}${key.slice(star + 1)}`, key)
+        if (side !== undefined) reach(file, side)
+      }
+    }
+  }
+  const imports = new Map<string, readonly string[]>()
+  for (const [file, side] of queue) {
+    const script = SCRIPT.test(file) && !DECLARATION.test(file)
+    if (!script && !STYLESHEET.test(file)) continue
+    let specifiers = imports.get(file)
+    if (specifiers === undefined) {
+      try {
+        const code = readFileSync(file, "utf8")
+        specifiers = script ? relativeImports(code) : stylesheetImports(code)
+      } catch {
+        specifiers = []
+      }
+      imports.set(file, specifiers)
+    }
+    for (const specifier of specifiers) {
+      const found = probe(join(dirname(file), withoutQuery(specifier)))
+      if (found !== undefined) reach(found, side)
+    }
+  }
+  return { owners, unmapped: [...unmapped].sort() }
+}
+
+/**
+ * The `package.json` of the installed package `name`, as Node finds it: the nearest
+ * `node_modules/<name>` at or above `fromDir`.
+ */
+export function installedManifest(fromDir: string, name: string): string | undefined {
+  let dir = fromDir
+  for (;;) {
+    const manifest = join(dir, "node_modules", name, "package.json")
+    if (isFile(manifest)) return manifest
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}