executable-stories-react 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,12 +1,232 @@
 import * as react from 'react';
 import { ReactNode, Ref } from 'react';
-import * as executable_stories_core from 'executable-stories-core';
-import { ReportDocMermaid, ReportDocCode, ReportDocSection, ReportDocCustom, StoryReport, ReportSummary as ReportSummary$1, ReportAttachment, ReportFeature as ReportFeature$1, ReportScenario as ReportScenario$1, ReportStep, ReportDocEntry, ReportDocNote, ReportDocTag, ReportDocKv, ReportDocTable, ReportDocLink, ReportDocScreenshot, ReportDocVideo, ReportDocHtml } from 'executable-stories-core';
-export { StoryReport, ReportDocEntry as StoryReportDocEntry, ReportFeature as StoryReportFeature, ReportScenario as StoryReportScenario, ReportStep as StoryReportStep, ReportSummary as StoryReportSummary } from 'executable-stories-core';
-import { OtelSpan } from 'executable-stories-core/types/otel';
 import * as mermaid from 'mermaid';
 import { z } from 'zod';
 
+/**
+ * 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$1 {
+    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$1 {
+    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$1 {
+    id: string;
+    title: string;
+    sourceFile: string;
+    summary: ReportSummary$1;
+    scenarios: ReportScenario$1[];
+}
+interface StoryReport {
+    schemaVersion: StoryReportSchemaVersion;
+    runId: string;
+    startedAtMs: number;
+    finishedAtMs: number;
+    durationMs: number;
+    projectRoot: string;
+    packageVersion?: string;
+    gitSha?: string;
+    ci?: ReportCIInfo;
+    coverage?: ReportCoverageSummary;
+    summary: ReportSummary$1;
+    features: ReportFeature$1[];
+}
+
 /**
  * Result<T> — explicit success/error type matching the cookbook convention.
  *
@@ -86,9 +306,10 @@ interface ReportSummaryViewProps {
 declare function ReportSummaryView({ summary, className, ariaLabel }: ReportSummaryViewProps): react.JSX.Element;
 
 /**
- * Run metadata line (started, duration, version, git SHA, CI) — the React
- * equivalent of the report's `.meta-info` block. Reads the top-level StoryReport
- * fields from context.
+ * Run metadata line (started, duration, version, branch, git SHA, CI, PR) —
+ * the React equivalent of the report's `.meta-info` block. Reads the top-level
+ * StoryReport fields from context. Commit and PR become links when the CI run
+ * URL lets us derive them safely (GitHub/GitLab shapes only).
  */
 declare function ReportMeta(): react.JSX.Element | null;
 
@@ -223,6 +444,14 @@ declare function MermaidDiagram({ entry, load }: {
     load?: MermaidLoader;
 }): react.JSX.Element;
 
+/**
+ * A screenshot that's still an absolute local filesystem path by the time it
+ * reaches this component means the report's asset bundler couldn't find the
+ * file to inline/copy it (deleted, moved, or never captured — see
+ * inlineScreenshotIfPossible in executable-stories-playwright). `<img src>`
+ * would 404 against a path from the machine that generated the report, so
+ * show a placeholder instead of a broken image.
+ */
 declare function DocScreenshot({ entry }: {
     entry: ReportDocScreenshot;
 }): react.JSX.Element;
@@ -232,6 +461,10 @@ declare function DocScreenshot({ entry }: {
  * a URL or a path that resolves alongside the report. Both `path` and `poster`
  * are adapter-supplied, so they go through the same scheme allow-list as the
  * DocHtml iframe src (no `javascript:`/`data:` URLs reach the DOM).
+ *
+ * An absolute local filesystem path means the report's asset bundler
+ * couldn't find/copy the file — a `<video src>` pointed at a runner-local
+ * path would just fail to load, so show a placeholder instead.
  */
 declare function DocVideo({ entry }: {
     entry: ReportDocVideo;
@@ -281,6 +514,71 @@ declare function ScenarioExplorer({ scenarios, summary }: ScenarioExplorerProps)
 declare function useCustomRenderers(): CustomRenderers;
 declare function useBuiltinRenderers(): BuiltinRenderers;
 
+type ReportCI = NonNullable<StoryReport["ci"]>;
+/**
+ * Epoch ms of the run the report documents — the staleness reference.
+ * Prefers finishedAtMs; falls back to startedAtMs for reports from adapters
+ * that only stamp a start time.
+ */
+declare function reportLastRunMs(report: Pick<StoryReport, "startedAtMs" | "finishedAtMs">): number | undefined;
+/**
+ * Human-readable age like "just now", "5 minutes ago", "3 hours ago",
+ * "12 days ago". Clock skew (thenMs in the future) reads as "just now".
+ */
+declare function formatRelativeAge(thenMs: number, nowMs: number): string;
+/**
+ * A report is stale once its run is `staleAfterDays` or more days old.
+ * A threshold of 0 (or negative) disables staleness entirely.
+ */
+declare function isReportStale(lastRunMs: number | undefined, staleAfterDays: number, nowMs: number): boolean;
+declare function ciDisplayName(name: string): string;
+/**
+ * Derive a browsable commit URL from the CI run URL, for the providers whose
+ * URL structure makes that safe:
+ *   GitHub Actions  …/owner/repo/actions/runs/123      -> …/owner/repo/commit/<sha>
+ *   GitLab CI       …/group/project/-/pipelines/123    -> …/group/project/-/commit/<sha>
+ * Other providers return undefined (a wrong link is worse than none).
+ */
+declare function commitUrl(ci: ReportCI | undefined, sha: string | undefined): string | undefined;
+/**
+ * Derive a pull-request URL for GitHub-shaped CI run URLs. GitLab and the
+ * rest return undefined for the same wrong-link-is-worse-than-none reason.
+ */
+declare function prUrl(ci: ReportCI | undefined): string | undefined;
+
+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 RunStreak {
+    status: ScenarioRunStatus;
+    /** How many consecutive trailing runs share that status (≥1). */
+    count: number;
+}
+/** The trailing same-status streak — "passing for 5 runs", "failing for 2". */
+declare function currentStreak(entries: readonly ScenarioRunEvent[]): RunStreak | undefined;
+/** Short human summary of a history window, used for the strip's tooltip. */
+declare function describeRunHistory(entries: readonly ScenarioRunEvent[]): string;
+
+/**
+ * Compact run-over-run timeline for one scenario: a dot per recent run,
+ * oldest → newest. Renders nothing outside <ReportInteractive> or when the
+ * report was generated without --history-file — history is presentation-layer
+ * data and never part of the StoryReport contract.
+ */
+declare function ScenarioRunHistory({ scenarioId }: {
+    scenarioId: string;
+}): react.JSX.Element | null;
+
 interface ReportEmptyProps {
     message?: string;
 }
@@ -291,7 +589,7 @@ interface ReportSchemaErrorProps {
 }
 declare function ReportSchemaError({ error }: ReportSchemaErrorProps): react.JSX.Element;
 
-declare function useReport(): executable_stories_core.StoryReport;
+declare function useReport(): StoryReport;
 
 /**
  * parseStoryReport — boundary validator. Accepts unknown input (file contents,
@@ -321,4 +619,4 @@ declare const STORY_REPORT_SCHEMA_MAJOR: 1;
 
 declare const storyReportSchema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
 
-export { type BuiltinRenderers, type CustomRenderer, type CustomRenderers, DocCode, DocCustom, DocEntry, DocHtml, DocKv, DocLink, DocMermaid, DocNote, DocScreenshot, DocSection, DocTable, DocTag, DocVideo, type ExplorerScenario, type ExplorerStatus, MermaidDiagram, MermaidSource, Report, ReportAttachments, ReportDocEntries, type ReportDocEntriesProps, ReportEmpty, type ReportEmptyProps, ReportFeature, ReportFeatureList, type ReportFeatureProps, ReportMeta, type ReportParseError, type ReportParseErrorCode, type ReportProps, ReportRoot, type ReportRootProps, ReportScenario, ReportScenarioList, type ReportScenarioListProps, type ReportScenarioProps, ReportSchemaError, type ReportSchemaErrorProps, ReportStepItem, ReportSteps, type ReportStepsProps, ReportSummary, type ReportSummaryProps, ReportSummaryView, type ReportSummaryViewProps, ReportTrace, type Result, STORY_REPORT_SCHEMA_MAJOR, ScenarioExplorer, type ScenarioExplorerProps, err, ok, parseStoryReport, storyReportSchema, useBuiltinRenderers, useCustomRenderers, useReport };
+export { type BuiltinRenderers, type CustomRenderer, type CustomRenderers, DocCode, DocCustom, DocEntry, DocHtml, DocKv, DocLink, DocMermaid, DocNote, DocScreenshot, DocSection, DocTable, DocTag, DocVideo, type ExplorerScenario, type ExplorerStatus, MermaidDiagram, MermaidSource, Report, ReportAttachments, ReportDocEntries, type ReportDocEntriesProps, ReportEmpty, type ReportEmptyProps, ReportFeature, ReportFeatureList, type ReportFeatureProps, ReportMeta, type ReportParseError, type ReportParseErrorCode, type ReportProps, ReportRoot, type ReportRootProps, ReportScenario, ReportScenarioList, type ReportScenarioListProps, type ReportScenarioProps, ReportSchemaError, type ReportSchemaErrorProps, ReportStepItem, ReportSteps, type ReportStepsProps, ReportSummary, type ReportSummaryProps, ReportSummaryView, type ReportSummaryViewProps, ReportTrace, type Result, type RunStreak, STORY_REPORT_SCHEMA_MAJOR, ScenarioExplorer, type ScenarioExplorerProps, type ScenarioHistoryMap, type ScenarioRunEvent, ScenarioRunHistory, type ScenarioRunStatus, type StoryReport, type ReportDocEntry as StoryReportDocEntry, type ReportFeature$1 as StoryReportFeature, type ReportScenario$1 as StoryReportScenario, type ReportStep as StoryReportStep, type ReportSummary$1 as StoryReportSummary, ciDisplayName, commitUrl, currentStreak, describeRunHistory, err, formatRelativeAge, isReportStale, ok, parseStoryReport, prUrl, reportLastRunMs, storyReportSchema, useBuiltinRenderers, useCustomRenderers, useReport };