executable-stories-formatters 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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-DyeUWfYK.js';
-export { h as DocPhase, J as JestAdapterOptions, i as JestAggregatedResult, j as JestFileResult, k as JestTestResult, O as OtelAttributeValue, l as OtelSpan, P as PlaywrightAdapterOptions, m as PlaywrightAnnotation, n as PlaywrightAttachment, o as PlaywrightError, p as PlaywrightLocation, q as PlaywrightStatus, r as PlaywrightTestCase, s as PlaywrightTestResult, t as RawStepEvent, u as RawTestCase, v as STORY_META_KEY, w as StepKeyword, x as StepMode, y as StoryFileReport, V as VitestAdapterOptions, z as VitestSerializedError, A as VitestState, B as VitestTestCase, C as VitestTestModule, E as VitestTestResult } from './index-DyeUWfYK.js';
+import { S as StoryMeta, C as CIInfo$1, a as StoryStep, D as DocEntry, R as RawStatus, b as RawAttachment, c as RawRun, d as CIProvider, e as RawCIInfo, f as adaptJestRun, g as adaptPlaywrightRun, h as adaptVitestRun } from './index-C4QO-SVT.js';
+export { i as DocPhase, J as JestAdapterOptions, j as JestAggregatedResult, k as JestFileResult, l as JestTestResult, O as OtelAttributeValue, m as OtelSpan, P as PlaywrightAdapterOptions, n as PlaywrightAnnotation, o as PlaywrightAttachment, p as PlaywrightError, q as PlaywrightLocation, r as PlaywrightStatus, s as PlaywrightTestCase, t as PlaywrightTestResult, u as RawStepEvent, v as RawTestCase, w as STORY_META_KEY, x as StepKeyword, y as StepMode, z as StoryFileReport, V as VitestAdapterOptions, A as VitestSerializedError, B as VitestState, E as VitestTestCase, F as VitestTestModule, G as VitestTestResult, H as toCIInfo, I as toRawCIInfo } from './index-C4QO-SVT.js';
 
 /**
  * Canonical types for Layer 2: Anti-Corruption Layer output.
@@ -85,6 +85,9 @@ interface CIInfo {
     name: string;
     url?: string;
     buildNumber?: string;
+    branch?: string;
+    commitSha?: string;
+    prNumber?: string;
 }
 /** Coverage summary for the test run */
 interface CoverageSummary {
@@ -121,6 +124,54 @@ interface TestRunResult {
     coverage?: CoverageSummary;
 }
 
+/**
+ * Notification types for webhook integrations (Slack, Teams).
+ */
+
+/** Summary of a test run for notification payloads. */
+interface NotificationSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    durationMs: number;
+    failedTests: Array<{
+        testId?: string;
+        name: string;
+        error?: string;
+    }>;
+    ci?: CIInfo$1;
+    reportUrl?: string;
+}
+/** When to send notifications. */
+type NotifyCondition = "always" | "on-failure" | "never";
+/** HMAC-SHA256 signing configuration for generic webhooks. */
+interface WebhookSignerHmac {
+    type: "hmac-sha256";
+    /** Secret key for HMAC computation */
+    secret: string;
+    /** Request header name for signature, e.g. "X-Signature" */
+    header: string;
+    /** Include timestamp in signed payload and emit timestamp header? */
+    includeTimestamp?: boolean;
+    /** Request header name for timestamp (default: "X-Timestamp"). Only emitted when includeTimestamp is true. */
+    timestampHeader?: string;
+}
+/** Configuration for a generic webhook endpoint. */
+interface GenericWebhookNotifierOptions {
+    url: string;
+    condition?: NotifyCondition;
+    method?: "POST" | "PUT";
+    headers?: Record<string, string>;
+    signer?: WebhookSignerHmac;
+}
+/** Versioned envelope sent to generic webhooks. */
+interface WebhookPayload {
+    schemaVersion: 1;
+    event: "test_run_finished";
+    summary: NotificationSummary;
+}
+
 /**
  * Configuration options for ACL and formatters.
  */
@@ -247,6 +298,28 @@ interface FormatterOptions {
     };
     /** Markdown specific options */
     markdown?: MarkdownFormatterOptions;
+    /** History tracking options */
+    history?: {
+        /** Path to JSON history file (enables tracking) */
+        filePath?: string;
+        /** Max runs to keep in history per test. Default: 10 */
+        maxRuns?: number;
+    };
+    /** Notification options */
+    notification?: {
+        /** Slack webhook URL (fallback: SLACK_WEBHOOK_URL env var) */
+        slackWebhookUrl?: string;
+        /** Teams webhook URL (fallback: TEAMS_WEBHOOK_URL env var) */
+        teamsWebhookUrl?: string;
+        /** When to send: "always", "on-failure", "never". Default: "on-failure" */
+        condition?: NotifyCondition;
+        /** URL to link in notifications */
+        reportUrl?: string;
+        /** Max failed tests to show. Default: 5 */
+        maxFailedTests?: number;
+        /** Generic webhook configurations */
+        webhooks?: GenericWebhookNotifierOptions[];
+    };
     /** Logger for warnings and info. Default: console */
     logger?: Logger;
     /** File writer function. Default: fs.promises.writeFile */
@@ -736,6 +809,51 @@ declare class CucumberJsonFormatter {
     private docEntryToArgument;
 }
 
+/**
+ * Types for history tracking and test metrics.
+ */
+
+interface HistoryEntry {
+    runId: string;
+    timestamp: number;
+    status: "passed" | "failed" | "skipped" | "pending";
+    durationMs: number;
+    ci?: {
+        provider?: CIProvider;
+        branch?: string;
+        commitSha?: string;
+    };
+}
+interface TestHistory {
+    testId: string;
+    testName: string;
+    sourceFile: string;
+    sourceLine?: number;
+    entries: HistoryEntry[];
+}
+interface HistoryStore {
+    version: 1;
+    maxRuns: number;
+    tests: Record<string, TestHistory>;
+    lastUpdated: number;
+}
+type StabilityGrade = "A" | "B" | "C" | "D" | "F";
+type FlakinessLevel = "stable" | "unstable" | "flaky";
+type PerformanceTrend = "improving" | "stable" | "regressing";
+interface TestMetrics {
+    testId: string;
+    flakinessLevel: FlakinessLevel;
+    flakinessScore: number;
+    failureRate: number;
+    stabilityGrade: StabilityGrade;
+    performanceTrend: PerformanceTrend;
+    avgDurationMs: number;
+    passRate: number;
+    longestPassStreak: number;
+    consecutiveFailures: number;
+    sampleSize: number;
+}
+
 /**
  * HTML Formatter - Layer 3.
  *
@@ -1371,8 +1489,19 @@ 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
+ * Detects known CI providers from environment variables and populates
+ * branch, commit SHA, PR number, build number, and URL metadata.
+ *
+ * Precedence (checked in order, first match wins):
+ *   1. TF_BUILD=True        -> azure
+ *   2. BUILDKITE=true        -> buildkite
+ *   3. GITHUB_ACTIONS=true   -> github
+ *   4. GITLAB_CI=true        -> gitlab
+ *   5. CIRCLECI=true         -> circleci
+ *   6. JENKINS_URL defined   -> jenkins
+ *   7. TRAVIS=true           -> travis
+ *   8. CI=true               -> unknown (generic fallback; note: fires in dev shells too)
+ *   9. Nothing               -> undefined (not in CI)
  */
 
 /**
@@ -1402,6 +1531,275 @@ declare function tryGetActiveOtelContext(): OtelTraceContext | undefined;
  */
 declare function resolveTraceUrl(template: string | undefined, traceId: string): string | undefined;
 
+/**
+ * Notification orchestrator.
+ *
+ * Builds a NotificationSummary from a TestRunResult and dispatches
+ * to configured notifiers (Slack, Teams, generic webhooks) based on condition.
+ *
+ * Env fallback and defaults are resolved internally so CLI and reporters
+ * behave identically with zero duplication.
+ *
+ * Follows the fn(args, deps) pattern.
+ * Never throws. Never logs webhook URLs.
+ */
+
+/** Arguments for sendNotifications. */
+interface SendNotificationsArgs {
+    run: TestRunResult;
+    /** Notification config from FormatterOptions.notification (or CLI-assembled equivalent) */
+    notification?: {
+        slackWebhookUrl?: string;
+        teamsWebhookUrl?: string;
+        condition?: NotifyCondition;
+        reportUrl?: string;
+        maxFailedTests?: number;
+        webhooks?: GenericWebhookNotifierOptions[];
+    };
+}
+/** Injectable dependencies for sendNotifications. */
+interface SendNotificationsDeps {
+    fetch?: typeof globalThis.fetch;
+    logger: {
+        warn(msg: string): void;
+    };
+    toCIInfo: (raw?: RawCIInfo) => CIInfo$1 | undefined;
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Send notifications to all configured channels.
+ *
+ * Resolves env fallbacks and defaults internally.
+ * Never throws. Logs warnings for failures.
+ * Never logs webhook URLs.
+ */
+declare function sendNotifications(args: SendNotificationsArgs, deps: SendNotificationsDeps): Promise<void>;
+
+/**
+ * Slack webhook notifier using Block Kit.
+ *
+ * Follows the fn(args, deps) pattern.
+ * Never logs the webhook URL.
+ */
+
+/** Arguments for sendSlackNotification. */
+interface SlackNotificationArgs {
+    summary: NotificationSummary;
+    webhookUrl: string;
+    maxFailedTests?: number;
+}
+/** Injectable dependencies for sendSlackNotification. */
+interface SlackNotificationDeps {
+    fetch: typeof globalThis.fetch;
+    logger: {
+        warn(msg: string): void;
+    };
+}
+/** Result of a notification send attempt. */
+interface NotificationResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Send a Slack notification via incoming webhook.
+ *
+ * Never throws. Returns `{ ok, error? }`.
+ * Never logs the webhook URL.
+ */
+declare function sendSlackNotification(args: SlackNotificationArgs, deps: SlackNotificationDeps): Promise<NotificationResult>;
+
+/**
+ * Microsoft Teams webhook notifier using Adaptive Cards.
+ *
+ * Follows the fn(args, deps) pattern.
+ * Never logs the webhook URL.
+ */
+
+/** Arguments for sendTeamsNotification. */
+interface TeamsNotificationArgs {
+    summary: NotificationSummary;
+    webhookUrl: string;
+    maxFailedTests?: number;
+}
+/** Injectable dependencies for sendTeamsNotification. */
+interface TeamsNotificationDeps {
+    fetch: typeof globalThis.fetch;
+    logger: {
+        warn(msg: string): void;
+    };
+}
+/** Result of a notification send attempt. */
+interface TeamsNotificationResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Send a Teams notification via incoming webhook.
+ *
+ * Never throws. Returns `{ ok, error? }`.
+ * Never logs the webhook URL.
+ */
+declare function sendTeamsNotification(args: TeamsNotificationArgs, deps: TeamsNotificationDeps): Promise<TeamsNotificationResult>;
+
+/**
+ * Generic webhook notifier.
+ *
+ * Sends a versioned JSON envelope to arbitrary HTTP endpoints with optional
+ * HMAC-SHA256 signing. Follows the fn(args, deps) pattern.
+ *
+ * Never throws. Never logs the webhook URL.
+ */
+
+/** Arguments for sendWebhookNotification. */
+interface WebhookNotificationArgs {
+    summary: NotificationSummary;
+    options: GenericWebhookNotifierOptions;
+    maxFailedTests?: number;
+}
+/** Injectable dependencies for sendWebhookNotification. */
+interface WebhookNotificationDeps {
+    fetch: typeof globalThis.fetch;
+    logger: {
+        warn(msg: string): void;
+    };
+}
+/** Result of a webhook send attempt. */
+interface WebhookNotificationResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Send a notification to a generic webhook endpoint.
+ *
+ * Never throws. Returns `{ ok, error? }`.
+ * Never logs the webhook URL.
+ */
+declare function sendWebhookNotification(args: WebhookNotificationArgs, deps: WebhookNotificationDeps): Promise<WebhookNotificationResult>;
+
+/**
+ * HMAC-SHA256 signing for generic webhook payloads.
+ *
+ * Pure function, isolated for testing.
+ * Uses node:crypto — zero new dependencies.
+ */
+/** Result of HMAC signing. */
+interface HmacSignResult {
+    /** Signature in format "sha256=<hex>" (GitHub-style, widely recognized) */
+    signature: string;
+    /** ISO 8601 timestamp, only present when includeTimestamp is true */
+    timestamp?: string;
+}
+/**
+ * Compute HMAC-SHA256 signature for a request body.
+ *
+ * When `includeTimestamp` is true, the signed input is `"<timestamp>.<body>"` and the
+ * timestamp is returned for the caller to emit as a header.
+ */
+declare function signBody(args: {
+    body: string;
+    secret: string;
+    includeTimestamp?: boolean;
+    /** Injectable for deterministic testing */
+    timestamp?: string;
+}): HmacSignResult;
+
+/**
+ * No-dependency ANSI escape sequence stripper.
+ */
+/** Strip ANSI escape sequences. Regex: \x1B\[[0-?]*[ -/]*[@-~] */
+declare function stripAnsi(text: string): string;
+
+/**
+ * History store: load, save, update (fn(args, deps) pattern).
+ */
+
+interface LoadHistoryArgs {
+    filePath: string;
+}
+interface LoadHistoryDeps {
+    readFile: (path: string) => string | undefined;
+    logger: {
+        warn(msg: string): void;
+    };
+}
+declare function loadHistory(args: LoadHistoryArgs, deps: LoadHistoryDeps): HistoryStore;
+interface SaveHistoryArgs {
+    filePath: string;
+    store: HistoryStore;
+}
+interface SaveHistoryDeps {
+    writeFile: (path: string, content: string) => void;
+}
+declare function saveHistory(args: SaveHistoryArgs, deps: SaveHistoryDeps): void;
+interface UpdateHistoryArgs {
+    store: HistoryStore;
+    run: TestRunResult;
+    maxRuns: number;
+}
+declare function updateHistory(args: UpdateHistoryArgs): HistoryStore;
+
+/**
+ * Flakiness calculation based on status transitions.
+ */
+
+interface FlakinessResult {
+    flakinessLevel: FlakinessLevel;
+    flakinessScore: number;
+    failureRate: number;
+    longestPassStreak: number;
+    longestFailStreak: number;
+}
+declare function calculateFlakiness(args: {
+    entries: HistoryEntry[];
+}): FlakinessResult;
+
+/**
+ * Performance trend detection via half-split comparison.
+ */
+
+interface PerformanceResult {
+    trend: PerformanceTrend;
+    avgDurationMs: number;
+}
+declare function detectPerformanceTrend(args: {
+    entries: HistoryEntry[];
+}): PerformanceResult;
+
+/**
+ * Stability grade calculation (composite score).
+ */
+
+interface CalculateStabilityArgs {
+    passRate: number;
+    flakinessScore: number;
+    longestPassStreak: number;
+    sampleSize: number;
+}
+declare function calculateStability(args: CalculateStabilityArgs): StabilityGrade;
+
+/**
+ * Composite test metrics from history entries.
+ */
+
+declare function computeTestMetrics(args: {
+    testId: string;
+    entries: HistoryEntry[];
+}): TestMetrics;
+
+/**
+ * Centralized sample-size policy for history metrics.
+ *
+ * Easy to tune without hunting across files.
+ */
+/** Minimum duration-bearing entries for performance trend analysis. */
+declare const MIN_PERF_SAMPLES = 6;
+/** Minimum entries before showing badges/metrics in reports. */
+declare const MIN_METRIC_SAMPLES = 5;
+/** Minimum entries for flakiness calculation (below this → "stable"). */
+declare const MIN_FLAKINESS_SAMPLES = 3;
+/** Check whether an array meets the minimum sample threshold. */
+declare function hasSufficientHistory(entries: unknown[], min: number): boolean;
+
 /**
  * @executable-stories/formatters
  *
@@ -1491,4 +1889,4 @@ declare function normalizeVitestResults(testModules: Parameters<typeof adaptVite
  */
 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 OtelTraceContext, 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, resolveTraceUrl, slugify, tryGetActiveOtelContext, validateCanonicalRun };
+export { type Attachment, type CIInfo, CIProvider, type CanonicalizeOptions, type ColocatedStyle, type CoverageSummary, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DocEntry, type FlakinessLevel, type FormatterOptions, type GenerateArgs, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type HistoryEntry, type HistoryStore, 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, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type NotificationSummary, type NotifyCondition, type OtelTraceContext, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, type PerformanceTrend, RawAttachment, RawCIInfo, RawRun, RawStatus, ReportGenerator, type ResolvedFormatterOptions, type StabilityGrade, type StepResult, StoryMeta, StoryStep, type TestCaseAttempt, type TestCaseResult, type TestHistory, type TestMetrics, type TestRunResult, type TestStatus, CIInfo$1 as TypedCIInfo, type ValidationResult, type WebhookPayload, type WebhookSignerHmac, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, assertValidRun, calculateFlakiness, calculateStability, canonicalizeRun, clearVersionCache, computeTestMetrics, createReportGenerator, deriveStepResults, detectCI, detectPerformanceTrend, findGitDir, formatDuration, generateRunId, generateTestCaseId, hasSufficientHistory, loadHistory, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, readBranchName, readGitSha, readPackageVersion, resolveAttachment, resolveAttachments, resolveTraceUrl, saveHistory, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, signBody, slugify, stripAnsi, tryGetActiveOtelContext, updateHistory, validateCanonicalRun };