Skip to content

Commit 659cb6a

Browse files
committed
feat(cli): --frame-check accepts a severity/seek/tol spec
The pipeline already carried FrameCheckOptions; only the flag was boolean, which meant a pipeline caller tuning severity or seek points would have them silently dropped — the two sides only agreed because today's caller happens to match the defaults. Bare --frame-check keeps the defaults; the value form mirrors --caption-zone's grammar, freezing the contract before a release pins it.
1 parent 67cdf0f commit 659cb6a

3 files changed

Lines changed: 76 additions & 22 deletions

File tree

‎packages/cli/src/commands/check.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1112,6 +1112,22 @@ describe("check pipeline", () => {
11121112
});
11131113
});
11141114

1115+
describe("frame-check flag grammar", () => {
1116+
it("keeps bare --frame-check on defaults and parses the value form", async () => {
1117+
const { parseFrameCheck } = await import("./check.js");
1118+
expect(parseFrameCheck(undefined)).toBeUndefined();
1119+
expect(parseFrameCheck(true)).toEqual({});
1120+
expect(parseFrameCheck("")).toEqual({});
1121+
expect(parseFrameCheck("severity=error;seek=.25,.75;tol=4")).toEqual({
1122+
severity: "error",
1123+
seek: [0.25, 0.75],
1124+
tol: 4,
1125+
});
1126+
expect(() => parseFrameCheck("bogus=1")).toThrow("Invalid --frame-check");
1127+
expect(() => parseFrameCheck("tol=-2")).toThrow("Invalid --frame-check");
1128+
});
1129+
});
1130+
11151131
describe("contrast persistence", () => {
11161132
it("demotes a single-sample contrast failure to warning but gates held failures", async () => {
11171133
const driver = fakeDriver({

‎packages/cli/src/commands/check.ts‎

Lines changed: 47 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ import {
1515
type CheckReport,
1616
type CheckSection,
1717
} from "../utils/checkPipeline.js";
18-
import type { CaptionZoneOptions } from "../utils/checkTypes.js";
18+
import type { CaptionZoneOptions, FrameCheckOptions } from "../utils/checkTypes.js";
1919

2020
export const examples: Example[] = [
2121
["Run the full verification gate", "hyperframes check"],
@@ -109,10 +109,9 @@ export function createCheckCommand(
109109
'Caption band "x0=0;y0=.82;x1=1;y1=1[;severity=warning|error][;seek=.5,1]" (fractions 0-1; defaults: warning, seek=1)',
110110
},
111111
"frame-check": {
112-
type: "boolean",
112+
type: "string",
113113
description:
114-
"Use as --frame-check (boolean/no value; tol=2px, severity=warning, seek=.5; breach floor=max(120px, 6% of shorter canvas edge))",
115-
default: false,
114+
'Bare --frame-check uses defaults (tol=2px, severity=warning, seek=.5; breach floor=max(120px, 6% of shorter canvas edge)); or pass "severity=error;seek=.25,.75;tol=4" to tune',
116115
},
117116
},
118117
async run({ args }) {
@@ -161,12 +160,55 @@ function parseCheckOptions(args: Record<string, unknown>): CheckOptions {
161160
strict: args.strict === true,
162161
snapshots: args.snapshots === true,
163162
captionZone: parseCaptionZone(args["caption-zone"]),
164-
frameCheck: args["frame-check"] === true ? {} : undefined,
163+
frameCheck: parseFrameCheck(args["frame-check"]),
165164
};
166165
}
167166

168167
const CAPTION_ZONE_FIELDS = new Set(["x0", "y0", "x1", "y1", "severity", "seek"]);
169168

169+
const FRAME_CHECK_FIELDS = new Set(["severity", "seek", "tol"]);
170+
171+
// Mirrors --caption-zone's spec grammar so the EF bridge's severity/seek/tol
172+
// options survive the migration instead of being silently dropped by a
173+
// boolean flag (bare --frame-check keeps today's defaults).
174+
export function parseFrameCheck(value: unknown): FrameCheckOptions | undefined {
175+
if (value === undefined || value === null || value === false) return undefined;
176+
if (value === true || value === "") return {};
177+
if (typeof value !== "string") throw frameCheckError();
178+
const fields = parseFrameCheckFields(value);
179+
const severity = captionSeverity(fields.get("severity"));
180+
const seek = captionSeeks(fields.get("seek"));
181+
const tol = parseFrameCheckTolerance(fields.get("tol"));
182+
return {
183+
...(severity ? { severity } : {}),
184+
...(seek ? { seek } : {}),
185+
...(tol !== undefined ? { tol } : {}),
186+
};
187+
}
188+
189+
function parseFrameCheckFields(value: string): Map<string, string> {
190+
const fields = new Map<string, string>();
191+
for (const part of value.split(";")) {
192+
const { key, entry } = parseCaptionField(part);
193+
if (!FRAME_CHECK_FIELDS.has(key) || fields.has(key)) throw frameCheckError();
194+
fields.set(key, entry);
195+
}
196+
return fields;
197+
}
198+
199+
function parseFrameCheckTolerance(raw: string | undefined): number | undefined {
200+
if (raw === undefined) return undefined;
201+
const tol = Number.parseFloat(raw);
202+
if (!Number.isFinite(tol) || tol < 0) throw frameCheckError();
203+
return tol;
204+
}
205+
206+
function frameCheckError(): Error {
207+
return new Error(
208+
'Invalid --frame-check: use bare --frame-check or "severity=warning|error;seek=.25,.75;tol=4" (all fields optional)',
209+
);
210+
}
211+
170212
function parseCaptionZone(value: unknown): CaptionZoneOptions | undefined {
171213
if (value === undefined || value === null) return undefined;
172214
const fields = parseCaptionFields(captionZoneString(value));

‎packages/cli/src/utils/checkBrowser.test.ts‎

Lines changed: 13 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -70,21 +70,25 @@ function installSessionMock(page: ReturnType<typeof fakePage>): void {
7070
);
7171
}
7272

73+
function mountCanvasFixture(inner = ""): void {
74+
document.body.innerHTML = `
75+
<div data-composition-id="main" data-duration="10" data-width="640" data-height="360">${inner}</div>
76+
`;
77+
Object.defineProperty(window, "innerWidth", { configurable: true, value: 640 });
78+
Object.defineProperty(window, "innerHeight", { configurable: true, value: 360 });
79+
}
80+
7381
it("carries raw browser geometry through the page driver and pipeline", async () => {
7482
vi.spyOn(Date, "now")
7583
.mockReturnValueOnce(100)
7684
.mockReturnValueOnce(160)
7785
.mockReturnValueOnce(200)
7886
.mockReturnValueOnce(240);
79-
document.body.innerHTML = `
80-
<div data-composition-id="main" data-duration="10" data-width="640" data-height="360">
87+
mountCanvasFixture(`
8188
<section data-composition-file="scenes/hero.html">
8289
<img id="hero-image" data-layout-name="hero" src="data:image/png;base64,AA==" />
8390
</section>
84-
</div>
85-
`;
86-
Object.defineProperty(window, "innerWidth", { configurable: true, value: 640 });
87-
Object.defineProperty(window, "innerHeight", { configurable: true, value: 360 });
91+
`);
8892
installRects();
8993
const page = fakePage();
9094
installSessionMock(page);
@@ -120,13 +124,9 @@ it("round-trips the browser script's raw contrast candidates back into finish",
120124
// candidate (width/height) makes every sample rect NaN and the audit
121125
// silently reports zero checked elements as green.
122126
vi.spyOn(Date, "now").mockReturnValue(100);
123-
document.body.innerHTML = `
124-
<div data-composition-id="main" data-duration="10" data-width="640" data-height="360">
127+
mountCanvasFixture(`
125128
<div id="headline">Readable copy</div>
126-
</div>
127-
`;
128-
Object.defineProperty(window, "innerWidth", { configurable: true, value: 640 });
129-
Object.defineProperty(window, "innerHeight", { configurable: true, value: 360 });
129+
`);
130130
const root = document.querySelector("[data-composition-id]");
131131
const headline = document.querySelector("#headline");
132132
if (!root || !headline) throw new Error("Contrast fixture failed to mount");
@@ -215,11 +215,7 @@ it("round-trips the browser script's raw contrast candidates back into finish",
215215

216216
it("carries validate's clip-duration audit into the runtime findings", async () => {
217217
vi.spyOn(Date, "now").mockReturnValue(100);
218-
document.body.innerHTML = `
219-
<div data-composition-id="main" data-duration="10" data-width="640" data-height="360"></div>
220-
`;
221-
Object.defineProperty(window, "innerWidth", { configurable: true, value: 640 });
222-
Object.defineProperty(window, "innerHeight", { configurable: true, value: 360 });
218+
mountCanvasFixture();
223219
const validateModule = await import("../commands/validate.js");
224220
vi.mocked(validateModule.auditClipDurations).mockResolvedValue([
225221
{

0 commit comments

Comments
 (0)