executable-stories-formatters 1.12.0 → 1.14.0

package/dist/index.d.cts

@@ -1655,6 +1655,20 @@ interface ScenarioIndex {
     summary: StoryReport["summary"];
     scenarios: ScenarioIndexItem[];
 }
+/**
+ * One scenario as this formatter emits it.
+ *
+ * This is an OUTPUT type: it describes what `toScenarioIndex` produces, which
+ * is why `hash` and `assertionState` are required here while
+ * `scenario-index-v1.json` marks both optional. The schema is deliberately the
+ * laxer of the two so artifacts written before either field existed still
+ * validate; every artifact written since carries them.
+ *
+ * The consequence, and it is intended: parsing an arbitrary v1 file and casting
+ * it to this type is not sound for those two fields. Validate against the
+ * schema and treat them as optional if you are reading files you did not just
+ * write.
+ */
 interface ScenarioIndexItem {
     id: string;
     title: string;
@@ -1681,6 +1695,12 @@ interface ScenarioIndexItem {
         message: string;
         stack?: string;
     };
+    /**
+     * Whether the scenario's claim was checked: `asserted`, `unasserted`, or
+     * `unobserved` where the adapter cannot count. A passing scenario that is
+     * `unasserted` ran and proved nothing.
+     */
+    assertionState: "asserted" | "unasserted" | "unobserved";
 }
 interface ScenarioIndexStep {
     id: string;
@@ -1691,6 +1711,11 @@ interface ScenarioIndexStep {
     durationMs: number;
     errorMessage?: string;
     docKinds: string[];
+    /**
+     * Assertions the framework observed. Absent means the adapter has no counter;
+     * `0` means it counted none. Never defaulted — the difference is the point.
+     */
+    assertions?: number;
 }
 interface ScenarioIndexFilters {
     statuses?: TestStatus$1[];
@@ -1812,6 +1837,82 @@ interface WatchHandle {
  */
 declare function startWatch(options: WatchOptions, deps?: WatchDeps): WatchHandle;
 
+interface AggregateDeps {
+    readFile: (filePath: string) => string;
+    listDir: (dir: string) => string[] | undefined;
+    logger: {
+        warn(msg: string): void;
+    };
+}
+interface AggregateResult {
+    run: TestRunResult;
+    /** How many per-file reports went into it. */
+    files: number;
+    /** Reports that could not be parsed. Named, never silently skipped. */
+    unreadable: string[];
+    /** Scenario ids claimed by more than one report. */
+    duplicateIds: string[];
+}
+/**
+ * Read every per-file report in `dir` and combine them into one run.
+ *
+ * Returns undefined when the directory holds no reports, so a caller can tell
+ * "nothing here yet" from "here is an empty run".
+ */
+declare function aggregateReports(args: {
+    dir: string;
+}, deps: AggregateDeps): AggregateResult | undefined;
+
+interface RunsLifecycleDeps {
+    readFile: (filePath: string) => string;
+    listDir: (dir: string) => string[] | undefined;
+    removeFile: (filePath: string) => void;
+    logger: {
+        warn(msg: string): void;
+    };
+}
+/** What one test file's report looks like from the outside. */
+interface AccumulatedFile {
+    sourceFile: string;
+    scenarios: number;
+    /** When this file's newest scenario last ran, or undefined if none say. */
+    lastRunAtMs?: number;
+    lastRunGitSha?: string;
+}
+interface RunsStatusReport {
+    /** Path of the reports directory, for the reader to go look. */
+    directory: string;
+    exists: boolean;
+    files: AccumulatedFile[];
+    totalScenarios: number;
+    /** Reports that could not be parsed. Named, never silently skipped. */
+    unreadable: string[];
+    /** Human-readable rendering, what the CLI prints. */
+    text: string;
+}
+/**
+ * What the report would be built from right now: every test file the state
+ * holds, how many scenarios each contributes, and how old those results are.
+ */
+declare function runsStatus(args: {
+    outputDir: string;
+    nowMs: number;
+}, deps: RunsLifecycleDeps): RunsStatusReport;
+interface RunsResetResult {
+    directory: string;
+    removed: number;
+    text: string;
+}
+/**
+ * Delete every per-file report. The next full test run writes them again.
+ *
+ * Removes only this directory's reports; anything rendered beside it in the
+ * output folder is the user's own output and is left alone.
+ */
+declare function runsReset(args: {
+    outputDir: string;
+}, deps: RunsLifecycleDeps): RunsResetResult;
+
 interface BehaviorDiffEntry {
     id: string;
     title: string;
@@ -2888,6 +2989,23 @@ interface GenerateDeps {
     logger: Logger;
     /** File writer function */
     writeFile: WriteFile;
+    /** Read a file. Throws when it is not there, like `fs.readFileSync`. */
+    readFile: (filePath: string) => string;
+    /** List a directory's entries, or undefined when it is not one. */
+    listDir: (dir: string) => string[] | undefined;
+    /** True when the path is present in the working tree. */
+    fileExists: (filePath: string) => boolean;
+    /** Delete a file. Absent paths are not an error. */
+    removeFile: (filePath: string) => Promise<void>;
+}
+/** Options for one `generate` call. */
+interface GenerateOptions {
+    /**
+     * Whether this run owns the reports of the files it covers and should update
+     * them. True for a test run. False when rendering an already-assembled run,
+     * such as the aggregate of a shard directory, which owns nothing.
+     */
+    persist?: boolean;
 }
 /** Result of generate function: Map of format to array of file paths */
 type GenerateResult = Map<OutputFormat, string[]>;
@@ -2913,7 +3031,24 @@ declare function normalizeFormats(formats: ReadonlyArray<FormatInput>): OutputFo
 declare class ReportGenerator {
     private options;
     private deps;
+    /**
+     * The run the last `generate()` actually rendered: this run folded into what
+     * previous runs accumulated. Callers that report on the output (the CLI's
+     * summary line) need to describe what was written, not just what was handed
+     * in. Undefined before the first generate.
+     */
+    private lastRenderedRun?;
+    /**
+     * What the execution formats rendered: this run after the same selection the
+     * documentation set gets. The CLI counts whichever set its output actually
+     * contains, so an excluded scenario is not reported as written.
+     */
+    private lastExecutedRun?;
     constructor(options?: FormatterOptions, deps?: Partial<GenerateDeps>);
+    /** The run the last `generate()` rendered, stored reports included. */
+    get renderedRun(): TestRunResult | undefined;
+    /** What the last `generate()` handed the execution formats. */
+    get executedRun(): TestRunResult | undefined;
     /**
      * Resolve options with defaults.
      */
@@ -2924,7 +3059,7 @@ declare class ReportGenerator {
      * @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(run: TestRunResult, options?: GenerateOptions): Promise<GenerateResult>;
     /**
      * Whether any output is colocated — the global mode, or any per-rule mode.
      * A colocated rule under a global aggregated mode still writes per-file
@@ -3387,4 +3522,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 AdapterDeps, AgentTextFormatter, type AnchorResolution, type AnchorState, type AstroAssetResult, AstroFormatter, type AstroFormatterOptions as AstroFormatterOpts, type AttachPolicy, type BehaviorDebuggerIssue, type BehaviorDiff, type BehaviorDiffEntry, type BehaviorManifest, BehaviorManifestJsonFormatter, type BehaviorManifestJsonOptions, type BehaviorSourceFile, type BehaviorTag, type BundleOptions, type BundleResult, type CaseBody, type CaseResult, type ChangeType, type ChangedFile, type ChangedFileReview, type CheckArgs, type CheckDeps, type CheckFailure, type CheckReport, type CheckStep, type CodeDiffAnnotation, type CodeDiffAnnotationInput, type CodeDiffEvidence, type CodeDiffInput, type CodeDiffScenarioRef, type CodeDiffSidecar, type CodeDiffSidecarAnnotation, type ColocatedStyle, type CompareFormat, type CompareFormatterOptions, type ConfluenceAuth, ConfluenceFormatter, type ConfluenceFormatterOptions as ConfluenceFormatterOpts, type CopyMarkdownAssetsOptions, type CoverageClass, type CoverageJson, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DEFAULT_LOCKFILE_PATH, type DeploymentEntry, type DeploymentLedger, type DeploymentStatus, type DiffAnchor, type DiffHunk, type DiffLine, type DiffRunsOptions, type EnvironmentDrift, type EvidenceStrength, type ExecutableStoriesConfig, type FetchFn, type FileChangeKind, type FileDiff, type FlakinessLevel, type Formatter, type FormatterOptions, type GenerateArgs, type GenerateCompareResult, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type GoalArgs, type GoalDeps, type GoalReport, type GoalRequirementResult, type HistoryEntry, type HistoryStore, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type JiraAuth, type JiraPublishMode, type ListScenariosArgs, type ListScenariosDeps, type LockEntry, type Lockfile, type Logger, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type NotificationSummary, type NotifyCondition, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, PROVIDER_NAMES, type PerformanceTrend, type ProviderName, type PublishConfluenceArgs, type PublishConfluenceDeps, type PublishConfluenceResult, type PublishJiraArgs, type PublishJiraDeps, type PublishJiraResult, type RatchetViolation, type RecordDeploymentArgs, type RecordDeploymentResult, type RecordResultsSummary, type ReleaseManifest, ReleaseManifestFormatter, type RemoteCase, ReportGenerator, type ResolvedFormatterOptions, type ResultAttachment, type ReviewAudience, type ReviewBand, type ReviewClaim, type ReviewContext, ReviewHtmlFormatter, type ReviewHtmlOptions, ReviewMarkdownFormatter, type ReviewMarkdownOptions, type ReviewResult, type ReviewSummary, RunDiffChangelogFormatter, type RunDiffChangelogOptions, RunDiffHtmlFormatter, type RunDiffHtmlOptions, RunDiffMarkdownFormatter, type RunDiffMarkdownOptions, type RunDiffResult, type RunDiffSummary, type ScenarioChangeFlags, type ScenarioChangeKind, type ScenarioDiff, type ScenarioIndex, type ScenarioIndexFilters, type ScenarioIndexItem, ScenarioIndexJsonFormatter, type ScenarioIndexJsonOptions, type ScenarioIndexStep, type ScenarioSnapshot, type SortTestCasesMode, type StabilityGrade, type StarlightBadge, StoryReportJsonFormatter, type StoryReportJsonOptions, type SyncAnalysis, type SyncApplyResult, type SyncEngineConfig, type SyncProvider, type SyncTargets, type TestHistory, type TestMetrics, type TestRailConfig, TraceabilityCsvFormatter, type TraceabilityMatrix, TraceabilityMatrixFormatter, type TraceabilityRequirement, type TriageArgs, type TriageDeps, type TriageItem, type TriageReport, type WatchDeps, type WatchHandle, type WatchOptions, type WebhookPayload, type WebhookSignerHmac, type WriteFile, type XrayConfig, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, analyzeSync, applySync, assembleCodeDiff, buildCheck, buildCoverageJson, buildGoal, buildProvider, buildReview, buildTriage, bundleAssets, calculateFlakiness, calculateStability, classifyStatusChange, clearVersionCache, codeDiffDiagnostics, collectAttachments, computeTestMetrics, copyMarkdownAssets, createAnchor, createPrCommentSummary, createReportGenerator, createTestRailProvider, createXrayProvider, deriveAudience, deriveChangeType, detectCI, detectPerformanceTrend, diffRuns, diffStoryReports, emptyLockfile, findGitDir, generateRunComparison, getDeploymentStatus, getEnvironmentDrift, gradeEvidence, hasSufficientHistory, hashCaseBody, isProviderName, isReviewableSource, isTestFile, joinNameAndExt, listScenarios, loadHistory, normalizeFormats, normalizeJestResults, normalizePlaywrightResults, normalizeVitestResults, parseLockfile, parseUnifiedDiff, projectBehaviours, publishConfluencePage, publishJiraIssue, readBranchName, readGitSha, readLockfile, readPackageVersion, recordDeployment, regenerateArtifacts, regenerateRun, relocateAnchor, renderApplyResult, renderCheck, renderCoverageMarkdown, renderCoverageText, renderGoal, renderPlan, renderTriage, rewriteAssetPaths, saveHistory, scenariosCoveringPaths, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, serializeLockfile, signBody, startWatch, stripAnsi, toAgentText, toBehaviorManifest, toCaseBody, toReleaseManifest, toScenarioIndex, toTraceabilityMatrix, updateHistory, writeLockfile };
+export { type AdapterDeps, AgentTextFormatter, type AggregateDeps, type AggregateResult, type AnchorResolution, type AnchorState, type AstroAssetResult, AstroFormatter, type AstroFormatterOptions as AstroFormatterOpts, type AttachPolicy, type BehaviorDebuggerIssue, type BehaviorDiff, type BehaviorDiffEntry, type BehaviorManifest, BehaviorManifestJsonFormatter, type BehaviorManifestJsonOptions, type BehaviorSourceFile, type BehaviorTag, type BundleOptions, type BundleResult, type CaseBody, type CaseResult, type ChangeType, type ChangedFile, type ChangedFileReview, type CheckArgs, type CheckDeps, type CheckFailure, type CheckReport, type CheckStep, type CodeDiffAnnotation, type CodeDiffAnnotationInput, type CodeDiffEvidence, type CodeDiffInput, type CodeDiffScenarioRef, type CodeDiffSidecar, type CodeDiffSidecarAnnotation, type ColocatedStyle, type CompareFormat, type CompareFormatterOptions, type ConfluenceAuth, ConfluenceFormatter, type ConfluenceFormatterOptions as ConfluenceFormatterOpts, type CopyMarkdownAssetsOptions, type CoverageClass, type CoverageJson, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DEFAULT_LOCKFILE_PATH, type DeploymentEntry, type DeploymentLedger, type DeploymentStatus, type DiffAnchor, type DiffHunk, type DiffLine, type DiffRunsOptions, type EnvironmentDrift, type EvidenceStrength, type ExecutableStoriesConfig, type FetchFn, type FileChangeKind, type FileDiff, type FlakinessLevel, type Formatter, type FormatterOptions, type GenerateArgs, type GenerateCompareResult, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type GoalArgs, type GoalDeps, type GoalReport, type GoalRequirementResult, type HistoryEntry, type HistoryStore, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type JiraAuth, type JiraPublishMode, type ListScenariosArgs, type ListScenariosDeps, type LockEntry, type Lockfile, type Logger, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type NotificationSummary, type NotifyCondition, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, PROVIDER_NAMES, type PerformanceTrend, type ProviderName, type PublishConfluenceArgs, type PublishConfluenceDeps, type PublishConfluenceResult, type PublishJiraArgs, type PublishJiraDeps, type PublishJiraResult, type RatchetViolation, type RecordDeploymentArgs, type RecordDeploymentResult, type RecordResultsSummary, type ReleaseManifest, ReleaseManifestFormatter, type RemoteCase, ReportGenerator, type ResolvedFormatterOptions, type ResultAttachment, type ReviewAudience, type ReviewBand, type ReviewClaim, type ReviewContext, ReviewHtmlFormatter, type ReviewHtmlOptions, ReviewMarkdownFormatter, type ReviewMarkdownOptions, type ReviewResult, type ReviewSummary, RunDiffChangelogFormatter, type RunDiffChangelogOptions, RunDiffHtmlFormatter, type RunDiffHtmlOptions, RunDiffMarkdownFormatter, type RunDiffMarkdownOptions, type RunDiffResult, type RunDiffSummary, type RunsResetResult, type RunsStatusReport, type ScenarioChangeFlags, type ScenarioChangeKind, type ScenarioDiff, type ScenarioIndex, type ScenarioIndexFilters, type ScenarioIndexItem, ScenarioIndexJsonFormatter, type ScenarioIndexJsonOptions, type ScenarioIndexStep, type ScenarioSnapshot, type SortTestCasesMode, type StabilityGrade, type StarlightBadge, StoryReportJsonFormatter, type StoryReportJsonOptions, type SyncAnalysis, type SyncApplyResult, type SyncEngineConfig, type SyncProvider, type SyncTargets, type TestHistory, type TestMetrics, type TestRailConfig, TraceabilityCsvFormatter, type TraceabilityMatrix, TraceabilityMatrixFormatter, type TraceabilityRequirement, type TriageArgs, type TriageDeps, type TriageItem, type TriageReport, type WatchDeps, type WatchHandle, type WatchOptions, type WebhookPayload, type WebhookSignerHmac, type WriteFile, type XrayConfig, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, aggregateReports, analyzeSync, applySync, assembleCodeDiff, buildCheck, buildCoverageJson, buildGoal, buildProvider, buildReview, buildTriage, bundleAssets, calculateFlakiness, calculateStability, classifyStatusChange, clearVersionCache, codeDiffDiagnostics, collectAttachments, computeTestMetrics, copyMarkdownAssets, createAnchor, createPrCommentSummary, createReportGenerator, createTestRailProvider, createXrayProvider, deriveAudience, deriveChangeType, detectCI, detectPerformanceTrend, diffRuns, diffStoryReports, emptyLockfile, findGitDir, generateRunComparison, getDeploymentStatus, getEnvironmentDrift, gradeEvidence, hasSufficientHistory, hashCaseBody, isProviderName, isReviewableSource, isTestFile, joinNameAndExt, listScenarios, loadHistory, normalizeFormats, normalizeJestResults, normalizePlaywrightResults, normalizeVitestResults, parseLockfile, parseUnifiedDiff, projectBehaviours, publishConfluencePage, publishJiraIssue, readBranchName, readGitSha, readLockfile, readPackageVersion, recordDeployment, regenerateArtifacts, regenerateRun, relocateAnchor, renderApplyResult, renderCheck, renderCoverageMarkdown, renderCoverageText, renderGoal, renderPlan, renderTriage, rewriteAssetPaths, runsReset, runsStatus, saveHistory, scenariosCoveringPaths, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, serializeLockfile, signBody, startWatch, stripAnsi, toAgentText, toBehaviorManifest, toCaseBody, toReleaseManifest, toScenarioIndex, toTraceabilityMatrix, updateHistory, writeLockfile };

package/dist/index.d.ts

@@ -1655,6 +1655,20 @@ interface ScenarioIndex {
     summary: StoryReport["summary"];
     scenarios: ScenarioIndexItem[];
 }
+/**
+ * One scenario as this formatter emits it.
+ *
+ * This is an OUTPUT type: it describes what `toScenarioIndex` produces, which
+ * is why `hash` and `assertionState` are required here while
+ * `scenario-index-v1.json` marks both optional. The schema is deliberately the
+ * laxer of the two so artifacts written before either field existed still
+ * validate; every artifact written since carries them.
+ *
+ * The consequence, and it is intended: parsing an arbitrary v1 file and casting
+ * it to this type is not sound for those two fields. Validate against the
+ * schema and treat them as optional if you are reading files you did not just
+ * write.
+ */
 interface ScenarioIndexItem {
     id: string;
     title: string;
@@ -1681,6 +1695,12 @@ interface ScenarioIndexItem {
         message: string;
         stack?: string;
     };
+    /**
+     * Whether the scenario's claim was checked: `asserted`, `unasserted`, or
+     * `unobserved` where the adapter cannot count. A passing scenario that is
+     * `unasserted` ran and proved nothing.
+     */
+    assertionState: "asserted" | "unasserted" | "unobserved";
 }
 interface ScenarioIndexStep {
     id: string;
@@ -1691,6 +1711,11 @@ interface ScenarioIndexStep {
     durationMs: number;
     errorMessage?: string;
     docKinds: string[];
+    /**
+     * Assertions the framework observed. Absent means the adapter has no counter;
+     * `0` means it counted none. Never defaulted — the difference is the point.
+     */
+    assertions?: number;
 }
 interface ScenarioIndexFilters {
     statuses?: TestStatus$1[];
@@ -1812,6 +1837,82 @@ interface WatchHandle {
  */
 declare function startWatch(options: WatchOptions, deps?: WatchDeps): WatchHandle;
 
+interface AggregateDeps {
+    readFile: (filePath: string) => string;
+    listDir: (dir: string) => string[] | undefined;
+    logger: {
+        warn(msg: string): void;
+    };
+}
+interface AggregateResult {
+    run: TestRunResult;
+    /** How many per-file reports went into it. */
+    files: number;
+    /** Reports that could not be parsed. Named, never silently skipped. */
+    unreadable: string[];
+    /** Scenario ids claimed by more than one report. */
+    duplicateIds: string[];
+}
+/**
+ * Read every per-file report in `dir` and combine them into one run.
+ *
+ * Returns undefined when the directory holds no reports, so a caller can tell
+ * "nothing here yet" from "here is an empty run".
+ */
+declare function aggregateReports(args: {
+    dir: string;
+}, deps: AggregateDeps): AggregateResult | undefined;
+
+interface RunsLifecycleDeps {
+    readFile: (filePath: string) => string;
+    listDir: (dir: string) => string[] | undefined;
+    removeFile: (filePath: string) => void;
+    logger: {
+        warn(msg: string): void;
+    };
+}
+/** What one test file's report looks like from the outside. */
+interface AccumulatedFile {
+    sourceFile: string;
+    scenarios: number;
+    /** When this file's newest scenario last ran, or undefined if none say. */
+    lastRunAtMs?: number;
+    lastRunGitSha?: string;
+}
+interface RunsStatusReport {
+    /** Path of the reports directory, for the reader to go look. */
+    directory: string;
+    exists: boolean;
+    files: AccumulatedFile[];
+    totalScenarios: number;
+    /** Reports that could not be parsed. Named, never silently skipped. */
+    unreadable: string[];
+    /** Human-readable rendering, what the CLI prints. */
+    text: string;
+}
+/**
+ * What the report would be built from right now: every test file the state
+ * holds, how many scenarios each contributes, and how old those results are.
+ */
+declare function runsStatus(args: {
+    outputDir: string;
+    nowMs: number;
+}, deps: RunsLifecycleDeps): RunsStatusReport;
+interface RunsResetResult {
+    directory: string;
+    removed: number;
+    text: string;
+}
+/**
+ * Delete every per-file report. The next full test run writes them again.
+ *
+ * Removes only this directory's reports; anything rendered beside it in the
+ * output folder is the user's own output and is left alone.
+ */
+declare function runsReset(args: {
+    outputDir: string;
+}, deps: RunsLifecycleDeps): RunsResetResult;
+
 interface BehaviorDiffEntry {
     id: string;
     title: string;
@@ -2888,6 +2989,23 @@ interface GenerateDeps {
     logger: Logger;
     /** File writer function */
     writeFile: WriteFile;
+    /** Read a file. Throws when it is not there, like `fs.readFileSync`. */
+    readFile: (filePath: string) => string;
+    /** List a directory's entries, or undefined when it is not one. */
+    listDir: (dir: string) => string[] | undefined;
+    /** True when the path is present in the working tree. */
+    fileExists: (filePath: string) => boolean;
+    /** Delete a file. Absent paths are not an error. */
+    removeFile: (filePath: string) => Promise<void>;
+}
+/** Options for one `generate` call. */
+interface GenerateOptions {
+    /**
+     * Whether this run owns the reports of the files it covers and should update
+     * them. True for a test run. False when rendering an already-assembled run,
+     * such as the aggregate of a shard directory, which owns nothing.
+     */
+    persist?: boolean;
 }
 /** Result of generate function: Map of format to array of file paths */
 type GenerateResult = Map<OutputFormat, string[]>;
@@ -2913,7 +3031,24 @@ declare function normalizeFormats(formats: ReadonlyArray<FormatInput>): OutputFo
 declare class ReportGenerator {
     private options;
     private deps;
+    /**
+     * The run the last `generate()` actually rendered: this run folded into what
+     * previous runs accumulated. Callers that report on the output (the CLI's
+     * summary line) need to describe what was written, not just what was handed
+     * in. Undefined before the first generate.
+     */
+    private lastRenderedRun?;
+    /**
+     * What the execution formats rendered: this run after the same selection the
+     * documentation set gets. The CLI counts whichever set its output actually
+     * contains, so an excluded scenario is not reported as written.
+     */
+    private lastExecutedRun?;
     constructor(options?: FormatterOptions, deps?: Partial<GenerateDeps>);
+    /** The run the last `generate()` rendered, stored reports included. */
+    get renderedRun(): TestRunResult | undefined;
+    /** What the last `generate()` handed the execution formats. */
+    get executedRun(): TestRunResult | undefined;
     /**
      * Resolve options with defaults.
      */
@@ -2924,7 +3059,7 @@ declare class ReportGenerator {
      * @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(run: TestRunResult, options?: GenerateOptions): Promise<GenerateResult>;
     /**
      * Whether any output is colocated — the global mode, or any per-rule mode.
      * A colocated rule under a global aggregated mode still writes per-file
@@ -3387,4 +3522,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 AdapterDeps, AgentTextFormatter, type AnchorResolution, type AnchorState, type AstroAssetResult, AstroFormatter, type AstroFormatterOptions as AstroFormatterOpts, type AttachPolicy, type BehaviorDebuggerIssue, type BehaviorDiff, type BehaviorDiffEntry, type BehaviorManifest, BehaviorManifestJsonFormatter, type BehaviorManifestJsonOptions, type BehaviorSourceFile, type BehaviorTag, type BundleOptions, type BundleResult, type CaseBody, type CaseResult, type ChangeType, type ChangedFile, type ChangedFileReview, type CheckArgs, type CheckDeps, type CheckFailure, type CheckReport, type CheckStep, type CodeDiffAnnotation, type CodeDiffAnnotationInput, type CodeDiffEvidence, type CodeDiffInput, type CodeDiffScenarioRef, type CodeDiffSidecar, type CodeDiffSidecarAnnotation, type ColocatedStyle, type CompareFormat, type CompareFormatterOptions, type ConfluenceAuth, ConfluenceFormatter, type ConfluenceFormatterOptions as ConfluenceFormatterOpts, type CopyMarkdownAssetsOptions, type CoverageClass, type CoverageJson, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DEFAULT_LOCKFILE_PATH, type DeploymentEntry, type DeploymentLedger, type DeploymentStatus, type DiffAnchor, type DiffHunk, type DiffLine, type DiffRunsOptions, type EnvironmentDrift, type EvidenceStrength, type ExecutableStoriesConfig, type FetchFn, type FileChangeKind, type FileDiff, type FlakinessLevel, type Formatter, type FormatterOptions, type GenerateArgs, type GenerateCompareResult, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type GoalArgs, type GoalDeps, type GoalReport, type GoalRequirementResult, type HistoryEntry, type HistoryStore, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type JiraAuth, type JiraPublishMode, type ListScenariosArgs, type ListScenariosDeps, type LockEntry, type Lockfile, type Logger, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type NotificationSummary, type NotifyCondition, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, PROVIDER_NAMES, type PerformanceTrend, type ProviderName, type PublishConfluenceArgs, type PublishConfluenceDeps, type PublishConfluenceResult, type PublishJiraArgs, type PublishJiraDeps, type PublishJiraResult, type RatchetViolation, type RecordDeploymentArgs, type RecordDeploymentResult, type RecordResultsSummary, type ReleaseManifest, ReleaseManifestFormatter, type RemoteCase, ReportGenerator, type ResolvedFormatterOptions, type ResultAttachment, type ReviewAudience, type ReviewBand, type ReviewClaim, type ReviewContext, ReviewHtmlFormatter, type ReviewHtmlOptions, ReviewMarkdownFormatter, type ReviewMarkdownOptions, type ReviewResult, type ReviewSummary, RunDiffChangelogFormatter, type RunDiffChangelogOptions, RunDiffHtmlFormatter, type RunDiffHtmlOptions, RunDiffMarkdownFormatter, type RunDiffMarkdownOptions, type RunDiffResult, type RunDiffSummary, type ScenarioChangeFlags, type ScenarioChangeKind, type ScenarioDiff, type ScenarioIndex, type ScenarioIndexFilters, type ScenarioIndexItem, ScenarioIndexJsonFormatter, type ScenarioIndexJsonOptions, type ScenarioIndexStep, type ScenarioSnapshot, type SortTestCasesMode, type StabilityGrade, type StarlightBadge, StoryReportJsonFormatter, type StoryReportJsonOptions, type SyncAnalysis, type SyncApplyResult, type SyncEngineConfig, type SyncProvider, type SyncTargets, type TestHistory, type TestMetrics, type TestRailConfig, TraceabilityCsvFormatter, type TraceabilityMatrix, TraceabilityMatrixFormatter, type TraceabilityRequirement, type TriageArgs, type TriageDeps, type TriageItem, type TriageReport, type WatchDeps, type WatchHandle, type WatchOptions, type WebhookPayload, type WebhookSignerHmac, type WriteFile, type XrayConfig, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, analyzeSync, applySync, assembleCodeDiff, buildCheck, buildCoverageJson, buildGoal, buildProvider, buildReview, buildTriage, bundleAssets, calculateFlakiness, calculateStability, classifyStatusChange, clearVersionCache, codeDiffDiagnostics, collectAttachments, computeTestMetrics, copyMarkdownAssets, createAnchor, createPrCommentSummary, createReportGenerator, createTestRailProvider, createXrayProvider, deriveAudience, deriveChangeType, detectCI, detectPerformanceTrend, diffRuns, diffStoryReports, emptyLockfile, findGitDir, generateRunComparison, getDeploymentStatus, getEnvironmentDrift, gradeEvidence, hasSufficientHistory, hashCaseBody, isProviderName, isReviewableSource, isTestFile, joinNameAndExt, listScenarios, loadHistory, normalizeFormats, normalizeJestResults, normalizePlaywrightResults, normalizeVitestResults, parseLockfile, parseUnifiedDiff, projectBehaviours, publishConfluencePage, publishJiraIssue, readBranchName, readGitSha, readLockfile, readPackageVersion, recordDeployment, regenerateArtifacts, regenerateRun, relocateAnchor, renderApplyResult, renderCheck, renderCoverageMarkdown, renderCoverageText, renderGoal, renderPlan, renderTriage, rewriteAssetPaths, saveHistory, scenariosCoveringPaths, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, serializeLockfile, signBody, startWatch, stripAnsi, toAgentText, toBehaviorManifest, toCaseBody, toReleaseManifest, toScenarioIndex, toTraceabilityMatrix, updateHistory, writeLockfile };
+export { type AdapterDeps, AgentTextFormatter, type AggregateDeps, type AggregateResult, type AnchorResolution, type AnchorState, type AstroAssetResult, AstroFormatter, type AstroFormatterOptions as AstroFormatterOpts, type AttachPolicy, type BehaviorDebuggerIssue, type BehaviorDiff, type BehaviorDiffEntry, type BehaviorManifest, BehaviorManifestJsonFormatter, type BehaviorManifestJsonOptions, type BehaviorSourceFile, type BehaviorTag, type BundleOptions, type BundleResult, type CaseBody, type CaseResult, type ChangeType, type ChangedFile, type ChangedFileReview, type CheckArgs, type CheckDeps, type CheckFailure, type CheckReport, type CheckStep, type CodeDiffAnnotation, type CodeDiffAnnotationInput, type CodeDiffEvidence, type CodeDiffInput, type CodeDiffScenarioRef, type CodeDiffSidecar, type CodeDiffSidecarAnnotation, type ColocatedStyle, type CompareFormat, type CompareFormatterOptions, type ConfluenceAuth, ConfluenceFormatter, type ConfluenceFormatterOptions as ConfluenceFormatterOpts, type CopyMarkdownAssetsOptions, type CoverageClass, type CoverageJson, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DEFAULT_LOCKFILE_PATH, type DeploymentEntry, type DeploymentLedger, type DeploymentStatus, type DiffAnchor, type DiffHunk, type DiffLine, type DiffRunsOptions, type EnvironmentDrift, type EvidenceStrength, type ExecutableStoriesConfig, type FetchFn, type FileChangeKind, type FileDiff, type FlakinessLevel, type Formatter, type FormatterOptions, type GenerateArgs, type GenerateCompareResult, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type GoalArgs, type GoalDeps, type GoalReport, type GoalRequirementResult, type HistoryEntry, type HistoryStore, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type JiraAuth, type JiraPublishMode, type ListScenariosArgs, type ListScenariosDeps, type LockEntry, type Lockfile, type Logger, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type NotificationSummary, type NotifyCondition, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, PROVIDER_NAMES, type PerformanceTrend, type ProviderName, type PublishConfluenceArgs, type PublishConfluenceDeps, type PublishConfluenceResult, type PublishJiraArgs, type PublishJiraDeps, type PublishJiraResult, type RatchetViolation, type RecordDeploymentArgs, type RecordDeploymentResult, type RecordResultsSummary, type ReleaseManifest, ReleaseManifestFormatter, type RemoteCase, ReportGenerator, type ResolvedFormatterOptions, type ResultAttachment, type ReviewAudience, type ReviewBand, type ReviewClaim, type ReviewContext, ReviewHtmlFormatter, type ReviewHtmlOptions, ReviewMarkdownFormatter, type ReviewMarkdownOptions, type ReviewResult, type ReviewSummary, RunDiffChangelogFormatter, type RunDiffChangelogOptions, RunDiffHtmlFormatter, type RunDiffHtmlOptions, RunDiffMarkdownFormatter, type RunDiffMarkdownOptions, type RunDiffResult, type RunDiffSummary, type RunsResetResult, type RunsStatusReport, type ScenarioChangeFlags, type ScenarioChangeKind, type ScenarioDiff, type ScenarioIndex, type ScenarioIndexFilters, type ScenarioIndexItem, ScenarioIndexJsonFormatter, type ScenarioIndexJsonOptions, type ScenarioIndexStep, type ScenarioSnapshot, type SortTestCasesMode, type StabilityGrade, type StarlightBadge, StoryReportJsonFormatter, type StoryReportJsonOptions, type SyncAnalysis, type SyncApplyResult, type SyncEngineConfig, type SyncProvider, type SyncTargets, type TestHistory, type TestMetrics, type TestRailConfig, TraceabilityCsvFormatter, type TraceabilityMatrix, TraceabilityMatrixFormatter, type TraceabilityRequirement, type TriageArgs, type TriageDeps, type TriageItem, type TriageReport, type WatchDeps, type WatchHandle, type WatchOptions, type WebhookPayload, type WebhookSignerHmac, type WriteFile, type XrayConfig, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, aggregateReports, analyzeSync, applySync, assembleCodeDiff, buildCheck, buildCoverageJson, buildGoal, buildProvider, buildReview, buildTriage, bundleAssets, calculateFlakiness, calculateStability, classifyStatusChange, clearVersionCache, codeDiffDiagnostics, collectAttachments, computeTestMetrics, copyMarkdownAssets, createAnchor, createPrCommentSummary, createReportGenerator, createTestRailProvider, createXrayProvider, deriveAudience, deriveChangeType, detectCI, detectPerformanceTrend, diffRuns, diffStoryReports, emptyLockfile, findGitDir, generateRunComparison, getDeploymentStatus, getEnvironmentDrift, gradeEvidence, hasSufficientHistory, hashCaseBody, isProviderName, isReviewableSource, isTestFile, joinNameAndExt, listScenarios, loadHistory, normalizeFormats, normalizeJestResults, normalizePlaywrightResults, normalizeVitestResults, parseLockfile, parseUnifiedDiff, projectBehaviours, publishConfluencePage, publishJiraIssue, readBranchName, readGitSha, readLockfile, readPackageVersion, recordDeployment, regenerateArtifacts, regenerateRun, relocateAnchor, renderApplyResult, renderCheck, renderCoverageMarkdown, renderCoverageText, renderGoal, renderPlan, renderTriage, rewriteAssetPaths, runsReset, runsStatus, saveHistory, scenariosCoveringPaths, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, serializeLockfile, signBody, startWatch, stripAnsi, toAgentText, toBehaviorManifest, toCaseBody, toReleaseManifest, toScenarioIndex, toTraceabilityMatrix, updateHistory, writeLockfile };