speckeeper 0.2.1 → 0.4.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,13 +1,13 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import chalk4 from 'chalk';
+import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { dirname, join, resolve } from 'path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { fileURLToPath } from 'url';
+import chalk4 from 'chalk';
 import { parse } from 'yaml';
 import 'crypto';
 import 'glob';
 import { z } from 'zod';
-import { fileURLToPath } from 'url';
 
 var defaultConfig = {
   srcDir: "src",
@@ -123,32 +123,36 @@ var RelationSchema = z.object({
 z.array(RelationSchema).optional();
 
 // src/core/model.ts
-var specStore = /* @__PURE__ */ new Map();
-function getSpecStore() {
-  return specStore;
-}
 var modelRegistry = /* @__PURE__ */ new Map();
-function registerModel(model) {
-  modelRegistry.set(model.id, model);
-}
 function getAllModels() {
   return Array.from(modelRegistry.values());
 }
-function registerModelsFromConfig(models) {
-  for (const model of models) {
-    if (model && typeof model === "object" && "id" in model && "schema" in model) {
-      registerModel(model);
+function buildRegistryFromConfig(specs) {
+  const registry = {};
+  if (!specs) return registry;
+  for (const entry of specs) {
+    if (!registry[entry.model.id]) {
+      registry[entry.model.id] = /* @__PURE__ */ new Map();
+    }
+    const map = registry[entry.model.id];
+    for (const spec of entry.data) {
+      map.set(spec.id, spec);
     }
   }
+  return registry;
 }
-function getSpecs(modelId) {
-  const map = specStore.get(modelId);
-  if (!map) return [];
-  return Array.from(map.values());
+function getSpecsFromConfig(specs, modelId) {
+  if (!specs) return [];
+  return specs.filter((e) => e.model.id === modelId).flatMap((e) => e.data);
 }
-function findModelTypeBySpecId(specId) {
-  for (const [modelId, map] of specStore) {
-    if (map.has(specId)) return modelId;
+function findModelTypeFromConfig(specs, specId) {
+  if (!specs) return null;
+  for (const entry of specs) {
+    for (const spec of entry.data) {
+      if (spec.id === specId) {
+        return entry.model.id;
+      }
+    }
   }
   return null;
 }
@@ -164,13 +168,11 @@ async function buildCommand(options) {
   console.log(chalk4.gray(`  Specs:   ${config.specsDir}/`));
   console.log("");
   try {
-    console.log(chalk4.blue("  Loading models..."));
-    registerModelsFromConfig(config.models || []);
-    console.log("");
+    const models = config.models || [];
+    const specs = config.specs;
     ensureDir(join(cwd, config.docsDir));
     ensureDir(join(cwd, config.specsDir));
     const files = [];
-    const models = getAllModels();
     if (models.length === 0) {
       console.log(chalk4.yellow("  No models registered. Add models to speckeeper.config.ts."));
       return;
@@ -184,8 +186,8 @@ async function buildCommand(options) {
         }
         continue;
       }
-      const specs = getSpecs(model.id);
-      if (specs.length === 0) {
+      const modelSpecs = getSpecsFromConfig(specs, model.id);
+      if (modelSpecs.length === 0) {
         if (options.verbose) {
           console.log(chalk4.gray(`    ${model.name}: no specs found`));
         }
@@ -195,7 +197,7 @@ async function buildCommand(options) {
         const outputDir = exporter.outputDir ? join(cwd, config.docsDir, exporter.outputDir) : join(cwd, config.docsDir);
         ensureDir(outputDir);
         if (exporter.single) {
-          for (const spec of specs) {
+          for (const spec of modelSpecs) {
             const content = exporter.single(spec);
             const filename = model.getFilename(spec, exporter.format) || spec.id;
             files.push({
@@ -205,7 +207,7 @@ async function buildCommand(options) {
           }
         }
         if (exporter.index) {
-          const indexContent = exporter.index(specs);
+          const indexContent = exporter.index(modelSpecs);
           files.push({
             path: join(outputDir, "index.md"),
             content: indexContent
@@ -241,13 +243,12 @@ async function lintCommand(options) {
   }
   console.log("");
   try {
-    console.log(chalk4.blue("  Loading models..."));
-    registerModelsFromConfig(config.models || []);
-    const models = getAllModels();
+    const models = config.models || [];
+    const specs = config.specs;
     console.log(chalk4.gray(`  Loaded: ${models.length} models`));
     console.log("");
     console.log(chalk4.blue("  Running lint checks..."));
-    const result = runModelLint(options);
+    const result = runModelLint(models, specs, options);
     console.log("");
     outputLintResults(result, options);
     if (result.errors > 0) {
@@ -258,13 +259,12 @@ async function lintCommand(options) {
     process.exit(1);
   }
 }
-function runModelLint(options) {
+function runModelLint(models, specs, options) {
   const issues = [];
-  const models = getAllModels();
   for (const model of models) {
-    const specs = getSpecs(model.id);
-    if (specs.length === 0) continue;
-    const lintResults = model.lintAll(specs);
+    const modelSpecs = getSpecsFromConfig(specs, model.id);
+    if (modelSpecs.length === 0) continue;
+    const lintResults = model.lintAll(modelSpecs);
     for (const result of lintResults) {
       issues.push({
         rule: result.ruleId,
@@ -323,18 +323,17 @@ async function driftCommand(options) {
   console.log(chalk4.gray(`  Docs:   ${config.docsDir}/`));
   console.log("");
   try {
-    console.log(chalk4.blue("  Loading models..."));
-    registerModelsFromConfig(config.models || []);
+    const models = config.models || [];
+    const specs = config.specs;
     const results = [];
-    const models = getAllModels();
     for (const model of models) {
-      const specs = getSpecs(model.id);
-      if (specs.length === 0) continue;
+      const modelSpecs = getSpecsFromConfig(specs, model.id);
+      if (modelSpecs.length === 0) continue;
       for (const exporter of model.getExporters()) {
         if (exporter.format !== "markdown") continue;
         const outputDir = exporter.outputDir ? join(cwd, config.docsDir, exporter.outputDir) : join(cwd, config.docsDir);
         if (exporter.single) {
-          for (const spec of specs) {
+          for (const spec of modelSpecs) {
             const filename = model.getFilename(spec, "markdown") || spec.id;
             const filePath = join(outputDir, `${filename}.md`);
             if (!existsSync(filePath)) {
@@ -355,7 +354,7 @@ async function driftCommand(options) {
           if (!existsSync(indexPath)) {
             results.push({ file: indexPath, status: "missing" });
           } else {
-            const expected = exporter.index(specs);
+            const expected = exporter.index(modelSpecs);
             const actual = readFileSync(indexPath, "utf-8");
             if (normalizeContent(expected) !== normalizeContent(actual)) {
               results.push({ file: indexPath, status: "drifted" });
@@ -414,17 +413,16 @@ async function checkCommand(type, options) {
   console.log(chalk4.gray(`  Type:   ${checkType}`));
   console.log("");
   try {
-    console.log(chalk4.blue("  Loading models..."));
-    registerModelsFromConfig(config.models || []);
-    const results = [];
-    const models = getAllModels();
+    const models = config.models || [];
+    const specs = config.specs;
     if (options.verbose) {
       console.log(chalk4.gray(`  Registered models: ${models.map((m) => m.id).join(", ")}`));
     }
+    const results = [];
     for (const model of models) {
-      const specs = getSpecs(model.id);
-      if (specs.length === 0) continue;
-      for (const spec of specs) {
+      const modelSpecs = getSpecsFromConfig(specs, model.id);
+      if (modelSpecs.length === 0) continue;
+      for (const spec of modelSpecs) {
         const sourcePath = model.getExternalSourcePath(spec);
         if (!sourcePath) continue;
         const fullPath = join(cwd, sourcePath);
@@ -458,7 +456,7 @@ async function checkCommand(type, options) {
     if (options.coverage) {
       console.log("");
       console.log(chalk4.blue("  Coverage checks..."));
-      const coverageResults = runAllCoverageChecks();
+      const coverageResults = runAllCoverageChecks(models, specs);
       if (coverageResults.length > 0) {
         outputAllCoverageResults(coverageResults);
         for (const check of coverageResults) {
@@ -466,7 +464,6 @@ async function checkCommand(type, options) {
             results.push({
               type: `coverage-${check.modelId}`,
               success: check.result.coveragePercent >= 80,
-              // fail if below 80%
               issues: check.result.uncoveredItems.slice(0, 10).map((item) => ({
                 severity: "warning",
                 message: `[${check.modelName}\u2192${check.targetModel}] '${item.id}'${item.sourceId ? ` (${item.sourceId})` : ""} not covered`,
@@ -528,15 +525,14 @@ function outputCheckResults(results) {
   console.log("");
   console.log(chalk4.gray(`  Summary: ${totalErrors} errors, ${totalWarnings} warnings`));
 }
-function runAllCoverageChecks() {
-  const models = getAllModels();
+function runAllCoverageChecks(models, specs) {
   const results = [];
-  const registry = Object.fromEntries(getSpecStore());
+  const registry = buildRegistryFromConfig(specs);
   for (const model of models) {
     const checker = model.getCoverageChecker();
     if (checker) {
-      const specs = getSpecs(model.id);
-      const result = model.checkCoverage(specs, registry);
+      const modelSpecs = getSpecsFromConfig(specs, model.id);
+      const result = model.checkCoverage(modelSpecs, registry);
       if (result) {
         results.push({
           modelId: model.id,
@@ -652,28 +648,27 @@ async function impactCommand(targetId, options) {
   console.log(chalk4.gray(`  Depth:  ${maxDepth}`));
   console.log("");
   try {
-    console.log(chalk4.blue("  Loading models..."));
-    registerModelsFromConfig(config.models || []);
-    const store = getSpecStore();
-    const targetType = findModelTypeBySpecId(targetId);
+    const specs = config.specs;
+    const registry = buildRegistryFromConfig(specs);
+    const targetType = findModelTypeFromConfig(specs, targetId);
     if (!targetType) {
       console.error(chalk4.red(`  Error: Target '${targetId}' not found`));
       process.exit(1);
     }
     console.log(chalk4.blue("  Analyzing impact..."));
-    const result = analyzeImpact(store, targetId, targetType, maxDepth);
+    const result = analyzeImpact(registry, targetId, targetType, maxDepth);
     outputImpactResults(result, options);
   } catch (error) {
     console.error(chalk4.red("Impact analysis failed:"), error);
     process.exit(1);
   }
 }
-function analyzeImpact(store, targetId, targetType, maxDepth) {
+function analyzeImpact(registry, targetId, targetType, maxDepth) {
   const impactedNodes = [];
   const visited = /* @__PURE__ */ new Set([targetId]);
   function findReferences(id, depth) {
     if (depth > maxDepth) return;
-    for (const [type, map] of store) {
+    for (const [type, map] of Object.entries(registry)) {
       for (const [itemId, item] of map) {
         if (visited.has(itemId)) continue;
         const itemStr = JSON.stringify(item);
@@ -772,14 +767,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"));
   }
 }
@@ -2271,14 +2266,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`,
@@ -2288,6 +2286,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();
@@ -2301,6 +2327,7 @@ function generateAllModelFiles(speckeeperNodes, resolvedEdges) {
     files.push(generateModelFile(node));
     files.push(generateSpecDataFile(node));
   }
+  files.push(generateDesignIndex(speckeeperNodes));
   return files;
 }
 
@@ -2499,8 +2526,17 @@ function printDiagnostics(diagnostics) {
 }
 
 // src/cli/index.ts
+function getVersion() {
+  try {
+    const __dirname2 = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(__dirname2, "..", "package.json"), "utf-8"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
 var program = new Command();
-program.name("speckeeper").description("Requirements and design management framework with TypeScript DSL").version("0.1.0");
+program.name("speckeeper").description("Requirements and design management framework with TypeScript DSL").version(getVersion());
 program.command("build").description("Generate docs/ and specs/ from TypeScript models").option("-c, --config <path>", "Path to config file").option("-o, --output <path>", "Base output directory path", ".").option("-f, --format <format>", "Output format: markdown, json, both", "both").option("-w, --watch", "Watch for changes and auto-regenerate").option("-v, --verbose", "Show detailed output").action(buildCommand);
 program.command("lint").description("Check design integrity (ID duplicates, references, layer violations, etc.)").option("-c, --config <path>", "Path to config file").option("-p, --phase <phase>", "Phase gate to check against (REQ, HLD, LLD, OPS)").option("-s, --strict", "Treat warnings as errors").option("--fix", "Attempt to fix auto-fixable issues").option("-f, --format <format>", "Output format: text, json, github", "text").action(lintCommand);
 program.command("drift").description("Check if generated files have been manually edited").option("-c, --config <path>", "Path to config file").option("-u, --update", "Auto-update if differences are found").option("-f, --format <format>", "Output format: text, json, diff", "text").action(driftCommand);