executable-stories-formatters 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1468 @@
+import { S as StoryMeta, a as StoryStep, D as DocEntry, R as RawStatus, b as RawAttachment, c as RawRun, d as RawCIInfo, e as adaptJestRun, f as adaptPlaywrightRun, g as adaptVitestRun } from './index-DCJ0NvAp.js';
+export { h as DocPhase, J as JestAdapterOptions, i as JestAggregatedResult, j as JestFileResult, k as JestTestResult, P as PlaywrightAdapterOptions, l as PlaywrightAnnotation, m as PlaywrightAttachment, n as PlaywrightError, o as PlaywrightLocation, p as PlaywrightStatus, q as PlaywrightTestCase, r as PlaywrightTestResult, s as RawStepEvent, t as RawTestCase, u as STORY_META_KEY, v as StepKeyword, w as StepMode, x as StoryFileReport, V as VitestAdapterOptions, y as VitestSerializedError, z as VitestState, A as VitestTestCase, B as VitestTestModule, C as VitestTestResult } from './index-DCJ0NvAp.js';
+
+/**
+ * Canonical types for Layer 2: Anti-Corruption Layer output.
+ *
+ * These types are strict and have all required fields populated.
+ * Formatters (Layer 3) accept only these canonical types.
+ */
+
+/** Canonical test status (Cucumber-compatible) */
+type TestStatus = "passed" | "failed" | "skipped" | "pending";
+/** Step result with status and timing */
+interface StepResult {
+    /** Step index (0-based) */
+    index: number;
+    /** Step status */
+    status: TestStatus;
+    /** Duration in milliseconds (default 0) */
+    durationMs: number;
+    /** Error message if step failed */
+    errorMessage?: string;
+}
+/** Resolved attachment (always has body) */
+interface Attachment {
+    /** Attachment name */
+    name: string;
+    /** MIME type */
+    mediaType: string;
+    /** Content (base64-encoded or URL) */
+    body: string;
+    /** Content encoding */
+    contentEncoding: "BASE64" | "IDENTITY";
+}
+/** Single test attempt for retry tracking */
+interface TestCaseAttempt {
+    /** Attempt number (0-based) */
+    attempt: number;
+    /** Status of this attempt */
+    status: TestStatus;
+    /** Duration of this attempt in milliseconds */
+    durationMs: number;
+    /** Error message if this attempt failed */
+    errorMessage?: string;
+    /** Error stack trace if this attempt failed */
+    errorStack?: string;
+}
+/** Canonical test case result */
+interface TestCaseResult {
+    /** Unique deterministic ID */
+    id: string;
+    /** Story metadata (required) */
+    story: StoryMeta;
+    /** Source file path (required) */
+    sourceFile: string;
+    /** Source line number (required, default 1) */
+    sourceLine: number;
+    /** Test status (required) */
+    status: TestStatus;
+    /** Duration in milliseconds (required, default 0) */
+    durationMs: number;
+    /** Error message if failed */
+    errorMessage?: string;
+    /** Error stack trace if failed */
+    errorStack?: string;
+    /** Attachments (required, empty array if none) */
+    attachments: Attachment[];
+    /** Step results (required, always populated via fallback rules) */
+    stepResults: StepResult[];
+    /** Full title path from suite/describe blocks (required, empty array if none) */
+    titlePath: string[];
+    /** Playwright project name (optional) */
+    projectName?: string;
+    /** Retry attempt number (required, default 0) */
+    retry: number;
+    /** Total retries configured (required, default 0) */
+    retries: number;
+    /** Normalized tags from story (required, empty array if none) */
+    tags: string[];
+    /** All retry attempts (optional, includes details per attempt) */
+    attempts?: TestCaseAttempt[];
+}
+/** CI environment info */
+interface CIInfo {
+    name: string;
+    url?: string;
+    buildNumber?: string;
+}
+/** Coverage summary for the test run */
+interface CoverageSummary {
+    /** Line coverage percentage (0-100) */
+    linesPct?: number;
+    /** Branch coverage percentage (0-100) */
+    branchesPct?: number;
+    /** Function coverage percentage (0-100) */
+    functionsPct?: number;
+    /** Statement coverage percentage (0-100) */
+    statementsPct?: number;
+}
+/** Canonical test run result */
+interface TestRunResult {
+    /** All test case results */
+    testCases: TestCaseResult[];
+    /** Run start time (epoch ms, required) */
+    startedAtMs: number;
+    /** Run finish time (epoch ms, required) */
+    finishedAtMs: number;
+    /** Total duration in milliseconds (required) */
+    durationMs: number;
+    /** Project root directory (required) */
+    projectRoot: string;
+    /** Unique run ID (required, generated) */
+    runId: string;
+    /** Package version */
+    packageVersion?: string;
+    /** Git commit SHA */
+    gitSha?: string;
+    /** CI environment info */
+    ci?: CIInfo;
+    /** Coverage summary for the run */
+    coverage?: CoverageSummary;
+}
+
+/**
+ * Configuration options for ACL and formatters.
+ */
+/** Options for canonicalizing raw run data */
+interface CanonicalizeOptions {
+    /** Attachment handling options */
+    attachments?: {
+        /** Max bytes before attachment becomes external link. Default: 512KB (524288) */
+        maxEmbedBytes?: number;
+        /** Directory for external attachments */
+        externalDir?: string;
+    };
+    /** Cucumber compatibility options */
+    cucumber?: {
+        /** Include trailing space in keywords (e.g., "Given "). Default: true */
+        keywordSpacing?: boolean;
+        /** Generate deterministic line numbers. Default: true */
+        deterministicLines?: boolean;
+    };
+    /** Default timestamps if not provided in raw data */
+    defaults?: {
+        /** Default start time (epoch ms). Default: Date.now() */
+        startedAtMs?: number;
+        /** Default finish time (epoch ms). Default: Date.now() */
+        finishedAtMs?: number;
+    };
+}
+/** Output format for report generation */
+type OutputFormat = "cucumber-json" | "cucumber-messages" | "cucumber-html" | "html" | "junit" | "markdown";
+/** Output mode for report routing */
+type OutputMode = "aggregated" | "colocated";
+/** Colocated output style */
+type ColocatedStyle = "mirrored" | "adjacent";
+/** Output rule for routing reports based on source file patterns */
+interface OutputRule {
+    /** Glob pattern to match sourceFile (uses micromatch, forward slashes) */
+    match: string;
+    /** Output mode for matched files */
+    mode?: OutputMode;
+    /** Colocated style (only applicable when mode is "colocated") */
+    colocatedStyle?: ColocatedStyle;
+    /** Output directory override */
+    outputDir?: string;
+    /** Output filename override (without extension) */
+    outputName?: string;
+    /** Formats to generate for matched files */
+    formats?: OutputFormat[];
+}
+/** Output configuration for report routing */
+interface OutputConfig {
+    /** Default output mode. Default: "aggregated" */
+    mode?: OutputMode;
+    /** Default colocated style. Default: "mirrored" */
+    colocatedStyle?: ColocatedStyle;
+    /** Rules for routing reports based on source file patterns */
+    rules?: OutputRule[];
+    /** Default output filename (without extension) */
+    outputName?: string;
+}
+/** Logger interface for dependency injection */
+interface Logger {
+    warn(msg: string): void;
+}
+/** File writer function type for dependency injection */
+type WriteFile = (path: string, contents: string) => Promise<void>;
+/** Formatter options for report generation */
+interface FormatterOptions {
+    /** Glob patterns to include test cases by sourceFile (forward slashes). If empty, all are considered. */
+    include?: string[];
+    /** Glob patterns to exclude test cases by sourceFile (forward slashes). Applied after include. */
+    exclude?: string[];
+    /** Output formats to generate. Default: ["cucumber-json"] */
+    formats?: OutputFormat[];
+    /** Output directory for generated reports. Default: "reports" */
+    outputDir?: string;
+    /** Base filename (without extension). Default: "test-results" */
+    outputName?: string;
+    /** Output routing configuration */
+    output?: OutputConfig;
+    /** Cucumber JSON specific options */
+    cucumberJson?: {
+        /** Pretty-print JSON output. Default: false */
+        pretty?: boolean;
+    };
+    /** HTML specific options */
+    html?: {
+        /** Report title. Default: "Test Results" */
+        title?: string;
+        /** Include dark mode toggle. Default: true */
+        darkMode?: boolean;
+        /** Include search/filter functionality. Default: true */
+        searchable?: boolean;
+        /** Start with scenarios collapsed. Default: false */
+        startCollapsed?: boolean;
+        /** Embed screenshots inline (base64). Default: true */
+        embedScreenshots?: boolean;
+        /** Enable syntax highlighting for code blocks (via highlight.js CDN). Default: true */
+        syntaxHighlighting?: boolean;
+        /** Enable live Mermaid diagram rendering (via Mermaid.js CDN). Default: true */
+        mermaidEnabled?: boolean;
+        /** Enable Markdown parsing for section doc entries (via marked.js CDN). Default: true */
+        markdownEnabled?: boolean;
+    };
+    /** JUnit XML specific options */
+    junit?: {
+        /** Test suite name. Default: "Test Suite" */
+        suiteName?: string;
+        /** Include system-out/system-err. Default: true */
+        includeOutput?: boolean;
+    };
+    /** Cucumber Messages (NDJSON) specific options */
+    cucumberMessages?: {
+        /** Strategy for deriving Source.uri. Default: "sourceFile" */
+        uriStrategy?: "sourceFile" | "virtual";
+        /** Whether to emit Source/GherkinDocument for synthesized features. Default: true */
+        includeSynthetics?: boolean;
+        /** Salt for deterministic IDs. Default: "" */
+        idSalt?: string;
+        /** Tool metadata for Meta envelope */
+        meta?: {
+            toolName?: string;
+            toolVersion?: string;
+        };
+    };
+    /** Markdown specific options */
+    markdown?: MarkdownFormatterOptions;
+    /** Logger for warnings and info. Default: console */
+    logger?: Logger;
+    /** File writer function. Default: fs.promises.writeFile */
+    writeFile?: WriteFile;
+}
+/** Markdown formatter options (extended for feature parity) */
+interface MarkdownFormatterOptions {
+    /** Report title. Default: "User Stories" */
+    title?: string;
+    /** Include status icons. Default: true */
+    includeStatusIcons?: boolean;
+    /** Include metadata table. Default: true */
+    includeMetadata?: boolean;
+    /** Include error details. Default: true */
+    includeErrors?: boolean;
+    /** Scenario heading level. Default: 3 */
+    scenarioHeadingLevel?: 2 | 3 | 4;
+    /** Step style. Default: "bullets" */
+    stepStyle?: "bullets" | "gherkin";
+    /** Group scenarios by. Default: "file" */
+    groupBy?: "file" | "suite" | "none";
+    /** Sort scenarios. Default: "source" */
+    sortScenarios?: "alpha" | "source" | "none";
+    /** Suite path separator. Default: " - " */
+    suiteSeparator?: string;
+    /** Include YAML front-matter for machine parsing. Default: false */
+    includeFrontMatter?: boolean;
+    /** Include summary table (counts, duration). Default: false */
+    includeSummaryTable?: boolean;
+    /** Base URL for source permalinks. E.g., "https://github.com/user/repo/blob" */
+    permalinkBaseUrl?: string;
+    /** URL template for ticket links. Use {ticket} as placeholder. E.g., "https://jira.example.com/browse/{ticket}" */
+    ticketUrlTemplate?: string;
+    /** Include source links when permalinkBaseUrl is set. Default: true */
+    includeSourceLinks?: boolean;
+    /** Custom renderers for doc entries */
+    customRenderers?: MarkdownRenderers;
+}
+
+/** Custom renderers for markdown doc entries */
+interface MarkdownRenderers {
+    /** Custom renderer for scenario header */
+    renderScenarioHeader?: (tc: TestCaseResult) => string | null;
+    /** Custom renderer for step */
+    renderStep?: (step: StoryStep) => string | null;
+    /** Custom renderer for doc entry */
+    renderDocEntry?: (entry: DocEntry) => string | null;
+    /** Custom renderer for footer */
+    renderFooter?: (run: TestRunResult) => string | null;
+}
+/** Resolved formatter options with all defaults applied */
+interface ResolvedFormatterOptions {
+    include: string[];
+    exclude: string[];
+    formats: OutputFormat[];
+    outputDir: string;
+    outputName: string;
+    output: {
+        mode: OutputMode;
+        colocatedStyle: ColocatedStyle;
+        rules: OutputRule[];
+        outputName?: string;
+    };
+    cucumberJson: {
+        pretty: boolean;
+    };
+    cucumberMessages: {
+        uriStrategy: "sourceFile" | "virtual";
+        includeSynthetics: boolean;
+        idSalt: string;
+        meta?: {
+            toolName?: string;
+            toolVersion?: string;
+        };
+    };
+    html: {
+        title: string;
+        darkMode: boolean;
+        searchable: boolean;
+        startCollapsed: boolean;
+        embedScreenshots: boolean;
+        syntaxHighlighting: boolean;
+        mermaidEnabled: boolean;
+        markdownEnabled: boolean;
+    };
+    junit: {
+        suiteName: string;
+        includeOutput: boolean;
+    };
+    markdown: {
+        title: string;
+        includeStatusIcons: boolean;
+        includeMetadata: boolean;
+        includeErrors: boolean;
+        scenarioHeadingLevel: 2 | 3 | 4;
+        stepStyle: "bullets" | "gherkin";
+        groupBy: "file" | "suite" | "none";
+        sortScenarios: "alpha" | "source" | "none";
+        suiteSeparator: string;
+        includeFrontMatter: boolean;
+        includeSummaryTable: boolean;
+        permalinkBaseUrl?: string;
+        ticketUrlTemplate?: string;
+        includeSourceLinks: boolean;
+        customRenderers?: MarkdownRenderers;
+    };
+}
+
+/**
+ * Cucumber JSON format types.
+ *
+ * Based on cucumber-js v11.x JSON formatter output.
+ * @see https://github.com/cucumber/cucumber-js/blob/main/src/formatter/json_formatter.ts
+ */
+/** Cucumber JSON tag */
+interface IJsonTag {
+    name: string;
+    line?: number;
+}
+/** Cucumber JSON doc string (step argument) */
+interface IJsonDocString {
+    content: string;
+    content_type?: string;
+    line: number;
+}
+/** Cucumber JSON data table row */
+interface IJsonTableRow {
+    cells: string[];
+}
+/** Cucumber JSON data table (step argument) */
+interface IJsonDataTable {
+    rows: IJsonTableRow[];
+}
+/** Cucumber JSON step argument */
+interface IJsonStepArgument {
+    doc_string?: IJsonDocString;
+    rows?: IJsonTableRow[];
+}
+/** Cucumber JSON embedding (attachment) */
+interface IJsonEmbedding {
+    data: string;
+    mime_type: string;
+    name?: string;
+}
+/** Cucumber JSON step result */
+interface IJsonStepResult {
+    /** Duration in nanoseconds */
+    duration?: number;
+    /** Error message if failed */
+    error_message?: string;
+    /** Status string */
+    status: "passed" | "failed" | "skipped" | "pending" | "undefined" | "ambiguous";
+}
+/** Cucumber JSON step */
+interface IJsonStep {
+    /** Step arguments (doc strings, data tables) */
+    arguments?: IJsonStepArgument[];
+    /** Embeddings (attachments) */
+    embeddings?: IJsonEmbedding[];
+    /** Step keyword with trailing space (e.g., "Given ") */
+    keyword: string;
+    /** Hidden step (background step, hook) */
+    hidden?: boolean;
+    /** Line number in feature file */
+    line: number;
+    /** Match info (step definition location) */
+    match?: {
+        location?: string;
+    };
+    /** Step name/text */
+    name: string;
+    /** Step result */
+    result: IJsonStepResult;
+}
+/** Cucumber JSON scenario (element) */
+interface IJsonScenario {
+    /** Scenario description */
+    description: string;
+    /** Scenario ID (slugified) */
+    id: string;
+    /** Scenario keyword */
+    keyword: string;
+    /** Line number in feature file */
+    line: number;
+    /** Scenario name */
+    name: string;
+    /** Scenario steps */
+    steps: IJsonStep[];
+    /** Scenario tags */
+    tags: IJsonTag[];
+    /** Element type (always "scenario" for us) */
+    type: "scenario" | "background";
+}
+/** Cucumber JSON feature */
+interface IJsonFeature {
+    /** Feature description */
+    description: string;
+    /** Feature elements (scenarios) */
+    elements: IJsonScenario[];
+    /** Feature ID (slugified) */
+    id: string;
+    /** Feature keyword */
+    keyword: string;
+    /** Line number (typically 1) */
+    line: number;
+    /** Feature name */
+    name: string;
+    /** Feature tags */
+    tags: IJsonTag[];
+    /** Feature file URI/path */
+    uri: string;
+}
+
+/**
+ * Status mapping from raw framework statuses to canonical TestStatus.
+ */
+
+/**
+ * Convert a raw status to canonical TestStatus.
+ *
+ * @param raw - The raw status from a framework
+ * @returns The canonical TestStatus
+ */
+declare function normalizeStatus(raw: RawStatus): TestStatus;
+
+/**
+ * ID generation and slug helpers for deterministic, Cucumber-compatible IDs.
+ */
+/**
+ * Generate a deterministic test case ID from source file and scenario name.
+ *
+ * @param sourceFile - The source file path
+ * @param scenario - The scenario name
+ * @returns A 12-character hex ID
+ */
+declare function generateTestCaseId(sourceFile: string, scenario: string): string;
+/**
+ * Generate a deterministic run ID from timestamp and project root.
+ *
+ * @param startedAtMs - Run start timestamp
+ * @param projectRoot - Project root directory
+ * @returns A 16-character hex ID
+ */
+declare function generateRunId(startedAtMs: number, projectRoot: string): string;
+/**
+ * Slugify a string for Cucumber JSON IDs.
+ *
+ * Converts to lowercase, replaces path separators/spaces with hyphens,
+ * removes other special chars, and trims leading/trailing hyphens.
+ *
+ * @param text - The text to slugify
+ * @returns A URL-safe slug
+ */
+declare function slugify(text: string): string;
+
+/**
+ * Step fallback rules for deriving step results from scenario status.
+ *
+ * When frameworks don't provide step-level results, we derive them
+ * from the overall scenario status using these rules.
+ */
+
+/**
+ * Derive step results from story steps and scenario status.
+ *
+ * Rules:
+ * - Passed: All steps are passed
+ * - Skipped/Pending: All steps are skipped/pending
+ * - Failed: Steps up to failure are passed, failing step is failed, rest are skipped
+ *   (Heuristic: last step is the failure, or use error info if available)
+ *
+ * @param steps - Story steps with keywords and text
+ * @param scenarioStatus - Overall scenario status
+ * @param error - Optional error information to help identify failing step
+ * @returns Array of step results
+ */
+declare function deriveStepResults(steps: StoryStep[], scenarioStatus: TestStatus, error?: {
+    message?: string;
+    stack?: string;
+}): StepResult[];
+/**
+ * Merge raw step events with derived step results.
+ *
+ * When we have partial step data from the framework, merge it with
+ * the derived results, preferring actual data over derived.
+ *
+ * @param derived - Derived step results from fallback rules
+ * @param events - Raw step events from framework (if any)
+ * @returns Merged step results
+ */
+declare function mergeStepResults(derived: StepResult[], events?: Array<{
+    index?: number;
+    status?: string;
+    durationMs?: number;
+    errorMessage?: string;
+}>): StepResult[];
+
+/**
+ * Attachment resolution: embed vs link decision.
+ *
+ * Attachments can either be embedded inline (base64) or linked to
+ * external files based on size thresholds.
+ */
+
+/** Options for attachment resolution */
+interface AttachmentOptions {
+    /** Max bytes before attachment becomes external link. Default: 512KB */
+    maxEmbedBytes?: number;
+    /** Directory for external attachments */
+    externalDir?: string;
+    /** Project root for relative paths */
+    projectRoot?: string;
+}
+/**
+ * Resolve a raw attachment to a canonical attachment.
+ *
+ * Decision logic:
+ * 1. If body is already provided, use it (check size for encoding decision)
+ * 2. If path is provided, read file and decide embed vs link
+ * 3. For large files, return a URL reference instead of embedding
+ *
+ * @param raw - Raw attachment from framework
+ * @param options - Resolution options
+ * @returns Resolved canonical attachment
+ */
+declare function resolveAttachment(raw: RawAttachment, options?: AttachmentOptions): Attachment;
+/**
+ * Resolve multiple attachments.
+ *
+ * @param attachments - Raw attachments array
+ * @param options - Resolution options
+ * @returns Resolved canonical attachments
+ */
+declare function resolveAttachments(attachments: RawAttachment[] | undefined, options?: AttachmentOptions): Attachment[];
+
+/**
+ * Anti-Corruption Layer (ACL) - Layer 2.
+ *
+ * Transforms permissive RawRun data from framework adapters into
+ * strict canonical TestRunResult for formatters.
+ */
+
+/**
+ * Canonicalize a raw run into a strict TestRunResult.
+ *
+ * This is the main entry point for the ACL. It:
+ * - Enforces required fields with defaults
+ * - Normalizes statuses to TestStatus enum
+ * - Applies step fallback rules
+ * - Resolves attachments (embed vs link)
+ * - Generates deterministic IDs
+ *
+ * @param raw - Raw run data from a framework adapter
+ * @param options - Canonicalization options
+ * @returns Strict canonical TestRunResult
+ */
+declare function canonicalizeRun(raw: RawRun, options?: CanonicalizeOptions): TestRunResult;
+
+/**
+ * Validation helpers for canonical TestRunResult.
+ *
+ * Used in tests to verify ACL output meets all invariants.
+ */
+
+/** Validation result */
+interface ValidationResult {
+    /** Whether the run is valid */
+    valid: boolean;
+    /** List of validation errors */
+    errors: string[];
+}
+/**
+ * Validate a canonical TestRunResult.
+ *
+ * Checks:
+ * - All required fields are present
+ * - stepResults length matches story.steps length
+ * - stepResults indexes are valid and unique
+ * - Durations are non-negative
+ * - Timestamps are valid
+ *
+ * @param run - The TestRunResult to validate
+ * @returns Validation result with errors if any
+ */
+declare function validateCanonicalRun(run: TestRunResult): ValidationResult;
+/**
+ * Assert that a run is valid, throwing if not.
+ *
+ * Useful in tests.
+ *
+ * @param run - The TestRunResult to validate
+ * @throws Error if validation fails
+ */
+declare function assertValidRun(run: TestRunResult): void;
+
+/**
+ * Cucumber JSON Formatter - Layer 3.
+ *
+ * Transforms canonical TestRunResult into Cucumber JSON format
+ * compatible with cucumber-js v11.x output.
+ */
+
+/** Options for Cucumber JSON formatting */
+interface CucumberJsonOptions {
+    /** Pretty-print JSON output. Default: false */
+    pretty?: boolean;
+    /** Include trailing space in keywords. Default: true */
+    keywordSpacing?: boolean;
+}
+/**
+ * Cucumber JSON Formatter.
+ *
+ * Transforms TestRunResult into an array of IJsonFeature objects
+ * that match the Cucumber JSON format specification.
+ */
+declare class CucumberJsonFormatter {
+    private options;
+    constructor(options?: CucumberJsonOptions);
+    /**
+     * Format a test run into Cucumber JSON features.
+     *
+     * Groups test cases by source file (one feature per file).
+     *
+     * @param run - Canonical test run result
+     * @returns Array of Cucumber JSON features
+     */
+    format(run: TestRunResult): IJsonFeature[];
+    /**
+     * Format and serialize to JSON string.
+     *
+     * @param run - Canonical test run result
+     * @returns JSON string
+     */
+    formatToString(run: TestRunResult): string;
+    /**
+     * Build a single feature from test cases in the same file.
+     */
+    private buildFeature;
+    /**
+     * Extract feature name from URI or test cases.
+     *
+     * Uses the top-level suite path if available, otherwise file name.
+     */
+    private extractFeatureName;
+    /**
+     * Extract feature-level tags from all test cases.
+     */
+    private extractFeatureTags;
+    /**
+     * Build a scenario from a test case.
+     */
+    private buildScenario;
+    /**
+     * Build steps from story steps and step results.
+     */
+    private buildSteps;
+    /**
+     * Build a single step.
+     */
+    private buildStep;
+    /**
+     * Build embeddings from screenshot doc entries.
+     */
+    private buildScreenshotEmbeddings;
+    /**
+     * Build step result.
+     */
+    private buildStepResult;
+    /**
+     * Build embeddings (attachments) for a step.
+     *
+     * Cucumber convention: attach to the failing step, or last step if no failure.
+     */
+    private buildEmbeddings;
+    /**
+     * Build step arguments from step docs.
+     *
+     * Converts doc entries to Cucumber step arguments (doc strings, data tables).
+     */
+    private buildStepArguments;
+    /**
+     * Convert a doc entry to a Cucumber step argument.
+     */
+    private docEntryToArgument;
+}
+
+/**
+ * HTML Formatter - Layer 3.
+ *
+ * Transforms canonical TestRunResult into a standalone HTML report.
+ * Implemented via createHtmlFormatter (fn(args, deps) pattern).
+ */
+
+/** Options for HTML formatting */
+interface HtmlOptions {
+    /** Report title. Default: "Test Results" */
+    title?: string;
+    /** Include dark mode toggle. Default: true */
+    darkMode?: boolean;
+    /** Include search/filter functionality. Default: true */
+    searchable?: boolean;
+    /** Start scenarios collapsed. Default: false */
+    startCollapsed?: boolean;
+    /** Embed screenshots inline (base64). Default: true */
+    embedScreenshots?: boolean;
+    /** Enable syntax highlighting for code blocks (via highlight.js CDN). Default: true */
+    syntaxHighlighting?: boolean;
+    /** Enable live Mermaid diagram rendering (via Mermaid.js CDN). Default: true */
+    mermaidEnabled?: boolean;
+    /** Enable Markdown parsing for section doc entries (via marked.js CDN). Default: true */
+    markdownEnabled?: boolean;
+}
+/**
+ * HTML Formatter.
+ *
+ * Transforms TestRunResult into a standalone HTML report with:
+ * - Dark/light mode toggle
+ * - Search/filter functionality
+ * - Collapsible features and scenarios
+ * - Modern, accessible design
+ *
+ * Thin wrapper around createHtmlFormatter for backward compatibility.
+ */
+declare class HtmlFormatter {
+    private formatFn;
+    constructor(options?: HtmlOptions);
+    /**
+     * Format a test run into standalone HTML.
+     *
+     * @param run - Canonical test run result
+     * @returns HTML string
+     */
+    format(run: TestRunResult): string;
+}
+
+/**
+ * JUnit XML Formatter - Layer 3.
+ *
+ * Transforms canonical TestRunResult into JUnit XML format
+ * for CI system integration.
+ */
+
+/** Options for JUnit XML formatting */
+interface JUnitOptions {
+    /** Test suite name. Default: "Test Suite" */
+    suiteName?: string;
+    /** Include system-out/system-err. Default: true */
+    includeOutput?: boolean;
+    /** Pretty-print XML output. Default: true */
+    pretty?: boolean;
+}
+/**
+ * JUnit XML Formatter.
+ *
+ * Transforms TestRunResult into JUnit XML format for CI integrations.
+ * Compatible with Jenkins, GitHub Actions, and other CI systems.
+ */
+declare class JUnitFormatter {
+    private options;
+    constructor(options?: JUnitOptions);
+    /**
+     * Format a test run into JUnit XML.
+     *
+     * @param run - Canonical test run result
+     * @returns JUnit XML string
+     */
+    format(run: TestRunResult): string;
+    /**
+     * Build a testsuite element for a file.
+     */
+    private buildTestSuite;
+    /**
+     * Build a testcase element.
+     */
+    private buildTestCase;
+    /**
+     * Build system-out content with steps and docs.
+     */
+    private buildSystemOut;
+    /**
+     * Render a step with its docs.
+     */
+    private renderStep;
+    /**
+     * Render a doc entry as plain text.
+     */
+    private renderDocEntry;
+}
+
+/**
+ * Markdown Formatter - Layer 3.
+ *
+ * Transforms canonical TestRunResult into Markdown documentation.
+ * Compatible with existing markdown output from framework reporters.
+ */
+
+/** Options for Markdown formatting */
+interface MarkdownOptions {
+    /** Report title. Default: "User Stories" */
+    title?: string;
+    /** Include status icons on scenarios. Default: true */
+    includeStatusIcons?: boolean;
+    /** Include metadata table (date, version). Default: true */
+    includeMetadata?: boolean;
+    /** Include error details for failed scenarios. Default: true */
+    includeErrors?: boolean;
+    /** Scenario heading level. Default: 3 */
+    scenarioHeadingLevel?: 2 | 3 | 4;
+    /** Step rendering style. Default: "bullets" */
+    stepStyle?: "bullets" | "gherkin";
+    /** Group scenarios by. Default: "file" */
+    groupBy?: "file" | "suite" | "none";
+    /** Sort scenarios. Default: "source" */
+    sortScenarios?: "alpha" | "source" | "none";
+    /** Suite path separator. Default: " - " */
+    suiteSeparator?: string;
+    /** Include YAML front-matter for machine parsing. Default: false */
+    includeFrontMatter?: boolean;
+    /** Include summary table (counts, duration). Default: false */
+    includeSummaryTable?: boolean;
+    /** Base URL for source permalinks. E.g., "https://github.com/user/repo/blob" */
+    permalinkBaseUrl?: string;
+    /** URL template for ticket links. Use {ticket} as placeholder */
+    ticketUrlTemplate?: string;
+    /** Include source links when permalinkBaseUrl is set. Default: true */
+    includeSourceLinks?: boolean;
+    /** Custom renderers for doc entries */
+    customRenderers?: MarkdownRenderers;
+}
+/**
+ * Markdown Formatter.
+ *
+ * Transforms TestRunResult into Markdown documentation that matches
+ * the output format of existing framework reporters.
+ */
+declare class MarkdownFormatter {
+    private options;
+    constructor(options?: MarkdownOptions);
+    /**
+     * Format a test run into Markdown.
+     *
+     * @param run - Canonical test run result
+     * @returns Markdown string
+     */
+    format(run: TestRunResult): string;
+    /**
+     * Render YAML front-matter.
+     */
+    private renderFrontMatter;
+    /**
+     * Render summary table.
+     */
+    private renderSummaryTable;
+    /**
+     * Format duration in human-readable form.
+     */
+    private formatDuration;
+    /**
+     * Render metadata table.
+     */
+    private renderMetadata;
+    /**
+     * Render scenarios grouped by file.
+     */
+    private renderByFile;
+    /**
+     * Render scenarios grouped by suite path.
+     */
+    private renderBySuite;
+    /**
+     * Render suite groups.
+     */
+    private renderSuiteGroups;
+    /**
+     * Render flat list of scenarios.
+     */
+    private renderFlatList;
+    /**
+     * Render a single scenario.
+     */
+    private renderScenario;
+    /**
+     * Render scenario body (docs, steps, errors).
+     */
+    private renderScenarioBody;
+    /**
+     * Build permalink URL for a test case.
+     */
+    private buildPermalink;
+    /**
+     * Render a step.
+     */
+    private renderStep;
+    /**
+     * Render a documentation entry.
+     */
+    private renderDocEntry;
+    /**
+     * Get status icon for a status.
+     */
+    private getStatusIcon;
+    /**
+     * Sort scenarios based on options.
+     */
+    private sortScenarios;
+    /**
+     * Sort suite groups.
+     */
+    private sortSuiteGroups;
+}
+
+/**
+ * Cucumber Messages types for NDJSON output.
+ *
+ * Minimal own types (no @cucumber/messages dependency) — consistent with
+ * the project's zero-external-deps-at-runtime approach.
+ *
+ * Based on the Cucumber Messages protocol:
+ * https://github.com/cucumber/messages
+ */
+/** Protobuf-style timestamp { seconds, nanos } */
+interface Timestamp {
+    seconds: number;
+    nanos: number;
+}
+/** Protobuf-style duration { seconds, nanos } */
+interface Duration {
+    seconds: number;
+    nanos: number;
+}
+/** Location in a source file */
+interface Location {
+    line: number;
+    column?: number;
+}
+interface Meta {
+    protocolVersion: string;
+    implementation: {
+        name: string;
+        version: string;
+    };
+    runtime: {
+        name: string;
+        version: string;
+    };
+    os: {
+        name: string;
+    };
+    cpu: {
+        name: string;
+    };
+}
+interface Source {
+    uri: string;
+    data: string;
+    mediaType: "text/x.cucumber.gherkin+plain";
+}
+interface Tag {
+    location: Location;
+    name: string;
+    id: string;
+}
+type KeywordType = "Unknown" | "Context" | "Action" | "Outcome" | "Conjunction";
+interface DocString {
+    location: Location;
+    mediaType?: string;
+    content: string;
+    delimiter: string;
+}
+interface TableCell {
+    location: Location;
+    value: string;
+}
+interface TableRow {
+    location: Location;
+    cells: TableCell[];
+    id: string;
+}
+interface DataTable {
+    location: Location;
+    rows: TableRow[];
+}
+interface Step {
+    location: Location;
+    keyword: string;
+    keywordType: KeywordType;
+    text: string;
+    id: string;
+    docString?: DocString;
+    dataTable?: DataTable;
+}
+interface Scenario {
+    location: Location;
+    tags: Tag[];
+    keyword: string;
+    name: string;
+    description: string;
+    steps: Step[];
+    id: string;
+}
+interface Background {
+    location: Location;
+    keyword: string;
+    name: string;
+    description: string;
+    steps: Step[];
+    id: string;
+}
+type FeatureChild = {
+    background: Background;
+    scenario?: undefined;
+} | {
+    scenario: Scenario;
+    background?: undefined;
+};
+interface Feature {
+    location: Location;
+    tags: Tag[];
+    language: string;
+    keyword: string;
+    name: string;
+    description: string;
+    children: FeatureChild[];
+}
+interface GherkinDocument {
+    uri: string;
+    feature: Feature;
+}
+type PickleStepType = "Unknown" | "Context" | "Action" | "Outcome";
+interface PickleDocString {
+    mediaType?: string;
+    content: string;
+}
+interface PickleTableCell {
+    value: string;
+}
+interface PickleTableRow {
+    cells: PickleTableCell[];
+}
+interface PickleTable {
+    rows: PickleTableRow[];
+}
+interface PickleStepArgument {
+    docString?: PickleDocString;
+    dataTable?: PickleTable;
+}
+interface PickleStep {
+    astNodeIds: string[];
+    id: string;
+    type: PickleStepType;
+    text: string;
+    argument?: PickleStepArgument;
+}
+interface PickleTag {
+    name: string;
+    astNodeId: string;
+}
+interface Pickle {
+    id: string;
+    uri: string;
+    name: string;
+    language: string;
+    steps: PickleStep[];
+    tags: PickleTag[];
+    astNodeIds: string[];
+}
+type TestStepResultStatus = "UNKNOWN" | "PASSED" | "SKIPPED" | "PENDING" | "UNDEFINED" | "AMBIGUOUS" | "FAILED";
+interface TestStepResult {
+    duration: Duration;
+    status: TestStepResultStatus;
+    message?: string;
+}
+interface TestStep {
+    id: string;
+    pickleStepId?: string;
+    stepDefinitionIds?: string[];
+}
+interface TestCase {
+    id: string;
+    pickleId: string;
+    testSteps: TestStep[];
+}
+interface TestRunStarted {
+    timestamp: Timestamp;
+}
+interface TestCaseStarted {
+    id: string;
+    testCaseId: string;
+    timestamp: Timestamp;
+    attempt: number;
+}
+interface TestStepStarted {
+    testCaseStartedId: string;
+    testStepId: string;
+    timestamp: Timestamp;
+}
+interface TestStepFinished {
+    testCaseStartedId: string;
+    testStepId: string;
+    testStepResult: TestStepResult;
+    timestamp: Timestamp;
+}
+interface TestCaseFinished {
+    testCaseStartedId: string;
+    timestamp: Timestamp;
+    willBeRetried: boolean;
+}
+interface TestRunFinished {
+    timestamp: Timestamp;
+    success: boolean;
+}
+type AttachmentContentEncoding = "IDENTITY" | "BASE64";
+interface CucumberAttachment {
+    testCaseStartedId: string;
+    testStepId?: string;
+    body: string;
+    mediaType: string;
+    contentEncoding: AttachmentContentEncoding;
+}
+/**
+ * Each NDJSON line is one Envelope with exactly one field set.
+ */
+type Envelope = {
+    meta: Meta;
+} | {
+    source: Source;
+} | {
+    gherkinDocument: GherkinDocument;
+} | {
+    pickle: Pickle;
+} | {
+    testRunStarted: TestRunStarted;
+} | {
+    testCase: TestCase;
+} | {
+    testCaseStarted: TestCaseStarted;
+} | {
+    testStepStarted: TestStepStarted;
+} | {
+    testStepFinished: TestStepFinished;
+} | {
+    testCaseFinished: TestCaseFinished;
+} | {
+    testRunFinished: TestRunFinished;
+} | {
+    attachment: CucumberAttachment;
+};
+
+/**
+ * CucumberMessagesFormatter — produces NDJSON compatible with @cucumber/html-formatter.
+ *
+ * Message stream order:
+ * Meta → Source* → GherkinDocument* → Pickle* → TestRunStarted →
+ * [TestCase, TestCaseStarted, TestStep*, TestCaseFinished]* → TestRunFinished
+ */
+
+interface CucumberMessagesOptions {
+    /** Strategy for deriving Source.uri. Default: "sourceFile" */
+    uriStrategy?: "sourceFile" | "virtual";
+    /** Whether to emit Source/GherkinDocument for synthesized features. Default: true */
+    includeSynthetics?: boolean;
+    /** Salt for deterministic IDs. Default: "" */
+    idSalt?: string;
+    /** Tool metadata for Meta envelope */
+    meta?: {
+        toolName?: string;
+        toolVersion?: string;
+    };
+}
+declare class CucumberMessagesFormatter {
+    private options;
+    constructor(options?: CucumberMessagesOptions);
+    /**
+     * Format a TestRunResult into an array of Envelope objects.
+     */
+    format(run: TestRunResult): Envelope[];
+    /**
+     * Format as NDJSON string (one JSON line per envelope).
+     */
+    formatToString(run: TestRunResult): string;
+    /**
+     * Build the Meta envelope.
+     */
+    private buildMetaEnvelope;
+    /**
+     * Group test cases by source file, preserving order.
+     */
+    private groupBySourceFile;
+}
+
+/**
+ * CucumberHtmlFormatter — produces the official Cucumber HTML report.
+ *
+ * Thin wrapper: reuses CucumberMessagesFormatter to generate NDJSON envelopes,
+ * then pipes them through @cucumber/html-formatter's CucumberHtmlStream.
+ */
+
+interface CucumberHtmlOptions {
+    /** Options forwarded to the underlying CucumberMessagesFormatter */
+    messages?: CucumberMessagesOptions;
+}
+declare class CucumberHtmlFormatter {
+    private messagesFormatter;
+    constructor(options?: CucumberHtmlOptions);
+    /**
+     * Format a TestRunResult into official Cucumber HTML.
+     *
+     * Returns a Promise because CucumberHtmlStream is a Node.js Transform stream.
+     */
+    format(run: TestRunResult): Promise<string>;
+    /**
+     * Format a TestRunResult into official Cucumber HTML string.
+     */
+    formatToString(run: TestRunResult): Promise<string>;
+}
+
+/**
+ * NDJSON-to-TestRunResult parser.
+ *
+ * Parses Cucumber Messages NDJSON (one JSON envelope per line) back into
+ * a TestRunResult suitable for rendering by HtmlFormatter or other formatters.
+ *
+ * This is the NDJSON compat path: it produces a minimal but sufficient
+ * TestRunResult. Fields not present in the NDJSON stream are given
+ * sensible defaults.
+ */
+
+/**
+ * Parse an NDJSON string into a TestRunResult.
+ *
+ * @param ndjson - NDJSON string (one JSON envelope per line)
+ * @returns TestRunResult reconstructed from the envelopes
+ */
+declare function parseNdjson(ndjson: string): TestRunResult;
+/**
+ * Parse an array of Envelope objects into a TestRunResult.
+ *
+ * @param envelopes - Array of Cucumber Messages envelopes
+ * @returns TestRunResult reconstructed from the envelopes
+ */
+declare function parseEnvelopes(envelopes: Envelope[]): TestRunResult;
+
+/**
+ * Git information utilities.
+ *
+ * Read git SHA and other info from the local repository.
+ */
+/**
+ * Read the current git SHA.
+ *
+ * Checks environment variables first (for CI), then reads from .git directory.
+ *
+ * @param cwd - Working directory to start search from
+ * @returns Git SHA or undefined if not in a git repo
+ */
+declare function readGitSha(cwd?: string): string | undefined;
+/**
+ * Find the .git directory starting from a given directory.
+ *
+ * @param start - Directory to start search from
+ * @returns Path to .git directory or undefined if not found
+ */
+declare function findGitDir(start: string): string | undefined;
+/**
+ * Read the current branch name.
+ *
+ * @param cwd - Working directory
+ * @returns Branch name or undefined
+ */
+declare function readBranchName(cwd?: string): string | undefined;
+
+/**
+ * Duration formatting utilities.
+ */
+/**
+ * Format milliseconds as human-readable duration.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted string (e.g., "123 ms", "1.5 s", "2m 30s")
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Convert milliseconds to nanoseconds.
+ *
+ * Used for Cucumber JSON format which expects nanoseconds.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Duration in nanoseconds
+ */
+declare function msToNanoseconds(ms: number): number;
+/**
+ * Convert nanoseconds to milliseconds.
+ *
+ * @param ns - Duration in nanoseconds
+ * @returns Duration in milliseconds
+ */
+declare function nanosecondsToMs(ns: number): number;
+
+/**
+ * Metadata utilities for reading package information.
+ */
+/**
+ * Read the package version from the closest package.json.
+ *
+ * Results are cached by root directory.
+ *
+ * @param root - Directory to start searching from
+ * @returns Package version string or undefined if not found
+ */
+declare function readPackageVersion(root: string): string | undefined;
+/**
+ * Clear the package version cache.
+ * Useful for testing.
+ */
+declare function clearVersionCache(): void;
+
+/**
+ * CI environment auto-detection utility.
+ *
+ * Detects known CI providers from environment variables.
+ * Precedence: GitHub Actions > CircleCI > Jenkins > Travis > GitLab CI > generic CI
+ */
+
+/**
+ * Detect CI environment from process.env.
+ * Returns undefined when not running in CI.
+ */
+declare function detectCI(env?: Record<string, string | undefined>): RawCIInfo | undefined;
+
+/**
+ * @executable-stories/formatters
+ *
+ * Cucumber-compatible report formats (JSON, HTML, JUnit, Markdown)
+ * for Jest, Vitest, and Playwright test results.
+ *
+ * Architecture:
+ * - Layer 1: Framework Adapters (adaptJestRun, adaptVitestRun, adaptPlaywrightRun)
+ * - Layer 2: Anti-Corruption Layer (canonicalizeRun)
+ * - Layer 3: Formatters (CucumberJsonFormatter, HtmlFormatter, JUnitFormatter, MarkdownFormatter)
+ */
+
+/** 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[]>;
+/**
+ * High-level report generator that combines multiple formatters.
+ *
+ * Accepts ONLY canonical TestRunResult - use adapters + canonicalizeRun first.
+ *
+ * Supports output routing:
+ * - Aggregated: All test cases in a single file
+ * - Colocated mirrored: Files mirrored under outputDir preserving directory structure
+ * - Colocated adjacent: Files written next to source files
+ * - Rule-based: Different routing based on source file patterns
+ */
+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>;
+    /**
+     * Generate reports for a single format.
+     */
+    private generateFormat;
+    /**
+     * Format content for a specific format.
+     */
+    private formatContent;
+}
+/**
+ * Factory function to create a ReportGenerator with dependency injection.
+ *
+ * Useful for testing and custom configurations.
+ */
+declare function createReportGenerator(options?: FormatterOptions, deps?: Partial<GenerateDeps>): ReportGenerator;
+
+/**
+ * Normalize Jest results to canonical TestRunResult.
+ *
+ * Combines adaptJestRun + canonicalizeRun.
+ */
+declare function normalizeJestResults(jestResults: Parameters<typeof adaptJestRun>[0], storyReports: Parameters<typeof adaptJestRun>[1], adapterOptions?: Parameters<typeof adaptJestRun>[2], canonicalizeOptions?: CanonicalizeOptions): TestRunResult;
+/**
+ * Normalize Vitest results to canonical TestRunResult.
+ *
+ * Combines adaptVitestRun + canonicalizeRun.
+ */
+declare function normalizeVitestResults(testModules: Parameters<typeof adaptVitestRun>[0], adapterOptions?: Parameters<typeof adaptVitestRun>[1], canonicalizeOptions?: CanonicalizeOptions): TestRunResult;
+/**
+ * Normalize Playwright results to canonical TestRunResult.
+ *
+ * Combines adaptPlaywrightRun + canonicalizeRun.
+ */
+declare function normalizePlaywrightResults(testResults: Parameters<typeof adaptPlaywrightRun>[0], adapterOptions?: Parameters<typeof adaptPlaywrightRun>[1], canonicalizeOptions?: CanonicalizeOptions): TestRunResult;
+
+export { type Attachment, type CIInfo, type CanonicalizeOptions, type ColocatedStyle, type CoverageSummary, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DocEntry, type FormatterOptions, type GenerateArgs, type GenerateDeps, type GenerateResult, HtmlFormatter, type HtmlOptions, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type Logger, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, RawAttachment, RawCIInfo, RawRun, RawStatus, ReportGenerator, type ResolvedFormatterOptions, type StepResult, StoryMeta, StoryStep, type TestCaseAttempt, type TestCaseResult, type TestRunResult, type TestStatus, type ValidationResult, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, assertValidRun, canonicalizeRun, clearVersionCache, createReportGenerator, deriveStepResults, detectCI, findGitDir, formatDuration, generateRunId, generateTestCaseId, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, readBranchName, readGitSha, readPackageVersion, resolveAttachment, resolveAttachments, slugify, validateCanonicalRun };