@nodii/dev 0.6.14 → 0.6.16

package/dist/vendor/ds-conformance.mjs

@@ -0,0 +1,921 @@
+// ds-conformance.mjs: the design-system conformance check (DEC-0034 MW6-14 to
+// MW6-17, as amended by DEC-0035, DEC-0036 and DEC-0045).
+//
+// Canonical source: design-system `infra/figma/ds-conformance.mjs`. Every copy
+// (Dev's submit gate, nodii-clis' `design check`) vendors these
+// exact bytes and pins their sha256 in a test, so a drift fails CI. Change it
+// in the design system first, then re-vendor.
+//
+// Pure and dependency-free: no imports, no I/O. It reads Figma REST /nodes
+// entries ({ document, components, componentSets, styles }) and returns
+// findings; the caller fetches.
+//
+//   checkConformance({ nodes, roles, mains, options })
+//     nodes:  the /nodes response's `nodes` map for the submitted node ids
+//     roles:  GET /design/roles rows ({ role, labels, componentName, nodeId,
+//             componentKey, variant, ... }); `variant` ({ prop: value })
+//             narrows a role to some variants of its set
+//     mains:  componentId (as the submitted file names it) -> the /nodes
+//             entry of that main component (from the library file for a
+//             remote component, from the same file for a local one), or
+//             null when it can't be resolved
+//     options: { library?: boolean, declaredRoles?: string[] }
+//     returns { version, findings, staleOverrides, libraryUpdatePending },
+//     each a list of { nodeId, check, detail }; only `findings` fail
+//   neededMains(nodes, mains, options) -> componentIds still to fetch; call
+//     it until it returns [] (each round can reveal instances inside slot
+//     content).
+
+export const VERSION = "1.0.3";
+
+/** @typedef {{ nodeId: string, check: string, detail: string }} Finding */
+/**
+ * @typedef {{ role: string, labels?: string[] | null,
+ *   componentName?: string | null, nodeId?: string | null,
+ *   componentKey?: string | null,
+ *   variant?: Record<string, string> | null }} RoleRow
+ */
+/**
+ * @typedef {{ document?: any, components?: Record<string, any>,
+ *   componentSets?: Record<string, any>, styles?: Record<string, any> }} NodesEntry
+ */
+
+// Fields an instance may override (text, swaps, variants, visibility, size,
+// layout, prototype links). Anything else listed in `overriddenFields` is a
+// visual override and fails unless its value equals the main's.
+const ALLOWED_FIELDS = new Set([
+  "name",
+  "characters",
+  "text",
+  "characterStyleOverrides",
+  "styleOverrideTable",
+  "lineTypes",
+  "lineIndentations",
+  "componentProperties",
+  "componentPropertyReferences",
+  "visible",
+  "width",
+  "height",
+  "size",
+  "layoutGrow",
+  "layoutAlign",
+  "layoutSizingHorizontal",
+  "layoutSizingVertical",
+  "layoutPositioning",
+  "primaryAxisSizingMode",
+  "counterAxisSizingMode",
+  "primaryAxisAlignItems",
+  "counterAxisAlignItems",
+  "itemSpacing",
+  "counterAxisSpacing",
+  "paddingLeft",
+  "paddingRight",
+  "paddingTop",
+  "paddingBottom",
+  "textAutoResize",
+  "textTruncation",
+  "maxLines",
+  "clipsContent",
+  "overflowDirection",
+  "constraints",
+  "transitionNodeID",
+  "transitionDuration",
+  "transitionEasing",
+  "interactions",
+  "reactions",
+  "exportSettings",
+  "pluginData",
+  "sharedPluginData",
+  // Choosing one of the library's variable modes (a size or density mode)
+  // is a mode, like a variant, not a look override.
+  "explicitVariableModes",
+  "minWidth",
+  "maxWidth",
+  "minHeight",
+  "maxHeight",
+  "layoutWrap",
+]);
+const TEXT_STYLE_FIELDS = new Set([
+  "fontSize",
+  "fontFamily",
+  "fontWeight",
+  "fontPostScriptName",
+  "fontStyle",
+  "italic",
+  "letterSpacing",
+  "lineHeightPx",
+  "lineHeightPercent",
+  "lineHeightPercentFontSize",
+  "lineHeightUnit",
+  "textCase",
+  "textDecoration",
+  "paragraphSpacing",
+  "paragraphIndent",
+  "textAlignHorizontal",
+  "textAlignVertical",
+]);
+// Overridden-field names that point at a node's `styles` map.
+const STYLE_FIELD = /^(inherit)?(Fill|Stroke|Text|Effect|Grid)StyleId$/i;
+
+const SURFACE_NAME = /^Surface \//;
+const CUSTOMER_HEADER =
+  /^(customer|client|contact|lead|applicant|candidate)s?( name)?$/i;
+const EXTERNAL_PLANE = /customer portal|partner room|external/i;
+// The viewer's own record (R5): the App Frame sidebar footer, the user menu
+// and the profile. Not any footer: a dialog or table footer can list others.
+const SELF_CONTAINER =
+  /sidebar ?footer|user button|user menu|account menu|profile/i;
+const SELF_TEXT = /\(you\)|^you$/i;
+const SIGNED_IN = /^(signed in( as\b.*)?|not you\?.*)$/i;
+// The signed-in account card (Account Context, kind=Account) shows the
+// viewer's own email.
+const SELF_COMPONENT = /^account context$/i;
+const NOT_A_PERSON = /^(you|the team)$/i;
+const MASKED = /[*•●]/;
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+const ROLE_MAILBOX =
+  /^(no-?reply|support|help|team|admin|info|billing|hello|contact|ops|security|privacy|legal)$/i;
+// A phone as people write one: international (+...) or grouped with
+// separators, never a bare run of digits inside an id ("v2413049671").
+const PHONE = /(?<![\w.+\-/])\+?\(?\d[\d ().-]{7,}\d(?![\w\-/])/g;
+// Without a "+", a phone is grouped the way numbers are dialled (98765 43210,
+// (555) 123-4567), not as an amount (1 000 000 000) or a date.
+const LOCAL_PHONE = /^(\(\d{3,5}\)[ .-]?|\d{3,5}[ .-])\d{3,5}([ .-]\d{2,5})?$/;
+const DATE = /^(\d{4}-\d{2}-\d{2}|\d{1,2}[-/.]\d{1,2}[-/.]\d{2,4})/;
+const ROLE_ANNOTATION = /\[role:([a-z0-9._-]+)\]/gi;
+
+/** "I12:34;56:78" -> ["12:34", "56:78"]; "12:34" -> ["12:34"]. */
+const segments = (id) => (id.startsWith("I") ? id.slice(1) : id).split(";");
+
+/**
+ * The id a descendant of `instanceId` has in that instance's main component,
+ * or null when `id` is not under it. The instance itself maps to the main's
+ * root (returned as "").
+ */
+function mainIdOf(instanceId, id) {
+  const outer = segments(instanceId);
+  const inner = segments(id);
+  if (inner.length < outer.length) return null;
+  for (let i = 0; i < outer.length; i++) if (inner[i] !== outer[i]) return null;
+  const rest = inner.slice(outer.length);
+  if (rest.length === 0) return "";
+  return rest.length === 1 ? rest[0] : `I${rest.join(";")}`;
+}
+
+const visibleNode = (n) => n && n.visible !== false;
+const visiblePaints = (paints) =>
+  Array.isArray(paints) &&
+  paints.some((p) => p && p.visible !== false && (p.opacity ?? 1) > 0);
+
+/**
+ * A value made comparable. `opaque` turns every variable id into one marker:
+ * a library variable is "VariableID:<key>/<id>" in a consuming file but
+ * "VariableID:<id>" in the library, and without the variables scope the two
+ * can't be matched, so across files a binding is compared by being bound,
+ * and the bound value by the resolved colour or number beside it.
+ */
+function normalise(value, opaque = false) {
+  if (typeof value === "string")
+    return opaque && value.startsWith("VariableID:") ? "VariableID:*" : value;
+  if (Array.isArray(value)) return value.map((v) => normalise(v, opaque));
+  if (value && typeof value === "object") {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const key of Object.keys(value).sort())
+      out[key] = normalise(value[key], opaque);
+    return out;
+  }
+  if (typeof value === "number") return Math.round(value * 1e4) / 1e4;
+  return value;
+}
+const KEYED_VARIABLE = /VariableID:[0-9a-f]{20,}\//;
+/** Equal, or equal but for variable ids written in another file's form. */
+function sameValue(a, b) {
+  const x = JSON.stringify(normalise(a));
+  const y = JSON.stringify(normalise(b));
+  if (x === y) return true;
+  if (KEYED_VARIABLE.test(x) === KEYED_VARIABLE.test(y)) return false;
+  return (
+    JSON.stringify(normalise(a, true)) === JSON.stringify(normalise(b, true))
+  );
+}
+const styleKeys = (node, styles) => {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const [kind, id] of Object.entries(node?.styles ?? {}))
+    out[kind] = styles?.[id]?.key ?? id;
+  return out;
+};
+
+/** The value a visual override field reads on a node, comparable across files. */
+function fieldValue(node, field, styles) {
+  if (STYLE_FIELD.test(field) || field === "styles")
+    return styleKeys(node, styles);
+  if (TEXT_STYLE_FIELDS.has(field) || field.startsWith("lineHeight"))
+    return node?.style?.[field];
+  // An image fill's picture is content (DEC-0048): only its scale mode,
+  // filters and opacity are look, so imageRef is left out of the comparison.
+  if (field === "fills" || field === "background")
+    return (node?.[field] ?? []).map((p) => {
+      if (p?.type !== "IMAGE") return p;
+      const { imageRef: _picture, gifRef: _gif, ...look } = p;
+      return look;
+    });
+  // A binding is judged per bound field: (un)binding a field the instance
+  // may override anyway (spacing, size) is that override, not a visual one.
+  if (field === "boundVariables") {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [key, value] of Object.entries(node?.boundVariables ?? {}))
+      if (!ALLOWED_FIELDS.has(key)) out[key] = value;
+    return out;
+  }
+  return node?.[field];
+}
+
+/** Every node in a document by id, with its parent. */
+function indexTree(root) {
+  /** @type {Map<string, any>} */
+  const byId = new Map();
+  /** @type {Map<string, any>} */
+  const parent = new Map();
+  const stack = [root];
+  while (stack.length > 0) {
+    const n = stack.pop();
+    if (!n || typeof n.id !== "string") continue;
+    byId.set(n.id, n);
+    // Children pushed last-first, so the walk (and the findings) follow
+    // document order.
+    const children = n.children ?? [];
+    for (let i = children.length - 1; i >= 0; i--) {
+      parent.set(children[i].id, n);
+      stack.push(children[i]);
+    }
+  }
+  return { byId, parent };
+}
+
+/** One submitted root, walked once, with the facts every check needs. */
+function analyse(entry, mains, library = false) {
+  const root = entry.document;
+  const components = entry.components ?? {};
+  const componentSets = entry.componentSets ?? {};
+  const { byId, parent } = indexTree(root);
+  /** @type {Map<string, ReturnType<typeof indexTree> | null>} */
+  const mainTrees = new Map();
+  const mainTree = (componentId) => {
+    if (!mainTrees.has(componentId)) {
+      const main = mains?.[componentId];
+      mainTrees.set(
+        componentId,
+        main?.document ? indexTree(main.document) : null,
+      );
+    }
+    return mainTrees.get(componentId) ?? null;
+  };
+  const ancestors = (n) => {
+    const out = [];
+    for (let p = parent.get(n.id); p; p = parent.get(p.id)) out.push(p);
+    return out;
+  };
+  /** The main node a node is drawn from by instance `inst`, if any. */
+  const mainNodeFor = (inst, id) => {
+    const tree = mainTree(inst.componentId);
+    const mainId = mainIdOf(inst.id, id);
+    if (!tree || mainId === null) return undefined;
+    return mainId === ""
+      ? mains[inst.componentId]?.document
+      : tree.byId.get(mainId);
+  };
+  /**
+   * A node is composed by the library when some library instance above it
+   * draws it from its main. Anything else (top-level layers, slot content,
+   * and everything inside an instance of a local component, which is the
+   * screen's own drawing) is the screen's. A library instance whose main
+   * can't be read counts as composing everything under it, so nothing is
+   * flagged on a guess. In the library file itself every component is local
+   * and every instance composes.
+   */
+  const composedMemo = new Map();
+  const composed = (n) => {
+    if (composedMemo.has(n.id)) return composedMemo.get(n.id);
+    let result = false;
+    for (const a of ancestors(n)) {
+      if (a.type !== "INSTANCE") continue;
+      if (!library && components[a.componentId]?.remote === false) continue;
+      const tree = mainTree(a.componentId);
+      if (!tree) {
+        result = true;
+        break;
+      }
+      if (mainNodeFor(a, n.id) !== undefined) {
+        result = true;
+        break;
+      }
+    }
+    composedMemo.set(n.id, result);
+    return result;
+  };
+  const shown = (n) =>
+    visibleNode(n) && ancestors(n).every((a) => visibleNode(a));
+  const componentOf = (inst) => components[inst.componentId] ?? null;
+  const setOf = (inst) => {
+    const c = componentOf(inst);
+    return c?.componentSetId ? (componentSets[c.componentSetId] ?? null) : null;
+  };
+  const componentLabel = (inst) =>
+    setOf(inst)?.name ?? componentOf(inst)?.name ?? inst.name;
+  return {
+    root,
+    components,
+    componentSets,
+    styles: entry.styles ?? {},
+    byId,
+    parent,
+    ancestors,
+    composed,
+    shown,
+    mainTree,
+    mainNodeFor,
+    componentOf,
+    setOf,
+    componentLabel,
+  };
+}
+
+/** Component ids whose mains the check still needs. */
+export function neededMains(nodes, mains = {}, options = {}) {
+  const want = new Set();
+  for (const entry of Object.values(nodes ?? {})) {
+    if (!entry?.document) continue;
+    const a = analyse(entry, mains, Boolean(options.library));
+    for (const n of a.byId.values()) {
+      if (n.type !== "INSTANCE" || !n.componentId) continue;
+      if (Object.prototype.hasOwnProperty.call(mains, n.componentId)) continue;
+      // The screen's own instances (for overrides and slot content), and
+      // every table header cell (for its fill).
+      if (!a.composed(n) || headerCell(a, n)) want.add(n.componentId);
+      // An overridden instance inside one may be a swap or a new variant,
+      // read against its own main.
+      if (!a.composed(n))
+        for (const o of n.overrides ?? []) {
+          const target = a.byId.get(o?.id);
+          if (!target) continue;
+          for (const p of [target, ...a.ancestors(target)]) {
+            if (p === n) break;
+            if (
+              p.type === "INSTANCE" &&
+              p.componentId &&
+              !Object.prototype.hasOwnProperty.call(mains, p.componentId)
+            )
+              want.add(p.componentId);
+          }
+        }
+    }
+  }
+  return [...want].sort();
+}
+
+function headerCell(a, inst) {
+  const c = a.componentOf(inst);
+  const set = a.setOf(inst);
+  if (/^table header$/i.test(set?.name ?? c?.name ?? "")) return true;
+  // Exactly a header part: a Command list's part=group-heading has no fill.
+  const part = inst.componentProperties?.part?.value;
+  if (typeof part === "string" && /^head(er)?$/i.test(part)) return true;
+  return /(^|,\s*)part=head(er)?(\s*,|$)/i.test(c?.name ?? "");
+}
+
+function matchesRole(a, inst, role, library) {
+  const c = a.componentOf(inst);
+  const set = a.setOf(inst);
+  const component =
+    (role.componentKey &&
+      (c?.key === role.componentKey || set?.key === role.componentKey)) ||
+    (library &&
+      (inst.componentId === role.nodeId ||
+        c?.componentSetId === role.nodeId)) ||
+    (set?.name ?? c?.name) === role.componentName;
+  if (!component) return false;
+  // Every variant pair the role names, in the variant's name or properties.
+  const pairs = (c?.name ?? "").split(",").map((x) => x.trim().toLowerCase());
+  return Object.entries(role.variant ?? {}).every(([prop, value]) => {
+    const want = `${prop}=${value}`.toLowerCase();
+    return (
+      pairs.includes(want) ||
+      String(inst.componentProperties?.[prop]?.value ?? "").toLowerCase() ===
+        String(value).toLowerCase()
+    );
+  });
+}
+
+/** Characters the screen chose: its own text, or an overridden label. */
+function screenText(a, n, overridden) {
+  return !a.composed(n) || overridden.has(n.id);
+}
+
+function textOf(n) {
+  return typeof n.characters === "string" ? n.characters.trim() : "";
+}
+
+/**
+ * @param {{ nodes: Record<string, NodesEntry | null>, roles?: RoleRow[],
+ *   mains?: Record<string, NodesEntry | null>,
+ *   options?: { library?: boolean, declaredRoles?: string[] } }} input
+ * @returns {{ version: string, findings: Finding[], staleOverrides: Finding[],
+ *   libraryUpdatePending: Finding[] }}
+ */
+export function checkConformance({
+  nodes,
+  roles: allRoles = [],
+  mains = {},
+  options = {},
+}) {
+  const library = Boolean(options.library);
+  // A role the library has no component for yet (MW6-10) matches nothing.
+  const roles = allRoles.filter((r) => r.nodeId && r.componentName);
+  /** @type {Finding[]} */
+  const findings = [];
+  /** @type {Finding[]} */
+  const staleOverrides = [];
+  /** @type {Finding[]} */
+  const libraryUpdatePending = [];
+  const seen = new Set();
+  const push = (list, nodeId, check, detail) => {
+    const key = `${nodeId}|${check}|${detail}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    list.push({ nodeId, check, detail });
+  };
+  const roleByKey = new Map(roles.map((r) => [r.role, r]));
+  const labelRoles = new Map();
+  for (const r of roles)
+    for (const label of r.labels ?? [])
+      labelRoles.set(label.trim().toLowerCase(), r);
+  const librarySetNames = new Set();
+  const usedRoles = new Set();
+
+  for (const entry of Object.values(nodes ?? {})) {
+    if (!entry?.document) continue;
+    const a = analyse(entry, mains, library);
+    for (const set of Object.values(a.componentSets))
+      if (set?.remote) librarySetNames.add(set.name);
+    // Every (node, field) the screen overrode on an instance it placed.
+    /** @type {Map<string, { fields: Set<string>, from: any }>} */
+    const overrideFields = new Map();
+    const overridden = new Set();
+    for (const n of a.byId.values()) {
+      if (n.type !== "INSTANCE" || a.composed(n)) continue;
+      for (const o of n.overrides ?? []) {
+        if (!o?.id) continue;
+        const held = overrideFields.get(o.id) ?? { fields: new Set(), from: n };
+        const fields = held.fields;
+        for (const f of o.overriddenFields ?? []) fields.add(f);
+        overrideFields.set(o.id, held);
+        if (fields.has("characters") || fields.has("text"))
+          overridden.add(o.id);
+      }
+    }
+
+    // instanceOverride: a visual override on a library instance, bound or
+    // not; one equal to the main's value is a stale mark (DEC-0035).
+    for (const [id, { fields, from }] of overrideFields) {
+      const node = a.byId.get(id);
+      if (!node || !a.shown(node)) continue;
+      const base = baselineInstance(a, mains, from, node);
+      if (!base) continue;
+      const mainNode = a.mainNodeFor(base, id);
+      if (!mainNode) continue;
+      const mainStyles = mains[base.componentId]?.styles ?? {};
+      const differ = [];
+      const equal = [];
+      for (const field of [...fields].sort()) {
+        if (ALLOWED_FIELDS.has(field)) continue;
+        if (exemptPaint(a, from, node, field)) continue;
+        const mine = fieldValue(node, field, a.styles);
+        const theirs = fieldValue(mainNode, field, mainStyles);
+        if (sameValue(mine, theirs)) equal.push(field);
+        else
+          differ.push(
+            `${field} ${shortValue(mine)} (main ${shortValue(theirs)})`,
+          );
+      }
+      const where = `on ${node.name} (${a.componentLabel(from)})`;
+      if (differ.length > 0)
+        push(
+          findings,
+          id,
+          "instanceOverride",
+          `${differ.join(", ")} overridden ${where}`,
+        );
+      if (equal.length > 0)
+        push(
+          staleOverrides,
+          id,
+          "instanceOverride",
+          `${equal.join(", ")} overridden ${where}, equal to the main: a stale mark`,
+        );
+    }
+
+    for (const n of a.byId.values()) {
+      if (!a.shown(n)) continue;
+      const own = !a.composed(n);
+
+      if (n.type === "INSTANCE")
+        for (const r of roles)
+          if (matchesRole(a, n, r, library)) usedRoles.add(r.role);
+
+      // tableHeaderFill (DEC-0036): every header cell keeps the library fill.
+      if (n.type === "INSTANCE" && headerCell(a, n)) {
+        const main = mains[n.componentId]?.document;
+        // The effective colour decides; the same colour on another variable
+        // id is an instance behind a library republish, not a failure.
+        if (main && !sameValue(n.fills ?? [], main.fills ?? []))
+          if (sameValue(paintColours(n.fills), paintColours(main.fills)))
+            push(
+              libraryUpdatePending,
+              n.id,
+              "libraryUpdatePending",
+              `${n.name} has the header colour on another variable id; accept the library update`,
+            );
+          else
+            push(
+              findings,
+              n.id,
+              "tableHeaderFill",
+              `${n.name} fill ${shortValue(n.fills)} differs from the library header fill ${shortValue(main.fills)} (${a.componentLabel(n)})`,
+            );
+        if (main && !visiblePaints(n.fills))
+          push(
+            findings,
+            n.id,
+            "tableHeaderFill",
+            `${n.name} has no visible header fill`,
+          );
+      }
+
+      // notFromLibrary: local parts and hand-drawn stand-ins, off the library.
+      if (!library && own) {
+        if (n.type === "COMPONENT" || n.type === "COMPONENT_SET") {
+          const setName =
+            n.type === "COMPONENT" ? a.parent.get(n.id)?.name : null;
+          if (!SURFACE_NAME.test(n.name) && !SURFACE_NAME.test(setName ?? ""))
+            push(
+              findings,
+              n.id,
+              "notFromLibrary",
+              `local ${n.type === "COMPONENT_SET" ? "component set" : "component"} ${n.name}`,
+            );
+        } else if (n.type === "INSTANCE") {
+          const c = a.componentOf(n);
+          const set = a.setOf(n);
+          if (
+            c &&
+            c.remote === false &&
+            !SURFACE_NAME.test(c.name ?? "") &&
+            !SURFACE_NAME.test(set?.name ?? "")
+          )
+            push(
+              findings,
+              n.id,
+              "notFromLibrary",
+              `instance of local component ${set?.name ?? c.name}`,
+            );
+        } else if (n.type === "FRAME" || n.type === "GROUP") {
+          // A frame named for a library part that holds none of it: the
+          // Table set is the cell set, so a "Table" frame of its cells is
+          // the library's own pattern, not a stand-in.
+          const named =
+            roles.find((r) => r.componentName === n.name) ||
+            librarySetNames.has(n.name);
+          const holdsIt =
+            named &&
+            [...indexTree(n).byId.values()].some(
+              (x) => x.type === "INSTANCE" && a.componentLabel(x) === n.name,
+            );
+          const drawn = visiblePaints(n.fills) || visiblePaints(n.strokes);
+          if (named && !holdsIt && drawn)
+            push(
+              findings,
+              n.id,
+              "notFromLibrary",
+              `frame named ${n.name} stands in for the library component`,
+            );
+          else if (handDrawnButton(n))
+            push(
+              findings,
+              n.id,
+              "notFromLibrary",
+              `hand-drawn button "${buttonText(n)}"`,
+            );
+        }
+      }
+
+      // roleMismatch by annotation: [role:<key>] in a layer name.
+      for (const match of n.name?.matchAll?.(ROLE_ANNOTATION) ?? []) {
+        const role = roleByKey.get(match[1]);
+        if (!role) continue;
+        if (n.type !== "INSTANCE" || !matchesRole(a, n, role, library))
+          push(
+            findings,
+            n.id,
+            "roleMismatch",
+            `${n.name} is annotated ${role.role} but is not a ${role.componentName}`,
+          );
+      }
+
+      if (n.type !== "TEXT") continue;
+      const text = textOf(n);
+
+      // roleMismatch by label: a mapped label on a button-like part that is
+      // not the role's component. The screen answers for a button it placed
+      // (even one whose variant carries the label) and for a label it
+      // overrode; a button a library block composes with its own label is
+      // the library's (MW6-17).
+      const role = labelRoles.get(text.toLowerCase());
+      if (role) {
+        const up = a.ancestors(n);
+        const holder = up
+          .slice(0, 3)
+          .find(
+            (x) =>
+              x.type === "INSTANCE" ||
+              ((x.type === "FRAME" || x.type === "COMPONENT") &&
+                (visiblePaints(x.fills) || visiblePaints(x.strokes))),
+          );
+        if (holder && (screenText(a, n, overridden) || !a.composed(holder))) {
+          // Stop at the first instance the screen placed: anything above it
+          // is a container, not the button.
+          const stop = up.findIndex(
+            (x) => x.type === "INSTANCE" && !a.composed(x),
+          );
+          const chain = (stop === -1 ? up : up.slice(0, stop + 1)).filter(
+            (x) => x.type === "INSTANCE",
+          );
+          if (!chain.some((inst) => matchesRole(a, inst, role, library)))
+            push(
+              findings,
+              holder.id,
+              "roleMismatch",
+              `"${text}" is drawn with ${holder.type === "INSTANCE" ? a.componentLabel(holder) : "a hand-drawn frame"}; ${role.role} is the ${role.componentName}`,
+            );
+        }
+      }
+
+      // otherPersonRevealed (DEC-0045). Never the viewer's own record (R5),
+      // never a colleague's display name on a staff surface (D1104).
+      if (
+        !screenText(a, n, overridden) ||
+        isSelf(a, n) ||
+        revealedByPermission(a, n)
+      )
+        continue;
+      for (const m of text.matchAll(EMAIL)) {
+        const local = m[0].split("@")[0] ?? "";
+        if (MASKED.test(local) || ROLE_MAILBOX.test(local)) continue;
+        push(findings, n.id, "otherPersonRevealed", `unmasked email ${m[0]}`);
+      }
+      for (const m of text.matchAll(PHONE)) {
+        const digits = m[0].replace(/\D/g, "");
+        if (DATE.test(m[0]) || MASKED.test(m[0])) continue;
+        const phoneShaped =
+          m[0].startsWith("+") || LOCAL_PHONE.test(m[0].trim());
+        if (phoneShaped && digits.length >= 10 && digits.length <= 15)
+          push(findings, n.id, "otherPersonRevealed", `unmasked phone ${m[0]}`);
+      }
+      if (
+        externalPlane(a, n) &&
+        nextToAvatar(a, n) &&
+        !NOT_A_PERSON.test(text) &&
+        !MASKED.test(text) &&
+        /\p{L}/u.test(text)
+      )
+        push(
+          findings,
+          n.id,
+          "otherPersonRevealed",
+          `"${text}" is named on an external plane; show "You" or "the team"`,
+        );
+    }
+
+    // otherPersonRevealed (b): a customer column shows names unmasked.
+    for (const header of a.byId.values()) {
+      if (
+        header.type !== "TEXT" ||
+        !CUSTOMER_HEADER.test(textOf(header)) ||
+        !a.shown(header)
+      )
+        continue;
+      // A column header sits in a table, list or grid; a "Customer" form
+      // label does not head anything.
+      const table = a
+        .ancestors(header)
+        .find((x) => /table|list|grid/i.test(x.name ?? ""));
+      // The header's cell bounds its column, unless the parent is the whole
+      // header row: then the header text's own box does.
+      const cell = a.parent.get(header.id);
+      const tableWidth =
+        table?.absoluteBoundingBox?.width ?? Number.POSITIVE_INFINITY;
+      const cellBox = cell?.absoluteBoundingBox;
+      const box =
+        cellBox && cellBox.width < tableWidth * 0.6
+          ? cellBox
+          : header.absoluteBoundingBox;
+      if (!table || !box) continue;
+      for (const n of indexTree(table).byId.values()) {
+        if (n.type !== "TEXT" || n.id === header.id || !a.shown(n)) continue;
+        if (!screenText(a, n, overridden)) continue;
+        const b = n.absoluteBoundingBox;
+        const text = textOf(n);
+        if (!b || b.y < box.y + box.height) continue;
+        const mid = b.x + b.width / 2;
+        if (mid < box.x || mid > box.x + box.width) continue;
+        if (
+          !/\p{L}{2}/u.test(text) ||
+          MASKED.test(text) ||
+          isSelf(a, n) ||
+          revealedByPermission(a, n)
+        )
+          continue;
+        push(
+          findings,
+          n.id,
+          "otherPersonRevealed",
+          `customer "${text}" shown unmasked under ${textOf(header)}`,
+        );
+      }
+    }
+  }
+
+  // roleMismatch by declared role: the brief named a role the screens never
+  // place.
+  const roots = Object.keys(nodes ?? {});
+  for (const declared of options.declaredRoles ?? []) {
+    const role = roleByKey.get(declared);
+    if (role && !usedRoles.has(role.role))
+      push(
+        findings,
+        roots[0] ?? "",
+        "roleMismatch",
+        `declared role ${role.role} has no ${role.componentName} instance`,
+      );
+  }
+  return { version: VERSION, findings, staleOverrides, libraryUpdatePending };
+}
+
+/**
+ * The instance whose main holds an overridden node's un-overridden value:
+ * the screen-placed instance carrying the override, or, below it, the
+ * deepest instance that was swapped or given another variant (its defaults
+ * come from its own main). Null when a main on the way can't be read.
+ */
+function baselineInstance(a, mains, from, node) {
+  const path = [node, ...a.ancestors(node)];
+  const top = path.indexOf(from);
+  if (top === -1) return null;
+  let base = from;
+  for (let i = top - 1; i >= 0; i--) {
+    const p = path[i];
+    if (p.type !== "INSTANCE") continue;
+    if (!mains[base.componentId]?.document) return null;
+    const counterpart = a.mainNodeFor(base, p.id);
+    const ownKey = a.components[p.componentId]?.key;
+    const mainKey = counterpart
+      ? mains[base.componentId]?.components?.[counterpart.componentId]?.key
+      : undefined;
+    if (!counterpart || ownKey !== mainKey) base = p;
+  }
+  return mains[base.componentId]?.document ? base : null;
+}
+
+const ICON = /^(icon|lucide)\//i;
+/**
+ * Design-system rulings on paint overrides: an icon takes its colour from
+ * where it sits (currentColor), so a bound fill or stroke on an Icon/ or
+ * lucide/ instance or its vectors is allowed (a Logo/ is not), and so is its
+ * stroke weight, which scales with the icon's size; a PiiText in
+ * mode=revealed inherits ink, so its fill may be set.
+ */
+function exemptPaint(a, from, node, field) {
+  if (field !== "fills" && field !== "strokes" && field !== "strokeWeight")
+    return false;
+  const path = [node, ...a.ancestors(node)];
+  const upTo = path.slice(0, path.indexOf(from) + 1);
+  const inIcon = upTo.some(
+    (x) => x.type === "INSTANCE" && ICON.test(a.componentLabel(x)),
+  );
+  // An icon's stroke weight scales with the size it is placed at.
+  if (field === "strokeWeight") return inIcon;
+  const bound = (node[field] ?? []).every((p) => p?.boundVariables?.color);
+  if (bound && inIcon) return true;
+  return field === "fills" && revealedByPermission(a, node);
+}
+const paintColours = (paints) =>
+  (paints ?? [])
+    .filter((p) => p && p.visible !== false)
+    .map((p) => p.color ?? null);
+
+/** A value as a finding shows it: a colour as hex, anything else as JSON. */
+function shortValue(value) {
+  const paint = Array.isArray(value) ? value.find((p) => p?.color) : null;
+  if (paint) {
+    const { r, g, b } = paint.color;
+    const hex = [r, g, b]
+      .map((c) =>
+        Math.round(c * 255)
+          .toString(16)
+          .padStart(2, "0"),
+      )
+      .join("");
+    return `#${hex.toUpperCase()}${paint.boundVariables ? " (bound)" : ""}`;
+  }
+  const text = JSON.stringify(value === undefined ? null : normalise(value));
+  return text.length > 80 ? `${text.slice(0, 77)}...` : text;
+}
+
+function buttonText(n) {
+  const texts = [...indexTree(n).byId.values()].filter(
+    (x) => x.type === "TEXT",
+  );
+  return texts.map(textOf).join(" ").trim();
+}
+function handDrawnButton(n) {
+  if (n.type !== "FRAME") return false;
+  if (!n.layoutMode || n.layoutMode === "NONE") return false;
+  if (!(visiblePaints(n.fills) || visiblePaints(n.strokes))) return false;
+  const radius =
+    n.cornerRadius ?? Math.max(0, ...(n.rectangleCornerRadii ?? [0]));
+  if (!(radius > 0)) return false;
+  const h = n.absoluteBoundingBox?.height ?? 0;
+  if (h < 24 || h > 48) return false;
+  const tree = [...indexTree(n).byId.values()];
+  if (
+    tree.some(
+      (x) =>
+        x.type === "FRAME" &&
+        x.id !== n.id &&
+        (visiblePaints(x.fills) || visiblePaints(x.strokes)),
+    )
+  )
+    return false;
+  const texts = tree.filter((x) => x.type === "TEXT");
+  if (texts.length !== 1) return false;
+  const words = buttonText(n).split(/\s+/).filter(Boolean);
+  return words.length > 0 && words.length <= 3;
+}
+function isSelf(a, n) {
+  const up = a.ancestors(n);
+  if (up.some((x) => SELF_CONTAINER.test(x.name ?? ""))) return true;
+  const accountCard = (x) => {
+    const set =
+      x.type === "INSTANCE"
+        ? a.componentLabel(x)
+        : x.type === "COMPONENT"
+          ? a.parent.get(x.id)?.name
+          : null;
+    if (!SELF_COMPONENT.test(set ?? "")) return false;
+    const name = x.type === "INSTANCE" ? a.componentOf(x)?.name : x.name;
+    const kind = x.componentProperties?.kind?.value;
+    return (
+      kind === "Account" || /(^|,\s*)kind=account(\s*,|$)/i.test(name ?? "")
+    );
+  };
+  if (up.some(accountCard)) return true;
+  const siblings = a.parent.get(n.id)?.children ?? [];
+  if (
+    [n, ...siblings].some((x) => x.type === "TEXT" && SELF_TEXT.test(textOf(x)))
+  )
+    return true;
+  // "Signed in" or "Not you?" in the same card: the nearest instance or
+  // component holding it, never a whole row or screen.
+  const card = up.find((x) => x.type === "INSTANCE" || x.type === "COMPONENT");
+  return card
+    ? [...indexTree(card).byId.values()].some(
+        (x) => x.type === "TEXT" && SIGNED_IN.test(textOf(x)),
+      )
+    : false;
+}
+function revealedByPermission(a, n) {
+  return [n, ...a.ancestors(n)].some((x) => {
+    if (x.type !== "INSTANCE") return false;
+    const name = a.componentLabel(x);
+    if (!/pii ?text/i.test(name)) return false;
+    const mode = x.componentProperties?.mode?.value;
+    return (
+      mode === "revealed" || /mode=revealed/i.test(a.componentOf(x)?.name ?? "")
+    );
+  });
+}
+function externalPlane(a, n) {
+  return [n, ...a.ancestors(n)].some((x) => EXTERNAL_PLANE.test(x.name ?? ""));
+}
+function nextToAvatar(a, n) {
+  const p = a.parent.get(n.id);
+  const near = [
+    ...(p?.children ?? []),
+    ...(a.parent.get(p?.id ?? "")?.children ?? []),
+  ];
+  return near.some(
+    (x) => x.type === "INSTANCE" && /avatar/i.test(a.componentLabel(x)),
+  );
+}