@nifrajs/cli 4.0.2 → 5.1.0

package/src/fix-recipes.ts

@@ -7,6 +7,8 @@ import { resolveWorkspaceLinkedPackage } from "./workspace-link.ts"
 export interface FixRecipe {
   readonly id: string
   readonly description: string
+  /** Run only by `nifra fix --code <code>`: the change it makes is a decision a person reviews first. */
+  readonly onlyWhenNamed?: true
   apply(root: string, diagnostic: Diagnostic): Promise<readonly string[]>
   readonly verify: string
 }
@@ -42,10 +44,15 @@ registerFixRecipe({
         "[nifra] the timing-safe fix finds each comparison in the syntax tree, so it needs TypeScript - run `bun add -d typescript`, then rerun the fix",
       )
     try {
-      const { rewriteSecretComparisons } = await import("./rules/security.ts")
+      const { provenBrowserFile, rewriteSecretComparisons } = await import("./rules/security.ts")
       const source = await readFile(path, "utf8")
       // Every site in the file at once, so the rest of that file's diagnostics find nothing left.
-      const rewritten = rewriteSecretComparisons(loaded.compiler, diagnostic.file, source)
+      const rewritten = rewriteSecretComparisons(
+        loaded.compiler,
+        diagnostic.file,
+        source,
+        provenBrowserFile(root, diagnostic.file),
+      )
       if (rewritten === source) return []
       await writeFile(path, rewritten, "utf8")
       return [diagnostic.file]
@@ -74,9 +81,44 @@ registerFixRecipe({
   },
 })
 
+registerFixRecipe({
+  id: "framework.api-prefix",
+  description:
+    "Serve the backend over HTTP at /api by exporting apiPrefix from the framework config.",
+  verify: "nifra check",
+  async apply(root) {
+    const { CONFIG_FILE, FRAMEWORK_FILE } = await import("./app-files.ts")
+    const { apiPrefixFix } = await import("./rules/pages.ts")
+    const frameworkPath = await resolveInsideProject(root, FRAMEWORK_FILE)
+    const configPath = await resolveInsideProject(root, CONFIG_FILE)
+    if (frameworkPath === undefined || configPath === undefined) return []
+    const source = async (path: string): Promise<string | undefined> => {
+      const file = Bun.file(path)
+      return (await file.exists()) ? await file.text() : undefined
+    }
+    const next = apiPrefixFix({
+      framework: await source(frameworkPath),
+      config: await source(configPath),
+    })
+    const edits: readonly (readonly [string, string, string | undefined])[] = [
+      [FRAMEWORK_FILE, frameworkPath, next.framework],
+      [CONFIG_FILE, configPath, next.config],
+    ]
+    const changed: string[] = []
+    for (const [file, path, text] of edits) {
+      if (text === undefined) continue
+      await writeFile(path, text, "utf8")
+      changed.push(file)
+    }
+    return changed
+  },
+})
+
 registerFixRecipe({
   id: "contracts.snapshot",
   description: "Refresh the opt-in contract lock after reviewing an intentional route change.",
+  // Rewriting the lock accepts whatever the routes changed to, which is the review the lock exists for.
+  onlyWhenNamed: true,
   verify: "nifra contracts check",
   async apply(root) {
     const { snapshotContracts } = await import("./contracts.ts")
@@ -135,6 +177,78 @@ registerFixRecipe({
   },
 })
 
+registerFixRecipe({
+  id: "route.split",
+  description:
+    "Move a route frontend file's server-only exports, and the code only they use, into its x.backend.ts.",
+  verify: "nifra check",
+  async apply(root, diagnostic) {
+    const file = diagnostic.file
+    if (file === undefined || (await resolveInsideProject(root, file)) === undefined) return []
+    const { splitRouteFile } = await import("./migrate-layout.ts")
+    return splitRouteFile(root, file)
+  },
+})
+
+registerFixRecipe({
+  id: "layout.migrate",
+  description:
+    "Move the app onto the frontend/backend layout, as `nifra migrate layout --write` does.",
+  onlyWhenNamed: true,
+  verify: "nifra check --lints-only",
+  async apply(root) {
+    const { migrateLayout } = await import("./migrate-layout.ts")
+    const result = await migrateLayout(root, { write: true })
+    return [
+      ...new Set([
+        ...result.moves.map((move) => move.to),
+        ...result.splits.flatMap((split) => [split.file, split.backend]),
+        ...result.rewritten,
+        ...result.tooling.map((edit) => edit.file),
+      ]),
+    ].sort()
+  },
+})
+
+registerFixRecipe({
+  id: "schemas.draft",
+  description:
+    "Draft the missing loader or action output schema from the function's return type, for the author to review.",
+  verify: "nifra check --lints-only",
+  async apply(root, diagnostic) {
+    const file = diagnostic.file
+    if (file === undefined) return []
+    const path = await resolveInsideProject(root, file)
+    if (path === undefined) return []
+    const schema = diagnostic.evidence
+      ?.find((line) => line.startsWith("missing: "))
+      ?.slice("missing: ".length)
+    if (schema !== "loaderOutput" && schema !== "actionOutput") return []
+    const { planOutputSchemas } = await import("./output-schemas.ts")
+    const source = await readFile(path, "utf8")
+    // Only this declaration: other schemas in the file, generated or hand-written, stay as they are.
+    const plan = await planOutputSchemas(
+      root,
+      [file],
+      (read) => (read === file ? source : undefined),
+      {
+        draft: (at, name) => at === file && name === schema,
+      },
+    )
+    const blocked =
+      plan.warnings.length > 0
+        ? plan.warnings.join("; ")
+        : plan.entries.find((entry) => entry.schema === schema && entry.reason !== undefined)
+            ?.reason
+    if (blocked !== undefined)
+      throw new Error(`[nifra] no ${schema} was drafted in ${file}: ${blocked}`)
+    const drafted = plan.edits.get(file)
+    if (drafted === undefined) return []
+    await writeFile(path, drafted, "utf8")
+    return [file]
+  },
+})
+
 /**
  * How many typecheck passes the reserved-segment codemod will run. A nested collision
  * (`/api/delete/then`) only reveals its second site once the first is rewritten, so one pass is not

package/src/hand-built-manifest.ts

@@ -0,0 +1,144 @@
+/**
+ * A route manifest built by hand from a list that names no backend half. `buildManifest(files, load)`
+ * pairs a page with its `.backend.*` half only when both are in `files`: it is pure, so it cannot know
+ * a half is missing. A test or server that spells the list out (an array literal, or `import.meta.glob`
+ * patterns) and leaves the halves out runs every route without its loader, action and guards.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { Glob } from "bun"
+import { codePositionMask } from "./check.ts"
+import { expressionEnd } from "./rules/data-guard.ts"
+
+/** A `buildManifest(...)` call whose file list reaches pages under `routes/` but not their halves. */
+export interface HandBuiltManifest {
+  readonly file: string
+  readonly line: number
+  /** How the list was spelled out. */
+  readonly source: "array" | "glob"
+  /** The backend halves, cwd-relative, of pages the list reaches but whose half it does not. */
+  readonly missing: readonly string[]
+}
+
+/** A `buildManifest(...)` call and the literal entries or glob patterns of its file list. */
+export interface ManifestList {
+  readonly file: string
+  readonly line: number
+  readonly source: "array" | "glob"
+  readonly entries: readonly string[]
+}
+
+// Mirrors `isRouteBackendFile` in @nifrajs/web's manifest.
+const BACKEND_HALF = /\.backend\.(?:[cm]?[jt]s)$/
+const LITERAL = /(["'`])((?:\\.|(?!\1)[^\\])*)\1/g
+
+const lineAt = (text: string, index: number): number => text.slice(0, index).split("\n").length
+
+/**
+ * The `buildManifest(` calls in `content` whose first argument is spelled out in source: an array of
+ * string literals, or an expression around `import.meta.glob(...)` with literal patterns. A list built
+ * any other way (a variable, a spread, a template with a substitution) is not read.
+ */
+export function manifestListsIn(file: string, content: string): ManifestList[] {
+  if (!content.includes("buildManifest")) return []
+  const mask = codePositionMask(content)
+  const lists: ManifestList[] = []
+  for (const call of mask.matchAll(/\bbuildManifest\s*\(/g)) {
+    const start = call.index + call[0].length
+    const end = expressionEnd(mask, start)
+    const argument = mask.slice(start, end).trim()
+    const literals = [...content.slice(start, end).matchAll(LITERAL)].map((m) => m[2] ?? "")
+    if (literals.some((text) => text.includes("${"))) continue
+    let source: ManifestList["source"]
+    if (argument.startsWith("[") && argument.endsWith("]")) {
+      // Every element a literal: the mask, with literals blanked, holds only brackets and commas.
+      if (!/^\[[\s,]*\]$/.test(argument)) continue
+      source = "array"
+    } else if (argument.includes("import.meta.glob(")) {
+      source = "glob"
+    } else continue
+    lists.push({ file, line: lineAt(content, call.index), source, entries: literals })
+  }
+  return lists
+}
+
+function filesUnder(routesDir: string): readonly string[] {
+  try {
+    return readdirSync(routesDir, { recursive: true, encoding: "utf8" }).map((rel) =>
+      rel.replaceAll("\\", "/"),
+    )
+  } catch {
+    return []
+  }
+}
+
+const stem = (file: string): string => file.replace(/\.[^./]+$/, "")
+
+/** A glob pattern from source, relative to `routes/` when it names that directory. */
+function routesRelative(pattern: string): string {
+  const at = pattern.lastIndexOf("routes/")
+  return at === -1 ? pattern.replace(/^(?:\.{0,2}\/)+/, "") : pattern.slice(at + "routes/".length)
+}
+
+function reaches(list: ManifestList): (file: string) => boolean {
+  if (list.source === "array") {
+    const listed = new Set(list.entries.map((entry) => entry.replace(/^\.\//, "")))
+    return (file) => listed.has(file)
+  }
+  const glob = (pattern: string): ((file: string) => boolean) => {
+    const compiled = new Glob(routesRelative(pattern))
+    return (file) => compiled.match(file) || compiled.match(`routes/${file}`)
+  }
+  const include = list.entries.filter((p) => !p.startsWith("!")).map(glob)
+  const exclude = list.entries.filter((p) => p.startsWith("!")).map((p) => glob(p.slice(1)))
+  return (file) => include.some((match) => match(file)) && !exclude.some((match) => match(file))
+}
+
+/** The `routes/` directory nearest above `file`, up to and including `cwd`'s own, as a cwd-relative path. */
+function routesDirFor(cwd: string, file: string): string | undefined {
+  for (let dir = dirname(file); ; dir = dirname(dir)) {
+    const candidate = dir === "." ? "routes" : `${dir}/routes`
+    const abs = join(cwd, candidate)
+    if (existsSync(abs) && statSync(abs).isDirectory()) return candidate
+    if (dir === "." || dir === "/" || dir === "") return undefined
+  }
+}
+
+/** The lists that reach a page under their app's `routes/` but not the backend half beside it. */
+export function handBuiltManifests(
+  cwd: string,
+  lists: readonly ManifestList[],
+): HandBuiltManifest[] {
+  const found: HandBuiltManifest[] = []
+  const filesByDir = new Map<string, readonly string[]>()
+  for (const list of lists) {
+    const routesDir = routesDirFor(cwd, list.file)
+    if (routesDir === undefined) continue
+    let files = filesByDir.get(routesDir)
+    if (files === undefined) {
+      files = filesUnder(join(cwd, routesDir))
+      filesByDir.set(routesDir, files)
+    }
+    const halves = files.filter((file) => BACKEND_HALF.test(file))
+    if (halves.length === 0) continue
+    const listed = reaches(list)
+    const missing = halves.filter((half) => {
+      if (listed(half)) return false
+      const page = stem(half.replace(BACKEND_HALF, ""))
+      return files.some((file) => !BACKEND_HALF.test(file) && stem(file) === page && listed(file))
+    })
+    if (missing.length > 0) {
+      const shown = missing.map((half) => `${routesDir}/${half}`)
+      found.push({ file: list.file, line: list.line, source: list.source, missing: shown })
+    }
+  }
+  return found
+}
+
+/** The advisory `nifra doctor` prints for one finding. */
+export function handBuiltManifestMessage(finding: HandBuiltManifest): string {
+  const list = finding.source === "array" ? "a file list" : "import.meta.glob patterns"
+  const shown = finding.missing.slice(0, 3)
+  const more = finding.missing.length > 3 ? ` and ${finding.missing.length - 3} more` : ""
+  return `${finding.file}:${finding.line} builds a route manifest from ${list} that leaves out ${finding.missing.length} backend half(s) of pages it lists (${shown.join(", ")}${more}). buildManifest pairs a page with its .backend.* half only when both are listed, so those pages run without their loaders, actions and guards. Use discoverRoutes("./routes") from @nifrajs/web/fs, or the generated server-manifest.`
+}

package/src/hooks-report.ts

@@ -0,0 +1,135 @@
+/**
+ * `nifra routes --hooks`: which hooks run for each route and for each prefix's unmatched paths, and the
+ * diff between two such reports (`--since <file>`, and `nifra upgrade`, which captures one before it
+ * writes). The report itself is `reflectHooks` from `@nifrajs/core/reflection`.
+ */
+import type { ReflectedHook, ReflectedHookReport } from "@nifrajs/core/reflection"
+
+/** Where `nifra upgrade --write` keeps the report it captured before editing anything. */
+export const HOOKS_BEFORE_UPGRADE_FILE = ".nifra/hooks-before-upgrade.json"
+
+export async function collectHookReport(backend: unknown): Promise<ReflectedHookReport> {
+  const { reflectHooks } = await import("@nifrajs/core/reflection")
+  return reflectHooks(backend)
+}
+
+const entryText = (hook: ReflectedHook): string =>
+  `${hook.kind} ${hook.name}${hook.headers === undefined ? "" : ` [${hook.headers.join(", ")}]`} (${hook.site})`
+
+/** One line per hook, keyed by `METHOD /path` for routes and `unmatched /prefix` for the rest. */
+export function hookReportTargets(report: ReflectedHookReport): Map<string, readonly string[]> {
+  const targets = new Map<string, readonly string[]>()
+  for (const route of report.routes) {
+    targets.set(`${route.method} ${route.path}`, route.hooks.map(entryText))
+  }
+  for (const entry of report.unmatched) {
+    targets.set(`unmatched ${entry.prefix}`, entry.hooks.map(entryText))
+  }
+  return targets
+}
+
+export function renderHookReport(report: ReflectedHookReport): string {
+  const targets = hookReportTargets(report)
+  if (targets.size === 0) return "no backend routes to report hooks for"
+  const lines: string[] = []
+  for (const [target, hooks] of targets) {
+    lines.push(target)
+    if (hooks.length === 0) lines.push("  (no hooks)")
+    for (const hook of hooks) lines.push(`  ${hook}`)
+  }
+  if (!report.complete) {
+    lines.push(
+      "",
+      "Some hooks have no recorded origin (site `unknown`): origins are recorded only outside production builds.",
+    )
+  }
+  return lines.join("\n")
+}
+
+export interface HookReportChange {
+  readonly target: string
+  readonly added: readonly string[]
+  readonly removed: readonly string[]
+}
+
+/** What runs differently: per route or unmatched prefix, the hooks it gained and lost. */
+export function diffHookReports(
+  before: ReflectedHookReport,
+  after: ReflectedHookReport,
+): readonly HookReportChange[] {
+  const old = hookReportTargets(before)
+  const now = hookReportTargets(after)
+  const changes: HookReportChange[] = []
+  const minus = (from: readonly string[], take: readonly string[]): string[] => {
+    const left = [...take]
+    return from.filter((entry) => {
+      const index = left.indexOf(entry)
+      if (index === -1) return true
+      left.splice(index, 1)
+      return false
+    })
+  }
+  const targets = [...new Set([...old.keys(), ...now.keys()])].sort()
+  for (const target of targets) {
+    const was = old.get(target) ?? []
+    const is = now.get(target) ?? []
+    const added = minus(is, was)
+    const removed = minus(was, is)
+    if (added.length > 0 || removed.length > 0) changes.push({ target, added, removed })
+  }
+  return changes
+}
+
+export function renderHookDiff(changes: readonly HookReportChange[]): string {
+  if (changes.length === 0) return "hook scope unchanged"
+  const lines: string[] = []
+  for (const change of changes) {
+    lines.push(change.target)
+    for (const entry of change.added) lines.push(`  + ${entry}`)
+    for (const entry of change.removed) lines.push(`  - ${entry}`)
+  }
+  return lines.join("\n")
+}
+
+const field = (value: unknown, key: string): unknown =>
+  typeof value === "object" && value !== null ? Reflect.get(value, key) : undefined
+
+const hooksValid = (row: unknown): boolean => {
+  const hooks = field(row, "hooks")
+  return (
+    Array.isArray(hooks) &&
+    hooks.every(
+      (hook) =>
+        typeof field(hook, "kind") === "string" &&
+        typeof field(hook, "name") === "string" &&
+        typeof field(hook, "site") === "string",
+    )
+  )
+}
+
+function isHookReport(value: unknown): value is ReflectedHookReport {
+  const routes = field(value, "routes")
+  const unmatched = field(value, "unmatched")
+  return (
+    typeof field(value, "complete") === "boolean" &&
+    Array.isArray(routes) &&
+    Array.isArray(unmatched) &&
+    routes.every(
+      (row) =>
+        typeof field(row, "method") === "string" &&
+        typeof field(row, "path") === "string" &&
+        hooksValid(row),
+    ) &&
+    unmatched.every((row) => typeof field(row, "prefix") === "string" && hooksValid(row))
+  )
+}
+
+/** A saved report, parsed; `undefined` when the text is not one. */
+export function parseHookReport(text: string): ReflectedHookReport | undefined {
+  try {
+    const value: unknown = JSON.parse(text)
+    return isHookReport(value) ? value : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/init-agents.ts

@@ -9,8 +9,8 @@
  *                                   `## Project structure` section, appended when missing (or a minimal
  *                                   file if none exists)
  *
- * The generators are imported from `create-nifra/agent-files` - the SAME source of truth `create-nifra`
- * uses at scaffold time - so a retrofitted app and a freshly scaffolded one get byte-identical configs.
+ * The generators come from `./agent-files.ts`, a byte-identical copy of the module `create-nifra` uses at
+ * scaffold time, so a retrofitted app and a freshly scaffolded one get byte-identical configs.
  *
  * Safety: this writes into the user's existing tree, so it NEVER silently clobbers a file they may have
  * customized. By default an existing `.mcp.json` / `CLAUDE.md` / `.cursor/mcp.json` is SKIPPED with a
@@ -44,7 +44,7 @@ import {
   MCP_SERVER_COMMAND,
   mcpJson,
   STRUCTURE_HEADING,
-} from "create-nifra/agent-files"
+} from "./agent-files.ts"
 import { installedNifraVersion, resolveRootState } from "./mcp-root.ts"
 
 /** What happened to one file during the retrofit, for the printed report + the `--json` shape. */
@@ -121,13 +121,17 @@ async function assertSafeParents(cwd: string, abs: string): Promise<void> {
   }
 }
 
-/** Refuse to write anything that is not a plain absent-or-regular file: a symlink here would
- * redirect the write, and a directory or device node would make it fail in a confusing way. */
-async function assertRegularTarget(abs: string, rel: string): Promise<void> {
+/** Never write anything that is not a plain absent-or-regular file: a symlink here would redirect
+ * the write, and a directory or device node would make it fail in a confusing way. Such a file is
+ * reported and left alone rather than stopping the run - a symlinked CLAUDE.md is a common alias
+ * for AGENTS.md. */
+async function nonRegularTarget(
+  abs: string,
+  rel: string,
+): Promise<InitAgentsFileResult | undefined> {
   const stat = await lstatOrMissing(abs)
-  if (stat !== undefined && (stat.isSymbolicLink() || !stat.isFile())) {
-    throw new Error(`[nifra] refusing to write non-regular file: ${rel}`)
-  }
+  if (stat === undefined || (stat.isFile() && !stat.isSymbolicLink())) return undefined
+  return { path: rel, action: "skipped", note: "not a regular file - left alone" }
 }
 
 /**
@@ -142,7 +146,8 @@ async function writeOwned(
 ): Promise<InitAgentsFileResult> {
   const abs = safeJoin(cwd, rel)
   await assertSafeParents(cwd, abs)
-  await assertRegularTarget(abs, rel)
+  const irregular = await nonRegularTarget(abs, rel)
+  if (irregular !== undefined) return irregular
   if (!force && (await fileExists(abs))) {
     return { path: rel, action: "skipped", note: "exists - pass --force to overwrite" }
   }
@@ -180,7 +185,8 @@ async function atomicWrite(
 async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
   const abs = safeJoin(cwd, AGENTS_MD_PATH)
   await assertSafeParents(cwd, abs)
-  await assertRegularTarget(abs, AGENTS_MD_PATH)
+  const irregular = await nonRegularTarget(abs, AGENTS_MD_PATH)
+  if (irregular !== undefined) return irregular
   const sections = [{ heading: "## MCP server", text: agentsMcpSection() }]
   if (await isDirectory(safeJoin(cwd, "routes"))) {
     sections.push({ heading: STRUCTURE_HEADING, text: agentsStructureSection() })
@@ -252,7 +258,7 @@ function nameMember(
   return { text: rewritten, named }
 }
 
-interface PinScan {
+export interface PinScan {
   /** The input with every stale pin rewritten - every other character untouched. */
   readonly text: string
   /** Pins found, current or stale. */
@@ -296,8 +302,9 @@ function repinRegistry(text: string, target: string, member?: string): PinScan {
   return named ? { ...scan, text: rewritten, named: member } : scan
 }
 
-/** Every file that carries the pin, and the part of it --sync-mcp may rewrite. */
-const PIN_SITES: readonly {
+/** Every file that carries the pin, and the part of it --sync-mcp and `nifra upgrade --write` may
+ * rewrite. */
+export const PIN_SITES: readonly {
   readonly path: string
   readonly repin: (text: string, target: string, member?: string) => PinScan
 }[] = [

package/src/internal/config-paths.ts

@@ -0,0 +1,154 @@
+/**
+ * The module path a nifra config names, read from its source without running it. The loader reads a
+ * string from the app root (`"./src/client.tsx"`, or an alias or package name the bundler resolves);
+ * `resolve`/`join` from `node:path` of the config's own folder and literal segments, or
+ * `fileURLToPath(new URL("x", import.meta.url))`, names a file relative to the config itself.
+ */
+import { posix } from "node:path"
+import type * as TS from "typescript"
+
+export interface StaticConfigPath {
+  /** `"app"`: read from the app root as the loader reads a string. `"config"`: from the config's folder. */
+  readonly base: "app" | "config"
+  readonly path: string
+  /** The string literal's text, quotes excluded, for an `"app"` path: [start, end). */
+  readonly span?: readonly [number, number]
+}
+
+const OWN_DIR = new Set(["import.meta.dir", "import.meta.dirname", "__dirname"])
+const PATH_MODULES = new Set(["node:path", "path", "node:path/posix", "path/posix"])
+const URL_MODULES = new Set(["node:url", "url"])
+
+interface PathBindings {
+  /** Local names of `resolve` and `join`. */
+  readonly calls: ReadonlySet<string>
+  /** Default and namespace imports of `node:path`. */
+  readonly namespaces: ReadonlySet<string>
+  readonly fileURLToPath: ReadonlySet<string>
+}
+
+function pathBindings(ts: typeof TS, sf: TS.SourceFile): PathBindings {
+  const calls = new Set<string>()
+  const namespaces = new Set<string>()
+  const fileURLToPath = new Set<string>()
+  for (const statement of sf.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+      continue
+    const from = statement.moduleSpecifier.text
+    const clause = statement.importClause
+    if (clause === undefined || clause.isTypeOnly) continue
+    const isPath = PATH_MODULES.has(from)
+    if (!isPath && !URL_MODULES.has(from)) continue
+    if (isPath && clause.name !== undefined) namespaces.add(clause.name.text)
+    const bindings = clause.namedBindings
+    if (bindings === undefined) continue
+    if (ts.isNamespaceImport(bindings)) {
+      if (isPath) namespaces.add(bindings.name.text)
+      continue
+    }
+    for (const element of bindings.elements) {
+      if (element.isTypeOnly) continue
+      const imported = (element.propertyName ?? element.name).text
+      if (isPath && (imported === "resolve" || imported === "join")) calls.add(element.name.text)
+      else if (!isPath && imported === "fileURLToPath") fileURLToPath.add(element.name.text)
+    }
+  }
+  return { calls, namespaces, fileURLToPath }
+}
+
+const unwrap = (ts: typeof TS, node: TS.Expression): TS.Expression => {
+  let current = node
+  while (
+    ts.isAsExpression(current) ||
+    ts.isSatisfiesExpression(current) ||
+    ts.isParenthesizedExpression(current) ||
+    ts.isNonNullExpression(current)
+  )
+    current = current.expression
+  return current
+}
+
+const isLiteral = (
+  ts: typeof TS,
+  node: TS.Node | undefined,
+): node is TS.StringLiteral | TS.NoSubstitutionTemplateLiteral =>
+  node !== undefined && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+
+/** A readable static path, normalized; `undefined` for an absolute one or a URL. */
+function relativeSegments(segments: readonly string[]): string | undefined {
+  if (segments.some((segment) => segment.startsWith("/") || /^[a-z][a-z\d+.-]*:/i.test(segment)))
+    return undefined
+  const path = posix.normalize(posix.join(...segments))
+  return path === "." ? undefined : path
+}
+
+/**
+ * Create a reader for one config file. It answers for an expression the config exports, so a path
+ * built any other way (a variable, `process.cwd()`, a template with substitutions) is `undefined`.
+ */
+export function configPathReader(
+  ts: typeof TS,
+  sf: TS.SourceFile,
+): (node: TS.Expression | undefined) => StaticConfigPath | undefined {
+  const bindings = pathBindings(ts, sf)
+  const isPathCall = (callee: TS.Expression): boolean =>
+    ts.isIdentifier(callee)
+      ? bindings.calls.has(callee.text)
+      : ts.isPropertyAccessExpression(callee) &&
+        ts.isIdentifier(callee.expression) &&
+        bindings.namespaces.has(callee.expression.text) &&
+        (callee.name.text === "resolve" || callee.name.text === "join")
+  return (node) => {
+    if (node === undefined) return undefined
+    const value = unwrap(ts, node)
+    if (isLiteral(ts, value))
+      return { base: "app", path: value.text, span: [value.getStart(sf) + 1, value.getEnd() - 1] }
+    if (!ts.isCallExpression(value)) return undefined
+    const [first, ...rest] = value.arguments
+    if (isPathCall(value.expression)) {
+      if (first === undefined || !OWN_DIR.has(first.getText(sf)) || rest.length === 0)
+        return undefined
+      const segments: string[] = []
+      for (const segment of rest) {
+        if (!isLiteral(ts, segment)) return undefined
+        segments.push(segment.text)
+      }
+      const path = relativeSegments(segments)
+      return path === undefined ? undefined : { base: "config", path }
+    }
+    if (
+      ts.isIdentifier(value.expression) &&
+      bindings.fileURLToPath.has(value.expression.text) &&
+      first !== undefined &&
+      ts.isNewExpression(first) &&
+      first.expression.getText(sf) === "URL" &&
+      first.arguments?.length === 2 &&
+      first.arguments[1]?.getText(sf) === "import.meta.url" &&
+      isLiteral(ts, first.arguments[0])
+    ) {
+      const path = relativeSegments([first.arguments[0].text])
+      return path === undefined ? undefined : { base: "config", path }
+    }
+    return undefined
+  }
+}
+
+/** The `export const <name> = ...` initializer in a config, or `undefined`. */
+export function exportedInitializer(
+  ts: typeof TS,
+  sf: TS.SourceFile,
+  name: string,
+): TS.Expression | undefined {
+  for (const statement of sf.statements) {
+    if (
+      !ts.isVariableStatement(statement) ||
+      !statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+    )
+      continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.name.text === name)
+        return declaration.initializer
+    }
+  }
+  return undefined
+}

package/src/internal/installed-package.ts

@@ -0,0 +1,15 @@
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+/** The manifest of the installed package `name`, as Node finds it: the nearest `node_modules/<name>`
+ * at or above the importing file. A workspace link resolves through its symlink. */
+export function installedManifest(fromFile: string, name: string): string | undefined {
+  let dir = dirname(fromFile)
+  for (;;) {
+    const manifest = join(dir, "node_modules", name, "package.json")
+    if (existsSync(manifest)) return manifest
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}