@nodii/dev 0.6.15 → 0.6.16

package/README.md

@@ -343,11 +343,18 @@ nodii-dev design check FILE_KEY|LINK [--nodes 12:34,12:56] [--roles decision.app
 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.
+- A library component is found in the DS file's published listing, or else
+  by Figma's lookup of its key. The DS file is the first file the role map
+  names, or else the first file registered in Dev as `design-system`.
+- It is read only from a library Dev has registered (`design-system` or
+  `surfaces`), at that library's newest "Components published" version
+  (DEC-0047), so an unpublished DS edit flags nothing. A library with no
+  recent publish is read at its head. `FIGMA_PAT` needs the
+  `file_versions:read` scope for this. `--json` gives `libraryVersion` (the
+  publish), `libraryRead`, and `libraryFellBack` (Figma couldn't serve the
+  publish, so the head was read).
+- An instance from a library Dev hasn't registered is an `unresolvedLibrary`
+  warning: nothing under it is flagged, and it never fails the check.
 
 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

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.15";
+export const VERSION = "0.6.16";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");

package/dist/design.js

@@ -126,53 +126,141 @@ export async function libraryIndex(figmaGet, dsFileKey) {
   return { fileKey: dsFileKey, byKey, keyByNode };
 }
 
+// The label Figma gives a library publish's version (DEC-0047).
+const PUBLISH_LABEL = "Components published";
+const VERSION_PAGES = 5;
+const KEY_LOOKUPS_AT_ONCE = 3;
+
+/**
+ * A library's newest "Components published" version (DEC-0047): what a
+ * consuming file can have. Null when none is in its recent history; its
+ * head is read then, as at the gate.
+ */
+export async function lastPublish(figmaGet, fileKey) {
+  let path = `/files/${encodeURIComponent(fileKey)}/versions?page_size=100`;
+  for (let page = 0; page < VERSION_PAGES && path; page++) {
+    let payload;
+    try {
+      payload = await figmaGet(path);
+    } catch (error) {
+      if (error instanceof CliError && error.code === "FIGMA_FORBIDDEN")
+        throw new CliError(error.code, `${error.message}: FIGMA_PAT can't read ${fileKey}'s version history (the file_versions:read scope), which finds the library's newest publish (DEC-0047)`, 1, error.details);
+      throw error;
+    }
+    const hit = (payload?.versions ?? []).find((v) => v.label === PUBLISH_LABEL);
+    if (hit) return hit.id;
+    // Figma links the next-older page as a full URL.
+    const older = payload?.pagination?.prev_page;
+    path = typeof older === "string" && older.startsWith(FIGMA_API) ? older.slice(FIGMA_API.length) : null;
+  }
+  return null;
+}
+
 /**
  * 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.
+ * id for it), resolved as Dev's gate resolves it (Dev issue 92, conformance
+ * 1.0.3), so both give one verdict:
+ * - a local component (remote: false) is read from this file;
+ * - a remote one is found in the DS file's published listing, else by Figma's
+ *   lookup of its key, and is read only from a library Dev has registered
+ *   (design-system or surfaces), at that library's newest publish
+ *   (DEC-0047), or its head when Figma can't serve that version;
+ * - one from a library Dev hasn't registered is null and is added to
+ *   `ctx.unresolved`, for an unresolvedLibrary warning;
+ * - anything else (no metadata, a main Figma lacks) is null.
+ * A null main makes the check treat everything under the instance as the
+ * library's, flagging nothing on a guess. `ctx` carries the DS index, the
+ * registered files and what earlier rounds found.
  */
-export async function fetchMains(figmaGet, fileKey, nodes, componentIds, ds = null) {
+export async function fetchMains(figmaGet, fileKey, nodes, componentIds, ctx = {}) {
+  const ds = ctx.ds ?? null;
+  const registered = ctx.registered ?? new Set(ds ? [ds.fileKey] : []);
+  ctx.homes ??= new Map();
+  ctx.published ??= new Map();
+  ctx.unresolved ??= new Set();
   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]);
+  const local = componentIds.filter((id) => meta[id]?.remote === false);
+  const remote = componentIds.filter((id) => meta[id]?.remote && meta[id].key);
+  // Where each key lives: the DS listing first, then Figma's lookup.
+  const lookup = [];
+  for (const key of new Set(remote.map((id) => meta[id].key))) {
+    if (ctx.homes.has(key)) continue;
+    const inDs = ds?.byKey.get(key);
+    if (inDs) ctx.homes.set(key, { fileKey: ds.fileKey, nodeId: inDs });
+    else lookup.push(key);
   }
-  // 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) => {
+  for (const part of chunks(lookup, KEY_LOOKUPS_AT_ONCE))
+    await Promise.all(part.map(async (key) => {
+      let m = null;
+      try {
+        m = (await figmaGet(`/components/${encodeURIComponent(key)}`)).meta;
+      } catch (error) {
+        if (!(error instanceof CliError) || error.code !== "FIGMA_NOT_FOUND") throw error;
+      }
+      ctx.homes.set(key, m?.file_key && m?.node_id ? { fileKey: String(m.file_key), nodeId: String(m.node_id) } : null);
+    }));
+  const byFile = new Map(); // library file -> main node -> this file's componentIds
+  for (const id of remote) {
+    const home = ctx.homes.get(meta[id].key);
+    if (!home || !registered.has(home.fileKey)) {
+      ctx.unresolved.add(id);
+      continue;
+    }
+    const nodesOf = byFile.get(home.fileKey) ?? new Map();
+    nodesOf.set(home.nodeId, [...(nodesOf.get(home.nodeId) ?? []), id]);
+    byFile.set(home.fileKey, nodesOf);
+  }
+  // Each read's /nodes entries, or null when Figma has no such file or
+  // version. A token that can't read the file fails: the gate would refuse.
+  const read = async (file, ids, version = null) => {
     const out = {};
     for (const part of chunks(ids, IDS_PER_CALL)) {
+      const query = `ids=${encodeURIComponent(part.join(","))}${version ? `&version=${encodeURIComponent(version)}` : ""}`;
       try {
-        Object.assign(out, (await figmaGet(`/files/${encodeURIComponent(file)}/nodes?ids=${encodeURIComponent(part.join(","))}`)).nodes ?? {});
+        Object.assign(out, (await figmaGet(`/files/${encodeURIComponent(file)}/nodes?${query}`)).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;
+        if (error instanceof CliError && error.code === "FIGMA_NOT_FOUND") return null;
+        throw error;
       }
     }
     return out;
   };
   const entry = (e) => (e?.document ? e : null);
+  for (const [file, nodesOf] of byFile) {
+    if (!ctx.published.has(file)) ctx.published.set(file, await lastPublish(figmaGet, file));
+    const version = ctx.published.get(file);
+    if (file === ds?.fileKey) ctx.libraryVersion = version;
+    // A published version Figma can't serve falls back to the file as it is.
+    let got = await read(file, [...nodesOf.keys()], version);
+    if (!got && version) {
+      got = await read(file, [...nodesOf.keys()]);
+      if (file === ds?.fileKey) ctx.libraryFellBack = true;
+    }
+    for (const [node, ids] of nodesOf) for (const id of ids) mains[id] = entry(got?.[node]);
+  }
   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]);
+    for (const id of local) mains[id] = entry(got?.[id]);
   }
   return mains;
 }
 
+/** The first instance of a component in the checked trees, to point a warning at. */
+function firstInstance(nodes, componentId) {
+  for (const entry of Object.values(nodes)) {
+    const stack = entry?.document ? [entry.document] : [];
+    while (stack.length) {
+      const n = stack.pop();
+      if (n.type === "INSTANCE" && n.componentId === componentId) return n.id;
+      for (const child of n.children ?? []) stack.push(child);
+    }
+  }
+  return null;
+}
+
 // 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).
@@ -223,29 +311,41 @@ export async function designCheck(target, flags = {}, { request = devRequest, en
   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).
+  // Mains may come from any library Dev has registered (the DS and the
+  // Surfaces libraries that publish blocks).
+  const registered = new Set([...files.filter((f) => ["design-system", "surfaces"].includes(f.kind)).map((f) => f.fileKey), ...(dsFileKey ? [dsFileKey] : [])]);
+  const ctx = { ds, registered };
   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));
+    Object.assign(mains, await fetchMains(get, fileKey, nodes, want, ctx));
   }
   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).
+  // A library Dev doesn't know is a warning, as at the gate, not silence.
   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 unresolved = ctx.unresolved ?? new Set();
+  const warnings = [...unresolved].map((id) => ({ nodeId: firstInstance(nodes, id) ?? id, check: "unresolvedLibrary",
+    detail: `${meta[id]?.name ?? id} comes from a library Dev hasn't registered; its instances were not checked against a main` }));
   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,
+    // Mains the gate would read that Figma didn't serve.
+    unresolvedMains: Object.keys(mains).filter((id) => !mains[id] && !unresolved.has(id) && (meta[id]?.remote === false || Boolean(meta[id]?.remote && meta[id]?.key))),
+    // The DS file's newest publish, as the gate reports it (null when it has
+    // none, or no DS main was needed); libraryFellBack says the head was read
+    // because Figma couldn't serve it.
+    libraryVersion: ctx.libraryVersion ?? null,
+    libraryRead: Boolean(dsFileKey && ctx.published?.has(dsFileKey)),
+    libraryFellBack: Boolean(ctx.libraryFellBack),
     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 ?? [],
+    warnings,
   };
   return { payload: { data }, exitCode: data.passed ? 0 : 1 };
 }
@@ -255,7 +355,8 @@ export function designCheckText({ data }) {
   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`);
+  if (data.libraryRead && data.libraryFellBack) lines.push(`note: Figma couldn't serve ${data.dsFileKey}'s newest publish, version ${data.libraryVersion}, so library mains were read at its head`);
+  else if (data.libraryRead) lines.push(data.libraryVersion ? `library mains read at ${data.dsFileKey}'s newest publish, version ${data.libraryVersion} (DEC-0047)` : `note: ${data.dsFileKey} has no "Components published" version in its recent history, so library mains were read at its head`);
   lines.push(data.passed ? "PASSED: no conformance findings" : `DS_CONFORMANCE_FAILED: ${data.findings.length} finding(s)`);
   return [...lines, ...conformanceLines(data)].join("\n");
 }