Files
plan2code/scripts/test-web-console-shape.mjs

420 lines
22 KiB
JavaScript

// Web console tests, the shape of the source: no console file grows past
// 3,000 lines, the files lib.mjs split into stand on their own, and the
// light theme's faintest ink meets WCAG AA contrast.
// Run with: node --test scripts/test-web-console-shape.mjs
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { spawnSync } from "node:child_process";
import { pathToFileURL } from "node:url";
import { ROOT } from "./web-console-test-helpers.mjs";
const CONSOLE_DIR = path.join(ROOT, "src", "web-console");
const MAX_LINES = 3000;
// Every .mjs, .js and .css file under `dir` (vendored code aside), as paths
// relative to it with forward slashes.
function sourceFiles(dir, rel = "") {
const out = [];
for (const e of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
const p = rel ? `${rel}/${e.name}` : e.name;
if (e.isDirectory()) {
if (p !== "public/vendor") out.push(...sourceFiles(dir, p));
} else if (/\.(mjs|js|css)$/.test(e.name)) out.push(p);
}
return out;
}
// A file's line count, as `wc -l` gives it for a file ending in a newline.
function lineCount(text) {
return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
}
// The lines that name each file over the limit.
function oversized(dir) {
return sourceFiles(dir)
.map((p) => [p, lineCount(fs.readFileSync(path.join(dir, p), "utf8"))])
.filter(([p, n]) => n > MAX_LINES)
.map(([p, n]) => `${p} is ${n} lines, over the ${MAX_LINES}-line limit: split it by job`);
}
test("shape: no console file is over 3,000 lines", () => {
assert.deepEqual(oversized(CONSOLE_DIR), []);
});
test("shape: the size check names the file that is too big", () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-shape-"));
try {
fs.mkdirSync(path.join(dir, "public", "vendor"), { recursive: true });
fs.writeFileSync(path.join(dir, "big.mjs"), "x\n".repeat(MAX_LINES + 1));
fs.writeFileSync(path.join(dir, "edge.css"), "x\n".repeat(MAX_LINES));
fs.writeFileSync(path.join(dir, "small.js"), "x\n");
fs.writeFileSync(path.join(dir, "public", "vendor", "huge.js"), "x\n".repeat(MAX_LINES * 2));
assert.deepEqual(oversized(dir), [`big.mjs is ${MAX_LINES + 1} lines, over the ${MAX_LINES}-line limit: split it by job`]);
} finally {
fs.rmSync(dir, { recursive: true, force: true });
}
});
test("shape: files.mjs still finds the console's own folder", async () => {
const { HERE, PUBLIC_DIR } = await import("../src/web-console/files.mjs");
assert.equal(path.basename(HERE), "web-console");
assert.equal(PUBLIC_DIR, path.join(HERE, "public"));
});
test("shape: lib.mjs is gone, and every file it split into is there", () => {
assert.equal(fs.existsSync(path.join(CONSOLE_DIR, "lib.mjs")), false, "src/web-console/lib.mjs still exists");
for (const f of SPLIT_FILES) {
const text = fs.readFileSync(path.join(CONSOLE_DIR, f), "utf8");
assert.match(text, /^\/\/ Plan2Code Web Console - \S.*\.\n/, `${f} opens with a one-line job comment`);
}
});
// Every page file but the entry (app.js) only defines things, so each one
// loads under plain Node with no page around it. Imported alone in a fresh
// process: one that reaches for `document` or `window` at load, or runs
// anything else that throws, is named with its first error line. One that
// starts a timer or a listener throws nothing but never exits: it is named too.
const LOAD_TIMEOUT_MS = 5000;
function pageLoadFailures(pub) {
return sourceFiles(pub)
.filter((p) => p.endsWith(".js") && p !== "app.js" && (!p.includes("/") || p.startsWith("screens/")))
.flatMap((p) => {
const url = pathToFileURL(path.join(pub, p)).href;
const r = spawnSync(process.execPath, ["--input-type=module", "-e", `await import(${JSON.stringify(url)});`], {
encoding: "utf8",
timeout: LOAD_TIMEOUT_MS,
});
if (r.error && r.error.code === "ETIMEDOUT") return [`${p} does not load on its own: still running after load (a timer or listener started at module scope)`];
if (r.status === 0) return [];
const line = r.stderr.split("\n").find((l) => /Error/.test(l)) || r.stderr.trim().split("\n")[0];
return [`${p} does not load on its own: ${line.trim()}`];
});
}
test("shape: every page file but app.js only defines things, and loads under plain Node", () => {
assert.deepEqual(pageLoadFailures(path.join(CONSOLE_DIR, "public")), []);
});
test("shape: the define-only check names a page file that touches the page at load", () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-define-only-"));
try {
fs.mkdirSync(path.join(dir, "screens"));
fs.mkdirSync(path.join(dir, "vendor"));
fs.writeFileSync(path.join(dir, "package.json"), '{ "type": "module" }\n');
fs.writeFileSync(path.join(dir, "app.js"), "document.title = 'the entry may';\n");
fs.writeFileSync(path.join(dir, "fine.js"), "export const title = () => document.title;\n");
fs.writeFileSync(path.join(dir, "screens", "eager.js"), "export const title = document.title;\n");
fs.writeFileSync(path.join(dir, "screens", "ticks.js"), "setInterval(() => {}, 1000);\n");
fs.writeFileSync(path.join(dir, "vendor", "lib.js"), "window.x = 1;\n");
const failures = pageLoadFailures(dir);
assert.equal(failures.length, 2, failures.join("\n"));
assert.match(failures.find((f) => f.startsWith("screens/eager.js")), /does not load on its own: ReferenceError: document is not defined/);
assert.match(failures.find((f) => f.startsWith("screens/ticks.js")), /does not load on its own: still running after load/);
} finally {
fs.rmSync(dir, { recursive: true, force: true });
}
});
// A screen reaches the rest of the page through ../state.js and the pure
// modules beside it, never through another screen: only core.js (the render
// loop, which draws every screen) imports screens, and only app.js (the
// entry) imports core.js. A screen's own components are not screens: files
// under a subdirectory of screens/ (screens/agents/) may be imported by the
// screen they serve and by each other, but never the other way, and never a
// top-level screen file. Each import that breaks that is named.
function pageImportProblems(pub) {
const problems = [];
for (const p of sourceFiles(pub).filter((f) => f.endsWith(".js") && (!f.includes("/") || f.startsWith("screens/")))) {
const text = fs.readFileSync(path.join(pub, p), "utf8");
for (const m of text.matchAll(/^\s*(?:import|export)\b[^;]*?\bfrom\s*["']([^"']+)["']|\bimport\(\s*["']([^"']+)["']\s*\)|^\s*import\s*["']([^"']+)["']/gm)) {
const spec = m[1] || m[2] || m[3];
if (!spec.startsWith(".")) continue;
const target = path.posix.join(path.posix.dirname(p), spec);
if (target === "screens/core.js" && p !== "app.js") problems.push(`${p} imports ${spec}: only app.js imports core.js`);
else if (p.startsWith("screens/") && p !== "screens/core.js" && /^screens\/[^/]+\.js$/.test(target))
problems.push(`${p} imports ${spec}: a screen imports ../state.js and the modules beside it, never another screen`);
}
}
return problems;
}
test("shape: a screen never imports another screen, and only app.js imports core.js", () => {
assert.deepEqual(pageImportProblems(path.join(CONSOLE_DIR, "public")), []);
});
test("shape: the import check names a screen that imports another, and any file but app.js importing core.js", () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-imports-"));
try {
fs.mkdirSync(path.join(dir, "screens"));
const put = (rel, text) => fs.writeFileSync(path.join(dir, rel), text);
put("app.js", 'import { render } from "./screens/core.js";\n');
put("state.js", "export const page = {};\n");
put("render.js", "export const el = () => null;\n");
put("screens/core.js", 'import { a } from "./a.js";\nimport { page } from "../state.js";\n');
put("screens/a.js", 'import { b } from "./b.js";\nimport { page } from "../state.js";\nimport { el } from "../render.js";\n');
put("screens/b.js", 'import { page } from "../state.js";\n');
put("screens/c.js", 'import { render } from "./core.js";\n');
put("helper.js", 'import { render } from "./screens/core.js";\n');
put("screens/d.js", 'import "./b.js";\n');
assert.deepEqual(pageImportProblems(dir).sort(), [
"helper.js imports ./screens/core.js: only app.js imports core.js",
"screens/a.js imports ./b.js: a screen imports ../state.js and the modules beside it, never another screen",
"screens/c.js imports ./core.js: only app.js imports core.js",
"screens/d.js imports ./b.js: a screen imports ../state.js and the modules beside it, never another screen",
]);
} finally {
fs.rmSync(dir, { recursive: true, force: true });
}
});
// The page's CSP refuses style attributes, so one set from script is dropped
// on the floor in the browser. Every page module, wherever a split moves the
// code that draws.
test("shape: no page module sets a style attribute from script", () => {
const pub = path.join(CONSOLE_DIR, "public");
const offenders = sourceFiles(pub)
.filter((p) => p.endsWith(".js"))
.filter((p) => /setAttribute\(\s*["']style["']/.test(fs.readFileSync(path.join(pub, p), "utf8")));
assert.deepEqual(offenders, []);
});
// Every URL the server's old `if` chain matched, in its order, so a route lost
// or moved in routes.mjs fails here by name: several match by prefix, and the
// token gate sits after the first two. SERVABLE stands for the page's own files
// and WORKSPACE_EDITS for /workspace/add, /edit and /remove. The git board has
// no routes of its own: its buttons are sends (`__git`), through /submit.
const ROUTE_ORDER = [
"/health", "/s/", "/handover", "/", "SERVABLE", "/overview", "/agents-doc", "/prototypes", "/prototype", "/handoff", "/version", "/state", "/events", "/draft",
"/looks", "/looks", "/subagents", "/learning/pause", "/learning/state", "/learning/lessons", "/pr-host", "/models", "/models", "/agents", "/agents", "/agents/test", "/agents/use-path", "/cleanup", "/upload",
"/notepad", "/notepad/text", "/notepad/image", "/notepad/thumb", "/notepad/image/delete", "/notepad/tab",
"/notepad/tab/rename", "/notepad/tab/delete", "/notepad/tab/order", "/notepad/tab/last", "/notepad/tab/sent", "/notepad/images/",
"/attachments/", "/shots/", "/uploads/", "/submit", "/open-link", "/open-prototype", "/chat", "/chat/decision", "/workspace",
"WORKSPACE_EDITS", "/workspace/scope", "/workspace/browse", "/loop-setup", "/loop-setup", "/spec-carry", "/cancel", "/ping", "/bye",
];
test("shape: routes.mjs lists every URL the server answers, in order", () => {
const routes = fs.readFileSync(path.join(CONSOLE_DIR, "routes.mjs"), "utf8");
const start = routes.indexOf("const ROUTES = [");
const list = routes.slice(start, routes.indexOf("\n];", start));
const entries = list
.split("\n")
.filter((line) => /^\s*\{/.test(line))
.map((line) => (line.match(/path: "([^"]*)"|startsWith\("([^"]*)"\)|\b(SERVABLE|WORKSPACE_EDITS)\b/) || []).slice(1).find(Boolean));
assert.deepEqual(entries, ROUTE_ORDER);
const edits = routes.match(/const WORKSPACE_EDITS = \{([^}]*)\}/)[1];
for (const p of ["/workspace/add", "/workspace/edit", "/workspace/remove"]) assert.ok(edits.includes(`"${p}"`), `${p} is a workspace edit`);
});
// Each file split out of lib.mjs, imported first and alone in a fresh
// process: a module-scope read of a value from a file still loading (an
// import cycle) throws here, naming the file, before it reaches a real run.
const SPLIT_FILES = ["files.mjs", "sessions.mjs", "scan.mjs", "patches.mjs", "inbox.mjs", "workspace.mjs", "settings.mjs"];
test("shape: every file split out of lib.mjs loads first and alone", () => {
for (const f of SPLIT_FILES) {
const url = pathToFileURL(path.join(CONSOLE_DIR, f)).href;
const r = spawnSync(process.execPath, ["--input-type=module", "-e", `await import(${JSON.stringify(url)});`], { encoding: "utf8" });
assert.equal(r.status, 0, `${f} does not load on its own: ${r.stderr.trim().split("\n").find((l) => /Error/.test(l)) || r.stderr}`);
}
});
// app.js is the entry and nothing else, so no test may read it as text: what a
// screen does is tested by driving the page, and what a screen file holds is
// read from that screen. A statement that both reads a file and names app.js
// is a read (a fetch of /app.js, or a fixture file called app.js, is not).
const SCRIPTS_DIR = path.join(ROOT, "scripts");
// parse-check.mjs only parses the entry, so it may name it.
const MAY_NAME_APP_JS = new Set(["parse-check.mjs"]);
// One statement that reads and names app.js, or a read helper handed it
// (`web("app.js")`, `publicSource("public/app.js")`), or a path to it
// under public/, in any file that also reads files.
function appJsReaders(dir) {
return fs
.readdirSync(dir)
.filter((f) => f.endsWith(".mjs") && f !== "test-web-console-shape.mjs" && !MAY_NAME_APP_JS.has(f))
.filter((f) => {
const text = fs.readFileSync(path.join(dir, f), "utf8");
// A bare readFileSync/readFile only counts against the web console's
// own public/app.js, named somewhere in the same statement: otherwise
// this would also catch a test reading some other app.js entirely,
// such as plan2code-app/ui/app.js (the desktop app's, a different file
// with its own shape rules in its own test). publicSource() implies
// the public dir by its own name, so any app.js it is handed counts.
const oneStatement = text
.split(";")
.some(
(statement) =>
/["'/]app\.js["']/.test(statement) &&
(/\bpublicSource\s*\(/.test(statement) || (/\b(readFileSync|readFile)\s*\(/.test(statement) && /\bpublic\b/.test(statement)))
);
const handedToAHelper = /\w\(\s*["'](?:(?:src\/web-console\/)?public\/)?app\.js["']\s*\)/.test(text);
const publicPath = /["']public["']\s*,\s*["']app\.js["']|\bpublic\/app\.js/.test(text) && /\breadFile(Sync)?\b/.test(text);
return oneStatement || handedToAHelper || publicPath;
})
.map((f) => `${f} reads public/app.js as text: test the behavior in a page test, or read the screen file that holds it`);
}
test("shape: no test in scripts/ reads public/app.js as text", () => {
assert.deepEqual(appJsReaders(SCRIPTS_DIR), []);
});
test("shape: the app.js check names the test file that reads it", () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-shape-"));
try {
fs.writeFileSync(path.join(dir, "test-fine.mjs"), 'const r = await fetch(base + "/app.js");\nfs.appendFileSync(path.join(d, "src", "app.js"), "x");\n');
assert.deepEqual(appJsReaders(dir), []);
fs.writeFileSync(path.join(dir, "test-reads-it.mjs"), 'const app = fs.readFileSync(path.join(ROOT, "public", "app.js"), "utf8");\n');
assert.deepEqual(appJsReaders(dir), ["test-reads-it.mjs reads public/app.js as text: test the behavior in a page test, or read the screen file that holds it"]);
fs.rmSync(path.join(dir, "test-reads-it.mjs"));
fs.writeFileSync(path.join(dir, "test-alias.mjs"), 'const web = (f) => fs.readFileSync(path.join(ROOT, "public", f), "utf8");\nconst app = web("app.js");\n');
assert.deepEqual(appJsReaders(dir), ["test-alias.mjs reads public/app.js as text: test the behavior in a page test, or read the screen file that holds it"]);
} finally {
fs.rmSync(dir, { recursive: true, force: true });
}
});
// The stylesheet is many files under public/styles/, joined by the server into
// the one /app.css the page asks for. CSS_ORDER is the one place the cascade
// order is stated: every file in it exists, each once, and no file in the folder
// is left out of it or served on its own.
test("shape: CSS_ORDER names every file in public/styles/ once, and none is served on its own", async () => {
const { CSS_ORDER, SERVABLE } = await import("../src/web-console/static.mjs");
const dir = path.join(CONSOLE_DIR, "public", "styles");
assert.ok(CSS_ORDER.length > 0, "CSS_ORDER lists files");
assert.equal(new Set(CSS_ORDER).size, CSS_ORDER.length, "no file is listed twice");
for (const f of CSS_ORDER) assert.ok(fs.existsSync(path.join(dir, f)), `CSS_ORDER lists ${f}, which is not in public/styles/`);
const onDisk = fs.readdirSync(dir).filter((f) => f.endsWith(".css")).sort();
assert.deepEqual([...CSS_ORDER].sort(), onDisk, "public/styles/ holds exactly the files CSS_ORDER lists");
for (const rel of SERVABLE) assert.ok(!rel.startsWith("styles/") && !CSS_ORDER.includes(rel), `${rel} must not be served on its own`);
});
// The files tables in the AGENTS-architecture-*.md area files give every console file a row,
// so a contributor finds where a job lives without searching. A row's first
// cell names the file by its path under src/web-console/ (backticked; one cell
// may name several files, joined by "·").
const DOCS_DIR = path.join(ROOT, ".agents-docs");
// Every architecture file (the index and its area files): the tables run across several.
function architectureMarkdown() {
return fs.readdirSync(DOCS_DIR)
.filter((f) => /^AGENTS-architecture(-[a-z-]+)?\.md$/.test(f))
.sort()
.map((f) => fs.readFileSync(path.join(DOCS_DIR, f), "utf8"))
.join("\n");
}
// The paths the files table names, from the first cell of each table row.
function tableFiles(markdown) {
const named = new Set();
for (const line of markdown.split("\n")) {
if (!line.startsWith("|")) continue;
const cell = line.split("|")[1] || "";
for (const m of cell.matchAll(/`([^`]+)`/g)) named.add(m[1]);
}
return named;
}
// One line per console file with no row in the table.
function undocumented(dir, markdown) {
const named = tableFiles(markdown);
return sourceFiles(dir)
.filter((p) => !named.has(p))
.map((p) => `${p} has no row in the files tables of the AGENTS-architecture area files: add one with its one-line job`);
}
test("shape: every console file has a row in the files tables of the AGENTS-architecture area files", () => {
const problems = undocumented(CONSOLE_DIR, architectureMarkdown());
assert.deepEqual(problems, []);
});
test("shape: the docs-table check names a file with no row, and passes one that has it", () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-docs-table-"));
try {
fs.mkdirSync(path.join(dir, "public"));
fs.writeFileSync(path.join(dir, "a.mjs"), "");
fs.writeFileSync(path.join(dir, "public", "b.js"), "");
const table = "| File | Role |\n|---|---|\n| `a.mjs` | the first |\n";
assert.deepEqual(undocumented(dir, table), [
"public/b.js has no row in the files tables of the AGENTS-architecture area files: add one with its one-line job",
]);
assert.deepEqual(undocumented(dir, `${table}| \`public/b.js\` · \`x.js\` | the second |\n`), []);
} finally {
fs.rmSync(dir, { recursive: true, force: true });
}
});
// A page test that reads a style or sets a scroll through locator.evaluate
// acts on whatever element the locator found, and a redraw can replace that
// element before the call runs: one off the page reads "" for every style and
// scrolls nothing anyone sees. On 3 and 4 core CI runners that failed a
// different page test at random on each run until the reads went through
// page-test-helpers.mjs's styleOf(), stylesOf() and scrollCard(), which retry
// until the element is still on the page. page.evaluate and waitForFunction
// look the element up afresh, so they are not flagged.
const RACY_STYLE = /(?<!\bpage)\.evaluate\(\s*\((\w+)\)\s*=>[^\n]*getComputedStyle\(\1\)/;
const RACY_SCROLL = /(?<!\bpage)\.evaluate\(\s*\((\w+)\)\s*=>\s*\(?\s*\1\.scrollTop\s*=[^=]/;
function racyPageReads(name, text) {
const problems = [];
text.split("\n").forEach((line, i) => {
if (RACY_STYLE.test(line)) problems.push(`${name}:${i + 1}: read the style with styleOf() or stylesOf() from page-test-helpers.mjs`);
if (RACY_SCROLL.test(line)) problems.push(`${name}:${i + 1}: scroll with scrollCard() from page-test-helpers.mjs`);
});
return problems;
}
test("shape: page tests read styles and set scrolls through the redraw-safe helpers", () => {
const dir = path.join(ROOT, "scripts");
const pageTests = fs.readdirSync(dir).filter((f) => /^test-web-console-page-.*\.mjs$/.test(f));
assert.ok(pageTests.length > 0, "the page tests were found");
const problems = pageTests.flatMap((f) => racyPageReads(f, fs.readFileSync(path.join(dir, f), "utf8")));
assert.deepEqual(problems, []);
});
test("shape: the redraw-safe check names a locator's style read and scroll, and passes page-wide ones", () => {
const racy = [
'await card.evaluate((el) => (el.scrollTop = 400));',
'const c = await chip.evaluate((b) => getComputedStyle(b).borderTopStyle);',
].join("\n");
assert.deepEqual(racyPageReads("x.mjs", racy), [
"x.mjs:1: scroll with scrollCard() from page-test-helpers.mjs",
"x.mjs:2: read the style with styleOf() or stylesOf() from page-test-helpers.mjs",
]);
const fine = [
'await s.page.evaluate(() => { document.getElementById("main").scrollTop = 4000; });',
'const top = await card.evaluate((el) => el.scrollTop === 0);',
'await s.page.waitForFunction(() => getComputedStyle(document.body).color);',
'const color = await s.page.evaluate((el) => getComputedStyle(el).color);',
].join("\n");
assert.deepEqual(racyPageReads("x.mjs", fine), []);
});
// The WCAG 2 contrast ratio of two "#rrggbb" colors.
function contrastRatio(a, b) {
const lum = (hex) => {
const [r, g, bl] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255).map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
return 0.2126 * r + 0.7152 * g + 0.0722 * bl;
};
const [hi, lo] = [lum(a), lum(b)].sort((x, y) => y - x);
return (hi + 0.05) / (lo + 0.05);
}
test("shape: the light theme's faintest ink, --ink-3, reads at 4.5:1 or better on --bg", () => {
const css = fs.readFileSync(path.join(CONSOLE_DIR, "public", "styles", "tokens.css"), "utf8");
// The first :root block is the light theme; the dark ones sit under their own selectors.
const light = css.match(/^:root \{([^}]*)\}/m);
assert.ok(light, "tokens.css opens with a :root block");
const token = (name) => {
const m = light[1].match(new RegExp(`--${name}:\\s*(#[0-9a-fA-F]{6})\\s*;`));
assert.ok(m, `--${name} is a #rrggbb color in the light :root block`);
return m[1];
};
const ratio = contrastRatio(token("ink-3"), token("bg"));
assert.ok(ratio >= 4.5, `--ink-3 ${token("ink-3")} on --bg ${token("bg")} is ${ratio.toFixed(2)}:1, under 4.5:1`);
});