executable-stories-formatters 1.0.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-formatters",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Cucumber-compatible report formats (HTML, Markdown, JUnit XML, Cucumber JSON) for executable-stories test results.",
   "author": "Jag Reehal <jag@jagreehal.com>",
   "license": "MIT",
@@ -62,8 +62,7 @@
     "yaml": "^2.9.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "executable-stories-core": "0.18.0",
-    "executable-stories-react": "0.2.1"
+    "executable-stories-react": "0.4.0"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.4.0",
@@ -75,7 +74,8 @@
     "tsx": "^4.22.4",
     "typescript": "~6.0.3",
     "vitest": "^4.1.8",
-    "vitest-mock-extended": "^4.0.0"
+    "vitest-mock-extended": "^4.0.0",
+    "executable-stories-core": "0.18.1"
   },
   "scripts": {
     "embed-assets": "node scripts/embed-react-assets.mjs",

package/schemas/explainer-v1.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://executable-stories.dev/schemas/explainer-v1.json",
+  "title": "Explainer provenance block v1",
+  "description": "The `explainer` frontmatter block that ties a hand-authored explainer document to the scenarios it explains. See the explain-change skill.",
+  "type": "object",
+  "required": ["version", "scenarios"],
+  "properties": {
+    "version": { "const": 1 },
+    "generated": {
+      "type": "string",
+      "description": "ISO date the explainer was generated (YYYY-MM-DD)."
+    },
+    "runId": {
+      "type": "string",
+      "description": "runId of the run the explainer was generated from."
+    },
+    "commit": { "type": "string", "description": "Commit sha the explainer explains." },
+    "branch": { "type": "string" },
+    "scenarios": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "hash"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Canonical scenario id (stable machine key)."
+          },
+          "title": {
+            "type": "string",
+            "description": "Scenario title at generation time; enables rename detection."
+          },
+          "hash": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{16}$",
+            "description": "scenarioContentHash at generation time (16 hex chars of sha256 over title + step keywords/texts)."
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/scenario-index-v1.json

@@ -37,6 +37,11 @@
       "properties": {
         "id": { "type": "string" },
         "title": { "type": "string" },
+        "hash": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{16}$",
+          "description": "Content hash (title + step keywords/texts) for explainer provenance; excludes status. Always emitted since 1.x, optional in the schema so pre-hash v1 artifacts stay valid."
+        },
         "status": { "$ref": "#/$defs/status" },
         "feature": { "type": "string" },
         "sourceFile": { "type": "string" },

package/templates/astro-thin/src/content.config.ts

@@ -10,12 +10,19 @@ import esConfig from '../executable-stories.config.mjs';
 export const collections = {
   // Hand-authored docs. `authoredDocsLoader` is a drop-in for Starlight's
   // docsLoader that ALSO: auto-titles frontmatter-free markdown from its first
-  // H1, and rewrites relative `*.md` cross-links to their routes — so you can
-  // drop in plain GitHub-style docs without edits.
+  // H1, rewrites relative `*.md` cross-links to their routes, and (because the
+  // shared config is passed as `explainers`) injects a fresh/stale banner into
+  // any doc carrying an `explainer` provenance block (explain-change skill) —
+  // with deep links to the cited scenarios' story pages.
   docs: defineCollection({
-    loader: authoredDocsLoader({ path: 'src/content/docs' }),
+    loader: authoredDocsLoader({ path: 'src/content/docs', explainers: esConfig }),
     schema: docsSchema({
-      extend: z.object({ verifiedBy: z.union([z.string(), z.array(z.string())]).optional() }),
+      extend: z.object({
+        verifiedBy: z.union([z.string(), z.array(z.string())]).optional(),
+        // Explainer provenance block — kept loose here (zod would otherwise
+        // strip it); `executable-stories check-explainers` validates strictly.
+        explainer: z.record(z.unknown()).optional(),
+      }),
     }),
   }),
   // Generated scenarios (executable-stories) — in-memory, never written to disk.