@tailor-platform/erp-kit 0.2.2 → 0.4.0

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

@@ -0,0 +1,178 @@
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { parseTestCasesFromDoc, parseItDescriptionsFromTest } from "../parse-doc-test-cases";
+import { runTestCaseSyncCheck } from "./sync-check-tests";
+
+describe("parseTestCasesFromDoc", () => {
+  it("extracts test cases from ## Test Cases section", () => {
+    const content = `# CreateProduct
+
+## Error Scenarios
+
+- **DUPLICATE_CODE**: A product with the same code already exists
+
+## Test Cases
+
+- returns error when code is empty
+- creates product in DRAFT status
+- passes custom fields through
+`;
+    const cases = parseTestCasesFromDoc(content);
+    expect(cases).toEqual([
+      "returns error when code is empty",
+      "creates product in DRAFT status",
+      "passes custom fields through",
+    ]);
+  });
+
+  it("returns empty array when no Test Cases section", () => {
+    const content = `# CreateProduct\n\n## Overview\n\nSome text.`;
+    expect(parseTestCasesFromDoc(content)).toEqual([]);
+  });
+
+  it("stops at next ## heading", () => {
+    const content = `## Test Cases
+
+- case one
+- case two
+
+## Other Section
+
+- not a test case
+`;
+    expect(parseTestCasesFromDoc(content)).toEqual(["case one", "case two"]);
+  });
+});
+
+describe("parseItDescriptionsFromTest", () => {
+  it("extracts it() descriptions from test file", () => {
+    const content = `
+describe("createProduct", () => {
+  it("returns error when code is empty", async () => {});
+  it("creates product in DRAFT status", async () => {});
+  it('passes custom fields through', async () => {});
+});`;
+    const descriptions = parseItDescriptionsFromTest(content);
+    expect(descriptions).toEqual([
+      "returns error when code is empty",
+      "creates product in DRAFT status",
+      "passes custom fields through",
+    ]);
+  });
+
+  it("returns empty array when no it() blocks", () => {
+    expect(parseItDescriptionsFromTest("const x = 1;")).toEqual([]);
+  });
+});
+
+describe("runTestCaseSyncCheck", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sync-check-tc-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("reports missing-test-case when doc has case not in test", async () => {
+    const docDir = path.join(tmpDir, "modules", "foo", "docs", "commands");
+    const testDir = path.join(tmpDir, "modules", "foo", "command");
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.mkdirSync(testDir, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(docDir, "CreateOrder.md"),
+      "# CreateOrder\n\n## Test Cases\n\n- creates order\n- validates input\n",
+    );
+    fs.writeFileSync(path.join(testDir, "createOrder.ts"), "export {}");
+    fs.writeFileSync(
+      path.join(testDir, "createOrder.test.ts"),
+      'describe("createOrder", () => { it("creates order", async () => {}); });',
+    );
+
+    const errors = await runTestCaseSyncCheck("modules", tmpDir);
+    expect(errors).toContainEqual(
+      expect.objectContaining({
+        type: "missing-test-case",
+        category: "command-test-case",
+        expectedBasename: "validates input",
+      }),
+    );
+  });
+
+  it("reports extra-test-case when test has case not in doc", async () => {
+    const docDir = path.join(tmpDir, "modules", "foo", "docs", "commands");
+    const testDir = path.join(tmpDir, "modules", "foo", "command");
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.mkdirSync(testDir, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(docDir, "CreateOrder.md"),
+      "# CreateOrder\n\n## Test Cases\n\n- creates order\n",
+    );
+    fs.writeFileSync(path.join(testDir, "createOrder.ts"), "export {}");
+    fs.writeFileSync(
+      path.join(testDir, "createOrder.test.ts"),
+      'describe("createOrder", () => { it("creates order", async () => {}); it("extra case", async () => {}); });',
+    );
+
+    const errors = await runTestCaseSyncCheck("modules", tmpDir);
+    expect(errors).toContainEqual(
+      expect.objectContaining({
+        type: "extra-test-case",
+        category: "command-test-case",
+        expectedBasename: "extra case",
+      }),
+    );
+  });
+
+  it("returns 0 when doc test cases match test it() descriptions", async () => {
+    const docDir = path.join(tmpDir, "modules", "foo", "docs", "commands");
+    const testDir = path.join(tmpDir, "modules", "foo", "command");
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.mkdirSync(testDir, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(docDir, "CreateOrder.md"),
+      "# CreateOrder\n\n## Test Cases\n\n- creates order\n- validates input\n",
+    );
+    fs.writeFileSync(path.join(testDir, "createOrder.ts"), "export {}");
+    fs.writeFileSync(
+      path.join(testDir, "createOrder.test.ts"),
+      'describe("createOrder", () => { it("creates order", async () => {}); it("validates input", async () => {}); });',
+    );
+
+    const errors = await runTestCaseSyncCheck("modules", tmpDir);
+    const tcErrors = errors.filter(
+      (e) => e.type === "missing-test-case" || e.type === "extra-test-case",
+    );
+    expect(tcErrors).toHaveLength(0);
+  });
+
+  it("skips test-case check when doc has no Test Cases section", async () => {
+    const docDir = path.join(tmpDir, "modules", "foo", "docs", "commands");
+    const testDir = path.join(tmpDir, "modules", "foo", "command");
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.mkdirSync(testDir, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(docDir, "CreateOrder.md"),
+      "# CreateOrder\n\n## Overview\n\nSome text.\n",
+    );
+    fs.writeFileSync(path.join(testDir, "createOrder.ts"), "export {}");
+    fs.writeFileSync(
+      path.join(testDir, "createOrder.test.ts"),
+      'describe("createOrder", () => { it("creates order", async () => {}); });',
+    );
+
+    const errors = await runTestCaseSyncCheck("modules", tmpDir);
+    const tcErrors = errors.filter(
+      (e) => e.type === "missing-test-case" || e.type === "extra-test-case",
+    );
+    expect(tcErrors).toHaveLength(0);
+  });
+});

package/src/commands/lib/sync-check-tests.ts

@@ -0,0 +1,69 @@
+import path from "node:path";
+import fs from "node:fs";
+import fg from "fast-glob";
+import { parseTestCasesFromDoc, parseItDescriptionsFromTest } from "../parse-doc-test-cases";
+import { testCaseCategories } from "./discovery";
+import type { CheckError } from "./sync-check-source";
+
+function toCamelCase(pascalCase: string): string {
+  return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
+}
+
+export async function runTestCaseSyncCheck(root: string, cwd: string): Promise<CheckError[]> {
+  const errors: CheckError[] = [];
+  const categories = testCaseCategories(root);
+
+  for (const category of categories) {
+    const docPaths = await fg(category.docPattern, { cwd });
+
+    for (const docPath of docPaths) {
+      const docFullPath = path.join(cwd, docPath);
+      const docContent = fs.readFileSync(docFullPath, "utf-8");
+      const docTestCases = parseTestCasesFromDoc(docContent);
+
+      if (docTestCases.length === 0) continue;
+
+      const docBasename = path.basename(docPath, ".md");
+      const docsIndex = docPath.indexOf("/docs/");
+      if (docsIndex === -1) continue;
+      const modulePath = docPath.substring(0, docsIndex);
+      const testFileName = `${toCamelCase(docBasename)}.test.ts`;
+      const testPath = path.join(modulePath, category.testDir, testFileName);
+      const testFullPath = path.join(cwd, testPath);
+
+      if (!fs.existsSync(testFullPath)) continue;
+
+      const testContent = fs.readFileSync(testFullPath, "utf-8");
+      const itDescriptions = parseItDescriptionsFromTest(testContent);
+
+      const docSet = new Set(docTestCases);
+      const testSet = new Set(itDescriptions);
+
+      for (const docCase of docSet) {
+        if (!testSet.has(docCase)) {
+          errors.push({
+            type: "missing-test-case",
+            category: category.name,
+            docPath,
+            sourcePath: testPath,
+            expectedBasename: docCase,
+          });
+        }
+      }
+
+      for (const testCase of testSet) {
+        if (!docSet.has(testCase)) {
+          errors.push({
+            type: "extra-test-case",
+            category: category.name,
+            docPath,
+            sourcePath: testPath,
+            expectedBasename: testCase,
+          });
+        }
+      }
+    }
+  }
+
+  return errors;
+}

package/src/commands/mock/index.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { defineCommand, arg } from "politty";
+import { executeCommand, success, silentFailure } from "../lib/command-result";
 import { runMockStart } from "./start";
 import { runMockValidate } from "./validate";
 
@@ -19,9 +20,11 @@ const startCommand = defineCommand({
       description: "Filter by provider or provider/scenario",
     }),
   }),
-  run: async (args) => {
-    const exitCode = await runMockStart(args.mocksRoot, args.filter, args.port);
-    process.exit(exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const exitCode = await runMockStart(args.mocksRoot, args.filter, args.port);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -37,9 +40,11 @@ const validateCommand = defineCommand({
       description: "Specific scenario paths to validate",
     }),
   }),
-  run: async (args) => {
-    const exitCode = await runMockValidate(args.mocksRoot, args.paths);
-    process.exit(exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const exitCode = await runMockValidate(args.mocksRoot, args.paths);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 

package/src/commands/module/generate.ts

@@ -2,34 +2,59 @@ import path from "node:path";
 import { defineCommand, arg } from "politty";
 import { z } from "zod";
 import { runGenerateCode } from "../../generator/generate-code";
+import { runGenerateDoc, MODULE_DOC_TYPES, type DocType } from "../generate-doc";
+import { executeCommand, success, silentFailure } from "../lib/command-result";
 
 const cwd = process.cwd();
 
-const codeCommand = defineCommand({
-  name: "code",
-  description: "Generate errors, permissions, command shells, and query shells from docs",
-  args: z.object({
-    root: arg(z.string(), {
-      alias: "r",
-      description: "Path to modules directory",
+const pathArgs = z.object({
+  path: arg(z.string(), {
+    alias: "p",
+    description: "Path to the module directory",
+  }),
+});
+
+const docCommand = defineCommand({
+  name: "doc",
+  description: "Create a documentation file from a schema template",
+  args: pathArgs.extend({
+    type: arg(z.enum(MODULE_DOC_TYPES as unknown as [string, ...string[]]), {
+      positional: true,
+      description: `Doc type (${MODULE_DOC_TYPES.join(", ")})`,
     }),
-    module: arg(z.string(), {
+    name: arg(z.string().optional(), {
       positional: true,
-      description: "Module name (e.g., primitives, item-management)",
+      description: "Item name (required for all types)",
     }),
   }),
   run: (args) => {
-    const modulePath = path.resolve(cwd, args.root, args.module);
-    console.log(`Generating code for ${args.module}...`);
-    const exitCode = runGenerateCode(modulePath, args.module);
-    process.exit(exitCode);
+    return executeCommand(async () => {
+      const exitCode = await runGenerateDoc(args.type as DocType, args.name, args.path, cwd);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
+  },
+});
+
+const codeCommand = defineCommand({
+  name: "code",
+  description: "Generate boilerplate, implementation stubs, and generated code from docs",
+  args: pathArgs,
+  run: (args) => {
+    return executeCommand(() => {
+      const modulePath = path.resolve(cwd, args.path);
+      const moduleName = path.basename(modulePath);
+      console.log(`Generating code for ${moduleName}...`);
+      const exitCode = runGenerateCode(modulePath, moduleName);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
 export const generateCommand = defineCommand({
   name: "generate",
-  description: "Generate code from model definitions and docs",
+  description: "Generate docs and code for a module",
   subCommands: {
+    doc: docCommand,
     code: codeCommand,
   },
 });

package/src/commands/module/index.ts

@@ -1,76 +1,63 @@
 import { z } from "zod";
 import { defineCommand, arg } from "politty";
 import { runCheck } from "../check";
+import { runInitModuleWithReadme } from "../init-module";
+import { executeCommand, success, silentFailure } from "../lib/command-result";
 import { runSyncCheck, formatSyncCheckReport } from "../sync-check";
-import { runScaffold, MODULE_TYPES, type ScaffoldType } from "../scaffold";
-import { runModuleList } from "./list";
 import { generateCommand } from "./generate";
 
 const cwd = process.cwd();
 
-const rootArgs = z.object({
-  root: arg(z.string(), {
-    alias: "r",
+const pathArgs = z.object({
+  path: arg(z.string(), {
+    alias: "p",
     description: "Path to modules directory",
   }),
 });
 
-const listCommand = defineCommand({
-  name: "list",
-  description: "List available modules",
-  run: () => {
-    const exitCode = runModuleList();
-    process.exit(exitCode);
-  },
-});
-
 const checkCommand = defineCommand({
   name: "check",
   description: "Validate module docs against schemas",
-  args: rootArgs,
-  run: async (args) => {
-    const exitCode = await runCheck({ modulesRoot: args.root }, cwd);
-    process.exit(exitCode);
+  args: pathArgs,
+  run: (args) => {
+    return executeCommand(async () => {
+      const exitCode = await runCheck({ modulesRoot: args.path }, cwd);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
 const syncCheckCommand = defineCommand({
   name: "sync-check",
   description: "Validate source <-> doc correspondence",
-  args: rootArgs,
-  run: async (args) => {
-    const result = await runSyncCheck({ modulesRoot: args.root }, cwd);
-    console.log(formatSyncCheckReport(result));
-    process.exit(result.exitCode);
+  args: pathArgs,
+  run: (args) => {
+    return executeCommand(async () => {
+      const result = await runSyncCheck({ modulesRoot: args.path }, cwd);
+      console.log(formatSyncCheckReport(result));
+      return result.exitCode === 0 ? success() : silentFailure(result.exitCode);
+    });
   },
 });
 
-const scaffoldCommand = defineCommand({
-  name: "scaffold",
-  description: "Generate module doc from schema template",
-  args: rootArgs.extend({
-    type: arg(z.enum(MODULE_TYPES as unknown as [string, ...string[]]), {
-      positional: true,
-      description: `Scaffold type (${MODULE_TYPES.join(", ")})`,
-    }),
-    parent: arg(z.string(), {
+const initCommand = defineCommand({
+  name: "init",
+  description: "Bootstrap a new module with directory structure and README",
+  args: z.object({
+    name: arg(z.string(), {
       positional: true,
       description: "Module name",
     }),
-    name: arg(z.string().optional(), {
+    dir: arg(z.string(), {
       positional: true,
-      description: "Item name (required for feature, command, model)",
+      description: "Parent directory where the module will be created",
     }),
   }),
-  run: async (args) => {
-    const exitCode = await runScaffold(
-      args.type as ScaffoldType,
-      args.parent,
-      args.name,
-      args.root,
-      cwd,
-    );
-    process.exit(exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const exitCode = await runInitModuleWithReadme(args.name, args.dir, cwd);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -78,10 +65,9 @@ export const moduleCommand = defineCommand({
   name: "module",
   description: "Module management",
   subCommands: {
-    list: listCommand,
     check: checkCommand,
     "sync-check": syncCheckCommand,
-    scaffold: scaffoldCommand,
+    init: initCommand,
     generate: generateCommand,
   },
 });

package/src/commands/parse-doc-test-cases.ts

@@ -43,13 +43,24 @@ export function parseTestCasesFromDoc(markdown: string): string[] {
 /**
  * Parse `it("...")` descriptions from a test file using regex.
  * Test files are not Markdown, so regex is appropriate here.
+ * Uses separate patterns per quote type so that e.g. an apostrophe
+ * inside a double-quoted string does not end the match early.
  */
 export function parseItDescriptionsFromTest(content: string): string[] {
   const descriptions: string[] = [];
-  const regex = /\bit\(\s*["'`]([^"'`]+)["'`]/g;
+  const regex = /\bit\(\s*"([^"]+)"/gs;
   let match: RegExpExecArray | null;
   while ((match = regex.exec(content)) !== null) {
-    descriptions.push(match[1]);
+    descriptions.push(match[1].replace(/\s+/g, " ").trim());
+  }
+  // Also match single-quoted and backtick-quoted descriptions
+  const singleQuoteRegex = /\bit\(\s*'([^']+)'/gs;
+  while ((match = singleQuoteRegex.exec(content)) !== null) {
+    descriptions.push(match[1].replace(/\s+/g, " ").trim());
+  }
+  const backtickRegex = /\bit\(\s*`([^`]+)`/gs;
+  while ((match = backtickRegex.exec(content)) !== null) {
+    descriptions.push(match[1].replace(/\s+/g, " ").trim());
   }
   return descriptions;
 }