@tailor-platform/erp-kit 0.1.2 → 0.2.0

package/src/commands/scaffold.test.ts

@@ -1,5 +1,17 @@
-import { describe, it, expect } from "vitest";
-import { resolveScaffoldPath } from "./scaffold.js";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  type Diagnostic,
+  DiagnosticCategory,
+  flattenDiagnosticMessageText,
+  ModuleKind,
+  ScriptTarget,
+  transpileModule,
+} from "typescript";
+import { describe, it, expect, afterEach } from "vitest";
+import { resolveScaffoldPath, scaffoldModuleSrc } from "./scaffold";
+import { getModuleSrcTemplates } from "./scaffold-templates";
 
 describe("resolveScaffoldPath", () => {
   // Module types
@@ -79,3 +91,81 @@ describe("resolveScaffoldPath", () => {
     );
   });
 });
+
+describe("scaffoldModuleSrc", () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("creates expected directories and files", () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "scaffold-test-"));
+    const moduleDir = path.join(tmpDir, "test-module");
+    fs.mkdirSync(moduleDir, { recursive: true });
+
+    scaffoldModuleSrc(moduleDir, "test-module");
+
+    // Verify directories exist directly under module root (flat structure)
+    for (const dir of ["db", "command", "executor", "generated", "lib", "query", "testing"]) {
+      expect(fs.existsSync(path.join(moduleDir, dir))).toBe(true);
+    }
+
+    // Verify .gitkeep in empty directories
+    for (const dir of ["db", "command", "executor", "generated", "query"]) {
+      expect(fs.existsSync(path.join(moduleDir, dir, ".gitkeep"))).toBe(true);
+    }
+
+    // Verify starter files exist
+    const expectedFiles = [
+      "module.ts",
+      "index.ts",
+      "permissions.ts",
+      "tailor.config.ts",
+      "lib/errors.ts",
+      "lib/types.ts",
+      "testing/fixtures.ts",
+    ];
+    for (const file of expectedFiles) {
+      expect(fs.existsSync(path.join(moduleDir, file))).toBe(true);
+    }
+
+    // Verify module name is used in content
+    const permissions = fs.readFileSync(path.join(moduleDir, "permissions.ts"), "utf-8");
+    expect(permissions).toContain('definePermissions("test-module"');
+
+    const config = fs.readFileSync(path.join(moduleDir, "tailor.config.ts"), "utf-8");
+    expect(config).toContain('name: "test-module"');
+
+    const moduleFile = fs.readFileSync(path.join(moduleDir, "module.ts"), "utf-8");
+    expect(moduleFile).toContain("defineModule");
+    expect(moduleFile).toContain("commands");
+    expect(moduleFile).toContain("queries");
+  });
+
+  it("generates syntactically valid TypeScript for all file templates", () => {
+    const templates = getModuleSrcTemplates();
+    const fileTemplates = templates.filter((t) => t.type === "file");
+
+    for (const entry of fileTemplates) {
+      const source = entry.content("test-module");
+      const result = transpileModule(source, {
+        reportDiagnostics: true,
+        compilerOptions: { target: ScriptTarget.ESNext, module: ModuleKind.ESNext },
+      });
+      const errors = (result.diagnostics ?? []).filter(
+        (d) => d.category === DiagnosticCategory.Error,
+      );
+      expect(
+        errors,
+        `syntax errors in template "${entry.path}": ${formatDiagnostics(errors)}`,
+      ).toHaveLength(0);
+    }
+  });
+});
+
+function formatDiagnostics(diagnostics: Diagnostic[]): string {
+  return diagnostics.map((d) => flattenDiagnosticMessageText(d.messageText, "\n")).join("; ");
+}

package/src/commands/scaffold.ts

@@ -1,7 +1,8 @@
 import path from "node:path";
 import fs from "node:fs";
-import { runMdschema } from "../mdschema.js";
-import { ALL_SCHEMAS } from "../schemas.js";
+import { runMdschema } from "../mdschema";
+import { ALL_SCHEMAS } from "../schemas";
+import { getModuleSrcTemplates } from "./scaffold-templates";
 
 export const MODULE_TYPES = ["module", "feature", "command", "model", "query"] as const;
 export const APP_TYPES = [
@@ -116,5 +117,24 @@ export async function runScaffold(
   if (stdout.trim()) console.log(stdout);
   if (stderr.trim()) console.error(stderr);
 
+  if (exitCode !== 0) return exitCode;
+
+  if (type === "module") {
+    scaffoldModuleSrc(path.dirname(absoluteOutput), parentName);
+  }
+
   return exitCode;
 }
+
+export function scaffoldModuleSrc(moduleDir: string, moduleName: string): void {
+  for (const entry of getModuleSrcTemplates()) {
+    const fullPath = path.join(moduleDir, entry.path);
+    if (entry.type === "dir") {
+      fs.mkdirSync(fullPath, { recursive: true });
+      fs.writeFileSync(path.join(fullPath, ".gitkeep"), "");
+    } else {
+      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+      fs.writeFileSync(fullPath, entry.content(moduleName));
+    }
+  }
+}

package/src/commands/sync-check.test.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 import os from "node:os";
 import fs from "node:fs";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { runSyncCheck } from "./sync-check.js";
+import { runSyncCheck, checkStaleness } from "./sync-check";
 
 describe("runSyncCheck", () => {
   let tmpDir: string;
@@ -131,6 +131,32 @@ describe("runSyncCheck", () => {
     expect(result.exitCode).toBe(0);
   });
 
+  it("matches generated query files to docs by stripping .generated suffix", async () => {
+    const srcDir = path.join(tmpDir, "modules", "foo", "query");
+    const docDir = path.join(tmpDir, "modules", "foo", "docs", "queries");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "getCurrency.generated.ts"), "export {}");
+    fs.writeFileSync(path.join(docDir, "GetCurrency.md"), "# GetCurrency");
+
+    const result = await runSyncCheck({ modulesRoot: "modules", appRoot: "examples" }, tmpDir);
+    expect(result.exitCode).toBe(0);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it("excludes generated command files from source matching", async () => {
+    const srcDir = path.join(tmpDir, "modules", "foo", "command");
+    const docDir = path.join(tmpDir, "modules", "foo", "docs", "commands");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "createOrder.ts"), "export {}");
+    fs.writeFileSync(path.join(srcDir, "createOrder.generated.ts"), "export {}");
+    fs.writeFileSync(path.join(docDir, "createOrder.md"), "# CreateOrder");
+
+    const result = await runSyncCheck({ modulesRoot: "modules", appRoot: "examples" }, tmpDir);
+    expect(result.exitCode).toBe(0);
+  });
+
   it("checks only module patterns when appRoot is not set", async () => {
     const resolverSrcDir = path.join(
       tmpDir,
@@ -151,3 +177,36 @@ describe("runSyncCheck", () => {
     expect(result.errors).toHaveLength(0);
   });
 });
+
+describe("checkStaleness", () => {
+  it("reports stale when doc mtime > generated mtime", () => {
+    const errors = checkStaleness(
+      [{ docPath: "docs/commands/CreateItem.md", docMtime: 2000 }],
+      [{ genPath: "lib/errors.generated.ts", genMtime: 1000 }],
+    );
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0].type).toBe("stale-generation");
+  });
+
+  it("reports no staleness when generated is newer", () => {
+    const errors = checkStaleness(
+      [{ docPath: "docs/commands/CreateItem.md", docMtime: 1000 }],
+      [{ genPath: "lib/errors.generated.ts", genMtime: 2000 }],
+    );
+
+    expect(errors).toHaveLength(0);
+  });
+
+  it("returns empty when no generated files", () => {
+    const errors = checkStaleness([{ docPath: "docs/commands/CreateItem.md", docMtime: 1000 }], []);
+
+    expect(errors).toHaveLength(0);
+  });
+
+  it("returns empty when no doc files", () => {
+    const errors = checkStaleness([], [{ genPath: "lib/errors.generated.ts", genMtime: 1000 }]);
+
+    expect(errors).toHaveLength(0);
+  });
+});

package/src/commands/sync-check.ts

@@ -33,7 +33,7 @@ function moduleCategories(root: string): CategoryConfig[] {
       name: "command",
       sourcePattern: `${root}/*/command/*.ts`,
       docPattern: `${root}/*/docs/commands/*.md`,
-      exclusions: [/\.test\.ts$/],
+      exclusions: [/\.test\.ts$/, /\.generated\.ts$/],
     },
     {
       name: "model",
@@ -91,7 +91,10 @@ export async function runSyncCheck(
     for (const sourcePath of sources) {
       const fileName = path.basename(sourcePath);
       if (shouldExclude(fileName, category.exclusions)) continue;
-      const basename = path.basename(sourcePath, path.extname(sourcePath));
+      let basename = path.basename(sourcePath, path.extname(sourcePath));
+      if (basename.endsWith(".generated")) {
+        basename = basename.slice(0, -".generated".length);
+      }
       sourceBasenames.set(basename.toLowerCase(), sourcePath);
     }
 
@@ -137,6 +140,36 @@ export async function runSyncCheck(
   };
 }
 
+export interface StalenessError {
+  type: "stale-generation";
+  docPath: string;
+  genPath: string;
+}
+
+export function checkStaleness(
+  docs: { docPath: string; docMtime: number }[],
+  generated: { genPath: string; genMtime: number }[],
+): StalenessError[] {
+  const errors: StalenessError[] = [];
+
+  if (generated.length === 0 || docs.length === 0) return errors;
+
+  const latestDocMtime = Math.max(...docs.map((d) => d.docMtime));
+  const oldestGenMtime = Math.min(...generated.map((g) => g.genMtime));
+
+  if (latestDocMtime > oldestGenMtime) {
+    const newestDoc = docs.find((d) => d.docMtime === latestDocMtime)!;
+    const oldestGen = generated.find((g) => g.genMtime === oldestGenMtime)!;
+    errors.push({
+      type: "stale-generation",
+      docPath: newestDoc.docPath,
+      genPath: oldestGen.genPath,
+    });
+  }
+
+  return errors;
+}
+
 export function formatSyncCheckReport(result: SyncCheckResult): string {
   const lines: string[] = [];
   lines.push(chalk.bold("docs-sync-check: Checking source-documentation correspondence...\n"));

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