1- import { defineCommand } from "citty" ;
1+ import { defineCommand , parseArgs } from "citty" ;
2+ import type { ArgsDef } from "citty" ;
23import type { Example } from "./_examples.js" ;
34import { parseAt } from "./layout.js" ;
45import { 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+
41129export 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+
167179function 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 {
213226function 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). */
237256export 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