@akanjs/devkit 3.1.1-rc.9 → 3.1.1

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");
+  }
+}