speckeeper 0.9.1 → 0.9.2

package/README.md

@@ -348,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

@@ -939,6 +939,8 @@ 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();
@@ -1010,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",
@@ -1048,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);
@@ -1070,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")) {