@tailor-platform/erp-kit 0.2.2 → 0.4.0

package/src/commands/init-module.ts

@@ -0,0 +1,74 @@
+import path from "node:path";
+import fs from "node:fs";
+import { runMdschema } from "../mdschema";
+import { MODULE_SCHEMAS, APP_COMPOSE_SCHEMAS } from "../schemas";
+
+export function runInitModule(name: string, dir: string): number {
+  const moduleDir = path.resolve(dir, name);
+
+  if (fs.existsSync(moduleDir)) {
+    console.error(`Directory already exists: ${moduleDir}`);
+    return 1;
+  }
+
+  fs.mkdirSync(moduleDir, { recursive: true });
+  return 0;
+}
+
+export async function runInitModuleWithReadme(
+  name: string,
+  dir: string,
+  cwd: string,
+): Promise<number> {
+  const initResult = runInitModule(name, dir);
+  if (initResult !== 0) return initResult;
+
+  const moduleDir = path.resolve(cwd, dir, name);
+  const readmePath = path.join(moduleDir, "README.md");
+  const schemaPath = MODULE_SCHEMAS.module;
+
+  const { exitCode, stdout, stderr } = await runMdschema(
+    ["generate", "--schema", schemaPath, "--output", readmePath],
+    cwd,
+  );
+
+  if (stdout.trim()) console.log(stdout);
+  if (stderr.trim()) console.error(stderr);
+
+  return exitCode;
+}
+
+export function runInitApp(name: string, dir: string): number {
+  const appDir = path.resolve(dir, name);
+
+  if (fs.existsSync(appDir)) {
+    console.error(`Directory already exists: ${appDir}`);
+    return 1;
+  }
+
+  fs.mkdirSync(appDir, { recursive: true });
+  return 0;
+}
+
+export async function runInitAppWithReadme(
+  name: string,
+  dir: string,
+  cwd: string,
+): Promise<number> {
+  const initResult = runInitApp(name, dir);
+  if (initResult !== 0) return initResult;
+
+  const appDir = path.resolve(cwd, dir, name);
+  const readmePath = path.join(appDir, "README.md");
+  const schemaPath = APP_COMPOSE_SCHEMAS.app;
+
+  const { exitCode, stdout, stderr } = await runMdschema(
+    ["generate", "--schema", schemaPath, "--output", readmePath],
+    cwd,
+  );
+
+  if (stdout.trim()) console.log(stdout);
+  if (stderr.trim()) console.error(stderr);
+
+  return exitCode;
+}

package/src/commands/lib/command-result.ts

@@ -0,0 +1,30 @@
+export type CommandResult = { exitCode: 0 } | { exitCode: number; message: string };
+
+export function success(): CommandResult {
+  return { exitCode: 0 };
+}
+
+export function failure(message: string, exitCode = 1): CommandResult {
+  return { exitCode, message };
+}
+
+export function silentFailure(exitCode = 1): CommandResult {
+  return { exitCode, message: "" };
+}
+
+export async function runCommand(
+  fn: () => CommandResult | Promise<CommandResult>,
+): Promise<CommandResult> {
+  const result = await fn();
+  if (result.exitCode !== 0 && "message" in result && result.message) {
+    console.error(result.message);
+  }
+  return result;
+}
+
+export async function executeCommand(
+  fn: () => CommandResult | Promise<CommandResult>,
+): Promise<never> {
+  const result = await runCommand(fn);
+  process.exit(result.exitCode);
+}

package/src/commands/lib/discovery.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest";
+import {
+  moduleCategories,
+  appComposeCategories,
+  testCaseCategories,
+  buildCheckTargets,
+} from "./discovery";
+
+describe("moduleCategories", () => {
+  it("produces command/model/query categories with correct patterns", () => {
+    const cats = moduleCategories("modules");
+    expect(cats).toHaveLength(3);
+
+    const command = cats.find((c) => c.name === "command")!;
+    expect(command.sourcePattern).toBe("modules/*/command/*.ts");
+    expect(command.docPattern).toBe("modules/*/docs/commands/*.md");
+    expect(command.exclusions).toEqual([/\.test\.ts$/, /\.generated\.ts$/]);
+
+    const model = cats.find((c) => c.name === "model")!;
+    expect(model.sourcePattern).toBe("modules/*/db/*.ts");
+    expect(model.docPattern).toBe("modules/*/docs/models/*.md");
+
+    const query = cats.find((c) => c.name === "query")!;
+    expect(query.sourcePattern).toBe("modules/*/query/*.ts");
+    expect(query.docPattern).toBe("modules/*/docs/queries/*.md");
+  });
+});
+
+describe("appComposeCategories", () => {
+  it("produces resolver category", () => {
+    const cats = appComposeCategories("apps");
+    expect(cats).toHaveLength(1);
+    expect(cats[0].name).toBe("resolver");
+    expect(cats[0].docPattern).toBe("apps/*/docs/resolver/*.md");
+  });
+});
+
+describe("testCaseCategories", () => {
+  it("produces command and query test case categories", () => {
+    const cats = testCaseCategories("modules");
+    expect(cats).toHaveLength(2);
+    expect(cats[0].testDir).toBe("command");
+    expect(cats[1].testDir).toBe("query");
+  });
+});
+
+describe("buildCheckTargets", () => {
+  it("builds module check targets", () => {
+    const targets = buildCheckTargets({ modulesRoot: "modules" });
+    expect(targets).toHaveLength(5);
+    expect(targets.map((t) => t.schemaKey)).toEqual([
+      "feature",
+      "command",
+      "model",
+      "query",
+      "module",
+    ]);
+    expect(targets[0].glob).toBe("modules/[a-zA-Z]*/docs/features/*.md");
+  });
+
+  it("builds app check targets", () => {
+    const targets = buildCheckTargets({ appRoot: "apps" });
+    expect(targets).toHaveLength(6);
+    expect(targets.map((t) => t.schemaKey)).toContain("screen");
+    expect(targets.find((t) => t.schemaKey === "screen")!.glob).toBe(
+      "apps/[a-zA-Z]*/docs/screen/*.md",
+    );
+  });
+
+  it("builds both when both roots provided", () => {
+    const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: "apps" });
+    expect(targets).toHaveLength(11);
+  });
+});

package/src/commands/lib/discovery.ts

@@ -0,0 +1,106 @@
+import { MODULE_PATHS, APP_PATHS } from "./paths";
+
+export interface CategoryConfig {
+  name: string;
+  sourcePattern: string;
+  docPattern: string;
+  exclusions: RegExp[];
+}
+
+export interface TestCaseCategoryConfig {
+  name: string;
+  docPattern: string;
+  testDir: string;
+}
+
+export interface CheckTarget {
+  glob: string;
+  schemaKey: string;
+}
+
+export function moduleCategories(root: string): CategoryConfig[] {
+  return [
+    {
+      name: "command",
+      sourcePattern: `${root}/*/${MODULE_PATHS.commands}/*.ts`,
+      docPattern: `${root}/*/${MODULE_PATHS.docs.commands}/*.md`,
+      exclusions: [/\.test\.ts$/, /\.generated\.ts$/],
+    },
+    {
+      name: "model",
+      sourcePattern: `${root}/*/${MODULE_PATHS.db}/*.ts`,
+      docPattern: `${root}/*/${MODULE_PATHS.docs.models}/*.md`,
+      exclusions: [/\.test\.ts$/, /^index\.ts$/],
+    },
+    {
+      name: "query",
+      sourcePattern: `${root}/*/${MODULE_PATHS.queries}/*.ts`,
+      docPattern: `${root}/*/${MODULE_PATHS.docs.queries}/*.md`,
+      exclusions: [/\.test\.ts$/],
+    },
+  ];
+}
+
+export function appComposeCategories(root: string): CategoryConfig[] {
+  return [
+    {
+      name: "resolver",
+      sourcePattern: `${root}/*/backend/src/resolvers/*.ts`,
+      docPattern: `${root}/*/${APP_PATHS.docs.resolver}/*.md`,
+      exclusions: [/\.test\.ts$/, /^index\.ts$/],
+    },
+  ];
+}
+
+export function testCaseCategories(root: string): TestCaseCategoryConfig[] {
+  return [
+    {
+      name: "command-test-case",
+      docPattern: `${root}/*/${MODULE_PATHS.docs.commands}/*.md`,
+      testDir: MODULE_PATHS.commands,
+    },
+    {
+      name: "query-test-case",
+      docPattern: `${root}/*/${MODULE_PATHS.docs.queries}/*.md`,
+      testDir: MODULE_PATHS.queries,
+    },
+  ];
+}
+
+export function buildCheckTargets(config: {
+  modulesRoot?: string;
+  appRoot?: string;
+}): CheckTarget[] {
+  const targets: CheckTarget[] = [];
+
+  if (config.modulesRoot) {
+    const m = config.modulesRoot;
+    targets.push(
+      { glob: `${m}/[a-zA-Z]*/${MODULE_PATHS.docs.features}/*.md`, schemaKey: "feature" },
+      { glob: `${m}/[a-zA-Z]*/${MODULE_PATHS.docs.commands}/*.md`, schemaKey: "command" },
+      { glob: `${m}/[a-zA-Z]*/${MODULE_PATHS.docs.models}/*.md`, schemaKey: "model" },
+      { glob: `${m}/[a-zA-Z]*/${MODULE_PATHS.docs.queries}/*.md`, schemaKey: "query" },
+      { glob: `${m}/[a-zA-Z]*/README.md`, schemaKey: "module" },
+    );
+  }
+
+  if (config.appRoot) {
+    const a = config.appRoot;
+    targets.push(
+      { glob: `${a}/[a-zA-Z]*/README.md`, schemaKey: "app" },
+      { glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.actors}/*.md`, schemaKey: "actors" },
+      {
+        glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/README.md`,
+        schemaKey: "business-flow",
+      },
+      {
+        glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/${APP_PATHS.storySegment}/*.md`,
+        schemaKey: "story",
+      },
+      { glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.screen}/*.md`, schemaKey: "screen" },
+      { glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.resolver}/*.md`, schemaKey: "resolver" },
+    );
+  }
+
+  return targets;
+}

package/src/commands/lib/paths.ts

@@ -0,0 +1,22 @@
+export const MODULE_PATHS = {
+  commands: "command",
+  db: "db",
+  queries: "query",
+  docs: {
+    commands: "docs/commands",
+    models: "docs/models",
+    queries: "docs/queries",
+    features: "docs/features",
+  },
+} as const;
+
+export const APP_PATHS = {
+  // Subdirectory name within docs/business-flow/<flow>/story/
+  storySegment: "story",
+  docs: {
+    resolver: "docs/resolver",
+    actors: "docs/actors",
+    businessFlow: "docs/business-flow",
+    screen: "docs/screen",
+  },
+} as const;

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

@@ -0,0 +1,197 @@
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { runSourceSyncCheck } from "./sync-check-source";
+
+describe("runSourceSyncCheck", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sync-check-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns 0 for an empty directory with no sources or docs", async () => {
+    const result = await runSourceSyncCheck(
+      { modulesRoot: "modules", appRoot: "examples" },
+      tmpDir,
+    );
+    expect(result.exitCode).toBe(0);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it("reports missing doc when source exists without doc", async () => {
+    const srcDir = path.join(tmpDir, "modules", "foo", "command");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "createOrder.ts"), "export {}");
+
+    const result = await runSourceSyncCheck(
+      { modulesRoot: "modules", appRoot: "examples" },
+      tmpDir,
+    );
+    expect(result.exitCode).toBe(1);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ type: "missing-doc", expectedBasename: "createorder" }),
+    );
+  });
+
+  it("reports orphaned doc when doc exists without source", async () => {
+    const docDir = path.join(tmpDir, "modules", "foo", "docs", "commands");
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.writeFileSync(path.join(docDir, "createOrder.md"), "# CreateOrder");
+
+    const result = await runSourceSyncCheck(
+      { modulesRoot: "modules", appRoot: "examples" },
+      tmpDir,
+    );
+    expect(result.exitCode).toBe(1);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ type: "orphaned-doc", expectedBasename: "createorder" }),
+    );
+  });
+
+  it("returns 0 when source and doc match", 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(docDir, "createOrder.md"), "# CreateOrder");
+
+    const result = await runSourceSyncCheck(
+      { modulesRoot: "modules", appRoot: "examples" },
+      tmpDir,
+    );
+    expect(result.exitCode).toBe(0);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it("excludes test files from source matching", async () => {
+    const srcDir = path.join(tmpDir, "modules", "foo", "command");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "createOrder.test.ts"), "test()");
+
+    const result = await runSourceSyncCheck(
+      { modulesRoot: "modules", appRoot: "examples" },
+      tmpDir,
+    );
+    expect(result.exitCode).toBe(0);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it("uses custom modulesRoot to rewrite glob patterns", async () => {
+    const srcDir = path.join(tmpDir, "custom-mods", "foo", "command");
+    const docDir = path.join(tmpDir, "custom-mods", "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(docDir, "createOrder.md"), "# CreateOrder");
+
+    const result = await runSourceSyncCheck({ modulesRoot: "custom-mods" }, tmpDir);
+    expect(result.exitCode).toBe(0);
+    expect(result.summary.totalSources).toBe(1);
+  });
+
+  it("uses custom appRoot to rewrite glob patterns", async () => {
+    const srcDir = path.join(tmpDir, "apps", "app1", "backend", "src", "resolvers");
+    const docDir = path.join(tmpDir, "apps", "app1", "docs", "resolver");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "myResolver.ts"), "export {}");
+    fs.writeFileSync(path.join(docDir, "myResolver.md"), "# MyResolver");
+
+    const result = await runSourceSyncCheck({ appRoot: "apps" }, tmpDir);
+    expect(result.exitCode).toBe(0);
+    expect(result.summary.totalSources).toBe(1);
+  });
+
+  it("reports missing doc for query source without doc", async () => {
+    const srcDir = path.join(tmpDir, "modules", "foo", "query");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "convertAmount.ts"), "export {}");
+
+    const result = await runSourceSyncCheck(
+      { modulesRoot: "modules", appRoot: "examples" },
+      tmpDir,
+    );
+    expect(result.exitCode).toBe(1);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({
+        type: "missing-doc",
+        category: "query",
+        expectedBasename: "convertamount",
+      }),
+    );
+  });
+
+  it("returns 0 when query source and doc match", 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, "convertAmount.ts"), "export {}");
+    fs.writeFileSync(path.join(docDir, "convertAmount.md"), "# ConvertAmount");
+
+    const result = await runSourceSyncCheck(
+      { modulesRoot: "modules", appRoot: "examples" },
+      tmpDir,
+    );
+    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 runSourceSyncCheck(
+      { 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 runSourceSyncCheck(
+      { 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,
+      "examples",
+      "app1",
+      "backend",
+      "src",
+      "modules",
+      "m1",
+      "resolvers",
+    );
+    fs.mkdirSync(resolverSrcDir, { recursive: true });
+    fs.writeFileSync(path.join(resolverSrcDir, "myResolver.ts"), "export {}");
+
+    const result = await runSourceSyncCheck({ modulesRoot: "modules", appRoot: undefined }, tmpDir);
+    // Without appRoot, app-compose patterns are not checked
+    expect(result.exitCode).toBe(0);
+    expect(result.errors).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,100 @@
+import path from "node:path";
+import fg from "fast-glob";
+import { moduleCategories, appComposeCategories, type CategoryConfig } from "./discovery";
+
+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 shouldExclude(fileName: string, exclusions: RegExp[]): boolean {
+  return exclusions.some((pattern) => pattern.test(fileName));
+}
+
+export async function runSourceSyncCheck(
+  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;
+  }
+
+  return {
+    exitCode: errors.length > 0 ? 1 : 0,
+    errors,
+    summary: {
+      categoriesChecked: allCategories.length,
+      totalSources,
+      totalDocs,
+    },
+  };
+}