@1agh/maude 0.58.2 → 0.59.0

package/apps/studio/figma/sanitize.ts

@@ -0,0 +1,407 @@
+/**
+ * @file       figma/sanitize.ts — the content rules (DDR-216 D6a + D6b).
+ * @scope      apps/studio/figma/sanitize.ts
+ * @purpose    The ONE place Figma-derived strings are made safe to emit, and
+ *             the ONE place imported nodes are made VISIBLE. Both translators
+ *             (`to-strokes.ts`, `to-artboard.ts`) go through here — D6's
+ *             "single writers" requirement is what makes the standing grep test
+ *             ("no translator interpolates a node's `name`/`characters` into
+ *             output itself") a real control rather than a hope.
+ *
+ * @invariant  TWO INDEPENDENT MECHANISMS, because Round 2 of the DDR-216 review
+ *             broke a single one twice:
+ *
+ *             D6a — CHARACTER CLASSES. An escaper covers characters that could
+ *             terminate a literal. It does NOT cover characters with NO GLYPH.
+ *             A payload encoded in the Unicode Tags block (U+E0000–E007F) — a
+ *             full ASCII alphabet that renders as literally nothing — passes
+ *             opacity 1, fontSize 16, high contrast, non-zero area, the escaper
+ *             AND `sanitizeAnnotationSvg`, and is reconstructed as plain text by
+ *             a model reading the file. Same for zero-width characters and the
+ *             Trojan-Source bidi technique (CVE-2021-42574), where the rendered
+ *             order a human reviews differs from the source order.
+ *
+ *             D6b — VISIBILITY, BY NORMALIZATION NOT DETECTION. The first draft
+ *             tried to DETECT invisible nodes (opacity / fontSize / ΔE / clip)
+ *             and the review broke it four ways — occlusion by an opaque later
+ *             sibling, ancestor clipping, opacity compounded down the tree, and
+ *             blend mode over a matching background — none of which a per-node
+ *             property check can see. The translator AUTHORS these nodes, so it
+ *             can GUARANTEE visibility instead of proving invisibility: clamp
+ *             the size, force the contrast, clamp the geometry. Hidden text
+ *             becomes VISIBLE text, which is strictly better than dropping it.
+ *
+ * @invariant  Neither mechanism makes an instruction stop reading like an
+ *             instruction. That is DDR-216 residual 1, named there, not a bug
+ *             here. What these rules buy is that nothing an agent later reads
+ *             is invisible to the human who imported it.
+ *
+ * @invariant  DEPENDENCY-FREE — pure string/number work.
+ */
+
+/** Every disposition this feature can report. A FIXED set: the per-import
+ *  summary's "never silently dropped" promise is only true because a caller
+ *  cannot invent a reason string (DDR-216 D5/D7).
+ *
+ *  A frozen ARRAY, with the type derived from it, rather than a bare union —
+ *  because a union alone is a compile-time promise and this repo runs **no
+ *  `tsc` gate** (CLAUDE.md states the omission deliberately: `quality` is
+ *  lint/tests/build/parity/tarball/tokens/site-content, no typecheck). That gap
+ *  is not hypothetical: `assets.ts` shipped `'asset-degraded'` — absent from the
+ *  union — to `main`, onto the wire (`http.ts` `/_api/figma/import`), into verb
+ *  stdout that an agent reads (D10), and into `FigmaImportPanel`. Found by the
+ *  DDR-219 design-stage review, fixed here with `asset-degraded` admitted as the
+ *  legitimate outcome it always was. See DDR-219 D9. */
+export const DISPOSITIONS = Object.freeze([
+  'imported',
+  'hidden-chars-dropped',
+  'hidden-node-skipped',
+  'text-normalized',
+  'geometry-clamped',
+  'truncated-text',
+  'truncated-attr',
+  'unmappable-type',
+  'unmappable-shape',
+  /** A comment whose pinned node no longer exists in the file — no position to place it at. */
+  'comment-target-deleted',
+  'bind-degraded-to-bbox',
+  'bind-dropped-self-connector',
+  'asset-pending',
+  'asset-skipped',
+  'asset-cap-reached',
+  /** A vector Figma declined to render as SVG, re-requested as PNG. */
+  'asset-degraded',
+  'jsx-cap-reached',
+  'value-rejected',
+  // ── The codegen route (DDR-219 D9). Three dispositions, one rule: what makes
+  // them safe is that `detail` carries a BOUNDED token plus a count, never the
+  // upstream family or utility name verbatim — `detail` is the one field on the
+  // wire no sanitizer touches, and it reaches verb stdout (D10), the HTTP route
+  // and the panel.
+  /** A Tailwind utility the mapper does not know, or whose value failed its grammar. */
+  'codegen-utility-unmapped',
+  /** A font family that did not survive the copy — a CSS fallback is NOT a report. */
+  'font-substituted',
+  /** Dev Mode unreachable / no seat / wrong document. The COMMON case, not an error state. */
+  'codegen-unavailable',
+  /** The converter itself could not be LOADED. Contract: REFUSE, never "let a model do it". */
+  'codegen-converter-unavailable',
+  /**
+   * The converter ran and REFUSED this frame — a parse error, an element outside
+   * the allowlist, a construct it does not understand (DDR-219 D5 rule 4).
+   *
+   * Deliberately NOT folded into `codegen-unavailable`: "Figma was unreachable"
+   * and "we looked at what Figma sent and would not emit it" are different
+   * facts, and conflating outcomes is how this feature reported success three
+   * times while losing content.
+   */
+  'codegen-frame-refused',
+] as const);
+
+export type Disposition = (typeof DISPOSITIONS)[number];
+
+const DISPOSITION_SET: ReadonlySet<string> = new Set(DISPOSITIONS);
+
+export function isDisposition(v: string): v is Disposition {
+  return DISPOSITION_SET.has(v);
+}
+
+/** `detail` is a code-owned note, and the only field on the wire that no
+ *  sanitizer touches — so it is the one place an upstream string would ride out
+ *  to a model unescaped (DDR-219 D9). It is NOT charset-restricted to ASCII:
+ *  real notes carry `—` and `→` legitimately. What distinguishes a code-owned
+ *  note from interpolated node text is that it is SHORT and carries no
+ *  zero-glyph payload, so those are what get asserted. Longest real note today
+ *  is 36 chars. */
+export const MAX_DETAIL_LEN = 64;
+
+export interface ReportEntry {
+  /** `^[0-9]+:[0-9]+$` — an identifier, never node text (DDR-216 D7). */
+  nodeId: string;
+  type: string;
+  disposition: Disposition;
+  /** A short code-owned note. NEVER node text, never an upstream string. */
+  detail?: string;
+}
+
+/** Collects dispositions. One per node per outcome; text is never quoted in. */
+export class ImportReport {
+  readonly entries: ReportEntry[] = [];
+
+  add(nodeId: string, type: string, disposition: Disposition, detail?: string): void {
+    // The backstop the missing `tsc` gate cannot provide. A disposition outside
+    // the set is a programming error, never bad input — so it throws rather than
+    // degrading: silent acceptance is exactly how `asset-degraded` reached main.
+    if (!DISPOSITION_SET.has(disposition)) {
+      throw new Error(`ImportReport: unknown disposition ${JSON.stringify(disposition)}`);
+    }
+    if (detail !== undefined && !isCodeOwnedDetail(detail)) {
+      throw new Error(
+        `ImportReport: detail must be a short code-owned note (<=${MAX_DETAIL_LEN} chars, no zero-glyph); got ${detail.length} chars`
+      );
+    }
+    this.entries.push(
+      detail ? { nodeId, type, disposition, detail } : { nodeId, type, disposition }
+    );
+  }
+
+  count(disposition: Disposition): number {
+    return this.entries.filter((e) => e.disposition === disposition).length;
+  }
+}
+
+/** True when `detail` looks like the code-owned note it is contracted to be. */
+export function isCodeOwnedDetail(detail: string): boolean {
+  return detail.length <= MAX_DETAIL_LEN && !ZERO_GLYPH_ONESHOT_RE.test(detail);
+}
+
+// ── D6a — character classes ─────────────────────────────────────────────────
+
+/**
+ * Characters with no glyph, or which reorder what a human sees relative to what
+ * is stored. Enumerated as ranges rather than a "printable ASCII only" filter,
+ * because unlike DDR-172's CSS values this text legitimately carries diacritics,
+ * CJK and emoji — the fixture's own `Příliš žluťoučký` must survive intact.
+ */
+/**
+ * Characters with no glyph, or which reorder what a human sees relative to what
+ * is stored.
+ *
+ * POSITIVE-CATEGORY rule, not a hand-kept range list. The first version
+ * enumerated ranges and was called "genuinely complete"; it was not — it missed
+ * U+3164 HANGUL FILLER (Unicode category **Lo**, a LETTER, which is exactly why
+ * whitespace/format filters keep it), U+FFA0, U+115F/U+1160, U+2800 BRAILLE
+ * PATTERN BLANK, U+180E, U+061C ARABIC LETTER MARK (a Trojan-Source control the
+ * paper lists), and U+FFF9–FFFB. Two of those are a binary alphabet; four are
+ * base-4 (post-implementation review F10).
+ *
+ * So: reject every format/control/unassigned/private-use code point by CATEGORY
+ * (`\p{Cf}\p{Cc}\p{Co}\p{Cn}`), plus an explicit list of code points that are
+ * *letters or symbols* by category but render blank. A category rule cannot rot
+ * the way an enumeration does.
+ */
+const ZERO_GLYPH_SOURCE = [
+  // Format / control / private-use / unassigned — the categories that cover
+  // every bidi control, every zero-width, the Tags block, and anything Unicode
+  // adds later without this list needing an edit.
+  '[\\p{Cf}\\p{Cc}\\p{Co}\\p{Cn}]',
+  // Blank-rendering code points that are LETTERS or SYMBOLS by category, so no
+  // category rule catches them. Listed one per alternative rather than as a
+  // character class: `\u034F` is a COMBINING character, and a class mixing it
+  // with base characters is the `noMisleadingCharacterClass` footgun.
+  '\\u00AD', // soft hyphen
+  '\\u034F', // combining grapheme joiner
+  '\\u061C', // arabic letter mark (Trojan Source)
+  '\\u115F', // hangul choseong filler
+  '\\u1160', // hangul jungseong filler
+  '\\u17B4', // khmer inherent AQ
+  '\\u17B5', // khmer inherent AA
+  '[\\u180B-\\u180E]', // mongolian selectors + vowel separator
+  '\\u2800', // braille pattern blank
+  '\\u3164', // HANGUL FILLER — category Lo, i.e. a LETTER
+  '[\\uFE00-\\uFE0F]', // variation selectors
+  '\\uFFA0', // halfwidth hangul filler
+  '[\\uFFF9-\\uFFFB]', // interlinear annotation
+  '[\\u{E0100}-\\u{E01EF}]', // variation selectors supplement
+].join('|');
+
+const ZERO_GLYPH_RE = new RegExp(ZERO_GLYPH_SOURCE, 'gu');
+
+/** The same rule without `g`. `RegExp.prototype.test` on a GLOBAL regex advances
+ *  `lastIndex` and so alternates true/false across calls on the same instance —
+ *  a one-shot predicate must never share the `g` instance. */
+const ZERO_GLYPH_ONESHOT_RE = new RegExp(ZERO_GLYPH_SOURCE, 'u');
+
+/** Tab / newline / carriage return are legitimate content — never stripped. */
+const KEEP_WHITESPACE_RE = /[\t\n\r]/;
+
+export interface CleanTextResult {
+  text: string;
+  /** True when D6a removed something — the caller reports `hidden-chars-dropped`. */
+  strippedHidden: boolean;
+  /** True when the length cap bit — the caller reports `truncated-text`. */
+  truncated: boolean;
+}
+
+/**
+ * D6a: NFC-normalize, strip zero-glyph/bidi characters, collapse runs of
+ * whitespace-ish control leftovers, and bound the length.
+ *
+ * `maxLen` is a per-sink capacity, not a security bound — the security bound is
+ * the character classes. A sticky that would overflow its card is truncated and
+ * REPORTED rather than silently overflowing (DDR-216 D5's bounded-degradation
+ * class, which is why `truncated` comes back rather than being swallowed).
+ */
+export function cleanText(raw: string, maxLen: number): CleanTextResult {
+  const normalized = raw.normalize('NFC');
+  const stripped = normalized.replace(ZERO_GLYPH_RE, (ch) =>
+    KEEP_WHITESPACE_RE.test(ch) ? ch : ''
+  );
+  const strippedHidden = stripped.length !== normalized.length;
+  const truncated = stripped.length > maxLen;
+  return { text: truncated ? stripped.slice(0, maxLen) : stripped, strippedHidden, truncated };
+}
+
+/**
+ * Attribute values (`data-dc-element`, a section label chip, …) get a strict
+ * ALLOWLIST charset rather than D6a's denylist: they are short, structural, and
+ * never need the full Unicode range. Empty after sanitizing ⇒ the caller falls
+ * back to a node-id-derived name (DDR-216 D6 sink table).
+ */
+export function attrValue(raw: string, maxLen = 64): string {
+  return raw
+    .normalize('NFC')
+    .replace(/[^A-Za-z0-9 _-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, maxLen);
+}
+
+/**
+ * A report token for `detail` — strict, and deliberately NOT `attrValue`.
+ *
+ * `attrValue` rewrites rejected characters to SPACES, which is right for a label
+ * and wrong here: a class token like `ignore.all.prior.instructions.and` comes
+ * back as that sentence, and `detail` reaches verb stdout (which D10 declares
+ * entirely code-owned), the HTTP summary and the panel. Charset-bounding is a
+ * markup control; it was never a semantic one (post-implementation review F3).
+ *
+ * So: a Tailwind FAMILY shape only — lowercase, digits, hyphens, NO SPACES ever
+ * — and anything else collapses to a fixed word. `unrecognized x7` is less
+ * informative than the raw token and cannot be read as an instruction, which is
+ * the right trade for a field an agent reads.
+ */
+export function reportToken(raw: string): string {
+  const head = /^[a-z][a-z0-9-]{0,23}/.exec(raw.trim().toLowerCase());
+  return head ? head[0] : 'unrecognized';
+}
+
+/**
+ * A JSX-safe identifier derived from a NODE ID — never from a Figma string.
+ * `2:17` → `Node_2_17`. This is the whole identifier story: there is no Figma
+ * text anywhere in the identifier space, which is why Round 1 and Round 2 both
+ * failed to construct an identifier-space attack.
+ */
+export function identifierFromNodeId(nodeId: string): string {
+  const safe = nodeId.replace(/[^0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  return `Node_${safe || '0'}`;
+}
+
+/**
+ * Escape a string for emission as a JSX **text child** inside a `{'…'}` string
+ * expression. Covers everything that could terminate the literal or the
+ * expression — including U+2028/U+2029, which terminate a JS string literal in
+ * some parsers and break tooling in others (Round 1 named both caveats; they are
+ * written into the rule here rather than left to the caller).
+ *
+ * Text is NEVER emitted as an attribute, never as markup, never through
+ * `dangerouslySetInnerHTML`.
+ */
+export function jsxStringLiteral(raw: string): string {
+  const body = raw
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    // Written as explicit escapes, never as literal characters in this source:
+    // a literal U+2028 here is invisible in every editor and one careless
+    // copy-paste away from silently vanishing from the rule.
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/\{/g, '\\u007b')
+    .replace(/\}/g, '\\u007d');
+  return `'${body}'`;
+}
+
+// ── D6b — visibility, by normalization ──────────────────────────────────────
+
+/** Below this a glyph is not readable at any sane zoom — clamp, don't drop. */
+export const MIN_FONT_SIZE = 8;
+/** WCAG-ish floor. Not an a11y claim — a "a human can see this exists" floor. */
+export const MIN_CONTRAST_RATIO = 2.5;
+
+function srgbChannel(c: number): number {
+  const v = c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  return v;
+}
+
+/** WCAG relative luminance from 0..1 linear sRGB components. */
+export function relativeLuminance(r: number, g: number, b: number): number {
+  return 0.2126 * srgbChannel(r) + 0.7152 * srgbChannel(g) + 0.0722 * srgbChannel(b);
+}
+
+export function contrastRatio(
+  fg: { r: number; g: number; b: number },
+  bg: { r: number; g: number; b: number }
+): number {
+  const l1 = relativeLuminance(fg.r, fg.g, fg.b);
+  const l2 = relativeLuminance(bg.r, bg.g, bg.b);
+  const [hi, lo] = l1 >= l2 ? [l1, l2] : [l2, l1];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+export function hexToRgb01(hex: string): { r: number; g: number; b: number } | null {
+  const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+  if (!m) return null;
+  const n = Number.parseInt(m[1], 16);
+  return { r: ((n >> 16) & 255) / 255, g: ((n >> 8) & 255) / 255, b: (n & 255) / 255 };
+}
+
+export function rgb01ToHex(c: { r: number; g: number; b: number }): string {
+  const to = (v: number) =>
+    Math.max(0, Math.min(255, Math.round(v * 255)))
+      .toString(16)
+      .padStart(2, '0');
+  return `#${to(c.r)}${to(c.g)}${to(c.b)}`;
+}
+
+/**
+ * D6b: force a foreground colour to be visible against its own resolved
+ * background. Returns the original when it already clears the floor, otherwise
+ * black or white — whichever wins — so white-on-white becomes black-on-white
+ * rather than being dropped.
+ */
+export function ensureContrast(fgHex: string, bgHex: string): { hex: string; changed: boolean } {
+  const fg = hexToRgb01(fgHex);
+  const bg = hexToRgb01(bgHex);
+  if (!fg || !bg) return { hex: fgHex, changed: false };
+  if (contrastRatio(fg, bg) >= MIN_CONTRAST_RATIO) return { hex: fgHex, changed: false };
+  const black = { r: 0, g: 0, b: 0 };
+  const white = { r: 1, g: 1, b: 1 };
+  const pick = contrastRatio(black, bg) >= contrastRatio(white, bg) ? black : white;
+  return { hex: rgb01ToHex(pick), changed: true };
+}
+
+/** D6b: a readable size, always. */
+export function ensureFontSize(size: number): { size: number; changed: boolean } {
+  if (!Number.isFinite(size) || size < MIN_FONT_SIZE) {
+    return { size: MIN_FONT_SIZE, changed: true };
+  }
+  return { size, changed: false };
+}
+
+/**
+ * D6b: clamp a node's world position into the board's occupied bounds (padded),
+ * so a stroke parked tens of thousands of units away — which on a real board
+ * (measured span x −3 244…+11 037) looks like ordinary geometry, not an
+ * anomaly — cannot hide off-screen.
+ */
+export interface Bounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+export function clampIntoBounds(
+  x: number,
+  y: number,
+  bounds: Bounds,
+  pad = 2000
+): { x: number; y: number; changed: boolean } {
+  const cx = Math.max(bounds.minX - pad, Math.min(bounds.maxX + pad, x));
+  const cy = Math.max(bounds.minY - pad, Math.min(bounds.maxY + pad, y));
+  return { x: cx, y: cy, changed: cx !== x || cy !== y };
+}