@cappa/core 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,8 +1,69 @@
1
1
  import "@blazediff/gmsd";
2
2
  import { Logger } from "@cappa/logger";
3
3
  import "@blazediff/core-native";
4
- import { ChangeRegion, InterpretResult, InterpretResult as InterpretResult$1 } from "@blazediff/interpret-native";
4
+ import { BoundingBox, ChangeRegion, InterpretResult, InterpretResult as InterpretResult$1 } from "@blazediff/interpret-native";
5
5
  import { Browser, BrowserContext, ConsoleMessage, Locator, Page } from "playwright-core";
6
+ //#region src/agent/verdict.d.ts
7
+ /**
8
+ * What a reviewer — heuristic or agent — believes a changed screenshot is.
9
+ *
10
+ * `ambiguous` is only ever produced by the heuristic: it is the signal that
11
+ * the change has to be looked at, and an agent's verdict must resolve it into
12
+ * one of the other three.
13
+ */
14
+ export declare const VERDICT_LABELS: readonly ["regression-likely", "intentional-likely", "noise-likely", "ambiguous"];
15
+ type VerdictLabel = (typeof VERDICT_LABELS)[number];
16
+ /** The labels a judge may hand back — everything but `ambiguous`. */
17
+ export declare const JUDGED_LABELS: readonly ["regression-likely", "intentional-likely", "noise-likely"];
18
+ type JudgedLabel = (typeof JUDGED_LABELS)[number];
19
+ /** What to do next with a screenshot carrying a label. */
20
+ type VerdictAction = "investigate" | "approve-if-intended" | "mask-or-approve";
21
+ export declare const ACTION_BY_LABEL: Record<VerdictLabel, VerdictAction>;
22
+ type Verdict = {
23
+ label: VerdictLabel;
24
+ /** One line, e.g. `2 regions: 1 addition, 1 color-change @ top-left (1.20%, medium)`. */
25
+ headline: string;
26
+ rationale: string[];
27
+ action: VerdictAction;
28
+ };
29
+ export declare const isVerdictLabel: (value: unknown) => value is VerdictLabel;
30
+ export declare const isJudgedLabel: (value: unknown) => value is JudgedLabel;
31
+ /**
32
+ * Change types are normalised to kebab-case before they are compared.
33
+ *
34
+ * `@blazediff/interpret-native` reports `color-change` today but earlier
35
+ * releases reported `ColorChange`; normalising keeps the heuristic working
36
+ * across a diff-engine upgrade instead of silently degrading every screenshot
37
+ * to `ambiguous`.
38
+ */
39
+ export declare const normalizeChangeType: (changeType: string) => string;
40
+ /** Below this share of the image, a low-severity change is not perceptible. */
41
+ export declare const SUB_PERCEPTUAL_PERCENT = 0.01;
42
+ type VerdictInput = {
43
+ /** Percentage of differing pixels (0-100), from the pixel diff. */
44
+ percentDifference?: number;
45
+ numDiffPixels?: number;
46
+ interpretation?: InterpretResult$1;
47
+ /** Expected and actual have different dimensions. */
48
+ differentSizes?: boolean;
49
+ };
50
+ /**
51
+ * A one-line description of a change, shaped so that the same kind of change
52
+ * on different screenshots produces the same headline — which is what lets an
53
+ * agent spot one shared cause (a footer timestamp, a theme toggle) across
54
+ * dozens of screenshots without opening any of them.
55
+ */
56
+ export declare const buildHeadline: (input: VerdictInput) => string;
57
+ /**
58
+ * Classify a changed screenshot from its diff interpretation alone.
59
+ *
60
+ * Deliberately conservative: only the cases the signals settle are labelled,
61
+ * and everything else is `ambiguous` so that it reaches a judge who can look
62
+ * at the pixels. A wrong `noise-likely` hides a regression; a wrong
63
+ * `ambiguous` costs one look.
64
+ */
65
+ export declare const deriveVerdict: (input: VerdictInput) => Verdict;
66
+ //#endregion
6
67
  //#region src/consoleEvents.d.ts
7
68
  /**
8
69
  * Minimum severity of browser console output to forward, ordered from most
@@ -169,6 +230,14 @@ export declare class ScreenshotFileSystem {
169
230
  * Write a file to the diff directory
170
231
  */
171
232
  writeDiffFile(filename: string, data: Buffer): Promise<void>;
233
+ /**
234
+ * Remove a screenshot's diff image and metadata sidecar, if any.
235
+ *
236
+ * A run that does not clear `diff/` — a filtered or single-screenshot
237
+ * re-capture — would otherwise leave the previous run's diff behind for a
238
+ * screenshot that now passes, and a screenshot with a diff is `changed`.
239
+ */
240
+ removeDiffFiles(filename: string): Promise<void>;
172
241
  /**
173
242
  * Get the path to a diff metadata sidecar file (`<name>.json`)
174
243
  */
@@ -959,6 +1028,24 @@ interface DiffMetadata {
959
1028
  /** Structured interpretation, present only when `diff.interpret` is enabled. */
960
1029
  interpretation?: InterpretResult$1;
961
1030
  }
1031
+ /**
1032
+ * The verdict `cappa agent check` reached for a changed screenshot, as the
1033
+ * review UI shows it.
1034
+ */
1035
+ interface AgentReview {
1036
+ label: VerdictLabel;
1037
+ headline: string;
1038
+ rationale: string[];
1039
+ action: VerdictAction;
1040
+ /** `heuristic` from the diff signals; `agent` from a judge's verdict. */
1041
+ source: "heuristic" | "agent";
1042
+ /** 0-1, when the judge gave one. */
1043
+ confidence?: number;
1044
+ /** A judgment was requested and no verdict had been written yet. */
1045
+ pending: boolean;
1046
+ /** When the check that produced this ran (ISO 8601). */
1047
+ reviewedAt: string;
1048
+ }
962
1049
  type ChangedScreenshot = {
963
1050
  category: "changed";
964
1051
  diffPath: string;
@@ -969,6 +1056,12 @@ type ChangedScreenshot = {
969
1056
  * `diff/<name>.json` sidecar. Absent if the sidecar was not written.
970
1057
  */
971
1058
  diffMeta?: DiffMetadata;
1059
+ /**
1060
+ * The last `cappa agent check` verdict. Absent when no check has run, or
1061
+ * when either image changed since — a verdict about other pixels is not one
1062
+ * worth showing.
1063
+ */
1064
+ review?: AgentReview;
972
1065
  };
973
1066
  type PassedScreenshot = {
974
1067
  category: "passed";
@@ -1787,7 +1880,9 @@ export declare function getDeletedScreenshots(outputDir: string): Promise<string
1787
1880
  *
1788
1881
  * The capture manifest is folded in here so every consumer — the CLI, the
1789
1882
  * server, the review UI — sees the same `taskId`, and so a screenshot captured
1790
- * before manifests existed simply has none rather than a wrong one.
1883
+ * before manifests existed simply has none rather than a wrong one. The last
1884
+ * `cappa agent check` verdict is folded in the same way, as `review`, while it
1885
+ * still describes the images on disk.
1791
1886
  */
1792
1887
  export declare const collectScreenshots: (outputDir: string) => Promise<Screenshot[]>;
1793
1888
  //#endregion
@@ -1908,5 +2003,272 @@ export declare class FsScreenshotStore implements ScreenshotStore {
1908
2003
  writeMeta(key: string, meta: DiffMetadata): Promise<void>;
1909
2004
  }
1910
2005
  //#endregion
1911
- export { type ApproveResult, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type ConsoleLogLevel, type CreateFileWatcher, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffMetadata, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type EmittableWatchEvent, type FailedScreenshot, type FileWatcher, type InterpretResult, type ListTargetsOptions, type LocalEngineOptions, type LogConsoleEvents, type NewScreenshot, type PassedScreenshot, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type RunDetail, type RunEvent, type RunEventListener, type RunEventType, type RunLogLevel, type RunState, type RunStoreOptions, type RunSummary, type RunTrigger, type RunnablePlugin, type Screenshot, type ScreenshotBucket, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, type ScreenshotCaptureSink, type ScreenshotOptions, type ScreenshotOrigin, type ScreenshotQuery, type ScreenshotSettings, type ScreenshotStore, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type SerializedError, type StartRunRequest, type StartWatchRequest, type SubscribeOptions, type Target, type TaskFailure, type TaskRecord, type TaskStatus, type UserConfig, type Viewport, type WarmBrowserOptions, type WatchChange, type WatchEvent, type WatchEventType, type WatchScope, type WatchSessionOptions, type WatchStatus };
2006
+ //#region src/agent/paths.d.ts
2007
+ /**
2008
+ * Where agent review keeps its state, inside `outputDir`.
2009
+ *
2010
+ * Its own module so screenshot collection can read the report without
2011
+ * importing the review pipeline, which itself collects screenshots.
2012
+ */
2013
+ export declare const AGENT_DIRNAME = ".cappa-agent";
2014
+ /** Bumped only if `request.json` or `report.json` change incompatibly. */
2015
+ export declare const AGENT_REPORT_VERSION = 1;
2016
+ export declare const agentDir: (outputDir: string) => string;
2017
+ export declare const agentReportPath: (outputDir: string) => string;
2018
+ //#endregion
2019
+ //#region src/agent/review.d.ts
2020
+ /**
2021
+ * Which changed screenshots get a judgment request.
2022
+ *
2023
+ * - `ambiguous`: only those the heuristic could not label (default)
2024
+ * - `all`: every changed screenshot, for a full second opinion
2025
+ * - `none`: heuristic labels only, no new requests
2026
+ *
2027
+ * Judgments that already exist are kept and applied in every mode.
2028
+ */
2029
+ type JudgeMode = "ambiguous" | "all" | "none";
2030
+ export declare const JUDGE_MODES: readonly JudgeMode[];
2031
+ type AgentRegion = {
2032
+ /** 1-based, matching the numbers in `locator.png` and rows in `regions.png`. */
2033
+ index: number;
2034
+ bbox: {
2035
+ x: number;
2036
+ y: number;
2037
+ width: number;
2038
+ height: number;
2039
+ };
2040
+ pixelCount: number;
2041
+ percentage: number;
2042
+ position: string;
2043
+ shape: string;
2044
+ changeType: string;
2045
+ confidence: number;
2046
+ };
2047
+ type AppliedVerdict = Verdict & {
2048
+ /** Whether the label came from the heuristic or from a judge. */
2049
+ source: "heuristic" | "agent";
2050
+ confidence?: number;
2051
+ };
2052
+ type JudgmentPaths = {
2053
+ dir: string;
2054
+ request: string;
2055
+ verdict: string;
2056
+ locator?: string;
2057
+ regions?: string;
2058
+ overview?: string;
2059
+ };
2060
+ type AgentReportEntry = {
2061
+ name: string;
2062
+ category: "changed" | "new" | "deleted";
2063
+ taskId?: string;
2064
+ plugin?: string;
2065
+ /** Absolute paths to the screenshot files. */
2066
+ paths: {
2067
+ expected?: string;
2068
+ actual?: string;
2069
+ diff?: string;
2070
+ };
2071
+ percentDifference?: number;
2072
+ numDiffPixels?: number;
2073
+ dimensions?: {
2074
+ expected: {
2075
+ width: number;
2076
+ height: number;
2077
+ };
2078
+ actual: {
2079
+ width: number;
2080
+ height: number;
2081
+ };
2082
+ };
2083
+ severity?: string;
2084
+ summary?: string;
2085
+ /** Largest first. */
2086
+ regions?: AgentRegion[];
2087
+ heuristic?: Verdict;
2088
+ /** The judge's verdict when there is a current one, else the heuristic's. */
2089
+ verdict?: AppliedVerdict;
2090
+ /** A judgment was requested and no valid verdict has been written yet. */
2091
+ pending: boolean;
2092
+ judgment?: JudgmentPaths;
2093
+ /** Why a `verdict.json` that exists was ignored. */
2094
+ verdictError?: string;
2095
+ };
2096
+ type AgentReport = {
2097
+ version: number;
2098
+ createdAt: string;
2099
+ outputDir: string;
2100
+ reportPath: string;
2101
+ judge: JudgeMode;
2102
+ totals: {
2103
+ total: number;
2104
+ passed: number;
2105
+ changed: number;
2106
+ new: number;
2107
+ deleted: number;
2108
+ pendingJudgments: number;
2109
+ };
2110
+ /** Every non-passing screenshot, changed ones first. */
2111
+ entries: AgentReportEntry[];
2112
+ };
2113
+ /**
2114
+ * The directory holding a screenshot's judgment.
2115
+ *
2116
+ * Screenshot names are relative paths (`example/button/primary`), so they map
2117
+ * onto nested directories directly; anything that would resolve outside the
2118
+ * judgments root is refused rather than written.
2119
+ */
2120
+ export declare const judgmentDir: (outputDir: string, name: string) => string;
2121
+ /** Ties a judgment to the exact pair of images it was made about. */
2122
+ export declare const fingerprintImages: (expectedPath: string, actualPath: string) => Promise<string>;
2123
+ type ParsedAgentVerdict = {
2124
+ ok: true;
2125
+ label: JudgedLabel;
2126
+ headline: string;
2127
+ rationale: string[];
2128
+ confidence?: number;
2129
+ } | {
2130
+ ok: false;
2131
+ error: string;
2132
+ };
2133
+ /**
2134
+ * Read a judge's verdict, accepting both the nested shape blazediff uses
2135
+ * (`{ verdict: { label, headline, rationale }, confidence }`) and a flat one
2136
+ * (`{ label, headline, rationale, confidence }`) — a judge that writes either
2137
+ * should not have its work thrown away over nesting.
2138
+ */
2139
+ export declare const parseAgentVerdict: (raw: unknown) => ParsedAgentVerdict;
2140
+ type RunAgentCheckOptions = {
2141
+ outputDir: string;
2142
+ /** The project's diff config — its threshold is reused for interpretation. */
2143
+ diff?: DiffOptions;
2144
+ judge?: JudgeMode;
2145
+ /** Regions rendered into `regions.png` per screenshot. Default 8. */
2146
+ maxTileRegions?: number;
2147
+ /** Screenshots analysed in parallel. Default 4. */
2148
+ concurrency?: number;
2149
+ now?: () => Date;
2150
+ };
2151
+ /**
2152
+ * Remove a screenshot's judgment — after it was approved, or because it is no
2153
+ * longer changed. Only the judgment's own files go: a directory can also be
2154
+ * the parent of another screenshot's judgment (`button` and `button/primary`).
2155
+ */
2156
+ export declare const clearJudgment: (outputDir: string, name: string) => Promise<void>;
2157
+ /**
2158
+ * Analyse every non-passing screenshot, write judgment requests for the ones
2159
+ * that need a judge, apply any verdicts already written, and persist the
2160
+ * full report to `<outputDir>/.cappa-agent/report.json`.
2161
+ */
2162
+ export declare const runAgentCheck: (options: RunAgentCheckOptions) => Promise<AgentReport>;
2163
+ /** Read the report the last {@link runAgentCheck} wrote, if any. */
2164
+ export declare const readAgentReport: (outputDir: string) => Promise<AgentReport | undefined>;
2165
+ type SlimAgentReport = {
2166
+ reportPath: string;
2167
+ total: number;
2168
+ passed: number;
2169
+ changed: number;
2170
+ new: number;
2171
+ deleted: number;
2172
+ pendingJudgments: number;
2173
+ results: Array<{
2174
+ name: string;
2175
+ category: AgentReportEntry["category"];
2176
+ verdict?: Pick<AppliedVerdict, "label" | "headline" | "action" | "source">;
2177
+ pending?: true;
2178
+ /** Judgment directory, present while a verdict is pending. */
2179
+ judgment?: string;
2180
+ verdictError?: string;
2181
+ }>;
2182
+ };
2183
+ /**
2184
+ * The report as an agent should first see it: one line of state per
2185
+ * screenshot, with the detail left in `report.json` and the judgment
2186
+ * requests for when it is actually needed.
2187
+ */
2188
+ export declare const toSlimAgentReport: (report: AgentReport) => SlimAgentReport;
2189
+ type AgentVerdictInput = {
2190
+ label: JudgedLabel;
2191
+ headline: string;
2192
+ rationale?: string[];
2193
+ confidence?: number;
2194
+ };
2195
+ /**
2196
+ * Record a judge's verdict for a screenshot with a pending request — the
2197
+ * validated alternative to hand-writing `verdict.json`.
2198
+ */
2199
+ export declare const writeAgentVerdict: (outputDir: string, name: string, input: AgentVerdictInput) => Promise<string>;
2200
+ //#endregion
2201
+ //#region src/agent/tiles.d.ts
2202
+ /**
2203
+ * Evidence images for a judge, sized for a model's context window rather than
2204
+ * for a human's screen.
2205
+ *
2206
+ * A full-page screenshot is easily 1920x8000 — expensive to read and mostly
2207
+ * unchanged. A judge needs two things instead: where the changes are
2208
+ * (`locator.png`, a small outlined thumbnail) and what each one looks like
2209
+ * before and after (`regions.png`, tight crops side by side). Together they
2210
+ * are typically one to two orders of magnitude smaller than the full images.
2211
+ */
2212
+ type TileOptions = {
2213
+ expectedPath: string;
2214
+ actualPath: string;
2215
+ /** Diff image to outline the regions on; falls back to the actual image. */
2216
+ diffPath?: string;
2217
+ /** Regions, largest first — row order in `regions.png` follows this. */
2218
+ regions: readonly BoundingBox[];
2219
+ outDir: string;
2220
+ /** Regions rendered into `regions.png`. Default 8. */
2221
+ maxRegions?: number;
2222
+ /**
2223
+ * Minimum context kept around each region, in pixels; grows with the
2224
+ * region's size. Default 24.
2225
+ */
2226
+ padding?: number;
2227
+ /** Largest width a single crop is rendered at. Default 640. */
2228
+ maxCropWidth?: number;
2229
+ };
2230
+ type TileResult = {
2231
+ /** Absolute path, or undefined when nothing could be drawn. */
2232
+ locator?: string;
2233
+ /** Absolute path, or undefined when there were no regions. */
2234
+ regions?: string;
2235
+ /** How many regions `regions.png` holds (≤ `maxRegions`). */
2236
+ renderedRegions: number;
2237
+ };
2238
+ export declare const padAndClamp: (bbox: BoundingBox, padding: number | {
2239
+ x: number;
2240
+ y: number;
2241
+ }, width: number, height: number) => BoundingBox;
2242
+ /**
2243
+ * Context kept around a region: proportional to its size, within bounds.
2244
+ *
2245
+ * A fixed margin is too tight for small regions — a changed letter cropped
2246
+ * with 24px around it says nothing about whether a button label got
2247
+ * truncated — and wasteful for large ones.
2248
+ */
2249
+ export declare const contextPadding: (bbox: BoundingBox, minimum: number) => {
2250
+ x: number;
2251
+ y: number;
2252
+ };
2253
+ /**
2254
+ * Write `locator.png` and `regions.png` into `outDir`.
2255
+ *
2256
+ * Expected and actual must have the same dimensions — region boxes are only
2257
+ * meaningful when both images share a coordinate space. Use
2258
+ * {@link renderOverview} when they do not.
2259
+ */
2260
+ export declare const renderJudgmentTiles: (options: TileOptions) => Promise<TileResult>;
2261
+ /**
2262
+ * Write `overview.png`: expected and actual, scaled down side by side.
2263
+ *
2264
+ * For screenshots whose dimensions changed, where no region can be located,
2265
+ * this is what the judge looks at instead of two full-size images.
2266
+ */
2267
+ export declare const renderOverview: (options: {
2268
+ expectedPath: string;
2269
+ actualPath: string;
2270
+ outDir: string;
2271
+ }) => Promise<string>;
2272
+ //#endregion
2273
+ export { type AgentRegion, type AgentReport, type AgentReportEntry, type AgentReview, type AgentVerdictInput, type AppliedVerdict, type ApproveResult, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type ConsoleLogLevel, type CreateFileWatcher, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffMetadata, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type EmittableWatchEvent, type FailedScreenshot, type FileWatcher, type InterpretResult, type JudgeMode, type JudgedLabel, type JudgmentPaths, type ListTargetsOptions, type LocalEngineOptions, type LogConsoleEvents, type NewScreenshot, type ParsedAgentVerdict, type PassedScreenshot, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type RunAgentCheckOptions, type RunDetail, type RunEvent, type RunEventListener, type RunEventType, type RunLogLevel, type RunState, type RunStoreOptions, type RunSummary, type RunTrigger, type RunnablePlugin, type Screenshot, type ScreenshotBucket, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, type ScreenshotCaptureSink, type ScreenshotOptions, type ScreenshotOrigin, type ScreenshotQuery, type ScreenshotSettings, type ScreenshotStore, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type SerializedError, type SlimAgentReport, type StartRunRequest, type StartWatchRequest, type SubscribeOptions, type Target, type TaskFailure, type TaskRecord, type TaskStatus, type TileOptions, type TileResult, type UserConfig, type Verdict, type VerdictAction, type VerdictInput, type VerdictLabel, type Viewport, type WarmBrowserOptions, type WatchChange, type WatchEvent, type WatchEventType, type WatchScope, type WatchSessionOptions, type WatchStatus };
1912
2274
  //# sourceMappingURL=index.d.mts.map