@nodii/dev 0.6.17 → 0.6.21

package/dist/vendor/ds-conformance.mjs

@@ -1,5 +1,6 @@
 // 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).
+// MW6-17, as amended by DEC-0035, DEC-0036 and DEC-0045, and scoped by
+// Dev issue 116).
 //
 // Canonical source: design-system `infra/figma/ds-conformance.mjs`. Every copy
 // (Dev's submit gate, nodii-clis' `design check`) vendors these
@@ -20,13 +21,16 @@
 //             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
+//     returns { version, findings, staleOverrides, libraryUpdatePending,
+//     outOfScope, outOfScopeNodes }, each list a list of { nodeId, check,
+//     detail }; only `findings` fail. `outOfScope` lists the roots of what
+//     the app-UI gate doesn't check (the Email kit), `outOfScopeNodes` how
+//     many nodes they hold
 //   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";
+export const VERSION = "1.0.4";
 
 /** @typedef {{ nodeId: string, check: string, detail: string }} Finding */
 /**
@@ -118,13 +122,30 @@ const TEXT_STYLE_FIELDS = new Set([
 const STYLE_FIELD = /^(inherit)?(Fill|Stroke|Text|Effect|Grid)StyleId$/i;
 
 const SURFACE_NAME = /^Surface \//;
+// Email is out of the app-UI gate's scope (Dev issue 116): the Email kit's
+// twelve registered parts (DESIGN-SYSTEM-33), an email (a frame named Email
+// that places only those parts), and the template editor's block palette.
+const EMAIL_KIT =
+  /^Email ?\/ ?(Header|Alert strip|Heading|Amount block|Button|Link fallback|Divider|Key-value row|Security note|Code box|QR pay block|Footer)$/i;
+const EMAIL_FRAME = /^email\b/i;
+const BLOCK_PALETTE = /^(email )?blocks? (panel|palette)$/i;
+// A column of a table, grid or list; a page named "List Page" is no column.
+const TABLE_CONTAINER = /table|list|grid/i;
+const NOT_A_TABLE = /\blist page\b/i;
 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;
+  /sidebar ?footer|user button|user menu|account menu|profile|\b(my|own) (account|tokens?|security|sessions?|settings|notification settings|records?)\b/i;
+// A frame the screen marks as the viewer's own: "[self]", "(self)", a
+// trailing "· self", or "(you)".
+const SELF_MARK = /\[self\]|\(self\)|·\s*self\s*$|\(you\)/i;
+// Where the screens show who the viewer is: the App Frame footer, the user
+// and account menus, and frames marked self or named my/own.
+const VIEWER_PLACE =
+  /sidebar ?footer|user button|user menu|account menu|\b(my|own) (profile|account|tokens?|security|sessions?|settings)\b/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
@@ -143,6 +164,16 @@ const PHONE = /(?<![\w.+\-/])\+?\(?\d[\d ().-]{7,}\d(?![\w\-/])/g;
 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;
+// otherPersonRevealed is about people (Dev issue 116): a value is judged
+// by the field it fills. A tenant's business contact (support phone or
+// email, caller or sender id, business address) is not personal.
+const BUSINESS_FIELD =
+  /\b(support|help ?desk|helpline|hotline|toll[- ]free|caller id|sender( id)?|sending (address|domain|number)|from (address|email|number)|reply[- ]to|business|tenant)\b/i;
+// A person's field wins: "Support agent" is a person.
+const PERSON_FIELD =
+  /\b(user|member|customer|recipient|applicant|employee|candidate|assignee|owner|invitee|requester|reviewer|agent|engineer|staff|rep|manager|person|personal|your|my)\b/i;
+// A field's frame names its label: field/Caller ID, select/Sender ID.
+const FIELD_FRAME = /^(field|select|input|textarea|kv|detail|row) ?\/ ?(.+)$/i;
 
 /** "I12:34;56:78" -> ["12:34", "56:78"]; "12:34" -> ["12:34"]. */
 const segments = (id) => (id.startsWith("I") ? id.slice(1) : id).split(";");
@@ -325,6 +356,25 @@ function analyse(entry, mains, library = false) {
   };
   const componentLabel = (inst) =>
     setOf(inst)?.name ?? componentOf(inst)?.name ?? inst.name;
+  // What the app-UI gate leaves out: each root, outermost first (byId is in
+  // document order, so a parent is decided before its children).
+  /** @type {Map<string, string>} */
+  const scopeRoots = new Map();
+  /** @type {Map<string, "kit" | "other" | "none">} */
+  const placedMemo = new Map();
+  const out = new Set();
+  for (const n of byId.values()) {
+    const p = parent.get(n.id);
+    if (p && out.has(p.id)) {
+      out.add(n.id);
+      continue;
+    }
+    const why = outOfScopeRoot(n, parent, componentLabel, placedMemo);
+    if (why) {
+      out.add(n.id);
+      scopeRoots.set(n.id, why);
+    }
+  }
   return {
     root,
     components,
@@ -340,7 +390,54 @@ function analyse(entry, mains, library = false) {
     componentOf,
     setOf,
     componentLabel,
+    out,
+    scopeRoots,
+  };
+}
+
+const emailKitPart = (n, parent, componentLabel) =>
+  (n.type === "INSTANCE" && EMAIL_KIT.test(componentLabel(n) ?? "")) ||
+  ((n.type === "COMPONENT" || n.type === "COMPONENT_SET") &&
+    (EMAIL_KIT.test(n.name ?? "") ||
+      (n.type === "COMPONENT" &&
+        EMAIL_KIT.test(parent.get(n.id)?.name ?? ""))));
+/**
+ * Why a node and everything in it is outside the app-UI gate, or null: an
+ * Email kit part, an email made of them (a frame named Email whose only
+ * placed parts, at any depth, are the kit's), or the template editor's
+ * block palette.
+ */
+function outOfScopeRoot(n, parent, componentLabel, memo) {
+  if (emailKitPart(n, parent, componentLabel))
+    return `Email kit part ${n.type === "INSTANCE" ? componentLabel(n) : n.name}`;
+  if (n.type !== "FRAME" && n.type !== "GROUP" && n.type !== "SECTION")
+    return null;
+  if (BLOCK_PALETTE.test(n.name ?? "")) return `email block palette ${n.name}`;
+  // Every part placed in it, at any depth, is the kit's.
+  /** @returns {"kit" | "other" | "none"} */
+  const placed = (x) => {
+    const hit = memo.get(x.id);
+    if (hit) return hit;
+    let kind = /** @type {"kit" | "other" | "none"} */ ("none");
+    if (emailKitPart(x, parent, componentLabel)) kind = "kit";
+    else if (x.type === "INSTANCE") kind = "other";
+    else
+      for (const c of x.children ?? []) {
+        const k = placed(c);
+        if (k === "other") {
+          kind = "other";
+          break;
+        }
+        if (k === "kit") kind = "kit";
+      }
+    memo.set(x.id, kind);
+    return kind;
   };
+  // An email is named so; an editor's workspace around it, or an app screen
+  // holding a kit part, stays in scope.
+  return EMAIL_FRAME.test(n.name ?? "") && placed(n) === "kit"
+    ? `email ${n.name}`
+    : null;
 }
 
 /** Component ids whose mains the check still needs. */
@@ -350,7 +447,7 @@ export function neededMains(nodes, mains = {}, options = {}) {
     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 (n.type !== "INSTANCE" || !n.componentId || a.out.has(n.id)) 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).
@@ -423,7 +520,8 @@ function textOf(n) {
  *   mains?: Record<string, NodesEntry | null>,
  *   options?: { library?: boolean, declaredRoles?: string[] } }} input
  * @returns {{ version: string, findings: Finding[], staleOverrides: Finding[],
- *   libraryUpdatePending: Finding[] }}
+ *   libraryUpdatePending: Finding[], outOfScope: Finding[],
+ *   outOfScopeNodes: number }}
  */
 export function checkConformance({
   nodes,
@@ -440,6 +538,9 @@ export function checkConformance({
   const staleOverrides = [];
   /** @type {Finding[]} */
   const libraryUpdatePending = [];
+  /** @type {Finding[]} */
+  const outOfScope = [];
+  const outNodes = new Set();
   const seen = new Set();
   const push = (list, nodeId, check, detail) => {
     const key = `${nodeId}|${check}|${detail}`;
@@ -454,12 +555,46 @@ export function checkConformance({
       labelRoles.set(label.trim().toLowerCase(), r);
   const librarySetNames = new Set();
   const usedRoles = new Set();
+  const analyses = Object.values(nodes ?? {})
+    .filter((entry) => entry?.document)
+    .map((entry) => analyse(entry, mains, library));
+  // The viewer (R5): the email and phone the screens show in the viewer's
+  // own places (the App Frame footer, a frame marked self). The same value
+  // anywhere else is still the viewer's own.
+  const viewer = new Set();
+  for (const a of analyses)
+    for (const n of a.byId.values()) {
+      if (n.type !== "TEXT" || a.out.has(n.id)) continue;
+      const ids = identifiers(textOf(n));
+      if (ids.length === 0) continue;
+      if (
+        a
+          .ancestors(n)
+          .some(
+            (x) =>
+              VIEWER_PLACE.test(x.name ?? "") || SELF_MARK.test(x.name ?? ""),
+          )
+      )
+        for (const id of ids) viewer.add(id);
+    }
 
-  for (const entry of Object.values(nodes ?? {})) {
-    if (!entry?.document) continue;
-    const a = analyse(entry, mains, library);
+  for (const a of analyses) {
     for (const set of Object.values(a.componentSets))
       if (set?.remote) librarySetNames.add(set.name);
+    for (const [nodeId, why] of a.scopeRoots) {
+      let count = 0;
+      for (const n of indexTree(a.byId.get(nodeId)).byId.values()) {
+        if (!outNodes.has(n.id)) count++;
+        outNodes.add(n.id);
+      }
+      if (count > 0)
+        push(
+          outOfScope,
+          nodeId,
+          "outOfScope",
+          `${why}: ${count} node${count === 1 ? "" : "s"} outside the app-UI gate (email, Dev issue 116)`,
+        );
+    }
     // Every (node, field) the screen overrode on an instance it placed.
     /** @type {Map<string, { fields: Set<string>, from: any }>} */
     const overrideFields = new Map();
@@ -481,12 +616,16 @@ export function checkConformance({
     // 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;
+      if (!node || !a.shown(node) || a.out.has(id)) 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 ?? {};
+      // Slot content a library part ships by default: its value there is
+      // the library's, not this file's (DEC-0047).
+      /** @type {ReturnType<typeof defaultSlotContent> | undefined} */
+      let slotDefault;
       const differ = [];
       const equal = [];
       for (const field of [...fields].sort()) {
@@ -494,7 +633,20 @@ export function checkConformance({
         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);
+        if (sameValue(mine, theirs)) {
+          equal.push(field);
+          continue;
+        }
+        if (slotDefault === undefined)
+          slotDefault = defaultSlotContent(a, mains, node);
+        if (
+          slotDefault &&
+          sameValue(
+            mine,
+            fieldValue(slotDefault.node, field, slotDefault.styles),
+          )
+        )
+          equal.push(field);
         else
           differ.push(
             `${field} ${shortValue(mine)} (main ${shortValue(theirs)})`,
@@ -518,7 +670,7 @@ export function checkConformance({
     }
 
     for (const n of a.byId.values()) {
-      if (!a.shown(n)) continue;
+      if (!a.shown(n) || a.out.has(n.id)) continue;
       const own = !a.composed(n);
 
       if (n.type === "INSTANCE")
@@ -670,14 +822,17 @@ export function checkConformance({
         revealedByPermission(a, n)
       )
         continue;
-      for (const m of text.matchAll(EMAIL)) {
+      const business = businessField(a, n);
+      for (const m of business ? [] : text.matchAll(EMAIL)) {
         const local = m[0].split("@")[0] ?? "";
         if (MASKED.test(local) || ROLE_MAILBOX.test(local)) continue;
+        if (viewer.has(m[0].toLowerCase())) continue;
         push(findings, n.id, "otherPersonRevealed", `unmasked email ${m[0]}`);
       }
-      for (const m of text.matchAll(PHONE)) {
+      for (const m of business ? [] : text.matchAll(PHONE)) {
         const digits = m[0].replace(/\D/g, "");
-        if (DATE.test(m[0]) || MASKED.test(m[0])) continue;
+        if (DATE.test(m[0]) || MASKED.test(m[0]) || viewer.has(digits))
+          continue;
         const phoneShaped =
           m[0].startsWith("+") || LOCAL_PHONE.test(m[0].trim());
         if (phoneShaped && digits.length >= 10 && digits.length <= 15)
@@ -703,14 +858,19 @@ export function checkConformance({
       if (
         header.type !== "TEXT" ||
         !CUSTOMER_HEADER.test(textOf(header)) ||
-        !a.shown(header)
+        !a.shown(header) ||
+        a.out.has(header.id)
       )
         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 ?? ""));
+        .find(
+          (x) =>
+            TABLE_CONTAINER.test(x.name ?? "") &&
+            !NOT_A_TABLE.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);
@@ -723,7 +883,13 @@ export function checkConformance({
           : 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 (
+          n.type !== "TEXT" ||
+          n.id === header.id ||
+          !a.shown(n) ||
+          a.out.has(n.id)
+        )
+          continue;
         if (!screenText(a, n, overridden)) continue;
         const b = n.absoluteBoundingBox;
         const text = textOf(n);
@@ -760,7 +926,74 @@ export function checkConformance({
         `declared role ${role.role} has no ${role.componentName} instance`,
       );
   }
-  return { version: VERSION, findings, staleOverrides, libraryUpdatePending };
+  return {
+    version: VERSION,
+    findings,
+    staleOverrides,
+    libraryUpdatePending,
+    outOfScope,
+    outOfScopeNodes: outNodes.size,
+  };
+}
+
+/** The emails (lower-cased) and phone digits a text shows. */
+function identifiers(text) {
+  return [
+    ...[...text.matchAll(EMAIL)].map((m) => m[0].toLowerCase()),
+    ...[...text.matchAll(PHONE)].map((m) => m[0].replace(/\D/g, "")),
+  ];
+}
+
+/**
+ * The labels of the field a text fills: its field frame's name
+ * (field/Caller ID), a Field instance's label, and its own layer name.
+ */
+function fieldLabels(a, n) {
+  const labels = [];
+  if (n.name && n.name !== n.characters) labels.push(n.name);
+  for (const x of a.ancestors(n).slice(0, 4)) {
+    const m = FIELD_FRAME.exec(x.name ?? "");
+    if (m) labels.push(m[2]);
+    for (const [prop, v] of Object.entries(x.componentProperties ?? {}))
+      if (/^label\b/i.test(prop) && typeof v?.value === "string")
+        labels.push(v.value);
+  }
+  return labels;
+}
+/** A business contact field (support, caller id, sender, business address). */
+function businessField(a, n) {
+  const labels = fieldLabels(a, n);
+  return (
+    labels.some((l) => BUSINESS_FIELD.test(l)) &&
+    !labels.some((l) => PERSON_FIELD.test(l))
+  );
+}
+
+/**
+ * The node a library part's main draws, by default, where `node` sits in
+ * slot content: the nearest slot above it, in the instance that owns that
+ * slot, matched by the layer names from the slot down. Null when the node
+ * isn't in slot content, the owner's main can't be read, or its default
+ * content has no such layer.
+ */
+function defaultSlotContent(a, mains, node) {
+  const up = a.ancestors(node);
+  const slotAt = up.findIndex((x) => x.type === "SLOT");
+  if (slotAt === -1) return null;
+  const slot = up[slotAt];
+  const owner = up.slice(slotAt + 1).find((x) => x.type === "INSTANCE");
+  const tree = owner ? a.mainTree(owner.componentId) : null;
+  if (!owner || !tree) return null;
+  const main = mains[owner.componentId];
+  const names = [...up.slice(0, slotAt).reverse(), node].map((x) => x.name);
+  let level = [...tree.byId.values()].filter(
+    (x) => x.type === "SLOT" && x.name === slot.name,
+  );
+  for (const name of names)
+    level = level.flatMap((x) =>
+      (x.children ?? []).filter((c) => c.name === name),
+    );
+  return level[0] ? { node: level[0], styles: main.styles ?? {} } : null;
 }
 
 /**
@@ -865,7 +1098,12 @@ function handDrawnButton(n) {
 }
 function isSelf(a, n) {
   const up = a.ancestors(n);
-  if (up.some((x) => SELF_CONTAINER.test(x.name ?? ""))) return true;
+  if (
+    up.some(
+      (x) => SELF_CONTAINER.test(x.name ?? "") || SELF_MARK.test(x.name ?? ""),
+    )
+  )
+    return true;
   const accountCard = (x) => {
     const set =
       x.type === "INSTANCE"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.17",
+  "version": "0.6.21",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {