@nodii/dev 0.6.13 → 0.6.15

package/README.md

@@ -147,6 +147,7 @@ prints them without creating anything.
 nodii-dev figma file add FILE_KEY --name TEXT --kind design-system|surfaces|prototype [--module M]
 nodii-dev figma lock FILE_KEY --title TEXT [--scope KIND:ID ...]
 nodii-dev figma scope add CHANGE_SET --scope KIND:ID [--scope ...]
+nodii-dev figma scope set CHANGE_SET --scope KIND:ID [--scope ...]
 nodii-dev figma publish-plan FILE_KEY
 nodii-dev figma check FILE_KEY
 nodii-dev figma log-write CHANGE_SET --tool TOOL --nodes NODE[,NODE]
@@ -190,7 +191,14 @@ refuses an overlap with `SCOPE_CONFLICT`; the CLI prints Dev's message, then
 the set holding the overlapping scope. `figma lock` without `--scope` locks the
 whole file, as older CLIs do, and that conflicts with every other set.
 `figma scope add` widens a set you hold, with the same check; nothing is ever
-widened silently.
+widened silently. `figma scope set` narrows a set you hold to exactly the
+scopes you give, and releases the rest for other sets: for example, a set
+migrated as a whole-file lock can keep just its page. It only narrows. Each
+scope must sit inside one the set holds (the whole file holds everything, and
+a page holds its components and creates); anything else is
+`SCOPE_NOT_NARROWER`. Dev refuses with `WRITE_OUT_OF_SCOPE` when a logged
+write or a submitted node would fall outside the narrower scopes, so keep a
+scope that holds them.
 
 Every write must fall inside the set's scopes (MW1-57.7). The post-hook
 logs each write's node ids, in colon form. It also logs the variable,
@@ -319,6 +327,80 @@ nodii-dev harness check [--json]               # 0 current, 1 differs from Dev,
 nodii-dev harness update --check               # the same check
 ```
 
+### DS conformance: `design roles` and `design check` (DEC-0034)
+
+Every UI role names exactly one DS component (MW6-14). Resolve your brief's
+roles before drawing, and run the submit gate's conformance check yourself
+before `figma submit`:
+
+```bash
+nodii-dev design roles [ROLE ...]          # role, component (and variant), entry, DS file + node; flags unknown roles
+nodii-dev design check FILE_KEY|LINK [--nodes 12:34,12:56] [--roles decision.approve,data.table] [--library] [--json]
+```
+
+`design check` reads the nodes from Figma's REST API with `FIGMA_PAT` (or
+`FIGMA_TOKEN`) and the role map from Dev (`listDesignRoles`). It then reads
+each instance's main the way Dev's submit gate does, so both reach one verdict:
+
+- A local component is read from the file.
+- A library component is read through the DS file's published listing, from
+  the DS file as it is now. The DS file is the first file the role map names,
+  or else the first file registered in Dev as `design-system`.
+- A component from another library, or one the DS hasn't published, isn't
+  read, and nothing under it is flagged.
+
+It runs the conformance module Dev's submit runs, vendored unchanged in
+`src/vendor/ds-conformance.mjs`. No `--nodes` checks every page; a link's
+`node-id` counts as one.
+
+A file registered in Dev as `design-system` checks as the library, so its own
+components are not stand-ins. `--library` forces that for another file, such as
+a branch of the DS file.
+
+It lists each finding (node id, check, detail): `roleMismatch`,
+`instanceOverride`, `notFromLibrary`, `otherPersonRevealed`,
+`tableHeaderFill`.
+
+- Overrides equal to the main's are listed as stale and never fail
+  (DEC-0035).
+- Nodes behind a library republish (the same value through a newer variable)
+  are listed as `libraryUpdatePending` and never fail: accept the library
+  update in that file (MW6-17).
+- Exit 1 with `DS_CONFORMANCE_FAILED` means Dev's submit would refuse the
+  same nodes. An error that stops the check (a Figma read, Dev) also exits 1,
+  with its own code. With `--json`, read `data.passed`. Note that `design check` reads the file as it is now, while the
+  submit reads the `figmaVersion` you send.
+- A node the file doesn't have is a `FIGMA_NODE_MISSING` finding; the
+  other nodes are still checked.
+- A whole page that Figma can't serve in time fails `FIGMA_TIMEOUT`: name
+  fewer nodes with `--nodes`.
+- A `FIGMA_PAT` that can't read the DS file fails `FIGMA_FORBIDDEN`, rather
+  than passing with the library overrides unchecked.
+
+The submit-time guards need the change set's images and versions, so only Dev
+runs them. `IMAGE_NOT_TRUECOLOR` (a palette or quantized review PNG) refuses.
+`STALE_FIGMA_VERSION` (a version older than the lane's last logged write) is a
+warning, never a refusal. Ask Dev for a dry run of its whole gate, which
+changes no state:
+
+```bash
+nodii-dev design check --change-set CS-123 [--file SUBMIT.json] [--figma-version V] [--json]
+```
+
+With no `--file`, Dev checks the set's current items at its last submitted
+version. A set never submitted needs `--file`: the body `figma submit --file`
+would send. A cold run can outlast the edge's gateway; the CLI then says
+`DEV_TIMEOUT` and to run it again (Dev keeps the mains it read for 5 minutes).
+
+When `figma submit`, `figma resubmit` or the dry run hits
+`DS_CONFORMANCE_FAILED`, the CLI prints each finding and Dev's warnings. A
+submit Dev accepts prints its warnings too. On a stale version it also prints
+the version's time, the lane's last write, and either "retry after <time>, or
+ask the coordinator to have the operator File > Save to version history", or
+the newer version to submit with. `--json` keeps Dev's fields: `warnings` (on
+an accepted submit too), and, on a refusal or a dry run, `staleVersion` (`figmaVersion`, `figmaVersionAt`, `latestVersion`,
+`latestVersionAt`, `lastWriteAt`, `retryAfter`).
+
 ### Moving an issue: `issues transition`
 
 `issues transition` moves an issue along Dev's status map (MW1-16) with

package/dist/api.js

@@ -102,7 +102,7 @@ export const GROUPS = {
   composite: "Composite", "service-edges": "ServiceEdges", lanes: "Lanes",
   swaps: "Swaps", ideas: "Ideas", terminology: "Terminology", credentials: "Credentials",
   rulebook: "ad-documents", "ad-decisions": "ad-decisions", domains: "ad-domains", standardizations: "standardizations",
-  archive: "archive", harness: "harness",
+  archive: "archive", harness: "harness", utils: "utils",
   // DEC-0020 rule delivery; `rules core|report|cap` are first-class (upload.js).
   rules: "rulebook",
 };

package/dist/cli.js

@@ -40,14 +40,18 @@ import {
   figmaPublishPlanText,
   figmaResubmit,
   figmaScopeAdd,
+  figmaScopeSet,
+  figmaScopeSetText,
   figmaSubmit,
   isChangeSetId,
   scopeText,
   scopesFrom,
+  conformanceLines,
 } from "./figma.js";
 export { figmaLock } from "./figma.js";
 import { docsCommand, rulebookCommand, rulesCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
+import { designCheck, designCheckText, designRoles, designRolesText } from "./design.js";
 import {
   ALIASES,
   GROUPS,
@@ -88,10 +92,18 @@ Usage: nodii-dev <command> [options] [--json]
   design guideline list [--drafted] [--all] | show ENTRY
   design guideline propose ENTRY --file FILE.md [--summary TEXT] [--dry-run]
   design changeset list [--entry KEY] [--state STATE] | show ID
+  design roles [ROLE ...]               # the role map: each UI role's one DS component (MW6-14)
+  design check FILE_KEY|LINK [--nodes A,B] [--roles R,S] [--library]
+                                        # the DS conformance check Dev's submit runs, before you submit;
+                                        # reads Figma with FIGMA_PAT; exit 1 = DS_CONFORMANCE_FAILED or an error (--json: data.passed)
+  design check --change-set CS [--file SUBMIT.json] [--figma-version V]
+                                        # Dev's dry run of the submit gate on a set, with the image guard;
+                                        # a stale version is a warning that prints when to retry
   figma lock FILE_KEY --title TEXT [--scope KIND:ID ...]
                                         # scopes: component:NODE page:NODE foundations create:PAGE:NAME;
                                         # no --scope locks the whole file (DEC-0032)
   figma scope add CHANGE_SET --scope KIND:ID [--scope ...]   # widen a held set's scopes
+  figma scope set CHANGE_SET --scope KIND:ID [--scope ...]   # narrow to exactly these; the rest frees
   figma publish-plan FILE_KEY           # what to publish, and what to leave unchecked in Figma's dialog
   figma published FILE_KEY|CHANGE_SET --figma-version V   # a file key marks every awaiting set published
   figma check|log-write|submit|apply|abandon|release
@@ -140,7 +152,7 @@ contracts, sagas, outbox-topics, tables, libraries, workers, projects, issues,
 backlogs, builds, changes, deploy-reports, runtime, people, agents, inbox,
 gate, design, runbooks, doctrine, changelog, health-verdicts, approval-kinds,
 notification-registry, skills, open-questions, decisions, drift, requests,
-rulebook, ad-decisions, domains, standardizations, archive, and harness.
+rulebook, ad-decisions, domains, standardizations, archive, harness, and utils.
 
 Run a command with --help or see the package README for all flags.`;
 
@@ -413,6 +425,18 @@ export async function main(argv = process.argv.slice(2)) {
   // Guideline change sets: approving or rejecting one is a person's action in Dev.
   if (command === "design" && action === "guideline") return emitCommand(await guidelineCommand(rest[0], rest.slice(1), f));
   if (command === "design" && action === "changeset") return emitCommand(await changeSetCommand(rest[0], rest.slice(1), f));
+  if (command === "design" && action === "roles") return emit(await designRoles(rest), json, designRolesText);
+  if (command === "design" && action === "check") {
+    if ((!rest[0] && f["change-set"] === undefined) || rest.length > 1)
+      throw new CliError("USAGE", "design check FILE_KEY|LINK [--nodes A,B] [--roles R,S] [--library] | design check --change-set CS [--file SUBMIT.json] [--figma-version V]", 2);
+    const result = await designCheck(rest[0], f);
+    emit(result.payload, json, result.human ?? designCheckText);
+    if (result.exitCode) {
+      if (!json) console.error(`DS_CONFORMANCE_FAILED: ${result.payload.data.findings.length} finding(s)`);
+      process.exitCode = result.exitCode;
+    }
+    return;
+  }
   if (command === "lane") return emitCommand(await laneCommand(action, rest, f));
   if (command === "next") return emitCommand(await nextCommand(action, f));
   if (command === "built") return emitCommand(await builtCommand(action, rest, f));
@@ -606,7 +630,8 @@ export async function main(argv = process.argv.slice(2)) {
     if (action === "lock")
       return emit(await figmaLock(rest[0], requireFlag(f, "title"), { scopes: scopesFrom(f) }), json, (p) => figmaLockText(p.data));
     if (action === "scope") {
-      if (rest[0] !== "add" || !rest[1] || rest.length > 2) throw new CliError("USAGE", "figma scope add CHANGE_SET --scope KIND:ID [--scope ...]", 2);
+      if (!["add", "set"].includes(rest[0]) || !rest[1] || rest.length > 2) throw new CliError("USAGE", "figma scope add|set CHANGE_SET --scope KIND:ID [--scope ...]", 2);
+      if (rest[0] === "set") return emit(await figmaScopeSet(rest[1], scopesFrom(f)), json, (p) => figmaScopeSetText(rest[1], p.data));
       return emit(await figmaScopeAdd(rest[1], scopesFrom(f)), json, (p) =>
         `${rest[1]} holds ${p.data?.scopes?.length ?? "its"} scope(s)${p.data?.scopes?.length ? `: ${p.data.scopes.map(scopeText).join(", ")}` : ""}`);
     }
@@ -620,7 +645,9 @@ export async function main(argv = process.argv.slice(2)) {
       return emit(await figmaFilePublished(rest[0], f.file ? JSON.parse(await readFile(f.file, "utf8")) : { figmaVersion: requireFlag(f, "figma-version") }), json, (p) => figmaFilePublishedText(p.data));
     if (action === "submit") {
       const payload = f.file ? JSON.parse(await readFile(f.file, "utf8")) : { figmaVersion: requireFlag(f, "figma-version") };
-      return emit(await figmaSubmit(rest[0], payload), json);
+      // A 200 carries top-level warnings (STALE_FIGMA_VERSION): print them.
+      return emit(await figmaSubmit(rest[0], payload), json, (p) =>
+        [JSON.stringify(p.data, null, 2), ...conformanceLines({ warnings: p.warnings })].join("\n"));
     }
     if (action === "file") {
       if (rest[0] !== "add") throw new CliError("USAGE", "figma file add FILE_KEY --name TEXT --kind KIND [--module M]", 2);
@@ -660,7 +687,7 @@ export async function main(argv = process.argv.slice(2)) {
       return emit(await figmaWithdraw(rest[0]), json, (p) => `Withdrew ${rest[0]}; it is back in ${p.data?.state ?? "editing"}.`);
     if (action === "resubmit")
       return emit(await figmaResubmit(rest[0], rest[1]), json, (p) =>
-        [`Re-submitted ${rest[0]}; it is ${p.data.state}.`, figmaChangeSetText(p.data)].join("\n"));
+        [`Re-submitted ${rest[0]}; it is ${p.data.state}.`, figmaChangeSetText(p.data), ...conformanceLines({ warnings: p.warnings })].join("\n"));
     if (action === "changeset") {
       if (rest[0] !== "show" || !rest[1] || rest.length > 2) throw new CliError("USAGE", "figma changeset show CHANGE_SET", 2);
       return emit(await figmaChangeSetShow(rest[1]), json, (p) => figmaChangeSetText(p.data));

package/dist/core.js

@@ -4,7 +4,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 
-export const VERSION = "0.6.13";
+export const VERSION = "0.6.15";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -184,7 +184,7 @@ export async function checkLogin() {
 export const encode = (value) => encodeURIComponent(value);
 // Switches never take the next token as their value, so
 // `docs upload --wait rulebook/` keeps rulebook/ as a path.
-const SWITCHES = new Set(["json", "wait", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted"]);
+const SWITCHES = new Set(["json", "wait", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library"]);
 export function parseArgs(argv) {
   const flags = {};
   const args = [];

package/dist/design.js

@@ -0,0 +1,306 @@
+// `nodii-dev design roles` and `design check` (DEC-0034, MW6-14 to MW6-17;
+// Dev issue 93). `roles` reads Dev's role map: each UI role names exactly
+// one DS component, and a lane resolves its brief's roles through it before
+// drawing. `check` runs the DS conformance check on a Figma file before a
+// submit: the same check Dev's submit gate runs (Dev issue 92), from the
+// module DESIGN-SYSTEM-60 owns, vendored unchanged in ./vendor. This file only
+// fetches what the check reads: the nodes, the role map and each instance's
+// library main.
+import { readFile } from "node:fs/promises";
+import { CliError, devRequest } from "./core.js";
+import { conformanceLines, figmaConformance, figmaFileKey } from "./figma.js";
+import { checkConformance, neededMains, VERSION as CHECK_VERSION } from "./vendor/ds-conformance.mjs";
+
+const FIGMA_API = "https://api.figma.com/v1";
+// The Figma nodes endpoint takes many ids per call; keep URLs well short of limits.
+const IDS_PER_CALL = 50;
+// Dev's gate stops after six rounds of mains; so does the check here.
+const MAX_MAIN_ROUNDS = 6;
+
+/** GET /design/roles (listDesignRoles): { data: [{ role, summary, labels, entryKey, componentName, fileKey, nodeId, componentKey, variant }], total }. */
+export async function designRoles(roles = [], { request = devRequest } = {}) {
+  const payload = await roleMap(request);
+  if (!roles.length) return payload;
+  const rows = payload.data ?? [];
+  const unknown = roles.filter((role) => !rows.some((x) => x.role === role));
+  return { ...payload, data: rows.filter((x) => roles.includes(x.role)), total: undefined, unknown };
+}
+
+/** listDesignRoles; a Dev or edge without the route says which issue brings it. */
+async function roleMap(request) {
+  try {
+    return await request("GET", "/api/v1/design/roles");
+  } catch (error) {
+    // The edge answers an unknown route `unroutable`; an older Dev, HTTP 404.
+    if (error instanceof CliError && ["unroutable", "HTTP_404", "NOT_FOUND", "ROUTE_NOT_FOUND"].includes(error.code))
+      throw new CliError("ROLE_MAP_UNAVAILABLE", `Dev doesn't serve the role map yet (GET /design/roles, Dev issue 92): ${error.code}: ${error.message}`, 1, error.details);
+    throw error;
+  }
+}
+
+// A role whose guideline names no library component yet (MW6-10).
+const blocked = (x) => !x.nodeId || !x.componentName;
+
+// A role played by some variants of a set names them: " [Kind=Approve]".
+const variantText = (v) => (v && Object.keys(v).length ? ` [${Object.entries(v).map(([k, x]) => `${k}=${x}`).join(", ")}]` : "");
+
+export function designRolesText(p) {
+  const lines = (p.data ?? []).map((x) => blocked(x)
+    ? `${x.role}\tblocked: no DS component (MW6-10)\t${x.entryKey ?? ""}`
+    : `${x.role}\t${x.componentName}${variantText(x.variant)}\t${x.entryKey}\t${x.fileKey} ${x.nodeId}`);
+  if (!lines.length && !p.unknown?.length) lines.push("No roles: Dev's role map is empty (DS guidelines list no roles: yet).");
+  for (const role of p.unknown ?? []) lines.push(`UNKNOWN ${role}: no DS component plays this role; ask the DS before drawing it by hand`);
+  return lines.join("\n");
+}
+
+/** The Figma token: FIGMA_PAT, as the design-system scripts read it, or FIGMA_TOKEN. Never printed. */
+export function figmaToken(env = process.env) {
+  const token = env.FIGMA_PAT || env.FIGMA_TOKEN;
+  if (!token) throw new CliError("FIGMA_TOKEN_REQUIRED", "design check reads the file from Figma's REST API: set FIGMA_PAT to a Figma personal access token that can read the file.", 2);
+  return token;
+}
+
+/** A Figma REST GET, retried on 429 and 5xx. */
+export function figmaClient(token, { fetchImpl = fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), attempts = 6, timeoutMs = 120_000 } = {}) {
+  return async function figmaGet(path) {
+    for (let attempt = 1; ; attempt++) {
+      let response;
+      try {
+        response = await fetchImpl(`${FIGMA_API}${path}`, { headers: { "X-Figma-Token": token }, signal: AbortSignal.timeout(timeoutMs) });
+        // The clock runs while a large body streams in, too.
+        if (response.ok) return await response.json();
+      } catch (error) {
+        if (error instanceof SyntaxError) throw new CliError("FIGMA_ERROR", `Figma answered ${path.split("?")[0]} with a body that isn't JSON`);
+        // A read that runs out the clock is too large, and would again: say how to narrow it.
+        if (error?.name === "TimeoutError")
+          throw new CliError("FIGMA_TIMEOUT", `Figma took over ${timeoutMs / 1000}s for ${path.split("?")[0]}; check fewer nodes with --nodes`);
+        if (attempt >= attempts) throw new CliError("FIGMA_UNREACHABLE", `Cannot reach Figma: ${error.message}`);
+        await sleep(1000 * attempt);
+        continue;
+      }
+      const retry = response.status === 429 || response.status >= 500;
+      if (retry && attempt < attempts) {
+        const after = Number(response.headers?.get?.("retry-after"));
+        await sleep(Number.isFinite(after) && after > 0 ? Math.min(after, 60) * 1000 : 1000 * 2 ** attempt);
+        continue;
+      }
+      const code = { 404: "FIGMA_NOT_FOUND", 403: "FIGMA_FORBIDDEN", 429: "FIGMA_RATE_LIMITED" }[response.status] ?? "FIGMA_ERROR";
+      const hint = response.status === 400 ? " (a malformed node id, or a request too large? check the ids, or fewer nodes, with --nodes)" : "";
+      throw new CliError(code, `Figma answered ${response.status} for ${path.split("?")[0]}${hint}`, 1, { status: response.status });
+    }
+  };
+}
+
+const chunks = (list, size) => Array.from({ length: Math.ceil(list.length / size) }, (_, i) => list.slice(i * size, (i + 1) * size));
+
+/** The /nodes `nodes` map for these ids (every page when none are given); a node Figma lacks is null. */
+export async function fetchNodes(figmaGet, fileKey, nodeIds) {
+  let ids = nodeIds;
+  if (!ids.length) {
+    const file = await figmaGet(`/files/${encodeURIComponent(fileKey)}?depth=1`);
+    ids = (file.document?.children ?? []).map((page) => page.id);
+  }
+  const nodes = {};
+  // A whole page is a large document: fetch pages one per call.
+  for (const part of chunks(ids, nodeIds.length ? IDS_PER_CALL : 1)) {
+    const response = await figmaGet(`/files/${encodeURIComponent(fileKey)}/nodes?ids=${encodeURIComponent(part.join(","))}`);
+    for (const id of part) nodes[id] = response.nodes?.[id] ?? null;
+  }
+  return nodes;
+}
+
+/**
+ * The DS file's published components and sets, key <-> node id: the index
+ * Dev's gate resolves remote mains and role keys through.
+ */
+export async function libraryIndex(figmaGet, dsFileKey) {
+  const file = encodeURIComponent(dsFileKey);
+  const [components, sets] = await Promise.all([figmaGet(`/files/${file}/components`), figmaGet(`/files/${file}/component_sets`)]);
+  const byKey = new Map();
+  const keyByNode = new Map();
+  for (const c of [...(components.meta?.components ?? []), ...(sets.meta?.component_sets ?? [])])
+    if (c.key) {
+      byKey.set(c.key, c.node_id);
+      keyByNode.set(c.node_id, c.key);
+    }
+  return { fileKey: dsFileKey, byKey, keyByNode };
+}
+
+/**
+ * The main of each instance, keyed by the instance's componentId (this file's
+ * id for it), resolved as Dev's gate resolves it (Dev issue 92), so both give
+ * one verdict. A local component (remote: false) is read from this file. A
+ * remote one is read only through the DS file's published listing, from the
+ * DS file as it is now. Anything else (another library, a key the DS hasn't
+ * published, no metadata) is null: the check then treats everything under
+ * that instance as the library's and flags nothing on a guess.
+ */
+export async function fetchMains(figmaGet, fileKey, nodes, componentIds, ds = null) {
+  const meta = Object.assign({}, ...Object.values(nodes).map((n) => n?.components ?? {}));
+  const mains = Object.fromEntries(componentIds.map((id) => [id, null]));
+  const local = [];
+  const fromLibrary = new Map(); // DS node id -> this file's componentIds
+  for (const id of componentIds) {
+    const c = meta[id];
+    const libraryNode = c?.key ? ds?.byKey.get(c.key) : undefined;
+    if (c?.remote === false) local.push(id);
+    else if (c?.remote && libraryNode) fromLibrary.set(libraryNode, [...(fromLibrary.get(libraryNode) ?? []), id]);
+  }
+  // Each read's /nodes entries. A 404 leaves its mains null, as in Dev's gate;
+  // a token that can't read the file fails, since the gate would refuse too.
+  const read = async (file, ids) => {
+    const out = {};
+    for (const part of chunks(ids, IDS_PER_CALL)) {
+      try {
+        Object.assign(out, (await figmaGet(`/files/${encodeURIComponent(file)}/nodes?ids=${encodeURIComponent(part.join(","))}`)).nodes ?? {});
+      } catch (error) {
+        if (error instanceof CliError && error.code === "FIGMA_FORBIDDEN")
+          throw new CliError(error.code, `${error.message}: FIGMA_PAT can't read ${file}, so its mains (and the overrides on them) can't be checked`, 1, error.details);
+        if (!(error instanceof CliError) || error.code !== "FIGMA_NOT_FOUND") throw error;
+      }
+    }
+    return out;
+  };
+  const entry = (e) => (e?.document ? e : null);
+  if (local.length) {
+    const got = await read(fileKey, local);
+    for (const id of local) mains[id] = entry(got[id]);
+  }
+  if (fromLibrary.size) {
+    const got = await read(ds.fileKey, [...fromLibrary.keys()]);
+    for (const [node, ids] of fromLibrary) for (const id of ids) mains[id] = entry(got[node]);
+  }
+  return mains;
+}
+
+// A repeated flag parses as an array: `--nodes a --nodes b,c` is a, b and c.
+const list = (value) => [value].flat().filter((x) => typeof x === "string").flatMap((x) => x.split(",")).map((x) => x.trim()).filter(Boolean);
+// A node id as a figma.com link writes it (12-34) or as the API does (12:34).
+const nodeId = (x) => (/^\d+-\d+$/.test(x) ? x.replace("-", ":") : x);
+
+/**
+ * `design check <fileKey|link> [--nodes a,b] [--roles r,s] [--library]`: the conformance
+ * findings for those nodes (every page when none are named). A link's
+ * node-id counts as --nodes. Exit 1 with DS_CONFORMANCE_FAILED when any
+ * finding fails; stale overrides (a value equal to the main's) are listed but
+ * never fail (DEC-0035).
+ */
+export async function designCheck(target, flags = {}, { request = devRequest, env = process.env, figmaGet, read } = {}) {
+  if (flags["change-set"] !== undefined) return designCheckChangeSet(target, flags, { request, ...(read ? { read } : {}) });
+  // A --nodes that names nothing must not widen to every page.
+  if (flags.nodes !== undefined && ([flags.nodes].flat().includes(true) || !list(flags.nodes).length))
+    throw new CliError("USAGE", "--nodes needs node ids, e.g. --nodes 12:34,12:56", 2);
+  if (flags.roles === true) throw new CliError("USAGE", "--roles needs role names, e.g. --roles decision.approve,data.table", 2);
+  const fileKey = figmaFileKey(target);
+  let decoded = target;
+  try {
+    decoded = typeof target === "string" ? decodeURIComponent(target) : target;
+  } catch {
+    throw new CliError("USAGE", `cannot read the link ${target}: a malformed %-escape`, 2);
+  }
+  const linkNode = typeof decoded === "string" ? /[?&]node-id=([0-9]+[-:][0-9]+)/.exec(decoded)?.[1] : undefined;
+  if (typeof decoded === "string" && /[?&]node-id=/.test(decoded) && !linkNode)
+    throw new CliError("USAGE", `the link's node-id isn't a frame or component id (12-34); pass --nodes`, 2);
+  const nodeIds = [...new Set([...list(flags.nodes).map(nodeId), ...(linkNode ? [nodeId(linkNode)] : [])])];
+  const get = figmaGet ?? figmaClient(figmaToken(env));
+  const [rows, files, nodes] = await Promise.all([
+    roleMap(request).then((p) => p.data ?? []),
+    request("GET", "/api/v1/design/files").then((p) => p.data ?? []),
+    fetchNodes(get, fileKey, nodeIds),
+  ]);
+  // As Dev's gate does: the DS file is the first (by role) the role map
+  // names, else the first file registered as design-system; a role row
+  // without a key takes it from that file's published listing.
+  const dsFiles = files.filter((f) => f.kind === "design-system").map((f) => f.fileKey).sort();
+  const dsFileKey = rows.find((r) => r.fileKey)?.fileKey ?? dsFiles[0] ?? null;
+  const ds = dsFileKey ? await libraryIndex(get, dsFileKey) : null;
+  const roles = rows.map((r) => ({
+    ...r,
+    componentKey: r.componentKey ?? (ds && r.nodeId && r.fileKey === ds.fileKey ? (ds.keyByNode.get(r.nodeId) ?? null) : null),
+  }));
+  // A file registered as design-system checks as the library, as at the gate:
+  // its own components are not stand-ins. --library forces it (a DS branch).
+  const library = flags.library === true || dsFiles.includes(fileKey);
+  // Each round of mains can reveal instances inside slot content, so fetch
+  // until the check needs no more (the module's contract).
+  const mains = {};
+  for (let round = 0; round < MAX_MAIN_ROUNDS; round++) {
+    const want = neededMains(nodes, mains, { library });
+    if (!want.length) break;
+    Object.assign(mains, await fetchMains(get, fileKey, nodes, want, ds));
+  }
+  const declaredRoles = list(flags.roles);
+  const result = checkConformance({ nodes, roles, mains, options: { library, ...(declaredRoles.length ? { declaredRoles } : {}) } });
+  // A node Figma lacks fails, as at the gate, and the rest are still checked.
+  const missing = Object.keys(nodes).filter((id) => !nodes[id]?.document);
+  const findings = [...missing.map((id) => ({ nodeId: id, check: "FIGMA_NODE_MISSING", detail: `Figma has no node ${id} in ${fileKey}` })), ...(result.findings ?? [])];
+  // Mains the gate reads (local, or in the DS listing) that Figma didn't
+  // serve, apart from those it never reads (another library).
+  const meta = Object.assign({}, ...Object.values(nodes).map((n) => n?.components ?? {}));
+  const gateReads = (id) => meta[id]?.remote === false || Boolean(meta[id]?.remote && ds?.byKey.has(meta[id].key));
+  const data = {
+    fileKey, nodeIds: Object.keys(nodes), checkVersion: result.version ?? CHECK_VERSION, roles: roles.filter((x) => !blocked(x)).length, library, dsFileKey,
+    unresolvedMains: Object.keys(mains).filter((id) => !mains[id] && gateReads(id)),
+    outsideLibraryMains: Object.keys(mains).filter((id) => !mains[id] && !gateReads(id)).length,
+    passed: findings.length === 0, findings, staleOverrides: result.staleOverrides ?? [],
+    // Same value through a different variable: the file is behind a library
+    // republish. Accept the update in Figma (MW6-17); never a failure.
+    libraryUpdatePending: result.libraryUpdatePending ?? [],
+  };
+  return { payload: { data }, exitCode: data.passed ? 0 : 1 };
+}
+
+export function designCheckText({ data }) {
+  const lines = [`${data.fileKey}: ${data.nodeIds.length} node(s), ${data.roles} role(s), check ${data.checkVersion}`];
+  if (!data.roles) lines.push("note: no role in Dev's role map names a DS component yet, so roleMismatch had nothing to check against");
+  if (!data.dsFileKey) lines.push("note: Dev names no DS file, so no library main was read; overrides on library instances were not checked");
+  if (data.unresolvedMains.length) lines.push(`note: ${data.unresolvedMains.length} main component(s) could not be read (${data.unresolvedMains.join(", ")}); overrides under them were not checked`);
+  if (data.outsideLibraryMains) lines.push(`note: ${data.outsideLibraryMains} instance main(s) are outside the DS file's published library; as at Dev's submit, nothing under them is checked`);
+  lines.push(data.passed ? "PASSED: no conformance findings" : `DS_CONFORMANCE_FAILED: ${data.findings.length} finding(s)`);
+  return [...lines, ...conformanceLines(data)].join("\n");
+}
+
+/**
+ * `design check --change-set CS-1 [--file SUBMIT.json] [--figma-version V]`: Dev's own dry run of
+ * the submit gate on a change set (checkDesignConformance): the same checks
+ * plus the submit-time guards against the set's items: IMAGE_NOT_TRUECOLOR
+ * refuses; STALE_FIGMA_VERSION is a warning. Changes no state.
+ */
+export async function designCheckChangeSet(target, flags, { request = devRequest, read = (f) => readFile(f, "utf8") } = {}) {
+  const id = flags["change-set"];
+  if (id === true || !id) throw new CliError("USAGE", "--change-set needs a change set id, e.g. --change-set CS-123", 2);
+  if (target !== undefined) throw new CliError("USAGE", "design check --change-set CS takes no file: Dev checks the set's own items", 2);
+  if (flags["figma-version"] === true) throw new CliError("USAGE", "--figma-version needs a version id", 2);
+  if (flags.file === true) throw new CliError("USAGE", "--file needs the submit body, e.g. --file submit.json", 2);
+  // A set never submitted has no version or items for Dev to check: send the
+  // body `figma submit --file` would send. --figma-version overrides its version.
+  let body = {};
+  if (flags.file) {
+    try {
+      body = JSON.parse(await read(flags.file));
+    } catch (error) {
+      throw new CliError("USAGE", `cannot read ${flags.file} as JSON: ${error.message}`, 2);
+    }
+    if (!body || typeof body !== "object" || Array.isArray(body)) throw new CliError("USAGE", `${flags.file}: expected the submit body, a JSON object`, 2);
+  }
+  if (flags["figma-version"]) body = { ...body, figmaVersion: String(flags["figma-version"]) };
+  let p;
+  try {
+    p = await figmaConformance(id, body, { request });
+  } catch (error) {
+    // A cold run reads every root and main from Figma and can outlast the
+    // edge's gateway (504, an HTML page). Dev keeps the mains it read for 5
+    // minutes, so the same run again usually answers.
+    if (error?.code !== "HTTP_504") throw error;
+    throw new CliError("DEV_TIMEOUT", `Dev's dry run of ${id} ran past the edge's gateway timeout while reading Figma; run it again (Dev keeps the library mains it read for 5 minutes)`, 1);
+  }
+  const r = p.data ?? {};
+  const data = { changeSetId: id, checkVersion: r.version, passed: Boolean(r.passed), checked: r.checked, findings: r.findings ?? [],
+    staleOverrides: r.staleOverrides ?? [], libraryUpdatePending: r.libraryUpdatePending ?? [], warnings: r.warnings ?? [], staleVersion: r.staleVersion ?? null };
+  return { payload: { data }, exitCode: data.passed ? 0 : 1, human: designCheckChangeSetText };
+}
+
+export function designCheckChangeSetText({ data }) {
+  const head = `${data.changeSetId}: Dev's submit gate, dry run${data.checkVersion ? `, check ${data.checkVersion}` : ""}`;
+  return [head, data.passed ? "PASSED: Dev would accept this submit" : `DS_CONFORMANCE_FAILED: ${data.findings.length} finding(s)`, ...conformanceLines(data)].join("\n");
+}