@nodii/dev 0.6.13 → 0.6.15

package/dist/figma.js

@@ -173,8 +173,45 @@ export function outOfScopeText(message, details, id = details?.changeSetId ?? "C
   ].join("\n");
 }
 
+/** The rows of a conformance result, as `design check` and a refused submit print them. */
+export function conformanceLines(r) {
+  const lines = [];
+  for (const f of r.findings ?? []) lines.push(`  ${f.nodeId}\t${f.check}\t${f.detail}`);
+  if (r.staleOverrides?.length) {
+    lines.push(`${r.staleOverrides.length} stale override(s), equal to the main (not failures; clear them with Reset):`);
+    for (const f of r.staleOverrides) lines.push(`  ${f.nodeId}\tstale\t${f.detail}`);
+  }
+  if (r.libraryUpdatePending?.length) {
+    lines.push(`${r.libraryUpdatePending.length} node(s) behind a library republish (not failures; accept the library update in this file, MW6-17):`);
+    for (const f of r.libraryUpdatePending) lines.push(`  ${f.nodeId}\t${f.check ?? "libraryUpdatePending"}\t${f.detail}`);
+  }
+  // Warnings never refuse: STALE_FIGMA_VERSION is one (Dev issue 92, until
+  // Dev issue 107). With staleVersion, its wait is printed below instead.
+  const warnings = (r.warnings ?? []).filter((f) => !(r.staleVersion && f.check === "STALE_FIGMA_VERSION"));
+  if (warnings.length) {
+    lines.push(`${warnings.length} warning(s) (not refusals):`);
+    for (const f of warnings) lines.push(`  ${f.nodeId}\t${f.check}\t${f.detail}`);
+  }
+  const v = r.staleVersion;
+  if (v) {
+    lines.push(`STALE_FIGMA_VERSION (a warning, not a refusal): version ${v.figmaVersion}${v.figmaVersionAt ? ` (${v.figmaVersionAt})` : " (not among Figma's recent versions)"} predates this lane's last write at ${v.lastWriteAt}.`);
+    lines.push(v.retryAfter
+      ? `  Figma has cut no version since (latest ${v.latestVersion ?? "none"}${v.latestVersionAt ? ` at ${v.latestVersionAt}` : ""}). Retry after ${v.retryAfter}, or ask the coordinator to have the operator File > Save to version history.`
+      : `  A newer version already holds the write: submit with --figma-version ${v.latestVersion}${v.latestVersionAt ? ` (${v.latestVersionAt})` : ""}.`);
+  }
+  return lines;
+}
+
+/** Dev's DS_CONFORMANCE_FAILED (DEC-0034): every finding, its warnings, and the wait on a stale version. */
+export function conformanceRefusalText(message, details, id = "CHANGE_SET") {
+  const n = details?.findings?.length ?? 0;
+  return [message, `${n} finding(s); after fixing, re-run Dev's gate without submitting: nodii-dev design check --change-set ${id} --file SUBMIT.json`, ...conformanceLines(details ?? {})].join("\n");
+}
+
 // Keep Dev's code and message; add what to do next.
 function scopeRefusal(error, id) {
+  if (error?.code === "DS_CONFORMANCE_FAILED")
+    return new CliError(error.code, conformanceRefusalText(error.message, error.details, id), error.exitCode ?? 1, error.details);
   if (error?.code === "SCOPE_CONFLICT")
     return new CliError(error.code, conflictText(error.message, error.details), error.exitCode ?? 1, error.details);
   if (error?.code === "WRITE_OUT_OF_SCOPE")
@@ -242,9 +279,48 @@ export async function figmaScopeAdd(id, scopes, { request = devRequest } = {}) {
   return changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/scopes`, { scopes });
 }
 
+/**
+ * Narrows a held set to exactly these scopes (Dev issue 104,
+ * setDesignChangeSetScopes); the rest is released for other sets. Each must
+ * sit inside what the set holds: the whole file holds everything, a page its
+ * components and creates.
+ */
+export async function figmaScopeSet(id, scopes, { request = devRequest } = {}) {
+  if (!id || !scopes.length) throw new CliError("USAGE", `figma scope set CHANGE_SET ${SCOPE_USAGE} [--scope ...]`, 2);
+  try {
+    return await request("PUT", `/api/v1/design/change-sets/${encode(id)}/scopes`, { scopes });
+  } catch (error) {
+    if (error?.code === "SCOPE_NOT_NARROWER")
+      throw new CliError(error.code, `${error.message}\nscope set only narrows; to claim more, run nodii-dev figma scope add ${id} --scope ...`, error.exitCode ?? 1, error.details);
+    if (error?.code === "WRITE_OUT_OF_SCOPE")
+      throw new CliError(
+        error.code,
+        [
+          error.message,
+          ...(error.details?.nodeIds?.length ? [`Would fall outside: ${error.details.nodeIds.join(", ")}`] : []),
+          `Keep a scope that holds them (styles and variables need --scope foundations), or revert those nodes to how they were at ${id}'s base version.`,
+        ].join("\n"),
+        error.exitCode ?? 1,
+        error.details,
+      );
+    throw scopeRefusal(error, id) ?? error;
+  }
+}
+
+/** What a narrowing left the set holding, and what it released. */
+export const figmaScopeSetText = (id, data) =>
+  [
+    `${id} holds ${data?.scopes?.length ?? 0} scope(s): ${(data?.scopes ?? []).map(scopeText).join(", ") || "none"}`,
+    ...(data?.released?.length ? [`Released for other sets: ${data.released.map(scopeText).join(", ")}`] : []),
+  ].join("\n");
+
 export const figmaSubmit = (id, payload, { request = devRequest } = {}) =>
   changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/submit`, payload);
 
+/** checkDesignConformance: the submit gate's dry run on a change set; changes no state. Body: { figmaVersion?, items? }. */
+export const figmaConformance = (id, body = {}, { request = devRequest } = {}) =>
+  changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/conformance`, body);
+
 export const figmaLogWrite = (id, tool, nodeIds, { request = devRequest } = {}) =>
   changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/writes`, { tool, nodeIds });