scenescout 3.15.0 → 3.17.0

package/dist/engine/baseline.js

@@ -0,0 +1,377 @@
+/**
+ * Visual baselines for `scenescout check --baseline compare|update`, as data.
+ *
+ * A baseline is an approved picture of a page (its viewport, from the top) or
+ * of one element on it, kept per route and per browser engine, beside a small
+ * JSON saying how it was taken. `compare` takes the same picture again and
+ * diffs it with the baseline (png.ts); `update` writes new baselines, and only
+ * when it is asked to. What has a baseline is the project's choice, listed in
+ * the baselines folder's targets.json; nothing is baselined by default.
+ *
+ * Everything here is pure: the targets file and its errors, the file layout,
+ * what a baseline records, whether two pictures were taken alike, the verdict,
+ * and the evidence an unmet baseline is filed with. The browser half is
+ * BrowserEngine.captureForBaseline, which only takes the picture; check-run.ts
+ * reads and writes the files. Table-tested in check-test.
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { z } from "zod";
+import { CAPTURE_MARGIN } from "./capture.js";
+import { ARIA_ROLES, fieldPath, issueMessage, parseJsonFile, parseTarget, TARGET_HELP } from "./flow.js";
+import { MEMORY_DIRNAME, redactRoute } from "./memory.js";
+import { decodePng, diffImages } from "./png.js";
+export const BASELINE_MODES = ["off", "compare", "update"];
+/** The targets file, at the top of the baselines folder. */
+export const TARGETS_FILE = "targets.json";
+/** The most targets one check takes pictures of: each one is a page load. */
+export const MAX_BASELINE_TARGETS = 100;
+/**
+ * The share of pixels, in percent, that may change before a baseline counts
+ * as not met. Not 0: two pictures of an unchanged page taken by one browser
+ * build on one machine compare at 0%, but a run on another machine, or after
+ * a browser or font update, can anti-alias text and curved edges a pixel
+ * differently, and a gate that fails on that noise teaches a team to ignore
+ * it. 0.1% is 1,152 pixels of a 1280×900 page and 64 of a 320×200 picture, so
+ * a smaller change passes unless the project lowers the threshold. A change of
+ * size always counts.
+ */
+export const DEFAULT_BASELINE_THRESHOLD = 0.1;
+/** The element a target names when it names none: the page's viewport, from the top. */
+const PAGE_ELEMENT = "page";
+/** Where the pictures of an unmet baseline go, beside report.md. */
+export const VISUAL_DIRNAME = "visual";
+/** The baselines folder when --baselines names none: inside .scenescout/, which git ignores, so nothing is committed unless the project chooses a folder of its own. */
+export function defaultBaselinesDir(projectDir) {
+    return path.join(projectDir, MEMORY_DIRNAME, "baselines");
+}
+/**
+ * The settings every baseline is taken with, in one copy: the check attaches
+ * with its window and scale, the browser takes the picture by the rest, and
+ * the JSON records them all, the window and scale as the browser reports them.
+ */
+export const BASELINE_CAPTURE = {
+    viewport: { width: 1280, height: 900 },
+    deviceScaleFactor: 1,
+    margin: CAPTURE_MARGIN,
+    reducedMotion: "reduce",
+    animations: "disabled",
+    caret: "hide",
+};
+/**
+ * Page-side source that stops every animation and transition before an
+ * element is measured, not only while the screenshot is taken: a target that
+ * itself moves would otherwise be cropped wherever it was mid-movement. Finite
+ * ones are finished, infinite ones cancelled, as the screenshot's own setting
+ * does. A string, like the collector, so no build step can wrap it in a
+ * helper the page does not have.
+ */
+export const STOP_ANIMATIONS_SCRIPT = `(() => {
+  for (const a of document.getAnimations()) {
+    const end = a.effect ? a.effect.getComputedTiming().endTime : Infinity;
+    if (end === Infinity) a.cancel();
+    else a.finish();
+  }
+  return true;
+})()`;
+const ELEMENT_HELP = `${PAGE_ELEMENT} or ${TARGET_HELP}`;
+/** What an element names: null for the page itself, else the target a saved flow would use. Undefined when it is neither. */
+export function elementTarget(element) {
+    if (element === PAGE_ELEMENT)
+        return null;
+    return parseTarget(element) ?? undefined;
+}
+const elementSchema = z.string().superRefine((e, ctx) => {
+    const target = elementTarget(e);
+    if (target === undefined)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `must be ${ELEMENT_HELP}` });
+    else if (target?.by === "role" && !ARIA_ROLES.has(target.role)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `names the role "${target.role}", which is not an ARIA role (e.g. button, link, region, img)` });
+    }
+});
+const targetsSchema = z
+    .object({
+    targets: z
+        .array(z
+        .object({
+        path: z.string().regex(/^\/\S*$/, "must be a path on the app, starting with / and with no spaces"),
+        element: elementSchema.optional(),
+    })
+        .strict())
+        .min(1, "lists nothing to keep a baseline of")
+        .max(MAX_BASELINE_TARGETS, `holds at most ${MAX_BASELINE_TARGETS} targets`),
+})
+    .strict()
+    .superRefine((file, ctx) => {
+    // Two entries for one picture would write one file twice and compare it twice.
+    const seen = new Map();
+    file.targets.forEach((t, i) => {
+        const key = `${t.path}\u0000${t.element ?? PAGE_ELEMENT}`;
+        const first = seen.get(key);
+        if (first === undefined)
+            seen.set(key, i);
+        else
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["targets", i], message: `repeats targets[${first}]` });
+    });
+});
+/** Validate a targets file's text. Every mistake names the file and the field, as a flow's do. */
+export function parseBaselineTargets(text, file) {
+    const parsed = parseJsonFile(text, file, targetsSchema);
+    if (!parsed.ok)
+        return parsed;
+    return { ok: true, targets: parsed.data.targets.map((t) => ({ path: t.path, element: t.element ?? PAGE_ELEMENT })) };
+}
+/** What to tell someone who asked for baselines in a folder with no targets file. */
+export function missingTargetsMessage(file) {
+    return (`there is no ${file}: list the pages and elements to keep baselines of there, e.g. ` +
+        `{"targets": [{"path": "/", "element": "page"}, {"path": "/settings", "element": "testid=profile-card"}]}`);
+}
+// ---------------------------------------------------------------------------
+// Where the files are
+// ---------------------------------------------------------------------------
+/**
+ * Text as a file name: lower-case letters, digits and dashes, then a hash of
+ * the exact text, so two that read alike never share a file. The readable part
+ * is taken from the text redacted as a route is, so a token in a target's path
+ * never becomes part of a file name, the report or the JSON.
+ */
+function fileKey(text, fallback) {
+    const slug = redactRoute(text)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48)
+        .replace(/-+$/, "") || fallback;
+    return `${slug}-${createHash("sha256").update(text).digest("hex").slice(0, 8)}`;
+}
+/** The folder of one route's baselines: `/settings/profile` → `settings-profile-<hash>`, `/` → `index-<hash>`. */
+export function routeFolder(routePath) {
+    return fileKey(routePath, "index");
+}
+/** The file name of one element's baseline, without its extension: `page`, or e.g. `testid-profile-card-<hash>`. */
+export function elementFile(element) {
+    return element === PAGE_ELEMENT ? PAGE_ELEMENT : fileKey(element, "element");
+}
+/**
+ * A target's baseline, relative to the baselines folder and with forward
+ * slashes: one folder per engine (a picture from one browser is not another's
+ * baseline), one per route, then the PNG and the JSON beside it.
+ */
+export function baselineFiles(engine, target) {
+    const stem = `${engine}/${routeFolder(target.path)}/${elementFile(target.element)}`;
+    return { png: `${stem}.png`, json: `${stem}.json` };
+}
+/** The pictures of an unmet baseline, relative to the check's output folder: what was expected, what it is now, and the changed pixels. */
+export function visualFiles(target) {
+    const stem = `${VISUAL_DIRNAME}/${routeFolder(target.path)}/${elementFile(target.element)}`;
+    return { expected: `${stem}.expected.png`, actual: `${stem}.actual.png`, diff: `${stem}.diff.png` };
+}
+/**
+ * Whether a file under the output folder's visual/ is one visualFiles names:
+ * a route folder and a picture named exactly as a check names them. Only
+ * these are cleared before a run writes its own, so nothing else that happens
+ * to sit there is ever deleted.
+ */
+export function isVisualPicture(folder, file) {
+    return /^[a-z0-9-]+-[0-9a-f]{8}$/.test(folder) && /^(page|[a-z0-9-]+-[0-9a-f]{8})\.(expected|actual|diff)\.png$/.test(file);
+}
+const size = z.object({ width: z.number().int().positive(), height: z.number().int().positive() });
+const metaSchema = z.object({
+    path: z.string(),
+    element: z.string(),
+    engine: z.string(),
+    platform: z.string(),
+    // Read as strings, not the values this version writes, so a baseline taken another way is reported as different, not as unreadable.
+    capture: z.object({
+        viewport: size,
+        deviceScaleFactor: z.number().positive(),
+        margin: z.number().int().min(0),
+        reducedMotion: z.string(),
+        animations: z.string(),
+        caret: z.string(),
+    }),
+    size,
+    capturedAt: z.string(),
+});
+export function baselineMeta(o) {
+    return {
+        path: o.target.path,
+        element: o.target.element,
+        engine: o.engine,
+        platform: o.platform,
+        capture: o.capture,
+        size: o.size,
+        capturedAt: o.capturedAt,
+    };
+}
+/** Read a baseline's JSON. An error says why it cannot be used, for the report. */
+export function parseBaselineMeta(text) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        return { ok: false, error: `its JSON is not valid (${err instanceof Error ? err.message : String(err)})` };
+    }
+    const parsed = metaSchema.safeParse(json);
+    if (!parsed.success) {
+        const first = parsed.error.issues[0];
+        return { ok: false, error: `its JSON is not a baseline's: ${fieldPath(first.path)} ${issueMessage(first)}` };
+    }
+    return { ok: true, meta: parsed.data };
+}
+/** How each setting is named and shown. Typed by CaptureSettings, so a setting added there must be added here, and so compared. */
+const SETTING_SHOWN = {
+    viewport: { label: "viewport", value: (v) => `${v.width}×${v.height}` },
+    deviceScaleFactor: { label: "device scale", value: (v) => String(v) },
+    margin: { label: "margin", value: (v) => `${v}px` },
+    reducedMotion: { label: "reducedMotion", value: (v) => v },
+    animations: { label: "animations", value: (v) => v },
+    caret: { label: "caret", value: (v) => v },
+};
+/** How two pictures' settings differ, one phrase each; empty when they were taken alike. */
+export function captureDifferences(stored, now) {
+    return Object.keys(SETTING_SHOWN).flatMap((k) => {
+        const { label, value } = SETTING_SHOWN[k];
+        const was = value(stored[k]);
+        const is = value(now[k]);
+        return was === is ? [] : [`${label} ${was} (now ${is})`];
+    });
+}
+/**
+ * Make sense of a target's two baseline files as found on disk (null for one
+ * that is not there). Half a baseline, a JSON that describes another target or
+ * browser, and a PNG that cannot be read or is not the size its JSON says are
+ * each unusable, with the reason: never silently compared, never silently
+ * treated as absent.
+ */
+export function readStoredBaseline(target, engine, png, json) {
+    if (png === null && json === null)
+        return null;
+    if (png === null)
+        return { problem: "its PNG is missing; only the JSON beside it is there" };
+    if (json === null)
+        return { problem: "the JSON beside its PNG is missing" };
+    const parsed = parseBaselineMeta(json);
+    if (!parsed.ok)
+        return { problem: parsed.error };
+    const m = parsed.meta;
+    if (m.path !== target.path || m.element !== target.element || m.engine !== engine) {
+        return { problem: `its JSON describes ${m.element} on ${m.path} in ${m.engine}, not this target` };
+    }
+    let image;
+    try {
+        image = decodePng(png);
+    }
+    catch (err) {
+        return { problem: `its PNG cannot be read: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (image.width !== m.size.width || image.height !== m.size.height) {
+        return { problem: `its PNG is ${image.width}×${image.height} where its JSON says ${m.size.width}×${m.size.height}` };
+    }
+    return { meta: m, image };
+}
+/**
+ * Far below the smallest step a share of pixels can take (100 / MAX_PIXELS),
+ * so a share exactly at the threshold is never read as past it because of
+ * floating point: 7 of 100 is 7.000000000000001%.
+ */
+const SHARE_EPSILON = 1e-9;
+/** Whether a comparison is a change: any change of size, or more of the pixels than the threshold allows. */
+export function isChange(diff, threshold) {
+    if (diff.sizeChanged)
+        return true;
+    return diff.total > 0 && (diff.changed / diff.total) * 100 > threshold + SHARE_EPSILON;
+}
+function diffSummary(d) {
+    return { percent: d.percent, changedPixels: d.changed, totalPixels: d.total, sizeChanged: d.sizeChanged, baseline: d.before, now: d.after };
+}
+/**
+ * Decide what becomes of one captured target, given its stored baseline and
+ * the picture just taken. A status of `updated` is the one that writes the new
+ * picture as its baseline; `diffImage` comes with `changed`, for the pictures
+ * kept beside the report. update rewrites what compare would not accept and
+ * leaves alone a baseline compare would (none of its pixels changed, or no
+ * more than the threshold allows), so an update that changes nothing changes
+ * no file and noise under the threshold does not churn the folder. A baseline
+ * taken on another operating system is rewritten however close it came, so
+ * retaking baselines where the check runs replaces every one of them.
+ */
+export function judgeBaseline(o) {
+    const { mode, stored, now } = o;
+    if (stored === null)
+        return mode === "update" ? { status: "updated", detail: "it had no baseline" } : { status: "no-baseline" };
+    const cannotUse = (why) => mode === "update" ? { status: "updated", detail: `replaced one that could not be used: ${why}` } : { status: "unusable", detail: why };
+    if ("problem" in stored)
+        return cannotUse(stored.problem);
+    const differs = captureDifferences(stored.meta.capture, now.capture);
+    if (differs.length > 0)
+        return cannotUse(`it was taken with other settings: ${differs.join(", ")}`);
+    const { platform } = stored.meta;
+    const otherSystem = platform !== now.platform;
+    const d = diffImages(stored.image, now.image);
+    const diff = diffSummary(d);
+    if (mode === "update") {
+        if (otherSystem)
+            return { status: "updated", detail: `replaced one taken on ${platform}`, diff };
+        if (!isChange(d, o.threshold))
+            return { status: "matches", diff };
+        // With the count, as describeChange gives it.
+        return { status: "updated", detail: `it was ${d.percent}% different (${d.changed} of ${d.total} pixels)`, diff };
+    }
+    const note = otherSystem ? { platformNote: `its baseline was taken on ${platform} and this check ran on ${now.platform}` } : {};
+    if (!isChange(d, o.threshold))
+        return { status: "matches", diff, ...note };
+    return { status: "changed", diff, diffImage: d.image, ...note };
+}
+/** The issue rule an unmet baseline is filed under (check.ts). */
+export const VISUAL_RULE = "visual-change";
+/**
+ * The evidence an unmet baseline is filed with, or null when the result is
+ * not an issue. A change and an unusable baseline (compare), and a target that
+ * could not be pictured at all (either mode), are issues: targets.json says
+ * the project expects to see it, and a comparison that compared nothing must
+ * not pass. No baseline yet is never one.
+ */
+export function baselineEvidence(r, run) {
+    const what = `${r.element} on ${r.path}`;
+    switch (r.status) {
+        case "not-captured":
+            return `${what} could not be captured: ${r.detail ?? "no reason given"}${run.mode === "update" ? ", so its baseline was not written" : ""}`;
+        case "unusable":
+            return `${what}: its baseline cannot be used (${r.detail ?? "no reason given"}); run the check with --baseline update to take it again`;
+        case "changed":
+            return `${what}: ${r.diff ? describeChange(r.diff, run.threshold) : "it no longer matches its baseline"}${r.files ? ` — diff: ${r.files.diff}` : ""}`;
+        default:
+            return null;
+    }
+}
+/** A change in words. A change of size always counts, whatever the threshold, so it is named first. */
+export function describeChange(d, threshold) {
+    if (d.sizeChanged) {
+        return `its size changed from ${d.baseline.width}×${d.baseline.height} to ${d.now.width}×${d.now.height}, which always counts (${d.percent}% of its pixels differ)`;
+    }
+    // The count beside the rounded share, so 0.504% past a 0.5% threshold does not read as 0.5% (allowed: 0.5%).
+    return `${d.percent}% of its pixels changed (${d.changedPixels} of ${d.totalPixels}; allowed: ${threshold}%)`;
+}
+/** The fingerprint of an unmet baseline: the same target in the same browser is the same alert, whatever its percentage this time. */
+export function baselineFingerprint(engine, r) {
+    return createHash("sha256").update(`${VISUAL_RULE}\u0000${engine}\u0000${r.path}\u0000${r.element}`).digest("hex").slice(0, 32);
+}
+/** How many results there are of each status, for the report's summary line. */
+export function countStatuses(results) {
+    const counts = { matches: 0, changed: 0, "no-baseline": 0, unusable: 0, "not-captured": 0, updated: 0 };
+    for (const r of results)
+        counts[r.status] += 1;
+    return counts;
+}
+/** Parse --baseline-threshold: a percentage from 0 to 100. */
+export function parseThreshold(raw) {
+    if (raw === undefined)
+        return { ok: true, value: DEFAULT_BASELINE_THRESHOLD };
+    const value = Number(raw.trim());
+    if (raw.trim() === "" || !Number.isFinite(value) || value < 0 || value > 100) {
+        return { ok: false, error: "--baseline-threshold must be a percentage from 0 to 100, e.g. 0.5" };
+    }
+    return { ok: true, value };
+}

package/dist/engine/brief.js

@@ -114,6 +114,21 @@ function laneObjective(modules, goal) {
     const what = `Own ${owned}`;
     return goal ? `${what} — ${goal}` : what;
 }
+/**
+ * How every lane works, whoever briefs it: formatBriefs passes these to a
+ * planner's lane agents, and an unattended run's lanes (`scenescout ci
+ * --lanes`) are given the same lines in their prompt. One list, so the two
+ * kinds of lane cannot drift apart.
+ */
+export const LANE_RULES = [
+    `A lane works ITS routes only. Two lanes auditing the same register while a third module is never opened is the failure this plan exists to prevent — and route coverage will look complete either way. A defect on a page it does not own is that page's lane's to file.`,
+    `Every acting tool takes a \`task\`. A lane that acts with none is refused, and the person watching the live view would otherwise see a browser clicking through their app with nothing to say why.`,
+    `File each defect with scout_finding the moment it is judged, before writing the report. A defect only in the report is not in the run's report.`,
+    `Before calling a list empty, stale or stuck, read the status of the request behind it: a correct empty result and a failed one can render identically.`,
+    `On a create form, submit one markup-shaped value, then open where that record is listed. Any lane's session catches it rendering as markup, so the list may belong to another lane.`,
+    `When a control is withheld from this role, call the endpoint behind it with scout_request: hiding a button is not enforcing a rule. When a sort or filter runs, check the result is what it claims.`,
+    `Check scout_coverage before finishing.`,
+];
 /**
  * The briefing the planner gives the lanes.
  *
@@ -133,13 +148,7 @@ export function formatBriefs(briefs, opts = {}) {
         `  scout_attach { session: "<lane>", url: "<origin><landing>", projectPath, mode: "${mode}"${signInArgument(opts)}, objective: "<objective>" }`,
         ``,
         `Rules to pass on, which a hand-written brief tends to drop:`,
-        `  · A lane works ITS routes only. Two lanes auditing the same register while a third module is never opened is the failure this plan exists to prevent — and route coverage will look complete either way. A defect on a page it does not own is that page's lane's to file.`,
-        `  · Every acting tool takes a \`task\`. A lane that acts with none is refused, and the person watching the live view would otherwise see a browser clicking through their app with nothing to say why.`,
-        `  · File each defect with scout_finding the moment it is judged, before writing the report. A defect only in the report is not in the run's report.`,
-        `  · Before calling a list empty, stale or stuck, read the status of the request behind it: a correct empty result and a failed one can render identically.`,
-        `  · On a create form, submit one markup-shaped value, then open where that record is listed. Any lane's session catches it rendering as markup, so the list may belong to another lane.`,
-        `  · When a control is withheld from this role, call the endpoint behind it with scout_request: hiding a button is not enforcing a rule. When a sort or filter runs, check the result is what it claims.`,
-        `  · Check scout_coverage before finishing.`,
+        ...LANE_RULES.map((rule) => `  · ${rule}`),
         `  · A lane reports back with scout_lane_report, not prose, and does NOT close its session: the planner folds the report, which checks each judged defect was filed, then closes it. Call scout_lane_report with no reply to get the instruction to put in its prompt.`,
         ``,
     ];