executable-stories-formatters 1.11.0 → 1.12.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { TestRunResult, TestCaseResult, TestStatus, Attachment } from 'executable-stories-core/types/test-result';
-export { Attachment, CIInfo, CoverageSummary, StepResult, TestCaseAttempt, TestCaseEvidence, TestCaseResult, TestRunResult, TestStatus } from 'executable-stories-core/types/test-result';
+export { Attachment, CIInfo, CoverageSummary, FeatureDeclaration, GlossaryTerm, StepResult, TestCaseAttempt, TestCaseEvidence, TestCaseResult, TestRunResult, TestStatus } from 'executable-stories-core/types/test-result';
 import { StoryStep, DocEntry, NormalizedTicket, StepKeyword } from 'executable-stories-core/types/story';
 export { DocEntry, DocPhase, NormalizedTicket, STORY_META_KEY, StepKeyword, StepMode, StoryMeta, StoryStep } from 'executable-stories-core/types/story';
 import { CIInfo, CIProvider } from 'executable-stories-core/types/ci';
@@ -8,11 +8,15 @@ import { adaptJestRun, adaptPlaywrightRun, adaptVitestRun } from './adapters.js'
 export { JestAdapterOptions, JestAggregatedResult, JestFileResult, JestTestResult, PlaywrightAdapterOptions, PlaywrightAnnotation, PlaywrightAttachment, PlaywrightError, PlaywrightLocation, PlaywrightStatus, PlaywrightTestCase, PlaywrightTestResult, StoryFileReport, VitestAdapterOptions, VitestSerializedError, VitestState, VitestTestCase, VitestTestModule, VitestTestResult } from './adapters.js';
 export { OtelAttributeValue, OtelSpan } from 'executable-stories-core/types/otel';
 import { RawCIInfo } from 'executable-stories-core/types/raw';
-export { RawAttachment, RawCIInfo, RawRun, RawStatus, RawStepEvent, RawTestCase } from 'executable-stories-core/types/raw';
+export { RawAttachment, RawCIInfo, RawFeature, RawGlossaryTerm, RawRun, RawStatus, RawStepEvent, RawTestCase } from 'executable-stories-core/types/raw';
 import { StoryReport, TestStatus as TestStatus$1, ReportStep } from 'executable-stories-core/types/story-report';
 export { ReportAttachment, ReportCIInfo, ReportCoverageSummary, ReportDocCode, ReportDocCustom, ReportDocEntry, ReportDocKv, ReportDocLink, ReportDocMermaid, ReportDocNote, ReportDocScreenshot, ReportDocSection, ReportDocTable, ReportDocTag, ReportFeature, ReportScenario, ReportStep, ReportSummary, ReportTicket, STORY_REPORT_SCHEMA_MAJOR, STORY_REPORT_SCHEMA_VERSION, StoryReport, StoryReportSchemaVersion } from 'executable-stories-core/types/story-report';
 export { ES_THEME_TOKENS_CSS, ES_THEME_TOKEN_VALUES } from 'executable-stories-core/theme/tokens';
-export { canonicalizeRun, deriveStepResults, generateRunId, generateTestCaseId, mergeStepResults, normalizeStatus, resolveAttachment, resolveAttachments, slugify } from 'executable-stories-core/converters/acl/index';
+export { canonicalizeRun } from 'executable-stories-core/converters/acl/canonicalize';
+export { normalizeStatus } from 'executable-stories-core/converters/acl/status';
+export { generateRunId, generateTestCaseId, slugify } from 'executable-stories-core/converters/acl/ids';
+export { deriveStepResults, mergeStepResults } from 'executable-stories-core/converters/acl/steps';
+export { resolveAttachment, resolveAttachments } from 'executable-stories-core/converters/acl/attachments';
 export { ValidationResult, assertValidRun, validateCanonicalRun } from 'executable-stories-core/converters/acl/validate';
 export { RunState, advanceState, initialRunState } from 'executable-stories-core';
 export { toStoryReport } from 'executable-stories-core/converters/story-report';
@@ -537,82 +541,6 @@ interface ResolvedFormatterOptions {
     allowMissingAssets: boolean;
 }
 
-type ScenarioChangeKind = "added" | "removed" | "renamed" | "moved" | "regressed" | "fixed" | "changed" | "unchanged";
-interface ScenarioChangeFlags {
-    status: boolean;
-    steps: boolean;
-    docs: boolean;
-    tags: boolean;
-    tickets: boolean;
-    source: boolean;
-    duration: boolean;
-    attachments: boolean;
-    error: boolean;
-    titlePath: boolean;
-}
-interface ScenarioSnapshot {
-    id: string;
-    scenario: string;
-    sourceFile: string;
-    sourceLine: number;
-    status: TestStatus;
-    durationMs: number;
-    tags: string[];
-    titlePath: string[];
-    steps: StoryStep[];
-    docs: DocEntry[];
-    tickets: NormalizedTicket[];
-    attachments: Attachment[];
-    errorMessage?: string;
-}
-interface ScenarioDiff {
-    kind: ScenarioChangeKind;
-    id: string;
-    scenario: string;
-    sourceFile: string;
-    sourceLine: number;
-    baseline?: ScenarioSnapshot;
-    current?: ScenarioSnapshot;
-    flags: ScenarioChangeFlags;
-    changedFields: string[];
-    durationDeltaMs?: number;
-    /** For `renamed`/`moved`: the baseline test-case id this behaviour was matched from. */
-    previousId?: string;
-    /** For `renamed`/`moved`: match confidence in 0..1 (1 = exact content fingerprint). */
-    matchConfidence?: number;
-    /** For `renamed`/`moved`: how the baseline/current pair was re-identified. */
-    matchedBy?: "fingerprint" | "similarity";
-}
-interface RunDiffSummary {
-    totalBaseline: number;
-    totalCurrent: number;
-    added: number;
-    removed: number;
-    /** Behaviours re-identified across a title change (content preserved). */
-    renamed: number;
-    /** Behaviours re-identified across a file move (content preserved). */
-    moved: number;
-    changed: number;
-    regressed: number;
-    fixed: number;
-    unchanged: number;
-    /**
-     * Baseline scenarios skipped because the current run is partial and never
-     * touched their source file. Always 0 for a full-run diff.
-     */
-    notRun: number;
-}
-interface RunDiffResult {
-    baseline: TestRunResult;
-    current: TestRunResult;
-    summary: RunDiffSummary;
-    scenarios: ScenarioDiff[];
-}
-type CompareFormat = "html" | "markdown" | "changelog";
-interface CompareFormatterOptions {
-    title?: string;
-}
-
 /**
  * Cucumber JSON format types.
  *
@@ -727,7 +655,7 @@ interface IJsonFeature {
  * between them and a vendor API.
  *
  * Adding a provider is one file in `adapters/` plus one line in
- * `adapters/index.ts`, with no edits to `engine.ts`. If a new adapter forces an
+ * `adapters/registry.ts`, with no edits to `engine.ts`. If a new adapter forces an
  * engine change, this port is wrong and gets fixed then, on evidence.
  *
  * Every method except `listCases` is optional. A read-only provider implements
@@ -1289,6 +1217,82 @@ declare function renderPlan(analysis: SyncAnalysis, opts: {
 /** What actually happened, printed after a real run. */
 declare function renderApplyResult(result: SyncApplyResult): string;
 
+type ScenarioChangeKind = "added" | "removed" | "renamed" | "moved" | "regressed" | "fixed" | "changed" | "unchanged";
+interface ScenarioChangeFlags {
+    status: boolean;
+    steps: boolean;
+    docs: boolean;
+    tags: boolean;
+    tickets: boolean;
+    source: boolean;
+    duration: boolean;
+    attachments: boolean;
+    error: boolean;
+    titlePath: boolean;
+}
+interface ScenarioSnapshot {
+    id: string;
+    scenario: string;
+    sourceFile: string;
+    sourceLine: number;
+    status: TestStatus;
+    durationMs: number;
+    tags: string[];
+    titlePath: string[];
+    steps: StoryStep[];
+    docs: DocEntry[];
+    tickets: NormalizedTicket[];
+    attachments: Attachment[];
+    errorMessage?: string;
+}
+interface ScenarioDiff {
+    kind: ScenarioChangeKind;
+    id: string;
+    scenario: string;
+    sourceFile: string;
+    sourceLine: number;
+    baseline?: ScenarioSnapshot;
+    current?: ScenarioSnapshot;
+    flags: ScenarioChangeFlags;
+    changedFields: string[];
+    durationDeltaMs?: number;
+    /** For `renamed`/`moved`: the baseline test-case id this behaviour was matched from. */
+    previousId?: string;
+    /** For `renamed`/`moved`: match confidence in 0..1 (1 = exact content fingerprint). */
+    matchConfidence?: number;
+    /** For `renamed`/`moved`: how the baseline/current pair was re-identified. */
+    matchedBy?: "fingerprint" | "similarity";
+}
+interface RunDiffSummary {
+    totalBaseline: number;
+    totalCurrent: number;
+    added: number;
+    removed: number;
+    /** Behaviours re-identified across a title change (content preserved). */
+    renamed: number;
+    /** Behaviours re-identified across a file move (content preserved). */
+    moved: number;
+    changed: number;
+    regressed: number;
+    fixed: number;
+    unchanged: number;
+    /**
+     * Baseline scenarios skipped because the current run is partial and never
+     * touched their source file. Always 0 for a full-run diff.
+     */
+    notRun: number;
+}
+interface RunDiffResult {
+    baseline: TestRunResult;
+    current: TestRunResult;
+    summary: RunDiffSummary;
+    scenarios: ScenarioDiff[];
+}
+type CompareFormat = "html" | "markdown" | "changelog";
+interface CompareFormatterOptions {
+    title?: string;
+}
+
 /**
  * Diff types — parsed unified patches and content-anchored annotation targets.
  *
@@ -1997,6 +2001,10 @@ declare class MarkdownFormatter {
      * Render scenarios grouped by file.
      */
     private renderByFile;
+    /**
+     * Render what a feature is for, ahead of the scenarios that prove it.
+     */
+    private renderFeatureDeclaration;
     /**
      * Render scenarios grouped by suite path.
      */
@@ -2717,6 +2725,19 @@ interface CheckFailure {
     /** True when this scenario was passing in the baseline run. */
     regressed: boolean;
 }
+/**
+ * A scenario that is switched off: skipped or pending, but not `it.todo`.
+ * A planned scenario is a spec waiting for code; a turned-off one is a spec
+ * you stopped validating, and the pack forgets it exists unless it is named.
+ */
+interface CheckTurnedOff {
+    id: string;
+    scenario: string;
+    /** `sourceFile:sourceLine` */
+    location: string;
+    status: "skipped" | "pending";
+    tickets: string[];
+}
 interface CheckReport {
     summary: {
         total: number;
@@ -2726,6 +2747,8 @@ interface CheckReport {
         pending: number;
     };
     failures: CheckFailure[];
+    /** Scenarios switched off — named, not just counted (see {@link CheckTurnedOff}). */
+    turnedOff: CheckTurnedOff[];
     /** Count of scenarios that went passed → failed vs. the baseline. */
     regressed: number;
     /** Count of scenarios that went failed → passed vs. the baseline. */
@@ -2844,7 +2867,100 @@ type TriageDeps = Record<string, never>;
 declare function buildTriage(args: TriageArgs, _deps?: TriageDeps): TriageReport;
 declare function renderTriage(report: TriageReport, format: "text" | "json"): string;
 
-declare function createPrCommentSummary(diff: RunDiffResult, maxScenarios?: number): string;
+/**
+ * ReportGenerator — turns a canonical TestRunResult into report files.
+ *
+ * Its own module rather than part of the package barrel: `watch.ts` needs the
+ * generator, and reaching for it through `./index` would pull every formatter
+ * and the React SSR path into that module's graph.
+ */
+
+/** Arguments for generate function */
+interface GenerateArgs {
+    /** Canonical test run result */
+    run: TestRunResult;
+    /** Optional options override */
+    options?: FormatterOptions;
+}
+/** Dependencies for generate function (injectable for testing) */
+interface GenerateDeps {
+    /** Logger for warnings */
+    logger: Logger;
+    /** File writer function */
+    writeFile: WriteFile;
+}
+/** Result of generate function: Map of format to array of file paths */
+type GenerateResult = Map<OutputFormat, string[]>;
+interface GenerateCompareResult {
+    files: string[];
+    diff: RunDiffResult;
+}
+/**
+ * Join an output name with a format extension, collapsing a stutter when the
+ * chosen name already carries the format's tag. With the default name "index",
+ * `story-report-json` writes `index.story-report.json`; but if the caller names
+ * the file `story-report`, this yields `story-report.json`, not
+ * `story-report.story-report.json`.
+ */
+declare function joinNameAndExt(name: string, ext: string): string;
+/**
+ * Normalise input formats to canonical {@link OutputFormat}s. Accepts the
+ * deprecated `"astro"` alias (renamed to `"astro-markdown"`) and warns once per
+ * process — so programmatic/config callers passing `"astro"` keep working
+ * instead of throwing, matching the CLI's deprecation behaviour.
+ */
+declare function normalizeFormats(formats: ReadonlyArray<FormatInput>): OutputFormat[];
+declare class ReportGenerator {
+    private options;
+    private deps;
+    constructor(options?: FormatterOptions, deps?: Partial<GenerateDeps>);
+    /**
+     * Resolve options with defaults.
+     */
+    private resolveOptions;
+    /**
+     * Generate reports for a test run.
+     *
+     * @param run - Canonical TestRunResult (use canonicalizeRun to create from RawRun)
+     * @returns Map of output format to generated file paths
+     */
+    generate(run: TestRunResult): Promise<GenerateResult>;
+    /**
+     * Whether any output is colocated — the global mode, or any per-rule mode.
+     * A colocated rule under a global aggregated mode still writes per-file
+     * reports that need an index.
+     */
+    private hasColocatedOutput;
+    /**
+     * Write the entry-point page for a colocated HTML report tree. `htmlPaths` is
+     * every HTML report already written this run. Returns the path written, or
+     * undefined when there is nothing to index or the index would clobber a report
+     * already at `index.html` — a colocated source file that produces it, or, in
+     * mixed mode, the global aggregate (whose default output name is also index).
+     */
+    private writeColocatedIndex;
+    /**
+     * Generate reports for a single format.
+     */
+    private generateFormat;
+    /**
+     * Format content for a specific format.
+     */
+    private formatContent;
+    /**
+     * Render a standalone HTML report via the shared React component tree
+     * (executable-stories-react). This is the same renderer the Astro docs site
+     * uses, so the two outputs cannot drift. Imported lazily so React stays out
+     * of the eager bundle unless this format is requested.
+     */
+    private formatHtmlReact;
+}
+/**
+ * Factory function to create a ReportGenerator with dependency injection.
+ *
+ * Useful for testing and custom configurations.
+ */
+declare function createReportGenerator(options?: FormatterOptions, deps?: Partial<GenerateDeps>): ReportGenerator;
 
 interface DiffRunsOptions {
     /**
@@ -2861,6 +2977,8 @@ interface DiffRunsOptions {
 }
 declare function diffRuns(baseline: TestRunResult, current: TestRunResult, options?: DiffRunsOptions): RunDiffResult;
 
+declare function createPrCommentSummary(diff: RunDiffResult, maxScenarios?: number): string;
+
 /**
  * Review domain — `buildReview(run, context)` mirrors `diffRuns(baseline, current)`.
  *
@@ -3239,92 +3357,6 @@ declare function toTraceabilityMatrix(run: TestRunResult): TraceabilityMatrix;
  *   HTML report renders via executable-stories-react — the `html` format)
  */
 
-/** Arguments for generate function */
-interface GenerateArgs {
-    /** Canonical test run result */
-    run: TestRunResult;
-    /** Optional options override */
-    options?: FormatterOptions;
-}
-/** Dependencies for generate function (injectable for testing) */
-interface GenerateDeps {
-    /** Logger for warnings */
-    logger: Logger;
-    /** File writer function */
-    writeFile: WriteFile;
-}
-/** Result of generate function: Map of format to array of file paths */
-type GenerateResult = Map<OutputFormat, string[]>;
-interface GenerateCompareResult {
-    files: string[];
-    diff: RunDiffResult;
-}
-/**
- * Join an output name with a format extension, collapsing a stutter when the
- * chosen name already carries the format's tag. With the default name "index",
- * `story-report-json` writes `index.story-report.json`; but if the caller names
- * the file `story-report`, this yields `story-report.json`, not
- * `story-report.story-report.json`.
- */
-declare function joinNameAndExt(name: string, ext: string): string;
-/**
- * Normalise input formats to canonical {@link OutputFormat}s. Accepts the
- * deprecated `"astro"` alias (renamed to `"astro-markdown"`) and warns once per
- * process — so programmatic/config callers passing `"astro"` keep working
- * instead of throwing, matching the CLI's deprecation behaviour.
- */
-declare function normalizeFormats(formats: ReadonlyArray<FormatInput>): OutputFormat[];
-declare class ReportGenerator {
-    private options;
-    private deps;
-    constructor(options?: FormatterOptions, deps?: Partial<GenerateDeps>);
-    /**
-     * Resolve options with defaults.
-     */
-    private resolveOptions;
-    /**
-     * Generate reports for a test run.
-     *
-     * @param run - Canonical TestRunResult (use canonicalizeRun to create from RawRun)
-     * @returns Map of output format to generated file paths
-     */
-    generate(run: TestRunResult): Promise<GenerateResult>;
-    /**
-     * Whether any output is colocated — the global mode, or any per-rule mode.
-     * A colocated rule under a global aggregated mode still writes per-file
-     * reports that need an index.
-     */
-    private hasColocatedOutput;
-    /**
-     * Write the entry-point page for a colocated HTML report tree. `htmlPaths` is
-     * every HTML report already written this run. Returns the path written, or
-     * undefined when there is nothing to index or the index would clobber a report
-     * already at `index.html` — a colocated source file that produces it, or, in
-     * mixed mode, the global aggregate (whose default output name is also index).
-     */
-    private writeColocatedIndex;
-    /**
-     * Generate reports for a single format.
-     */
-    private generateFormat;
-    /**
-     * Format content for a specific format.
-     */
-    private formatContent;
-    /**
-     * Render a standalone HTML report via the shared React component tree
-     * (executable-stories-react). This is the same renderer the Astro docs site
-     * uses, so the two outputs cannot drift. Imported lazily so React stays out
-     * of the eager bundle unless this format is requested.
-     */
-    private formatHtmlReact;
-}
-/**
- * Factory function to create a ReportGenerator with dependency injection.
- *
- * Useful for testing and custom configurations.
- */
-declare function createReportGenerator(options?: FormatterOptions, deps?: Partial<GenerateDeps>): ReportGenerator;
 declare function generateRunComparison(args: {
     baseline: TestRunResult;
     current: TestRunResult;