Skip to content

Commit 36526bf

Browse files
authored
feat(cli): scope check to a time range or a set of components (#5516)
* feat(cli): scope check to a time range or a set of components * fix(cli): keep ranged check gates truthful Refuse ranged caption and frame gates when none of their seek times falls inside the requested range. Make ranged motion reporting, overlap timestamps, filtering tests, and scope documentation match.
1 parent 69f3306 commit 36526bf

7 files changed

Lines changed: 376 additions & 32 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -713,7 +713,7 @@ did, in one command and one browser session.
713713

714714
```bash
715715
npx hyperframes check [dir]
716-
npx hyperframes check [dir] --json # {ok, browserSkipped, lint, runtime, layout, motion, contrast, hdr, snapshots}
716+
npx hyperframes check [dir] --json # {ok, browserSkipped, scope, lint, runtime, layout, motion, contrast, hdr, snapshots}
717717
npx hyperframes check [dir] --snapshots
718718
npx hyperframes check [dir] --at 1.5,4,7.25
719719
npx hyperframes check [dir] --strict # warnings fail too
@@ -729,6 +729,11 @@ When the browser never ran (lint errors, a linter crash, or a browser launch
729729
failure), `browserSkipped` is `true` and the `layout`, `motion` and `contrast`
730730
sections are empty, not clean.
731731

732+
Scoped checks add `scope` to the JSON report with the requested range and
733+
components, hidden-finding count, and scope notes. Component filtering changes
734+
the returned finding arrays only; section counts, `ok`, and the exit code still
735+
cover every finding from the full check.
736+
732737
| Flag | Description |
733738
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
734739
| `--json` | One aggregated envelope. Every finding carries a selector, `data-*` identity, source file, bbox, and sample time. |
@@ -737,6 +742,8 @@ sections are empty, not clean.
737742
| `--at` | Explicit timestamps in seconds, comma-separated |
738743
| `--at-transitions` | Also sample every tween start and end, to catch transient overlaps at transition seams |
739744
| `--max-transition-samples` | Cap the transition-derived samples. When it truncates, the omitted count is reported. Default: unlimited. |
745+
| `--range <start,end>` | Sample only this interval, in global seconds. Lint stays project-wide; whole-timeline motion and `sweep_static` are skipped. |
746+
| `--components <selectors>` | Report only findings that involve these elements or their descendants. Counts, `ok` and the exit code still cover all. |
740747
| `--max-issues` | Findings to print or return after static collapse (default 80) |
741748
| `--collapse-static` / `--no-collapse-static` | Fold a repeated static finding into one row (default: on) |
742749
| `--tolerance` | Allowed overflow in px before reporting (default 2) |
@@ -749,6 +756,10 @@ sections are empty, not clean.
749756
| `--browser-gpu` / `--no-browser-gpu` | Hardware GPU capture, or deterministic SwiftShader (default: auto-detect) |
750757
| `--proxy` / `--no-proxy` | Auto-transcode browser-hostile codecs before checking (default: on) |
751758

759+
`--caption-zone` and `--frame-check` refuse a ranged check when none of their
760+
configured seek samples falls inside `--range`; a requested gate never silently
761+
passes without running.
762+
752763
Contrast failures are errors, and each one reports the sampled foreground and
753764
background colours, the measured ratio against the required one, and a
754765
compliant colour you could use instead.

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

Lines changed: 111 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ vi.mock("../telemetry/events.js", () => ({
99
}));
1010

1111
import { contrastRatio, parseColorRGBA } from "./contrast-bg.js";
12-
import { createCheckCommand } from "./check.js";
12+
import { createCheckCommand, parseCheckRange } from "./check.js";
1313
import { trackCommandFailures } from "../utils/command-failure-tracking.js";
1414
import type { CommandDef } from "citty";
1515

@@ -2259,3 +2259,113 @@ describe("dense motion-overlap re-sampling", () => {
22592259
expect(report.layout.findings.some((f) => f.code === "content_overlap")).toBe(true);
22602260
});
22612261
});
2262+
2263+
describe("scoped check", () => {
2264+
it("bounds all runtime seeks, including dense overlap and transition samples", async () => {
2265+
const times: number[] = [];
2266+
const overlapTimes: number[] = [];
2267+
const driver = fakeDriver({
2268+
getDuration: async () => 10,
2269+
getTransitionBoundaries: async () => [1, 7.9, 9],
2270+
seek: async (t) => {
2271+
times.push(t);
2272+
},
2273+
seekGeometry: async (t) => {
2274+
times.push(t);
2275+
overlapTimes.push(t);
2276+
},
2277+
});
2278+
const { report } = await runScenario(driver, { range: [7.8, 8.2], atTransitions: true });
2279+
expect(times.length).toBeGreaterThan(3);
2280+
expect(times.every((t) => t >= 7.8 && t <= 8.2)).toBe(true);
2281+
expect(times).toContain(7.9);
2282+
expect(overlapTimes.every((time) => (String(time).split(".")[1]?.length ?? 0) <= 3)).toBe(true);
2283+
expect(report.scope?.range).toEqual([7.8, 8.2]);
2284+
});
2285+
it("keeps the full-check failure when the only error is hidden by filtering", async () => {
2286+
const driver = fakeDriver({
2287+
collectLayout: async () => [layoutIssue("error")],
2288+
matchComponents: async (_c, f) => f.map(() => false),
2289+
});
2290+
const { report } = await runScenario(driver, {
2291+
components: ["#selected"],
2292+
collapseStatic: false,
2293+
});
2294+
expect(report.ok).toBe(false);
2295+
expect(report.layout.findings).toHaveLength(0);
2296+
expect(report.layout.errorCount).toBe(1);
2297+
expect(report.runtime.findings).toHaveLength(0);
2298+
expect(report.scope?.hiddenFindings).toBe(1);
2299+
});
2300+
it.each([
2301+
{
2302+
flag: "--caption-zone",
2303+
options: {
2304+
range: [1, 2] as [number, number],
2305+
captionZone: { x0: 0, y0: 0.5, x1: 1, y1: 0.7 },
2306+
},
2307+
},
2308+
{
2309+
flag: "--frame-check",
2310+
options: { range: [0, 1] as [number, number], frameCheck: {} },
2311+
},
2312+
])(
2313+
"refuses $flag when none of its gate samples lie within --range",
2314+
async ({ flag, options }) => {
2315+
const { report } = await runScenario(fakeDriver({ getDuration: async () => 4 }), options);
2316+
expect(report.ok).toBe(false);
2317+
expect(report.browserSkipped).toBe(true);
2318+
expect(report.runtime.findings).toEqual([
2319+
expect.objectContaining({ message: expect.stringContaining(`No ${flag} seek samples`) }),
2320+
]);
2321+
},
2322+
);
2323+
it("marks a motion spec disabled when a range skips whole-timeline assertions", async () => {
2324+
const motion: MotionSpecResolution = {
2325+
kind: "valid",
2326+
path: "/project/index.motion.json",
2327+
spec: { assertions: [] },
2328+
};
2329+
const { report } = await runScenario(
2330+
fakeDriver({ getDuration: async () => 4 }),
2331+
{ range: [1, 2] },
2332+
{ motion },
2333+
);
2334+
expect(report.motion).toEqual(
2335+
expect.objectContaining({
2336+
enabled: false,
2337+
specPath: "/project/index.motion.json",
2338+
samples: 0,
2339+
}),
2340+
);
2341+
});
2342+
it("rejects a range outside the film rather than passing an empty check", async () => {
2343+
const { report } = await runScenario(fakeDriver({ getDuration: async () => 2 }), {
2344+
range: [3, 4],
2345+
});
2346+
expect(report.ok).toBe(false);
2347+
expect(report.browserSkipped).toBe(true);
2348+
expect(report.runtime.findings[0]?.message).toContain("2 seconds");
2349+
});
2350+
});
2351+
2352+
it("validates range syntax before running a check", () => {
2353+
expect(parseCheckRange("7.8,8.2")).toEqual([7.8, 8.2]);
2354+
expect(parseCheckRange("7.8:8.2")).toEqual([7.8, 8.2]);
2355+
for (const value of ["", "1", "1,1", "2,1", "-1,2", "NaN,2", "1,Infinity", ",2", "1,2,3"])
2356+
expect(() => parseCheckRange(value)).toThrow();
2357+
});
2358+
2359+
it("applies transition sample limits within the requested range", async () => {
2360+
const driver = fakeDriver({
2361+
getDuration: async () => 10,
2362+
getTransitionBoundaries: async () => [0, 1, 2, 3, 4, 5, 6, 7.8, 7.9, 8, 9, 10],
2363+
});
2364+
const { report } = await runScenario(driver, {
2365+
range: [7.8, 8],
2366+
atTransitions: true,
2367+
maxTransitionSamples: 2,
2368+
});
2369+
expect(report.layout.transitionSamples).toEqual([7.8, 8]);
2370+
expect(report.layout.transitionSamplesDropped).toBe(3);
2371+
});

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

Lines changed: 45 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,16 @@ const CHECK_COMMAND_ARGS = {
4949
description: "Number of midpoint samples across the duration (default: 9)",
5050
default: "9",
5151
},
52+
range: {
53+
type: "string",
54+
description:
55+
"Runtime sample interval in global seconds: start,end. Static lint remains project-wide.",
56+
},
57+
components: {
58+
type: "string",
59+
description:
60+
"CSS selector list: filter findings involving these components or descendants; preserve full-check status.",
61+
},
5262
at: {
5363
type: "string",
5464
description: "Comma-separated timestamps in seconds (e.g., --at 1.5,4,7.25)",
@@ -174,6 +184,8 @@ function parseCheckOptions(args: Record<string, unknown>): CheckOptions {
174184
const maxTransitionSamples = positiveInteger(args["max-transition-samples"], 0);
175185
return {
176186
samples: positiveInteger(args.samples, DEFAULT_CHECK_OPTIONS.samples),
187+
range: parseCheckRange(args.range),
188+
components: typeof args.components === "string" ? [args.components] : undefined,
177189
at: parseAt(args.at),
178190
atTransitions: args["at-transitions"] === true,
179191
maxTransitionSamples: maxTransitionSamples > 0 ? maxTransitionSamples : undefined,
@@ -192,6 +204,23 @@ function parseCheckOptions(args: Record<string, unknown>): CheckOptions {
192204
};
193205
}
194206

207+
export function parseCheckRange(value: unknown): [number, number] | undefined {
208+
if (value === undefined) return undefined;
209+
const parts = String(value).split(/[,:]/);
210+
const start = Number(parts[0]),
211+
end = Number(parts[1]);
212+
if (
213+
parts.length !== 2 ||
214+
parts.some((p) => !p.trim()) ||
215+
!Number.isFinite(start) ||
216+
!Number.isFinite(end) ||
217+
start < 0 ||
218+
end <= start
219+
)
220+
throw new Error("Invalid --range: use non-negative start,end with end > start");
221+
return [start, end];
222+
}
223+
195224
const CAPTION_ZONE_FIELDS = new Set(["x0", "y0", "x1", "y1", "severity", "seek"]);
196225

197226
const FRAME_CHECK_FIELDS = new Set(["severity", "seek", "tol"]);
@@ -392,6 +421,12 @@ function nonNegativeNumber(value: unknown, fallback: number): number {
392421
}
393422

394423
function printHumanReport(report: CheckReport): void {
424+
if (report.scope) {
425+
console.log(
426+
`Scope: ${report.scope.range ? report.scope.range.join("–") + "s" : "full timeline"}; ${report.scope.hiddenFindings} findings hidden by component filter. Counts/status include hidden findings.`,
427+
);
428+
for (const note of report.scope.notes) console.log(note);
429+
}
395430
printSection("Lint", report.lint);
396431
if (report.browserSkipped) {
397432
console.log();
@@ -409,10 +444,17 @@ function printHumanReport(report: CheckReport): void {
409444
console.log(`${report.ok ? c.success("◇") : c.error("◇")} ${label}`);
410445
}
411446

447+
function isEmptySection(section: CheckSection): boolean {
448+
return (
449+
section.findings.length === 0 &&
450+
section.errorCount + section.warningCount + section.infoCount === 0
451+
);
452+
}
453+
412454
function printSection(title: string, section: CheckSection): void {
413455
console.log();
414456
console.log(c.bold(title));
415-
if (section.findings.length === 0) {
457+
if (isEmptySection(section)) {
416458
console.log(` ${c.success("◇")} 0 errors, 0 warnings`);
417459
return;
418460
}
@@ -423,7 +465,7 @@ function printSection(title: string, section: CheckSection): void {
423465
function printLayoutSection(title: string, section: CheckReport["layout"]): void {
424466
console.log();
425467
console.log(c.bold(title));
426-
if (section.findings.length === 0) {
468+
if (isEmptySection(section)) {
427469
console.log(` ${c.success("◇")} 0 issues across ${section.samples.length} sample(s)`);
428470
} else {
429471
for (const finding of section.findings) {
@@ -447,7 +489,7 @@ function printContrastSection(report: CheckReport): void {
447489
console.log(` ${c.dim("◇")} skipped`);
448490
return;
449491
}
450-
if (section.findings.length === 0) {
492+
if (isEmptySection(section)) {
451493
console.log(
452494
` ${c.success("◇")} ${section.passed}/${section.checked} text checks pass WCAG AA`,
453495
);

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import {
1010
} from "../capture/captureCompositionFrame.js";
1111
import { DEFAULT_CHECK_OPTIONS, runAuditGrid } from "./checkPipeline.js";
1212
import {
13+
matchComponentFindings,
1314
captureOverviewShot,
1415
keepBrokenImageAborts,
1516
preResolveHostileMediaProxies,
@@ -999,3 +1000,35 @@ function fakePage() {
9991000
}),
10001001
});
10011002
}
1003+
1004+
describe("component output membership", () => {
1005+
it("includes descendants and either side of a collision; keeps unresolved findings", () => {
1006+
document.body.innerHTML =
1007+
'<section id="selected"><span id="child"></span></section><section id="other"><span id="outside"></span></section>';
1008+
const finding = (selector: string, containerSelector?: string) => ({
1009+
code: "content_overlap",
1010+
severity: "error" as const,
1011+
selector,
1012+
containerSelector,
1013+
sourceFile: "index.html",
1014+
dataAttributes: {},
1015+
bbox: { x: 0, y: 0, width: 1, height: 1 },
1016+
time: 1,
1017+
message: "collision",
1018+
});
1019+
expect(
1020+
matchComponentFindings({
1021+
components: ["#selected"],
1022+
findings: [
1023+
finding("#child"),
1024+
finding("#outside", "#child"),
1025+
finding("#outside", "#other"),
1026+
finding("#gone"),
1027+
],
1028+
}),
1029+
).toEqual([true, true, false, true]);
1030+
expect(() => matchComponentFindings({ components: ["#missing"], findings: [] })).toThrow(
1031+
"matched nothing",
1032+
);
1033+
});
1034+
});

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -527,6 +527,8 @@ function wireNetworkListeners(page: Page, drafts: RuntimeDraft[], currentTime: (
527527
function createPageDriver(page: Page, setTime: (time: number) => void): CheckAuditDriver {
528528
return {
529529
initialize: (contrast) => injectAuditScripts(page, contrast),
530+
matchComponents: (components, findings) =>
531+
page.evaluate(matchComponentFindings, { components, findings }),
530532
getDuration: () => getCompositionDuration(page),
531533
hasNoTimelineDeclaration: () => hasNoTimelineDeclaration(page),
532534
getTransitionBoundaries: () => collectTweenBoundaries(page),
@@ -1480,3 +1482,34 @@ function urlPath(url: string): string {
14801482
return url;
14811483
}
14821484
}
1485+
1486+
export function matchComponentFindings({
1487+
components,
1488+
findings,
1489+
}: {
1490+
components: string[];
1491+
findings: CheckFinding[];
1492+
}): boolean[] {
1493+
const roots = components.flatMap((selector) => {
1494+
const matches = [...document.querySelectorAll(selector)];
1495+
if (!matches.length) throw new Error(`Component selector matched nothing: ${selector}`);
1496+
return matches;
1497+
});
1498+
function matchesSelector(selector: string): boolean | null {
1499+
try {
1500+
const elements = [...document.querySelectorAll(selector)];
1501+
if (!elements.length) return null;
1502+
return elements.some((el) => roots.some((root) => root.contains(el)));
1503+
} catch {
1504+
return null;
1505+
}
1506+
}
1507+
return findings.map((finding) => {
1508+
if (!finding.selector || finding.selector === "[data-composition-id]") return true;
1509+
const container = Reflect.get(finding, "containerSelector");
1510+
return (
1511+
matchesSelector(finding.selector) !== false ||
1512+
(typeof container === "string" && matchesSelector(container) !== false)
1513+
);
1514+
});
1515+
}

0 commit comments

Comments
 (0)