speckeeper 0.9.4 → 0.10.1

package/docs/model-guide.md

@@ -109,7 +109,10 @@ export interface Exporter<T> {
   format: 'markdown' | 'json' | 'mermaid';
   single?: (spec: T) => string;
   index?: (specs: T[]) => string;
+  /** Subdirectory under docsDir (used with single + index/index.md) */
   outputDir?: string;
+  /** Direct output file path relative to docsDir (used with index-only exporters) */
+  outputFile?: string;
   filename?: (spec: T) => string;
 }
 
@@ -138,34 +141,31 @@ export interface CheckResult {
   }>;
 }
 
-/**
- * Coverage result
- */
-export interface CoverageResult {
-  /** Total target count */
-  total: number;
-  /** Covered count */
-  covered: number;
-  /** Uncovered count */
-  uncovered: number;
-  /** Coverage rate (%) */
-  coveragePercent: number;
-  /** Details of covered items */
-  coveredItems: { id: string; description?: string }[];
-  /** Details of uncovered items */
-  uncoveredItems: { id: string; description?: string; sourceId?: string }[];
+// ============================================================================
+// Deep Validation (replaces per-model externalChecker)
+// ============================================================================
+
+/** OpenAPI deep validation mapping */
+export interface OpenAPIValidationMapping {
+  path: string;
+  method?: string;
+  parameters?: Array<{ name: string; in?: string; type?: string }>;
+  responseProperties?: Array<{ name: string; type?: string }>;
+}
+
+/** DDL deep validation mapping */
+export interface DDLValidationMapping {
+  tableName: string;
+  columns?: Array<{ name: string; type?: string }>;
+  checkTypes?: boolean;
 }
 
 /**
- * Coverage checker definition
- * 
- * Verify cross-model consistency (coverage).
- * Example: Whether TestRef covers acceptanceCriteria of Requirement
+ * Deep validation rule for a specific source type.
+ * The mapper extracts expected structure from a spec for detailed comparison
+ * against the matched source object.
  */
-export interface CoverageChecker<T> {
-  /** Target model ID for coverage (e.g. 'requirement') */
-  targetModel: string;
-  /** Description of coverage check */
+export interface DeepValidationRule<T, TMapping = unknown> {
 ```
 <!--@embedoc:end-->
 
@@ -175,54 +175,54 @@ export interface CoverageChecker<T> {
 **src/core/model.ts (Model Class Properties)**
 
 ```typescript
-  /** Execute coverage check */
-  check: (
-    specs: T[],
-    registry: Record<string, Map<string, unknown>>
-  ) => CoverageResult;
 }
 
-// ============================================================================
-// Renderer (for embeds)
-// ============================================================================
-
 /**
- * Render context
- * Simplified version compatible with embedoc's EmbedContext
+ * Deep validation configuration keyed by source type.
+ * Models define this to enable Level 2/3 checks beyond existence.
  */
-export interface RenderContext {
-  /** Parameters (filter conditions other than format, etc.) */
-  params: Record<string, string | undefined>;
-  /** Markdown helpers */
-  markdown: {
-    /** Generate table */
-    table: (headers: string[], rows: (string | unknown)[][]) => string;
-  };
+export interface DeepValidationConfig<T> {
+  openapi?: DeepValidationRule<T, OpenAPIValidationMapping>;
+  ddl?: DeepValidationRule<T, DDLValidationMapping>;
+  [sourceType: string]: DeepValidationRule<T, unknown> | undefined;
 }
 
 /**
- * Renderer definition
- * 
- * Model-specific rendering called from embeds
+ * Lookup key configuration keyed by source type.
+ * When a model's spec ID differs from the external identifier
+ * (e.g. entity ID "user" vs DDL table name "users"),
+ * define a mapper per source type to derive the external key.
+ * If not defined for a source type, spec.id is used as-is.
  */
-export interface Renderer<T> {
-  /** Format ID ('table', 'list', 'detail', 'spec-chapter', etc.) */
-  format: string;
-  /** Rendering process */
-  render: (specs: T[], ctx: RenderContext) => string;
+export interface LookupKeyConfig<T> {
+  [sourceType: string]: ((spec: T) => string) | undefined;
 }
 
-// ============================================================================
-// Model Base Class
-// ============================================================================
+/**
+ * Coverage result
+ */
+export interface CoverageResult {
+  /** Total target count */
+  total: number;
+  /** Covered count */
+  covered: number;
+  /** Uncovered count */
+  uncovered: number;
+  /** Coverage rate (%) */
+  coveragePercent: number;
+  /** Details of covered items */
+  coveredItems: { id: string; description?: string }[];
+  /** Details of uncovered items */
+  uncoveredItems: { id: string; description?: string; sourceId?: string }[];
+}
 
 /**
- * Model base class
+ * Coverage checker definition
  * 
- * @template TSchema - Zod schema type
+ * Verify cross-model consistency (coverage).
+ * Example: Whether TestRef covers acceptanceCriteria of Requirement
  */
-export abstract class Model<TSchema extends ZodType> {
-  /** Singleton instance storage (per subclass) */
+export interface CoverageChecker<T> {
 ```
 <!--@embedoc:end-->
 
@@ -493,61 +493,65 @@ class TestRefModel extends Model<typeof TestRefSchema> {
   protected exporters: Exporter<TestRef>[] = [
     {
       format: 'markdown',
-      single: (spec) => {
+      index: (specs) => {
         const lines: string[] = [];
-        lines.push(`# ${spec.id}: ${spec.description}`);
-        lines.push('');
-        lines.push('## Test Source');
+        lines.push('# Test Reference List');
         lines.push('');
-        lines.push(`- **Path**: \`${spec.source.path}\``);
-        lines.push(`- **Framework**: ${spec.source.framework}`);
-        if (spec.source.resultPath) {
-          lines.push(`- **Result JSON**: \`${spec.source.resultPath}\``);
+        lines.push('| ID | Description | Framework | Requirements Count |');
+        lines.push('|----|-------------|-----------|-------------------|');
+        for (const spec of specs) {
+          lines.push(
+            `| ${spec.id} | ${spec.description} | ${spec.source.framework} | ${spec.verifiesRequirements.length} |`,
+          );
         }
         lines.push('');
-
-        lines.push('## Verified Requirements');
-        lines.push('');
-        for (const reqId of spec.verifiesRequirements) {
-          lines.push(`- ${reqId}`);
-        }
+        lines.push('---');
         lines.push('');
 
-        if (spec.implementsCommand) {
-          lines.push('## Implemented Command');
+        for (const spec of specs) {
+          lines.push(`## ${spec.id}: ${spec.description}`);
           lines.push('');
-          lines.push(`- ${spec.implementsCommand}`);
+          lines.push('### Test Source');
+          lines.push('');
+          lines.push(`- **Path**: \`${spec.source.path}\``);
+          lines.push(`- **Framework**: ${spec.source.framework}`);
+          if (spec.source.resultPath) {
+            lines.push(`- **Result JSON**: \`${spec.source.resultPath}\``);
+          }
           lines.push('');
-        }
 
-        if (spec.testCasePatterns && spec.testCasePatterns.length > 0) {
-          lines.push('## Test Case Patterns');
+          lines.push('### Verified Requirements');
           lines.push('');
-          lines.push('| Acceptance Criteria ID | Pattern | Description |');
-          lines.push('|------------------------|---------|-------------|');
-          for (const p of spec.testCasePatterns) {
-            lines.push(`| ${p.acceptanceCriteriaId} | \`${p.pattern}\` | ${p.description || '-'} |`);
+          for (const reqId of spec.verifiesRequirements) {
+            lines.push(`- ${reqId}`);
           }
           lines.push('');
-        }
 
-        return lines.join('\n');
-      },
-      index: (specs) => {
-        const lines: string[] = [];
-        lines.push('# Test Reference List');
-        lines.push('');
-        lines.push('| ID | Description | Framework | Requirements Count |');
-        lines.push('|----|-------------|-----------|-------------------|');
-        for (const spec of specs) {
-          lines.push(
-            `| [${spec.id}](./${spec.id}.md) | ${spec.description} | ${spec.source.framework} | ${spec.verifiesRequirements.length} |`,
-          );
+          if (spec.implementsCommand) {
+            lines.push('### Implemented Command');
+            lines.push('');
+            lines.push(`- ${spec.implementsCommand}`);
+            lines.push('');
+          }
+
+          if (spec.testCasePatterns && spec.testCasePatterns.length > 0) {
+            lines.push('### Test Case Patterns');
+            lines.push('');
+            lines.push('| Acceptance Criteria ID | Pattern | Description |');
+            lines.push('|------------------------|---------|-------------|');
+            for (const p of spec.testCasePatterns) {
+              lines.push(`| ${p.acceptanceCriteriaId} | \`${p.pattern}\` | ${p.description || '-'} |`);
+            }
+            lines.push('');
+          }
+
+          lines.push('---');
+          lines.push('');
         }
-        return lines.join('\n');
+
+        return lines.join('\n').replace(/\n---\n\n$/s, '\n');
       },
-      outputDir: 'test-refs',
-      filename: (spec) => spec.id,
+      outputFile: 'design/test-refs.md',
     },
   ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speckeeper",
-  "version": "0.9.4",
+  "version": "0.10.1",
   "description": "TypeScript-first specification validation framework with external SSOT integration",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,6 +40,7 @@
     "prepublishOnly": "npm run build",
     "docs": "embedoc build",
     "docs:watch": "embedoc watch",
+    "dsl:generate": "npx agent-runtime generate --config dsl/agent-runtime.config.yaml",
     "contract:validate": "npx cli-contracts validate",
     "contract:generate": "npx cli-contracts generate",
     "ci": "npm run ci:validate && npm run ci:generate && npm run ci:verify",
@@ -70,6 +71,14 @@
     "yaml": "^2.3.4",
     "zod": "^3.22.4"
   },
+  "peerDependencies": {
+    "agent-contracts-runtime": ">=0.13.0"
+  },
+  "peerDependenciesMeta": {
+    "agent-contracts-runtime": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/node": "^20.11.0",
@@ -77,7 +86,9 @@
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",
     "@vitest/coverage-v8": "^1.6.1",
-    "cli-contracts": "^0.2.0",
+    "agent-contracts": "^0.21.0",
+    "agent-contracts-runtime": "^0.13.0",
+    "cli-contracts": "^0.6.1",
     "eslint": "^9.39.2",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",