@leonidstern/census 0.0.0-stage → 0.2.0

package/cli/playwright.mjs

@@ -0,0 +1,63 @@
+// The census inside your own Playwright tests: after your sign-in, setup and steps, read the page you are on.
+//
+//   import { census, lines, save } from "census/playwright";
+//   const home = await census(page, { rules, sources: true });
+//   console.log(lines(home));
+//   save("census-out", { home });   // home.txt and census.json, for census diff
+//
+// Playwright isn't a dependency: you pass your own page. Forced hover, pressed and focus colors need Chromium (they
+// go through Chrome's DevTools Protocol); in Firefox and WebKit the census reads them from the CSS rules.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { forceStates, mapPlaces, pageMapper } from "./read.mjs";
+import { censusLines, mergeCensus } from "../dist/census.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+let script;
+
+/**
+ * The census of the page as it is now (a Census: groups and, for census diff, each element's look).
+ * - rules: your design system's values (rules.json's shape)
+ * - states: "force" (default; Chromium only, else "rules") or "rules"
+ * - sources: true adds "@ file:line" where each part that needs a fix was used (a dev build), mapped through the
+ *   page's source maps; root: the project folder, to write the paths relative to it (default: the current one)
+ * - hide: a selector of elements to hide first (a dev overlay, a cookie banner)
+ * - selector: read only this element and what is inside it
+ */
+export async function census(page, { rules = {}, states = "force", sources = false, root, hide, selector } = {}) {
+  script ??= readFileSync(join(here, "../dist/census.js"), "utf8");
+  // an evaluate runs in the page's own world, past its Content-Security-Policy, and changes nothing but window.census
+  if (!(await page.evaluate(() => !!window.census))) await page.evaluate(script);
+  if (hide) await page.evaluate((h) => { const s = document.createElement("style"); s.id = "census-hide"; s.textContent = `${h}{display:none!important}`; document.head.append(s); }, hide);
+  const cdp = states === "force" ? await page.context().newCDPSession(page).catch(() => null) : null;
+  try {
+    if (cdp) {
+      await cdp.send("DOM.enable"); await cdp.send("CSS.enable");
+      let root;
+      await forceStates({
+        evaluate: (fn, arg) => page.evaluate(fn, arg),
+        async nodes(sel) { root ??= (await cdp.send("DOM.getDocument", { depth: 0 })).root.nodeId; return (await cdp.send("DOM.querySelectorAll", { nodeId: root, selector: sel })).nodeIds; },
+        force: (ids, classes) => Promise.all(ids.map((nodeId) => cdp.send("CSS.forcePseudoState", { nodeId, forcedPseudoClasses: classes }))),
+      });
+    }
+    const data = await page.evaluate(([r, sel]) => window.census.data(r, sel), [{ ...rules, sources, items: true }, selector]);
+    if (!sources) return data;
+    const origin = new URL(page.url()).origin;
+    return mapPlaces(data, pageMapper(page, new Set(/^https?:/.test(origin) ? [origin] : []), root ?? process.cwd()));
+  } finally {
+    if (hide) await page.evaluate(() => document.getElementById("census-hide")?.remove()).catch(() => {});
+    await cdp?.detach().catch(() => {});
+  }
+}
+
+/** A census as text, the way the CLI writes it. */
+export const lines = (data) => censusLines(data).join("\n");
+
+/** Writes <name>.txt for each page, all.txt (the pages merged) when there are several, and census.json, as the CLI does. */
+export function save(dir, pages) {
+  mkdirSync(dir, { recursive: true });
+  for (const [name, data] of Object.entries(pages)) writeFileSync(join(dir, `${name}.txt`), `${lines(data)}\n`);
+  if (Object.keys(pages).length > 1) writeFileSync(join(dir, "all.txt"), `${lines(mergeCensus(pages))}\n`);
+  writeFileSync(join(dir, "census.json"), JSON.stringify(pages));
+}

package/cli/read.mjs

@@ -0,0 +1,59 @@
+// What a capture does in a page, for any driver: the CLI's own DevTools client and the Playwright helper. A `page`
+// here has evaluate(fn, arg), and for forced states nodes(selector) → protocol node ids and force(nodeIds, classes).
+import { mapSources, sourceMapper } from "./sourcemap.mjs";
+
+// Chrome forces each state on each control in view (hover and press on everything above it too, as a real pointer
+// would), with transitions off, and the census reads the control's colors in that state. Controls alike are forced
+// once (census.forceMark). Each step replaces the last forcing, so a control takes 4 reads and 3 forcings. Returns how
+// many controls were forced.
+export async function forceStates(page) {
+  await page.evaluate(() => { const s = document.createElement("style"); s.id = "census-still"; s.textContent = "*,*::before,*::after{transition:none!important;animation-play-state:paused!important}"; document.head.append(s); });
+  const step = (i, read, next) => page.evaluate(([j, r, n]) => window.census.forceRead(j, r, n), [i, read, next]);
+  try {
+    const n = await page.evaluate(() => window.census.forceMark());
+    for (let i = 0; i < n; i++) {
+      const [el] = await page.nodes(`[data-census-f="${i}"]`);
+      if (!el) continue;
+      const up = await page.nodes(`[data-census-up~="${i}"]`);
+      await step(i, null, "hover");
+      await page.force([el, ...up], ["hover"]);
+      await step(i, "hover", "pressed");
+      await page.force([el, ...up], ["hover", "active"]);
+      await step(i, "pressed", "focus");
+      await page.force(up, []);
+      await page.force([el], ["focus", "focus-visible"]);
+      await step(i, "focus", null);
+      await page.force([el], []);
+    }
+    return n;
+  } finally {
+    await page.evaluate(() => { window.census.forceDone(); document.getElementById("census-still")?.remove(); });
+  }
+}
+
+/**
+ * A source mapper that fetches maps through the page (its cookies, its cache), only from `origins` (a page's stack
+ * frames could name any address), with no redirects and at most 64 MB a file.
+ */
+export function pageMapper(page, origins, root = process.cwd()) {
+  return sourceMapper(async (u) => {
+    let url;
+    try { url = new URL(u); } catch { return null; }
+    if (!origins.has(url.origin)) return null;
+    return page.evaluate(async (h) => {
+      try {
+        const r = await fetch(h, { redirect: "error", credentials: "same-origin" });
+        if (!r.ok || Number(r.headers.get("content-length") ?? 0) > 64e6) return null;
+        const t = await r.text();
+        return t.length > 64e6 ? null : t;
+      } catch { return null; }
+    }, url.href).catch(() => null);
+  }, root);
+}
+
+/** Every " @ {bundle frames}" place in a census (or a map of them) mapped to its file and line. */
+export async function mapPlaces(v, map) {
+  return typeof v === "string" ? (v.includes(" @ ") ? mapSources(v, map) : v)
+    : Array.isArray(v) ? Promise.all(v.map((x) => mapPlaces(x, map)))
+    : v && typeof v === "object" ? Object.fromEntries(await Promise.all(Object.entries(v).map(async ([k, x]) => [k, await mapPlaces(x, map)]))) : v;
+}

package/cli/sourcemap.mjs

@@ -0,0 +1,110 @@
+// Bundled-code places ("http://host/chunk.js:120:33") back to the app's files ("src/ui/Header.tsx:42"),
+// through the source maps the page serves. Plain source map v3, index maps (sections) included; no dependencies.
+
+const B64 = new Map([..."ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"].map((c, i) => [c, i]));
+
+/** One line of mappings as [generated column, source, line, column] segments (absolute values). */
+function decode(mappings) {
+  const lines = [];
+  let src = 0, line = 0, col = 0;
+  for (const text of mappings.split(";")) {
+    const segs = [];
+    let gen = 0;
+    for (const seg of text.split(",")) {
+      if (!seg) continue;
+      const v = [];
+      for (let i = 0, shift = 0, val = 0; i < seg.length; i++) {
+        const d = B64.get(seg[i]);
+        val += (d & 31) << shift;
+        if (d & 32) shift += 5;
+        else { v.push(val & 1 ? -(val >>> 1) : val >>> 1); val = 0; shift = 0; }
+      }
+      gen += v[0];
+      if (v.length >= 4) { src += v[1]; line += v[2]; col += v[3]; segs.push([gen, src, line, col]); }
+    }
+    lines.push(segs);
+  }
+  return lines;
+}
+
+/** Where a 1-based line and column of the generated file came from: { source, line } or null. */
+function lookup(map, line, col) {
+  if (map.sections) {
+    let best = null;
+    for (const s of map.sections) {
+      const o = s.offset;
+      if (o.line + 1 < line || (o.line + 1 === line && o.column <= col - 1)) best = s;
+      else break;
+    }
+    if (!best) return null;
+    const o = best.offset;
+    return lookup(best.map, line - o.line, line - 1 === o.line ? col - o.column : col);
+  }
+  map._lines ??= decode(map.mappings ?? "");
+  const segs = map._lines[line - 1];
+  if (!segs?.length) return null;
+  let hit = null;
+  for (const s of segs) { if (s[0] <= col - 1) hit = s; else break; }
+  hit ??= segs[0];
+  const source = (map.sourceRoot ? map.sourceRoot.replace(/\/?$/, "/") : "") + map.sources[hit[1]];
+  return { source, line: hit[2] + 1 };
+}
+
+/** A source path as the app's own: bundler prefixes off, relative to the project. */
+export function cleanSource(s, root = process.cwd()) {
+  let p = decodeURIComponent(s)
+    .replace(/^(turbopack|webpack|webpack-internal):\/\/\/?(\[project\]\/|_N_E\/|\(app-pages-browser\)\/)?/, "")
+    .replace(/^file:\/\//, "")
+    .replace(/\?.*$/, "")
+    .replace(/^\.\//, "");
+  if (p.startsWith(root + "/")) p = p.slice(root.length + 1);
+  return p;
+}
+
+/**
+ * A mapper for one capture: `get(url)` fetches a file as text (through the browser context, so a signed-in
+ * page's chunks come too). map("url:line:col") gives "src/x.tsx:42", or null when there is no map.
+ */
+export function sourceMapper(get, root) {
+  const maps = new Map();
+  const mapOf = async (url) => {
+    if (maps.has(url)) return maps.get(url);
+    let map = null;
+    try {
+      const js = await get(url);
+      const ref = /\/[/*][#@]\s*sourceMappingURL=([^\s*]+)\s*(?:\*\/)?\s*$/.exec(js ?? "")?.[1];
+      if (ref) {
+        const text = ref.startsWith("data:") ? Buffer.from(ref.slice(ref.indexOf(",") + 1), /;base64,/.test(ref) ? "base64" : "utf8").toString("utf8") : await get(new URL(ref, url).href);
+        map = text ? JSON.parse(text) : null;
+      }
+    } catch { map = null; }
+    maps.set(url, map);
+    return map;
+  };
+  return async (place) => {
+    const m = /^(.*):(\d+):(\d+)$/.exec(place);
+    if (!m) return null;
+    const map = await mapOf(m[1]);
+    const hit = map && lookup(map, +m[2], +m[3]);
+    return hit ? `${cleanSource(hit.source, root)}:${hit.line}` : null;
+  };
+}
+
+/**
+ * The census text with its places mapped: "{frame frame frame}" (React 19's stack at the use site) becomes the
+ * first frame that maps into the app's own files; a lone "url:line:col" after " @ " becomes its file and line.
+ */
+export async function mapSources(text, map) {
+  const groups = [...new Set(text.match(/ @ \{[^{}]+\}| @ (?:https?|file):\/\/\S+:\d+:\d+/g) ?? [])];
+  const said = new Map();
+  for (const g of groups) {
+    const frames = g.slice(3).replace(/^\{|\}$/g, "").split(" ");
+    let out = null;
+    for (const f of frames) {
+      const s = await map(f);
+      if (s && !/node_modules|^\[externals\]|^\[turbopack\]/.test(s)) { out = s; break; }
+    }
+    said.set(g, out ? ` @ ${out}` : "");
+  }
+  return text.replace(/ @ \{[^{}]+\}| @ (?:https?|file):\/\/\S+:\d+:\d+/g, (g) => said.get(g) ?? "");
+}

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/census.d.ts

@@ -0,0 +1,193 @@
+import { type CheckSetting, type Finding } from "./findings";
+export declare const ownId: (el: Element) => string;
+export declare function nameOf(el: Element): string;
+/**
+ * The screen as lines, for a reader that can't see it: "window 1440x860",
+ * one line per region ("#toolbar 0,0 1440x52"), then what looks wrong:
+ * "cut-text" (its words don't fit and are clipped), "overlap" (two texts
+ * drawn over each other), "outside" (a region past the window's edge),
+ * "wrapped" (a row's items dropped onto another line), "no-edge" (a filled
+ * button the color of what's behind it), "faint" (words or an icon too close
+ * to the color behind them: contrast from computed styles, no pixels),
+ * "faded" (a control see-through but not turned off), "squeezed" (a list
+ * meant to scroll given almost no height), "covered" (something solid over a
+ * control's middle).
+ * Drawn things (a canvas) show only as their box; the page's state says
+ * what's in them. Words come only from the app's own controls
+ * (buttons, menu items, headings), never from what people wrote; mark
+ * anything else private with data-census-private. About 50 elements a millisecond; run it once, on Send.
+ */
+export declare function layoutLines(root?: Element, cap?: number, skip?: (el: Element) => boolean, faint?: number): string[];
+/** What shows behind an element, from computed styles: its own background color, else its ancestors'. For a canvas whose background is CSS and not drawn. */
+export declare function behind(el: Element | null): [number, number, number, number];
+/** A text-align said by the writing direction: start, end, center or justify. */
+export declare function sayAlign(a: string, dir: string): string;
+/**
+ * How a box lays out its children, as a key: "row gap 8 pad 8 16 items center", "grid 3 cols gap 0/16", "column gaps
+ * 12-16 (margins)", or a filled box's padding, "box pad 16". The gaps are measured between the children as drawn, so
+ * margins count too, and the key says when they, not gap, make the space. Null for a box that lays nothing out.
+ */
+export declare function layoutOf(el: Element, cs: CSSStyleDeclaration, r: DOMRect, filled: boolean): {
+    key: string;
+    kids: string;
+} | null;
+/**
+ * A design system's allowed values, to mark what is off it. Colors as CSS
+ * colors; sizes in px. `parts`: the design system's part names, so a place
+ * is named by its part (Button) rather than the component around it, and a
+ * native control that no listed part drew says so. `shadows`: its named
+ * box-shadows. `ignore`: a selector for subtrees to leave out. `foreign:
+ * false` keeps what no component drew (by default, on a page with component
+ * names, such a subtree with controls in it is named once and left out).
+ * `closed`: also what pop-ups not opened yet would look like (React only).
+ * `sources`: " @ file:line" where a place's part was used, on the places that
+ * need a fix (set where used, off the system, a part in two looks).
+ * `items`: also each element's own look (Census.items), for diffCensus.
+ * `extends`: "recommended@1" turns on the accessibility checks, "best-practice@1" the max check (findings.ts CHECKS);
+ * either a name or a list of them. `checks` sets one check's level and number ("off", "rule", a number, or
+ * ["rule", number]).
+ * `max`: how many distinct values a group may hold (findings.ts MAX_DEFAULTS), by census group name — { "fill": 16 },
+ * or "off" for a group. The max check is on by default when rules.json gives no values at all, so a run with no file
+ * still says something.
+ */
+export type StyleRules = {
+    colors?: Record<string, string>;
+    type?: string[];
+    radii?: number[];
+    parts?: string[];
+    shadows?: Record<string, string>;
+    ignore?: string;
+    foreign?: boolean;
+    closed?: boolean;
+    sources?: boolean;
+    items?: boolean;
+    extends?: string | string[];
+    checks?: Record<string, CheckSetting>;
+    max?: Record<string, number | "off">;
+    /** what a box of a role must look like, by ARIA role (dialog, menu, listbox, tooltip) or part name: a color name, a shadow name, a corner in px */
+    roles?: Record<string, {
+        fill?: string;
+        shadow?: string;
+        radius?: number;
+    }>;
+    /** the color names text may use (icons aside) */
+    text?: string[];
+    /** what a state does to a control's fill: "wash white-5" (that color laid over the resting fill) or a color name */
+    states?: Record<string, string>;
+    /** parts that must no longer be on screen */
+    legacy?: string[];
+    /** the text colors each fill takes, by color name */
+    pairs?: Record<string, string[]>;
+    /** the lowest contrast text may have; 2 when not given */
+    contrast?: number;
+};
+/** The census as data: groups of counted values with a few places each. censusLines writes it out; mergeCensus joins pages. */
+export type CensusLook = {
+    state: string;
+    shape: string;
+    skin: string;
+    say: string;
+    n: number;
+    at: string[];
+    lo?: number;
+    hi?: number;
+};
+export type CensusRow = {
+    key: string;
+    n: number;
+    note?: string;
+    at: string[];
+    looks?: CensusLook[];
+    flag?: boolean;
+};
+export type CensusGroup = {
+    name: string;
+    what?: string;
+    rows: CensusRow[];
+    more?: number;
+};
+/** One element's look, for a diff between two captures (rules.items): `id` names it with its words, `loose` without them. */
+export type CensusItem = {
+    id: string;
+    loose: string;
+    at: string;
+    box: [number, number, number, number];
+    look: Record<string, string>;
+};
+export type Census = {
+    head: string;
+    groups: CensusGroup[];
+    items?: CensusItem[]; /** a second read a moment later, by the capture */
+    again?: {
+        items?: CensusItem[];
+    };
+    findings?: Finding[]; /** the accessibility findings are in the text: rules asked for them (extends or checks); without, the text is as it always was */
+    report?: boolean;
+};
+/**
+ * A box-shadow as its layers: `rings` are the ones with no offset or blur
+ * (a line drawn as a shadow: "#ffffff1a 1px (ring)"), `rest` the real
+ * shadows ("0 4px 6px -1px #0000001a"). Layers that draw nothing (see-through,
+ * or all zero) are dropped.
+ */
+export declare function shadowLayers(css: string): {
+    rings: string[];
+    rest: string[];
+};
+/** The state a control says it is in (ARIA, data-state, disabled): "disabled", "selected", "open", or two of them; "" at rest. */
+export declare function stateOf(el: Element): string;
+/** A font stack said against the first one: what it adds and what it leaves out (whole, when they share little). */
+export declare function fontDiff(stack: string, first: string): string;
+/**
+ * The component that drew an element as its own root, with its variant
+ * props ("Button variant=secondary size=sm"): a `data-part` attribute (and
+ * `data-variant`, `data-size`) if the app sets one, else React's own
+ * component names, which dev builds keep. A part with no variant of its own
+ * takes its family's ("TabsTab of TabsList variant=secondary"), and a part
+ * drawn with another names both ("Badge variant=info < Text size=sm").
+ * Only short word-like prop values of the PART_PROPS keys, never text. ""
+ * when nothing says.
+ */
+export declare function partOf(el: Element, parts?: string[]): string;
+/** A selector's specificity as one number (ids, then classes, attributes and pseudo-classes, then types): :where() counts nothing, :is(), :not() and :has() their most specific branch. */
+export declare function specificity(sel: string): number;
+/** The census written out: one line a value, a group under its heading. */
+export declare function censusLines(c: Census): string[];
+/**
+ * Several pages' censuses as one: a value on more than one page is said
+ * once, with the pages it is on ("(all)", "(home+cart)"), its counts added
+ * and a place from each page, tagged "[home]".
+ */
+export declare function mergeCensus(pages: Record<string, Census>, rules?: StyleRules): Census;
+/**
+ * Every style the screen uses, counted, for a reader checking a design
+ * system without seeing it: font stacks, text styles ("type 14/500/20 ×38"),
+ * text, fill and line colors, corner radii, shadows, fields, control
+ * heights, the hover, pressed and focus colors the page's rules give each
+ * control, what a part's use site changed ("set where used"), pop-up layers,
+ * and each part with its looks by state. Each value names up to 3 places
+ * (role and the app's own words, the part that drew it, where, its box).
+ * Values nearly the same as a more used one are marked "near"; with rules,
+ * a value off them says OFF and names the nearest. Loading placeholders,
+ * controls under the pointer or focused when read (they wear a state),
+ * things caught mid-animation and what no component drew are counted apart.
+ * Then what the layout check finds. Only on request (a design check), never
+ * in a feedback bundle by default: it adds one hidden element to the page
+ * while it reads and takes it out again.
+ */
+export declare function styleLines(rules?: StyleRules, root?: Element, cap?: number): string[];
+/** styleLines as data (see Census). */
+export declare function styleData(rules?: StyleRules, root?: Element, cap?: number): Census;
+/**
+ * Marks the controls in view (data-census-f="i", the ones above them data-census-up="i") and reads their resting look;
+ * returns how many to force. A control like one already marked shares its readings and isn't marked.
+ */
+export declare function forceMark(): number;
+/**
+ * Control i, between two of Chrome's forcings: reads its look in the state just forced (`read`), takes off the
+ * attributes a kit sets from its own pointer handlers, then sets the ones of the state forced next (`next`). A press
+ * is read twice: as Chrome forces it, then with data-pressed too ("pressed-attr"), and the page's rules choose.
+ */
+export declare function forceRead(i: number, read: string | null, next: string | null): void;
+/** Takes the marks off. */
+export declare function forceDone(): void;