@tailor-platform/erp-kit 0.3.0 → 0.4.1

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,
+    },
+  };
+}

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;
+}