speckeeper 0.9.0 → 0.9.2

package/README.md

@@ -290,6 +290,28 @@ class EntityModel extends Model<typeof EntitySchema> {
 
 Without `deepValidation`, speckeeper still performs existence checks for all spec IDs across all configured sources.
 
+#### Lookup keys (when spec ID differs from external identifier)
+
+By default, the global scanner searches for each spec's `id` in external sources. When the external identifier differs — for example, entity ID `"user"` vs DDL table name `"users"` — define `lookupKeys` on the model to map per source type:
+
+```typescript
+class EntityModel extends Model<typeof EntitySchema> {
+  readonly id = 'entity';
+  readonly name = 'Entity';
+  readonly idPrefix = 'ENT';
+  readonly schema = EntitySchema;
+
+  protected lookupKeys: LookupKeyConfig<Entity> = {
+    ddl: (spec) => spec.tableName,
+    openapi: (spec) => spec.schemaName ?? spec.id,
+  };
+}
+```
+
+With this configuration, when scanning DDL sources the scanner searches for `spec.tableName` instead of `spec.id`. If a match is found, the result is mapped back to the original spec ID for reporting and deep validation.
+
+`lookupKeys` is optional per source type — any source type not listed falls back to `spec.id`.
+
 #### Custom scanners
 
 For file formats not covered by the built-in scanners, provide a custom `SourceScanner` plugin:
@@ -326,6 +348,43 @@ speckeeper check
   ✓ All checks passed
 ```
 
+#### Transitive coverage
+
+Narrative-level specs (e.g. UseCases) rarely have direct `@verifies UC-001` annotations in code. Instead, they are verified indirectly through a chain: UseCase is satisfied by Requirements, and those Requirements are verified by tests.
+
+Configure `coverage.transitiveRelations` to enable automatic transitive coverage:
+
+```typescript
+// speckeeper.config.ts
+export default defineConfig({
+  sources: [/* ... */],
+  coverage: {
+    transitiveRelations: ['satisfies'],
+  },
+});
+```
+
+When `speckeeper check --coverage` runs:
+
+1. The global scan determines which specs are **directly covered** (found in external sources)
+2. For each transitive relation type, the framework walks the relation graph
+3. A spec is **transitively covered** if ALL specs that relate to it via a transitive relation are themselves covered (directly or transitively)
+
+No per-model code is needed. Coverage is computed purely from relation data and config.
+
+```bash
+$ npx speckeeper check test --coverage
+
+  Transitive coverage (via satisfies)
+  ─────────────────────────────────────
+  Total:     12
+  Covered:   11  (8 direct + 3 transitive)
+  Uncovered: 1
+  Coverage:  92%
+```
+
+Multi-level chains are supported. For example, with `transitiveRelations: ['satisfies', 'verifies']`, if TEST-001 verifies FR-001, and FR-001 satisfies UC-001, then UC-001 is transitively covered when TEST-001 is directly matched.
+
 ## Model Levels & Traceability
 
 speckeeper organizes models by abstraction level:

package/dist/cli.js

@@ -727,7 +727,7 @@ function loadFileContent(filePath, sourceType) {
   }
   return content;
 }
-function runGlobalScan(sources, specIds, basePath) {
+function runGlobalScan(sources, specIds, basePath, lookupKeyMap) {
   const cwd = basePath ?? process.cwd();
   const result = /* @__PURE__ */ new Map();
   const warnings = [];
@@ -740,6 +740,13 @@ function runGlobalScan(sources, specIds, basePath) {
       });
       continue;
     }
+    const keyToSpecId = /* @__PURE__ */ new Map();
+    for (const specId of specIds) {
+      const overrides = lookupKeyMap?.get(specId);
+      const key = overrides?.[source.type] ?? specId;
+      keyToSpecId.set(key, specId);
+    }
+    const keysToSearch = Array.from(keyToSpecId.keys());
     const allFiles = /* @__PURE__ */ new Set();
     for (const pattern of source.paths) {
       const found = glob.sync(pattern, {
@@ -768,7 +775,7 @@ function runGlobalScan(sources, specIds, basePath) {
       if (content == null) continue;
       let matches;
       try {
-        matches = scanner.findSpecIds(content, specIds, relPath);
+        matches = scanner.findSpecIds(content, keysToSearch, relPath);
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
         warnings.push({
@@ -779,17 +786,19 @@ function runGlobalScan(sources, specIds, basePath) {
         continue;
       }
       for (const match of matches) {
+        const originalSpecId = keyToSpecId.get(match.specId) ?? match.specId;
         const globalMatch = {
           ...match,
+          specId: originalSpecId,
           sourceType: source.type,
           relation: source.relation,
           filePath: relPath
         };
-        const existing = result.get(match.specId);
+        const existing = result.get(originalSpecId);
         if (existing) {
           existing.push(globalMatch);
         } else {
-          result.set(match.specId, [globalMatch]);
+          result.set(originalSpecId, [globalMatch]);
         }
       }
     }
@@ -930,19 +939,39 @@ async function checkCommand(type, options) {
       console.log(chalk4.gray(`  Sources: ${sources.length} configured`));
     }
     const results = [];
+    const transitiveRelations = config.coverage?.transitiveRelations ?? [];
+    let transitiveCoverageData;
     const allSpecIds = [];
     const specIdToModel = /* @__PURE__ */ new Map();
+    const lookupKeyMap = /* @__PURE__ */ new Map();
     for (const model of models) {
       const modelSpecs = getSpecsFromConfig(specs, model.id);
+      const modelLookupKeys = model.getLookupKeys?.();
       for (const spec of modelSpecs) {
         const specId = spec.id;
         allSpecIds.push(specId);
         specIdToModel.set(specId, { modelId: model.id, spec });
+        if (modelLookupKeys) {
+          const overrides = {};
+          for (const [sourceType, mapper] of Object.entries(modelLookupKeys)) {
+            if (typeof mapper === "function") {
+              overrides[sourceType] = mapper(spec);
+            }
+          }
+          if (Object.keys(overrides).length > 0) {
+            lookupKeyMap.set(specId, overrides);
+          }
+        }
       }
     }
     if (sources.length > 0 && allSpecIds.length > 0) {
       const filteredSources = checkType === "all" ? sources : sources.filter((s) => s.type === checkType);
-      const { matches, warnings: scanWarnings } = runGlobalScan(filteredSources, allSpecIds, cwd);
+      const { matches, warnings: scanWarnings } = runGlobalScan(
+        filteredSources,
+        allSpecIds,
+        cwd,
+        lookupKeyMap.size > 0 ? lookupKeyMap : void 0
+      );
       for (const sw of scanWarnings) {
         results.push({
           type: sw.sourceType,
@@ -983,9 +1012,20 @@ async function checkCommand(type, options) {
           }
         }
       }
+      const directlyCovered = new Set(matches.keys());
+      let coveredSet = directlyCovered;
+      if (transitiveRelations.length > 0) {
+        const allSpecsWithRelations = allSpecIds.map((id) => {
+          const entry = specIdToModel.get(id);
+          const spec = entry?.spec;
+          return { id, relations: spec?.relations };
+        });
+        transitiveCoverageData = computeTransitiveCoverage(directlyCovered, allSpecsWithRelations, transitiveRelations);
+        coveredSet = transitiveCoverageData.coveredSet;
+      }
       if (options.verbose) {
         for (const specId of allSpecIds) {
-          if (!matches.has(specId)) {
+          if (!coveredSet.has(specId)) {
             const entry = specIdToModel.get(specId);
             results.push({
               type: entry?.modelId ?? "unknown",
@@ -1021,17 +1061,47 @@ async function checkCommand(type, options) {
             });
           }
         }
+      }
+      if (transitiveCoverageData && transitiveRelations.length > 0) {
+        const total = allSpecIds.length;
+        const directCount = transitiveCoverageData.directCount;
+        const transitiveCount = transitiveCoverageData.transitiveCount;
+        const covered = directCount + transitiveCount;
+        const uncovered = total - covered;
+        const coveragePercent = total > 0 ? Math.round(covered / total * 100) : 100;
         console.log("");
-        console.log(chalk4.gray("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
-        const allPassed = coverageResults.every((c) => c.result.coveragePercent >= 80);
-        if (allPassed) {
-          console.log(chalk4.green("  \u2713 All coverage checks passed (\u226580%)"));
-        } else {
-          const failed = coverageResults.filter((c) => c.result.coveragePercent < 80);
-          console.log(chalk4.yellow(`  \u26A0 ${failed.length} coverage check(s) below 80%`));
+        console.log(chalk4.blue(`  Transitive coverage (via ${transitiveRelations.join(", ")})`));
+        console.log(chalk4.gray(`  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`));
+        console.log(chalk4.gray(`  Total:     ${total}`));
+        console.log(chalk4.green(`  Covered:   ${covered}  (${directCount} direct + ${transitiveCount} transitive)`));
+        console.log(chalk4.yellow(`  Uncovered: ${uncovered}`));
+        const color = coveragePercent >= 80 ? chalk4.green : coveragePercent >= 50 ? chalk4.yellow : chalk4.red;
+        console.log(color(`  Coverage:  ${coveragePercent}%`));
+        if (uncovered > 0) {
+          const uncoveredIds = allSpecIds.filter((id) => !transitiveCoverageData.coveredSet.has(id));
+          const display = uncoveredIds.slice(0, 10);
+          console.log("");
+          console.log(chalk4.yellow("  Uncovered items:"));
+          for (const id of display) {
+            const entry = specIdToModel.get(id);
+            console.log(chalk4.yellow(`    - ${id} (${entry?.modelId ?? "unknown"})`));
+          }
+          if (uncoveredIds.length > 10) {
+            console.log(chalk4.yellow(`    ... and ${uncoveredIds.length - 10} more`));
+          }
         }
-      } else {
+      }
+      console.log("");
+      console.log(chalk4.gray("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+      const allCoverageResults = [...coverageResults];
+      const allPassed = allCoverageResults.every((c) => c.result.coveragePercent >= 80);
+      if (coverageResults.length === 0 && !transitiveCoverageData) {
         console.log(chalk4.gray("  No coverage checker found"));
+      } else if (allPassed) {
+        console.log(chalk4.green("  \u2713 All coverage checks passed (\u226580%)"));
+      } else {
+        const failed = allCoverageResults.filter((c) => c.result.coveragePercent < 80);
+        console.log(chalk4.yellow(`  \u26A0 ${failed.length} coverage check(s) below 80%`));
       }
     }
     const hasErrors = results.some((r) => !r.success);
@@ -1043,6 +1113,38 @@ async function checkCommand(type, options) {
     process.exit(1);
   }
 }
+function computeTransitiveCoverage(directlyCovered, allSpecs, transitiveRelations) {
+  if (transitiveRelations.length === 0) {
+    return { coveredSet: new Set(directlyCovered), directCount: directlyCovered.size, transitiveCount: 0 };
+  }
+  const reverseRelations = /* @__PURE__ */ new Map();
+  for (const spec of allSpecs) {
+    if (!spec.relations) continue;
+    for (const rel of spec.relations) {
+      if (!transitiveRelations.includes(rel.type)) continue;
+      const existing = reverseRelations.get(rel.target) ?? [];
+      existing.push(spec.id);
+      reverseRelations.set(rel.target, existing);
+    }
+  }
+  const coveredSet = new Set(directlyCovered);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [targetId, sourceIds] of reverseRelations) {
+      if (coveredSet.has(targetId)) continue;
+      if (sourceIds.length > 0 && sourceIds.every((id) => coveredSet.has(id))) {
+        coveredSet.add(targetId);
+        changed = true;
+      }
+    }
+  }
+  return {
+    coveredSet,
+    directCount: directlyCovered.size,
+    transitiveCount: coveredSet.size - directlyCovered.size
+  };
+}
 function loadExternalData(filePath) {
   const content = readFileSync(filePath, "utf-8");
   if (filePath.endsWith(".yaml") || filePath.endsWith(".yml")) {