executable-stories-formatters 0.6.2 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executable-stories-formatters",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Cucumber-compatible report formats (HTML, Markdown, JUnit XML, Cucumber JSON) for executable-stories test results.",
   "author": "Jag Reehal <jag@jagreehal.com>",
   "license": "MIT",
@@ -57,16 +57,16 @@
   ],
   "dependencies": {
     "@cucumber/html-formatter": "^23.0.0",
-    "@cucumber/messages": "^32.0.1",
+    "@cucumber/messages": "^32.2.0",
     "ajv": "^8.18.0"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.3.0",
-    "@types/node": "^25.3.2",
+    "@types/node": "^25.5.0",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "~5.9.3",
-    "vitest": "^4.0.18",
+    "vitest": "^4.1.0",
     "vitest-mock-extended": "^3.1.0"
   },
   "scripts": {

package/schemas/raw-run.schema.json

@@ -164,8 +164,21 @@
         },
         "tickets": {
           "type": "array",
-          "items": { "type": "string" },
-          "description": "Ticket/issue references for requirements traceability (e.g., ['JIRA-123'])."
+          "items": {
+            "oneOf": [
+              { "type": "string" },
+              {
+                "type": "object",
+                "properties": {
+                  "id": { "type": "string" },
+                  "url": { "type": "string" }
+                },
+                "required": ["id"],
+                "additionalProperties": false
+              }
+            ]
+          },
+          "description": "Ticket/issue references. Each item is either a string ID or an object with id and optional url."
         },
         "meta": {
           "type": "object",
@@ -208,6 +221,19 @@
           "type": "array",
           "items": { "$ref": "#/$defs/DocEntry" },
           "description": "Rich documentation entries attached to this step."
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique step identifier within the scenario (e.g., 'step-0')."
+        },
+        "wrapped": {
+          "type": "boolean",
+          "description": "Whether this step wraps a function call (Fn/Expect pattern)."
+        },
+        "durationMs": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Step-level duration in milliseconds (from startTimer/endTimer)."
         }
       },
       "required": ["keyword", "text"],
@@ -237,7 +263,8 @@
           "properties": {
             "kind": { "const": "note" },
             "text": { "type": "string" },
-            "phase": { "$ref": "#/$defs/DocPhase" }
+            "phase": { "$ref": "#/$defs/DocPhase" },
+            "children": { "type": "array", "items": { "$ref": "#/$defs/DocEntry" }, "description": "Nested child doc entries for grouping." }
           },
           "required": ["kind", "text", "phase"],
           "additionalProperties": false
@@ -251,7 +278,8 @@
               "type": "array",
               "items": { "type": "string" }
             },
-            "phase": { "$ref": "#/$defs/DocPhase" }
+            "phase": { "$ref": "#/$defs/DocPhase" },
+            "children": { "type": "array", "items": { "$ref": "#/$defs/DocEntry" }, "description": "Nested child doc entries for grouping." }
           },
           "required": ["kind", "names", "phase"],
           "additionalProperties": false
@@ -263,7 +291,8 @@
             "kind": { "const": "kv" },
             "label": { "type": "string" },
             "value": {},
-            "phase": { "$ref": "#/$defs/DocPhase" }
+            "phase": { "$ref": "#/$defs/DocPhase" },
+            "children": { "type": "array", "items": { "$ref": "#/$defs/DocEntry" }, "description": "Nested child doc entries for grouping." }
           },
           "required": ["kind", "label", "value", "phase"],
           "additionalProperties": false
@@ -276,7 +305,8 @@
             "label": { "type": "string" },
             "content": { "type": "string" },
             "lang": { "type": "string" },
-            "phase": { "$ref": "#/$defs/DocPhase" }
+            "phase": { "$ref": "#/$defs/DocPhase" },
+            "children": { "type": "array", "items": { "$ref": "#/$defs/DocEntry" }, "description": "Nested child doc entries for grouping." }
           },
           "required": ["kind", "label", "content", "phase"],
           "additionalProperties": false
@@ -298,7 +328,8 @@
                 "items": { "type": "string" }
               }
             },
-            "phase": { "$ref": "#/$defs/DocPhase" }
+            "phase": { "$ref": "#/$defs/DocPhase" },
+            "children": { "type": "array", "items": { "$ref": "#/$defs/DocEntry" }, "description": "Nested child doc entries for grouping." }
           },
           "required": ["kind", "label", "columns", "rows", "phase"],
           "additionalProperties": false
@@ -310,7 +341,8 @@
             "kind": { "const": "link" },
             "label": { "type": "string" },
             "url": { "type": "string" },
-            "phase": { "$ref": "#/$defs/DocPhase" }
+            "phase": { "$ref": "#/$defs/DocPhase" },
+            "children": { "type": "array", "items": { "$ref": "#/$defs/DocEntry" }, "description": "Nested child doc entries for grouping." }
           },
           "required": ["kind", "label", "url", "phase"],
           "additionalProperties": false
@@ -322,7 +354,8 @@
             "kind": { "const": "section" },
             "title": { "type": "string" },
             "markdown": { "type": "string" },
-            "phase": { "$ref": "#/$defs/DocPhase" }
+            "phase": { "$ref": "#/$defs/DocPhase" },
+            "children": { "type": "array", "items": { "$ref": "#/$defs/DocEntry" }, "description": "Nested child doc entries for grouping." }
           },
           "required": ["kind", "title", "markdown", "phase"],
           "additionalProperties": false
@@ -334,7 +367,8 @@
             "kind": { "const": "mermaid" },
             "code": { "type": "string" },
             "title": { "type": "string" },
-            "phase": { "$ref": "#/$defs/DocPhase" }
+            "phase": { "$ref": "#/$defs/DocPhase" },
+            "children": { "type": "array", "items": { "$ref": "#/$defs/DocEntry" }, "description": "Nested child doc entries for grouping." }
           },
           "required": ["kind", "code", "phase"],
           "additionalProperties": false
@@ -346,7 +380,8 @@
             "kind": { "const": "screenshot" },
             "path": { "type": "string" },
             "alt": { "type": "string" },
-            "phase": { "$ref": "#/$defs/DocPhase" }
+            "phase": { "$ref": "#/$defs/DocPhase" },
+            "children": { "type": "array", "items": { "$ref": "#/$defs/DocEntry" }, "description": "Nested child doc entries for grouping." }
           },
           "required": ["kind", "path", "phase"],
           "additionalProperties": false
@@ -358,7 +393,8 @@
             "kind": { "const": "custom" },
             "type": { "type": "string" },
             "data": {},
-            "phase": { "$ref": "#/$defs/DocPhase" }
+            "phase": { "$ref": "#/$defs/DocPhase" },
+            "children": { "type": "array", "items": { "$ref": "#/$defs/DocEntry" }, "description": "Nested child doc entries for grouping." }
           },
           "required": ["kind", "type", "data", "phase"],
           "additionalProperties": false

package/skills/formatters-cli/SKILL.md

@@ -36,6 +36,12 @@ executable-stories format raw-run.json --format html,markdown,junit
 # Read from stdin
 cat raw-run.json | executable-stories format --stdin --format markdown
 
+# Compare two canonical runs for review-friendly output
+executable-stories compare baseline.json current.json \
+  --input-type canonical \
+  --format html,markdown \
+  --output-name review-diff
+
 # Validate JSON against schema
 executable-stories validate raw-run.json
 ```
@@ -55,6 +61,8 @@ const generator = new ReportGenerator({
   formats: ["markdown", "html"],
   outputDir: "docs",
   outputName: "user-stories",
+  outputNameTimestamp: true,   // optional: unique filenames per run (e.g. user-stories-1739123456.md)
+  sortTestCases: "id",        // optional: stable order for diff-friendly reports
 });
 
 const outputs = await generator.generate(canonical);
@@ -99,6 +107,8 @@ const cucumberJson = new CucumberJsonFormatter().formatToString(canonical);
 --format html,markdown,junit,cucumber-json,cucumber-html,cucumber-messages
 --output-dir reports          # Base directory (default: reports)
 --output-name test-results    # Base filename (default: test-results)
+--output-name-timestamp       # Append run timestamp (UTC seconds) to filename for before/after diffs
+--sort-test-cases id|source|none  # Deterministic scenario order (default: none). Use id for diff-friendly output
 --input-type raw              # raw | canonical | ndjson
 
 # Filtering
@@ -118,8 +128,49 @@ const cucumberJson = new CucumberJsonFormatter().formatToString(canonical);
 # Machine output
 --json-summary                # Print JSON summary to stdout
 --emit-canonical path.json    # Write canonical JSON
+
+# Asset Bundling
+--asset-mode none|copy        # Asset bundling strategy (default: none)
+--allow-missing-assets        # Warn on missing assets instead of failing
+```
+
+## Asset Bundling
+
+Use `--asset-mode copy` to produce a portable report directory. All locally-referenced assets
+(Playwright videos, screenshots, attachment files) are copied into an `assets/` subdirectory
+and HTML paths are rewritten.
+
+```bash
+executable-stories format raw-run.json --format html --output-dir report --asset-mode copy
 ```
 
+Output:
+```
+report/
+  test-results.html   # paths rewritten to assets/
+  assets/
+    video-3f2c1a7b.webm
+    step-1-91ab22de.png
+```
+
+### GitHub Actions usage
+
+```yaml
+- run: npx executable-stories format .executable-stories/raw-run.json --format html --output-dir report --asset-mode copy
+- uses: actions/upload-artifact@v4
+  with:
+    name: test-report
+    path: report/
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--asset-mode none` | Default. No asset bundling. |
+| `--asset-mode copy` | Copy local assets to `assets/`, rewrite paths. |
+| `--allow-missing-assets` | Warn on missing assets instead of failing. |
+
 ### Validation
 
 ```typescript
@@ -138,6 +189,35 @@ const result = validateCanonicalRun(canonical);
 assertValidRun(canonical);
 ```
 
+### Before/after diffs (evolution of tests)
+
+To compare reports across runs (e.g. in CI or locally), use timestamped filenames and deterministic ordering so diffs show real changes instead of random reordering from parallel test execution:
+
+```bash
+executable-stories format raw-run.json --format markdown,html \
+  --output-name-timestamp \
+  --sort-test-cases id
+```
+
+- `--output-name-timestamp`: appends run start time in UTC seconds (e.g. `test-results-1739123456.md`), so each run produces a unique, chronologically sortable file.
+- `--sort-test-cases id`: sorts scenarios by deterministic id (hash of source file + scenario name) so report content order is stable across runs.
+
+Programmatic: set `outputNameTimestamp: true` and `sortTestCases: "id"` (or `"source"` for file/line order) on `FormatterOptions`.
+
+For first-class run comparisons, use the dedicated compare subcommand:
+
+```bash
+executable-stories compare baseline.json current.json \
+  --input-type canonical \
+  --format html,markdown \
+  --output-dir reports \
+  --output-name test-results-diff
+```
+
+- Generates a standalone HTML review report with filter chips for `Regressed`, `Fixed`, `Added`, `Removed`, and `Changed`.
+- Generates Markdown with per-scenario before/after summaries for PR discussion or artifact storage.
+- Use canonical input when you already persist prior runs; raw and ndjson inputs are also supported as long as both files use the same `--input-type`.
+
 ### Notifications
 
 ```bash