@encore-os/eos-spec 0.7.0 → 0.9.0

package/dist/lib/walkthrough-coverage.js

@@ -0,0 +1,111 @@
+// src/lib/walkthrough-coverage.ts
+//
+// Canonical walkthrough filmed-coverage contract (the engine source of truth that
+// encoreos's repo-local `scripts/specs/check-walkthrough-coverage.ts` and
+// `tests/e2e/utils/walkthrough-manifest.ts` repoint to — REPOINT.md / encoreos#12).
+//
+// The `@walkthrough` Playwright lane records a per-AC clip + step screenshots and
+// writes `docs/walkthroughs/<spec>/manifest.json`; `walkthrough:build` stitches the
+// MP4 and patches each AC's `chapterStartMs`. This module is the predicate that
+// consumes that manifest:
+//   • an AC is "filmed" only with a NON-EMPTY clip AND a NUMERIC chapterStartMs
+//     (the latter only exists after the stitch pass — a pass-1-only manifest fails);
+//   • a user story is "covered" only when a FILMED in-spec AC lists it;
+//   • a manifest whose specSha disagrees with the current spec is STALE (re-record).
+//
+// Pure + dependency-free so both the CLI (`eos-spec walkthrough --check`) and any
+// browser/consumer call site share one definition.
+import { createHash } from 'node:crypto';
+/**
+ * Stable manifest sha over the spec's AC + user-story ids. Order-insensitive
+ * (ids sorted) so reordering the spec doesn't spuriously invalidate a recording;
+ * adding/removing an AC or story does (→ STALE, re-record). 16 hex chars.
+ */
+export function computeSpecSha(acIds, storyIds) {
+    const canonical = JSON.stringify({ ac: [...acIds].sort(), us: [...storyIds].sort() });
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}
+/**
+ * Is a single AC "filmed"? A non-empty `clip` AND a finite numeric `chapterStartMs`
+ * (the stitch-pass field). A pass-1-only manifest (clip present, chapterStartMs
+ * absent) is NOT filmed — `walkthrough:build` must run.
+ */
+export function acFilmStatus(ac) {
+    if (!ac.clip || ac.clip.trim() === '') {
+        return { id: ac.id, filmed: false, reason: 'no clip (AC not recorded — undriveable UI stays MISSING)' };
+    }
+    if (typeof ac.chapterStartMs !== 'number' || !Number.isFinite(ac.chapterStartMs)) {
+        return { id: ac.id, filmed: false, reason: 'no numeric chapterStartMs (run `walkthrough:build` to stitch)' };
+    }
+    return { id: ac.id, filmed: true, reason: `filmed (clip + chapter @ ${ac.chapterStartMs}ms)` };
+}
+/** The set of story ids covered by at least one FILMED AC that lists them. */
+export function coveredStoryIds(manifest) {
+    const covered = new Set();
+    for (const ac of manifest.acceptance_criteria) {
+        if (!acFilmStatus(ac).filmed)
+            continue;
+        for (const s of ac.stories ?? [])
+            covered.add(s);
+    }
+    return covered;
+}
+/** Extract canonical AC ids (frontmatter) and user-story ids (body) from spec text. */
+export function specRequirementIds(specText) {
+    const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(specText);
+    const fmRaw = fmMatch?.[0] ?? '';
+    const fmBlock = fmMatch?.[1] ?? '';
+    const acIds = [];
+    for (const line of fmBlock.split('\n')) {
+        const m = /^ {2}- id:\s*["']?(AC-\d+)["']?\s*$/.exec(line);
+        if (m?.[1])
+            acIds.push(m[1]);
+    }
+    const body = fmRaw ? specText.slice(fmRaw.length) : specText;
+    const storyIds = [];
+    for (const line of body.split('\n')) {
+        const m = /^\s*-\s+\*{0,2}(US-\d+)\*{0,2}\s+\[[a-z_]+\]/.exec(line);
+        if (m?.[1])
+            storyIds.push(m[1]);
+    }
+    return { acIds: [...new Set(acIds)], storyIds: [...new Set(storyIds)] };
+}
+/**
+ * Whole-manifest verdict against the spec's current requirement ids. The spec is
+ * the source of truth: an AC the spec declares but the manifest never recorded is
+ * `unfilmed`. The specSha is recomputed from the spec's ids and compared to the
+ * manifest's — a mismatch means the spec changed since recording (STALE).
+ */
+export function checkWalkthroughCoverage(manifest, expected) {
+    const currentSha = computeSpecSha(expected.acIds, expected.storyIds);
+    const stale = manifest.specSha !== currentSha;
+    const byId = new Map(manifest.acceptance_criteria.map((a) => [a.id, a]));
+    const unfilmed = [];
+    let acFilmed = 0;
+    for (const id of expected.acIds) {
+        const ac = byId.get(id);
+        if (!ac) {
+            unfilmed.push({ id, filmed: false, reason: 'declared in spec but absent from manifest (not recorded)' });
+            continue;
+        }
+        const s = acFilmStatus(ac);
+        if (s.filmed)
+            acFilmed++;
+        else
+            unfilmed.push(s);
+    }
+    const covered = coveredStoryIds(manifest);
+    const uncovered = expected.storyIds.filter((s) => !covered.has(s));
+    const ok = !stale && unfilmed.length === 0 && uncovered.length === 0;
+    return {
+        stale,
+        acTotal: expected.acIds.length,
+        acFilmed,
+        unfilmed,
+        storiesTotal: expected.storyIds.length,
+        storiesCovered: expected.storyIds.length - uncovered.length,
+        uncovered,
+        ok,
+    };
+}
+//# sourceMappingURL=walkthrough-coverage.js.map

package/dist/lib/walkthrough-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walkthrough-coverage.js","sourceRoot":"","sources":["../../src/lib/walkthrough-coverage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@encore-os/eos-spec",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Portable, config-driven spec-pipeline engine + quality harness. One canonical engine consumed as a library (with a client-safe /pure subpath) by every Encore-OS repo.",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",