okengine 0.14.1 → 0.15.2

package/src/compiler/generate-adopt.ts

@@ -1,20 +1,30 @@
 /**
- * `.adopt()` route-barrel generator — the disk-file alternative to a
- * virtual-module Bun plugin (investigated and rejected: `Bun.plugin()`'s
+ * `.adopt()` / auto-register barrel generator — the disk-file alternative
+ * to a virtual-module Bun plugin (investigated and rejected: `Bun.plugin()`'s
  * `onResolve` is never invoked for an unresolvable specifier during a plain
  * runtime `import()`, so `oke dev` and `oke build` would resolve a virtual
  * module differently — measured, not assumed).
  *
- * A real file on disk is an ordinary import: identical resolution under
- * `oke dev`'s runtime `import()` and `oke build`'s `Bun.build()`. Convention
- * (validated against every current example app — both `create-oke`
- * templates and the `skyport` compiler fixture, 7/7): every unit under
- * `<rootDir>/src/flows/*` has an `index.ts` barrel.
+ * Two unit shapes:
+ * - **Barrel** — only `index.ts` (+ skip-list) → `import * as notes from "./notes/index.ts"; export { notes }`
+ * - **Tree** — `[param]` / `(group)` / extra route files → synthesized namespace
+ *   with `stampHttpPath` / `stampFlowName` after import
+ *
+ * Mixed barrel `index.ts` + tree files is a generate error (ambiguous:
+ * `index` is also a reserved leaf).
  */
 
-import { mkdir, readdir, rename, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import {
+  importSpecifierFromWalked,
+  isSkipFlowFile,
+  nameFromFlowFile,
+  pathFromFlowFile,
+  toPosixPath,
+} from "./flow-path.ts";
+
 /** Options for {@link generateAdoptBarrel}. */
 export interface GenerateAdoptBarrelOptions {
   /** Project root (contains `src/flows`). */
@@ -29,13 +39,16 @@ export interface AdoptBarrelResult {
   readonly source: string;
   /** Unit (folder) names included, sorted. */
   readonly units: readonly string[];
-  /** Folders under `flowsDir` skipped for lacking an `index.ts` barrel. */
+  /** Folders under `flowsDir` skipped (empty / invalid name / no routes). */
   readonly skipped: readonly string[];
 }
 
 const GENERATED_HEADER =
   "// AUTO-GENERATED by `oke dev` / `oke build` — do not edit by hand.\n" +
-  "// Regenerated from every `src/flows/<unit>/index.ts` unit folder.\n";
+  "// Regenerated from every `src/flows/<unit>/` folder (barrel or file tree).\n";
+
+const CATCHALL_COMMENT =
+  '// Catch-all param is "*" — call api.docs.get({ "*": "a/b/c" }), not { slug }.\n';
 
 /** Filename of the on-disk `.adopt()` barrel under the flows directory. */
 export const ADOPT_BARREL_FILE = "generated.ts";
@@ -43,11 +56,39 @@ export const ADOPT_BARREL_FILE = "generated.ts";
 /** A folder name usable as an `export * as <name>` binding. */
 const VALID_UNIT_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 
+const EXPORT_CONST = /^export const ([A-Za-z_$][A-Za-z0-9_$]*)\b/gm;
+
+const EXPLICIT_FLOW_UNIT = /flow\(\s*["']([A-Za-z_$][A-Za-z0-9_$]*)\./g;
+
+/**
+ * Generate-time failure (mixed barrel + tree, export collision, unit drift).
+ */
+export class GenerateAdoptError extends Error {
+  /** Stable error name. */
+  override readonly name = "GenerateAdoptError";
+
+  /**
+   * @param message - Why generation failed
+   */
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/** One route file discovered under a unit folder. */
+interface WalkedFlowFile {
+  /** POSIX path relative to the unit folder (`[id]/get.ts`). */
+  readonly relFromUnit: string;
+  /** File source (for export + drift scans). */
+  readonly source: string;
+  /** `export const` names. */
+  readonly exports: readonly string[];
+}
+
 /**
  * Write the adopt barrel atomically: `generated.ts.tmp` → rename to
- * `generated.ts`. Concurrent readers (e.g. `bun --hot` racing a save) never
- * observe a torn/partial file — plain `writeFile` on the destination would
- * truncate first.
+ * `generated.ts`. Skips the write when bytes are unchanged so the `src/`
+ * watcher + bun `--hot` do not loop.
  *
  * @param rootDir - Project root
  * @param source - Full barrel source from {@link generateAdoptBarrel}
@@ -57,24 +98,28 @@ export async function writeAdoptBarrel(
   rootDir: string,
   source: string,
   flowsDir = "src/flows",
-): Promise<void> {
+): Promise<{ written: boolean }> {
   const dir = join(rootDir, flowsDir);
   const target = join(dir, ADOPT_BARREL_FILE);
   const tmp = `${target}.tmp`;
   await mkdir(dir, { recursive: true });
+  try {
+    const existing = await readFile(target, "utf8");
+    if (existing === source) return { written: false };
+  } catch {
+    // missing — write
+  }
   await writeFile(tmp, source);
   await rename(tmp, target);
+  return { written: true };
 }
 
 /**
- * Scan `<rootDir>/<flowsDir>/*` and emit a barrel re-exporting every unit
- * folder's `index.ts` under its folder name — the same shape
- * `.adopt({ main, notes })` already takes by hand.
+ * Scan `<rootDir>/<flowsDir>/*` and emit a barrel that registers every unit.
  *
- * Never throws: a missing/unreadable flows directory yields an empty
- * barrel, same posture as the rest of the lazy AoT tooling (best-effort,
- * boot-time checks are what enforce staleness — see
- * `assertAdoptBarrelFresh` in `kernel/boot.ts`).
+ * Never throws for a missing/unreadable flows directory (empty barrel).
+ * Mixed barrel + tree, export collisions, and unit-prefix drift throw
+ * {@link GenerateAdoptError}.
  *
  * @param options - Root dir / flows dir override
  */
@@ -86,12 +131,17 @@ export async function generateAdoptBarrel(
 
   const units: string[] = [];
   const skipped: string[] = [];
+  const unitBlocks: string[] = [];
+  const registerNames: string[] = [];
+  const declareLines: string[] = [];
+  let hasCatchAll = false;
+  let needsStampImport = false;
+
   try {
     const dirents = await readdir(abs, { withFileTypes: true });
     for (const d of dirents.sort((a, b) => a.name.localeCompare(b.name))) {
       if (!d.isDirectory()) continue;
-      const hasBarrel = await Bun.file(join(abs, d.name, "index.ts")).exists();
-      if (!hasBarrel) {
+      if (d.name.startsWith("_")) {
         skipped.push(d.name);
         continue;
       }
@@ -99,13 +149,217 @@ export async function generateAdoptBarrel(
         skipped.push(d.name);
         continue;
       }
+
+      const unitAbs = join(abs, d.name);
+      const files = await listFlowFiles(unitAbs);
+      const hasIndex = files.some((f) => f.relFromUnit === "index.ts");
+      const hasOther = files.some((f) => f.relFromUnit !== "index.ts");
+
+      if (hasIndex && hasOther) {
+        throw new GenerateAdoptError(
+          `Unit "${d.name}" mixes a barrel index.ts with tree route files. ` +
+            `Use only index.ts (barrel), or move the collection path to route.ts ` +
+            `and keep [id]/ beside it.`,
+        );
+      }
+
+      if (files.length === 0) {
+        skipped.push(d.name);
+        continue;
+      }
+
       units.push(d.name);
+      registerNames.push(d.name);
+      declareLines.push(`    readonly ${d.name}: typeof ${d.name};`);
+
+      if (unitBlocks.length > 0) unitBlocks.push("");
+
+      if (hasIndex && !hasOther) {
+        const spec = JSON.stringify(importSpecifierFromWalked(`${d.name}/index.ts`));
+        unitBlocks.push(`import * as ${d.name} from ${spec};`);
+        unitBlocks.push(`export { ${d.name} };`);
+        continue;
+      }
+
+      needsStampImport = true;
+      const { lines, catchAll } = emitTreeUnit(d.name, files);
+      if (catchAll) hasCatchAll = true;
+      unitBlocks.push(...lines);
     }
-  } catch {
+  } catch (err) {
+    if (err instanceof GenerateAdoptError) throw err;
     // Missing flows dir — empty barrel, not a throw (mirrors extractManifest).
   }
 
-  const lines = units.map((u) => `export * as ${u} from "./${u}/index.ts";`);
-  const source = lines.length > 0 ? `${GENERATED_HEADER}${lines.join("\n")}\n` : GENERATED_HEADER;
+  const parts: string[] = [GENERATED_HEADER.trimEnd()];
+  if (hasCatchAll) parts.push(CATCHALL_COMMENT.trimEnd());
+  if (registerNames.length > 0) {
+    const stamp = needsStampImport ? ", stampFlowName, stampHttpPath" : "";
+    parts.push(`import { registerFlowUnits${stamp} } from "okengine";`);
+  }
+  if (unitBlocks.length > 0) {
+    parts.push(unitBlocks.join("\n"));
+  }
+  if (registerNames.length > 0) {
+    parts.push(`registerFlowUnits({ ${registerNames.join(", ")} });`);
+    parts.push('declare module "okengine" {');
+    parts.push("  interface RegisteredFlowUnits {");
+    parts.push(...declareLines);
+    parts.push("  }");
+    parts.push("}");
+  }
+
+  const source = `${parts.join("\n")}\n`;
   return { source, units, skipped };
 }
+
+/**
+ * Walk a unit folder for route files (skip-list applied).
+ *
+ * @param unitAbs - Absolute unit directory
+ */
+async function listFlowFiles(unitAbs: string): Promise<WalkedFlowFile[]> {
+  const out: WalkedFlowFile[] = [];
+
+  const walk = async (dir: string, rel: string): Promise<void> => {
+    const dirents = await readdir(dir, { withFileTypes: true });
+    for (const d of dirents) {
+      if (d.name.startsWith("_")) continue;
+      const posixName = toPosixPath(d.name);
+      if (d.isDirectory()) {
+        if (posixName.startsWith("[[") && posixName.endsWith("]]")) {
+          throw new GenerateAdoptError(
+            `Optional catch-all "${posixName}" is not supported — use [...slug] (param is "*").`,
+          );
+        }
+        await walk(join(dir, d.name), rel ? `${rel}/${posixName}` : posixName);
+        continue;
+      }
+      if (!posixName.endsWith(".ts") && !posixName.endsWith(".tsx")) continue;
+      if (isSkipFlowFile(posixName)) continue;
+      const relFile = rel ? `${rel}/${posixName}` : posixName;
+      const source = await readFile(join(dir, d.name), "utf8");
+      const exports = listExportedConsts(source);
+      const relPosix = toPosixPath(relFile);
+      // Barrel `index.ts` counts even with no `export const` (`export {}` / re-exports).
+      if (exports.length === 0 && relPosix !== "index.ts") continue;
+      out.push({ relFromUnit: relPosix, source, exports });
+    }
+  };
+
+  try {
+    await walk(unitAbs, "");
+  } catch (err) {
+    if (err instanceof GenerateAdoptError) throw err;
+  }
+
+  return out.sort((a, b) => a.relFromUnit.localeCompare(b.relFromUnit));
+}
+
+/**
+ * Collect `export const` binding names.
+ *
+ * @param source - TypeScript source
+ */
+export function listExportedConsts(source: string): string[] {
+  const names: string[] = [];
+  EXPORT_CONST.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = EXPORT_CONST.exec(source))) {
+    const name = match[1];
+    if (name) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * Emit import + stamped namespace for a tree unit.
+ *
+ * @param unit - Folder name
+ * @param files - Walked route files
+ */
+function emitTreeUnit(
+  unit: string,
+  files: WalkedFlowFile[],
+): { lines: string[]; catchAll: boolean } {
+  const used = new Map<string, string>();
+  let catchAll = false;
+  const importLines: string[] = [];
+  const fieldLines: string[] = [];
+
+  for (const file of files) {
+    if (file.relFromUnit.includes("[...")) catchAll = true;
+    assertUnitPrefix(unit, file);
+    const spec = importSpecifierFromWalked(`${unit}/${file.relFromUnit}`);
+    if (spec.includes("\\")) {
+      throw new GenerateAdoptError(
+        `Import specifier for ${unit}/${file.relFromUnit} is not POSIX.`,
+      );
+    }
+    const alias = importAlias(unit, file.relFromUnit);
+    importLines.push(`import * as ${alias} from ${JSON.stringify(spec)};`);
+
+    const inferred =
+      pathFromFlowFile(`${unit}/${file.relFromUnit}`) ??
+      pathFromFlowFile(`src/flows/${unit}/${file.relFromUnit}`);
+
+    for (const exp of file.exports) {
+      const prev = used.get(exp);
+      if (prev !== undefined) {
+        throw new GenerateAdoptError(
+          `Unit "${unit}" exports "${exp}" from both ${prev} and ${file.relFromUnit}.`,
+        );
+      }
+      used.set(exp, file.relFromUnit);
+      const flowName = nameFromFlowFile(`${unit}/${file.relFromUnit}`, exp) ?? `${unit}.${exp}`;
+      const pathLit = JSON.stringify(inferred ?? "/");
+      fieldLines.push(
+        `  ${exp}: stampHttpPath(stampFlowName(${alias}.${exp}, ${JSON.stringify(flowName)}), ${pathLit}),`,
+      );
+    }
+  }
+
+  const lines = [
+    ...importLines,
+    "",
+    `const ${unit} = {`,
+    ...fieldLines,
+    `};`,
+    `export { ${unit} };`,
+  ];
+  return { lines, catchAll };
+}
+
+/**
+ * Fail when `flow("other.x")` lives under a different unit folder.
+ *
+ * @param unit - Folder name
+ * @param file - Walked file
+ */
+function assertUnitPrefix(unit: string, file: WalkedFlowFile): void {
+  EXPLICIT_FLOW_UNIT.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = EXPLICIT_FLOW_UNIT.exec(file.source))) {
+    const prefix = match[1];
+    if (prefix && prefix !== unit) {
+      throw new GenerateAdoptError(
+        `flow("${prefix}.…") in ${unit}/${file.relFromUnit} does not match the folder "${unit}".`,
+      );
+    }
+  }
+}
+
+/**
+ * Stable import alias for a walked file (`notes/[id]/get.ts` → `notes_$id$_get`).
+ *
+ * @param unit - Unit folder
+ * @param relFromUnit - POSIX relative path
+ */
+export function importAlias(unit: string, relFromUnit: string): string {
+  const posix = toPosixPath(relFromUnit).replace(/\.[^.]+$/, "");
+  const body = posix
+    .replace(/\[/g, "$")
+    .replace(/\]/g, "$")
+    .replace(/[^\w$]/g, "_");
+  return `${unit}_${body}`;
+}