Skip to content

Write HTML. Render video. Built for agents.

fix(cli): group sampled check findings by element and rule (#5174)

Miguel Ángel188475aaf2cc
diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.ts
index 69d629639e..7415104133 100644
--- a/packages/cli/src/commands/check.test.ts
+++ b/packages/cli/src/commands/check.test.ts
@@ -724,7 +724,7 @@ it("checks media overflow at the default midpoint and applies warning severity",
});
});
-it("converts progress seeks to time, gates each collector, and keeps the first caption hit", async () => {
+it("converts progress seeks to time, gates each collector, and keeps distinct caption elements", async () => {
const collectGeometryCandidates = vi.fn(gateCandidates);
const { report } = await runScenario(
fakeDriver({
@@ -760,6 +760,13 @@ it("converts progress seeks to time, gates each collector, and keeps the first c
time: 2,
}),
expect.objectContaining({ code: "frame_out_of_frame", severity: "error", time: 4 }),
+ expect.objectContaining({
+ code: "caption_zone_collision",
+ severity: "error",
+ selector: "#later-heading",
+ time: 6,
+ times: [6],
+ }),
]);
expect(report.ok).toBe(false);
});
@@ -861,7 +868,7 @@ it("suppresses frame breaches below the per-canvas floor and reports those above
]);
});
-it("keeps frame findings at distinct rounded positions across requested seeks", async () => {
+it("reports one moving element rule with both requested seek times", async () => {
const collectGeometryCandidates = vi.fn(async (time: number) => [
geometryCandidate({
kind: "media",
@@ -886,8 +893,16 @@ it("keeps frame findings at distinct rounded positions across requested seeks",
);
expect(report.layout.findings).toEqual([
- expect.objectContaining({ code: "frame_out_of_frame", time: 2 }),
- expect.objectContaining({ code: "frame_out_of_frame", time: 6 }),
+ expect.objectContaining({
+ code: "frame_out_of_frame",
+ time: 2,
+ times: [2, 6],
+ firstSeen: 2,
+ lastSeen: 6,
+ occurrences: 2,
+ heldMs: 0,
+ bbox: { x: 1920, y: 100, width: 130, height: 100 },
+ }),
]);
});
@@ -1689,6 +1704,209 @@ describe("layout flag grammar", () => {
});
});
+describe("sampled finding reporting", () => {
+ it("keeps the representative crop time paired with its geometry when dense observations arrive earlier", async () => {
+ const movingOverlap = (time: number): AnchoredLayoutIssue => {
+ const rect = fixtureRect(time * 1000, 20, 300, 80);
+ return {
+ ...layoutIssue("warning", { time, code: "content_overlap" }),
+ rect,
+ bbox: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
+ };
+ };
+ const captureFindingCrops = vi.fn(async () => []);
+ const { report } = await runScenario(
+ fakeDriver({
+ getDuration: vi.fn(async () => 1),
+ collectLayout: vi.fn(async (time: number) => (time === 0.5 ? [movingOverlap(time)] : [])),
+ collectOverlap: vi.fn(async (time: number) =>
+ time >= 0.125 && time <= 0.75 ? [movingOverlap(time)] : [],
+ ),
+ }),
+ { samples: 2, at: [0.5, 0.875], contrast: false, snapshots: true },
+ { captureFindingCrops },
+ );
+ expect(report.layout.findings).toEqual([
+ expect.objectContaining({
+ code: "content_overlap",
+ severity: "error",
+ time: 0.5,
+ firstSeen: 0.125,
+ times: [0.125, 0.25, 0.375, 0.5, 0.625, 0.75],
+ bbox: { x: 500, y: 20, width: 300, height: 80 },
+ }),
+ ]);
+ expect(captureFindingCrops).toHaveBeenCalledWith(
+ PROJECT,
+ expect.objectContaining({ snapshots: true }),
+ [
+ {
+ filename: "finding-00-content_overlap.png",
+ time: 0.5,
+ bbox: { x: 500, y: 20, width: 300, height: 80 },
+ },
+ ],
+ );
+ });
+
+ it("retains all sampled times for a stationary frame failure", async () => {
+ const { report } = await runScenario(
+ fakeDriver({
+ getDuration: vi.fn(async () => 8),
+ collectGeometryCandidates: vi.fn(async (time: number) => [
+ geometryCandidate({
+ kind: "media",
+ tag: "img",
+ text: "img",
+ selector: "#stationary",
+ rect: fixtureRect(1920, 100, 130, 100),
+ overflow: { right: 130 },
+ time,
+ }),
+ ]),
+ }),
+ { contrast: false, samples: 1, frameCheck: { seek: [0.25, 0.75] } },
+ );
+ expect(report.layout.findings).toEqual([
+ expect.objectContaining({
+ code: "frame_out_of_frame",
+ selector: "#stationary",
+ times: [2, 6],
+ }),
+ ]);
+ });
+
+ it("keeps different rules on one element as separate findings", async () => {
+ const { report } = await runScenario(
+ fakeDriver({
+ collectLayout: vi.fn(async (time: number) => [
+ layoutIssue("error", { time, code: "clipped_text" }),
+ layoutIssue("error", { time, code: "text_box_overflow" }),
+ ]),
+ }),
+ { contrast: false, samples: 2, at: [0.5, 1.5] },
+ );
+ expect(report.layout.findings.map(({ code, times }) => ({ code, times }))).toEqual([
+ { code: "clipped_text", times: [0.5, 1.5] },
+ { code: "text_box_overflow", times: [0.5, 1.5] },
+ ]);
+ });
+
+ it("retains per-sample layout observations when collapse is explicitly disabled", async () => {
+ const { report } = await runScenario(
+ fakeDriver({
+ collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
+ }),
+ { contrast: false, collapseStatic: false, samples: 2, at: [0.5, 1.5] },
+ );
+ expect(report.layout.findings.map(({ code, time }) => ({ code, time }))).toEqual([
+ { code: "clipped_text", time: 0.5 },
+ { code: "clipped_text", time: 1.5 },
+ ]);
+ });
+
+ it("reports held low contrast once with every occurrence time in JSON and terminal output", async () => {
+ const times = [0.111, 0.556, 1, 1.444, 1.889];
+ const { report } = await runScenario(
+ fakeDriver({
+ getDuration: vi.fn(async () => 2),
+ collectContrast: vi.fn(async (time: number) => ({
+ entries: [contrastEntry({ time, selector: "#low", ratio: time === 1 ? 1.2 : 2.5 })],
+ pngBase64: PNG_BASE64,
+ })),
+ }),
+ { samples: 5, at: times },
+ );
+ expect(report.contrast.findings).toEqual([
+ expect.objectContaining({
+ selector: "#low",
+ severity: "error",
+ times,
+ time: 1,
+ ratio: 1.2,
+ }),
+ ]);
+ expect(report.contrast.errorCount).toBe(1);
+ expect(report.contrast.checked).toBe(5);
+ expect(checkExitCode(report)).toBe(1);
+ const command = createCheckCommand({
+ resolveProject: () => PROJECT,
+ runPipeline: vi.fn(async () => report),
+ withMeta: (value) => value,
+ });
+ const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+ await runCommand(command, { rawArgs: [] });
+ const output = log.mock.calls.map(([line]) => String(line)).join("\n");
+ expect(output.match(/#low/g)).toHaveLength(1);
+ expect(output).toContain("t=0.111, 0.556, 1, 1.444, 1.889s");
+ log.mockClear();
+ await runCommand(command, { rawArgs: ["--json"] });
+ expect(JSON.parse(String(log.mock.calls[0]?.[0])).contrast.findings).toEqual(
+ report.contrast.findings,
+ );
+ });
+
+ it("keeps same-selector contrast failures in separate source files and grades each independently", async () => {
+ const { report } = await runScenario(
+ fakeDriver({
+ collectContrast: vi.fn(async (time: number) => ({
+ entries: [
+ contrastEntry({
+ time,
+ selector: "#low",
+ sourceFile: time < 1 ? "index.html" : "compositions/scene.html",
+ }),
+ ],
+ pngBase64: PNG_BASE64,
+ })),
+ }),
+ { samples: 2, at: [0.5, 1.5] },
+ );
+ expect(report.contrast.findings).toEqual([
+ expect.objectContaining({ sourceFile: "index.html", severity: "warning", times: [0.5] }),
+ expect.objectContaining({
+ sourceFile: "compositions/scene.html",
+ severity: "warning",
+ times: [1.5],
+ }),
+ ]);
+ });
+
+ it("keeps same-selector layout findings from separate source files", async () => {
+ const { report } = await runScenario(
+ fakeDriver({
+ collectLayout: vi.fn(async (time: number) => [
+ {
+ ...layoutIssue("error", { time }),
+ sourceFile: time < 1 ? "index.html" : "compositions/scene.html",
+ },
+ ]),
+ }),
+ { contrast: false, samples: 2, at: [0.5, 1.5] },
+ );
+ expect(report.layout.findings).toEqual([
+ expect.objectContaining({ sourceFile: "index.html", times: [0.5] }),
+ expect.objectContaining({ sourceFile: "compositions/scene.html", times: [1.5] }),
+ ]);
+ });
+
+ it("reports an element's repeated layout rule once even when its text changes", async () => {
+ const { report } = await runScenario(
+ fakeDriver({
+ collectLayout: vi.fn(async (time: number) => [
+ {
+ ...layoutIssue("error", { time }),
+ text: time < 1 ? "First" : "Changed",
+ },
+ ]),
+ }),
+ { contrast: false, samples: 2, at: [0.5, 1.5] },
+ );
+ expect(report.layout.findings).toHaveLength(1);
+ expect(report.layout.findings[0]).toMatchObject({ code: "clipped_text", times: [0.5, 1.5] });
+ });
+});
+
describe("contrast persistence", () => {
it("demotes a single-sample contrast failure to warning but gates held failures", async () => {
const driver = fakeDriver({
diff --git a/packages/cli/src/commands/check.ts b/packages/cli/src/commands/check.ts
index 787b221c5d..354b01b67e 100644
--- a/packages/cli/src/commands/check.ts
+++ b/packages/cli/src/commands/check.ts
@@ -1,3 +1,4 @@
+import { formatFindingTimes } from "../utils/checkFindings.js";
import { defineCommand, parseArgs } from "citty";
import type { ArgsDef } from "citty";
import type { Example } from "./_examples.js";
@@ -467,7 +468,7 @@ function printContrastSection(report: CheckReport): void {
}
for (const finding of section.findings) {
console.log(
- ` ${c.error("✗")} ${finding.selector} ${finding.ratio}:1 (need ${finding.requiredRatio}:1, t=${finding.time}s)`,
+ ` ${c.error("✗")} ${finding.selector} ${finding.ratio}:1 (need ${finding.requiredRatio}:1, ${formatFindingTimes(finding)})`,
);
console.log(` ${c.dim(`Try ${finding.suggestedColor}; source ${finding.sourceFile}`)}`);
}
@@ -492,7 +493,7 @@ function printSnapshotSection(report: CheckReport): void {
}
function printFinding(finding: CheckFinding): void {
- const where = `${finding.sourceFile} ${finding.selector} t=${finding.time}s`;
+ const where = `${finding.sourceFile} ${finding.selector} ${formatFindingTimes(finding)}`;
console.log(` ${findingIcon(finding)} ${finding.code}: ${finding.message}`);
console.log(` ${c.dim(where)}`);
if (finding.fixHint) console.log(` ${c.dim(`Fix: ${finding.fixHint}`)}`);
diff --git a/packages/cli/src/commands/layout-audit.browser.js b/packages/cli/src/commands/layout-audit.browser.js
index eec189178b..e082e557f2 100644
--- a/packages/cli/src/commands/layout-audit.browser.js
+++ b/packages/cli/src/commands/layout-audit.browser.js
@@ -454,7 +454,7 @@
const overflow = {};
if (overflowX > tolerance) overflow.right = round(overflowX);
if (overflowY > tolerance) overflow.bottom = round(overflowY);
- const selector = selectorFor(element);
+ const selector = uniqueSelectorFor(element);
const text = textContentFor(element);
const rect = toRect(element.getBoundingClientRect());
const fontSize = parsePx(style.fontSize);
@@ -537,7 +537,7 @@
const textRect = unionRects(lineRects);
if (!textRect) return [];
const text = textContentFor(element, true);
- const selector = selectorFor(element);
+ const selector = uniqueSelectorFor(element);
const issues = [];
const container = nearestConstraint(element, root, rootRect);
@@ -568,7 +568,7 @@
severity: "error",
time,
selector,
- containerSelector: selectorFor(container),
+ containerSelector: uniqueSelectorFor(container),
text,
message: "Text extends outside its nearest visual/container box.",
rect: visibleTextRect,
@@ -591,7 +591,7 @@
severity: "info",
time,
selector,
- containerSelector: selectorFor(root),
+ containerSelector: uniqueSelectorFor(root),
text,
message: "Text extends outside the composition canvas.",
rect: textRect,
@@ -644,8 +644,8 @@
code: "container_overflow",
severity: "warning",
time,
- selector: selectorFor(child),
- containerSelector: selectorFor(container),
+ selector: uniqueSelectorFor(child),
+ containerSelector: uniqueSelectorFor(container),
message: checksEveryChild
? "Element extends outside a clipping layout container."
: "Nowrap text is wider than its container.",
@@ -1198,7 +1198,7 @@
code: "text_not_painted",
severity: "error",
time,
- selector: selectorFor(element),
+ selector: uniqueSelectorFor(element),
text,
message:
"Text paints with an effectively transparent fill (-webkit-text-fill-color / color), so its glyphs are invisible.",
@@ -1242,8 +1242,8 @@
code: "escaped_container",
severity: "warning",
time,
- selector: selectorFor(element),
- containerSelector: selectorFor(parent),
+ selector: uniqueSelectorFor(element),
+ containerSelector: uniqueSelectorFor(parent),
text: textContentFor(element),
message:
"Positioned element renders far outside its offset parent — its coordinates were likely computed in a different frame (canvas/viewport pixels).",
@@ -1319,8 +1319,8 @@
code: "panel_out_of_canvas",
severity: rectArea(rect) >= rootArea * PANEL_HERO_AREA_FRACTION ? "warning" : "info",
time,
- selector: selectorFor(element),
- containerSelector: selectorFor(root),
+ selector: uniqueSelectorFor(element),
+ containerSelector: uniqueSelectorFor(root),
text: textContentFor(element).slice(0, 48),
message: "Painted panel extends outside the composition canvas.",
rect,
@@ -1436,8 +1436,8 @@
code: "canvas_content_at_edge",
severity: "warning",
time,
- selector: selectorFor(canvas),
- containerSelector: selectorFor(root),
+ selector: uniqueSelectorFor(canvas),
+ containerSelector: uniqueSelectorFor(root),
message: `Canvas content touches the frame edge (${sides.join(", ")}).`,
rect,
containerRect: rootRect,
@@ -1605,8 +1605,8 @@
code: "connector_detached",
severity: "warning",
time,
- selector: selectorFor(path),
- containerSelector: selectorFor(svg),
+ selector: uniqueSelectorFor(path),
+ containerSelector: uniqueSelectorFor(svg),
message: pasteBug
? `Connector path endpoints render ${gap}px from the nearest anchorable element, but the path's user-space coordinates would attach if read as screen pixels — screen/viewport numbers were likely written into SVG \`d\` without inverting the CTM.`
: `Connector path endpoints render ${gap}px from the nearest anchorable element — a marked shaft that meets no node.`,
@@ -1743,9 +1743,9 @@
code: "connector_orphan",
severity: "warning",
time,
- selector: selectorFor(path),
- containerSelector: selectorFor(svg),
- message: `Connector shaft is visible while ${dark.length === 2 ? "both endpoints are" : `its endpoint ${selectorFor(dark[0].element)} is`} not on stage.`,
+ selector: uniqueSelectorFor(path),
+ containerSelector: uniqueSelectorFor(svg),
+ message: `Connector shaft is visible while ${dark.length === 2 ? "both endpoints are" : `its endpoint ${uniqueSelectorFor(dark[0].element)} is`} not on stage.`,
rect: toRect({
left: Math.min(rendered.start.x, rendered.end.x),
top: Math.min(rendered.start.y, rendered.end.y),
@@ -1925,7 +1925,7 @@
const box = element.getBoundingClientRect();
if (box.width * box.height <= 400) continue;
samples.push({
- selector: selectorFor(element),
+ selector: uniqueSelectorFor(element),
cx: round(box.left + box.width / 2),
cy: round(box.top + box.height / 2),
w: round(box.width),
@@ -2113,7 +2113,7 @@
hubCache.set(svg, hub);
}
samples.push({
- selector: selectorFor(element),
+ selector: uniqueSelectorFor(element),
ax: round(a.x),
ay: round(a.y),
bx: round(b.x),
diff --git a/packages/cli/src/commands/layout-audit.browser.test.ts b/packages/cli/src/commands/layout-audit.browser.test.ts
index 9c05c7fb34..082bf7d13e 100644
--- a/packages/cli/src/commands/layout-audit.browser.test.ts
+++ b/packages/cli/src/commands/layout-audit.browser.test.ts
@@ -1298,6 +1298,26 @@ describe("layout-audit.browser coordinate-frame findings", () => {
n2: { backgroundColor: "rgb(30, 40, 50)" },
};
+ it("identifies two same-class detached connectors separately", () => {
+ document.body.innerHTML = foreignFrameDom
+ .replace('id="detached" ', "")
+ .replace(
+ 'id="anchored" class="connector-line" d="M 900 353 L 300 53"',
+ 'class="connector-line" d="M 970 570 L 370 270"',
+ );
+ installGeometry(foreignFrameRects, foreignFrameStyles);
+ installConnectorGeometry({ e: 80, f: 227 });
+ installAuditScript();
+ const issues = runAudit().filter((issue) => issue.code === "connector_detached");
+ expect(issues.map((issue) => issue.selector)).toEqual([
+ "#connector-svg > path:nth-of-type(1)",
+ "#connector-svg > path:nth-of-type(2)",
+ ]);
+ const paths = document.querySelectorAll("#connector-svg > path");
+ expect(document.querySelector(issues[0]!.selector)).toBe(paths[0]);
+ expect(document.querySelector(issues[1]!.selector)).toBe(paths[1]);
+ });
+
it("flags connector paths drawn in a foreign frame and passes anchored ones", () => {
document.body.innerHTML = foreignFrameDom;
installGeometry(foreignFrameRects, foreignFrameStyles);
diff --git a/packages/cli/src/utils/checkFindings.ts b/packages/cli/src/utils/checkFindings.ts
new file mode 100644
index 0000000000..fe45bedc59
--- /dev/null
+++ b/packages/cli/src/utils/checkFindings.ts
@@ -0,0 +1,41 @@
+import type { CheckFinding } from "./checkTypes.js";
+
+const SEVERITY = { info: 0, warning: 1, error: 2 } satisfies Record<
+ CheckFinding["severity"],
+ number
+>;
+
+/** Element identity is scoped to the source document, not the whole project. */
+export function findingElementKey(finding: Pick<CheckFinding, "sourceFile" | "selector">): string {
+ return JSON.stringify([finding.sourceFile, finding.selector]);
+}
+
+/** Group observations without changing their grading; retain one matching evidence anchor. */
+export function groupSampledFindings<T extends CheckFinding>(
+ findings: T[],
+ compareEvidence: (next: T, current: T) => number = () => 0,
+): (T & { times: number[] })[] {
+ const groups = new Map<string, { finding: T; times: Set<number> }>();
+ for (const finding of findings) {
+ const key = JSON.stringify([findingElementKey(finding), finding.code]);
+ const times = finding.times ?? [finding.time];
+ const group = groups.get(key);
+ if (!group) {
+ groups.set(key, { finding, times: new Set(times) });
+ continue;
+ }
+ for (const time of times) group.times.add(time);
+ const severity = SEVERITY[finding.severity] - SEVERITY[group.finding.severity];
+ if (severity > 0 || (severity === 0 && compareEvidence(finding, group.finding) > 0)) {
+ group.finding = finding;
+ }
+ }
+ return [...groups.values()].map(({ finding, times }) => ({
+ ...finding,
+ times: [...times].sort((a, b) => a - b),
+ }));
+}
+
+export function formatFindingTimes(finding: Pick<CheckFinding, "time" | "times">): string {
+ return `t=${(finding.times ?? [finding.time]).join(", ")}s`;
+}
diff --git a/packages/cli/src/utils/checkPipeline.ts b/packages/cli/src/utils/checkPipeline.ts
index d1b148dfdd..6e3585d557 100644
--- a/packages/cli/src/utils/checkPipeline.ts
+++ b/packages/cli/src/utils/checkPipeline.ts
@@ -1,3 +1,4 @@
+import { findingElementKey, groupSampledFindings } from "./checkFindings.js";
import { mkdirSync, writeFileSync } from "node:fs";
import { join, relative } from "node:path";
import { trackCheckReport, trackCommandFailure } from "../telemetry/events.js";
@@ -9,6 +10,7 @@ import {
buildLayoutSampleTimes,
buildTransitionSampleTimes,
collapseStaticLayoutIssues,
+ longestContiguousRunMs,
dedupeLayoutIssues,
limitLayoutIssues,
mergeSampleTimes,
@@ -226,11 +228,6 @@ interface GridSamples {
indicatorFrames: OffPivotFrame[];
}
-interface GeometrySeen {
- caption: Set<string>;
- frame: Set<string>;
-}
-
function geometryRequest(
time: number,
grid: SampleGrid,
@@ -283,7 +280,7 @@ function captionFinding(
options: CheckOptions,
canvas: Canvas,
time: number,
-): { key: string; issue: AnchoredLayoutIssue } | null {
+): AnchoredLayoutIssue | null {
const zone = options.captionZone;
if (!zone || candidate.kind !== "text" || !candidateIsSized(candidate, canvas)) return null;
// Backstop for mocks/non-browser sources; browser already strips via closest() (own attrs only here).
@@ -293,16 +290,13 @@ function captionFinding(
const text = candidate.text.slice(0, 48);
const pctFromBottom = Math.round(((canvas.height - cy) / canvas.height) * 100);
return {
- key: `${candidate.tag}|${text}`,
- issue: {
- ...geometryIssueAnchor(candidate, time),
- code: "caption_zone_collision",
- severity: zone.severity === "error" ? "error" : "warning",
- text,
- message: `<${candidate.tag}> "${text}" overlaps the reserved caption band (~${pctFromBottom}% up from the bottom).`,
- fixHint:
- "Keep main content outside the configured caption band, or mark intentional lower-third copy with data-layout-allow-caption-zone.",
- },
+ ...geometryIssueAnchor(candidate, time),
+ code: "caption_zone_collision",
+ severity: zone.severity === "error" ? "error" : "warning",
+ text,
+ message: `<${candidate.tag}> "${text}" overlaps the reserved caption band (~${pctFromBottom}% up from the bottom).`,
+ fixHint:
+ "Keep main content outside the configured caption band, or mark intentional lower-third copy with data-layout-allow-caption-zone.",
};
}
@@ -331,7 +325,7 @@ function frameFinding(
options: CheckOptions,
canvas: Canvas,
time: number,
-): { key: string; issue: AnchoredLayoutIssue } | null {
+): AnchoredLayoutIssue | null {
if (!options.frameCheck || candidate.kind !== "media" || !candidateIsSized(candidate, canvas)) {
return null;
}
@@ -342,36 +336,22 @@ function frameFinding(
if (maxOverflow(candidate) < floor) return null;
const text = candidate.text.slice(0, 48);
return {
- key: `${candidate.tag}|${text}|${Math.round(candidate.rect.left)},${Math.round(candidate.rect.top)}`,
- issue: {
- ...geometryIssueAnchor(candidate, time),
- code: "frame_out_of_frame",
- severity: options.frameCheck.severity === "error" ? "error" : "warning",
- text,
- overflow: candidate.overflow,
- message: overflowMessage(candidate),
- fixHint: "Keep media within the composition frame's safe area.",
- },
+ ...geometryIssueAnchor(candidate, time),
+ code: "frame_out_of_frame",
+ severity: options.frameCheck.severity === "error" ? "error" : "warning",
+ text,
+ overflow: candidate.overflow,
+ message: overflowMessage(candidate),
+ fixHint: "Keep media within the composition frame's safe area.",
};
}
-function appendGeometryFinding(
- result: { key: string; issue: AnchoredLayoutIssue } | null,
- seen: Set<string>,
- issues: AnchoredLayoutIssue[],
-): void {
- if (!result || seen.has(result.key)) return;
- seen.add(result.key);
- issues.push(result.issue);
-}
-
async function collectGeometryAt(
driver: CheckAuditDriver,
options: CheckOptions,
grid: SampleGrid,
canvas: Canvas,
time: number,
- seen: GeometrySeen,
): Promise<AnchoredLayoutIssue[]> {
const request = geometryRequest(time, grid, options);
if (!request) return [];
@@ -379,10 +359,12 @@ async function collectGeometryAt(
const issues: AnchoredLayoutIssue[] = [];
for (const candidate of candidates) {
if (request.text) {
- appendGeometryFinding(captionFinding(candidate, options, canvas, time), seen.caption, issues);
+ const finding = captionFinding(candidate, options, canvas, time);
+ if (finding) issues.push(finding);
}
if (request.media) {
- appendGeometryFinding(frameFinding(candidate, options, canvas, time), seen.frame, issues);
+ const finding = frameFinding(candidate, options, canvas, time);
+ if (finding) issues.push(finding);
}
}
return issues;
@@ -399,7 +381,6 @@ async function collectGridSamples(
const contrastSet = new Set(grid.contrastSamples);
const geometryEnabled = grid.captionSamples.length > 0 || grid.frameSamples.length > 0;
const canvas = geometryEnabled ? await driver.getCanvas() : null;
- const geometrySeen: GeometrySeen = { caption: new Set(), frame: new Set() };
const collected: GridSamples = {
layoutIssues: [],
motionFrames: [],
@@ -428,14 +409,7 @@ async function collectGridSamples(
collected.indicatorFrames.push(await driver.collectOffPivotRotationSample(time));
}
if (canvas) {
- const geometryIssues = await collectGeometryAt(
- driver,
- options,
- grid,
- canvas,
- time,
- geometrySeen,
- );
+ const geometryIssues = await collectGeometryAt(driver, options, grid, canvas, time);
collected.layoutIssues.push(...geometryIssues);
issuesAtTime.push(...geometryIssues);
}
@@ -1325,13 +1299,13 @@ function contrastFailureHeld(
const failureSamples = new Map<string, Set<number>>();
for (const entry of entries) {
if (entry.wcagAA) continue;
- const key = `${entry.selector}|${entry.text}`;
+ const key = findingElementKey(entry);
const times = failureSamples.get(key) ?? new Set<number>();
times.add(entry.time);
failureSamples.set(key, times);
}
return (entry) =>
- sampledTimes < 2 || (failureSamples.get(`${entry.selector}|${entry.text}`)?.size ?? 0) >= 2;
+ sampledTimes < 2 || (failureSamples.get(findingElementKey(entry))?.size ?? 0) >= 2;
}
function buildContrastResults(entries: ContrastAuditEntry[]): {
@@ -1366,7 +1340,13 @@ function buildContrastResults(entries: ContrastAuditEntry[]): {
time: entry.time,
});
}
- return { findings, passed };
+ return {
+ findings: groupSampledFindings(
+ findings,
+ (next, current) => current.ratio / current.requiredRatio - next.ratio / next.requiredRatio,
+ ),
+ passed,
+ };
}
function suggestedColor(fg: string, bg: string, requiredRatio: number): string {
@@ -1508,7 +1488,18 @@ function shapeLayoutFindings(
const all = options.collapseStatic
? collapseStaticLayoutIssues(deduped, totalSampleCount)
: deduped;
- const limited = limitLayoutIssues(all, options.maxIssues);
+ const anchored = all.map(ensureAnchoredLayoutIssue);
+ let grouped = anchored;
+ if (options.collapseStatic) {
+ grouped = groupSampledFindings(anchored).map((finding) => ({
+ ...finding,
+ firstSeen: finding.times[0] ?? finding.time,
+ lastSeen: finding.times.at(-1) ?? finding.time,
+ occurrences: finding.times.length,
+ heldMs: longestContiguousRunMs(finding.times),
+ }));
+ }
+ const limited = limitLayoutIssues(grouped, options.maxIssues);
return {
findings: limited.issues.map(ensureAnchoredLayoutIssue),
totalIssueCount: limited.totalIssueCount,
diff --git a/packages/cli/src/utils/checkTypes.ts b/packages/cli/src/utils/checkTypes.ts
index bc61a61912..394fb2f12d 100644
--- a/packages/cli/src/utils/checkTypes.ts
+++ b/packages/cli/src/utils/checkTypes.ts
@@ -63,6 +63,7 @@ export interface CheckAnchor {
sourceFile: string;
bbox: CheckBbox;
time: number;
+ times?: number[];
}
export interface CheckFinding extends CheckAnchor {
diff --git a/packages/cli/src/utils/layoutAudit.ts b/packages/cli/src/utils/layoutAudit.ts
index 56fbc6aee5..0626c71eac 100644
--- a/packages/cli/src/utils/layoutAudit.ts
+++ b/packages/cli/src/utils/layoutAudit.ts
@@ -1,3 +1,4 @@
+import { formatFindingTimes } from "./checkFindings.js";
export interface LayoutRect {
left: number;
top: number;
@@ -48,6 +49,7 @@ export interface LayoutIssue {
code: LayoutIssueCode;
severity: LayoutIssueSeverity;
time: number;
+ times?: number[];
firstSeen?: number;
lastSeen?: number;
occurrences?: number;
@@ -141,10 +143,12 @@ export function summarizeLayoutIssues(issues: LayoutIssue[]): LayoutSummary {
}
export function formatLayoutIssue(issue: LayoutIssue): string {
- const timeLabel =
- issue.occurrences && issue.occurrences > 1
- ? `t=${formatNumber(issue.firstSeen ?? issue.time)}-${formatNumber(issue.lastSeen ?? issue.time)}s (${issue.occurrences} samples)`
- : `t=${formatNumber(issue.time)}s`;
+ let timeLabel = `t=${formatNumber(issue.time)}s`;
+ if (issue.times) {
+ timeLabel = formatFindingTimes(issue);
+ } else if (issue.occurrences && issue.occurrences > 1) {
+ timeLabel = `t=${formatNumber(issue.firstSeen ?? issue.time)}-${formatNumber(issue.lastSeen ?? issue.time)}s (${issue.occurrences} samples)`;
+ }
const parts = [
timeLabel,
issue.code,
@@ -164,6 +168,7 @@ export function dedupeLayoutIssues(issues: LayoutIssue[]): LayoutIssue[] {
for (const issue of issues) {
const key = [
+ Reflect.get(issue, "sourceFile") ?? "",
issue.code,
issue.severity,
issue.time.toFixed(3),
@@ -258,18 +263,18 @@ export function collapseStaticLayoutIssues(
applyPersistenceTier(
{
...issue,
- time: firstSeen,
firstSeen,
lastSeen,
occurrences,
heldMs: longestContiguousRunMs(times),
+ times: [...new Set(times)].sort((a, b) => a - b),
},
multiSampleRun,
),
);
}
-function longestContiguousRunMs(times: number[]): number {
+export function longestContiguousRunMs(times: number[]): number {
const sorted = [...new Set(times)].sort((a, b) => a - b);
const first = sorted[0];
const last = sorted.at(-1);
@@ -375,6 +380,7 @@ function severityRank(severity: LayoutIssueSeverity): number {
function staticIssueKey(issue: LayoutIssue): string {
return [
+ Reflect.get(issue, "sourceFile") ?? "",
issue.code,
issue.severity,
issue.selector,