executable-stories-react 0.2.1 → 0.4.0

package/dist/ssr.d.cts

@@ -1,4 +1,226 @@
-import { 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.
@@ -24,6 +246,20 @@ interface ReportParseError {
 }
 type ReportParseErrorCode = "INVALID_INPUT" | "SCHEMA_VERSION_MISMATCH" | "VALIDATION_FAILED";
 
+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[]>;
+
 /**
  * Server-only entry: render a StoryReport to a standalone HTML document string.
  *
@@ -61,6 +297,18 @@ interface RenderReportToHtmlOptions {
      * no-JS fallback.
      */
     islandScript?: string;
+    /**
+     * Days before the interactive report flags itself as stale ("Last verified
+     * N days ago" warning banner). 0 disables the warning. Default 7.
+     */
+    staleAfterDays?: number;
+    /**
+     * Recent run events per scenario id (joined from the CLI's --history-file
+     * store). Embedded as JSON next to the report data; the interactive island
+     * renders a run-over-run timeline strip on each scenario card. Ignored for
+     * static (non-island) output.
+     */
+    scenarioHistory?: ScenarioHistoryMap;
 }
 /**
  * Render a StoryReport (or a parse Result) to a complete, self-contained HTML
@@ -69,4 +317,4 @@ interface RenderReportToHtmlOptions {
  */
 declare function renderReportToHtml(report: StoryReport | Result<StoryReport>, options?: RenderReportToHtmlOptions): string;
 
-export { type RenderReportToHtmlOptions, renderReportToHtml };
+export { type RenderReportToHtmlOptions, type ScenarioHistoryMap, type ScenarioRunEvent, renderReportToHtml };

package/dist/ssr.d.ts

@@ -1,4 +1,226 @@
-import { 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.
@@ -24,6 +246,20 @@ interface ReportParseError {
 }
 type ReportParseErrorCode = "INVALID_INPUT" | "SCHEMA_VERSION_MISMATCH" | "VALIDATION_FAILED";
 
+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[]>;
+
 /**
  * Server-only entry: render a StoryReport to a standalone HTML document string.
  *
@@ -61,6 +297,18 @@ interface RenderReportToHtmlOptions {
      * no-JS fallback.
      */
     islandScript?: string;
+    /**
+     * Days before the interactive report flags itself as stale ("Last verified
+     * N days ago" warning banner). 0 disables the warning. Default 7.
+     */
+    staleAfterDays?: number;
+    /**
+     * Recent run events per scenario id (joined from the CLI's --history-file
+     * store). Embedded as JSON next to the report data; the interactive island
+     * renders a run-over-run timeline strip on each scenario card. Ignored for
+     * static (non-island) output.
+     */
+    scenarioHistory?: ScenarioHistoryMap;
 }
 /**
  * Render a StoryReport (or a parse Result) to a complete, self-contained HTML
@@ -69,4 +317,4 @@ interface RenderReportToHtmlOptions {
  */
 declare function renderReportToHtml(report: StoryReport | Result<StoryReport>, options?: RenderReportToHtmlOptions): string;
 
-export { type RenderReportToHtmlOptions, renderReportToHtml };
+export { type RenderReportToHtmlOptions, type ScenarioHistoryMap, type ScenarioRunEvent, renderReportToHtml };