mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* test(cli): error boxes and diff's failure line print control characters as escapes * fix(cli): error boxes and command failure lines print control characters as visible escapes * style(cli): format the escaped error lines
916 lines
32 KiB
TypeScript
916 lines
32 KiB
TypeScript
import { terminalText } from "@hyperframes/core";
|
||
import { captureArtifactRevision } from "../utils/artifactCapture.js";
|
||
import { pngDimensions } from "../utils/pngDimensions.js";
|
||
import { randomUUID } from "node:crypto";
|
||
import { writeFileSync } from "node:fs";
|
||
import { dirname, join, resolve } from "node:path";
|
||
import {
|
||
recordArtifacts,
|
||
type ArtifactCapture,
|
||
type ArtifactInput,
|
||
type ArtifactRecord,
|
||
} from "@hyperframes/studio-server/history";
|
||
import { formatFindingTimes } from "../utils/checkFindings.js";
|
||
import { withProjectLock } from "../utils/projectLock.js";
|
||
import { readToolContext, reportArtifacts, type ToolContext } from "../utils/toolContext.js";
|
||
import { parseArgs } from "citty";
|
||
import { defineCommand } from "../utils/defineCommand.js";
|
||
import type { ArgsDef } from "citty";
|
||
import type { Example } from "./_examples.js";
|
||
import { parseAt } from "./layout.js";
|
||
import { c } from "../ui/colors.js";
|
||
import { registerBrowserSessionCleanup } from "../browser/launch.js";
|
||
import { normalizeErrorMessage } from "../utils/errorMessage.js";
|
||
import { CliUsageError, failUsage, setCommandExitCode } from "../utils/commandResult.js";
|
||
import { swallowedFlagUsageError } from "../utils/reject-unknown-flags.js";
|
||
import { formatLayoutIssue } from "../utils/layoutAudit.js";
|
||
import { resolveProject, type ProjectDir } from "../utils/project.js";
|
||
import { withMeta } from "../utils/updateCheck.js";
|
||
import {
|
||
DEFAULT_CHECK_OPTIONS,
|
||
checkExitCode,
|
||
leavesNothingToLoad,
|
||
prelaunchBrowserForNextCheck,
|
||
runCheckPipeline,
|
||
selectFindingCropRequests,
|
||
type CheckFinding,
|
||
type CheckOptions,
|
||
type CheckReport,
|
||
type CheckSection,
|
||
} from "../utils/checkPipeline.js";
|
||
import type { CaptionZoneOptions, FrameCheckOptions, LayoutOptions } from "../utils/checkTypes.js";
|
||
import { resolveLocalBrowserGpuMode } from "../browser/gpuPolicy.js";
|
||
import { SOCIAL_SAFE_AREA_NAMES } from "@hyperframes/core/safe-areas";
|
||
import type { SafeZone } from "../utils/safeZones.js";
|
||
import { preResolveHostileMediaProxies, type PreparedMediaFile } from "../utils/checkBrowser.js";
|
||
import { parseTimeoutMs } from "../utils/timeoutArg.js";
|
||
import { failureMessage, jsonFailure } from "../utils/jsonError.js";
|
||
import { recordLastCheck } from "../telemetry/config.js";
|
||
import { failureCodes } from "../utils/checkFailureCodes.js";
|
||
import {
|
||
browserIdentity,
|
||
checkCacheKey,
|
||
checkCacheable,
|
||
readCachedPass,
|
||
storePass,
|
||
} from "../utils/checkCache.js";
|
||
import { recordFolder } from "../utils/projectRecords.js";
|
||
import { VERSION } from "../version.js";
|
||
|
||
export const examples: Example[] = [
|
||
["Run the full verification gate", "hyperframes check"],
|
||
["Output one agent-readable envelope", "hyperframes check --json"],
|
||
["Persist the five audited contrast frames", "hyperframes check --snapshots"],
|
||
["Also fail on warnings", "hyperframes check --strict"],
|
||
["Make only the browser-playable video copies, then exit", "hyperframes check --prepare-media"],
|
||
];
|
||
|
||
type SavedCheck = Pick<ArtifactRecord, "id" | "revision" | "report" | "attribution">;
|
||
type SavedCheckReport = CheckReport & { saved?: SavedCheck };
|
||
|
||
export interface CheckCommandDependencies {
|
||
resolveProject(dir: string | undefined): ProjectDir;
|
||
runPipeline(project: ProjectDir, options: CheckOptions): Promise<SavedCheckReport>;
|
||
prepareMedia(project: ProjectDir, options: CheckOptions): Promise<PreparedMediaFile[]>;
|
||
withMeta(value: object): object;
|
||
browserIdentity?(): Promise<string | undefined>;
|
||
}
|
||
|
||
const DEFAULT_COMMAND_DEPENDENCIES: CheckCommandDependencies = {
|
||
resolveProject,
|
||
async runPipeline(project, options) {
|
||
const capturing = captureArtifactRevision(project.dir).catch(warnNotRecorded);
|
||
const id = randomUUID();
|
||
console.error(
|
||
`[hyperframes] check: the report is saved to ${checkReportFile(project.dir, id)} when the check ends, unless a warning says it could not be saved`,
|
||
);
|
||
const report = await runCheckPipeline(project, options);
|
||
const images = (files: readonly string[]) => files.map((file) => resolve(project.dir, file));
|
||
reportArtifacts("check", "frame", images(report.snapshots.files));
|
||
reportArtifacts("check", "finding", images(report.snapshots.findingFiles));
|
||
const capture = await capturing;
|
||
if (!capture) return report;
|
||
try {
|
||
return { ...report, saved: await saveCheckReport(project, options, report, capture, id) };
|
||
} catch (error) {
|
||
warnNotRecorded(error);
|
||
return report;
|
||
}
|
||
},
|
||
async prepareMedia(project, options) {
|
||
const { bundleWithLocalizedFonts } = await import("../utils/bundleWithLocalizedFonts.js");
|
||
const html = await bundleWithLocalizedFonts(project.dir);
|
||
return (await preResolveHostileMediaProxies(project.dir, html, options.autoProxy)).files;
|
||
},
|
||
withMeta,
|
||
};
|
||
|
||
function warnNotRecorded(error: unknown): undefined {
|
||
console.warn(`${c.warn("⚠")} Check report was not recorded: ${normalizeErrorMessage(error)}`);
|
||
return undefined;
|
||
}
|
||
|
||
export function checkReportFile(projectDir: string, id: string): string {
|
||
return join(projectDir, ".hyperframes", "artifacts", "checks", `${id}.json`);
|
||
}
|
||
|
||
function makeReportFolder(path: string, projectDir: string): void {
|
||
if (!recordFolder(projectDir, "artifacts/checks"))
|
||
throw new Error(
|
||
`${dirname(path)} is reached through a link or a file; remove it and run again`,
|
||
);
|
||
}
|
||
|
||
async function saveCheckReport(
|
||
project: ProjectDir,
|
||
options: CheckOptions,
|
||
report: CheckReport,
|
||
capture: ArtifactCapture,
|
||
id: string,
|
||
): Promise<SavedCheck> {
|
||
const path = checkReportFile(project.dir, id);
|
||
makeReportFolder(path, project.dir);
|
||
writeFileSync(path, JSON.stringify(report, null, 2) + "\n", { flag: "wx" });
|
||
const reportScope =
|
||
"scope" in report && typeof report.scope === "object" && report.scope !== null
|
||
? report.scope
|
||
: undefined;
|
||
const artifacts: ArtifactInput[] = [
|
||
{
|
||
kind: "check",
|
||
id,
|
||
scope: reportScope ? "scoped" : "project",
|
||
report: resolve(path),
|
||
metadata: {
|
||
ok: report.ok,
|
||
browserSkipped: report.browserSkipped,
|
||
scope: reportScope,
|
||
options,
|
||
},
|
||
},
|
||
];
|
||
for (const [index, image] of report.snapshots.files.entries()) {
|
||
artifacts.push({
|
||
kind: "snapshot",
|
||
id: `${id}-${index}`,
|
||
scope: "full",
|
||
image: resolve(project.dir, image),
|
||
time: report.snapshots.times[index],
|
||
metadata: {
|
||
checkId: id,
|
||
...pngDimensions(resolve(project.dir, image)),
|
||
},
|
||
});
|
||
}
|
||
const crops = selectFindingCropRequests(report);
|
||
for (const [index, image] of report.snapshots.findingFiles.entries()) {
|
||
const crop = crops.find((request) => image.endsWith(request.filename));
|
||
artifacts.push({
|
||
kind: "snapshot",
|
||
id: `${id}-crop-${index}`,
|
||
scope: "finding",
|
||
image: resolve(project.dir, image),
|
||
time: crop?.time,
|
||
metadata: {
|
||
checkId: id,
|
||
finding: crop,
|
||
...pngDimensions(resolve(project.dir, image)),
|
||
},
|
||
});
|
||
}
|
||
const [saved] = await recordArtifacts(project.dir, capture, artifacts);
|
||
if (!saved) throw new Error("no history record was written");
|
||
reportArtifacts("check", "check-report", [resolve(path)]);
|
||
return {
|
||
id: saved.id,
|
||
revision: saved.revision,
|
||
report: saved.report,
|
||
attribution: saved.attribution,
|
||
};
|
||
}
|
||
|
||
const CHECK_COMMAND_ARGS = {
|
||
dir: { type: "positional", description: "Project directory", required: false },
|
||
json: { type: "boolean", description: "Output agent-readable JSON", default: false },
|
||
"lint-verbose": {
|
||
type: "boolean",
|
||
description: "Accepted as render's spelling; check always prints every lint finding",
|
||
default: false,
|
||
},
|
||
samples: {
|
||
type: "string",
|
||
description: "Number of midpoint samples across the duration",
|
||
default: "9",
|
||
},
|
||
range: {
|
||
type: "string",
|
||
description:
|
||
"Runtime sample interval in global seconds: start,end. Static lint remains project-wide.",
|
||
},
|
||
components: {
|
||
type: "string",
|
||
description:
|
||
"CSS selector list: filter findings involving these components or descendants; preserve full-check status.",
|
||
},
|
||
at: {
|
||
type: "string",
|
||
description: "Comma-separated timestamps in seconds (e.g., --at 1.5,4,7.25)",
|
||
},
|
||
"at-transitions": {
|
||
type: "boolean",
|
||
description:
|
||
"Also sample at every tween start/end boundary (plus segment midpoints) to catch transient overlaps at transition seams",
|
||
default: false,
|
||
},
|
||
"max-transition-samples": {
|
||
type: "string",
|
||
description:
|
||
"Optional cap on transition-derived samples; when it truncates, the omitted count is reported (default: unlimited)",
|
||
},
|
||
"max-issues": {
|
||
type: "string",
|
||
description: "Maximum issues to print or return after static collapse",
|
||
default: "80",
|
||
},
|
||
"collapse-static": {
|
||
type: "boolean",
|
||
description: "Collapse repeated static issues across samples",
|
||
default: true,
|
||
},
|
||
tolerance: {
|
||
type: "string",
|
||
description: "Allowed pixel overflow before reporting an issue",
|
||
default: "2",
|
||
},
|
||
budget: {
|
||
type: "string",
|
||
description:
|
||
"Stop the whole check this long after it starts (ms, or 90s, 8m; at least 30s) and report what it found so far",
|
||
},
|
||
cache: {
|
||
type: "boolean",
|
||
description:
|
||
"Return the stored result when the project, options and CLI are unchanged since the last pass (pass --no-cache to always re-run)",
|
||
default: true,
|
||
},
|
||
timeout: {
|
||
type: "string",
|
||
description:
|
||
"Initial render-ready timeout in ms, or with a unit (45s, 2m); also sets the navigation minimum (10s floor, default: 45000, as snapshot and render)",
|
||
default: String(DEFAULT_CHECK_OPTIONS.timeout),
|
||
},
|
||
contrast: {
|
||
type: "boolean",
|
||
description: "Run the WCAG AA contrast pass (enabled by default)",
|
||
default: true,
|
||
},
|
||
craft: {
|
||
type: "boolean",
|
||
description:
|
||
"Run the craft pass (dead stretches, unread lines, silent films; enabled by default). --no-craft skips it, e.g. for a render preflight",
|
||
default: true,
|
||
},
|
||
strict: {
|
||
type: "boolean",
|
||
description: "Exit non-zero on warnings too",
|
||
default: false,
|
||
},
|
||
"prepare-media": {
|
||
type: "boolean",
|
||
description:
|
||
"Only make the browser-playable copies of videos Chrome cannot decode, then exit (no browser, no report). Stopped copies resume on the next run",
|
||
default: false,
|
||
},
|
||
proxy: {
|
||
type: "boolean",
|
||
description:
|
||
"Auto-transcode browser-hostile video codecs (default: hyperframes.json media.autoProxy, which defaults on)",
|
||
default: undefined,
|
||
},
|
||
"browser-gpu": {
|
||
type: "boolean",
|
||
description:
|
||
"Use hardware browser GPU capture; pass --no-browser-gpu for deterministic SwiftShader (default: auto-detect, PRODUCER_BROWSER_GPU_MODE overrides)",
|
||
default: undefined,
|
||
},
|
||
snapshots: {
|
||
type: "boolean",
|
||
description: "Save contrast-pass PNGs under .hyperframes/artifacts/snapshots/",
|
||
default: false,
|
||
},
|
||
"include-unmounted": {
|
||
type: "boolean",
|
||
description: "Also lint compositions/ files that index.html never mounts",
|
||
default: false,
|
||
},
|
||
"caption-zone": {
|
||
type: "string",
|
||
description:
|
||
'Caption band "x0=0;y0=.82;x1=1;y1=1[;severity=warning|error][;seek=.5,1]" (fractions 0-1; defaults: warning, seek=1)',
|
||
},
|
||
"safe-zone": {
|
||
type: "string",
|
||
description:
|
||
"Warn when text leaves a safe area: tiktok, reels or shorts on 9:16 (default: all three), standard (title-safe margins, any frame), or off",
|
||
},
|
||
"frame-check": {
|
||
type: "string",
|
||
description:
|
||
'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',
|
||
},
|
||
layout: {
|
||
type: "string",
|
||
description: 'Layout knobs: "proseCoverageFloor=0.05" (0–1; default 0.15).',
|
||
},
|
||
} satisfies ArgsDef;
|
||
|
||
export function createCheckCommand(
|
||
dependencies: CheckCommandDependencies = DEFAULT_COMMAND_DEPENDENCIES,
|
||
) {
|
||
return defineCommand({
|
||
meta: {
|
||
name: "check",
|
||
description:
|
||
"Run lint, runtime, layout, motion, and WCAG contrast verification in one browser session",
|
||
},
|
||
args: CHECK_COMMAND_ARGS,
|
||
async run({ rawArgs }) {
|
||
const args = parseArgs(rawArgs, CHECK_COMMAND_ARGS);
|
||
const asJson = args.json === true;
|
||
|
||
const reported = untilReported();
|
||
try {
|
||
const options = parseCheckOptions(args);
|
||
const project = dependencies.resolveProject(args.dir);
|
||
if (!asJson) {
|
||
console.log(`${c.accent("◆")} Checking ${c.accent(project.name)}`);
|
||
}
|
||
if (args["prepare-media"] === true) {
|
||
await runPrepareMedia(dependencies, project, options, asJson);
|
||
return;
|
||
}
|
||
recordLastCheck({ at: new Date().toISOString(), codes: {} });
|
||
const report = await checkOrReplay(dependencies, project, options);
|
||
recordLastCheck({
|
||
at: new Date().toISOString(),
|
||
exitCode: checkExitCode(report),
|
||
codes: failureCodes(report),
|
||
});
|
||
if (asJson) {
|
||
console.log(JSON.stringify(dependencies.withMeta(report), null, 2));
|
||
if (report.saved)
|
||
console.error(`[hyperframes] check: report saved to ${report.saved.report}`);
|
||
} else {
|
||
printHumanReport(report);
|
||
if (report.saved) {
|
||
console.log(`Report: ${report.saved.report}`);
|
||
console.log(
|
||
`Revision: ${report.saved.revision ?? "none"} (${report.saved.attribution})`,
|
||
);
|
||
}
|
||
}
|
||
setCommandExitCode(checkExitCode(report));
|
||
} catch (error) {
|
||
recordLastCheck({
|
||
at: new Date().toISOString(),
|
||
exitCode: 1,
|
||
codes: { [error instanceof CliUsageError ? error.code : "runtime_error"]: 1 },
|
||
});
|
||
reportCheckFailure(error, asJson, (value) => dependencies.withMeta(value));
|
||
} finally {
|
||
reported.done();
|
||
}
|
||
},
|
||
});
|
||
}
|
||
|
||
async function checkOrReplay(
|
||
dependencies: CheckCommandDependencies,
|
||
project: ProjectDir,
|
||
options: CheckOptions,
|
||
): Promise<SavedCheckReport> {
|
||
const identify = dependencies.browserIdentity ?? browserIdentity;
|
||
return withProjectLock(project.dir, "check", async () => {
|
||
const keyNow = async () =>
|
||
checkCacheable(options)
|
||
? checkCacheKey(project.dir, options, VERSION, await identify())
|
||
: undefined;
|
||
const key = await keyNow();
|
||
const cached = key ? readCachedPass(project.dir, key) : undefined;
|
||
if (cached) return cached;
|
||
const report = await dependencies.runPipeline(project, options);
|
||
const treeUnchangedByTheRun = key !== undefined && (await keyNow()) === key;
|
||
if (treeUnchangedByTheRun) storePass(project.dir, key, report);
|
||
return report;
|
||
});
|
||
}
|
||
|
||
function reportCheckFailure(
|
||
error: unknown,
|
||
asJson: boolean,
|
||
addMeta: (value: object) => object,
|
||
): void {
|
||
const message = failureMessage(error);
|
||
const usage = error instanceof CliUsageError;
|
||
if (asJson) {
|
||
const code = usage ? error.code : "runtime_error";
|
||
console.log(JSON.stringify(addMeta(jsonFailure(code, message)), null, 2));
|
||
} else {
|
||
console.error(`${c.error("✗")} Check failed: ${terminalText(message)}`);
|
||
}
|
||
if (usage) failUsage();
|
||
setCommandExitCode(1);
|
||
}
|
||
|
||
const REPORT_GRACE_MS = 5_000;
|
||
const MIN_BUDGET_MS = 30_000;
|
||
const BUDGET_REPORT_MS = 10_000;
|
||
|
||
function parseBudget(raw: unknown): CheckOptions["budget"] {
|
||
const ms = parseTimeoutMs(raw, 0, MIN_BUDGET_MS, console.error, "--budget");
|
||
return ms > 0 ? { ms, stopAt: Date.now() + ms - BUDGET_REPORT_MS } : undefined;
|
||
}
|
||
|
||
function untilReported(): { done: () => void } {
|
||
let done = (): void => undefined;
|
||
const printed = new Promise<void>((resolve) => {
|
||
done = resolve;
|
||
});
|
||
const forget = registerBrowserSessionCleanup(
|
||
() =>
|
||
new Promise<void>((resolve) => {
|
||
const timer = setTimeout(resolve, REPORT_GRACE_MS);
|
||
void printed.then(() => {
|
||
clearTimeout(timer);
|
||
resolve();
|
||
});
|
||
}),
|
||
);
|
||
return {
|
||
done: () => {
|
||
done();
|
||
forget();
|
||
},
|
||
};
|
||
}
|
||
|
||
async function runPrepareMedia(
|
||
dependencies: CheckCommandDependencies,
|
||
project: ProjectDir,
|
||
options: CheckOptions,
|
||
asJson: boolean,
|
||
): Promise<void> {
|
||
const files = await withProjectLock(project.dir, "check", () =>
|
||
dependencies.prepareMedia(project, options),
|
||
);
|
||
const failed = files.filter((file) => file.state === "failed");
|
||
if (asJson) {
|
||
console.log(
|
||
JSON.stringify(
|
||
dependencies.withMeta({
|
||
ok: failed.length === 0,
|
||
prepared: files,
|
||
total: files.length,
|
||
ready: files.length - failed.length,
|
||
failed: failed.length,
|
||
}),
|
||
null,
|
||
2,
|
||
),
|
||
);
|
||
} else {
|
||
const mark = failed.length === 0 ? c.success("✓") : c.error("✗");
|
||
console.log(
|
||
`${mark} Browser-playable copies: ${files.length - failed.length}/${files.length} ready`,
|
||
);
|
||
for (const file of failed) console.log(` ${file.file}: ${file.reason}`);
|
||
}
|
||
setCommandExitCode(failed.length === 0 ? 0 : 1);
|
||
}
|
||
|
||
function checkReview(): ToolContext["checkReview"] {
|
||
return readToolContext().checkReview;
|
||
}
|
||
|
||
function parseCheckOptions(args: Record<string, unknown>): CheckOptions {
|
||
const maxTransitionSamples = positiveInteger(args, "max-transition-samples", 0);
|
||
return {
|
||
samples: positiveInteger(args, "samples", DEFAULT_CHECK_OPTIONS.samples),
|
||
range: parseCheckRange(args.range),
|
||
components: typeof args.components === "string" ? [args.components] : undefined,
|
||
at: parseAt(args.at),
|
||
atTransitions: args["at-transitions"] === true,
|
||
maxTransitionSamples: maxTransitionSamples > 0 ? maxTransitionSamples : undefined,
|
||
maxIssues: positiveInteger(args, "max-issues", DEFAULT_CHECK_OPTIONS.maxIssues),
|
||
collapseStatic: args["collapse-static"] !== false,
|
||
tolerance: nonNegativeNumber(args, "tolerance", DEFAULT_CHECK_OPTIONS.tolerance),
|
||
timeout: parseTimeoutMs(args.timeout, DEFAULT_CHECK_OPTIONS.timeout, 500),
|
||
budget: parseBudget(args.budget),
|
||
cache: args.cache !== false,
|
||
contrast: args.contrast !== false,
|
||
craft: args.craft !== false,
|
||
...(checkReview()?.skipContrastInMotion ? { skipContrastInMotion: true } : {}),
|
||
strict: args.strict === true,
|
||
snapshots: args.snapshots === true,
|
||
...(checkReview()?.findingFrames ? { findingFrames: true } : {}),
|
||
...(checkReview()?.inspect ? { inspect: true } : {}),
|
||
captionZone: parseCaptionZone(args["caption-zone"]),
|
||
safeZones: parseSafeZone(args["safe-zone"]),
|
||
frameCheck: parseFrameCheck(args["frame-check"]),
|
||
layout: parseLayout(args.layout),
|
||
autoProxy: args.proxy as boolean | undefined,
|
||
browserGpuMode: resolveLocalBrowserGpuMode(args["browser-gpu"] as boolean | undefined),
|
||
includeUnmounted: args["include-unmounted"] === true,
|
||
};
|
||
}
|
||
|
||
export function prelaunchBrowserForCheck(rawArgs: string[]) {
|
||
const args = parseArgs(rawArgs, CHECK_COMMAND_ARGS);
|
||
return prelaunchBrowserForNextCheck(resolveProject(args.dir), parseCheckOptions(args));
|
||
}
|
||
|
||
export function parseCheckRange(value: unknown): [number, number] | undefined {
|
||
if (value === undefined) return undefined;
|
||
const parts = String(value).split(/[,:]/);
|
||
const start = Number(parts[0]),
|
||
end = Number(parts[1]);
|
||
if (
|
||
parts.length !== 2 ||
|
||
parts.some((p) => !p.trim()) ||
|
||
!Number.isFinite(start) ||
|
||
!Number.isFinite(end) ||
|
||
start < 0 ||
|
||
end <= start
|
||
)
|
||
throw new CliUsageError("Invalid --range: use non-negative start,end with end > start");
|
||
return [start, end];
|
||
}
|
||
|
||
const CAPTION_ZONE_FIELDS = new Set(["x0", "y0", "x1", "y1", "severity", "seek"]);
|
||
|
||
const FRAME_CHECK_FIELDS = new Set(["severity", "seek", "tol"]);
|
||
|
||
const LAYOUT_FIELDS = new Set(["proseCoverageFloor"]);
|
||
|
||
// Mirrors --caption-zone's spec grammar so the EF bridge's severity/seek/tol
|
||
// options survive the migration instead of being silently dropped by a
|
||
// boolean flag (bare --frame-check keeps today's defaults).
|
||
export function parseFrameCheck(value: unknown): FrameCheckOptions | undefined {
|
||
if (value === undefined || value === null || value === false) return undefined;
|
||
if (value === true || value === "") return {};
|
||
if (typeof value !== "string") throw frameCheckError();
|
||
if (value.startsWith("-")) throw swallowedFlagUsageError("frame-check", value);
|
||
const fields = parseFrameCheckFields(value);
|
||
const severity = captionSeverity(fields.get("severity"), frameCheckError);
|
||
const seek = captionSeeks(fields.get("seek"), frameCheckError);
|
||
const tol = parseFrameCheckTolerance(fields.get("tol"));
|
||
return {
|
||
...(severity ? { severity } : {}),
|
||
...(seek ? { seek } : {}),
|
||
...(tol !== undefined ? { tol } : {}),
|
||
};
|
||
}
|
||
|
||
function parseFrameCheckFields(value: string): Map<string, string> {
|
||
const fields = new Map<string, string>();
|
||
for (const part of value.split(";")) {
|
||
const { key, entry } = parseCaptionField(part, frameCheckError);
|
||
if (!FRAME_CHECK_FIELDS.has(key) || fields.has(key)) throw frameCheckError();
|
||
fields.set(key, entry);
|
||
}
|
||
return fields;
|
||
}
|
||
|
||
function parseFrameCheckTolerance(raw: string | undefined): number | undefined {
|
||
if (raw === undefined) return undefined;
|
||
const tol = parseNumberStrict(raw);
|
||
if (tol === null || tol < 0) throw frameCheckError();
|
||
return tol;
|
||
}
|
||
|
||
function frameCheckError(): Error {
|
||
return new CliUsageError(
|
||
'Invalid --frame-check: use bare --frame-check or "severity=warning|error;seek=.25,.75;tol=4" (all fields optional)',
|
||
);
|
||
}
|
||
|
||
/** Parse `--layout "proseCoverageFloor=0.05"` (semicolon-separated key=value, like caption-zone). */
|
||
export function parseLayout(value: unknown): LayoutOptions | undefined {
|
||
if (value === undefined || value === null || value === false) return undefined;
|
||
if (value === true || value === "") throw layoutError();
|
||
if (typeof value !== "string") throw layoutError();
|
||
const fields = parseLayoutFields(value);
|
||
const proseCoverageFloor = parseProseCoverageFloor(fields.get("proseCoverageFloor"));
|
||
if (proseCoverageFloor === undefined) throw layoutError();
|
||
return { proseCoverageFloor };
|
||
}
|
||
|
||
function parseLayoutFields(value: string): Map<string, string> {
|
||
const fields = new Map<string, string>();
|
||
for (const part of value.split(";")) {
|
||
const trimmed = part.trim();
|
||
if (!trimmed) continue;
|
||
const separator = trimmed.indexOf("=");
|
||
if (separator <= 0) throw layoutError();
|
||
const key = trimmed.slice(0, separator).trim();
|
||
const entry = trimmed.slice(separator + 1).trim();
|
||
if (!LAYOUT_FIELDS.has(key) || fields.has(key)) throw layoutError();
|
||
fields.set(key, entry);
|
||
}
|
||
return fields;
|
||
}
|
||
|
||
function parseProseCoverageFloor(raw: string | undefined): number | undefined {
|
||
if (raw === undefined) return undefined;
|
||
const floor = parseNumberStrict(raw);
|
||
if (floor === null || floor < 0 || floor > 1) throw layoutError();
|
||
return floor;
|
||
}
|
||
|
||
function layoutError(): Error {
|
||
return new CliUsageError(
|
||
'Invalid --layout: use "proseCoverageFloor=0.05" with a fraction from 0 to 1 (inclusive)',
|
||
);
|
||
}
|
||
|
||
/** Reject trailing garbage that Number.parseFloat would silently accept (`4px`, `0.05abc`). */
|
||
function parseNumberStrict(raw: string): number | null {
|
||
if (raw === "") return null;
|
||
const value = Number(raw);
|
||
return Number.isFinite(value) ? value : null;
|
||
}
|
||
|
||
export function parseSafeZone(value: unknown): SafeZone[] {
|
||
if (value === undefined) return [...SOCIAL_SAFE_AREA_NAMES];
|
||
if (value === "off") return [];
|
||
const zone = [...SOCIAL_SAFE_AREA_NAMES, "standard" as const].find((name) => name === value);
|
||
if (!zone)
|
||
throw new CliUsageError("Invalid --safe-zone; use tiktok, reels, shorts, standard or off.");
|
||
return [zone];
|
||
}
|
||
|
||
function parseCaptionZone(value: unknown): CaptionZoneOptions | undefined {
|
||
if (value === undefined || value === null) return undefined;
|
||
const fields = parseCaptionFields(captionZoneString(value));
|
||
const { x0, y0, x1, y1 } = parseCaptionBounds(fields);
|
||
const severity = captionSeverity(fields.get("severity"));
|
||
const seek = captionSeeks(fields.get("seek"));
|
||
return {
|
||
x0,
|
||
y0,
|
||
x1,
|
||
y1,
|
||
...(severity ? { severity } : {}),
|
||
...(seek ? { seek } : {}),
|
||
};
|
||
}
|
||
|
||
function captionZoneString(value: unknown): string {
|
||
if (typeof value !== "string" || value.trim() === "") throw captionZoneError();
|
||
return value;
|
||
}
|
||
|
||
function parseCaptionFields(value: string): Map<string, string> {
|
||
const fields = new Map<string, string>();
|
||
for (const part of value.split(";")) {
|
||
const { key, entry } = parseCaptionField(part);
|
||
if (!CAPTION_ZONE_FIELDS.has(key) || fields.has(key)) throw captionZoneError();
|
||
fields.set(key, entry);
|
||
}
|
||
return fields;
|
||
}
|
||
|
||
function parseCaptionField(
|
||
part: string,
|
||
errorFactory: () => Error = captionZoneError,
|
||
): { key: string; entry: string } {
|
||
const separator = part.indexOf("=");
|
||
if (separator <= 0) throw errorFactory();
|
||
return {
|
||
key: part.slice(0, separator).trim(),
|
||
entry: part.slice(separator + 1).trim(),
|
||
};
|
||
}
|
||
|
||
function parseCaptionBounds(fields: Map<string, string>): {
|
||
x0: number;
|
||
y0: number;
|
||
x1: number;
|
||
y1: number;
|
||
} {
|
||
const x0 = requiredCaptionFraction(fields, "x0");
|
||
const y0 = requiredCaptionFraction(fields, "y0");
|
||
const x1 = requiredCaptionFraction(fields, "x1");
|
||
const y1 = requiredCaptionFraction(fields, "y1");
|
||
if (x0 > x1 || y0 > y1) throw captionZoneError();
|
||
return { x0, y0, x1, y1 };
|
||
}
|
||
|
||
function requiredCaptionFraction(fields: Map<string, string>, key: string): number {
|
||
const value = captionFraction(fields.get(key));
|
||
if (value === null) throw captionZoneError();
|
||
return value;
|
||
}
|
||
|
||
function captionFraction(value: string | undefined): number | null {
|
||
if (value === undefined || value === "") return null;
|
||
const parsed = parseNumberStrict(value);
|
||
return parsed !== null && parsed >= 0 && parsed <= 1 ? parsed : null;
|
||
}
|
||
|
||
function captionSeverity(
|
||
value: string | undefined,
|
||
errorFactory: () => Error = captionZoneError,
|
||
): "error" | "warning" | undefined {
|
||
if (value === undefined) return undefined;
|
||
if (value === "error" || value === "warning") return value;
|
||
throw errorFactory();
|
||
}
|
||
|
||
function captionSeeks(
|
||
value: string | undefined,
|
||
errorFactory: () => Error = captionZoneError,
|
||
): number[] | undefined {
|
||
if (value === undefined) return undefined;
|
||
if (value === "") return [];
|
||
const values = value.split(",").map(captionFraction);
|
||
if (values.some((entry) => entry === null)) throw errorFactory();
|
||
return values.flatMap((entry) => (entry === null ? [] : entry));
|
||
}
|
||
|
||
function captionZoneError(): Error {
|
||
return new CliUsageError(
|
||
'Invalid --caption-zone; use "x0=0;y0=.82;x1=1;y1=1[;severity=warning|error][;seek=.5,1]" with fractions from 0 to 1.',
|
||
);
|
||
}
|
||
|
||
function positiveInteger(args: Record<string, unknown>, flag: string, fallback: number): number {
|
||
const value = args[flag];
|
||
if (value === undefined) return fallback;
|
||
const parsed = wholeStringNumber(value);
|
||
if (!Number.isInteger(parsed) || parsed < 1)
|
||
throw new CliUsageError(`Invalid --${flag}: ${JSON.stringify(value)}; use a positive integer`);
|
||
return parsed;
|
||
}
|
||
|
||
function nonNegativeNumber(args: Record<string, unknown>, flag: string, fallback: number): number {
|
||
const value = args[flag];
|
||
if (value === undefined) return fallback;
|
||
const parsed = wholeStringNumber(value);
|
||
if (!Number.isFinite(parsed) || parsed < 0)
|
||
throw new CliUsageError(
|
||
`Invalid --${flag}: ${JSON.stringify(value)}; use a non-negative number`,
|
||
);
|
||
return parsed;
|
||
}
|
||
|
||
function wholeStringNumber(value: unknown): number {
|
||
const text = String(value).trim();
|
||
return text === "" ? NaN : Number(text);
|
||
}
|
||
|
||
function browserSkippedLine(report: CheckReport): string {
|
||
return report.lint.findings.some(leavesNothingToLoad)
|
||
? "Browser validation skipped: the lint error above leaves no composition to load. Fix it and run check again. Layout, motion, and contrast were not checked, so this is not a clean pass."
|
||
: "Browser session never ran — layout, motion, and contrast below are empty placeholders, not a clean pass.";
|
||
}
|
||
|
||
function printHumanReport(report: CheckReport): void {
|
||
if (report.cached)
|
||
console.log(
|
||
`${c.dim("◇")} Nothing changed since the pass at ${report.cached.at}; showing that result. Remote scripts and assets were not fetched again. Run with --no-cache to check again.`,
|
||
);
|
||
if (report.scope) {
|
||
console.log(
|
||
`Scope: ${report.scope.range ? report.scope.range.join("–") + "s" : "full timeline"}; ${report.scope.hiddenFindings} findings hidden by component filter. Counts/status include hidden findings.`,
|
||
);
|
||
for (const note of report.scope.notes) console.log(note);
|
||
}
|
||
printSection("Lint", report.lint);
|
||
if (report.browserSkipped) {
|
||
console.log();
|
||
console.log(` ${c.warn("⚠")} ${browserSkippedLine(report)}`);
|
||
}
|
||
printSection("Runtime", report.runtime);
|
||
printLayoutSection("Layout", report.layout);
|
||
printSection("Motion", report.motion);
|
||
printContrastSection(report);
|
||
printCraftSection(report);
|
||
printSection("Audio", report.audio);
|
||
printSnapshotSection(report);
|
||
console.log();
|
||
const label = report.ok ? c.success("Check passed") : c.error("Check failed");
|
||
console.log(`${report.ok ? c.success("◇") : c.error("◇")} ${label}`);
|
||
}
|
||
|
||
function isEmptySection(section: CheckSection): boolean {
|
||
return (
|
||
section.findings.length === 0 &&
|
||
section.errorCount + section.warningCount + section.infoCount === 0
|
||
);
|
||
}
|
||
|
||
function printSection(title: string, section: CheckSection): void {
|
||
console.log();
|
||
console.log(c.bold(title));
|
||
if (isEmptySection(section)) {
|
||
console.log(` ${c.success("◇")} 0 errors, 0 warnings`);
|
||
return;
|
||
}
|
||
for (const finding of section.findings) printFinding(finding);
|
||
printCounts(section);
|
||
}
|
||
|
||
function printLayoutSection(title: string, section: CheckReport["layout"]): void {
|
||
console.log();
|
||
console.log(c.bold(title));
|
||
if (isEmptySection(section)) {
|
||
console.log(` ${c.success("◇")} 0 issues across ${section.samples.length} sample(s)`);
|
||
} else {
|
||
for (const finding of section.findings) {
|
||
const formatted = formatLayoutIssue(finding).replace(/\n/g, "\n ");
|
||
console.log(` ${findingIcon(finding)} ${formatted}`);
|
||
}
|
||
printCounts(section);
|
||
}
|
||
if (section.transitionSamplesDropped > 0) {
|
||
console.log(
|
||
` ${c.warn("⚠")} ${section.transitionSamplesDropped} transition sample(s) omitted`,
|
||
);
|
||
}
|
||
}
|
||
|
||
function printContrastSection(report: CheckReport): void {
|
||
const section = report.contrast;
|
||
console.log();
|
||
console.log(c.bold("Contrast"));
|
||
if (!section.enabled) {
|
||
console.log(` ${c.dim("◇")} skipped`);
|
||
return;
|
||
}
|
||
if (isEmptySection(section)) {
|
||
console.log(
|
||
` ${c.success("◇")} ${section.passed}/${section.checked} text checks pass WCAG AA`,
|
||
);
|
||
return;
|
||
}
|
||
for (const finding of section.findings) {
|
||
const text = finding.text ? ` ${c.dim(`"${terminalText(finding.text)}"`)}` : "";
|
||
console.log(
|
||
` ${findingIcon(finding)} ${terminalText(finding.selector)}${text} ${finding.ratio}:1 (need ${finding.requiredRatio}:1, ${formatFindingTimes(finding)})`,
|
||
);
|
||
const source = `Try ${terminalText(finding.suggestedColor)}; source ${terminalText(finding.sourceFile)}`;
|
||
console.log(` ${c.dim(source)}`);
|
||
}
|
||
printCounts(section);
|
||
}
|
||
|
||
function printCraftSection(report: CheckReport): void {
|
||
const section = report.craft;
|
||
if (!section.enabled) {
|
||
console.log();
|
||
console.log(c.bold("Craft"));
|
||
console.log(` ${c.dim("◇")} skipped`);
|
||
return;
|
||
}
|
||
printSection("Craft", section);
|
||
}
|
||
|
||
function printSnapshotSection(report: CheckReport): void {
|
||
console.log();
|
||
console.log(c.bold("Snapshots"));
|
||
if (!report.snapshots.enabled) {
|
||
console.log(` ${c.dim("◇")} disabled`);
|
||
} else {
|
||
console.log(` ${c.success("◇")} ${report.snapshots.files.length} PNG(s) saved`);
|
||
for (const file of report.snapshots.files) console.log(` ${c.dim(file)}`);
|
||
if (report.snapshots.findingFiles.length > 0) {
|
||
console.log(
|
||
` ${c.success("◇")} ${report.snapshots.findingFiles.length} finding crop(s) saved`,
|
||
);
|
||
for (const file of report.snapshots.findingFiles) console.log(` ${c.dim(file)}`);
|
||
}
|
||
}
|
||
}
|
||
|
||
function printFinding(finding: CheckFinding): void {
|
||
const where = `${terminalText(finding.sourceFile)} ${terminalText(finding.selector)} ${formatFindingTimes(finding)}`;
|
||
console.log(` ${findingIcon(finding)} ${finding.code}: ${terminalText(finding.message)}`);
|
||
console.log(` ${c.dim(where)}`);
|
||
if (finding.fixHint) console.log(` ${c.dim(`Fix: ${terminalText(finding.fixHint)}`)}`);
|
||
}
|
||
|
||
function findingIcon(finding: CheckFinding): string {
|
||
if (finding.severity === "error") return c.error("✗");
|
||
if (finding.severity === "warning") return c.warn("⚠");
|
||
return c.dim("ℹ");
|
||
}
|
||
|
||
function printCounts(section: CheckSection): void {
|
||
console.log(
|
||
` ${c.dim(`${section.errorCount} error(s), ${section.warningCount} warning(s), ${section.infoCount} info(s)`)}`,
|
||
);
|
||
}
|
||
|
||
export default createCheckCommand();
|