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

package/scanner/size-full-normalization-regression.ts

@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict';
+
+import { splitClassName } from '../src/tailwind';
+import { LayoutParser } from '../src/layout/layout-parser';
+
+/**
+ * Regression: `size-full` is Tailwind shorthand for `w-full h-full`. The
+ * plugin had separate code paths for `w-full` and `h-full` (each correctly
+ * marks the node for the deferred-layout stretch pipeline), but `size-full`
+ * was silently dropped — no sizing parser, no full-width/height mark, no
+ * STRETCH alignment.
+ *
+ * Symptom: `<AvatarFallback className="flex size-full ...">` rendered at
+ * its text-content size (24×19 — just "CN") instead of filling its
+ * 40×40 Avatar.Root parent. `<AvatarImage className="size-full">` rendered
+ * as a 200×150 placeholder. Both look broken next to a Storybook that
+ * happily rendered the same primitives correctly.
+ *
+ * Architectural fix: normalize `size-full` into `w-full h-full` at the
+ * `splitClassName` boundary — the single bottleneck every downstream
+ * parser passes through. Every existing w-full / h-full handler now
+ * applies to size-full automatically with zero parallel code paths. The
+ * numeric `size-N` form has its own dedicated handler in sizing.ts and is
+ * intentionally left as-is (it sets `widthMode`/`heightMode` to FIXED in
+ * one go, not via the FILL cascade).
+ *
+ * This file locks the boundary so a refactor of splitClassName can't
+ * regress this without breaking the test.
+ */
+
+// ---------------------------------------------------------------------------
+// splitClassName — size-full expands to w-full + h-full
+// ---------------------------------------------------------------------------
+
+{
+  assert.deepEqual(
+    splitClassName('size-full'),
+    ['w-full', 'h-full'],
+    'bare size-full expands into [w-full, h-full]',
+  );
+}
+
+{
+  // In context with siblings — order preserved, expansion happens in-place.
+  assert.deepEqual(
+    splitClassName('flex size-full items-center'),
+    ['flex', 'w-full', 'h-full', 'items-center'],
+    'size-full expanded in-place; siblings keep order',
+  );
+}
+
+{
+  // size-N (numeric) — NOT expanded. The numeric handler in sizing.ts
+  // sets both modes FIXED in one go; turning it into `w-N h-N` would
+  // route through a different (and slower) code path.
+  assert.deepEqual(
+    splitClassName('size-10'),
+    ['size-10'],
+    'numeric size-N is NOT expanded — its FIXED handler stays the source of truth',
+  );
+  assert.deepEqual(
+    splitClassName('size-4 size-8 size-[40px]'),
+    ['size-4', 'size-8', 'size-[40px]'],
+    'numeric / arbitrary size-* forms are left intact',
+  );
+}
+
+{
+  // Important-modifier handling still strips ! around the token.
+  assert.deepEqual(
+    splitClassName('!size-full'),
+    ['w-full', 'h-full'],
+    'leading-! is stripped before expansion (so !size-full still expands)',
+  );
+  assert.deepEqual(
+    splitClassName('size-full!'),
+    ['w-full', 'h-full'],
+    'trailing-! is stripped before expansion',
+  );
+}
+
+{
+  // Empty / whitespace inputs are no-ops.
+  assert.deepEqual(splitClassName(''), [], 'empty string → []');
+  assert.deepEqual(splitClassName('   '), [], 'whitespace-only → []');
+  assert.deepEqual(splitClassName(undefined), [], 'undefined → []');
+}
+
+// ---------------------------------------------------------------------------
+// LayoutParser — size-full now drives FILL on both axes
+// ---------------------------------------------------------------------------
+
+{
+  // After splitClassName expansion, the parser sees w-full h-full and sets
+  // both axes to FILL. This is what makes AvatarFallback fill its parent
+  // rather than hug its text content.
+  const ir = LayoutParser.parseToIR(splitClassName('flex size-full'));
+  assert.equal(
+    ir.widthMode,
+    'FILL',
+    'size-full sets widthMode=FILL via expansion → w-full handler',
+  );
+  assert.equal(
+    ir.heightMode,
+    'FILL',
+    'size-full sets heightMode=FILL via expansion → h-full handler',
+  );
+}
+
+{
+  // Sanity: plain w-full alone only fills the width axis.
+  const ir = LayoutParser.parseToIR(splitClassName('w-full'));
+  assert.equal(ir.widthMode, 'FILL', 'w-full alone fills width only');
+  assert.notEqual(ir.heightMode, 'FILL', 'w-full alone does NOT fill height');
+}
+
+{
+  // And numeric size still produces FIXED on both axes — the parser-level
+  // contract we don't want to drift.
+  const ir = LayoutParser.parseToIR(splitClassName('size-10'));
+  assert.equal(ir.widthMode, 'FIXED', 'size-10 → widthMode=FIXED');
+  assert.equal(ir.heightMode, 'FIXED', 'size-10 → heightMode=FIXED');
+  assert.equal(ir.fixedWidth, 40, 'size-10 → fixedWidth=40px');
+  assert.equal(ir.fixedHeight, 40, 'size-10 → fixedHeight=40px');
+}
+
+console.log('size-full-normalization-regression: PASS (7 split cases + 3 IR cases)');

package/scanner/state-classification-regression.ts

@@ -0,0 +1,175 @@
+import assert from 'node:assert/strict';
+import * as path from 'node:path';
+import { ComponentScanner } from './component-scanner';
+
+/**
+ * Regression: marketing molecules whose JSX root is a wrapper component
+ * (e.g. `<Hero>...</Hero>`) — including ones that expand into a fragment
+ * `<>...</>` — must not be classified as `state` components even if a
+ * deeply-nested element carries hover/focus classes (typical in chips,
+ * links, or buttons inside the molecule).
+ *
+ * History: this same logical hole has caused HeroSection to be wrongly
+ * rendered as a State Matrix + symbol multiple times. Each time a fix
+ * landed in `hasRootStateModifier` it covered the case the regression
+ * was reported with, but missed the next variant — fragment-rooted
+ * expansion was the most recent miss. Lock it in.
+ */
+
+// Test-only view of ComponentScanner that surfaces the otherwise-private
+// `project` field and `analyzeState` method. The runtime members exist;
+// TS hides them. Cast through `unknown` to avoid `any`.
+type ComponentAnalysisLike = unknown;
+interface TestScannerView {
+  project: import('ts-morph').Project;
+  analyzeState: (sourceFile: import('ts-morph').SourceFile, filePath: string) => ComponentAnalysisLike;
+}
+
+function makeScanner(): TestScannerView {
+  // ScannerConfig requires componentPaths/filePattern/exclude. Pass empty values
+  // — the regression tests stuff source files into `project` directly via
+  // createSourceFile, so the scanner never reads the filesystem.
+  const scanner = new ComponentScanner({
+    componentPaths: [],
+    filePattern: '*.tsx',
+    exclude: [],
+  });
+  return scanner as unknown as TestScannerView;
+}
+
+function fixturePath(relative: string): string {
+  return path.resolve(process.cwd(), 'tools/figma-plugin/scanner/__fixtures__', relative);
+}
+
+const scanner = makeScanner();
+
+// ---------------------------------------------------------------------------
+// Case 1: <Hero> wrapper component as root — direct uppercase wrapper.
+// Was already covered by the original heuristic; included so a future
+// "simplification" doesn't regress this.
+// ---------------------------------------------------------------------------
+{
+  // File basename must match the exported function name — the scanner
+  // uses the basename to find the component definition.
+  const file = scanner.project.createSourceFile(
+    fixturePath('hero-section.tsx'),
+    `
+      import { Hero } from '@/components/hero';
+
+      export function HeroSection() {
+        return (
+          <Hero>
+            <a className="hover:ring-gray-900/20 ring-1">Get started</a>
+          </Hero>
+        );
+      }
+    `,
+    { overwrite: true }
+  );
+  const result = scanner.analyzeState(file, file.getFilePath());
+  assert.equal(
+    result,
+    null,
+    'A component whose root JSX is an uppercase wrapper (<Hero>) must NOT be classified as `state` even when a nested element has hover classes.'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Case 2: fragment-rooted component — the actual recurring break.
+// HeroSection's root expands to `<><div className="relative isolate">...
+// </div></>` once Hero is inlined. Pre-fix, the empty-tagName fragment
+// failed the uppercase wrapper check and got treated as a state primitive.
+// ---------------------------------------------------------------------------
+{
+  // Filename matches function name so the scanner can resolve the JSX tree.
+  const file = scanner.project.createSourceFile(
+    fixturePath('fragment-rooted-section.tsx'),
+    `
+      export function FragmentRootedSection() {
+        return (
+          <>
+            <div className="relative isolate">
+              <a className="hover:ring-gray-900/20 ring-1">Get started</a>
+            </div>
+          </>
+        );
+      }
+    `,
+    { overwrite: true }
+  );
+  const result = scanner.analyzeState(file, file.getFilePath());
+  assert.equal(
+    result,
+    null,
+    'A component whose root JSX is a fragment (<>...</>) must NOT be classified as `state` — only deeply nested elements carry the hover/focus classes.'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Case 3: the positive control. A real state primitive — root is a plain
+// HTML element with hover/focus classes directly on it. Must STILL be
+// classified as state. Ensures we haven't accidentally killed the feature.
+// ---------------------------------------------------------------------------
+{
+  // Filename matches function name so the scanner resolves the JSX tree.
+  const file = scanner.project.createSourceFile(
+    fixturePath('styled-input.tsx'),
+    `
+      export function StyledInput(props: any) {
+        return (
+          <input
+            {...props}
+            className="border h-9 px-3 hover:border-primary focus-visible:ring-2 disabled:opacity-50"
+          />
+        );
+      }
+    `,
+    { overwrite: true }
+  );
+  const result = scanner.analyzeState(file, file.getFilePath());
+  assert.notEqual(
+    result,
+    null,
+    'A genuine state primitive (root <input> with hover/focus/disabled classes directly on it) must STILL be classified as `state`.'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Case 4: shadcn-style Label — only carries `peer-disabled:` and
+// `group-data-[disabled=true]:` modifiers (passive reactions to a
+// parent's state, NOT its own state axis). Must NOT be classified as
+// `state` — otherwise the runtime renders it via the state-master
+// path, which has no slot for the label's text children, and a story
+// like `<Dialog>... <Label>Name</Label> <Input/> ...</Dialog>` ends up
+// with the labels invisible. Lock this in so a future widening of the
+// state-modifier list doesn't silently re-break it.
+// ---------------------------------------------------------------------------
+{
+  const file = scanner.project.createSourceFile(
+    fixturePath('passive-label.tsx'),
+    `
+      export function Label({ className, ...props }: any) {
+        return (
+          <label
+            className={
+              "flex items-center gap-2 text-sm leading-none font-medium select-none " +
+              "group-data-[disabled=true]:pointer-events-none " +
+              "group-data-[disabled=true]:opacity-50 " +
+              "peer-disabled:cursor-not-allowed peer-disabled:opacity-50"
+            }
+            {...props}
+          />
+        );
+      }
+    `,
+    { overwrite: true }
+  );
+  const result = scanner.analyzeState(file, file.getFilePath());
+  assert.equal(
+    result,
+    null,
+    'A component whose only "state" modifiers are passive `group-*:` / `peer-*:` reactions must NOT be classified as `state` — it has no own-element state axis, and the runtime would lose its text children when rendering via the state-master path.',
+  );
+}
+
+console.log('state-classification-regression: ok');

package/scanner/story-diagnostics-regression.ts

@@ -0,0 +1,216 @@
+import assert from 'node:assert/strict';
+import { _internal, setStoryRenderDiagnostics } from '../src/design-system/story-diagnostics';
+import type { ComponentDef, ComponentStory, LayoutInfo } from '../src/components';
+import type { JsxNode } from '../src/tailwind';
+
+/**
+ * Regression: story-diagnostics writes the `inkbridge:story-scan` and
+ * `inkbridge:story-render` plugin-data values that the `Debug Selection`
+ * plugin command reads. The string format is contract — anyone reading the
+ * pluginData (the dev console output, future tooling) parses by the
+ * `key=value;key=value` shape. Lock the shape and the per-helper inputs.
+ *
+ * Extracted from `src/design-system/story-builder.ts` into
+ * `src/design-system/story-diagnostics.ts`. setStoryRenderDiagnostics is a
+ * side-effect on a LayoutInfo (Figma node); the regression uses a stub that
+ * captures setPluginData calls so the format can be asserted in Node.
+ */
+
+const { getStoryTreeRootTag, getStoryTreeRootChildCount, summarizeLayoutClasses } = _internal;
+
+function el(tag: string, children: JsxNode[] = []): JsxNode {
+  return { type: 'element', tagName: tag, props: {}, children } as unknown as JsxNode;
+}
+
+function story(overrides: Partial<ComponentStory> = {}): ComponentStory {
+  return { name: 'TestStory', jsxTree: null, instances: [], layoutClasses: [], ...overrides } as ComponentStory;
+}
+
+// ---------------------------------------------------------------------------
+// getStoryTreeRootTag — null/non-element/missing tag tolerances
+// ---------------------------------------------------------------------------
+
+assert.equal(getStoryTreeRootTag(story({ jsxTree: null })), '', 'null jsxTree → empty string');
+assert.equal(getStoryTreeRootTag(story({ jsxTree: el('div') })), 'div', 'div root → "div"');
+assert.equal(
+  getStoryTreeRootTag(story({ jsxTree: el('Header') })),
+  'Header',
+  'component-cased tag preserved',
+);
+
+// Non-element root (text-only).
+{
+  const tree = { type: 'text', value: 'hello' } as unknown as JsxNode;
+  assert.equal(
+    getStoryTreeRootTag(story({ jsxTree: tree })),
+    '',
+    'text-root story has no tag — return empty string',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// getStoryTreeRootChildCount — null / array / non-array tolerances
+// ---------------------------------------------------------------------------
+
+assert.equal(getStoryTreeRootChildCount(story({ jsxTree: null })), 0, 'null tree → 0');
+assert.equal(getStoryTreeRootChildCount(story({ jsxTree: el('div') })), 0, 'empty children → 0');
+assert.equal(
+  getStoryTreeRootChildCount(story({ jsxTree: el('div', [el('span'), el('span'), el('span')]) })),
+  3,
+  'three children → 3',
+);
+
+// Non-array children defensive: when jsxTree has children: undefined or null.
+{
+  const tree = { type: 'element', tagName: 'div', props: {}, children: null } as unknown as JsxNode;
+  assert.equal(
+    getStoryTreeRootChildCount(story({ jsxTree: tree })),
+    0,
+    'non-array children → 0 (not NaN, not throw)',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// summarizeLayoutClasses — join + truncation
+// ---------------------------------------------------------------------------
+
+assert.equal(summarizeLayoutClasses(undefined, 50), '', 'undefined input → empty string');
+assert.equal(summarizeLayoutClasses(['flex', 'p-4'], 50), 'flex p-4', 'array joins by space');
+assert.equal(
+  summarizeLayoutClasses(['a', 'b', 'c'], 3),
+  'a b',
+  'truncates when joined length > maxLength',
+);
+assert.equal(
+  summarizeLayoutClasses(['short'], 10),
+  'short',
+  'no truncation when joined length <= maxLength',
+);
+
+// Edge: empty array → empty string.
+assert.equal(summarizeLayoutClasses([], 50), '', 'empty array → empty string');
+
+// ---------------------------------------------------------------------------
+// setStoryRenderDiagnostics — full integration: format + plugin-data writes
+// ---------------------------------------------------------------------------
+
+// Stub LayoutInfo that captures setPluginData calls.
+function makeLayoutStub(): { layout: LayoutInfo; writes: Record<string, string> } {
+  const writes: Record<string, string> = {};
+  const layout = {
+    children: [],
+    setPluginData: (key: string, value: string) => {
+      writes[key] = value;
+    },
+  } as unknown as LayoutInfo;
+  return { layout, writes };
+}
+
+// Happy path: writes all four plugin-data keys with the documented format.
+{
+  const { layout, writes } = makeLayoutStub();
+  const def = { name: 'Button' } as ComponentDef;
+  const tree = el('div', [el('span'), el('p')]);
+  const s = story({
+    name: 'Default',
+    jsxTree: tree,
+    instances: [{ componentName: 'Button' } as unknown],
+    layoutClasses: ['flex', 'p-4'],
+  });
+
+  setStoryRenderDiagnostics(layout, def, s, 'tree', 5, true);
+
+  assert.equal(writes['inkbridge:story-name'], 'Default', 'story name written');
+  assert.equal(writes['inkbridge:story-def'], 'Button', 'def name written');
+
+  // scanSummary format: jsx=...;root=...;rootChildren=...;instances=...;layout=...
+  assert.equal(
+    writes['inkbridge:story-scan'],
+    'jsx=1;root=div;rootChildren=2;instances=1;layout=flex p-4',
+    'scan summary uses canonical key=value;... format',
+  );
+
+  // renderSummary format: mode=...;added=...;treeSelected=...;children=...;engine=...
+  assert.match(
+    writes['inkbridge:story-render'],
+    /^mode=tree;added=5;treeSelected=1;children=0;engine=.+$/,
+    'render summary uses canonical key=value;... format, engine version present',
+  );
+}
+
+// jsx=0 path when no jsxTree
+{
+  const { layout, writes } = makeLayoutStub();
+  setStoryRenderDiagnostics(
+    layout,
+    { name: 'Button' } as ComponentDef,
+    story({ jsxTree: null }),
+    'instance',
+    1,
+    false,
+  );
+  assert.match(writes['inkbridge:story-scan'], /^jsx=0;root=;rootChildren=0;/, 'no tree → jsx=0;root=');
+  assert.match(writes['inkbridge:story-render'], /treeSelected=0/, 'treeSelected reflects useStoryTree=false');
+}
+
+// Defensive: missing setPluginData → no throw
+{
+  const layoutWithoutSetPluginData = { children: [] } as unknown as LayoutInfo;
+  // Should silently do nothing rather than throw.
+  setStoryRenderDiagnostics(
+    layoutWithoutSetPluginData,
+    { name: 'X' } as ComponentDef,
+    story(),
+    'mode',
+    0,
+    false,
+  );
+  // (no assertion needed — getting here means no throw)
+}
+
+// Defensive: setPluginData throws → caught silently
+{
+  const writes: Record<string, string> = {};
+  let throwCount = 0;
+  const layout = {
+    children: [],
+    setPluginData: (key: string, value: string) => {
+      if (key === 'inkbridge:story-scan') {
+        throwCount++;
+        throw new Error('simulated figma failure');
+      }
+      writes[key] = value;
+    },
+  } as unknown as LayoutInfo;
+
+  setStoryRenderDiagnostics(
+    layout,
+    { name: 'X' } as ComponentDef,
+    story(),
+    'mode',
+    0,
+    false,
+  );
+  // We don't care which writes succeeded — only that the throw didn't escape.
+  assert.equal(throwCount, 1, 'inner throw was reached');
+  // (no further assertion needed — getting here means the outer catch swallowed the error)
+}
+
+// Layout-class truncation: very long class list is capped at 120 chars in
+// the scan summary.
+{
+  const { layout, writes } = makeLayoutStub();
+  const longClasses = Array.from({ length: 50 }, (_, i) => `cls-${i}`); // ~6*50 = 300+ chars joined
+  setStoryRenderDiagnostics(
+    layout,
+    { name: 'X' } as ComponentDef,
+    story({ layoutClasses: longClasses }),
+    'mode',
+    0,
+    false,
+  );
+  const layoutSegment = writes['inkbridge:story-scan'].split('layout=')[1] || '';
+  assert.ok(layoutSegment.length <= 120, `layout summary capped at 120 chars (got ${layoutSegment.length})`);
+}
+
+console.log('story-diagnostics-regression: PASS');