@gakim-digital/dexter-bridge 0.12.2 → 0.13.1

package/src/framerRequirementContract.js

@@ -0,0 +1,303 @@
+// The model turns the user's request into requirements it can check: a value
+// a layer must carry, a link, a size, a distance, a layer that must stay
+// inside its parent. This module checks them against live Framer data, so a
+// requirement counts as met because Framer shows it, not because the model
+// says so. Dexter does not model Framer's features: the model names the layer
+// and the property, and this module reads what is there.
+
+const MAX_SEARCH_DEPTH = 6;
+const MAX_OBSERVED_CHARS = 1000;
+const DEFAULT_TOLERANCE_PX = 2;
+export const MEASURES = ['width', 'height', 'gap', 'insideParent'];
+
+function isRecord(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function text(value, maximum = 500) {
+  return typeof value === 'string'
+    ? value.trim().slice(0, maximum)
+    : '';
+}
+
+function uniqueStrings(values, maximum = 50) {
+  return Array.from(new Set(
+    (Array.isArray(values) ? values : [])
+      .map((value) => text(value, 500))
+      .filter(Boolean),
+  )).slice(0, maximum);
+}
+
+function contractError(code, message) {
+  return Object.assign(new Error(message), { code, statusCode: 400 });
+}
+
+function normalizeRequirement(raw, index) {
+  const id = text(raw?.id, 120);
+  const description = text(raw?.text, 500);
+  if (!isRecord(raw) || !id || description.length < 3) {
+    throw contractError(
+      'FRAMER_REQUIREMENT_INVALID',
+      `Requirement ${index + 1} needs an id and the text of what must be true.`,
+    );
+  }
+  return { id, text: description, nodeIds: uniqueStrings(raw.nodeIds, 50) };
+}
+
+export function normalizeRequirements(rawRequirements) {
+  const requirements = (Array.isArray(rawRequirements) ? rawRequirements : [])
+    .slice(0, 40)
+    .map(normalizeRequirement);
+  const ids = new Set();
+  for (const requirement of requirements) {
+    if (ids.has(requirement.id)) {
+      throw contractError(
+        'FRAMER_REQUIREMENT_INVALID',
+        `Requirement ids must be unique; "${requirement.id}" is duplicated.`,
+      );
+    }
+    ids.add(requirement.id);
+  }
+  return requirements;
+}
+
+export function mergeRequirements(current, next) {
+  const byId = new Map(current.map((item) => [item.id, item]));
+  next.forEach((item) => byId.set(item.id, item));
+  return [...byId.values()];
+}
+
+function finiteNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+export function normalizeChecks(rawChecks, requirements) {
+  const requirementIds = new Set(requirements.map((item) => item.id));
+  const checks = (Array.isArray(rawChecks) ? rawChecks : []).slice(0, 80);
+  if (!checks.length) {
+    throw contractError(
+      'FRAMER_CHECKS_REQUIRED',
+      'Send at least one check: a requirement id, a layer id, and either a property or a measure.',
+    );
+  }
+  return checks.map((raw, index) => {
+    const requirementId = text(raw?.requirementId, 120);
+    const nodeId = text(raw?.nodeId, 200);
+    const property = text(raw?.property, 120);
+    const measure = text(raw?.measure, 40);
+    const invalid = (reason) => contractError(
+      'FRAMER_CHECK_INVALID',
+      `Check ${index + 1} ${reason}`,
+    );
+    if (!isRecord(raw) || !requirementIds.has(requirementId) || !nodeId) {
+      throw invalid(`must name a requirement from your plan (${[...requirementIds].join(', ') || 'none planned'}) and a layer id.`);
+    }
+    if (Boolean(property) === Boolean(measure)) {
+      throw invalid('needs either a property or a measure, not both.');
+    }
+    if (property) {
+      return { requirementId, nodeId, property, contains: text(raw.contains, 500) };
+    }
+    if (!MEASURES.includes(measure)) {
+      throw invalid(`has an unknown measure; use one of ${MEASURES.join(', ')}.`);
+    }
+    const otherNodeId = text(raw.otherNodeId, 200);
+    if (measure === 'gap' && !otherNodeId) throw invalid('measures a gap, so it needs otherNodeId.');
+    const expected = finiteNumber(raw.expected);
+    if (measure !== 'insideParent' && expected === null) {
+      throw invalid(`measures ${measure}, so it needs the expected number of pixels.`);
+    }
+    return {
+      requirementId,
+      nodeId,
+      measure,
+      ...(otherNodeId ? { otherNodeId } : {}),
+      ...(expected !== null ? { expected } : {}),
+      tolerance: Math.max(0, finiteNumber(raw.tolerance) ?? DEFAULT_TOLERANCE_PX),
+    };
+  });
+}
+
+export function checkNodeIds(checks) {
+  return uniqueStrings(checks.filter((check) => check.property).map((check) => check.nodeId), 200);
+}
+
+export function measureChecks(checks) {
+  return checks.filter((check) => check.measure);
+}
+
+function hasContent(value) {
+  if (value === undefined || value === null || value === '') return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (isRecord(value)) return Object.keys(value).length > 0;
+  return true;
+}
+
+// Finds the property on the node itself. Child nodes are skipped so a
+// descendant cannot satisfy a claim about its parent. A dotted name such as
+// `link.href` or `hoverEffect.opacity` reads the field inside the property's value.
+function propertyValues(node, property) {
+  const values = keyValues(node, property);
+  const [head, ...path] = property.split('.');
+  if (values.length > 0 || path.length === 0) return values;
+  return keyValues(node, head)
+    .map((value) => path.reduce(
+      (current, key) => (isRecord(current) ? current[key] : undefined),
+      value,
+    ))
+    .filter(hasContent);
+}
+
+function keyValues(node, property) {
+  const values = [];
+  const visit = (current, depth) => {
+    if (depth > MAX_SEARCH_DEPTH || values.length >= 10) return;
+    if (Array.isArray(current)) {
+      current.forEach((item) => visit(item, depth + 1));
+      return;
+    }
+    if (!isRecord(current)) return;
+    for (const [key, nested] of Object.entries(current)) {
+      if (key === 'children') continue;
+      if (key === property) {
+        if (hasContent(nested)) values.push(nested);
+      } else {
+        visit(nested, depth + 1);
+      }
+    }
+  };
+  visit(node, 0);
+  return values;
+}
+
+function serialized(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return '';
+  }
+}
+
+function propertyVerdict(check, nodes) {
+  const node = nodes instanceof Map ? nodes.get(check.nodeId) : nodes?.[check.nodeId];
+  if (!node) return { ...check, verdict: 'unknown', reason: `layer ${check.nodeId} was not found` };
+  const values = propertyValues(node, check.property);
+  if (values.length === 0) {
+    return { ...check, verdict: 'unknown', reason: `${check.property} is not set on ${check.nodeId}` };
+  }
+  const observed = serialized(values.length === 1 ? values[0] : values);
+  if (check.contains && !observed.toLowerCase().includes(check.contains.toLowerCase())) {
+    return {
+      ...check,
+      verdict: 'contradicted',
+      reason: `${check.property} on ${check.nodeId} is ${observed.slice(0, 200)}, not ${check.contains}`,
+      observedValue: observed.slice(0, MAX_OBSERVED_CHARS),
+    };
+  }
+  return { ...check, verdict: 'verified', observedValue: observed.slice(0, MAX_OBSERVED_CHARS) };
+}
+
+// `measured` holds what the measuring program found for each measure check,
+// in the same order: { value } in pixels, { inside, overflow } for
+// insideParent, or { error }.
+function measureVerdict(check, measured) {
+  if (!measured || measured.error) {
+    return { ...check, verdict: 'unknown', reason: measured?.error || `${check.nodeId} could not be measured` };
+  }
+  if (check.measure === 'insideParent') {
+    return measured.inside
+      ? { ...check, verdict: 'verified', observedValue: 'inside its parent' }
+      : {
+          ...check,
+          verdict: 'contradicted',
+          reason: `${check.nodeId} sticks out of its parent by ${measured.overflow}px`,
+          observedValue: `overflows by ${measured.overflow}px`,
+        };
+  }
+  const value = Number(measured.value);
+  const label = check.measure === 'gap' ? `gap between ${check.nodeId} and ${check.otherNodeId}` : `${check.measure} of ${check.nodeId}`;
+  if (Math.abs(value - check.expected) <= check.tolerance) {
+    return { ...check, verdict: 'verified', observedValue: `${value}px` };
+  }
+  return {
+    ...check,
+    verdict: 'contradicted',
+    reason: `${label} measures ${value}px, not ${check.expected}px`,
+    observedValue: `${value}px`,
+  };
+}
+
+export function verifyChecks({ checks, nodes, measurements = [] }) {
+  let measureIndex = 0;
+  return checks.map((check) => (check.property
+    ? propertyVerdict(check, nodes)
+    : measureVerdict(check, measurements[measureIndex++])));
+}
+
+// Summarizes the latest check results for every requirement. A requirement is
+// met once every layer it names has a verified check (or, naming none, once
+// one check verified it) and no check contradicts it.
+// status: missing (a requirement or one of its layers was never checked),
+// contradicted (Framer shows something else), unverified (a property or
+// layer could not be found), or verified.
+export function summarizeRequirements(requirements, checkResults) {
+  const items = requirements.map((requirement) => {
+    const results = checkResults.filter((result) => result.requirementId === requirement.id);
+    const verifiedNodeIds = new Set(
+      results.filter((result) => result.verdict === 'verified').map((result) => result.nodeId),
+    );
+    const contradictions = results
+      .filter((result) => result.verdict === 'contradicted')
+      .map((result) => result.reason);
+    const checkedNodeIds = new Set(results.map((result) => result.nodeId));
+    const uncheckedNodeIds = requirement.nodeIds.filter((nodeId) => !checkedNodeIds.has(nodeId));
+    const covered = requirement.nodeIds.length > 0
+      ? requirement.nodeIds.every((nodeId) => verifiedNodeIds.has(nodeId))
+      : verifiedNodeIds.size > 0;
+    return {
+      requirementId: requirement.id,
+      text: requirement.text,
+      checked: results.length > 0 && uncheckedNodeIds.length === 0,
+      verdict: contradictions.length > 0 ? 'contradicted' : covered ? 'verified' : 'unknown',
+      uncheckedNodeIds,
+      contradictions: uniqueStrings(contradictions, 20),
+      unknowns: uniqueStrings(
+        results.filter((result) => result.verdict === 'unknown').map((result) => result.reason),
+        20,
+      ),
+    };
+  });
+  const status = items.some((item) => !item.checked)
+    ? 'missing'
+    : items.some((item) => item.verdict === 'contradicted')
+      ? 'contradicted'
+      : items.some((item) => item.verdict === 'unknown')
+        ? 'unverified'
+        : 'verified';
+  return { status, requirements: items };
+}
+
+// Compares two snapshots of layers that had to stay as they were. A snapshot
+// maps a layer id to { name, rect, props } where props is the serialized
+// layer without children.
+export function unchangedViolations(before, after, tolerance = 1) {
+  const changes = [];
+  for (const [id, earlier] of Object.entries(before || {})) {
+    const later = after?.[id];
+    const name = earlier.name || id;
+    if (!later) {
+      changes.push(`${name} was removed`);
+      continue;
+    }
+    const a = earlier.rect;
+    const b = later.rect;
+    if (a && b && ['x', 'y', 'width', 'height'].some((key) => Math.abs(a[key] - b[key]) > tolerance)) {
+      changes.push(`${name} moved or resized (${a.width}×${a.height} at ${a.x},${a.y} → ${b.width}×${b.height} at ${b.x},${b.y})`);
+    } else if (earlier.props !== later.props) {
+      changes.push(`${name} has different settings`);
+    }
+    if (changes.length >= 20) break;
+  }
+  return changes;
+}