@cappa/core 0.13.2 → 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.cjs +930 -6
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +402 -11
- package/dist/index.d.mts +402 -11
- package/dist/index.mjs +902 -7
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,8 +1,93 @@
|
|
|
1
|
-
import { ChangeRegion, InterpretResult, InterpretResult as InterpretResult$1 } from "@blazediff/interpret-native";
|
|
1
|
+
import { BoundingBox, ChangeRegion, InterpretResult, InterpretResult as InterpretResult$1 } from "@blazediff/interpret-native";
|
|
2
2
|
import "@blazediff/gmsd";
|
|
3
|
-
import { Browser, BrowserContext, Locator, Page } from "playwright-core";
|
|
3
|
+
import { Browser, BrowserContext, ConsoleMessage, Locator, Page } from "playwright-core";
|
|
4
4
|
import { Logger } from "@cappa/logger";
|
|
5
5
|
import "@blazediff/core-native";
|
|
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
|
|
67
|
+
//#region src/consoleEvents.d.ts
|
|
68
|
+
/**
|
|
69
|
+
* Minimum severity of browser console output to forward, ordered from most
|
|
70
|
+
* to least severe. Browser `console.warn` is reported by Playwright as
|
|
71
|
+
* `warning`; it maps to `"warn"` here.
|
|
72
|
+
*/
|
|
73
|
+
type ConsoleLogLevel = "error" | "warn" | "info" | "log" | "debug";
|
|
74
|
+
/**
|
|
75
|
+
* `true` forwards every console message at the logger's debug level (the
|
|
76
|
+
* historical behaviour), `false` forwards none, and a {@link ConsoleLogLevel}
|
|
77
|
+
* forwards messages at or above that severity at their matching logger level.
|
|
78
|
+
*/
|
|
79
|
+
type LogConsoleEvents = boolean | ConsoleLogLevel;
|
|
80
|
+
export declare const CONSOLE_LOG_LEVELS: readonly ConsoleLogLevel[];
|
|
81
|
+
type ConsoleEventLogger = Record<ConsoleLogLevel, (message: any, ...args: any[]) => void>;
|
|
82
|
+
/** Maps a Playwright `ConsoleMessage.type()` onto a {@link ConsoleLogLevel}. */
|
|
83
|
+
export declare const toConsoleLogLevel: (type: ReturnType<ConsoleMessage["type"]> | string) => ConsoleLogLevel;
|
|
84
|
+
/**
|
|
85
|
+
* Wires a page's `console` and `pageerror` events to `logger` according to
|
|
86
|
+
* `setting`. Uncaught page errors are always forwarded — at error level when
|
|
87
|
+
* a severity threshold is set, at debug level otherwise.
|
|
88
|
+
*/
|
|
89
|
+
export declare const attachConsoleLogging: (page: Pick<Page, "on">, setting: LogConsoleEvents | undefined, logger: ConsoleEventLogger) => void;
|
|
90
|
+
//#endregion
|
|
6
91
|
//#region src/compare/pixel.d.ts
|
|
7
92
|
interface CompareResult$1 {
|
|
8
93
|
numDiffPixels: number;
|
|
@@ -145,6 +230,14 @@ export declare class ScreenshotFileSystem {
|
|
|
145
230
|
* Write a file to the diff directory
|
|
146
231
|
*/
|
|
147
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>;
|
|
148
241
|
/**
|
|
149
242
|
* Get the path to a diff metadata sidecar file (`<name>.json`)
|
|
150
243
|
*/
|
|
@@ -469,7 +562,7 @@ declare class ScreenshotTool {
|
|
|
469
562
|
logger: ScreenshotLogger;
|
|
470
563
|
retries: number;
|
|
471
564
|
filesystem: ScreenshotFileSystem;
|
|
472
|
-
logConsoleEvents:
|
|
565
|
+
logConsoleEvents: LogConsoleEvents;
|
|
473
566
|
connectionTimeout: number;
|
|
474
567
|
private defaultUserAgent;
|
|
475
568
|
/** The real logger, kept so `setLogSink(null)` restores the same instance. */
|
|
@@ -488,7 +581,7 @@ declare class ScreenshotTool {
|
|
|
488
581
|
diff?: DiffOptions;
|
|
489
582
|
retries?: number;
|
|
490
583
|
concurrency?: number;
|
|
491
|
-
logConsoleEvents?:
|
|
584
|
+
logConsoleEvents?: LogConsoleEvents;
|
|
492
585
|
connectionTimeout?: number;
|
|
493
586
|
});
|
|
494
587
|
/**
|
|
@@ -813,12 +906,17 @@ type UserConfig = {
|
|
|
813
906
|
*/
|
|
814
907
|
concurrency?: number;
|
|
815
908
|
/**
|
|
816
|
-
*
|
|
909
|
+
* Which browser console events to log while executing capture tasks.
|
|
910
|
+
*
|
|
911
|
+
* - `true` (default): every console message, at the logger's debug level
|
|
912
|
+
* - `false`: none
|
|
913
|
+
* - `"error" | "warn" | "info" | "log" | "debug"`: only messages at or above
|
|
914
|
+
* that severity, logged at their matching level (so `"error"` surfaces
|
|
915
|
+
* browser errors without `--log-level` tweaks)
|
|
817
916
|
*
|
|
818
|
-
*
|
|
819
|
-
* console output when you do not need the additional details.
|
|
917
|
+
* Uncaught page errors are always logged.
|
|
820
918
|
*/
|
|
821
|
-
logConsoleEvents?:
|
|
919
|
+
logConsoleEvents?: LogConsoleEvents;
|
|
822
920
|
/**
|
|
823
921
|
* Timeout in milliseconds for network connections (e.g. fetching stories,
|
|
824
922
|
* navigating to pages). If a connection does not respond within this time,
|
|
@@ -930,6 +1028,24 @@ interface DiffMetadata {
|
|
|
930
1028
|
/** Structured interpretation, present only when `diff.interpret` is enabled. */
|
|
931
1029
|
interpretation?: InterpretResult$1;
|
|
932
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
|
+
}
|
|
933
1049
|
type ChangedScreenshot = {
|
|
934
1050
|
category: "changed";
|
|
935
1051
|
diffPath: string;
|
|
@@ -940,6 +1056,12 @@ type ChangedScreenshot = {
|
|
|
940
1056
|
* `diff/<name>.json` sidecar. Absent if the sidecar was not written.
|
|
941
1057
|
*/
|
|
942
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;
|
|
943
1065
|
};
|
|
944
1066
|
type PassedScreenshot = {
|
|
945
1067
|
category: "passed";
|
|
@@ -1525,7 +1647,7 @@ type LocalEngineOptions = {
|
|
|
1525
1647
|
diff?: DiffOptions;
|
|
1526
1648
|
retries?: number;
|
|
1527
1649
|
concurrency?: number;
|
|
1528
|
-
logConsoleEvents?:
|
|
1650
|
+
logConsoleEvents?: LogConsoleEvents;
|
|
1529
1651
|
fullPage?: boolean;
|
|
1530
1652
|
viewport?: Viewport;
|
|
1531
1653
|
connectionTimeout?: number;
|
|
@@ -1758,7 +1880,9 @@ export declare function getDeletedScreenshots(outputDir: string): Promise<string
|
|
|
1758
1880
|
*
|
|
1759
1881
|
* The capture manifest is folded in here so every consumer — the CLI, the
|
|
1760
1882
|
* server, the review UI — sees the same `taskId`, and so a screenshot captured
|
|
1761
|
-
* 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.
|
|
1762
1886
|
*/
|
|
1763
1887
|
export declare const collectScreenshots: (outputDir: string) => Promise<Screenshot[]>;
|
|
1764
1888
|
//#endregion
|
|
@@ -1879,5 +2003,272 @@ export declare class FsScreenshotStore implements ScreenshotStore {
|
|
|
1879
2003
|
writeMeta(key: string, meta: DiffMetadata): Promise<void>;
|
|
1880
2004
|
}
|
|
1881
2005
|
//#endregion
|
|
1882
|
-
|
|
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 };
|
|
1883
2274
|
//# sourceMappingURL=index.d.cts.map
|