speckeeper 0.7.1 → 0.8.0

package/README.md

@@ -152,7 +152,7 @@ npx speckeeper impact FR-001
 | `speckeeper check` | Verify consistency with external SSOT |
 | `speckeeper check test --coverage` | Verify test coverage for requirements |
 | `speckeeper scaffold` | Generate model skeletons from a mermaid flowchart |
-| `speckeeper drift` | Detect manual edits to generated `docs/` files |
+| `speckeeper drift` | Detect manual edits to generated `specs/` files |
 | `speckeeper impact <id>` | Analyze change impact for a specific element |
 
 **Note**: `speckeeper build` generates machine-readable `specs/` output. For human-readable docs (`docs/`), use [embedoc](https://www.npmjs.com/package/embedoc) or similar tools with the model rendering API.

package/dist/cli.js

@@ -196,9 +196,7 @@ async function buildCommand(options) {
       }
       for (const exporter of exporters) {
         const outputDir = exporter.outputDir ? join(cwd, config.docsDir, exporter.outputDir) : join(cwd, config.docsDir);
-        if (exporter.single) {
-          ensureDir(outputDir);
-        }
+        ensureDir(outputDir);
         if (exporter.single) {
           for (const spec of modelSpecs) {
             const content = exporter.single(spec);
@@ -211,12 +209,8 @@ async function buildCommand(options) {
         }
         if (exporter.index) {
           const indexContent = exporter.index(modelSpecs);
-          const indexPath = exporter.outputFile ? join(cwd, config.docsDir, exporter.outputFile) : join(outputDir, "index.md");
-          if (!exporter.outputFile) {
-            ensureDir(outputDir);
-          }
           files.push({
-            path: indexPath,
+            path: join(outputDir, "index.md"),
             content: indexContent
           });
         }
@@ -357,7 +351,7 @@ async function driftCommand(options) {
           }
         }
         if (exporter.index) {
-          const indexPath = exporter.outputFile ? join(cwd, config.docsDir, exporter.outputFile) : join(outputDir, "index.md");
+          const indexPath = join(outputDir, "index.md");
           if (!existsSync(indexPath)) {
             results.push({ file: indexPath, status: "missing" });
           } else {
@@ -1270,10 +1264,56 @@ function toKebabCase(s) {
   return s.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase();
 }
 
+// src/scaffold/artifact-defaults.ts
+var SPECIALIZED_CHECKER_MAP = {
+  openapi: "externalOpenAPIChecker",
+  sqlschema: "externalSqlSchemaChecker"
+};
+function generateCheckerCode(bindings, modelName) {
+  const dslImports = /* @__PURE__ */ new Set(["annotationChecker"]);
+  for (const b of bindings) {
+    const specialized = SPECIALIZED_CHECKER_MAP[b.targetClass];
+    if (specialized) dslImports.add(specialized);
+  }
+  const checks = bindings.map((b) => {
+    const specialized = SPECIALIZED_CHECKER_MAP[b.targetClass];
+    const artifact = `'${b.targetClass}'`;
+    const relationType = `'${b.edgeType}'`;
+    if (specialized) {
+      return `{ artifact: ${artifact}, relationType: ${relationType}, checker: ${specialized}() }`;
+    }
+    return `{ artifact: ${artifact}, relationType: ${relationType} }`;
+  });
+  let config;
+  if (checks.length === 1) {
+    config = checks[0];
+  } else {
+    config = `{
+    checks: [
+      ${checks.join(",\n      ")}
+    ],
+  }`;
+  }
+  const code = `protected externalChecker = annotationChecker<${modelName}>(${config});`;
+  return {
+    code,
+    dslImports: Array.from(dslImports)
+  };
+}
+
 // src/scaffold/templates/base.ts
 function generateBaseModel(params) {
   const schemaName = `${params.modelName}Schema`;
   const className = `${params.modelName}Model`;
+  const hasCheckerBindings = params.checkerBindings && params.checkerBindings.length > 0;
+  const checkerGen = hasCheckerBindings ? generateCheckerCode(params.checkerBindings, params.modelName) : null;
+  const dslImportItems = ["requireField"];
+  if (checkerGen) {
+    dslImportItems.push(...checkerGen.dslImports);
+  }
+  const dslImportLine = `import { ${dslImportItems.join(", ")} } from 'speckeeper/dsl';`;
+  const externalCheckerLine = checkerGen ? `
+  ${checkerGen.code}` : "";
   return `/**
  * ${params.modelName} Model Definition
  *
@@ -1282,7 +1322,7 @@ function generateBaseModel(params) {
 import { z } from 'zod';
 import { Model, RelationSchema } from 'speckeeper';
 import type { LintRule, Exporter, ModelLevel } from 'speckeeper';
-import { requireField } from 'speckeeper/dsl';
+${dslImportLine}
 
 // =============================================================================
 // Schema Definition
@@ -1318,7 +1358,7 @@ class ${className} extends Model<typeof ${schemaName}> {
     requireField<${params.modelName}>('description'),
   ];
 
-  protected exporters: Exporter<${params.modelName}>[] = [];
+  protected exporters: Exporter<${params.modelName}>[] = [];${externalCheckerLine}
 }
 
 export { ${className} };
@@ -1350,51 +1390,22 @@ function resolveCheckerBindings(_nodeId, outgoingEdges, nodes, speckeeperClassNa
 function generateModelFile(node, _incomingEdges, outgoingEdges, allNodes) {
   const templateInfo = resolveModelTemplate(node.id, node.classes, node.subgraph);
   const templateFn = MODEL_TEMPLATE_FUNCTIONS[templateInfo.templateName];
+  const bindings = allNodes ? resolveCheckerBindings(node.id, outgoingEdges, allNodes, "speckeeper") : [];
+  const checkerBindings = bindings.length > 0 ? bindings.map((b) => ({ edgeType: b.edgeType, targetClass: b.targetClass })) : void 0;
   const params = {
     modelId: templateInfo.fileName,
     modelName: templateInfo.modelName,
     idPrefix: templateInfo.defaultIdPrefix,
     level: templateInfo.defaultLevel,
-    description: node.label ?? node.id
+    description: node.label ?? node.id,
+    checkerBindings
   };
-  let content;
-  if (!templateFn) {
-    content = MODEL_TEMPLATE_FUNCTIONS["base"](params);
-  } else {
-    content = templateFn(params);
-  }
-  const bindings = allNodes ? resolveCheckerBindings(node.id, outgoingEdges, allNodes, "speckeeper") : [];
-  if (bindings.length > 0) {
-    content += generateCheckerBindingComment(bindings);
-  }
+  const content = !templateFn ? MODEL_TEMPLATE_FUNCTIONS["base"](params) : templateFn(params);
   return {
     relativePath: `_models/${templateInfo.fileName}.ts`,
     content
   };
 }
-var CHECKER_FACTORY_MAP = {
-  openapi: "externalOpenAPIChecker",
-  sqlschema: "externalSqlSchemaChecker",
-  test: "testChecker"
-};
-function generateCheckerBindingComment(bindings) {
-  const lines = [
-    "",
-    "// =============================================================================",
-    "// Checker Bindings (auto-detected from flowchart edges)",
-    "// =============================================================================",
-    "//",
-    "// Import and assign to externalChecker in the Model class:",
-    "// import { " + bindings.map((b) => CHECKER_FACTORY_MAP[b.targetClass] ?? "externalSsotChecker").join(", ") + " } from 'speckeeper/dsl';",
-    "//"
-  ];
-  for (const b of bindings) {
-    const factory = CHECKER_FACTORY_MAP[b.targetClass] ?? `/* custom checker for '${b.targetClass}' */`;
-    lines.push(`// ${b.edgeType} \u2192 ${b.targetNodeId} (class: ${b.targetClass}): ${factory}`);
-  }
-  lines.push("");
-  return lines.join("\n");
-}
 function generateSpecDataFile(node) {
   const templateInfo = resolveModelTemplate(node.id, node.classes, node.subgraph);
   const className = `${templateInfo.modelName}Model`;
@@ -1637,7 +1648,7 @@ var program = new Command();
 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").option("--fail-on-drift", "Exit with code 1 if drift is detected (for CI)").action(driftCommand);
+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);
 program.command("check").description("Check external SSOT conformance (including custom models)").argument("[type]", "Type of check: external-ssot, openapi, ddl, iac, custom, all, test").option("-c, --config <path>", "Path to config file").option("--strict", "Treat warnings as errors").option("-v, --verbose", "Show detailed output").option("--coverage", "Check if all testable acceptance criteria are covered by TestRefs").action(checkCommand);
 program.command("new").description("Create a new element with auto-generated ID").argument("<type>", "Type: requirement, usecase, entity, component, screen, flow, error-case, term").option("-k, --kind <kind>", "Sub-kind (e.g., functional, non-functional for requirements)").option("-n, --name <name>", "Name of the element").option("-o, --output <path>", "Output directory path").option("-t, --template <path>", "Path to template file").action(newCommand);
 program.command("impact").description("Analyze impact of changes to an ID").argument("<id>", "ID to analyze (e.g., REQ-001, ENT-ORDER)").option("-c, --config <path>", "Path to config file").option("-d, --depth <depth>", "Analysis depth (reference tracking level)", "3").option("--direction <direction>", "Analysis direction: upstream, downstream, both", "both").option("-f, --format <format>", "Output format: text, json, mermaid", "text").action(impactCommand);