okengine 0.14.1 → 0.15.2

package/src/compiler/flow-path.test.ts

@@ -0,0 +1,96 @@
+/**
+ * File-tree path stamps — POSIX normalize is a requirement, not an assumption.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  importSpecifierFromWalked,
+  nameFromFlowFile,
+  pathFromFlowFile,
+  toPosixPath,
+  unitFromFlowFile,
+} from "./flow-path.ts";
+
+describe("toPosixPath / importSpecifierFromWalked", () => {
+  test("normalizes Windows backslashes to /", () => {
+    expect(toPosixPath("notes\\[id]\\get.ts")).toBe("notes/[id]/get.ts");
+  });
+
+  test("emits a POSIX import specifier even when the walked path used \\", () => {
+    const spec = importSpecifierFromWalked("notes\\[id]\\get.ts");
+    expect(spec).toBe("./notes/[id]/get.ts");
+    expect(spec.includes("\\")).toBe(false);
+  });
+
+  test("catch-all walked with \\ becomes a quoted-ready POSIX specifier", () => {
+    expect(importSpecifierFromWalked("docs\\[...slug]\\get.ts")).toBe("./docs/[...slug]/get.ts");
+  });
+});
+
+describe("pathFromFlowFile", () => {
+  test("[id] → :id on a reserved get leaf", () => {
+    expect(pathFromFlowFile("notes/[id]/get.ts")).toBe("/notes/:id");
+  });
+
+  test("[...slug] → *", () => {
+    expect(pathFromFlowFile("docs/[...slug]/get.ts")).toBe("/docs/*");
+  });
+
+  test("(group) is omitted from the URL", () => {
+    expect(pathFromFlowFile("notes/(ops)/archive.ts")).toBe("/notes/archive");
+  });
+
+  test("reserved leaves do not add a segment", () => {
+    expect(pathFromFlowFile("notes/list.ts")).toBe("/notes");
+    expect(pathFromFlowFile("notes/create.ts")).toBe("/notes");
+    expect(pathFromFlowFile("notes/route.ts")).toBe("/notes");
+    expect(pathFromFlowFile("notes/[id]/update.ts")).toBe("/notes/:id");
+    expect(pathFromFlowFile("notes/[id]/remove.ts")).toBe("/notes/:id");
+  });
+
+  test("action leaves add a segment", () => {
+    expect(pathFromFlowFile("notes/[id]/archive.ts")).toBe("/notes/:id/archive");
+    expect(pathFromFlowFile("notes/query.ts")).toBe("/notes/query");
+  });
+
+  test("main omits the URL prefix — health.ts is /health, index/route is /", () => {
+    expect(pathFromFlowFile("main/health.ts")).toBe("/health");
+    expect(pathFromFlowFile("main/index.ts")).toBe("/");
+    expect(pathFromFlowFile("main/route.ts")).toBe("/");
+  });
+
+  test("skip-list files return undefined", () => {
+    expect(pathFromFlowFile("notes/shapes.ts")).toBeUndefined();
+    expect(pathFromFlowFile("notes/signals.ts")).toBeUndefined();
+    expect(pathFromFlowFile("notes/list.test.ts")).toBeUndefined();
+    expect(pathFromFlowFile("notes/_lib/util.ts")).toBeUndefined();
+    expect(pathFromFlowFile("src/flows/generated.ts")).toBeUndefined();
+  });
+
+  test("accepts a source path under src/flows/", () => {
+    expect(pathFromFlowFile("src/flows/notes/[id]/get.ts")).toBe("/notes/:id");
+  });
+
+  test("Windows-shaped string yields the same URL as POSIX (requirement)", () => {
+    expect(pathFromFlowFile("notes\\[id]\\get.ts")).toBe("/notes/:id");
+    expect(pathFromFlowFile("notes\\[...slug]\\get.ts")).toBe("/notes/*");
+    expect(pathFromFlowFile("src\\flows\\notes\\[id]\\get.ts")).toBe("/notes/:id");
+  });
+
+  test("[[...slug]] optional catch-all is not inferred", () => {
+    expect(pathFromFlowFile("docs/[[...slug]]/get.ts")).toBeUndefined();
+  });
+});
+
+describe("nameFromFlowFile / unitFromFlowFile", () => {
+  test("unit + export — [id] is not part of the name", () => {
+    expect(unitFromFlowFile("src/flows/notes/[id]/get.ts")).toBe("notes");
+    expect(nameFromFlowFile("src/flows/notes/[id]/get.ts", "get")).toBe("notes.get");
+    expect(nameFromFlowFile("notes/[id]/archive.ts", "archive")).toBe("notes.archive");
+  });
+
+  test("main unit keeps the main. prefix on the Flow name", () => {
+    expect(nameFromFlowFile("main/health.ts", "health")).toBe("main.health");
+    expect(nameFromFlowFile("main/route.ts", "root")).toBe("main.root");
+  });
+});

package/src/compiler/flow-path.ts

@@ -0,0 +1,173 @@
+/**
+ * File-tree URL + Flow-name stamps.
+ *
+ * One catalog for the adopt generator and Manifest extract — never derive a
+ * URL from `flow("notes.get")`. Always POSIX-normalize first; Windows `\`
+ * must not leak into inferred paths or generated import specifiers.
+ */
+
+/** Reserved leaves that do not add a URL segment (same five as `http.resource`, plus `index` / `route`). */
+export const RESERVED_LEAVES: ReadonlySet<string> = new Set([
+  "list",
+  "create",
+  "get",
+  "update",
+  "remove",
+  "index",
+  "route",
+]);
+
+/** Filenames that are never routes. */
+export const SKIP_FLOW_FILENAMES: ReadonlySet<string> = new Set([
+  "generated.ts",
+  "shapes.ts",
+  "signals.ts",
+]);
+
+/**
+ * Convert a filesystem path to POSIX `/` separators.
+ *
+ * Requirement, not an assumption: `node:path` `join` / `relative` emit `\`
+ * on Windows. ESM specifiers and URL stamps are always `/`.
+ *
+ * @param path - Walked or hand-built path (may contain `\`)
+ */
+export function toPosixPath(path: string): string {
+  return path.replace(/\\/g, "/");
+}
+
+/**
+ * Build an ESM import specifier from a path walked relative to `src/flows`.
+ *
+ * Always POSIX — even when `walked` used `\`.
+ *
+ * @param walked - Relative path from the flows directory
+ */
+export function importSpecifierFromWalked(walked: string): string {
+  const posix = toPosixPath(walked).replace(/^\.?\//, "");
+  return `./${posix}`;
+}
+
+/**
+ * True when a file (or its basename) is on the skip list.
+ *
+ * @param fileName - Basename or relative path
+ */
+export function isSkipFlowFile(fileName: string): boolean {
+  const base = toPosixPath(fileName).split("/").pop() ?? fileName;
+  if (base.startsWith("_")) return true;
+  if (SKIP_FLOW_FILENAMES.has(base)) return true;
+  if (base.endsWith(".test.ts") || base.endsWith(".test.tsx")) return true;
+  return false;
+}
+
+/**
+ * Strip a source path down to the segment after `flows/`.
+ *
+ * Accepts `notes/[id]/get.ts`, `src/flows/notes/[id]/get.ts`, or an absolute
+ * path containing `/flows/`.
+ *
+ * @param input - Relative or absolute path
+ */
+export function relFromFlowsDir(input: string): string {
+  const posix = toPosixPath(input).replace(/^\.?\//, "");
+  const marker = "/flows/";
+  const idx = posix.lastIndexOf(marker);
+  if (idx >= 0) return posix.slice(idx + marker.length);
+  if (posix.startsWith("flows/")) return posix.slice("flows/".length);
+  if (posix.startsWith("src/flows/")) return posix.slice("src/flows/".length);
+  return posix;
+}
+
+/**
+ * Infer the HTTP path from a flow file's location under `src/flows`.
+ *
+ * - `[id]` → `:id`, `[...slug]` → `*`
+ * - `(group)` omitted
+ * - reserved leaves omit their filename
+ * - `main` omits the first URL segment
+ * - skip-list files return `undefined`
+ *
+ * @param relFromFlowsDirOrSource - Path relative to flows or a source file path
+ */
+export function pathFromFlowFile(relFromFlowsDirOrSource: string): string | undefined {
+  const posix = toPosixPath(relFromFlowsDirOrSource);
+  const rel = relFromFlowsDir(posix);
+  if (!rel) return undefined;
+
+  const parts = rel.split("/").filter(Boolean);
+  if (parts.length < 2) return undefined;
+
+  const fileName = parts[parts.length - 1]!;
+  if (isSkipFlowFile(fileName)) return undefined;
+  if (!/\.(ts|tsx|js|jsx)$/.test(fileName)) return undefined;
+
+  const leaf = fileName.replace(/\.(ts|tsx|js|jsx)$/, "");
+  const unit = parts[0]!;
+  const dirs = parts.slice(1, -1);
+
+  const segments: string[] = [];
+  if (unit !== "main") segments.push(unit);
+
+  for (const dir of dirs) {
+    if (dir.startsWith("_")) return undefined;
+    if (dir.startsWith("(") && dir.endsWith(")")) continue;
+    if (dir.startsWith("[[") && dir.endsWith("]]")) return undefined;
+    const mapped = mapSegment(dir);
+    if (mapped === undefined) return undefined;
+    segments.push(mapped);
+  }
+
+  if (!RESERVED_LEAVES.has(leaf)) {
+    const mapped = mapSegment(leaf);
+    if (mapped === undefined) return undefined;
+    segments.push(mapped);
+  }
+
+  if (segments.length === 0) return "/";
+  return `/${segments.join("/")}`;
+}
+
+/**
+ * Infer `unit.export` from a flow file + export name.
+ *
+ * `[id]` / `(group)` never enter the name.
+ *
+ * @param filePath - Source path under `flows/`
+ * @param exportName - `export const` binding
+ */
+export function nameFromFlowFile(
+  filePath: string,
+  exportName: string | undefined,
+): string | undefined {
+  if (!exportName) return undefined;
+  const unit = unitFromFlowFile(filePath);
+  if (!unit) return undefined;
+  return `${unit}.${exportName}`;
+}
+
+/**
+ * First-level folder under `src/flows` — the client unit.
+ *
+ * @param filePath - Source path
+ */
+export function unitFromFlowFile(filePath: string): string | undefined {
+  const rel = relFromFlowsDir(filePath);
+  const unit = rel.split("/").filter(Boolean)[0];
+  if (!unit) return undefined;
+  if (unit.startsWith("[") || unit.startsWith("(") || unit.startsWith("_")) return undefined;
+  if (unit.includes(".")) return undefined;
+  return unit;
+}
+
+/**
+ * Map one folder or leaf token to a URL segment.
+ *
+ * @param token - `[id]`, `[...slug]`, or a static name
+ */
+function mapSegment(token: string): string | undefined {
+  if (token.startsWith("[[") && token.endsWith("]]")) return undefined;
+  if (token.startsWith("[...") && token.endsWith("]")) return "*";
+  if (token.startsWith("[") && token.endsWith("]")) return `:${token.slice(1, -1)}`;
+  return token;
+}

package/src/compiler/generate-adopt.test.ts

@@ -6,7 +6,8 @@ import { describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { generateAdoptBarrel } from "./generate-adopt.ts";
+import { importSpecifierFromWalked } from "./flow-path.ts";
+import { generateAdoptBarrel, GenerateAdoptError, writeAdoptBarrel } from "./generate-adopt.ts";
 
 async function makeUnit(root: string, name: string, withIndex = true): Promise<void> {
   const dir = join(root, "src/flows", name);
@@ -22,8 +23,11 @@ describe("generateAdoptBarrel", () => {
       await makeUnit(root, "main");
       const result = await generateAdoptBarrel({ rootDir: root });
       expect(result.units).toEqual(["main", "notes"]);
-      expect(result.source).toContain('export * as main from "./main/index.ts";');
-      expect(result.source).toContain('export * as notes from "./notes/index.ts";');
+      expect(result.source).toContain('import * as main from "./main/index.ts";');
+      expect(result.source).toContain('import * as notes from "./notes/index.ts";');
+      expect(result.source).toContain("export { main };");
+      expect(result.source).toContain("export { notes };");
+      expect(result.source).toContain("registerFlowUnits({ main, notes })");
       expect(result.skipped).toEqual([]);
     } finally {
       await rm(root, { recursive: true, force: true });
@@ -66,6 +70,15 @@ describe("generateAdoptBarrel", () => {
       );
       const result = await generateAdoptBarrel({ rootDir: root });
       const generatedPath = join(root, "src/flows/generated.ts");
+      await mkdir(join(root, "node_modules/okengine"), { recursive: true });
+      await writeFile(
+        join(root, "node_modules/okengine/package.json"),
+        JSON.stringify({ name: "okengine", type: "module", exports: "./index.ts" }),
+      );
+      await writeFile(
+        join(root, "node_modules/okengine/index.ts"),
+        "export function registerFlowUnits() {}\n",
+      );
       await writeFile(generatedPath, result.source);
 
       // Same shape as `import * as main from "./flows/main"; import * as
@@ -82,4 +95,100 @@ describe("generateAdoptBarrel", () => {
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test("tree unit synthesizes a namespace and POSIX-quoted [id] imports", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-gen-"));
+    try {
+      const getDir = join(root, "src/flows/notes/[id]");
+      await mkdir(getDir, { recursive: true });
+      await writeFile(
+        join(root, "src/flows/notes/list.ts"),
+        'export const list = { name: "notes.list" };\n',
+      );
+      await writeFile(join(getDir, "get.ts"), 'export const get = { name: "notes.get" };\n');
+      const result = await generateAdoptBarrel({ rootDir: root });
+      expect(result.units).toEqual(["notes"]);
+      expect(result.source).toContain('from "./notes/[id]/get.ts"');
+      expect(result.source).toContain('from "./notes/list.ts"');
+      expect(result.source.includes("\\")).toBe(false);
+      expect(result.source).toContain("stampHttpPath");
+      expect(result.source).toContain('"/notes/:id"');
+      expect(result.source).toContain('"/notes"');
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("mixed barrel index.ts + tree files is a generate error", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-gen-"));
+    try {
+      await mkdir(join(root, "src/flows/notes/[id]"), { recursive: true });
+      await writeFile(join(root, "src/flows/notes/index.ts"), "export const list = 1;\n");
+      await writeFile(join(root, "src/flows/notes/[id]/get.ts"), "export const get = 1;\n");
+      await expect(generateAdoptBarrel({ rootDir: root })).rejects.toBeInstanceOf(
+        GenerateAdoptError,
+      );
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("two files exporting the same name is a generate error", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-gen-"));
+    try {
+      await mkdir(join(root, "src/flows/notes"), { recursive: true });
+      await writeFile(join(root, "src/flows/notes/list.ts"), "export const get = 1;\n");
+      await writeFile(join(root, "src/flows/notes/route.ts"), "export const get = 2;\n");
+      await expect(generateAdoptBarrel({ rootDir: root })).rejects.toThrow(/exports "get"/);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("flow('tasks.get') under notes/ is a generate error", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-gen-"));
+    try {
+      await mkdir(join(root, "src/flows/notes"), { recursive: true });
+      await writeFile(
+        join(root, "src/flows/notes/get.ts"),
+        'export const get = flow("tasks.get", { do: () => 1 });\n',
+      );
+      await expect(generateAdoptBarrel({ rootDir: root })).rejects.toThrow(
+        /does not match the folder/,
+      );
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("writeAdoptBarrel skips identical bytes", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-gen-"));
+    try {
+      await mkdir(join(root, "src/flows"), { recursive: true });
+      const source = "// same\n";
+      expect((await writeAdoptBarrel(root, source)).written).toBe(true);
+      expect((await writeAdoptBarrel(root, source)).written).toBe(false);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("import specifiers stay POSIX when the walked path used backslash", () => {
+    const spec = importSpecifierFromWalked("notes\\[id]\\get.ts");
+    expect(spec).toBe("./notes/[id]/get.ts");
+    expect(spec.includes("\\")).toBe(false);
+  });
+
+  test("[...slug] unit adds the * client-key comment", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oke-adopt-gen-"));
+    try {
+      await mkdir(join(root, "src/flows/docs/[...slug]"), { recursive: true });
+      await writeFile(join(root, "src/flows/docs/[...slug]/get.ts"), "export const get = 1;\n");
+      const result = await generateAdoptBarrel({ rootDir: root });
+      expect(result.source).toContain('Catch-all param is "*"');
+      expect(result.source).toContain('from "./docs/[...slug]/get.ts"');
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });