@akanjs/devkit 3.1.1-rc.15 → 3.1.1-rc.16

package/storeWriteScanner.ts

@@ -0,0 +1,50 @@
+import type ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { type StoreCallTarget, StoreSource } from "./storeSource";
+import { WritePath } from "./writePath";
+import type { WritingActionIndex } from "./writingActionIndex";
+
+export interface StoreMultiWrite {
+  action: string;
+  line: number;
+  writes: string[];
+  writeCount: number;
+  isRootChain: boolean;
+}
+
+export class StoreWriteScanner {
+  readonly #index: WritingActionIndex;
+
+  constructor(index: WritingActionIndex) {
+    this.#index = index;
+  }
+
+  scan({ file, sourceFile }: Pick<SourceFileInfo, "file" | "sourceFile">): StoreMultiWrite[] {
+    const source = new StoreSource({ file, sourceFile });
+    return source.methods.flatMap((method) => {
+      const targets = new Map<ts.CallExpression, StoreCallTarget>();
+      const path = new WritePath((call) => {
+        const target = this.#index.writeOf(source, method, call);
+        if (target) targets.set(call, target);
+        return !!target;
+      });
+      const writes = path.along(method.body);
+      const writeCount = path.countOf(writes);
+      const second = writes[1] ?? writes[0];
+      if (writeCount < 2 || !second) return [];
+      return [
+        {
+          action: method.name,
+          line: sourceFile.getLineAndCharacterOfPosition(second.getStart(sourceFile)).line + 1,
+          writes: writes.map((call) => path.labelOf(call, sourceFile)),
+          writeCount,
+          isRootChain: writes.some((call) => StoreWriteScanner.#crossesStores(targets.get(call), method.store)),
+        },
+      ];
+    });
+  }
+
+  static #crossesStores(target: StoreCallTarget | undefined, ownStore: string) {
+    return (target?.kind === "static" && target.store !== ownStore) || (target?.kind === "action" && !target.isOwn);
+  }
+}

package/testOnlyExportScanner.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { TestOnlyExportScanner } from "./testOnlyExportScanner";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(
+    file,
+    content,
+    ts.ScriptTarget.Latest,
+    true,
+    file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  ),
+});
+
+const scan = (files: Record<string, string>) =>
+  new TestOnlyExportScanner().scan(Object.entries(files).map(([file, content]) => fileOf(file, content)));
+
+const layout = [
+  "export const groupLabelHeight = 30;",
+  "export const computeGroupBoxes = () => [groupLabelHeight];",
+  "export const groupEdgeStrips = (pad: number): number[] => (pad > 0 ? groupEdgeStrips(pad - 1) : []);",
+  "export const layoutBoard = () => 1;",
+  "",
+].join("\n");
+
+const layoutTest = [
+  'import { computeGroupBoxes, groupEdgeStrips, groupLabelHeight, layoutBoard } from "./boardLayout";',
+  "test(() => [computeGroupBoxes(), groupEdgeStrips(1), groupLabelHeight, layoutBoard()]);",
+  "",
+].join("\n");
+
+describe("TestOnlyExportScanner", () => {
+  test("flags an export only tests reference, even when it calls itself", () => {
+    const warnings = scan({
+      "apps/demo/webkit/boardLayout.ts": layout,
+      "apps/demo/webkit/boardLayout.test.ts": layoutTest,
+      "apps/demo/ui/Board.tsx":
+        'import { layoutBoard } from "@apps/demo/webkit";\nexport const Board = () => layoutBoard();\n',
+    });
+
+    expect(warnings.map((warning) => warning.message)).toEqual([
+      'Exported "computeGroupBoxes" is referenced only by tests: apps/demo/webkit/boardLayout.test.ts.',
+      'Exported "groupEdgeStrips" is referenced only by tests: apps/demo/webkit/boardLayout.test.ts.',
+    ]);
+    expect(warnings[0]).toMatchObject({
+      rule: "akan.global.test-only-export",
+      scope: "global",
+      file: "apps/demo/webkit/boardLayout.ts",
+      line: 2,
+      locations: [{ file: "apps/demo/webkit/boardLayout.test.ts", line: 1 }],
+    });
+  });
+
+  test("passes an export another source file uses, or that a function in its own file uses", () => {
+    const warnings = scan({
+      "apps/demo/webkit/boardLayout.ts": layout,
+      "apps/demo/webkit/boardLayout.test.ts": layoutTest,
+      "apps/demo/ui/Board.tsx": [
+        'import * as webkit from "@apps/demo/webkit";',
+        "export const Board = () => [webkit.computeGroupBoxes(), webkit.groupEdgeStrips(2), webkit.layoutBoard()];",
+        "",
+      ].join("\n"),
+    });
+
+    expect(warnings).toEqual([]);
+  });
+
+  test("passes an export no test references, and leaves lib facets and lib modules alone", () => {
+    expect(
+      scan({
+        "apps/demo/common/unused.ts": "export const unused = 1;\n",
+        "libs/demo/webkit/signedIn.ts": "export const signedIn = () => true;\n",
+        "libs/demo/webkit/signedIn.test.ts": 'import { signedIn } from "./signedIn";\ntest(() => signedIn());\n',
+        "apps/demo/lib/post/post.constant.ts": "export class PostInput {}\n",
+        "apps/demo/lib/post/post.signal.test.ts": "const input = new PostInput();\n",
+      }),
+    ).toEqual([]);
+  });
+});

package/testOnlyExportScanner.ts

@@ -0,0 +1,124 @@
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+interface ExportedDeclaration {
+  name: string;
+  line: number;
+  statement: ts.Statement;
+}
+
+interface TestReference {
+  file: string;
+  line: number;
+}
+
+export class TestOnlyExportScanner {
+  static readonly rule = "akan.global.test-only-export";
+  static #facets = new Set(["common", "webkit", "srvkit", "ui"]);
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    const liveFileNumByName = new Map<string, number>();
+    const testRefsByName = new Map<string, TestReference[]>();
+    for (const { file, sourceFile } of sourceFiles) {
+      const isTest = TestOnlyExportScanner.#isTest(file);
+      for (const [name, line] of TestOnlyExportScanner.#identifierLinesOf(sourceFile)) {
+        if (!isTest) liveFileNumByName.set(name, (liveFileNumByName.get(name) ?? 0) + 1);
+        else if (testRefsByName.has(name)) testRefsByName.get(name)?.push({ file, line });
+        else testRefsByName.set(name, [{ file, line }]);
+      }
+    }
+    return sourceFiles
+      .filter(({ file }) => TestOnlyExportScanner.#isFacetSource(file))
+      .flatMap(({ file, sourceFile }) => {
+        const declarations = TestOnlyExportScanner.#exportedDeclarationsOf(sourceFile);
+        return declarations
+          .filter(({ name }) => (liveFileNumByName.get(name) ?? 0) <= 1)
+          .filter(({ name }) => !TestOnlyExportScanner.#isUsedInFile(sourceFile, name, declarations))
+          .flatMap(({ name, line }) => {
+            const testRefs = testRefsByName.get(name);
+            if (!testRefs?.length) return [];
+            return [
+              {
+                rule: TestOnlyExportScanner.rule,
+                scope: "global" as const,
+                severity: "warning" as const,
+                file,
+                line,
+                message: `Exported "${name}" is referenced only by tests: ${testRefs.map((ref) => ref.file).join(", ")}.`,
+                locations: testRefs,
+              },
+            ];
+          });
+      });
+  }
+
+  static #isTest(file: string) {
+    return /\.(test|spec)\.tsx?$/.test(file);
+  }
+
+  //? A lib's facets are public API for every workspace that installs it, so an export no app here calls is not dead.
+  static #isFacetSource(file: string) {
+    const segments = file.split("/");
+    if (segments[0] !== "apps") return false;
+    return TestOnlyExportScanner.#facets.has(segments[2] ?? "") && !TestOnlyExportScanner.#isTest(file);
+  }
+
+  static #identifierLinesOf(sourceFile: ts.SourceFile) {
+    const lines = new Map<string, number>();
+    const visit = (node: ts.Node) => {
+      if (ts.isIdentifier(node) && !lines.has(node.text))
+        lines.set(node.text, sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1);
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return lines;
+  }
+
+  static #exportedDeclarationsOf(sourceFile: ts.SourceFile): ExportedDeclaration[] {
+    return sourceFile.statements.flatMap((statement) => {
+      if (!TestOnlyExportScanner.#isNamedExport(statement)) return [];
+      return TestOnlyExportScanner.#declaredNamesOf(statement).map((identifier) => ({
+        name: identifier.text,
+        line: sourceFile.getLineAndCharacterOfPosition(identifier.getStart(sourceFile)).line + 1,
+        statement,
+      }));
+    });
+  }
+
+  static #isNamedExport(statement: ts.Statement) {
+    if (!ts.canHaveModifiers(statement)) return false;
+    const modifiers = ts.getModifiers(statement) ?? [];
+    return (
+      modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) &&
+      !modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword)
+    );
+  }
+
+  static #declaredNamesOf(statement: ts.Statement): ts.Identifier[] {
+    if (ts.isVariableStatement(statement))
+      return statement.declarationList.declarations
+        .map((declaration) => declaration.name)
+        .filter((name): name is ts.Identifier => ts.isIdentifier(name));
+    if (
+      ts.isFunctionDeclaration(statement) ||
+      ts.isClassDeclaration(statement) ||
+      ts.isInterfaceDeclaration(statement) ||
+      ts.isTypeAliasDeclaration(statement) ||
+      ts.isEnumDeclaration(statement)
+    )
+      return statement.name ? [statement.name] : [];
+    return [];
+  }
+
+  static #isUsedInFile(sourceFile: ts.SourceFile, name: string, declarations: ExportedDeclaration[]) {
+    const ownStatements = new Set(declarations.filter((entry) => entry.name === name).map((entry) => entry.statement));
+    let used = false;
+    const visit = (node: ts.Node) => {
+      if (used || ownStatements.has(node as ts.Statement)) return;
+      if (ts.isIdentifier(node) && node.text === name) used = true;
+      else ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return used;
+  }
+}

package/workflow/artifacts.ts

@@ -1,5 +1,6 @@
 import { capitalize } from "akanjs/common";
 import type { Workspace } from "../commandDecorators";
+import { InteractionScaffold } from "./interactionScaffold";
 import type {
   GeneratedSyncState,
   PrimitiveChangedFile,
@@ -156,11 +157,15 @@ export const workflowPathsForPlan = (plan: WorkflowPlan) => {
   const app = planInputString(plan, "app");
   const module = planInputString(plan, "module");
   const moduleClass = module ? capitalize(module) : "<Module>";
+  const rawInteraction = planInputString(plan, "interaction");
+  const interaction = rawInteraction ? (InteractionScaffold.nameOf(rawInteraction) ?? rawInteraction) : null;
   return plan.predictedChanges.map((change) =>
     change.target
       .replace(/^\*\//, app ? `apps/${app}/` : "")
       .replaceAll("<module>", module || "<module>")
-      .replaceAll("<Module>", moduleClass),
+      .replaceAll("<Module>", moduleClass)
+      .replaceAll("<interaction>", interaction || "<interaction>")
+      .replaceAll("<Interaction>", interaction ? capitalize(interaction) : "<Interaction>"),
   );
 };
 

package/workflow/executor.ts

@@ -312,7 +312,7 @@ const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan):
   return { diagnostics, postApplyChecks };
 };
 
-const resolveWorkflowSys = async (workspace: Workspace, target: string | null): Promise<Sys | null> => {
+export const resolveWorkflowSys = async (workspace: Workspace, target: string | null): Promise<Sys | null> => {
   if (!target) return null;
   const [apps, libs] = await workspace.getSyss();
   if (apps.includes(target)) return AppExecutor.from(workspace, target);
@@ -375,10 +375,10 @@ const addMutationActionSurfaceInspection = (plan: WorkflowPlan): WorkflowStepRes
   const moduleClassName = moduleComponentName(module);
   return surfaceReview(plan, {
     code: "add-mutation-action-surface-review",
-    target: `*/${moduleSourcePaths(module).store}`,
-    action: `Name the endpoint's guards and add its dictionary .endpoint() entry with a .desc(). After sync, fetch.${mutation} exists; write a store action only for a toast, an optimistic update, or a multi-field write, and put the control that calls it in ${moduleClassName}.Util.tsx.`,
-    message: `Workflow apply does not write store or UI code for ${module}.${mutation}; review whether a screen should call it.`,
-    reason: "Review action surface guidance before manually editing store or UI files.",
+    target: `*/${moduleSourcePaths(module).util}`,
+    action: `Fill the ${moduleClassName} chain method (validate, mutate, return this) and replace its transition comment. After sync, call st.do.${mutation}(id) from the control in ${moduleClassName}.Util.tsx; a second write that must land with it is another with/after entry, never a second fetch in the store action.`,
+    message: `Workflow apply does not write UI code for ${module}.${mutation}; review which screen calls it.`,
+    reason: "Review action surface guidance before manually editing UI files.",
   });
 };
 
@@ -404,6 +404,7 @@ export const createWorkflowStepRegistry = ({
   addEnumField,
   addMutation,
   addSlice,
+  createInteraction,
 }: WorkflowPrimitiveOperations): WorkflowStepRegistry => {
   const inspect = async () => undefined;
   const commandOnly = async () => undefined;
@@ -484,17 +485,31 @@ export const createWorkflowStepRegistry = ({
       ),
     [workflowStepKey("add-enum-field", "update-dictionary")]: inspect,
     [workflowStepKey("add-enum-field", "update-option")]: inspect,
-    [workflowStepKey("add-mutation", "update-service")]: async (_step, plan) =>
+    [workflowStepKey("add-mutation", "update-document")]: async (_step, plan) =>
       primitiveReportToWorkflowStepResult(
         await addMutation({
           app: workflowStringInput(plan.inputs.app),
           module: workflowStringInput(plan.inputs.module),
           mutation: workflowStringInput(plan.inputs.mutation),
+          guards: workflowStringArrayInput(plan.inputs.guard),
+          withCalls: workflowStringArrayInput(plan.inputs.with),
+          afterCalls: workflowStringArrayInput(plan.inputs.after),
         }),
       ),
+    [workflowStepKey("add-mutation", "update-service")]: inspect,
     [workflowStepKey("add-mutation", "update-signal")]: inspect,
-    [workflowStepKey("add-mutation", "update-action-surfaces")]: async (_step, plan) =>
+    [workflowStepKey("add-mutation", "update-store")]: inspect,
+    [workflowStepKey("add-mutation", "update-dictionary")]: inspect,
+    [workflowStepKey("add-mutation", "add-signal-test")]: inspect,
+    [workflowStepKey("add-mutation", "connect-action-ui")]: async (_step, plan) =>
       addMutationActionSurfaceInspection(plan),
+    [workflowStepKey("create-interaction", "create-interaction")]: async (_step, plan) =>
+      primitiveReportToWorkflowStepResult(
+        await createInteraction({
+          app: workflowStringInput(plan.inputs.app),
+          interaction: workflowStringInput(plan.inputs.interaction),
+        }),
+      ),
     [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) =>
       primitiveReportToWorkflowStepResult(
         await addSlice({

package/workflow/guardCatalog.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { createTempApp, tempRoots, writeJson, writeText } from "../testHelpers";
+import { GuardCatalog } from "./guardCatalog";
+
+const track = tempRoots();
+
+const guardFile = (names: string[]) =>
+  names.map((name) => `export class ${name} implements Guard {\n  canPass() {\n    return true;\n  }\n}\n`).join("\n");
+
+const createAppWithLibs = async () => {
+  const temp = track(await createTempApp("demo"));
+  const lib = (name: string, files: Record<string, string>) =>
+    Promise.all([
+      writeText(path.join(temp.root, "libs", name, "akan.config.ts"), "export default {};\n"),
+      ...Object.entries(files).map(([file, content]) => writeText(path.join(temp.root, "libs", name, file), content)),
+    ]);
+  await lib("shared", {
+    "srvkit/guards.ts": guardFile(["Admin", "User"]),
+    "srvkit/internalArgs.ts": "export class Self implements InternalArg {}\n",
+    "srvkit/guards.signal.test.ts": guardFile(["TestOnly"]),
+    "akan.lib.json": JSON.stringify({ libDeps: ["util"] }),
+  });
+  await lib("util", { "srvkit/guards.ts": guardFile(["Machine"]) });
+  await lib("other", { "srvkit/guards.ts": guardFile(["Elsewhere"]) });
+  await writeText(path.join(temp.root, "apps/demo/srvkit/guards.ts"), guardFile(["LocalOnly"]));
+  return temp;
+};
+
+describe("GuardCatalog", () => {
+  test("reads the target's srvkit, the libs it reaches, and the framework's Public", async () => {
+    const { root, app } = await createAppWithLibs();
+    await writeJson(path.join(root, "apps/demo/akan.app.json"), { libDeps: ["shared"] });
+
+    const catalog = await GuardCatalog.load(app);
+
+    expect(catalog.reachedLibs).toEqual(["shared", "util"]);
+    expect(catalog.names.sort()).toEqual(["Admin", "LocalOnly", "Machine", "Public", "User"]);
+    expect(catalog.resolve("LocalOnly").specifier).toBe("@apps/demo/srvkit");
+    expect(catalog.resolve("Admin").specifier).toBe("@libs/shared/srvkit");
+    expect(catalog.resolve("Public").specifier).toBe("akanjs/signal");
+    expect(catalog.resolve("Elsewhere").specifier).toBeNull();
+  });
+
+  test("falls back to every workspace lib before a sync has recorded the target's deps", async () => {
+    const { app } = await createAppWithLibs();
+
+    expect((await GuardCatalog.load(app)).resolve("Elsewhere").specifier).toBe("@libs/other/srvkit");
+  });
+
+  test("names the acting user only when the guard guarantees one and its internal arg exists", async () => {
+    const { app } = await createAppWithLibs();
+    const catalog = await GuardCatalog.load(app);
+
+    expect(catalog.actingUserOf(["User"])).toMatchObject({ argName: "Self", specifier: "@libs/shared/srvkit" });
+    expect(catalog.actingUserOf(["Admin"])).toBeNull();
+    expect(catalog.actingUserOf(["SignedIn"])).toBeNull();
+  });
+});

package/workflow/guardCatalog.ts

@@ -0,0 +1,108 @@
+import type { Sys } from "../commandDecorators";
+
+interface CatalogEntry {
+  name: string;
+  specifier: string;
+}
+
+interface ActingUser {
+  argName: string;
+  specifier: string;
+  param: string;
+  value: string;
+  serviceParam: string;
+}
+
+export class GuardCatalog {
+  static readonly frameworkGuards = ["Public"] as const;
+  static readonly #actingArgOf = new Map<string, Omit<ActingUser, "specifier">>([
+    ["User", { argName: "Self", param: "self", value: "self.id", serviceParam: "selfId" }],
+    [
+      "SignedIn",
+      { argName: "CurrentUserId", param: "currentUserId", value: "currentUserId", serviceParam: "currentUserId" },
+    ],
+  ]);
+  readonly #guards: CatalogEntry[];
+  readonly #internalArgs: CatalogEntry[];
+  readonly reachedLibs: string[];
+
+  constructor(guards: CatalogEntry[], internalArgs: CatalogEntry[], reachedLibs: string[]) {
+    this.#guards = guards;
+    this.#internalArgs = internalArgs;
+    this.reachedLibs = reachedLibs;
+  }
+
+  static async load(sys: Sys) {
+    const reachedLibs = await GuardCatalog.#reachedLibs(sys);
+    const scopes = [{ type: sys.type, name: sys.name }, ...reachedLibs.map((name) => ({ type: "lib" as const, name }))];
+    const exports = (await Promise.all(scopes.map((scope) => GuardCatalog.#srvkitExports(sys, scope)))).flat();
+    const frameworkGuards = GuardCatalog.frameworkGuards.map((name) => ({ name, specifier: "akanjs/signal" }));
+    return new GuardCatalog(
+      [...exports.filter((entry) => entry.kind === "Guard"), ...frameworkGuards],
+      exports.filter((entry) => entry.kind === "InternalArg"),
+      reachedLibs,
+    );
+  }
+
+  get names() {
+    return [...new Set(this.#guards.map((guard) => guard.name))];
+  }
+
+  resolve(name: string) {
+    const matches = this.#guards.filter((guard) => guard.name === name);
+    const specifiers = [...new Set(matches.map((guard) => guard.specifier))];
+    return { specifier: specifiers[0] ?? null, ambiguous: specifiers.length > 1 ? specifiers : null };
+  }
+
+  actingUserOf(guards: readonly string[]): ActingUser | null {
+    for (const guard of guards) {
+      const acting = GuardCatalog.#actingArgOf.get(guard);
+      const specifier = acting
+        ? this.#internalArgs.find((entry) => entry.name === acting.argName)?.specifier
+        : undefined;
+      if (acting && specifier) return { ...acting, specifier };
+    }
+    return null;
+  }
+
+  static async #reachedLibs(sys: Sys) {
+    const workspaceLibs = await sys.workspace.getLibs();
+    const depsOf = async (type: "app" | "lib", name: string) => {
+      const jsonPath = `${type}s/${name}/akan.${type}.json`;
+      if (!(await sys.workspace.exists(jsonPath))) return null;
+      const { libDeps } = (await sys.workspace.readJson(jsonPath)) as { libDeps?: unknown };
+      return Array.isArray(libDeps) ? libDeps.filter((lib): lib is string => workspaceLibs.includes(lib)) : [];
+    };
+    const direct = await depsOf(sys.type, sys.name);
+    if (!direct) return workspaceLibs.filter((lib) => sys.type !== "lib" || lib !== sys.name);
+    const reached = new Set<string>();
+    const queue = [...direct];
+    while (queue.length) {
+      const lib = queue.shift();
+      if (!lib || reached.has(lib) || (sys.type === "lib" && lib === sys.name)) continue;
+      reached.add(lib);
+      queue.push(...((await depsOf("lib", lib)) ?? []));
+    }
+    return [...reached];
+  }
+
+  static async #srvkitExports(sys: Sys, scope: { type: "app" | "lib"; name: string }) {
+    const dir = `${scope.type}s/${scope.name}/srvkit`;
+    const files = (await sys.workspace.readdir(dir)).filter(
+      (file) => /\.tsx?$/.test(file) && !/\.(test|spec)\.tsx?$/.test(file) && file !== "index.ts",
+    );
+    const specifier = `@${scope.type}s/${scope.name}/srvkit`;
+    const contents = await Promise.all(files.map((file) => sys.workspace.readFile(`${dir}/${file}`)));
+    return contents.flatMap((content) =>
+      [...content.matchAll(/export class ([A-Z][A-Za-z0-9_]*)\s+implements\s+([^{]+)\{/g)].flatMap((match) => {
+        const implemented = (match[2] ?? "").split(",").map((name) => name.replace(/<.*$/s, "").trim());
+        const kind = implemented.includes("Guard")
+          ? "Guard"
+          : implemented.includes("InternalArg")
+            ? "InternalArg"
+            : null;
+        return kind && match[1] ? [{ kind, name: match[1], specifier }] : [];
+      }),
+    );
+  }
+}

package/workflow/index.ts

@@ -1,6 +1,10 @@
 export * from "./artifacts";
 export * from "./executor";
+export * from "./guardCatalog";
+export * from "./interactionScaffold";
 export * from "./moduleIndex";
+export * from "./mutationScaffold";
+export * from "./mutationSource";
 export * from "./plan";
 export * from "./render";
 export * from "./rolloutGate";

package/workflow/interactionScaffold.ts

@@ -0,0 +1,122 @@
+import { capitalize, lowerlize } from "akanjs/common";
+import type { Sys } from "../commandDecorators";
+import type { ScaffoldFile, WorkflowDiagnostic } from "./types";
+
+export class InteractionScaffold {
+  readonly name: string;
+  readonly className: string;
+  readonly hookName: string;
+  readonly #commonSpecifier: string;
+
+  constructor(sys: Sys, name: string) {
+    this.name = name;
+    this.className = capitalize(name);
+    this.hookName = `use${this.className}`;
+    this.#commonSpecifier = `@${sys.type}s/${sys.name}/common`;
+  }
+
+  static nameOf(raw: string) {
+    const name = lowerlize(raw.replace(/^use(?=[A-Z])/, ""));
+    return /^[a-z][A-Za-z0-9]*$/.test(name) ? name : null;
+  }
+
+  static async build(sys: Sys, raw: string | null) {
+    const diagnostics: WorkflowDiagnostic[] = [];
+    const name = raw ? InteractionScaffold.nameOf(raw) : null;
+    if (!name) {
+      diagnostics.push({
+        severity: "error",
+        code: "create-interaction-name-invalid",
+        input: "interaction",
+        message: `Interaction name "${raw ?? ""}" must be camelCase (boardKeys), optionally prefixed with use.`,
+      });
+      return { diagnostics, files: [] as ScaffoldFile[] };
+    }
+    const scaffold = new InteractionScaffold(sys, name);
+    const files = scaffold.files;
+    const taken = (
+      await Promise.all(
+        scaffold.claimedPaths.map(async (path) =>
+          (await sys.exists(path)) ? `${sys.type}s/${sys.name}/${path}` : null,
+        ),
+      )
+    ).filter((path): path is string => !!path);
+    if (taken.length)
+      diagnostics.push({
+        severity: "error",
+        code: "create-interaction-exists",
+        input: "interaction",
+        message: `${taken.join(", ")} already exists; pick another interaction name or extend the existing files.`,
+      });
+    return { diagnostics, files: taken.length ? [] : files };
+  }
+
+  get claimedPaths() {
+    const { name, hookName } = this;
+    return [
+      `common/${name}.ts`,
+      `common/${name}.tsx`,
+      `common/${name}.test.ts`,
+      `webkit/${hookName}.tsx`,
+      `webkit/${hookName}.ts`,
+    ];
+  }
+
+  get files(): ScaffoldFile[] {
+    return [
+      {
+        path: `common/${this.name}.ts`,
+        content: this.logicSource,
+        action: "create",
+        reason: "Pure interaction logic.",
+      },
+      {
+        path: `common/${this.name}.test.ts`,
+        content: this.testSource,
+        action: "create",
+        reason: "Test of the pure interaction logic.",
+      },
+      { path: `webkit/${this.hookName}.tsx`, content: this.hookSource, action: "create", reason: "Client hook." },
+    ];
+  }
+
+  get logicSource() {
+    return [
+      `export class ${this.className} {`,
+      "  static next<State extends object>(state: State, input: Partial<State>) {",
+      "    return { ...state, ...input };",
+      "  }",
+      "}",
+      "",
+    ].join("\n");
+  }
+
+  get testSource() {
+    return [
+      'import { describe, expect, it } from "bun:test";',
+      `import { ${this.className} } from "./${this.name}";`,
+      "",
+      `describe(${JSON.stringify(this.className)}, () => {`,
+      '  it("applies an input over the state it is handed", () => {',
+      `    expect(${this.className}.next({ idx: 0, isOpen: false }, { idx: 1 })).toEqual({ idx: 1, isOpen: false });`,
+      "  });",
+      "});",
+      "",
+    ].join("\n");
+  }
+
+  get hookSource() {
+    return [
+      '"use client";',
+      `import { ${this.className} } from "${this.#commonSpecifier}";`,
+      "",
+      `export const ${this.hookName} = <State extends object>(state: State, commit: (next: State) => void) => {`,
+      "  const change = async (input: Partial<State>) => {",
+      `    commit(${this.className}.next(state, input));`,
+      "  };",
+      "  return { change };",
+      "};",
+      "",
+    ].join("\n");
+  }
+}