executable-stories-react 0.2.1 → 0.4.0

package/dist/interactive.d.cts

@@ -1,6 +1,229 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { ReportDocCustom, ReportDocMermaid, ReportDocCode, ReportDocSection, StoryReport } from 'executable-stories-core';
+
+/**
+ * OTel span types for trace waterfall rendering.
+ *
+ * Structurally compatible with autotel's SerializedSpan
+ * and raw OTel nanosecond formats. No import dependency on autotel.
+ */
+type OtelAttributeValue = string | number | boolean | string[] | number[] | boolean[];
+interface OtelSpan {
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    /** Preferred: epoch-based milliseconds (from autotel's SerializedSpan) */
+    startTimeMs?: number;
+    durationMs?: number;
+    /** Compatibility: raw OTel nanosecond timestamps */
+    startTimeUnixNano?: number;
+    endTimeUnixNano?: number;
+    status: "ok" | "error" | "unset";
+    statusMessage?: string;
+    attributes?: Record<string, OtelAttributeValue>;
+}
+
+/** Phase tracks when the doc entry was added */
+type DocPhase = "static" | "runtime";
+
+/**
+ * StoryReport — public, frozen contract for UI renderers.
+ *
+ * Distinct from internal TestRunResult. Pre-grouped feature → scenario tree,
+ * with pre-computed summaries at every level. Adapter concerns (rawStatus,
+ * projectName, titlePath) are stripped at the toStoryReport boundary.
+ *
+ * Versioning: semver-style "<major>.<minor>". Additive-only within a major.
+ * Source of truth: schemas/story-report-v1.json. Types here must stay in sync.
+ */
+
+type StoryReportSchemaVersion = `1.${number}`;
+type TestStatus = "passed" | "failed" | "skipped" | "pending";
+type StepKeyword = "Given" | "When" | "Then" | "And" | "But";
+type StepMode = "normal" | "skip" | "only" | "todo" | "fails" | "concurrent";
+interface ReportSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    pending: number;
+    durationMs: number;
+}
+interface ReportTicket {
+    id: string;
+    url?: string;
+}
+interface ReportAttachment {
+    name: string;
+    mediaType: string;
+    body: string;
+    contentEncoding: "BASE64" | "IDENTITY";
+}
+interface ReportCIInfo {
+    name: string;
+    url?: string;
+    buildNumber?: string;
+    branch?: string;
+    commitSha?: string;
+    prNumber?: string;
+}
+interface ReportCoverageSummary {
+    linesPct?: number;
+    branchesPct?: number;
+    functionsPct?: number;
+    statementsPct?: number;
+}
+type ReportDocEntry = ReportDocNote | ReportDocTag | ReportDocKv | ReportDocCode | ReportDocTable | ReportDocLink | ReportDocSection | ReportDocMermaid | ReportDocScreenshot | ReportDocVideo | ReportDocHtml | ReportDocCustom;
+interface ReportDocNote {
+    kind: "note";
+    text: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocTag {
+    kind: "tag";
+    names: string[];
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocKv {
+    kind: "kv";
+    label: string;
+    value: unknown;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocCode {
+    kind: "code";
+    label: string;
+    content: string;
+    lang?: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocTable {
+    kind: "table";
+    label: string;
+    columns: string[];
+    rows: string[][];
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocLink {
+    kind: "link";
+    label: string;
+    url: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocSection {
+    kind: "section";
+    title: string;
+    markdown: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocMermaid {
+    kind: "mermaid";
+    code: string;
+    title?: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocScreenshot {
+    kind: "screenshot";
+    path: string;
+    alt?: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocVideo {
+    kind: "video";
+    path: string;
+    caption?: string;
+    poster?: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocHtml {
+    kind: "html";
+    /** Local HTML file path (exactly one of path/url/content) */
+    path?: string;
+    /** Remote URL rendered via iframe src (exactly one of path/url/content) */
+    url?: string;
+    /** Inline HTML content rendered via iframe srcdoc (exactly one of path/url/content) */
+    content?: string;
+    title?: string;
+    /** Iframe height: number → px, string passed through (e.g. "60vh"). Default 400px. */
+    height?: number | string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocCustom {
+    kind: "custom";
+    type: string;
+    data: unknown;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportStep {
+    id: string;
+    index: number;
+    keyword: StepKeyword;
+    text: string;
+    status: TestStatus;
+    durationMs: number;
+    errorMessage?: string;
+    mode?: StepMode;
+    docEntries: ReportDocEntry[];
+}
+interface ReportScenario {
+    id: string;
+    title: string;
+    status: TestStatus;
+    /**
+     * True for scenarios authored with the framework's todo modifier
+     * (e.g. `it.todo`): specified behavior with no implementation yet.
+     * Canonical status stays "pending"; this flags why.
+     */
+    planned?: boolean;
+    durationMs: number;
+    tags: string[];
+    tickets?: ReportTicket[];
+    /** Product-code paths/globs this scenario exercises (project-root-relative). */
+    covers?: string[];
+    sourceLine?: number;
+    errorMessage?: string;
+    errorStack?: string;
+    retry: number;
+    retries: number;
+    docEntries: ReportDocEntry[];
+    steps: ReportStep[];
+    attachments: ReportAttachment[];
+    /** OTel spans for the trace waterfall (carried through from the run). */
+    otelSpans?: OtelSpan[];
+}
+interface ReportFeature {
+    id: string;
+    title: string;
+    sourceFile: string;
+    summary: ReportSummary;
+    scenarios: ReportScenario[];
+}
+interface StoryReport {
+    schemaVersion: StoryReportSchemaVersion;
+    runId: string;
+    startedAtMs: number;
+    finishedAtMs: number;
+    durationMs: number;
+    projectRoot: string;
+    packageVersion?: string;
+    gitSha?: string;
+    ci?: ReportCIInfo;
+    coverage?: ReportCoverageSummary;
+    summary: ReportSummary;
+    features: ReportFeature[];
+}
 
 /**
  * Result<T> — explicit success/error type matching the cookbook convention.
@@ -43,6 +266,20 @@ interface BuiltinRenderers {
     section?: (entry: ReportDocSection) => ReactNode;
 }
 
+type ScenarioRunStatus = "passed" | "failed" | "skipped" | "pending";
+/** One historical run of a scenario, oldest → newest in a history array. */
+interface ScenarioRunEvent {
+    /** Epoch ms the run started. */
+    timestamp: number;
+    status: ScenarioRunStatus;
+    runId?: string;
+    durationMs?: number;
+    commitSha?: string;
+    branch?: string;
+}
+/** Recent run events keyed by ReportScenario.id. */
+type ScenarioHistoryMap = Record<string, ScenarioRunEvent[]>;
+
 interface ReportInteractiveProps {
     /** A StoryReport, or a Result-wrapped one (e.g., from parseStoryReport). */
     report: StoryReport | Result<StoryReport>;
@@ -60,6 +297,16 @@ interface ReportInteractiveProps {
      * Starlight, where Starlight renders the page `<h1>`.
      */
     hideHeader?: boolean;
+    /**
+     * Days before the report is flagged as stale (warning banner instead of the
+     * "Verified N ago" line). 0 disables the stale warning. Default 7.
+     */
+    staleAfterDays?: number;
+    /**
+     * Recent run events per scenario id (from the CLI's --history-file store).
+     * When present, scenario cards show a run-over-run timeline strip.
+     */
+    scenarioHistory?: ScenarioHistoryMap;
 }
 declare function ReportInteractive(props: ReportInteractiveProps): react.JSX.Element;
 
@@ -134,6 +381,26 @@ interface ReportFailureBannerProps {
 }
 declare function ReportFailureBanner({ failures }: ReportFailureBannerProps): react.JSX.Element | null;
 
+interface ReportFreshnessProps {
+    /** Epoch ms of the run this report documents (see reportLastRunMs). */
+    lastRunMs?: number;
+    /** CI run URL, linked from the banner so readers can check for newer runs. */
+    ciUrl?: string;
+    /** Days before the report counts as stale; 0 disables the warning. */
+    staleAfterDays: number;
+    /** Test seam: fixed "now"; defaults to Date.now() on mount. */
+    nowMs?: number;
+}
+/**
+ * The report's freshness signal. Fresh reports get a one-line "Last verified
+ * N ago" status; reports older than `staleAfterDays` get a warning banner —
+ * living documentation is only trustworthy while it is recent.
+ *
+ * Age is computed on mount (never during server render): the static HTML is
+ * generated once but read later, so any age baked in at build time would lie.
+ */
+declare function ReportFreshness({ lastRunMs, ciUrl, staleAfterDays, nowMs }: ReportFreshnessProps): react.JSX.Element | null;
+
 interface ReportShortcutsHelpProps {
     open: boolean;
     onClose: () => void;
@@ -163,4 +430,4 @@ declare function useKeyboardShortcuts(handlers: KeyboardShortcutHandlers): void;
  */
 declare function useDeepLinkScroll(): void;
 
-export { type FailureRef, type IslandRendererOptions, type KeyboardShortcutHandlers, ReportFailureBanner, type ReportFailureBannerProps, ReportInteractive, ReportInteractiveIsland, type ReportInteractiveIslandProps, type ReportInteractiveProps, ReportSearch, type ReportSearchProps, ReportShortcutsHelp, type ReportShortcutsHelpProps, buildIslandRenderers, filterReport, listFailures, normalizeQuery, useDeepLinkScroll, useKeyboardShortcuts };
+export { type FailureRef, type IslandRendererOptions, type KeyboardShortcutHandlers, ReportFailureBanner, type ReportFailureBannerProps, ReportFreshness, type ReportFreshnessProps, ReportInteractive, ReportInteractiveIsland, type ReportInteractiveIslandProps, type ReportInteractiveProps, ReportSearch, type ReportSearchProps, ReportShortcutsHelp, type ReportShortcutsHelpProps, buildIslandRenderers, filterReport, listFailures, normalizeQuery, useDeepLinkScroll, useKeyboardShortcuts };

package/dist/interactive.d.ts

@@ -1,6 +1,229 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { ReportDocCustom, ReportDocMermaid, ReportDocCode, ReportDocSection, StoryReport } from 'executable-stories-core';
+
+/**
+ * OTel span types for trace waterfall rendering.
+ *
+ * Structurally compatible with autotel's SerializedSpan
+ * and raw OTel nanosecond formats. No import dependency on autotel.
+ */
+type OtelAttributeValue = string | number | boolean | string[] | number[] | boolean[];
+interface OtelSpan {
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    /** Preferred: epoch-based milliseconds (from autotel's SerializedSpan) */
+    startTimeMs?: number;
+    durationMs?: number;
+    /** Compatibility: raw OTel nanosecond timestamps */
+    startTimeUnixNano?: number;
+    endTimeUnixNano?: number;
+    status: "ok" | "error" | "unset";
+    statusMessage?: string;
+    attributes?: Record<string, OtelAttributeValue>;
+}
+
+/** Phase tracks when the doc entry was added */
+type DocPhase = "static" | "runtime";
+
+/**
+ * StoryReport — public, frozen contract for UI renderers.
+ *
+ * Distinct from internal TestRunResult. Pre-grouped feature → scenario tree,
+ * with pre-computed summaries at every level. Adapter concerns (rawStatus,
+ * projectName, titlePath) are stripped at the toStoryReport boundary.
+ *
+ * Versioning: semver-style "<major>.<minor>". Additive-only within a major.
+ * Source of truth: schemas/story-report-v1.json. Types here must stay in sync.
+ */
+
+type StoryReportSchemaVersion = `1.${number}`;
+type TestStatus = "passed" | "failed" | "skipped" | "pending";
+type StepKeyword = "Given" | "When" | "Then" | "And" | "But";
+type StepMode = "normal" | "skip" | "only" | "todo" | "fails" | "concurrent";
+interface ReportSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    pending: number;
+    durationMs: number;
+}
+interface ReportTicket {
+    id: string;
+    url?: string;
+}
+interface ReportAttachment {
+    name: string;
+    mediaType: string;
+    body: string;
+    contentEncoding: "BASE64" | "IDENTITY";
+}
+interface ReportCIInfo {
+    name: string;
+    url?: string;
+    buildNumber?: string;
+    branch?: string;
+    commitSha?: string;
+    prNumber?: string;
+}
+interface ReportCoverageSummary {
+    linesPct?: number;
+    branchesPct?: number;
+    functionsPct?: number;
+    statementsPct?: number;
+}
+type ReportDocEntry = ReportDocNote | ReportDocTag | ReportDocKv | ReportDocCode | ReportDocTable | ReportDocLink | ReportDocSection | ReportDocMermaid | ReportDocScreenshot | ReportDocVideo | ReportDocHtml | ReportDocCustom;
+interface ReportDocNote {
+    kind: "note";
+    text: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocTag {
+    kind: "tag";
+    names: string[];
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocKv {
+    kind: "kv";
+    label: string;
+    value: unknown;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocCode {
+    kind: "code";
+    label: string;
+    content: string;
+    lang?: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocTable {
+    kind: "table";
+    label: string;
+    columns: string[];
+    rows: string[][];
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocLink {
+    kind: "link";
+    label: string;
+    url: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocSection {
+    kind: "section";
+    title: string;
+    markdown: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocMermaid {
+    kind: "mermaid";
+    code: string;
+    title?: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocScreenshot {
+    kind: "screenshot";
+    path: string;
+    alt?: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocVideo {
+    kind: "video";
+    path: string;
+    caption?: string;
+    poster?: string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocHtml {
+    kind: "html";
+    /** Local HTML file path (exactly one of path/url/content) */
+    path?: string;
+    /** Remote URL rendered via iframe src (exactly one of path/url/content) */
+    url?: string;
+    /** Inline HTML content rendered via iframe srcdoc (exactly one of path/url/content) */
+    content?: string;
+    title?: string;
+    /** Iframe height: number → px, string passed through (e.g. "60vh"). Default 400px. */
+    height?: number | string;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportDocCustom {
+    kind: "custom";
+    type: string;
+    data: unknown;
+    phase: DocPhase;
+    children?: ReportDocEntry[];
+}
+interface ReportStep {
+    id: string;
+    index: number;
+    keyword: StepKeyword;
+    text: string;
+    status: TestStatus;
+    durationMs: number;
+    errorMessage?: string;
+    mode?: StepMode;
+    docEntries: ReportDocEntry[];
+}
+interface ReportScenario {
+    id: string;
+    title: string;
+    status: TestStatus;
+    /**
+     * True for scenarios authored with the framework's todo modifier
+     * (e.g. `it.todo`): specified behavior with no implementation yet.
+     * Canonical status stays "pending"; this flags why.
+     */
+    planned?: boolean;
+    durationMs: number;
+    tags: string[];
+    tickets?: ReportTicket[];
+    /** Product-code paths/globs this scenario exercises (project-root-relative). */
+    covers?: string[];
+    sourceLine?: number;
+    errorMessage?: string;
+    errorStack?: string;
+    retry: number;
+    retries: number;
+    docEntries: ReportDocEntry[];
+    steps: ReportStep[];
+    attachments: ReportAttachment[];
+    /** OTel spans for the trace waterfall (carried through from the run). */
+    otelSpans?: OtelSpan[];
+}
+interface ReportFeature {
+    id: string;
+    title: string;
+    sourceFile: string;
+    summary: ReportSummary;
+    scenarios: ReportScenario[];
+}
+interface StoryReport {
+    schemaVersion: StoryReportSchemaVersion;
+    runId: string;
+    startedAtMs: number;
+    finishedAtMs: number;
+    durationMs: number;
+    projectRoot: string;
+    packageVersion?: string;
+    gitSha?: string;
+    ci?: ReportCIInfo;
+    coverage?: ReportCoverageSummary;
+    summary: ReportSummary;
+    features: ReportFeature[];
+}
 
 /**
  * Result<T> — explicit success/error type matching the cookbook convention.
@@ -43,6 +266,20 @@ interface BuiltinRenderers {
     section?: (entry: ReportDocSection) => ReactNode;
 }
 
+type ScenarioRunStatus = "passed" | "failed" | "skipped" | "pending";
+/** One historical run of a scenario, oldest → newest in a history array. */
+interface ScenarioRunEvent {
+    /** Epoch ms the run started. */
+    timestamp: number;
+    status: ScenarioRunStatus;
+    runId?: string;
+    durationMs?: number;
+    commitSha?: string;
+    branch?: string;
+}
+/** Recent run events keyed by ReportScenario.id. */
+type ScenarioHistoryMap = Record<string, ScenarioRunEvent[]>;
+
 interface ReportInteractiveProps {
     /** A StoryReport, or a Result-wrapped one (e.g., from parseStoryReport). */
     report: StoryReport | Result<StoryReport>;
@@ -60,6 +297,16 @@ interface ReportInteractiveProps {
      * Starlight, where Starlight renders the page `<h1>`.
      */
     hideHeader?: boolean;
+    /**
+     * Days before the report is flagged as stale (warning banner instead of the
+     * "Verified N ago" line). 0 disables the stale warning. Default 7.
+     */
+    staleAfterDays?: number;
+    /**
+     * Recent run events per scenario id (from the CLI's --history-file store).
+     * When present, scenario cards show a run-over-run timeline strip.
+     */
+    scenarioHistory?: ScenarioHistoryMap;
 }
 declare function ReportInteractive(props: ReportInteractiveProps): react.JSX.Element;
 
@@ -134,6 +381,26 @@ interface ReportFailureBannerProps {
 }
 declare function ReportFailureBanner({ failures }: ReportFailureBannerProps): react.JSX.Element | null;
 
+interface ReportFreshnessProps {
+    /** Epoch ms of the run this report documents (see reportLastRunMs). */
+    lastRunMs?: number;
+    /** CI run URL, linked from the banner so readers can check for newer runs. */
+    ciUrl?: string;
+    /** Days before the report counts as stale; 0 disables the warning. */
+    staleAfterDays: number;
+    /** Test seam: fixed "now"; defaults to Date.now() on mount. */
+    nowMs?: number;
+}
+/**
+ * The report's freshness signal. Fresh reports get a one-line "Last verified
+ * N ago" status; reports older than `staleAfterDays` get a warning banner —
+ * living documentation is only trustworthy while it is recent.
+ *
+ * Age is computed on mount (never during server render): the static HTML is
+ * generated once but read later, so any age baked in at build time would lie.
+ */
+declare function ReportFreshness({ lastRunMs, ciUrl, staleAfterDays, nowMs }: ReportFreshnessProps): react.JSX.Element | null;
+
 interface ReportShortcutsHelpProps {
     open: boolean;
     onClose: () => void;
@@ -163,4 +430,4 @@ declare function useKeyboardShortcuts(handlers: KeyboardShortcutHandlers): void;
  */
 declare function useDeepLinkScroll(): void;
 
-export { type FailureRef, type IslandRendererOptions, type KeyboardShortcutHandlers, ReportFailureBanner, type ReportFailureBannerProps, ReportInteractive, ReportInteractiveIsland, type ReportInteractiveIslandProps, type ReportInteractiveProps, ReportSearch, type ReportSearchProps, ReportShortcutsHelp, type ReportShortcutsHelpProps, buildIslandRenderers, filterReport, listFailures, normalizeQuery, useDeepLinkScroll, useKeyboardShortcuts };
+export { type FailureRef, type IslandRendererOptions, type KeyboardShortcutHandlers, ReportFailureBanner, type ReportFailureBannerProps, ReportFreshness, type ReportFreshnessProps, ReportInteractive, ReportInteractiveIsland, type ReportInteractiveIslandProps, type ReportInteractiveProps, ReportSearch, type ReportSearchProps, ReportShortcutsHelp, type ReportShortcutsHelpProps, buildIslandRenderers, filterReport, listFailures, normalizeQuery, useDeepLinkScroll, useKeyboardShortcuts };