inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

package/scanner/block-cache-regression.ts

@@ -0,0 +1,195 @@
+import assert from 'node:assert/strict';
+import {
+  blockHashMatchesCurrent,
+  normalizeForPreflight,
+  parseStoredBlockHash,
+} from '../src/design-system/block-cache';
+import type { ComponentDef } from '../src/components';
+
+/**
+ * Regression: the block-cache helpers decide which component blocks survive
+ * across re-renders. They run on every preflight and every Generate. If the
+ * matching logic drifts, the plugin either rebuilds blocks unnecessarily
+ * (destroying user annotations) or keeps stale blocks the user expects to
+ * have been regenerated.
+ *
+ * Three pure-data helpers are covered here. `findComponentBlocksInPage` is
+ * Figma-API-bound (reads plugin data + walks the scene graph) and is exercised
+ * by the actual plugin under real Figma — not in this fixture.
+ *
+ * Extracted from `src/design-system/story-builder.ts` into
+ * `src/design-system/block-cache.ts`.
+ */
+
+// ---------------------------------------------------------------------------
+// parseStoredBlockHash — string parsing of `def:token` and `def:token:engine`
+// ---------------------------------------------------------------------------
+
+// Null / empty / non-string inputs return null (defensive: plugin data reads
+// can return null for absent keys).
+assert.equal(parseStoredBlockHash(null), null, 'null input must parse as null');
+assert.equal(parseStoredBlockHash(''), null, 'empty string must parse as null');
+assert.equal(
+  parseStoredBlockHash('only-one-part'),
+  null,
+  'single-segment string (no colon) must parse as null',
+);
+
+// Two-part legacy format (pre-engine-aware blocks).
+assert.deepEqual(
+  parseStoredBlockHash('abc:def'),
+  { defHash: 'abc', tokenHash: 'def', engineHash: null },
+  'two-part hash parses without engine — must support legacy blocks',
+);
+
+// Three-part current format.
+assert.deepEqual(
+  parseStoredBlockHash('abc:def:1.2.3'),
+  { defHash: 'abc', tokenHash: 'def', engineHash: '1.2.3' },
+  'three-part hash parses with engine segment',
+);
+
+// Four+ parts (engine segment carries colons) — anything after the second
+// colon joins back into engineHash so SemVer prereleases (1.0.0-rc.1) or
+// fingerprints with colons don't truncate.
+assert.deepEqual(
+  parseStoredBlockHash('a:b:c:d:e'),
+  { defHash: 'a', tokenHash: 'b', engineHash: 'c:d:e' },
+  'multi-colon engine segment must rejoin into engineHash, not truncate',
+);
+
+// ---------------------------------------------------------------------------
+// blockHashMatchesCurrent — exact-or-tolerant comparison
+// ---------------------------------------------------------------------------
+
+// No stored hash → never matches (treated as "this block was never tagged").
+assert.equal(
+  blockHashMatchesCurrent(null, 'def', 'tok', 'eng'),
+  false,
+  'null stored hash must not match — forces a rebuild for untagged blocks',
+);
+
+// Exact match of all three parts → true.
+assert.equal(
+  blockHashMatchesCurrent('def:tok:eng', 'def', 'tok', 'eng'),
+  true,
+  'exact 3-part match is the canonical hit',
+);
+
+// Backward compat: legacy 2-part hash with matching def+token → true (engine
+// is tolerated as a free variable so engine upgrades don't force rebuilds).
+assert.equal(
+  blockHashMatchesCurrent('def:tok', 'def', 'tok', 'eng'),
+  true,
+  'legacy 2-part stored hash matches when def+token equal — engine upgrade does not rebuild',
+);
+
+// Engine drift on a 3-part stored hash → still matches (def+token wins).
+assert.equal(
+  blockHashMatchesCurrent('def:tok:old-engine', 'def', 'tok', 'new-engine'),
+  true,
+  'def+token match with different engine segment must still match — supports render-engine version migration',
+);
+
+// Different defHash → must not match.
+assert.equal(
+  blockHashMatchesCurrent('OTHER:tok:eng', 'def', 'tok', 'eng'),
+  false,
+  'different defHash must force rebuild',
+);
+
+// Different tokenHash → must not match (token change is a real rebuild trigger).
+assert.equal(
+  blockHashMatchesCurrent('def:OTHER:eng', 'def', 'tok', 'eng'),
+  false,
+  'different tokenHash must force rebuild',
+);
+
+// Garbage stored hash → unparseable, no match.
+assert.equal(
+  blockHashMatchesCurrent('garbage', 'def', 'tok', 'eng'),
+  false,
+  'unparseable stored hash must not match',
+);
+
+// ---------------------------------------------------------------------------
+// normalizeForPreflight — hoist analysis fields onto top-level def shape
+// ---------------------------------------------------------------------------
+
+// def without analysis is returned as-is (defensive: not all defs come from
+// the scanner — some are constructed in tests / preflight only).
+{
+  const def = { name: 'X', stories: [] } as unknown as ComponentDef;
+  assert.equal(
+    normalizeForPreflight(def),
+    def,
+    'def without analysis must return identity (no normalization needed)',
+  );
+}
+
+// def with analysis: analysis fields hoist, top-level classification fields preserved.
+{
+  const raw = {
+    filePath: 'top-file',
+    stories: [{ name: 'TopStory' }],
+    kind: 'atom',
+    usesCount: 3,
+    usedByCount: 5,
+    isLeaf: false,
+    hasStory: true,
+    analysis: {
+      filePath: 'analysis-file',
+      stories: [{ name: 'AnalysisStory' }],
+      hasStory: true,
+      otherAnalysisField: 'kept',
+    },
+  } as unknown as ComponentDef;
+
+  const out = normalizeForPreflight(raw);
+  assert.equal(out.filePath, 'analysis-file', 'analysis.filePath wins when present');
+  assert.deepEqual(
+    out.stories,
+    [{ name: 'AnalysisStory' }],
+    'analysis.stories wins when present (array, not top-level)',
+  );
+  assert.equal(out.hasStory, true, 'analysis.hasStory wins when boolean');
+  assert.equal(out.kind, 'atom', 'top-level kind is preserved (classification stays on the raw def)');
+  assert.equal(out.usesCount, 3, 'top-level usesCount is preserved');
+  assert.equal(out.usedByCount, 5, 'top-level usedByCount is preserved');
+  assert.equal(out.isLeaf, false, 'top-level isLeaf is preserved');
+  assert.equal((out as { otherAnalysisField?: string }).otherAnalysisField, 'kept', 'unknown analysis fields are kept');
+}
+
+// Fallback: analysis lacks fields → top-level values fill in.
+{
+  const raw = {
+    filePath: 'top-file',
+    stories: [{ name: 'TopStory' }],
+    hasStory: true,
+    analysis: {
+      // No filePath, no stories, no hasStory — exercise every fallback path.
+      otherField: 'x',
+    },
+  } as unknown as ComponentDef;
+
+  const out = normalizeForPreflight(raw);
+  assert.equal(out.filePath, 'top-file', 'top-level filePath fills in when analysis.filePath absent');
+  assert.deepEqual(
+    out.stories,
+    [{ name: 'TopStory' }],
+    'top-level stories fill in when analysis.stories absent',
+  );
+  assert.equal(out.hasStory, true, 'top-level hasStory fills in when analysis.hasStory missing');
+}
+
+// hasStory falsy-coercion: analysis without boolean hasStory + falsy raw.hasStory → false.
+{
+  const raw = {
+    stories: [],
+    analysis: {},
+  } as unknown as ComponentDef;
+  const out = normalizeForPreflight(raw);
+  assert.equal(out.hasStory, false, 'falsy fallbacks coerce to false (not undefined)');
+}
+
+console.log('block-cache-regression: PASS');

package/scanner/bundle-size-regression.ts

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Regression: lock in the minified `code.js` bundle size so accidental
+ * imports (a heavy third-party lib, an unintentional non-tree-shakable
+ * re-export, dropping `minify: true` from build.mjs) don't silently
+ * double the plugin payload.
+ *
+ * Threshold has ~10% headroom over the current minified size. Bump it
+ * deliberately if real new functionality justifies the growth — the
+ * commit message should explain why.
+ *
+ * Must run AFTER `pnpm build` (the verify chain does that). If
+ * `code.js` is missing or stale, the assertion fails informatively.
+ */
+
+const CODE_JS_PATH = path.resolve(process.cwd(), 'tools/figma-plugin/code.js');
+const MAX_BYTES = 360 * 1024; // 360 KB ceiling (current ~325 KB)
+
+if (!fs.existsSync(CODE_JS_PATH)) {
+  console.error('bundle-size-regression: FAIL — code.js missing at ' + CODE_JS_PATH);
+  console.error('  Run `pnpm build` first.');
+  process.exit(1);
+}
+
+const stat = fs.statSync(CODE_JS_PATH);
+const sizeKB = (stat.size / 1024).toFixed(1);
+
+assert.ok(
+  stat.size <= MAX_BYTES,
+  `code.js is ${sizeKB} KB, exceeds ceiling of ${(MAX_BYTES / 1024).toFixed(0)} KB.\n` +
+    `If the growth is intentional (real new functionality, not accidental bloat),\n` +
+    `bump MAX_BYTES in scanner/bundle-size-regression.ts and explain in the commit.`
+);
+
+// Also sanity-check that minification actually ran — minified IIFE
+// should be on a single long line, not many short lines. If somebody
+// drops `minify: !isWatch` from build.mjs, this catches it before the
+// raw size assertion would.
+const content = fs.readFileSync(CODE_JS_PATH, 'utf8');
+const linesOverThreshold = content.split('\n').filter(l => l.length > 1000).length;
+assert.ok(
+  linesOverThreshold > 0,
+  'code.js does not appear to be minified — no lines over 1000 characters found.\n' +
+    'Check that build.mjs still has `minify: !isWatch`.'
+);
+
+console.log(`bundle-size-regression: PASS (code.js = ${sizeKB} KB, ceiling ${(MAX_BYTES / 1024).toFixed(0)} KB)`);

package/scanner/child-sizing-matrix-regression.ts

@@ -0,0 +1,303 @@
+import assert from 'node:assert/strict';
+
+(globalThis as unknown as { figma: unknown }).figma = {
+  notify: () => undefined,
+  showUI: () => undefined,
+  createFrame: () => makeStubFrame(),
+};
+
+import {
+  LayoutParser,
+  setFrameCrossAlign,
+  setFrameFromBlockFlow,
+  setFrameInlineAlign,
+} from '../src/layout/layout-parser';
+
+// MATRIX REGRESSION — child sizing under varying parent context.
+//
+// The recurring "context-dependent sizing" class of bug:
+//   The per-class parser correctly records a child's sizing intent (HUG /
+//   inline-display / w-full / etc.), then a LATER pass overrides it based on
+//   parent-side state alone, never reading the child's recorded intent.
+//
+// Historical fix sites in this class (see troubleshooting.md):
+//   1. `inline-flex` pill in BLOCK-FLOW VERTICAL parent → re-stretched.
+//      Fix-site recurred 3× across refactors (tailwind.ts, layout-parser
+//      implicit-stretch pass, ui-builder.ts text-resize branch).
+//   2. `inline-flex` button in REAL FLEX-col STRETCH parent → did NOT
+//      stretch after over-broad inline-display exclusion. Dialog footer
+//      base-breakpoint regression.
+//   3. `text-center` on a block-flow parent → inline children not centered.
+//   4. `w-full` block child → correct STRETCH in vertical parent, `grow=1`
+//      in horizontal parent. Easy to break when refactoring either branch.
+//
+// This fixture asserts the truth table — every cell is one (child intent,
+// parent context) cross product. A future refactor that drifts ANY cell
+// triggers here, regardless of which pass introduced the drift.
+//
+// Cells overlap with `inline-flex-regression.ts` by design — that file
+// documents the incident narrative; this file is the systematic net.
+
+type StubFrame = {
+  type: 'FRAME';
+  layoutMode: 'NONE' | 'HORIZONTAL' | 'VERTICAL';
+  primaryAxisSizingMode: 'AUTO' | 'FIXED';
+  counterAxisSizingMode: 'AUTO' | 'FIXED';
+  primaryAxisAlignItems: string;
+  counterAxisAlignItems: string;
+  layoutAlign: string;
+  layoutGrow: number;
+  layoutSizingHorizontal: 'HUG' | 'FIXED' | 'FILL';
+  layoutSizingVertical: 'HUG' | 'FIXED' | 'FILL';
+  counterAxisAlignSelf: string;
+  width: number;
+  height: number;
+  paddingLeft: number;
+  paddingRight: number;
+  paddingTop: number;
+  paddingBottom: number;
+  fills: unknown[];
+  strokes: unknown[];
+  effects: unknown[];
+  children: never[];
+  appendChild(): void;
+  resize(w: number, h: number): void;
+};
+
+function makeStubFrame(): StubFrame {
+  return {
+    type: 'FRAME',
+    layoutMode: 'NONE',
+    primaryAxisSizingMode: 'AUTO',
+    counterAxisSizingMode: 'AUTO',
+    primaryAxisAlignItems: 'MIN',
+    counterAxisAlignItems: 'MIN',
+    layoutAlign: 'INHERIT',
+    layoutGrow: 0,
+    layoutSizingHorizontal: 'HUG',
+    layoutSizingVertical: 'HUG',
+    counterAxisAlignSelf: 'AUTO',
+    width: 0,
+    height: 0,
+    paddingLeft: 0,
+    paddingRight: 0,
+    paddingTop: 0,
+    paddingBottom: 0,
+    fills: [],
+    strokes: [],
+    effects: [],
+    children: [],
+    appendChild() { /* no-op */ },
+    resize(w, h) { this.width = w; this.height = h; },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Parent + child factories
+//
+// Each factory mimics the state the per-class parser would have already
+// written to the frame BEFORE `applyChildProperties` runs. Keeping these
+// here (rather than running tailwind.ts in-process) means the matrix tests
+// the implicit-stretch / w-full / text-align passes in isolation, which is
+// where the historical recurrences happened.
+// ---------------------------------------------------------------------------
+
+type ParentKind =
+  | 'flex-col-stretch'         // real flex container, CSS items-stretch default
+  | 'block-flow'                // <div> promoted to VERTICAL but inline-flow
+  | 'block-flow-text-center'    // block-flow with text-align: center
+  | 'horizontal-row';           // <div class="flex flex-row">
+
+function makeParent(kind: ParentKind): FrameNode {
+  const parent = makeStubFrame();
+  if (kind === 'horizontal-row') {
+    parent.layoutMode = 'HORIZONTAL';
+    parent.width = 600;
+    parent.primaryAxisSizingMode = 'FIXED';
+    setFrameCrossAlign(parent as unknown as FrameNode, 'MIN');
+    setFrameFromBlockFlow(parent as unknown as FrameNode, false);
+  } else {
+    parent.layoutMode = 'VERTICAL';
+    parent.width = 600;
+    parent.primaryAxisSizingMode = 'FIXED';
+    if (kind === 'flex-col-stretch') {
+      setFrameCrossAlign(parent as unknown as FrameNode, 'STRETCH');
+      setFrameFromBlockFlow(parent as unknown as FrameNode, false);
+    } else {
+      setFrameCrossAlign(parent as unknown as FrameNode, 'MIN');
+      setFrameFromBlockFlow(parent as unknown as FrameNode, true);
+      if (kind === 'block-flow-text-center') {
+        setFrameInlineAlign(parent as unknown as FrameNode, 'CENTER');
+      }
+    }
+  }
+  return parent as unknown as FrameNode;
+}
+
+type ChildKind =
+  | 'inline-flex-pill'   // <span class="inline-flex items-center rounded-full px-3 py-1">
+  | 'block-w-full'       // <div class="w-full p-4">
+  | 'block-plain'        // <div class="p-4">
+  | 'absolute-overlay';  // <div class="absolute inset-0">
+
+// NOTE on `absolute-overlay`: classes deliberately omit `w-full` / `h-full`.
+// The implicit-stretch exclusion for out-of-flow children is what this matrix
+// tests. The `w-full` handler in applyChildProperties writes `STRETCH` even
+// for absolute children (dead — Figma ignores layoutAlign on absolutely-
+// positioned children); the actual full-resize happens downstream in
+// `applyFullWidthIfPossible` (commit d817a58). That sizing surface has its
+// own regression in `aspect-percent-position-regression.ts`.
+
+function makeChild(kind: ChildKind): { child: FrameNode; classes: string[] } {
+  const child = makeStubFrame();
+  if (kind === 'inline-flex-pill') {
+    // Per-class parser already wrote HORIZONTAL + HUG-mode for inline-flex.
+    child.layoutMode = 'HORIZONTAL';
+    return {
+      child: child as unknown as FrameNode,
+      classes: 'inline-flex items-center rounded-full px-3 py-1 text-sm font-medium'.split(' '),
+    };
+  }
+  if (kind === 'block-w-full') {
+    return {
+      child: child as unknown as FrameNode,
+      classes: 'w-full p-4'.split(' '),
+    };
+  }
+  if (kind === 'block-plain') {
+    return {
+      child: child as unknown as FrameNode,
+      classes: 'p-4'.split(' '),
+    };
+  }
+  // absolute-overlay (deliberately NO w-full / h-full — see note above)
+  return {
+    child: child as unknown as FrameNode,
+    classes: 'absolute inset-0'.split(' '),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Truth table — every cell catches a class of historical drift.
+// `note` documents which incident the row guards against.
+// ---------------------------------------------------------------------------
+
+interface Cell {
+  child: ChildKind;
+  parent: ParentKind;
+  expect: {
+    layoutAlign?: 'INHERIT' | 'STRETCH';
+    layoutGrow?: number;
+    counterAxisAlignSelf?: 'AUTO' | 'CENTER' | 'MIN' | 'MAX';
+  };
+  note: string;
+}
+
+const CELLS: Cell[] = [
+  // ---- inline-flex pill ---------------------------------------------------
+  { child: 'inline-flex-pill', parent: 'flex-col-stretch',
+    expect: { layoutAlign: 'STRETCH' },
+    note: 'dialog footer base-bp: inline-flex button SHOULD stretch in real flex parent' },
+  { child: 'inline-flex-pill', parent: 'block-flow',
+    expect: { layoutAlign: 'INHERIT' },
+    note: 'recurring 3-site pill bug: must NOT stretch in block-flow vertical card' },
+  { child: 'inline-flex-pill', parent: 'block-flow-text-center',
+    expect: { layoutAlign: 'INHERIT', counterAxisAlignSelf: 'CENTER' },
+    note: 'round-trip "in motion" pill: NOT stretched, BUT centered via text-align inheritance' },
+  { child: 'inline-flex-pill', parent: 'horizontal-row',
+    expect: { layoutAlign: 'INHERIT' },
+    note: 'horizontal parent has no implicit-stretch pass; inline-flex passes through' },
+
+  // ---- block w-full -------------------------------------------------------
+  { child: 'block-w-full', parent: 'flex-col-stretch',
+    expect: { layoutAlign: 'STRETCH' },
+    note: 'w-full in vertical flex parent → STRETCH cross-axis' },
+  { child: 'block-w-full', parent: 'block-flow',
+    expect: { layoutAlign: 'STRETCH' },
+    note: 'w-full in block-flow parent → STRETCH (CSS items-stretch emulation)' },
+  { child: 'block-w-full', parent: 'block-flow-text-center',
+    expect: { layoutAlign: 'STRETCH' },
+    note: 'block child not affected by text-align — full-width regardless' },
+  { child: 'block-w-full', parent: 'horizontal-row',
+    expect: { layoutGrow: 1 },
+    note: 'w-full in horizontal parent → grow primary axis (NOT layoutAlign)' },
+
+  // ---- plain block (no width directive) -----------------------------------
+  { child: 'block-plain', parent: 'flex-col-stretch',
+    expect: { layoutAlign: 'STRETCH' },
+    note: 'CSS items-stretch default applies to block child' },
+  { child: 'block-plain', parent: 'block-flow',
+    expect: { layoutAlign: 'STRETCH' },
+    note: 'plugin emulates items-stretch for block children in block-flow' },
+  { child: 'block-plain', parent: 'block-flow-text-center',
+    expect: { layoutAlign: 'STRETCH' },
+    note: 'text-center is for inline children only; block child still stretches' },
+  { child: 'block-plain', parent: 'horizontal-row',
+    expect: { layoutAlign: 'INHERIT', layoutGrow: 0 },
+    note: 'no width directive in horizontal parent: neither grow nor stretch' },
+
+  // ---- absolute overlay (out-of-flow) -------------------------------------
+  { child: 'absolute-overlay', parent: 'flex-col-stretch',
+    expect: { layoutAlign: 'INHERIT' },
+    note: 'out-of-flow children opt out of implicit-stretch regardless of parent' },
+  { child: 'absolute-overlay', parent: 'block-flow',
+    expect: { layoutAlign: 'INHERIT' },
+    note: 'absolute child in block-flow: position handled by deferred-layout, not stretch' },
+  { child: 'absolute-overlay', parent: 'block-flow-text-center',
+    expect: { layoutAlign: 'INHERIT' },
+    note: 'absolute child not affected by text-center' },
+  { child: 'absolute-overlay', parent: 'horizontal-row',
+    expect: { layoutAlign: 'INHERIT' },
+    note: 'absolute child in horizontal parent: position handled separately' },
+];
+
+function runRegression(): void {
+  const failures: string[] = [];
+
+  for (const cell of CELLS) {
+    const parent = makeParent(cell.parent);
+    const { child, classes } = makeChild(cell.child);
+
+    LayoutParser.applyChildProperties(child, classes, parent);
+
+    const cellId = `${cell.child} × ${cell.parent}`;
+    const stub = child as unknown as StubFrame;
+
+    if (cell.expect.layoutAlign !== undefined) {
+      if (stub.layoutAlign !== cell.expect.layoutAlign) {
+        failures.push(
+          `${cellId}: expected layoutAlign=${cell.expect.layoutAlign}, got ${stub.layoutAlign}\n  → ${cell.note}`,
+        );
+      }
+    }
+    if (cell.expect.layoutGrow !== undefined) {
+      if (stub.layoutGrow !== cell.expect.layoutGrow) {
+        failures.push(
+          `${cellId}: expected layoutGrow=${cell.expect.layoutGrow}, got ${stub.layoutGrow}\n  → ${cell.note}`,
+        );
+      }
+    }
+    if (cell.expect.counterAxisAlignSelf !== undefined) {
+      if (stub.counterAxisAlignSelf !== cell.expect.counterAxisAlignSelf) {
+        failures.push(
+          `${cellId}: expected counterAxisAlignSelf=${cell.expect.counterAxisAlignSelf}, got ${stub.counterAxisAlignSelf}\n  → ${cell.note}`,
+        );
+      }
+    }
+  }
+
+  if (failures.length > 0) {
+    for (const msg of failures) console.error('  ✗ ' + msg);
+    assert.fail(`${failures.length}/${CELLS.length} matrix cells failed`);
+  }
+
+  console.log(`child-sizing-matrix-regression: PASS (${CELLS.length} cells)`);
+}
+
+try {
+  runRegression();
+} catch (err) {
+  console.error('child-sizing-matrix-regression: FAIL');
+  console.error(err);
+  process.exit(1);
+}