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

package/workflow/mutationSource.ts

@@ -0,0 +1,219 @@
+import { lowerlize } from "akanjs/common";
+import { bilingualLabelForField, moduleComponentName, titleize } from "./source";
+
+export interface MutationCall {
+  ref: string;
+  method: string;
+  field: string | null;
+  args: string[];
+}
+
+export interface MutationActingUser {
+  argName: string;
+  param: string;
+  value: string;
+  serviceParam: string;
+}
+
+export interface MutationSourceSpec {
+  module: string;
+  mutation: string;
+  guards: readonly string[];
+  acting: MutationActingUser | null;
+  withCalls: readonly MutationCall[];
+  afterCalls: readonly MutationCall[];
+}
+
+export class MutationSource {
+  static readonly #irregularParticiples = new Map([
+    ["admit", "admitted"],
+    ["bind", "bound"],
+    ["build", "built"],
+    ["choose", "chosen"],
+    ["commit", "committed"],
+    ["control", "controlled"],
+    ["cut", "cut"],
+    ["find", "found"],
+    ["freeze", "frozen"],
+    ["get", "got"],
+    ["give", "given"],
+    ["hide", "hidden"],
+    ["hold", "held"],
+    ["keep", "kept"],
+    ["lead", "led"],
+    ["leave", "left"],
+    ["lose", "lost"],
+    ["make", "made"],
+    ["omit", "omitted"],
+    ["pay", "paid"],
+    ["permit", "permitted"],
+    ["put", "put"],
+    ["read", "read"],
+    ["run", "run"],
+    ["sell", "sold"],
+    ["send", "sent"],
+    ["set", "set"],
+    ["show", "shown"],
+    ["shut", "shut"],
+    ["split", "split"],
+    ["submit", "submitted"],
+    ["take", "taken"],
+    ["transfer", "transferred"],
+    ["win", "won"],
+    ["write", "written"],
+  ]);
+  readonly spec: MutationSourceSpec;
+  readonly modelClassName: string;
+  readonly model: string;
+  readonly idParam: string;
+  readonly chainMethod: string;
+
+  constructor(spec: MutationSourceSpec) {
+    this.spec = spec;
+    this.modelClassName = moduleComponentName(spec.module);
+    this.model = lowerlize(this.modelClassName);
+    this.idParam = `${this.model}Id`;
+    this.chainMethod = MutationSource.chainMethodOf(spec.mutation, this.modelClassName);
+  }
+
+  static chainMethodOf(mutation: string, modelClassName: string) {
+    const dropped = mutation.replace(modelClassName, "");
+    return dropped && dropped !== mutation ? lowerlize(dropped) : mutation;
+  }
+
+  static participleOf(verb: string) {
+    const irregular = MutationSource.#irregularParticiples.get(verb);
+    if (irregular) return irregular;
+    if (verb.endsWith("e")) return `${verb}d`;
+    if (/[^aeiou]y$/.test(verb)) return `${verb.slice(0, -1)}ied`;
+    if (/^[^aeiou]*[aeiou][^aeiouwxy]$/.test(verb)) return `${verb}${verb.at(-1)}ed`;
+    return `${verb}ed`;
+  }
+
+  get isPublic() {
+    return this.spec.guards.includes("Public");
+  }
+
+  get #verb() {
+    return this.chainMethod.replace(/[A-Z].*$/s, "");
+  }
+
+  get #noun() {
+    return titleize(this.model).toLowerCase();
+  }
+
+  get chainMethodBlock() {
+    return [
+      `  // any → ${MutationSource.participleOf(this.#verb)}.`,
+      `  ${this.chainMethod}() {`,
+      "    return this;",
+      "  }",
+    ].join("\n");
+  }
+
+  get serviceMethod() {
+    return this.chainMethod;
+  }
+
+  get serviceMethodBlock() {
+    const { acting } = this.spec;
+    const params = [`${this.idParam}: string`, ...(acting ? [`${acting.serviceParam}: string`] : [])];
+    const load = `const ${this.model} = await this.get${this.modelClassName}(${this.idParam});`;
+    const owned = acting
+      ? [
+          `// TODO: ${this.spec.guards.join(" and ")} admits any signed-in caller; refuse a ${acting.serviceParam} that may not ${this.#verb} this ${this.#noun}.`,
+        ]
+      : [];
+    const chained = `${this.model}.${this.chainMethod}().save()`;
+    const head = `  async ${this.serviceMethod}(${params.join(", ")}) {`;
+    if (!this.spec.withCalls.length && !this.spec.afterCalls.length)
+      return [head, `    ${load}`, ...owned.map((line) => `    ${line}`), `    return await ${chained};`, "  }"].join(
+        "\n",
+      );
+    return [
+      head,
+      "    return await this.transaction(async () => {",
+      `      ${load}`,
+      ...owned.map((line) => `      ${line}`),
+      `      await ${chained};`,
+      ...this.spec.withCalls.map((call) => `      await ${MutationSource.#callOf(call)};`),
+      ...this.spec.afterCalls.map((call) => `      await this.afterCommit(() => ${MutationSource.#callOf(call)});`),
+      `      return ${this.model};`,
+      "    });",
+      "  }",
+    ].join("\n");
+  }
+
+  get signalEntry() {
+    const options = this.isPublic
+      ? `{ guards: [${this.spec.guards.join(", ")}], rateLimit: { calls: 20 } }`
+      : `{ guards: [${this.spec.guards.join(", ")}] }`;
+    const { acting } = this.spec;
+    const execParams = [this.idParam, ...(acting ? [acting.param] : [])];
+    const serviceArgs = [this.idParam, ...(acting ? [acting.value] : [])];
+    return [
+      `${this.spec.mutation}: mutation(cnst.${this.modelClassName}, ${options})`,
+      `    .param("${this.idParam}", ID)`,
+      ...(acting ? [`    .with(${acting.argName})`] : []),
+      `    .exec(async function (${execParams.join(", ")}) {`,
+      `      return await this.${this.model}Service.${this.serviceMethod}(${serviceArgs.join(", ")});`,
+      "    }),",
+    ].join("\n");
+  }
+
+  get storeActionBlock() {
+    return [
+      `  async ${this.spec.mutation}(${this.idParam}: string) {`,
+      `    this.set${this.modelClassName}(await fetch.${this.spec.mutation}(${this.idParam}));`,
+      "  }",
+    ].join("\n");
+  }
+
+  dictionaryEntryOf(modelKo?: string) {
+    const label = bilingualLabelForField(this.spec.mutation);
+    const modelLabel = { ...bilingualLabelForField(this.model), ...(modelKo ? { ko: modelKo } : {}) };
+    const pair = (en: string, ko: string) => `[${JSON.stringify(en)}, ${JSON.stringify(ko)}]`;
+    const idPair = pair(`${modelLabel.en} ID`, `${modelLabel.ko} ID`);
+    return [
+      `${this.spec.mutation}: fn(${pair(label.en, label.ko)})`,
+      `      .desc(${pair(`API to ${label.en.toLowerCase()}`, `${label.ko} API`)})`,
+      "      .arg((t) => ({",
+      `        ${this.idParam}: t(${idPair}).desc(${idPair}),`,
+      "      })),",
+    ].join("\n");
+  }
+
+  get testTitles() {
+    const guards = this.spec.guards.join(" and ");
+    const participle = MutationSource.participleOf(this.#verb);
+    return [
+      `${this.spec.mutation} leaves the ${this.#noun} ${participle} for a caller ${guards} admits`,
+      ...(this.spec.guards.every((guard) => guard === "Public")
+        ? []
+        : [`${this.spec.mutation} refuses a caller ${guards} turns away`]),
+      ...(this.spec.acting
+        ? [`${this.spec.mutation} refuses a signed-in caller who may not ${this.#verb} the ${this.#noun}`]
+        : []),
+    ];
+  }
+
+  testCaseLines(itName: string, indent: string) {
+    return this.testTitles.map((title) => `${indent}${itName}.todo(${JSON.stringify(title)});`);
+  }
+
+  get testFile() {
+    return [
+      'import { describe, it } from "bun:test";',
+      "",
+      `describe(${JSON.stringify(`${this.modelClassName} Signal`)}, () => {`,
+      ...this.testCaseLines("it", "  "),
+      "});",
+      "",
+    ].join("\n");
+  }
+
+  static #callOf(call: MutationCall) {
+    const target = call.field ? `this.${call.field}` : "this";
+    return `${target}.${call.method}(${call.args.join(", ")})`;
+  }
+}

package/workflow/plan.ts

@@ -1,5 +1,9 @@
 import { capitalize } from "akanjs/common";
+import type { Workspace } from "../commandDecorators";
 import { workflowPlanApproval } from "./artifacts";
+import { resolveWorkflowSys } from "./executor";
+import { InteractionScaffold } from "./interactionScaffold";
+import { MutationScaffold } from "./mutationScaffold";
 import { coerceFieldDefault, moduleSourcePaths } from "./source";
 import type {
   WorkflowDiagnostic,
@@ -420,3 +424,53 @@ export const createWorkflowPlan = (spec: WorkflowSpec, rawInputs: Record<string,
     approval: workflowPlanApproval,
   };
 };
+
+const planString = (inputs: Record<string, WorkflowInputValue>, name: string) =>
+  typeof inputs[name] === "string" ? inputs[name] : null;
+const planStrings = (inputs: Record<string, WorkflowInputValue>, name: string) =>
+  Array.isArray(inputs[name]) ? inputs[name] : null;
+
+export const inspectWorkflowPlan = async (workspace: Workspace, plan: WorkflowPlan): Promise<WorkflowPlan> => {
+  if (plan.workflow !== "add-mutation" && plan.workflow !== "create-interaction") return plan;
+  const app = planString(plan.inputs, "app");
+  if (!app) return plan;
+  const sys = await resolveWorkflowSys(workspace, app).catch(() => null);
+  if (!sys)
+    return {
+      ...plan,
+      diagnostics: [
+        ...plan.diagnostics,
+        {
+          severity: "error",
+          code: "workflow-target-missing",
+          input: "app",
+          message: `No app or library named ${app}.`,
+        },
+      ],
+    };
+  const inspected =
+    plan.workflow === "add-mutation"
+      ? await MutationScaffold.build(
+          sys,
+          {
+            module: planString(plan.inputs, "module"),
+            mutation: planString(plan.inputs, "mutation"),
+            guards: planStrings(plan.inputs, "guard"),
+            withCalls: planStrings(plan.inputs, "with"),
+            afterCalls: planStrings(plan.inputs, "after"),
+          },
+          { strict: false },
+        )
+      : { ...(await InteractionScaffold.build(sys, planString(plan.inputs, "interaction"))), recommendations: [] };
+  const failedInputs = new Set(
+    plan.diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.input),
+  );
+  return {
+    ...plan,
+    diagnostics: [
+      ...plan.diagnostics,
+      ...inspected.diagnostics.filter((diagnostic) => !diagnostic.input || !failedInputs.has(diagnostic.input)),
+    ],
+    recommendations: [...plan.recommendations, ...inspected.recommendations],
+  };
+};

package/workflow/render.ts

@@ -1,3 +1,4 @@
+import { camelToKebabCase } from "../commandDecorators/camelToKebabCase";
 import type {
   PrimitiveFormat,
   PrimitiveWriteReport,
@@ -33,7 +34,13 @@ export const renderWorkflowList = (specs: readonly WorkflowSpec[]) =>
   [
     "# Akan Workflows",
     "",
-    ...specs.flatMap((spec) => [`- \`${spec.name}\`: ${spec.description}`, `  - When: ${spec.whenToUse}`]),
+    ...specs.flatMap((spec) => [
+      `- \`${spec.name}\`: ${spec.description}`,
+      `  - When: ${spec.whenToUse}`,
+      ...(spec.replacesRules?.length
+        ? [`  - Fixes: ${spec.replacesRules.map((rule) => `\`${rule}\``).join(", ")}`]
+        : []),
+    ]),
     "",
   ].join("\n");
 
@@ -46,12 +53,20 @@ export const renderWorkflowExplain = (spec: WorkflowSpec) =>
     "## When To Use",
     spec.whenToUse,
     "",
+    ...(spec.replacesRules?.length
+      ? [
+          "## Replaces Rules",
+          "This path is the fix when lint or the gate reports:",
+          ...spec.replacesRules.map((rule) => `- \`${rule}\``),
+          "",
+        ]
+      : []),
     "## Inputs",
     ...Object.entries(spec.inputs).map(
       ([name, input]) =>
-        `- \`${name}\`${input.required ? " (required)" : ""}: ${input.description}${
-          input.allowedValues ? ` Allowed: ${input.allowedValues.join(", ")}.` : ""
-        }`,
+        `- \`${name}\`${camelToKebabCase(name) === name ? "" : ` (\`--${camelToKebabCase(name)}\`)`}${
+          input.required ? " (required)" : ""
+        }: ${input.description}${input.allowedValues ? ` Allowed: ${input.allowedValues.join(", ")}.` : ""}`,
     ),
     "",
     "## Optional Surfaces",

package/workflow/source.test.ts

@@ -1,9 +1,16 @@
 import { describe, expect, test } from "bun:test";
 import {
+  appendTopLevelTestCases,
+  classMethodParameters,
+  ensureImportDeclaration,
+  ensureNamedImport,
   hasClassMethod,
+  hasDictionaryEndpointEntry,
   hasSignalFactoryEntry,
   hasSourceParseErrors,
   insertClassMethod,
+  insertDictionaryEndpointEntry,
+  insertDictionaryEnum,
   insertSignalFactoryEntry,
   inspectDictionaryStructure,
 } from "./source";
@@ -173,3 +180,181 @@ export class BannerEndpoint extends endpoint(srv.banner, ({ mutation }) => ({
     expect(next).toBe(content);
   });
 });
+
+describe("import editing", () => {
+  const signal = `import { endpoint, internal, slice } from "akanjs/signal";
+
+import * as srv from "../srv";
+`;
+
+  test("adds a name in Biome's order and keeps a type modifier", () => {
+    const content = 'import { type Dayjs, dayjs } from "akanjs/base";\n';
+
+    expect(ensureNamedImport(content, "akanjs/base", "ID")).toBe(
+      'import { type Dayjs, dayjs, ID } from "akanjs/base";\n',
+    );
+    expect(ensureNamedImport(signal, "akanjs/signal", "None")).toContain(
+      'import { endpoint, internal, None, slice } from "akanjs/signal";',
+    );
+  });
+
+  test("never adds a value name to a type-only import", () => {
+    const next = ensureNamedImport('import type { Guard } from "akanjs/signal";\n', "akanjs/signal", "Public");
+
+    expect(next).toContain('import type { Guard } from "akanjs/signal";');
+    expect(next).toContain('import { Public } from "akanjs/signal";');
+  });
+
+  test("puts a new declaration in its chunk, in source order", () => {
+    const withPackages = ensureNamedImport(
+      ensureNamedImport(signal, "akanjs/base", "ID"),
+      "@libs/shared/srvkit",
+      "Admin",
+    );
+    const withRelative = ensureImportDeclaration(withPackages, "../cnst", "* as cnst");
+
+    expect(withRelative).toBe(`import { Admin } from "@libs/shared/srvkit";
+import { ID } from "akanjs/base";
+import { endpoint, internal, slice } from "akanjs/signal";
+
+import * as cnst from "../cnst";
+import * as srv from "../srv";
+`);
+    expect(
+      ensureImportDeclaration('import { serve } from "akanjs/service";\n\nexport {};\n', "../srv", "type * as srv"),
+    ).toBe('import { serve } from "akanjs/service";\n\nimport type * as srv from "../srv";\n\nexport {};\n');
+  });
+});
+
+describe("dictionary endpoint entries", () => {
+  const dictionary = `export const dictionary = modelDictionary(["en", "ko"])
+  .slice<TaskSlice>((fn) => ({}))
+  .endpoint<TaskEndpoint>((fn) => ({}))
+  .error({})
+  .translate({});
+`;
+
+  test("inserts an entry into the endpoint stage and finds it again", () => {
+    const next = insertDictionaryEndpointEntry(
+      dictionary,
+      "Task",
+      "archiveTask",
+      'archiveTask: fn(["Archive", "보관"]),',
+    );
+
+    expect(next).toContain('.endpoint<TaskEndpoint>((fn) => ({\n    archiveTask: fn(["Archive", "보관"]),\n  }))');
+    expect(hasDictionaryEndpointEntry(next ?? "", "Task", "archiveTask")).toBe(true);
+    expect(hasDictionaryEndpointEntry(dictionary, "Task", "archiveTask")).toBe(false);
+  });
+
+  test("answers null when the dictionary has no endpoint stage for the model", () => {
+    expect(insertDictionaryEndpointEntry(dictionary, "Note", "pinNote", "pinNote: fn([]),")).toBeNull();
+  });
+});
+
+describe("insertDictionaryEnum", () => {
+  const dictionary = (tail: string) => `import { modelDictionary } from "akanjs/dictionary";
+
+import type { Task } from "./task.constant";
+
+// Stages: .model() field labels, .enum() value labels, .error() messages, .translate() UI messages.
+
+export const dictionary = modelDictionary(["en", "ko"])
+  .of((t) => t(["Task", "할 일"]))
+  .model<Task>((t) => ({
+    title: t(["Title", "제목"]),
+  }))${tail};
+`;
+
+  test("inserts before the chain's own .error() stage, not a comment that names it", () => {
+    const next = insertDictionaryEnum(
+      dictionary(`
+  .error({ notFound: ["Not found", "없음"] })
+  .translate({})`),
+      "TaskPriority",
+      "taskPriority",
+      ["low", "high"],
+    );
+    expect(next).not.toBeNull();
+    expect(hasSourceParseErrors(next ?? "", "task.dictionary.ts")).toBe(false);
+    expect(next?.split("\n").slice(-7)).toEqual([
+      '  .enum<TaskPriority>("taskPriority", (t) => ({',
+      '    low: t(["Low", "Low"]),',
+      '    high: t(["High", "High"]),',
+      "  }))",
+      '  .error({ notFound: ["Not found", "없음"] })',
+      "  .translate({});",
+      "",
+    ]);
+    expect(inspectDictionaryStructure(next ?? "", "Task").chainOrderValid).toBe(true);
+  });
+
+  test("appends to the end of a chain with no later stage", () => {
+    const next = insertDictionaryEnum(dictionary(""), "TaskPriority", "taskPriority", ["low"]);
+    expect(hasSourceParseErrors(next ?? "", "task.dictionary.ts")).toBe(false);
+    expect(next).toContain(
+      '  }))\n  .enum<TaskPriority>("taskPriority", (t) => ({\n    low: t(["Low", "Low"]),\n  }));\n',
+    );
+  });
+
+  test("leaves an existing enum stage alone and refuses a file that does not parse", () => {
+    const withEnum = insertDictionaryEnum(dictionary(""), "TaskPriority", "taskPriority", ["low"]) ?? "";
+    expect(insertDictionaryEnum(withEnum, "TaskPriority", "taskPriority", ["low"])).toBe(withEnum);
+    expect(
+      insertDictionaryEnum("export const dictionary = modelDictionary([", "TaskPriority", "taskPriority", ["low"]),
+    ).toBeNull();
+  });
+});
+
+describe("classMethodParameters", () => {
+  test("reads names and which parameters a caller may leave out", () => {
+    const content = `export class NoteService {
+  async pushNote(taskId: string, note?: string, retries = 3) {}
+}`;
+
+    expect(classMethodParameters(content, "NoteService", "pushNote")).toEqual([
+      { name: "taskId", optional: false },
+      { name: "note", optional: true },
+      { name: "retries", optional: true },
+    ]);
+    expect(classMethodParameters(content, "NoteService", "missing")).toBeNull();
+  });
+});
+
+describe("appendTopLevelTestCases", () => {
+  const render = (itName: string, indent: string) => [`${indent}${itName}.todo("archives");`];
+
+  test("appends inside the outermost describe with the runner name the file imports", () => {
+    const content = `import { describe, expect, test } from "bun:test";
+
+describe("Task Signal", () => {
+  test("creates", () => {
+    expect(1).toBe(1);
+  });
+});
+`;
+
+    expect(
+      appendTopLevelTestCases(content, "Task Signal", render),
+    ).toBe(`import { describe, expect, test } from "bun:test";
+
+describe("Task Signal", () => {
+  test("creates", () => {
+    expect(1).toBe(1);
+  });
+  test.todo("archives");
+});
+`);
+  });
+
+  test("adds a describe when the file has none", () => {
+    const next = appendTopLevelTestCases('import { expect } from "bun:test";\n', "Task Signal", render);
+
+    expect(next).toBe(`import { describe, expect, it } from "bun:test";
+
+describe("Task Signal", () => {
+  it.todo("archives");
+});
+`);
+  });
+});