@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/src/generator/generate-code.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it } from "vitest";
+import {
+  generateErrors,
+  generatePermissions,
+  generateCommandShell,
+  generateQueryShell,
+  generateQueryStub,
+  generateQueryTestStub,
+} from "./generate-code";
+import type { ParsedCommandDoc } from "./parse-command-doc";
+
+describe("generateErrors", () => {
+  it("generates error classes from parsed command docs", () => {
+    const docs: ParsedCommandDoc[] = [
+      {
+        commandName: "createItem",
+        errors: [
+          { code: "DUPLICATE_SKU", description: "An item with the same SKU already exists" },
+          { code: "UNIT_NOT_FOUND", description: "Referenced unit does not exist or is inactive" },
+        ],
+        externalDependencies: [],
+      },
+      {
+        commandName: "activateItem",
+        errors: [
+          { code: "ITEM_NOT_FOUND", description: "Item does not exist" },
+          { code: "INVALID_STATE_TRANSITION", description: "Item is not in a valid state" },
+        ],
+        externalDependencies: [],
+      },
+    ];
+
+    const result = generateErrors(docs);
+
+    expect(result).toContain("// @generated — do not edit");
+    expect(result).toContain('import { createDomainError } from "../../shared/internal";');
+    expect(result).toContain("export const DuplicateSkuError = createDomainError(");
+    expect(result).toContain('"DuplicateSkuError", "DUPLICATE_SKU"');
+    expect(result).toContain("export const UnitNotFoundError = createDomainError(");
+    expect(result).toContain("export const ItemNotFoundError = createDomainError(");
+    expect(result).toContain("export const InvalidStateTransitionError = createDomainError(");
+  });
+
+  it("deduplicates error codes across commands", () => {
+    const docs: ParsedCommandDoc[] = [
+      {
+        commandName: "createItem",
+        errors: [{ code: "ITEM_NOT_FOUND", description: "Item does not exist" }],
+        externalDependencies: [],
+      },
+      {
+        commandName: "updateItem",
+        errors: [{ code: "ITEM_NOT_FOUND", description: "Item does not exist" }],
+        externalDependencies: [],
+      },
+    ];
+
+    const result = generateErrors(docs);
+
+    const matches = result.match(/ItemNotFoundError/g);
+    // Class name appears exactly twice: export declaration + first arg to createDomainError
+    expect(matches).toHaveLength(2);
+  });
+
+  it("returns empty string when no errors", () => {
+    const docs: ParsedCommandDoc[] = [
+      { commandName: "noop", errors: [], externalDependencies: [] },
+    ];
+
+    const result = generateErrors(docs);
+
+    expect(result).toBe("");
+  });
+});
+
+describe("generatePermissions", () => {
+  it("generates permissions from command names", () => {
+    const commandNames = ["createItem", "updateItem", "activateItem", "deleteItem"];
+
+    const result = generatePermissions("item-management", commandNames);
+
+    expect(result).toContain("// @generated — do not edit");
+    expect(result).toContain('import { definePermissions } from "../../shared/internal";');
+    expect(result).toContain('"item-management"');
+    expect(result).toContain('"createItem"');
+    expect(result).toContain('"updateItem"');
+    expect(result).toContain('"activateItem"');
+    expect(result).toContain('"deleteItem"');
+    expect(result).toContain("as const");
+  });
+
+  it("sorts command names alphabetically", () => {
+    const commandNames = ["deleteItem", "activateItem", "createItem"];
+
+    const result = generatePermissions("item-management", commandNames);
+
+    const activateIdx = result.indexOf('"activateItem"');
+    const createIdx = result.indexOf('"createItem"');
+    const deleteIdx = result.indexOf('"deleteItem"');
+    expect(activateIdx).toBeLessThan(createIdx);
+    expect(createIdx).toBeLessThan(deleteIdx);
+  });
+});
+
+describe("generateCommandShell", () => {
+  it("generates defineCommand wiring that imports run from hand-written file", () => {
+    const doc: ParsedCommandDoc = {
+      commandName: "activateItem",
+      errors: [
+        { code: "ITEM_NOT_FOUND", description: "Item does not exist" },
+        { code: "INVALID_STATE_TRANSITION", description: "Item is not in a valid state" },
+      ],
+      externalDependencies: [],
+    };
+
+    const result = generateCommandShell(doc);
+
+    expect(result).toContain("// @generated — do not edit");
+    expect(result).toContain('import { defineCommand } from "../../shared/internal";');
+    expect(result).toContain('import { permissions } from "../lib/permissions.generated";');
+    expect(result).toContain('import { run } from "./activateItem";');
+    expect(result).toContain(
+      "export const activateItem = defineCommand(permissions.activateItem, run);",
+    );
+  });
+
+  it("generates defineCommand for commands with external dependencies", () => {
+    const doc: ParsedCommandDoc = {
+      commandName: "createItem",
+      errors: [],
+      externalDependencies: [{ module: "primitives", entity: "Unit" }],
+    };
+
+    const result = generateCommandShell(doc);
+
+    expect(result).toContain('import { defineCommand } from "../../shared/internal";');
+    expect(result).toContain('import { run } from "./createItem";');
+    expect(result).toContain(
+      "export const createItem = defineCommand(permissions.createItem, run);",
+    );
+  });
+});
+
+describe("generateQueryShell", () => {
+  it("generates defineQuery wiring that imports run from hand-written file", () => {
+    const doc: ParsedCommandDoc = {
+      commandName: "getTaxonomyNode",
+      errors: [],
+      externalDependencies: [],
+    };
+
+    const result = generateQueryShell(doc);
+
+    expect(result).toContain("// @generated — do not edit");
+    expect(result).toContain('import { defineQuery } from "../../shared/internal";');
+    expect(result).toContain('import { run } from "./getTaxonomyNode";');
+    expect(result).toContain("export const getTaxonomyNode = defineQuery(run);");
+  });
+});
+
+describe("generateQueryStub", () => {
+  it("generates a stub implementation with ReadonlyDB and input interface", () => {
+    const doc: ParsedCommandDoc = {
+      commandName: "getTaxonomyNode",
+      errors: [],
+      externalDependencies: [],
+    };
+
+    const result = generateQueryStub(doc);
+
+    expect(result).toContain('import type { ReadonlyDB } from "../../shared/internal";');
+    expect(result).toContain('import type { DB } from "../generated/kysely-tailordb";');
+    expect(result).toContain("export interface GetTaxonomyNodeInput {");
+    expect(result).toContain(
+      "export async function run(db: ReadonlyDB<DB>, input: GetTaxonomyNodeInput)",
+    );
+    expect(result).toContain("return {};");
+  });
+});
+
+describe("generateQueryTestStub", () => {
+  it("generates a test stub with createMockDb and run import", () => {
+    const doc: ParsedCommandDoc = {
+      commandName: "getTaxonomyNode",
+      errors: [],
+      externalDependencies: [],
+    };
+
+    const result = generateQueryTestStub(doc);
+
+    expect(result).toContain('import { describe, expect, it } from "vitest";');
+    expect(result).toContain('import { createMockDb } from "../../testing/index";');
+    expect(result).toContain('import type { DB } from "../generated/kysely-tailordb";');
+    expect(result).toContain('import { run, type GetTaxonomyNodeInput } from "./getTaxonomyNode";');
+    expect(result).toContain('describe("getTaxonomyNode"');
+    expect(result).toContain("const { db } = createMockDb<DB>();");
+    expect(result).toContain("await run(db, {} as GetTaxonomyNodeInput)");
+    expect(result).toContain("expect(result).toBeDefined();");
+  });
+});

package/src/generator/generate-code.ts

@@ -0,0 +1,260 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseCommandDoc, errorCodeToClassName, type ParsedCommandDoc } from "./parse-command-doc";
+
+export function generateErrors(docs: ParsedCommandDoc[]): string {
+  const seen = new Set<string>();
+  const lines: string[] = [];
+
+  for (const doc of docs) {
+    for (const error of doc.errors) {
+      if (seen.has(error.code)) continue;
+      seen.add(error.code);
+
+      const className = errorCodeToClassName(error.code);
+      lines.push(`export const ${className} = createDomainError(`);
+      lines.push(`  "${className}", "${error.code}",`);
+      const escapedDesc = error.description.replace(/`/g, "'");
+      lines.push(`  (identifier: string) => \`${escapedDesc}: \${identifier}\`,`);
+      lines.push(`);`);
+      lines.push(``);
+    }
+  }
+
+  if (lines.length === 0) return "";
+
+  return `// @generated — do not edit
+import { createDomainError } from "../../shared/internal";
+
+${lines.join("\n")}`;
+}
+
+export function generateCommandStub(doc: ParsedCommandDoc): string {
+  const pascal = doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1);
+  const inputType = `${pascal}Input`;
+
+  return `import { ok, type CommandContext } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export interface ${inputType} {
+  // TODO: define input fields
+}
+
+export async function run(db: DB, input: ${inputType}, ctx: CommandContext) {
+  // TODO: implement
+  return ok({});
+}
+`;
+}
+
+export function generateTestStub(doc: ParsedCommandDoc): string {
+  const pascal = doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1);
+
+  return `import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import type { CommandContext } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+import { run, ${pascal}Input } from "./${doc.commandName}";
+
+describe("${doc.commandName} - test scenario", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["TODO:${doc.commandName}"],
+  };
+
+  it("should be implemented", async () => {
+    const { db } = createMockDb<DB>();
+    const result = await run(db, {} as ${pascal}Input, ctx);
+    expect(result.ok).toBe(true);
+  });
+});
+`;
+}
+
+export function generateCommandShell(doc: ParsedCommandDoc): string {
+  const lines: string[] = [
+    `// @generated — do not edit`,
+    `import { defineCommand } from "../../shared/internal";`,
+    `import { permissions } from "../lib/permissions.generated";`,
+    `import { run } from "./${doc.commandName}";`,
+    ``,
+    `export const ${doc.commandName} = defineCommand(permissions.${doc.commandName}, run);`,
+    ``,
+  ];
+
+  return lines.join("\n");
+}
+
+export function generateQueryShell(doc: ParsedCommandDoc): string {
+  const lines: string[] = [
+    `// @generated — do not edit`,
+    `import { defineQuery } from "../../shared/internal";`,
+    `import { run } from "./${doc.commandName}";`,
+    ``,
+    `export const ${doc.commandName} = defineQuery(run);`,
+    ``,
+  ];
+
+  return lines.join("\n");
+}
+
+export function generateQueryStub(doc: ParsedCommandDoc): string {
+  const pascal = doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1);
+  const inputType = `${pascal}Input`;
+
+  return `import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export interface ${inputType} {
+  // TODO: define input fields
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ${inputType}) {
+  // TODO: implement
+  return {};
+}
+`;
+}
+
+export function generateQueryTestStub(doc: ParsedCommandDoc): string {
+  const pascal = doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1);
+  const inputType = `${pascal}Input`;
+
+  return `import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { run, type ${inputType} } from "./${doc.commandName}";
+
+describe("${doc.commandName}", () => {
+  it("should be implemented", async () => {
+    const { db } = createMockDb<DB>();
+    const result = await run(db, {} as ${inputType});
+    expect(result).toBeDefined();
+  });
+});
+`;
+}
+
+export function generatePermissions(moduleName: string, commandNames: string[]): string {
+  const sorted = [...commandNames].sort();
+  const entries = sorted.map((name) => `  "${name}",`).join("\n");
+
+  return `// @generated — do not edit
+import { definePermissions } from "../../shared/internal";
+
+export const { permissions, own, all } = definePermissions("${moduleName}", [
+${entries}
+] as const);
+`;
+}
+
+export function runGenerateCode(modulePath: string, moduleName: string): number {
+  const docsDir = path.join(modulePath, "docs", "commands");
+  const libDir = path.join(modulePath, "lib");
+  const commandDir = path.join(modulePath, "command");
+
+  if (!fs.existsSync(docsDir)) {
+    console.error(`No docs/commands/ directory found at ${docsDir}`);
+    return 1;
+  }
+
+  const mdFiles = fs.readdirSync(docsDir).filter((f) => f.endsWith(".md"));
+  if (mdFiles.length === 0) {
+    console.error(`No command docs found in ${docsDir}`);
+    return 1;
+  }
+
+  const parsedDocs: ParsedCommandDoc[] = [];
+
+  for (const file of mdFiles) {
+    const content = fs.readFileSync(path.join(docsDir, file), "utf-8");
+    const name = path.basename(file, ".md");
+    parsedDocs.push(parseCommandDoc(name, content));
+  }
+
+  // Also parse query docs for error extraction
+  const queryDocsDir = path.join(modulePath, "docs", "queries");
+  const allDocsForErrors = [...parsedDocs];
+  if (fs.existsSync(queryDocsDir)) {
+    const queryFiles = fs.readdirSync(queryDocsDir).filter((f) => f.endsWith(".md"));
+    for (const file of queryFiles) {
+      const content = fs.readFileSync(path.join(queryDocsDir, file), "utf-8");
+      const name = path.basename(file, ".md");
+      allDocsForErrors.push(parseCommandDoc(name, content));
+    }
+  }
+
+  let generated = 0;
+
+  const errorsContent = generateErrors(allDocsForErrors);
+  if (errorsContent) {
+    fs.mkdirSync(libDir, { recursive: true });
+    const errorsFile = path.join(libDir, "errors.generated.ts");
+    fs.writeFileSync(errorsFile, errorsContent);
+    console.log(`  wrote ${path.relative(modulePath, errorsFile)}`);
+    generated++;
+  }
+
+  const commandNames = parsedDocs.map((d) => d.commandName);
+  const permissionsContent = generatePermissions(moduleName, commandNames);
+  const permissionsFile = path.join(libDir, "permissions.generated.ts");
+  fs.writeFileSync(permissionsFile, permissionsContent);
+  console.log(`  wrote ${path.relative(modulePath, permissionsFile)}`);
+  generated++;
+
+  fs.mkdirSync(commandDir, { recursive: true });
+  for (const doc of parsedDocs) {
+    const implFile = path.join(commandDir, `${doc.commandName}.ts`);
+    const shellContent = generateCommandShell(doc);
+    const shellFile = path.join(commandDir, `${doc.commandName}.generated.ts`);
+    fs.writeFileSync(shellFile, shellContent);
+    console.log(`  wrote ${path.relative(modulePath, shellFile)}`);
+    generated++;
+
+    if (!fs.existsSync(implFile)) {
+      fs.writeFileSync(implFile, generateCommandStub(doc));
+      console.log(`  scaffolded ${path.relative(modulePath, implFile)}`);
+    }
+
+    const testFile = path.join(commandDir, `${doc.commandName}.test.ts`);
+    if (!fs.existsSync(testFile)) {
+      fs.writeFileSync(testFile, generateTestStub(doc));
+      console.log(`  scaffolded ${path.relative(modulePath, testFile)}`);
+    }
+  }
+
+  // Generate query files from docs/queries/*.md
+  if (fs.existsSync(queryDocsDir)) {
+    const queryFiles = fs.readdirSync(queryDocsDir).filter((f) => f.endsWith(".md"));
+    if (queryFiles.length > 0) {
+      const queryDir = path.join(modulePath, "query");
+      fs.mkdirSync(queryDir, { recursive: true });
+
+      for (const file of queryFiles) {
+        const content = fs.readFileSync(path.join(queryDocsDir, file), "utf-8");
+        const name = path.basename(file, ".md");
+        const doc = parseCommandDoc(name, content);
+
+        const shellFile = path.join(queryDir, `${doc.commandName}.generated.ts`);
+        fs.writeFileSync(shellFile, generateQueryShell(doc));
+        console.log(`  wrote ${path.relative(modulePath, shellFile)}`);
+        generated++;
+
+        const implFile = path.join(queryDir, `${doc.commandName}.ts`);
+        if (!fs.existsSync(implFile)) {
+          fs.writeFileSync(implFile, generateQueryStub(doc));
+          console.log(`  scaffolded ${path.relative(modulePath, implFile)}`);
+        }
+
+        const testFile = path.join(queryDir, `${doc.commandName}.test.ts`);
+        if (!fs.existsSync(testFile)) {
+          fs.writeFileSync(testFile, generateQueryTestStub(doc));
+          console.log(`  scaffolded ${path.relative(modulePath, testFile)}`);
+        }
+      }
+    }
+  }
+
+  console.log(`Generated ${generated} file(s) for ${moduleName}`);
+  return 0;
+}

package/src/generator/parse-command-doc.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+import { parseCommandDoc, errorCodeToClassName } from "./parse-command-doc";
+
+describe("parseCommandDoc", () => {
+  it("extracts error codes and descriptions from Error Scenarios section", () => {
+    const markdown = `# CreateItem
+
+## Overview
+
+Creates a new item.
+
+## Business Rules
+
+- SKU must be unique
+
+## Process Flow
+
+\`\`\`mermaid
+flowchart TD
+    A[Start] --> B[End]
+\`\`\`
+
+## External Dependencies
+
+- [primitives::Unit](../../../primitives/docs/models/Unit.md) - Validates UoM
+
+## Error Scenarios
+
+- **DUPLICATE_SKU**: An item with the same SKU already exists
+- **DUPLICATE_BARCODE**: An item with the same barcode already exists
+- **UNIT_NOT_FOUND**: Referenced unit does not exist or is inactive
+`;
+
+    const result = parseCommandDoc("CreateItem", markdown);
+
+    expect(result.commandName).toBe("createItem");
+    expect(result.errors).toEqual([
+      { code: "DUPLICATE_SKU", description: "An item with the same SKU already exists" },
+      { code: "DUPLICATE_BARCODE", description: "An item with the same barcode already exists" },
+      { code: "UNIT_NOT_FOUND", description: "Referenced unit does not exist or is inactive" },
+    ]);
+    expect(result.externalDependencies).toEqual([{ module: "primitives", entity: "Unit" }]);
+  });
+
+  it("handles command doc with no external dependencies", () => {
+    const markdown = `# CreateUser
+
+## Overview
+
+Creates a new user.
+
+## Business Rules
+
+- Email must be unique
+
+## Process Flow
+
+\`\`\`mermaid
+flowchart TD
+    A[Start] --> B[End]
+\`\`\`
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **USER_ALREADY_EXISTS**: User with this email already exists
+- **INVALID_EMAIL**: Invalid email format
+`;
+
+    const result = parseCommandDoc("CreateUser", markdown);
+
+    expect(result.commandName).toBe("createUser");
+    expect(result.externalDependencies).toEqual([]);
+    expect(result.errors).toHaveLength(2);
+  });
+
+  it("handles command doc without External Dependencies section", () => {
+    const markdown = `# ActivateItem
+
+## Overview
+
+Activates a draft item.
+
+## Business Rules
+
+- Item must be in DRAFT status
+
+## Process Flow
+
+\`\`\`mermaid
+flowchart TD
+    A[Start] --> B[End]
+\`\`\`
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Item does not exist
+- **INVALID_STATE_TRANSITION**: Item is not in a valid state for activation
+`;
+
+    const result = parseCommandDoc("ActivateItem", markdown);
+
+    expect(result.commandName).toBe("activateItem");
+    expect(result.externalDependencies).toEqual([]);
+    expect(result.errors).toHaveLength(2);
+  });
+
+  it("extracts multiple external dependencies", () => {
+    const markdown = `# CreateOrder
+
+## Overview
+
+Creates an order.
+
+## Business Rules
+
+- Must reference valid item and customer
+
+## Process Flow
+
+\`\`\`mermaid
+flowchart TD
+    A[Start] --> B[End]
+\`\`\`
+
+## External Dependencies
+
+- [item-management::Item](../../../item-management/docs/models/Item.md) - Validates item
+- [primitives::Currency](../../../primitives/docs/models/Currency.md) - Validates currency
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+`;
+
+    const result = parseCommandDoc("CreateOrder", markdown);
+
+    expect(result.externalDependencies).toEqual([
+      { module: "item-management", entity: "Item" },
+      { module: "primitives", entity: "Currency" },
+    ]);
+  });
+});
+
+describe("errorCodeToClassName", () => {
+  it("converts UPPER_SNAKE_CASE to PascalCase with Error suffix", () => {
+    expect(errorCodeToClassName("DUPLICATE_SKU")).toBe("DuplicateSkuError");
+    expect(errorCodeToClassName("UNIT_NOT_FOUND")).toBe("UnitNotFoundError");
+    expect(errorCodeToClassName("ITEM_NOT_FOUND")).toBe("ItemNotFoundError");
+    expect(errorCodeToClassName("USER_ALREADY_EXISTS")).toBe("UserAlreadyExistsError");
+  });
+
+  it("handles single word codes", () => {
+    expect(errorCodeToClassName("UNAUTHORIZED")).toBe("UnauthorizedError");
+  });
+});