speckeeper 0.2.0 → 0.3.0

package/README.md

@@ -69,21 +69,23 @@ npx speckeeper scaffold --source requirements.md
 
 This generates:
 - `design/_models/` — Model classes with Zod schemas, lint rules, and exporters derived from your flowchart
+- `design/*.ts` — Spec data files using `defineSpecs()` for each model
+- `design/index.ts` — Entry point that aggregates all spec modules via `mergeSpecs()`
 - `design/_checkers/` — External checker skeletons for `implements` edges (e.g. OpenAPI, DDL)
-- `design/_models/index.ts` — Re-exports and `allModels` array
-- `speckeeper.config.ts` — Configuration wired to the generated models
 
 See [Scaffold Mermaid Specification](./docs/scaffold-mermaid-spec.md) for the full input format and built-in node mappings.
 
 ### 3. Fill in your specifications
 
-Edit files in `design/` to add your actual specification data:
+Edit spec data files in `design/` to add your actual specification data. Each file uses `defineSpecs()` to pair Model instances with data:
 
 ```typescript
 // design/requirements.ts
-import type { Requirement } from 'speckeeper';
+import { defineSpecs } from 'speckeeper';
+import type { Requirement } from './_models/requirement';
+import { FunctionalRequirementModel } from './_models/requirement';
 
-export const requirements: Requirement[] = [
+const requirements: Requirement[] = [
   {
     id: 'FR-001',
     name: 'User Authentication',
@@ -96,8 +98,14 @@ export const requirements: Requirement[] = [
     ],
   },
 ];
+
+export default defineSpecs(
+  [FunctionalRequirementModel.instance, requirements],
+);
 ```
 
+`design/index.ts` aggregates all spec files, and `speckeeper.config.ts` imports the result — no manual wiring needed beyond adding your spec file to `design/index.ts`.
+
 ### 4. Run validation
 
 ```bash

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import chalk4 from 'chalk';
-import { dirname, relative, join, resolve, extname, basename } from 'path';
+import { dirname, join, resolve } from 'path';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { parse } from 'yaml';
 import 'crypto';
@@ -127,9 +127,6 @@ var specStore = /* @__PURE__ */ new Map();
 function getSpecStore() {
   return specStore;
 }
-function resetSpecStore() {
-  specStore.clear();
-}
 var modelRegistry = /* @__PURE__ */ new Map();
 function registerModel(model) {
   modelRegistry.set(model.id, model);
@@ -137,103 +134,30 @@ function registerModel(model) {
 function getAllModels() {
   return Array.from(modelRegistry.values());
 }
-function clearModelRegistry() {
-  modelRegistry.clear();
-}
-function isModelInstance(value) {
-  if (!value || typeof value !== "object") return false;
-  const obj = value;
-  return typeof obj.id === "string" && typeof obj.name === "string" && typeof obj.idPrefix === "string" && obj.schema !== void 0 && typeof obj.validate === "function" && typeof obj.lint === "function";
-}
-function registerExportedModelInstances(module) {
-  for (const [, exportValue] of Object.entries(module)) {
-    if (!exportValue || typeof exportValue !== "object") continue;
-    if (isModelInstance(exportValue)) {
-      registerModel(exportValue);
-    }
-  }
-}
-async function loadModelsFromDirectory(dirPath, options = {}) {
-  const loadedFiles = [];
-  if (!existsSync(dirPath)) {
-    return loadedFiles;
-  }
-  const entries = readdirSync(dirPath);
-  for (const entry of entries) {
-    const fullPath = join(dirPath, entry);
-    const stat = statSync(fullPath);
-    if (stat.isDirectory() && options.recursive) {
-      const subFiles = await loadModelsFromDirectory(fullPath, options);
-      loadedFiles.push(...subFiles);
-    } else if (stat.isFile()) {
-      const ext = extname(entry);
-      if ([".ts", ".js", ".mts", ".mjs"].includes(ext) && !entry.endsWith(".d.ts")) {
-        if (basename(entry, ext) === "index") {
-          continue;
-        }
-        try {
-          const module = await import(fullPath);
-          loadedFiles.push(fullPath);
-          registerExportedModelInstances(module);
-        } catch (error) {
-          console.error(`Failed to load from ${fullPath}:`, error);
-        }
-      }
-    }
-  }
-  return loadedFiles;
-}
-async function loadAllModels(config, cwd = process.cwd()) {
-  resetSpecStore();
-  clearModelRegistry();
-  const loadedFiles = [];
-  const errors = [];
-  if (config.models && Array.isArray(config.models)) {
-    for (const model of config.models) {
-      if (isModelInstance(model)) {
-        registerModel(model);
-      }
-    }
-  }
-  const designDir = resolve(cwd, config.designDir || "design");
-  const modelDirs = [
-    { path: join(designDir, "_models") },
-    { path: join(designDir, "requirements") },
-    { path: join(designDir, "usecases") },
-    { path: join(designDir, "architecture") },
-    { path: join(designDir, "data-model") },
-    { path: join(designDir, "screens") },
-    { path: join(designDir, "flows") },
-    { path: join(designDir, "glossary") },
-    { path: designDir }
-  ];
-  for (const { path: dirPath } of modelDirs) {
-    if (!existsSync(dirPath)) {
-      continue;
-    }
-    try {
-      const files = await loadModelsFromDirectory(dirPath, { recursive: true });
-      loadedFiles.push(...files);
-    } catch (error) {
-      errors.push({ file: dirPath, error });
+function registerModelsFromConfig(models) {
+  for (const model of models) {
+    if (model && typeof model === "object" && "id" in model && "schema" in model) {
+      registerModel(model);
     }
   }
-  const store = getSpecStore();
-  const registry = {};
-  for (const [modelId, specMap] of store) {
-    registry[modelId] = specMap;
-  }
-  return {
-    registry,
-    loadedFiles,
-    errors
-  };
 }
-function getSpecsFromRegistry(registry, modelId) {
-  const map = registry[modelId];
+function getSpecs(modelId) {
+  const map = specStore.get(modelId);
   if (!map) return [];
   return Array.from(map.values());
 }
+function findModelTypeBySpecId(specId) {
+  for (const [modelId, map] of specStore) {
+    if (map.has(specId)) return modelId;
+  }
+  return null;
+}
+function registerSpecsFromConfig(specs) {
+  if (!specs) return;
+  for (const entry of specs) {
+    entry.model.register(entry.data);
+  }
+}
 
 // src/cli/build.ts
 async function buildCommand(options) {
@@ -247,14 +171,8 @@ async function buildCommand(options) {
   console.log("");
   try {
     console.log(chalk4.blue("  Loading models..."));
-    const { registry, loadedFiles, errors: loadErrors } = await loadAllModels(config, cwd);
-    if (loadErrors.length > 0) {
-      console.log(chalk4.yellow(`  \u26A0 ${loadErrors.length} file(s) failed to load`));
-      for (const { file, error } of loadErrors) {
-        console.log(chalk4.yellow(`    - ${relative(cwd, file)}: ${error}`));
-      }
-    }
-    console.log(chalk4.gray(`  Loaded: ${loadedFiles.length} files`));
+    registerModelsFromConfig(config.models || []);
+    registerSpecsFromConfig(config.specs);
     console.log("");
     ensureDir(join(cwd, config.docsDir));
     ensureDir(join(cwd, config.specsDir));
@@ -273,7 +191,7 @@ async function buildCommand(options) {
         }
         continue;
       }
-      const specs = getSpecsFromRegistry(registry, model.id);
+      const specs = getSpecs(model.id);
       if (specs.length === 0) {
         if (options.verbose) {
           console.log(chalk4.gray(`    ${model.name}: no specs found`));
@@ -323,7 +241,6 @@ async function buildCommand(options) {
 async function lintCommand(options) {
   console.log(chalk4.blue("speckeeper lint"));
   console.log("");
-  const cwd = process.cwd();
   const config = await loadConfig(options.config);
   console.log(chalk4.gray(`  Design: ${config.designDir || "design"}/`));
   if (options.phase) {
@@ -332,17 +249,13 @@ async function lintCommand(options) {
   console.log("");
   try {
     console.log(chalk4.blue("  Loading models..."));
-    const { registry, loadedFiles, errors: loadErrors } = await loadAllModels(config, cwd);
-    if (loadErrors.length > 0) {
-      console.log(chalk4.yellow(`  \u26A0 ${loadErrors.length} file(s) failed to load`));
-      for (const { file, error } of loadErrors) {
-        console.log(chalk4.yellow(`    - ${relative(cwd, file)}: ${error}`));
-      }
-    }
-    console.log(chalk4.gray(`  Loaded: ${loadedFiles.length} files`));
+    registerModelsFromConfig(config.models || []);
+    registerSpecsFromConfig(config.specs);
+    const models = getAllModels();
+    console.log(chalk4.gray(`  Loaded: ${models.length} models`));
     console.log("");
     console.log(chalk4.blue("  Running lint checks..."));
-    const result = runModelLint(registry, options);
+    const result = runModelLint(options);
     console.log("");
     outputLintResults(result, options);
     if (result.errors > 0) {
@@ -353,11 +266,11 @@ async function lintCommand(options) {
     process.exit(1);
   }
 }
-function runModelLint(registry, options) {
+function runModelLint(options) {
   const issues = [];
   const models = getAllModels();
   for (const model of models) {
-    const specs = getSpecsFromRegistry(registry, model.id);
+    const specs = getSpecs(model.id);
     if (specs.length === 0) continue;
     const lintResults = model.lintAll(specs);
     for (const result of lintResults) {
@@ -419,11 +332,12 @@ async function driftCommand(options) {
   console.log("");
   try {
     console.log(chalk4.blue("  Loading models..."));
-    const { registry } = await loadAllModels(config, cwd);
+    registerModelsFromConfig(config.models || []);
+    registerSpecsFromConfig(config.specs);
     const results = [];
     const models = getAllModels();
     for (const model of models) {
-      const specs = getSpecsFromRegistry(registry, model.id);
+      const specs = getSpecs(model.id);
       if (specs.length === 0) continue;
       for (const exporter of model.getExporters()) {
         if (exporter.format !== "markdown") continue;
@@ -510,14 +424,15 @@ async function checkCommand(type, options) {
   console.log("");
   try {
     console.log(chalk4.blue("  Loading models..."));
-    const { registry } = await loadAllModels(config, cwd);
+    registerModelsFromConfig(config.models || []);
+    registerSpecsFromConfig(config.specs);
     const results = [];
     const models = getAllModels();
     if (options.verbose) {
       console.log(chalk4.gray(`  Registered models: ${models.map((m) => m.id).join(", ")}`));
     }
     for (const model of models) {
-      const specs = getSpecsFromRegistry(registry, model.id);
+      const specs = getSpecs(model.id);
       if (specs.length === 0) continue;
       for (const spec of specs) {
         const sourcePath = model.getExternalSourcePath(spec);
@@ -553,7 +468,7 @@ async function checkCommand(type, options) {
     if (options.coverage) {
       console.log("");
       console.log(chalk4.blue("  Coverage checks..."));
-      const coverageResults = runAllCoverageChecks(registry);
+      const coverageResults = runAllCoverageChecks();
       if (coverageResults.length > 0) {
         outputAllCoverageResults(coverageResults);
         for (const check of coverageResults) {
@@ -623,13 +538,14 @@ function outputCheckResults(results) {
   console.log("");
   console.log(chalk4.gray(`  Summary: ${totalErrors} errors, ${totalWarnings} warnings`));
 }
-function runAllCoverageChecks(registry) {
+function runAllCoverageChecks() {
   const models = getAllModels();
   const results = [];
+  const registry = Object.fromEntries(getSpecStore());
   for (const model of models) {
     const checker = model.getCoverageChecker();
     if (checker) {
-      const specs = getSpecsFromRegistry(registry, model.id);
+      const specs = getSpecs(model.id);
       const result = model.checkCoverage(specs, registry);
       if (result) {
         results.push({
@@ -740,7 +656,6 @@ async function impactCommand(targetId, options) {
     console.log(chalk4.gray("  Usage: speckeeper impact <id>"));
     process.exit(1);
   }
-  const cwd = process.cwd();
   const config = await loadConfig(options.config);
   const maxDepth = options.depth ? parseInt(options.depth, 10) : 3;
   console.log(chalk4.gray(`  Target: ${targetId}`));
@@ -748,35 +663,28 @@ async function impactCommand(targetId, options) {
   console.log("");
   try {
     console.log(chalk4.blue("  Loading models..."));
-    const { registry } = await loadAllModels(config, cwd);
-    const target = findById(registry, targetId);
-    if (!target) {
+    registerModelsFromConfig(config.models || []);
+    registerSpecsFromConfig(config.specs);
+    const store = getSpecStore();
+    const targetType = findModelTypeBySpecId(targetId);
+    if (!targetType) {
       console.error(chalk4.red(`  Error: Target '${targetId}' not found`));
       process.exit(1);
     }
     console.log(chalk4.blue("  Analyzing impact..."));
-    const result = analyzeImpact(registry, targetId, target.type, maxDepth);
+    const result = analyzeImpact(store, targetId, targetType, maxDepth);
     outputImpactResults(result, options);
   } catch (error) {
     console.error(chalk4.red("Impact analysis failed:"), error);
     process.exit(1);
   }
 }
-function findById(registry, id) {
-  for (const [type, map] of Object.entries(registry)) {
-    if (map instanceof Map && map.has(id)) {
-      return { type, data: map.get(id) };
-    }
-  }
-  return null;
-}
-function analyzeImpact(registry, targetId, targetType, maxDepth) {
+function analyzeImpact(store, targetId, targetType, maxDepth) {
   const impactedNodes = [];
   const visited = /* @__PURE__ */ new Set([targetId]);
   function findReferences(id, depth) {
     if (depth > maxDepth) return;
-    for (const [type, map] of Object.entries(registry)) {
-      if (!(map instanceof Map)) continue;
+    for (const [type, map] of store) {
       for (const [itemId, item] of map) {
         if (visited.has(itemId)) continue;
         const itemStr = JSON.stringify(item);
@@ -875,14 +783,14 @@ async function runInit(options = {}) {
   console.log("  Next steps:");
   if (packageJsonCreated) {
     console.log(chalk4.gray("    1. Run `npm install` to install dependencies"));
-    console.log(chalk4.gray("    2. Edit design/_models/ to customize your models"));
-    console.log(chalk4.gray("    3. Add specifications in design/"));
+    console.log(chalk4.gray("    2. Add spec data in design/*.ts using defineSpecs()"));
+    console.log(chalk4.gray("    3. Import new spec files in design/index.ts"));
     console.log(chalk4.gray("    4. Run `npx speckeeper lint` to validate"));
   } else {
     console.log(chalk4.gray("    1. Add speckeeper and zod to your package.json dependencies"));
     console.log(chalk4.gray('    2. Ensure "type": "module" is set in package.json'));
-    console.log(chalk4.gray("    3. Edit design/_models/ to customize your models"));
-    console.log(chalk4.gray("    4. Add specifications in design/"));
+    console.log(chalk4.gray("    3. Add spec data in design/*.ts using defineSpecs()"));
+    console.log(chalk4.gray("    4. Import new spec files in design/index.ts"));
     console.log(chalk4.gray("    5. Run `npx speckeeper lint` to validate"));
   }
 }
@@ -2374,14 +2282,17 @@ function generateSpecDataFile(node) {
  *
  * Generated by speckeeper scaffold \u2014 add your specs below.
  */
+import { defineSpecs } from 'speckeeper';
 import type { ${typeName} } from './_models/${fileName}';
 import { ${className} } from './_models/${fileName}';
 
-export const ${varName}: ${typeName}[] = [
+const ${varName}: ${typeName}[] = [
   // { id: '${templateInfo.defaultIdPrefix}-001', name: '...', description: '...' },
 ];
 
-${className}.instance.register(${varName});
+export default defineSpecs(
+  [${className}.instance, ${varName}],
+);
 `;
   return {
     relativePath: `${fileName}.ts`,
@@ -2391,6 +2302,34 @@ ${className}.instance.register(${varName});
 function toCamelCase3(pascalCase) {
   return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
 }
+function generateDesignIndex(speckeeperNodes) {
+  const generated = /* @__PURE__ */ new Set();
+  const specFiles = [];
+  for (const node of speckeeperNodes) {
+    const templateInfo = resolveModelTemplate(node.id);
+    const key = templateInfo.templateName === "base" ? `base:${node.id}` : templateInfo.templateName;
+    if (generated.has(key)) continue;
+    generated.add(key);
+    specFiles.push({
+      varName: toCamelCase3(templateInfo.modelName),
+      fileName: templateInfo.fileName
+    });
+  }
+  const imports = specFiles.map((f) => `import ${f.varName} from './${f.fileName}';`).join("\n");
+  const args = specFiles.map((f) => f.varName).join(", ");
+  const content = `/**
+ * Design entry point \u2014 generated by speckeeper scaffold
+ */
+import { mergeSpecs } from 'speckeeper';
+${imports}
+
+export default mergeSpecs(${args});
+`;
+  return {
+    relativePath: "index.ts",
+    content
+  };
+}
 function generateAllModelFiles(speckeeperNodes, resolvedEdges) {
   const files = [];
   const generated = /* @__PURE__ */ new Set();
@@ -2404,6 +2343,7 @@ function generateAllModelFiles(speckeeperNodes, resolvedEdges) {
     files.push(generateModelFile(node));
     files.push(generateSpecDataFile(node));
   }
+  files.push(generateDesignIndex(speckeeperNodes));
   return files;
 }