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.
This commit is contained in:
Xuanru Li
2026-10-13 03:13:26 +00:00
committed by GitHub
parent 69f3306415
commit 36526bf1a6
7 changed files with 376 additions and 32 deletions
@@ -10,6 +10,7 @@ import {
} from "../capture/captureCompositionFrame.js";
import { DEFAULT_CHECK_OPTIONS, runAuditGrid } from "./checkPipeline.js";
import {
matchComponentFindings,
captureOverviewShot,
keepBrokenImageAborts,
preResolveHostileMediaProxies,
@@ -999,3 +1000,35 @@ function fakePage() {
}),
});
}
describe("component output membership", () => {
it("includes descendants and either side of a collision; keeps unresolved findings", () => {
document.body.innerHTML =
'<section id="selected"><span id="child"></span></section><section id="other"><span id="outside"></span></section>';
const finding = (selector: string, containerSelector?: string) => ({
code: "content_overlap",
severity: "error" as const,
selector,
containerSelector,
sourceFile: "index.html",
dataAttributes: {},
bbox: { x: 0, y: 0, width: 1, height: 1 },
time: 1,
message: "collision",
});
expect(
matchComponentFindings({
components: ["#selected"],
findings: [
finding("#child"),
finding("#outside", "#child"),
finding("#outside", "#other"),
finding("#gone"),
],
}),
).toEqual([true, true, false, true]);
expect(() => matchComponentFindings({ components: ["#missing"], findings: [] })).toThrow(
"matched nothing",
);
});
});
+33
View File
@@ -527,6 +527,8 @@ function wireNetworkListeners(page: Page, drafts: RuntimeDraft[], currentTime: (
function createPageDriver(page: Page, setTime: (time: number) => void): CheckAuditDriver {
return {
initialize: (contrast) => injectAuditScripts(page, contrast),
matchComponents: (components, findings) =>
page.evaluate(matchComponentFindings, { components, findings }),
getDuration: () => getCompositionDuration(page),
hasNoTimelineDeclaration: () => hasNoTimelineDeclaration(page),
getTransitionBoundaries: () => collectTweenBoundaries(page),
@@ -1480,3 +1482,34 @@ function urlPath(url: string): string {
return url;
}
}
export function matchComponentFindings({
components,
findings,
}: {
components: string[];
findings: CheckFinding[];
}): boolean[] {
const roots = components.flatMap((selector) => {
const matches = [...document.querySelectorAll(selector)];
if (!matches.length) throw new Error(`Component selector matched nothing: ${selector}`);
return matches;
});
function matchesSelector(selector: string): boolean | null {
try {
const elements = [...document.querySelectorAll(selector)];
if (!elements.length) return null;
return elements.some((el) => roots.some((root) => root.contains(el)));
} catch {
return null;
}
}
return findings.map((finding) => {
if (!finding.selector || finding.selector === "[data-composition-id]") return true;
const container = Reflect.get(finding, "containerSelector");
return (
matchesSelector(finding.selector) !== false ||
(typeof container === "string" && matchesSelector(container) !== false)
);
});
}
+132 -27
View File
@@ -132,31 +132,74 @@ function gateSampleTimes(
return mergeSampleTimes(fractions.map((fraction) => fraction * duration));
}
function validateSampleRange([start, end]: [number, number], duration: number): void {
if (!Number.isFinite(start + end) || start < 0 || end <= start || end > duration)
throw new Error(`Check range must lie within the composition duration (${duration} seconds)`);
}
function gateSamplesInRange(
flag: "--caption-zone" | "--frame-check",
samples: number[],
inRange: (time: number) => boolean,
range: [number, number] | undefined,
): number[] {
if (!range) return samples;
const selected = samples.filter(inRange);
if (samples.length > 0 && selected.length === 0) {
throw new Error(`No ${flag} seek samples lie within --range`);
}
return selected;
}
function layoutSamplesInRange(options: CheckOptions, duration: number) {
if (!options.range)
return {
inRange: (_t: number) => true,
baseSamples: buildLayoutSampleTimes({ duration, samples: options.samples, at: options.at }),
};
validateSampleRange(options.range, duration);
const [start, end] = options.range;
const inRange = (t: number) => t >= start && t <= end;
const selected = (options.at ?? []).filter(inRange);
if (options.at?.length && !selected.length) throw new Error("No --at samples lie within --range");
const baseSamples = buildLayoutSampleTimes({
duration: end - start,
samples: options.samples,
at: selected.map((t) => t - start),
}).map((t) => t + start);
return { inRange, baseSamples };
}
async function buildSampleGrid(
driver: CheckAuditDriver,
options: CheckOptions,
): Promise<SampleGrid> {
const duration = await driver.getDuration();
const baseSamples = buildLayoutSampleTimes({
duration,
samples: options.samples,
at: options.at,
});
const { inRange, baseSamples } = layoutSamplesInRange(options, duration);
const transitions = options.atTransitions
? buildTransitionSampleTimes({
duration,
boundaries: await driver.getTransitionBoundaries(),
boundaries: (await driver.getTransitionBoundaries()).filter(inRange),
cap: options.maxTransitionSamples,
})
: { times: [], dropped: 0 };
const captionSamples = options.captionZone
? gateSampleTimes(duration, options.captionZone.seek, 1)
: [];
const frameSamples = options.frameCheck
? gateSampleTimes(duration, options.frameCheck.seek, 0.5)
: [];
const auditSamples = mergeSampleTimes(baseSamples, transitions.times);
const layoutSamples = mergeSampleTimes(auditSamples, captionSamples, frameSamples);
const captionSamples = gateSamplesInRange(
"--caption-zone",
options.captionZone ? gateSampleTimes(duration, options.captionZone.seek, 1) : [],
inRange,
options.range,
);
const frameSamples = gateSamplesInRange(
"--frame-check",
options.frameCheck ? gateSampleTimes(duration, options.frameCheck.seek, 0.5) : [],
inRange,
options.range,
);
transitions.times = transitions.times.filter(inRange);
const auditSamples = mergeSampleTimes(baseSamples, transitions.times).filter(inRange);
const layoutSamples = mergeSampleTimes(auditSamples, captionSamples, frameSamples).filter(
inRange,
);
if (layoutSamples.length === 0) {
throw new Error("Could not determine composition duration — no layout samples run");
}
@@ -433,7 +476,7 @@ async function collectGridSamples(
collected.screenshots.push({ time, pngBase64: capture.pngBase64 });
}
}
await collectMotionOverlapSamples(driver, grid, collected);
await collectMotionOverlapSamples(driver, grid, collected, options.range);
return collected;
}
@@ -459,9 +502,14 @@ async function collectMotionOverlapSamples(
driver: CheckAuditDriver,
grid: SampleGrid,
collected: GridSamples,
range?: [number, number],
): Promise<void> {
const baseTimes = new Set(grid.layoutSamples);
for (const time of buildOverlapSampleTimes(grid.duration)) {
const overlapTimes = buildOverlapSampleTimes(range ? range[1] - range[0] : grid.duration);
const shiftedTimes = range
? mergeSampleTimes(overlapTimes.map((time) => time + range[0]))
: overlapTimes;
for (const time of shiftedTimes) {
if (baseTimes.has(time)) continue;
// Settle-free seek: collectOverlap reads getBoundingClientRect geometry, valid synchronously after setTime, so the dense pass skips the per-seek paint settle.
await driver.seekGeometry(time);
@@ -1098,7 +1146,11 @@ export async function runAuditGrid(
): Promise<CheckBrowserResult> {
await driver.initialize(options.contrast);
const grid = await buildSampleGrid(driver, options);
const plan = await planMotionSampling(driver, motion, grid.duration);
const plan = await planMotionSampling(
driver,
options.range ? { kind: "none" } : motion,
grid.duration,
);
const seekLoopStart = Date.now();
const collected = await collectGridSamples(driver, options, grid, plan);
const seekLoopMs = Date.now() - seekLoopStart;
@@ -1113,18 +1165,36 @@ export async function runAuditGrid(
motionIssues = [...motionIssues, ...(await driver.anchorMotionIssues(evaluated))];
}
const userPicked = new Set(grid.userPickedSamples);
const sweepFindings = detectSweepStatic(
grid.duration,
collected.layoutStateSignatures.filter((sample) => !userPicked.has(sample.time)),
motionIssues,
await driver.hasNoTimelineDeclaration(),
);
const sweepFindings = options.range
? []
: detectSweepStatic(
grid.duration,
collected.layoutStateSignatures.filter((sample) => !userPicked.has(sample.time)),
motionIssues,
await driver.hasNoTimelineDeclaration(),
);
const rotationFindings = detectRotationPivotDrift(
collected.rotationSamples,
await driver.getCanvas(),
);
const offPivotFindings = detectOffPivotRotation(collected.indicatorFrames);
const contrast = buildContrastResults(collected.contrastEntries);
if (options.components?.length) {
if (!driver.matchComponents)
throw new Error("Component filtering unavailable in this check driver");
const findings = [
...collected.layoutIssues,
...sweepFindings,
...rotationFindings,
...offPivotFindings,
...motionIssues,
...contrast.findings,
];
const matches = await driver.matchComponents(options.components, findings);
findings.forEach((finding, i) => {
finding.componentMatch = matches[i];
});
}
return {
duration: grid.duration,
layoutSamples: grid.layoutSamples,
@@ -1413,8 +1483,11 @@ function buildReport(
hdrPromotion: CheckReport["hdr"]["autoPromotion"] = null,
hdrInspection: CheckReport["hdr"]["inspection"] = "available",
): CheckReport {
const layout = shapeLayoutSection(browser.layoutIssues, browser, options);
const shapedMotion = shapeLayoutFindings(browser.motionIssues, options);
const shaping = options.components?.length
? { ...options, maxIssues: Number.MAX_SAFE_INTEGER }
: options;
const layout = shapeLayoutSection(browser.layoutIssues, browser, shaping);
const shapedMotion = shapeLayoutFindings(browser.motionIssues, shaping);
const motionFindings: CheckFinding[] = [...shapedMotion.findings, ...extraMotionFindings];
const runtime = section(browser.runtimeFindings);
const motionSection = section(motionFindings);
@@ -1440,7 +1513,7 @@ function buildReport(
layout,
motion: {
...motionSection,
enabled: motion.kind !== "none",
enabled: motion.kind !== "none" && !options.range,
specPath: motion.kind === "none" ? undefined : motion.path,
samples: browser.motionSampleCount,
},
@@ -1461,7 +1534,7 @@ function buildReport(
};
trackCheckReport({
contrastGate: options.contrast,
motionGate: motion.kind !== "none",
motionGate: motion.kind !== "none" && !options.range,
captionZoneGate: options.captionZone !== undefined,
frameCheckGate: options.frameCheck !== undefined,
snapshotsGate: options.snapshots,
@@ -1484,6 +1557,38 @@ function buildReport(
exitCode: checkExitCode(report),
runId: getRunId(),
});
return filterComponentReport(report, options);
}
function filterComponentReport(report: CheckReport, options: CheckOptions): CheckReport {
if (!options.range && !options.components?.length) return report;
{
report.scope = {
range: options.range,
components: options.components,
hiddenFindings: 0,
notes: [
"Static lint and unscoped runtime failures remain project-wide.",
...(options.range
? [
"Whole-timeline motion assertions and frozen-sweep detection are skipped for range checks.",
]
: []),
],
};
for (const group of [report.layout, report.motion, report.contrast]) {
const before = group.findings.length;
group.findings = group.findings.filter((f) => f.componentMatch !== false);
report.scope.hiddenFindings += before - group.findings.length;
if (group !== report.contrast && group.findings.length > options.maxIssues) {
group.findings = group.findings.slice(0, options.maxIssues);
report.scope.notes.push(
"Selected findings exceed --max-issues; increase it to see the remainder.",
);
if (group === report.layout) report.layout.truncated = true;
}
}
}
return report;
}
+10
View File
@@ -8,6 +8,8 @@ import type { HdrAutoPromotion } from "@hyperframes/engine";
export interface CheckOptions {
samples: number;
range?: [number, number];
components?: string[];
at?: number[];
atTransitions: boolean;
maxTransitionSamples?: number;
@@ -70,6 +72,7 @@ export interface CheckAnchor {
bbox: CheckBbox;
time: number;
times?: number[];
componentMatch?: boolean;
}
export interface CheckFinding extends CheckAnchor {
@@ -186,6 +189,7 @@ export type MotionSpecResolution =
export interface CheckAuditDriver {
initialize(contrast: boolean): Promise<void>;
matchComponents?(components: string[], findings: CheckFinding[]): Promise<boolean[]>;
getDuration(): Promise<number>;
/** True when the root composition explicitly declares that it is intentionally timeline-free. */
hasNoTimelineDeclaration(): Promise<boolean>;
@@ -271,6 +275,12 @@ export interface CheckSection<T extends CheckFinding = CheckFinding> {
}
export interface CheckReport {
scope?: {
range?: [number, number];
components?: string[];
hiddenFindings: number;
notes: string[];
};
ok: boolean;
strict: boolean;
browserSkipped: boolean;