@graphty/visual-review 0.0.1 → 0.1.1

package/trusted/lib/init.mjs

@@ -0,0 +1,196 @@
+/**
+ * `visual-review init`: writes a repository's config, its Git LFS rule and its GitHub Actions
+ * workflows from the templates in this package's templates/ directory.
+ *
+ * The workflows are the templates with four placeholders filled in (`# __SETUP__` is a comment,
+ * so a template is valid YAML): the default branch, the
+ * package manager's setup and install steps, the command that runs this CLI, and this package's
+ * version (the gate job runs exactly that published version with npx). A workflow init wrote
+ * starts with GENERATED, so `--force` rewrites it and never a workflow someone wrote by hand.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { CONFIG_FILE, loadConfig } from "./config.mjs";
+
+const PACKAGE = join(dirname(fileURLToPath(import.meta.url)), "../..");
+export const GENERATED = "# Generated by visual-review init";
+
+/** Per package manager: the steps that install Node and the dependencies, and how to run the CLI. */
+const MANAGERS = {
+    npm: { lock: "package-lock.json", cli: "npx visual-review", setup: setup("npm", "npm ci") },
+    pnpm: {
+        lock: "pnpm-lock.yaml",
+        cli: "pnpm exec visual-review",
+        setup: `- uses: pnpm/action-setup@v4\n\n${setup("pnpm", "pnpm install --frozen-lockfile")}`,
+    },
+    yarn: { lock: "yarn.lock", cli: "yarn visual-review", setup: setup("yarn", "yarn install --frozen-lockfile") },
+};
+
+function setup(cache, install) {
+    return [
+        "- uses: actions/setup-node@v4",
+        "  with:",
+        "      node-version: 22.x",
+        `      cache: ${cache}`,
+        "",
+        "# HUSKY=0: git hooks are for people, not for CI's install.",
+        "- name: Install dependencies",
+        `  run: ${install}`,
+        "  env:",
+        '      HUSKY: "0"',
+    ].join("\n");
+}
+
+/**
+ * The package manager a repository uses, from its lockfile.
+ * @param {string} root the repository
+ * @returns {"npm" | "pnpm" | "yarn"} the manager
+ */
+export function packageManager(root) {
+    const found = Object.keys(MANAGERS).find((m) => m !== "npm" && existsSync(join(root, MANAGERS[m].lock)));
+    return /** @type {"npm" | "pnpm" | "yarn"} */ (found ?? "npm");
+}
+
+/**
+ * Fills in a template.
+ * @param {string} name the template's file name in templates/
+ * @param {{ branch: string, manager: "npm" | "pnpm" | "yarn", version: string }} values what goes in
+ * @returns {string} the workflow
+ */
+export function renderTemplate(name, { branch, manager, version }) {
+    const m = MANAGERS[manager];
+    return readFileSync(join(PACKAGE, "templates", name), "utf8").replace(
+        /^( *)# __SETUP__$|__BRANCH__|__CLI__|__VERSION__/gm,
+        (match, indent) =>
+            indent !== undefined
+                ? m.setup
+                      .split("\n")
+                      .map((l) => (l === "" ? "" : indent + l))
+                      .join("\n")
+                : { __BRANCH__: branch, __CLI__: m.cli, __VERSION__: version }[match],
+    );
+}
+
+function defaultBranch(root) {
+    const git = (...args) => execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: "pipe" }).trim();
+    try {
+        return git("symbolic-ref", "--short", "refs/remotes/origin/HEAD").replace(/^origin\//, "");
+    } catch {
+        try {
+            return git("branch", "--show-current") || "main";
+        } catch {
+            return "main";
+        }
+    }
+}
+
+/**
+ * Appends a line to a file unless a line already starts with `prefix`.
+ * @param {string} file the file, created when missing
+ * @param {string} prefix what an existing line starts with when the text is already there
+ * @param {string} text the lines to append
+ * @returns {boolean} whether it wrote
+ */
+function appendOnce(file, prefix, text) {
+    const old = existsSync(file) ? readFileSync(file, "utf8") : "";
+    if (old.split("\n").some((l) => l.startsWith(prefix))) {
+        return false;
+    }
+    writeFileSync(file, `${old}${old === "" || old.endsWith("\n") ? "" : "\n"}${text}\n`);
+    return true;
+}
+
+/**
+ * Whether git already ignores a directory (asked of a file in it, since a rule such as `dir/*`
+ * ignores the files but not the path itself).
+ * @param {string} root the repository
+ * @param {string} dir the directory, relative to the repository
+ * @returns {boolean} true when a file in it is ignored
+ */
+function ignored(root, dir) {
+    try {
+        execFileSync("git", ["check-ignore", "-q", "--no-index", `${dir}/x`], { cwd: root, stdio: "ignore" });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Sets up a repository.
+ * @param {string} root the repository's top level
+ * @param {{ force?: boolean }} [options] rewrite the workflows init wrote before (never the
+ *     config, which is the repository's own, and never a workflow written by hand)
+ * @returns {string[]} one line per file: what was written or kept
+ */
+export function init(root, { force = false } = {}) {
+    const report = [];
+    const manager = packageManager(root);
+    const configFile = join(root, CONFIG_FILE);
+    if (existsSync(configFile)) {
+        report.push(`kept     ${CONFIG_FILE}`);
+    } else {
+        const starter = {
+            defaultBranch: defaultBranch(root),
+            workflow: "visual-review.yml",
+            baselines: "visual-baselines",
+            workDir: ".visual-review",
+            commitPrefix: "test",
+            issueLabels: ["bug"],
+            projects: {
+                storybook: {
+                    storybook: "storybook-static",
+                    build: `${manager} run build-storybook`,
+                    workers: 4,
+                },
+            },
+        };
+        writeFileSync(configFile, `${JSON.stringify(starter, null, 4)}\n`);
+        report.push(`wrote    ${CONFIG_FILE}`);
+    }
+    const config = loadConfig(root);
+
+    const rule = `${config.baselines}/**/*.png`;
+    report.push(
+        appendOnce(
+            join(root, ".gitattributes"),
+            `${rule} `,
+            `# Visual review baselines are stored in Git LFS.\n${rule} filter=lfs diff=lfs merge=lfs -text`,
+        )
+            ? `wrote    .gitattributes (${rule} in Git LFS)`
+            : "kept     .gitattributes",
+    );
+    report.push(
+        !ignored(root, config.workDir) &&
+            appendOnce(join(root, ".gitignore"), `/${config.workDir}/`, `/${config.workDir}/`)
+            ? `wrote    .gitignore (/${config.workDir}/)`
+            : "kept     .gitignore",
+    );
+
+    const version = JSON.parse(readFileSync(join(PACKAGE, "package.json"), "utf8")).version;
+    const values = { branch: config.defaultBranch, manager, version };
+    for (const [template, file] of [
+        ["visual-review.yml", config.workflow],
+        ["visual-seed.yml", "visual-seed.yml"],
+    ]) {
+        const path = join(root, ".github/workflows", file);
+        const rel = `.github/workflows/${file}`;
+        if (existsSync(path) && !(force && readFileSync(path, "utf8").startsWith(GENERATED))) {
+            report.push(`kept     ${rel}${force ? " (not written by init, so never replaced)" : ""}`);
+            continue;
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, renderTemplate(template, values));
+        report.push(`wrote    ${rel}`);
+    }
+    report.push(
+        "",
+        `Next: edit ${CONFIG_FILE} (one entry per Storybook), commit these files, and push a pull request.`,
+        'Then make the "Visual gate" check required, and seed the first baselines (README, "Seeding").',
+    );
+    return report;
+}

package/trusted/lib/results.mjs

@@ -0,0 +1,158 @@
+/**
+ * results.json: what one capture run of one Storybook project found, item by item.
+ *
+ * Capture writes it; CI, the review page and later the MCP server read it. It arrives from a CI
+ * artifact, so every reader validates it before using a field: nothing in it is trusted, and a
+ * `file` name is later joined to a directory, so it may never leave that directory.
+ */
+
+/**
+ * Every status an item can have. `unseeded` ("no baseline yet") is a story with no baseline whose
+ * capture matches master's newest capture of it, so the pull request did not change it. `moved`
+ * is a story that looks exactly as the baseline of the id it was renamed from (`from`, named in
+ * the project's renames.json); a renamed story that looks different is `changed` with `from`.
+ */
+const STATUSES = ["unchanged", "moved", "changed", "new", "unseeded", "removed", "unstable", "failed", "excluded"];
+
+/** The most items one file may hold (compact-mantine has about 830 today). */
+export const MAX_ITEMS = 5000;
+
+const MAX_STRING = 2000;
+const MAX_CONSOLE = 100;
+
+const SHA1 = /^[0-9a-f]{40}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+
+// Which hashes a status requires (true), forbids (false) or leaves open (absent).
+const HASHES = {
+    unchanged: { baseline: true, capture: true },
+    changed: { baseline: true, capture: true },
+    moved: { baseline: true, capture: true },
+    new: { baseline: false, capture: true },
+    unseeded: { baseline: false, capture: true },
+    removed: { baseline: true, capture: false },
+};
+
+const isInt = (v, min = 0) => Number.isInteger(v) && v >= min;
+const isStr = (v) => typeof v === "string" && v.length > 0 && v.length <= MAX_STRING;
+const isPair = (v) => Array.isArray(v) && v.length === 2 && v.every((n) => isInt(n, 1));
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * Checks a parsed results.json.
+ * @param {any} r the parsed JSON, untrusted
+ * @returns {string[]} one message per problem; empty when the file is valid
+ */
+export function validateResults(r) {
+    if (!isObj(r)) {
+        return ["results must be an object"];
+    }
+    const errors = [];
+    const check = (ok, message) => {
+        if (!ok) {
+            errors.push(message);
+        }
+    };
+
+    check(r.version === 1, "version must be 1");
+    check(typeof r.project === "string" && NAME.test(r.project), "project must be a lowercase name");
+    check(typeof r.commit === "string" && SHA1.test(r.commit), "commit must be a 40-character sha");
+    check(
+        r.headSha === null || (typeof r.headSha === "string" && SHA1.test(r.headSha)),
+        "headSha must be a sha or null",
+    );
+    for (const key of ["pr", "runId", "runAttempt"]) {
+        check(r[key] === null || isInt(r[key], 1), `${key} must be a positive integer or null`);
+    }
+    check(
+        r.local === null ||
+            (isObj(r.local) &&
+                isStr(r.local.describe) &&
+                typeof r.local.diff === "string" &&
+                SHA256.test(r.local.diff)),
+        "local must be null or { describe, diff }",
+    );
+    check(typeof r.seeded === "boolean", "seeded must be a boolean");
+    check(typeof r.complete === "boolean", "complete must be a boolean");
+    check(isInt(r.expected), "expected must be a non-negative integer");
+    check(isStr(r.capturedAt) && !Number.isNaN(Date.parse(r.capturedAt)), "capturedAt must be a date");
+    check(isObj(r.clock), "clock must be an object");
+    check(isObj(r.environment), "environment must be an object");
+    // Device pixels per CSS pixel. Captures made before it was recorded were at 1.
+    check(r.scale === undefined || r.scale === 1 || r.scale === 2, "scale must be 1 or 2");
+
+    if (!Array.isArray(r.items)) {
+        errors.push("items must be an array");
+        return errors;
+    }
+    if (r.items.length > MAX_ITEMS) {
+        errors.push(`items holds ${r.items.length} entries; the most allowed is ${MAX_ITEMS}`);
+        return errors;
+    }
+
+    const seen = new Set();
+    r.items.forEach((item, i) => {
+        const at = `items[${i}]`;
+        if (!isObj(item)) {
+            errors.push(`${at} must be an object`);
+            return;
+        }
+        const idOk = typeof item.id === "string" && item.id.length <= 200 && NAME.test(item.id);
+        const modeOk =
+            item.mode === null || (typeof item.mode === "string" && item.mode.length <= 50 && NAME.test(item.mode));
+        check(idOk, `${at}.id must be a Storybook story id`);
+        check(modeOk, `${at}.mode must be a lowercase name or null`);
+        // The file name is derived, never chosen: `<id>[.<mode>].png`. That alone keeps "/" and ".."
+        // out of it, because neither the id nor the mode can contain them.
+        if (idOk && modeOk) {
+            const expected = item.mode === null ? `${item.id}.png` : `${item.id}.${item.mode}.png`;
+            check(item.file === expected, `${at}.file must be "${expected}"`);
+            const key = `${item.id}\u0000${item.mode}`;
+            check(!seen.has(key), `${at} is a duplicate of ${item.id} ${item.mode ?? ""}`.trimEnd());
+            seen.add(key);
+        } else {
+            check(false, `${at}.file cannot be checked without a valid id and mode`);
+        }
+
+        check(STATUSES.includes(item.status), `${at}.status must be one of ${STATUSES.join(", ")}`);
+        // The story id a renamed story's baseline was read under (absent when it was not renamed).
+        check(
+            item.from === undefined ||
+                item.from === null ||
+                (typeof item.from === "string" && item.from.length <= 200 && NAME.test(item.from)),
+            `${at}.from must be a Storybook story id or null`,
+        );
+        check(item.status !== "moved" || typeof item.from === "string", `${at}.from is required for a moved item`);
+        check(typeof item.flaky === "boolean", `${at}.flaky must be a boolean`);
+        for (const key of ["baseline", "capture"]) {
+            const v = item[key];
+            check(v === null || (typeof v === "string" && SHA256.test(v)), `${at}.${key} must be a sha256 or null`);
+            const rule = HASHES[item.status]?.[key];
+            check(rule !== true || typeof v === "string", `${at}.${key} is required for a ${item.status} item`);
+            check(rule !== false || v === null, `${at}.${key} must be null for a ${item.status} item`);
+        }
+        for (const key of ["size", "baselineSize"]) {
+            check(item[key] === null || isPair(item[key]), `${at}.${key} must be [width, height] or null`);
+        }
+        check(item.changedPixels === null || isInt(item.changedPixels), `${at}.changedPixels must be a count or null`);
+        check(
+            item.bbox === null ||
+                (Array.isArray(item.bbox) && item.bbox.length === 4 && item.bbox.every((n) => isInt(n))),
+            `${at}.bbox must be four integers or null`,
+        );
+        check(
+            typeof item.threshold === "number" && item.threshold >= 0 && item.threshold <= 1,
+            `${at}.threshold must be 0..1`,
+        );
+        check(typeof item.includeAA === "boolean", `${at}.includeAA must be a boolean`);
+        check(item.reason === null || isStr(item.reason), `${at}.reason must be a string or null`);
+        check(
+            Array.isArray(item.console) &&
+                item.console.length <= MAX_CONSOLE &&
+                item.console.every((line) => typeof line === "string" && line.length <= MAX_STRING),
+            `${at}.console must be at most ${MAX_CONSOLE} strings`,
+        );
+    });
+    return errors;
+}