@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/src/commands/sync-check.ts

@@ -1,264 +1,20 @@
-import path from "node:path";
-import fs from "node:fs";
-import fg from "fast-glob";
 import chalk from "chalk";
-import { parseTestCasesFromDoc, parseItDescriptionsFromTest } from "./parse-doc-test-cases";
+import { runSourceSyncCheck, type SyncCheckResult, type CheckError } from "./lib/sync-check-source";
+import { runTestCaseSyncCheck } from "./lib/sync-check-tests";
 
-interface CategoryConfig {
-  name: string;
-  sourcePattern: string;
-  docPattern: string;
-  exclusions: RegExp[];
-}
-
-export interface CheckError {
-  type: "missing-doc" | "orphaned-doc" | "missing-test-case" | "extra-test-case";
-  category: string;
-  sourcePath?: string;
-  docPath?: string;
-  expectedBasename: string;
-}
-
-export interface SyncCheckResult {
-  exitCode: number;
-  errors: CheckError[];
-  summary: {
-    categoriesChecked: number;
-    totalSources: number;
-    totalDocs: number;
-  };
-}
-
-function moduleCategories(root: string): CategoryConfig[] {
-  return [
-    {
-      name: "command",
-      sourcePattern: `${root}/*/command/*.ts`,
-      docPattern: `${root}/*/docs/commands/*.md`,
-      exclusions: [/\.test\.ts$/, /\.generated\.ts$/],
-    },
-    {
-      name: "model",
-      sourcePattern: `${root}/*/db/*.ts`,
-      docPattern: `${root}/*/docs/models/*.md`,
-      exclusions: [/\.test\.ts$/, /^index\.ts$/],
-    },
-    {
-      name: "query",
-      sourcePattern: `${root}/*/query/*.ts`,
-      docPattern: `${root}/*/docs/queries/*.md`,
-      exclusions: [/\.test\.ts$/],
-    },
-  ];
-}
-
-function appComposeCategories(root: string): CategoryConfig[] {
-  return [
-    {
-      name: "resolver",
-      sourcePattern: `${root}/*/backend/src/modules/**/resolvers/*.ts`,
-      docPattern: `${root}/*/docs/resolver/*.md`,
-      exclusions: [/\.test\.ts$/, /^index\.ts$/],
-    },
-  ];
-}
-
-function shouldExclude(fileName: string, exclusions: RegExp[]): boolean {
-  return exclusions.some((pattern) => pattern.test(fileName));
-}
+export type { SyncCheckResult, CheckError } from "./lib/sync-check-source";
 
 export async function runSyncCheck(
   config: { modulesRoot?: string; appRoot?: string },
   cwd: string,
 ): Promise<SyncCheckResult> {
-  const errors: CheckError[] = [];
-  let totalSources = 0;
-  let totalDocs = 0;
-
-  const allCategories: CategoryConfig[] = [];
-  if (config.modulesRoot) {
-    allCategories.push(...moduleCategories(config.modulesRoot));
-  }
-  if (config.appRoot) {
-    allCategories.push(...appComposeCategories(config.appRoot));
-  }
-
-  for (const category of allCategories) {
-    const sources = await fg(category.sourcePattern, { cwd });
-    const docs = await fg(category.docPattern, { cwd });
-
-    const sourceBasenames = new Map<string, string>();
-    const docBasenames = new Map<string, string>();
-
-    for (const sourcePath of sources) {
-      const fileName = path.basename(sourcePath);
-      if (shouldExclude(fileName, category.exclusions)) continue;
-      let basename = path.basename(sourcePath, path.extname(sourcePath));
-      if (basename.endsWith(".generated")) {
-        basename = basename.slice(0, -".generated".length);
-      }
-      sourceBasenames.set(basename.toLowerCase(), sourcePath);
-    }
-
-    for (const docPath of docs) {
-      const basename = path.basename(docPath, path.extname(docPath));
-      docBasenames.set(basename.toLowerCase(), docPath);
-    }
-
-    for (const [basename, sourcePath] of sourceBasenames) {
-      if (!docBasenames.has(basename)) {
-        errors.push({
-          type: "missing-doc",
-          category: category.name,
-          sourcePath,
-          expectedBasename: basename,
-        });
-      }
-    }
-
-    for (const [basename, docPath] of docBasenames) {
-      if (!sourceBasenames.has(basename)) {
-        errors.push({
-          type: "orphaned-doc",
-          category: category.name,
-          docPath,
-          expectedBasename: basename,
-        });
-      }
-    }
-
-    totalSources += sourceBasenames.size;
-    totalDocs += docBasenames.size;
-  }
-
+  const sourceResult = await runSourceSyncCheck(config, cwd);
   if (config.modulesRoot) {
     const testCaseErrors = await runTestCaseSyncCheck(config.modulesRoot, cwd);
-    errors.push(...testCaseErrors);
+    sourceResult.errors.push(...testCaseErrors);
+    sourceResult.exitCode = sourceResult.errors.length > 0 ? 1 : 0;
   }
-
-  return {
-    exitCode: errors.length > 0 ? 1 : 0,
-    errors,
-    summary: {
-      categoriesChecked: allCategories.length,
-      totalSources,
-      totalDocs,
-    },
-  };
-}
-
-interface TestCaseCategoryConfig {
-  name: string;
-  docPattern: string;
-  testDir: string;
-}
-
-function testCaseCategories(root: string): TestCaseCategoryConfig[] {
-  return [
-    {
-      name: "command-test-case",
-      docPattern: `${root}/*/docs/commands/*.md`,
-      testDir: "command",
-    },
-    {
-      name: "query-test-case",
-      docPattern: `${root}/*/docs/queries/*.md`,
-      testDir: "query",
-    },
-  ];
-}
-
-function toCamelCase(pascalCase: string): string {
-  return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
-}
-
-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;
-}
-
-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;
+  return sourceResult;
 }
 
 export function formatSyncCheckReport(result: SyncCheckResult): string {

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

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import { runGenerateAppCode } from "./generate-app-code";
+
+describe("runGenerateAppCode", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "erp-kit-app-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("generates resolver stubs and tests from docs", () => {
+    // Set up docs
+    const docsDir = path.join(tmpDir, "docs", "resolver");
+    fs.mkdirSync(docsDir, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(docsDir, "createItem.md"),
+      `# createItem
+
+## Overview
+
+Creates a new item.
+
+## Modules Commands Used
+
+- \`item-management.createItem\` — Creates a new item record
+
+## Exception Handling
+
+| Error Code | Description |
+| --- | --- |
+| DUPLICATE_SKU | SKU already exists |
+`,
+    );
+
+    fs.writeFileSync(
+      path.join(docsDir, "getMyProfile.md"),
+      `# getMyProfile
+
+## Overview
+
+Gets profile.
+
+## Modules Commands Used
+
+- \`user-management.getMyProfile\` — Fetches profile
+`,
+    );
+
+    const exitCode = runGenerateAppCode(tmpDir);
+    expect(exitCode).toBe(0);
+
+    const resolverDir = path.join(tmpDir, "backend", "src", "resolvers");
+    expect(fs.existsSync(resolverDir)).toBe(true);
+
+    const files = fs.readdirSync(resolverDir).sort();
+    // Template scaffolding may copy additional files (e.g. createUser.ts)
+    expect(files).toContain("createItem.test.ts");
+    expect(files).toContain("createItem.ts");
+    expect(files).toContain("getMyProfile.test.ts");
+    expect(files).toContain("getMyProfile.ts");
+    expect(files).not.toContain("createItem.generated.ts");
+
+    // Stub has createResolver
+    const stub = fs.readFileSync(path.join(resolverDir, "createItem.ts"), "utf-8");
+    expect(stub).toContain("createResolver");
+    expect(stub).toContain('name: "createItem"');
+    expect(stub).toContain('getDB("main-db")');
+
+    // Test stub exists
+    const test = fs.readFileSync(path.join(resolverDir, "createItem.test.ts"), "utf-8");
+    expect(test).toContain('describe("createItem"');
+  });
+
+  it("does not overwrite existing stubs on re-run", () => {
+    const docsDir = path.join(tmpDir, "docs", "resolver");
+    fs.mkdirSync(docsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(docsDir, "createItem.md"),
+      `# createItem
+
+## Overview
+Creates an item.
+
+## Modules Commands Used
+- \`item-management.createItem\` — Creates item
+`,
+    );
+
+    runGenerateAppCode(tmpDir);
+
+    // Modify the stub
+    const resolverDir = path.join(tmpDir, "backend", "src", "resolvers");
+    const stubPath = path.join(resolverDir, "createItem.ts");
+    fs.writeFileSync(stubPath, "// custom implementation");
+
+    // Re-run
+    runGenerateAppCode(tmpDir);
+
+    // Stub should not be overwritten
+    expect(fs.readFileSync(stubPath, "utf-8")).toBe("// custom implementation");
+  });
+
+  it("returns 0 with no docs/resolver directory", () => {
+    const exitCode = runGenerateAppCode(tmpDir);
+    expect(exitCode).toBe(0);
+  });
+
+  it("returns 0 with empty docs/resolver directory", () => {
+    fs.mkdirSync(path.join(tmpDir, "docs", "resolver"), { recursive: true });
+    const exitCode = runGenerateAppCode(tmpDir);
+    expect(exitCode).toBe(0);
+  });
+});

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

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseResolverDoc } from "./parse-resolver-doc";
+import { generateResolverStub, generateResolverTestStub } from "./generate-stubs";
+import { scaffoldAppBoilerplate } from "./scaffold";
+
+export function runGenerateAppCode(appPath: string): number {
+  const appName = path.basename(appPath);
+  scaffoldAppBoilerplate(appPath, appName);
+
+  const docsDir = path.join(appPath, "docs", "resolver");
+  const resolverDir = path.join(appPath, "backend", "src", "resolvers");
+
+  if (!fs.existsSync(docsDir)) {
+    console.log(`No docs/resolver/ directory found — skipping resolver generation`);
+    console.log(`Generated boilerplate for ${appName}`);
+    return 0;
+  }
+
+  const mdFiles = fs.readdirSync(docsDir).filter((f) => f.endsWith(".md"));
+  if (mdFiles.length === 0) {
+    console.log(`No resolver docs found — skipping resolver generation`);
+    console.log(`Generated boilerplate for ${appName}`);
+    return 0;
+  }
+
+  fs.mkdirSync(resolverDir, { recursive: true });
+  let generated = 0;
+
+  for (const file of mdFiles) {
+    const content = fs.readFileSync(path.join(docsDir, file), "utf-8");
+    const fileName = path.basename(file, ".md");
+    const doc = parseResolverDoc(fileName, content);
+
+    const implFile = path.join(resolverDir, `${doc.resolverName}.ts`);
+    if (!fs.existsSync(implFile)) {
+      fs.writeFileSync(implFile, generateResolverStub(doc.resolverName));
+      console.log(`  scaffolded ${path.relative(appPath, implFile)}`);
+      generated++;
+    }
+
+    const testFile = path.join(resolverDir, `${doc.resolverName}.test.ts`);
+    if (!fs.existsSync(testFile)) {
+      fs.writeFileSync(testFile, generateResolverTestStub(doc.resolverName));
+      console.log(`  scaffolded ${path.relative(appPath, testFile)}`);
+    }
+  }
+
+  console.log(`Scaffolded ${generated} resolver(s) for ${appName}`);
+  return 0;
+}

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

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { describe, it, expect, afterEach } from "vitest";
-import { copyTemplateDir, scaffoldModuleBoilerplate } from "./generate-code";
+import { copyTemplateDir, scaffoldModuleBoilerplate } from "./scaffold";
 
 describe("scaffoldModuleBoilerplate", () => {
   let tmpDir: string;
@@ -33,7 +33,6 @@ describe("scaffoldModuleBoilerplate", () => {
       "index.ts",
       "permissions.ts",
       "tailor.config.ts",
-      "lib/errors.ts",
       "lib/types.ts",
       "testing/fixtures.ts",
     ];

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

@@ -1,14 +1,14 @@
 import { describe, expect, it } from "vitest";
+import { moduleNameToPrefix, generateErrors } from "./generate-errors";
+import { generatePermissions } from "./generate-permissions";
+import { generateCommandShell, generateQueryShell } from "./generate-shells";
 import {
-  generateErrors,
-  generatePermissions,
-  generateCommandShell,
-  generateQueryShell,
   generateQueryStub,
   generateQueryTestStub,
   generateDbStub,
-  moduleNameToPrefix,
-} from "./generate-code";
+  generateResolverStub,
+  generateResolverTestStub,
+} from "./generate-stubs";
 import type { ParsedCommandDoc } from "./parse-command-doc";
 
 describe("moduleNameToPrefix", () => {
@@ -44,7 +44,9 @@ describe("generateErrors", () => {
     const result = generateErrors("item-management", docs);
 
     expect(result).toContain("// @generated — do not edit");
-    expect(result).toContain('import { createDomainError } from "../../../shared";');
+    expect(result).toContain(
+      'import { createDomainError } from "@tailor-platform/erp-kit/module";',
+    );
     expect(result).toContain("export const DuplicateSkuError = createDomainError(");
     expect(result).toContain('"DuplicateSkuError", "ITEM_MANAGEMENT_DUPLICATE_SKU"');
     expect(result).toContain("export const UnitNotFoundError = createDomainError(");
@@ -92,7 +94,9 @@ describe("generatePermissions", () => {
     const result = generatePermissions("item-management", commandNames);
 
     expect(result).toContain("// @generated — do not edit");
-    expect(result).toContain('import { definePermissions } from "../../../shared";');
+    expect(result).toContain(
+      'import { definePermissions } from "@tailor-platform/erp-kit/module";',
+    );
     expect(result).toContain('"item-management"');
     expect(result).toContain('"createItem"');
     expect(result).toContain('"updateItem"');
@@ -128,7 +132,7 @@ describe("generateCommandShell", () => {
     const result = generateCommandShell(doc);
 
     expect(result).toContain("// @generated — do not edit");
-    expect(result).toContain('import { defineCommand } from "../../../shared";');
+    expect(result).toContain('import { defineCommand } from "@tailor-platform/erp-kit/module";');
     expect(result).toContain('import { permissions } from "../lib/permissions.generated";');
     expect(result).toContain('import { run } from "./activateItem";');
     expect(result).toContain(
@@ -145,7 +149,7 @@ describe("generateCommandShell", () => {
 
     const result = generateCommandShell(doc);
 
-    expect(result).toContain('import { defineCommand } from "../../../shared";');
+    expect(result).toContain('import { defineCommand } from "@tailor-platform/erp-kit/module";');
     expect(result).toContain('import { run } from "./createItem";');
     expect(result).toContain(
       "export const createItem = defineCommand(permissions.createItem, run);",
@@ -164,7 +168,7 @@ describe("generateQueryShell", () => {
     const result = generateQueryShell(doc);
 
     expect(result).toContain("// @generated — do not edit");
-    expect(result).toContain('import { defineQuery } from "../../../shared";');
+    expect(result).toContain('import { defineQuery } from "@tailor-platform/erp-kit/module";');
     expect(result).toContain('import { run } from "./getTaxonomyNode";');
     expect(result).toContain("export const getTaxonomyNode = defineQuery(run);");
   });
@@ -180,7 +184,7 @@ describe("generateQueryStub", () => {
 
     const result = generateQueryStub(doc);
 
-    expect(result).toContain('import type { ReadonlyDB } from "../../../shared";');
+    expect(result).toContain('import type { ReadonlyDB } from "@tailor-platform/erp-kit/module";');
     expect(result).toContain('import type { DB } from "../generated/kysely-tailordb";');
     expect(result).toContain("export interface GetTaxonomyNodeInput {");
     expect(result).toContain(
@@ -233,3 +237,30 @@ describe("generateQueryTestStub", () => {
     expect(result).toContain("expect(result).toBeDefined();");
   });
 });
+
+describe("generateResolverStub", () => {
+  it("generates a createResolver stub with SDK imports and transaction boilerplate", () => {
+    const result = generateResolverStub("createItem");
+
+    expect(result).toContain('import { createResolver, t } from "@tailor-platform/sdk";');
+    expect(result).toContain('import { createContext } from "@tailor-platform/erp-kit/app";');
+    expect(result).toContain('import { getDB } from "@/generated/kysely-tailordb";');
+    expect(result).toContain('name: "createItem"');
+    expect(result).toContain('operation: "mutation"');
+    expect(result).toContain('getDB("main-db")');
+    expect(result).toContain("db.transaction().execute");
+    expect(result).toContain('.description("CreateItem response")');
+  });
+});
+
+describe("generateResolverTestStub", () => {
+  it("generates a test that imports and verifies the resolver", () => {
+    const result = generateResolverTestStub("createItem");
+
+    expect(result).toContain('import { describe, expect, it } from "vitest";');
+    expect(result).toContain('describe("createItem"');
+    expect(result).toContain('import("./createItem")');
+    expect(result).toContain("expect(resolver.default).toBeDefined()");
+    expect(result).toContain('expect(resolver.default.name).toBe("createItem")');
+  });
+});