Skip to content

Commit 70cc4f5

Browse files
authored
fix(cli): stop bare --frame-check from swallowing the next flag (#2966)
citty parses string options greedily, so a bare --frame-check consumed the following flag as its value (--caption-zone silently dropped, --json disabled) and failed with an error blaming --caption-zone. Normalize rawArgs at the check command boundary (bare --frame-check followed by a flag or at end becomes --frame-check=), attribute frame-check spec errors to --frame-check, and detect dash-prefixed values with corrective guidance. Fixes #2965
1 parent 127eb19 commit 70cc4f5

2 files changed

Lines changed: 194 additions & 97 deletions

File tree

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

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -359,6 +359,66 @@ it("parses the caption-zone grammar and enables the frame gate", async () => {
359359
);
360360
});
361361

362+
it("preserves caption-zone after bare --frame-check", async () => {
363+
const { report } = await runScenario(fakeDriver());
364+
const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
365+
vi.spyOn(console, "log").mockImplementation(() => undefined);
366+
const command = createCheckCommand({
367+
resolveProject: () => PROJECT,
368+
runPipeline,
369+
withMeta: (value) => value,
370+
});
371+
372+
await runCommand(command, {
373+
rawArgs: [
374+
"--frame-check",
375+
"--caption-zone",
376+
"x0=0;y0=.82;x1=1;y1=1;severity=error;seek=.25,1",
377+
"--json",
378+
],
379+
});
380+
381+
expect(runPipeline).toHaveBeenCalledWith(
382+
PROJECT,
383+
expect.objectContaining({
384+
captionZone: {
385+
x0: 0,
386+
y0: 0.82,
387+
x1: 1,
388+
y1: 1,
389+
severity: "error",
390+
seek: [0.25, 1],
391+
},
392+
frameCheck: {},
393+
}),
394+
);
395+
});
396+
397+
it("preserves --json after bare --frame-check", async () => {
398+
const { report } = await runScenario(fakeDriver());
399+
const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
400+
const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
401+
const command = createCheckCommand({
402+
resolveProject: () => PROJECT,
403+
runPipeline,
404+
withMeta: (value) => value,
405+
});
406+
407+
await runCommand(command, {
408+
rawArgs: ["--snapshots", "--samples", "15", "--frame-check", "--json"],
409+
});
410+
411+
expect(runPipeline).toHaveBeenCalledWith(
412+
PROJECT,
413+
expect.objectContaining({
414+
samples: 15,
415+
snapshots: true,
416+
frameCheck: {},
417+
}),
418+
);
419+
expect(log).toHaveBeenCalledWith(expect.stringContaining('"ok"'));
420+
});
421+
362422
it("threads --no-proxy into the browser check options", async () => {
363423
const { report } = await runScenario(fakeDriver());
364424
const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
@@ -1166,6 +1226,15 @@ describe("frame-check flag grammar", () => {
11661226
expect(() => parseFrameCheck("tol=4px")).toThrow("Invalid --frame-check");
11671227
expect(() => parseFrameCheck("tol=2garbage")).toThrow("Invalid --frame-check");
11681228
});
1229+
1230+
it("attributes swallowed option values to --frame-check", async () => {
1231+
const { parseFrameCheck } = await import("./check.js");
1232+
1233+
expect(() => parseFrameCheck("--json")).toThrow(
1234+
'Invalid --frame-check: value "--json" appears to have swallowed the next option; use --frame-check= or move --frame-check to the end',
1235+
);
1236+
expect(() => parseFrameCheck("severity")).toThrow("Invalid --frame-check");
1237+
});
11691238
});
11701239

11711240
describe("layout flag grammar", () => {

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

Lines changed: 125 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
import { defineCommand } from "citty";
1+
import { defineCommand, parseArgs } from "citty";
2+
import type { ArgsDef } from "citty";
23
import type { Example } from "./_examples.js";
34
import { parseAt } from "./layout.js";
45
import { c } from "../ui/colors.js";
@@ -38,6 +39,93 @@ const DEFAULT_COMMAND_DEPENDENCIES: CheckCommandDependencies = {
3839
withMeta,
3940
};
4041

42+
const CHECK_COMMAND_ARGS = {
43+
dir: { type: "positional", description: "Project directory", required: false },
44+
json: { type: "boolean", description: "Output agent-readable JSON", default: false },
45+
samples: {
46+
type: "string",
47+
description: "Number of midpoint samples across the duration (default: 9)",
48+
default: "9",
49+
},
50+
at: {
51+
type: "string",
52+
description: "Comma-separated timestamps in seconds (e.g., --at 1.5,4,7.25)",
53+
},
54+
"at-transitions": {
55+
type: "boolean",
56+
description:
57+
"Also sample at every tween start/end boundary (plus segment midpoints) to catch transient overlaps at transition seams",
58+
default: false,
59+
},
60+
"max-transition-samples": {
61+
type: "string",
62+
description:
63+
"Optional cap on transition-derived samples; when it truncates, the omitted count is reported (default: unlimited)",
64+
},
65+
"max-issues": {
66+
type: "string",
67+
description: "Maximum issues to print or return after static collapse (default: 80)",
68+
default: "80",
69+
},
70+
"collapse-static": {
71+
type: "boolean",
72+
description: "Collapse repeated static issues across samples (default: true)",
73+
default: true,
74+
},
75+
tolerance: {
76+
type: "string",
77+
description: "Allowed pixel overflow before reporting an issue (default: 2)",
78+
default: "2",
79+
},
80+
timeout: {
81+
type: "string",
82+
description:
83+
"Initial render-ready timeout in ms; also sets the navigation minimum (10s floor, default: 3000)",
84+
default: "3000",
85+
},
86+
contrast: {
87+
type: "boolean",
88+
description: "Run the WCAG AA contrast pass (enabled by default)",
89+
default: true,
90+
},
91+
strict: {
92+
type: "boolean",
93+
description: "Exit non-zero on warnings too",
94+
default: false,
95+
},
96+
proxy: {
97+
type: "boolean",
98+
description:
99+
"Auto-transcode browser-hostile video codecs (default: hyperframes.json media.autoProxy, which defaults on)",
100+
default: undefined,
101+
},
102+
"browser-gpu": {
103+
type: "boolean",
104+
description:
105+
"Use hardware browser GPU capture; pass --no-browser-gpu for deterministic SwiftShader (default: auto-detect, PRODUCER_BROWSER_GPU_MODE overrides)",
106+
default: undefined,
107+
},
108+
snapshots: {
109+
type: "boolean",
110+
description: "Save the five contrast-pass PNGs under snapshots/",
111+
default: false,
112+
},
113+
"caption-zone": {
114+
type: "string",
115+
description:
116+
'Caption band "x0=0;y0=.82;x1=1;y1=1[;severity=warning|error][;seek=.5,1]" (fractions 0-1; defaults: warning, seek=1)',
117+
},
118+
"frame-check": {
119+
type: "string",
120+
description:
121+
'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',
122+
},
123+
layout: {
124+
type: "string",
125+
description: 'Layout knobs: "proseCoverageFloor=0.05" (0–1; default 0.15).',
126+
},
127+
} satisfies ArgsDef;
128+
41129
export function createCheckCommand(
42130
dependencies: CheckCommandDependencies = DEFAULT_COMMAND_DEPENDENCIES,
43131
) {
@@ -47,93 +135,9 @@ export function createCheckCommand(
47135
description:
48136
"Run lint, runtime, layout, motion, and WCAG contrast verification in one browser session",
49137
},
50-
args: {
51-
dir: { type: "positional", description: "Project directory", required: false },
52-
json: { type: "boolean", description: "Output agent-readable JSON", default: false },
53-
samples: {
54-
type: "string",
55-
description: "Number of midpoint samples across the duration (default: 9)",
56-
default: "9",
57-
},
58-
at: {
59-
type: "string",
60-
description: "Comma-separated timestamps in seconds (e.g., --at 1.5,4,7.25)",
61-
},
62-
"at-transitions": {
63-
type: "boolean",
64-
description:
65-
"Also sample at every tween start/end boundary (plus segment midpoints) to catch transient overlaps at transition seams",
66-
default: false,
67-
},
68-
"max-transition-samples": {
69-
type: "string",
70-
description:
71-
"Optional cap on transition-derived samples; when it truncates, the omitted count is reported (default: unlimited)",
72-
},
73-
"max-issues": {
74-
type: "string",
75-
description: "Maximum issues to print or return after static collapse (default: 80)",
76-
default: "80",
77-
},
78-
"collapse-static": {
79-
type: "boolean",
80-
description: "Collapse repeated static issues across samples (default: true)",
81-
default: true,
82-
},
83-
tolerance: {
84-
type: "string",
85-
description: "Allowed pixel overflow before reporting an issue (default: 2)",
86-
default: "2",
87-
},
88-
timeout: {
89-
type: "string",
90-
description:
91-
"Initial render-ready timeout in ms; also sets the navigation minimum (10s floor, default: 3000)",
92-
default: "3000",
93-
},
94-
contrast: {
95-
type: "boolean",
96-
description: "Run the WCAG AA contrast pass (enabled by default)",
97-
default: true,
98-
},
99-
strict: {
100-
type: "boolean",
101-
description: "Exit non-zero on warnings too",
102-
default: false,
103-
},
104-
proxy: {
105-
type: "boolean",
106-
description:
107-
"Auto-transcode browser-hostile video codecs (default: hyperframes.json media.autoProxy, which defaults on)",
108-
default: undefined,
109-
},
110-
"browser-gpu": {
111-
type: "boolean",
112-
description:
113-
"Use hardware browser GPU capture; pass --no-browser-gpu for deterministic SwiftShader (default: auto-detect, PRODUCER_BROWSER_GPU_MODE overrides)",
114-
default: undefined,
115-
},
116-
snapshots: {
117-
type: "boolean",
118-
description: "Save the five contrast-pass PNGs under snapshots/",
119-
default: false,
120-
},
121-
"caption-zone": {
122-
type: "string",
123-
description:
124-
'Caption band "x0=0;y0=.82;x1=1;y1=1[;severity=warning|error][;seek=.5,1]" (fractions 0-1; defaults: warning, seek=1)',
125-
},
126-
"frame-check": {
127-
type: "string",
128-
description:
129-
'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',
130-
},
131-
layout: {
132-
type: "string",
133-
description: 'Layout knobs: "proseCoverageFloor=0.05" (0–1; default 0.15).',
134-
},
135-
},
136-
async run({ args }) {
138+
args: CHECK_COMMAND_ARGS,
139+
async run({ rawArgs }) {
140+
const args = parseArgs(normalizeFrameCheckRawArgs(rawArgs), CHECK_COMMAND_ARGS);
137141
const asJson = args.json === true;
138142

139143
try {
@@ -164,6 +168,14 @@ export function createCheckCommand(
164168
});
165169
}
166170

171+
function normalizeFrameCheckRawArgs(rawArgs: string[]): string[] {
172+
return rawArgs.map((arg, index) => {
173+
if (arg !== "--frame-check") return arg;
174+
const next = rawArgs[index + 1];
175+
return next === undefined || next.startsWith("-") ? "--frame-check=" : arg;
176+
});
177+
}
178+
167179
function parseCheckOptions(args: Record<string, unknown>): CheckOptions {
168180
const maxTransitionSamples = positiveInteger(args["max-transition-samples"], 0);
169181
return {
@@ -199,9 +211,10 @@ export function parseFrameCheck(value: unknown): FrameCheckOptions | undefined {
199211
if (value === undefined || value === null || value === false) return undefined;
200212
if (value === true || value === "") return {};
201213
if (typeof value !== "string") throw frameCheckError();
214+
if (value.startsWith("-")) throw swallowedOptionError("frame-check", value);
202215
const fields = parseFrameCheckFields(value);
203-
const severity = captionSeverity(fields.get("severity"));
204-
const seek = captionSeeks(fields.get("seek"));
216+
const severity = captionSeverity(fields.get("severity"), frameCheckError);
217+
const seek = captionSeeks(fields.get("seek"), frameCheckError);
205218
const tol = parseFrameCheckTolerance(fields.get("tol"));
206219
return {
207220
...(severity ? { severity } : {}),
@@ -213,7 +226,7 @@ export function parseFrameCheck(value: unknown): FrameCheckOptions | undefined {
213226
function parseFrameCheckFields(value: string): Map<string, string> {
214227
const fields = new Map<string, string>();
215228
for (const part of value.split(";")) {
216-
const { key, entry } = parseCaptionField(part);
229+
const { key, entry } = parseCaptionField(part, frameCheckError);
217230
if (!FRAME_CHECK_FIELDS.has(key) || fields.has(key)) throw frameCheckError();
218231
fields.set(key, entry);
219232
}
@@ -233,6 +246,12 @@ function frameCheckError(): Error {
233246
);
234247
}
235248

249+
function swallowedOptionError(flag: string, value: string): Error {
250+
return new Error(
251+
`Invalid --${flag}: value "${value}" appears to have swallowed the next option; use --${flag}= or move --${flag} to the end`,
252+
);
253+
}
254+
236255
/** Parse `--layout "proseCoverageFloor=0.05"` (semicolon-separated key=value, like caption-zone). */
237256
export function parseLayout(value: unknown): LayoutOptions | undefined {
238257
if (value === undefined || value === null || value === false) return undefined;
@@ -310,9 +329,12 @@ function parseCaptionFields(value: string): Map<string, string> {
310329
return fields;
311330
}
312331

313-
function parseCaptionField(part: string): { key: string; entry: string } {
332+
function parseCaptionField(
333+
part: string,
334+
errorFactory: () => Error = captionZoneError,
335+
): { key: string; entry: string } {
314336
const separator = part.indexOf("=");
315-
if (separator <= 0) throw captionZoneError();
337+
if (separator <= 0) throw errorFactory();
316338
return {
317339
key: part.slice(0, separator).trim(),
318340
entry: part.slice(separator + 1).trim(),
@@ -345,17 +367,23 @@ function captionFraction(value: string | undefined): number | null {
345367
return parsed !== null && parsed >= 0 && parsed <= 1 ? parsed : null;
346368
}
347369

348-
function captionSeverity(value: string | undefined): "error" | "warning" | undefined {
370+
function captionSeverity(
371+
value: string | undefined,
372+
errorFactory: () => Error = captionZoneError,
373+
): "error" | "warning" | undefined {
349374
if (value === undefined) return undefined;
350375
if (value === "error" || value === "warning") return value;
351-
throw captionZoneError();
376+
throw errorFactory();
352377
}
353378

354-
function captionSeeks(value: string | undefined): number[] | undefined {
379+
function captionSeeks(
380+
value: string | undefined,
381+
errorFactory: () => Error = captionZoneError,
382+
): number[] | undefined {
355383
if (value === undefined) return undefined;
356384
if (value === "") return [];
357385
const values = value.split(",").map(captionFraction);
358-
if (values.some((entry) => entry === null)) throw captionZoneError();
386+
if (values.some((entry) => entry === null)) throw errorFactory();
359387
return values.flatMap((entry) => (entry === null ? [] : entry));
360388
}
361389

0 commit comments

Comments
 (0)