@discourser/design-system 0.15.1 → 0.18.0

package/src/figma-codex/__tests__/writer.test.ts

@@ -0,0 +1,111 @@
+// @vitest-environment node
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { writeManifest } from '../writer';
+import type { ComponentEntry } from '../schema';
+
+const sampleEntry: ComponentEntry = {
+  name: 'Button',
+  type: 'simple',
+  figma: {
+    fileKey: 'ABC123',
+    nodeId: '1:2',
+    url: 'https://www.figma.com/design/ABC123/F?node-id=1-2',
+  },
+  imports: {
+    primary: "import { Button } from '@discourser/design-system/Button'",
+    namedExports: ['Button'],
+    subpath: '@discourser/design-system/Button',
+  },
+  props: [{ name: 'label', type: 'string', required: true }],
+  example: '<Button label="Click me" />',
+  sourcePath: 'src/components/Button.tsx',
+};
+
+describe('writeManifest', () => {
+  let tmpDir: string;
+  let outputPath: string;
+
+  beforeEach(() => {
+    tmpDir = join(tmpdir(), `figma-codex-writer-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+    outputPath = join(tmpDir, 'figma-codex.json');
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('writes valid JSON to the output path', () => {
+    writeManifest(
+      { Button: sampleEntry },
+      { packageName: '@discourser/design-system', outputPath },
+      tmpDir,
+    );
+    const raw = readFileSync(outputPath, 'utf-8');
+    expect(() => JSON.parse(raw)).not.toThrow();
+  });
+
+  it('includes schema version 1.0.0', () => {
+    writeManifest(
+      { Button: sampleEntry },
+      { packageName: '@discourser/design-system', outputPath },
+      tmpDir,
+    );
+    const manifest = JSON.parse(readFileSync(outputPath, 'utf-8'));
+    expect(manifest.version).toBe('1.0.0');
+  });
+
+  it('includes generatedAt ISO timestamp', () => {
+    writeManifest(
+      { Button: sampleEntry },
+      { packageName: '@discourser/design-system', outputPath },
+      tmpDir,
+    );
+    const manifest = JSON.parse(readFileSync(outputPath, 'utf-8'));
+    expect(manifest.generatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  it('includes all provided components', () => {
+    writeManifest(
+      { Button: sampleEntry },
+      { packageName: '@discourser/design-system', outputPath },
+      tmpDir,
+    );
+    const manifest = JSON.parse(readFileSync(outputPath, 'utf-8'));
+    expect(manifest.components).toHaveProperty('Button');
+    expect(manifest.components.Button.name).toBe('Button');
+  });
+
+  it('uses 2-space indentation', () => {
+    writeManifest(
+      { Button: sampleEntry },
+      { packageName: '@discourser/design-system', outputPath },
+      tmpDir,
+    );
+    const raw = readFileSync(outputPath, 'utf-8');
+    expect(raw).toContain('  "version"');
+  });
+
+  it('collects figmaFiles from all components', () => {
+    writeManifest(
+      { Button: sampleEntry },
+      { packageName: '@discourser/design-system', outputPath },
+      tmpDir,
+    );
+    const manifest = JSON.parse(readFileSync(outputPath, 'utf-8'));
+    expect(manifest.figmaFiles).toHaveProperty('ABC123');
+  });
+
+  it('handles empty component list without throwing', () => {
+    expect(() =>
+      writeManifest(
+        {},
+        { packageName: '@discourser/design-system', outputPath },
+        tmpDir,
+      ),
+    ).not.toThrow();
+  });
+});

package/src/figma-codex/config.ts

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface FigmaCodexConfig {
+  include: string[];
+  outputPath: string;
+  packageName: string;
+  tsconfig: string;
+}
+
+const DEFAULTS: FigmaCodexConfig = {
+  include: ['src/components/**/*.figma.tsx'],
+  outputPath: 'dist/figma-codex.json',
+  packageName: '',
+  tsconfig: 'tsconfig.json',
+};
+
+export function loadConfig(
+  projectRoot: string = process.cwd(),
+): FigmaCodexConfig {
+  let userConfig: Partial<FigmaCodexConfig> = {};
+
+  const configPath = join(projectRoot, 'figma-codex.config.json');
+  if (existsSync(configPath)) {
+    userConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
+  }
+
+  let packageName = userConfig.packageName ?? '';
+  if (!packageName) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      packageName = pkg.name ?? '';
+    }
+  }
+
+  return {
+    ...DEFAULTS,
+    ...userConfig,
+    packageName,
+  };
+}

package/src/figma-codex/fixtures/CompoundComponent/CompoundComponent.tsx

@@ -0,0 +1,17 @@
+'use client';
+// Test fixture — resolver uses text-based regex, imports not required to be valid.
+// Globals declared below satisfy TypeScript; the resolver reads this file as raw text.
+import type { FC, ComponentProps } from 'react';
+
+declare const ark: {
+  div: FC<ComponentProps<'div'>>;
+  h2: FC<ComponentProps<'h2'>>;
+  span: FC<ComponentProps<'span'>>;
+};
+declare function withProvider<T>(el: T, slot: string): T;
+declare function withContext<T>(el: T, slot: string): T;
+
+export type RootProps = ComponentProps<'div'>;
+export const Root = withProvider(ark.div, 'root');
+export const Header = withContext(ark.div, 'header');
+export const Body = withContext(ark.div, 'body');

package/src/figma-codex/fixtures/CompoundComponent/index.ts

@@ -0,0 +1 @@
+export { Root, Header, Body, type RootProps } from './CompoundComponent';

package/src/figma-codex/fixtures/CompoundComponent.figma.tsx

@@ -0,0 +1,14 @@
+import figma from '@figma/code-connect';
+import * as CompoundComponent from './CompoundComponent/index';
+
+figma.connect(
+  CompoundComponent.Root,
+  'https://www.figma.com/design/ABC123/TestFile?node-id=5-10',
+  {
+    example: () => (
+      <CompoundComponent.Root>
+        <CompoundComponent.Header>Title</CompoundComponent.Header>
+      </CompoundComponent.Root>
+    ),
+  },
+);

package/src/figma-codex/fixtures/SimpleComponent.figma.tsx

@@ -0,0 +1,10 @@
+import figma from '@figma/code-connect';
+import { SimpleComponent } from './SimpleComponent';
+
+figma.connect(
+  SimpleComponent,
+  'https://www.figma.com/design/ABC123/TestFile?node-id=1-2',
+  {
+    example: () => <SimpleComponent label="Hello" />,
+  },
+);

package/src/figma-codex/fixtures/SimpleComponent.tsx

@@ -0,0 +1,10 @@
+export interface SimpleComponentProps {
+  /** The display label */
+  label: string;
+  /** Optional size variant */
+  size?: 'sm' | 'md' | 'lg';
+}
+
+export const SimpleComponent = (props: SimpleComponentProps) => (
+  <div>{props.label}</div>
+);

package/src/figma-codex/fixtures/expected-output.json

@@ -0,0 +1,78 @@
+{
+  "version": "1.0.0",
+  "packageName": "@test/design-system",
+  "generatedAt": "2026-02-27T19:21:46.956Z",
+  "gitHash": "3fd0a961",
+  "figmaFiles": {
+    "ABC123": {
+      "fileKey": "ABC123"
+    }
+  },
+  "components": {
+    "CompoundComponent": {
+      "name": "CompoundComponent",
+      "type": "compound",
+      "figma": {
+        "fileKey": "ABC123",
+        "nodeId": "5:10",
+        "url": "https://www.figma.com/design/ABC123/TestFile?node-id=5-10"
+      },
+      "imports": {
+        "primary": "import * as CompoundComponent from '@test/design-system/CompoundComponent'",
+        "namedExports": [
+          "CompoundComponent.Root",
+          "CompoundComponent.Header",
+          "CompoundComponent.Body"
+        ]
+      },
+      "props": [],
+      "subComponents": [
+        {
+          "name": "Root",
+          "element": "div"
+        },
+        {
+          "name": "Header",
+          "element": "div"
+        },
+        {
+          "name": "Body",
+          "element": "div"
+        }
+      ],
+      "example": "<CompoundComponent.Root>\n        <CompoundComponent.Header>Title</CompoundComponent.Header>\n      </CompoundComponent.Root>",
+      "sourcePath": "src/figma-codex/fixtures/CompoundComponent/index.ts"
+    },
+    "SimpleComponent": {
+      "name": "SimpleComponent",
+      "type": "simple",
+      "figma": {
+        "fileKey": "ABC123",
+        "nodeId": "1:2",
+        "url": "https://www.figma.com/design/ABC123/TestFile?node-id=1-2"
+      },
+      "imports": {
+        "primary": "import { SimpleComponent } from '@test/design-system/SimpleComponent'",
+        "namedExports": [
+          "SimpleComponent"
+        ]
+      },
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "description": "The display label"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "required": false,
+          "description": "Optional size variant"
+        }
+      ],
+      "example": "<SimpleComponent label=\"Hello\" />",
+      "sourcePath": "src/figma-codex/fixtures/SimpleComponent.tsx"
+    }
+  }
+}

package/src/figma-codex/generate.ts

@@ -0,0 +1,106 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseFigmaFile, ParseError } from './parser';
+import { resolveComponent } from './resolver';
+import { writeManifest } from './writer';
+import { loadConfig, type FigmaCodexConfig } from './config';
+import type { ComponentEntry } from './schema';
+
+/** Recursively find all .figma.tsx files under a directory */
+function findFigmaFiles(rootDir: string): string[] {
+  const files: string[] = [];
+
+  function walk(dir: string) {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith('.figma.tsx')) files.push(full);
+    }
+  }
+
+  walk(rootDir);
+  return files;
+}
+
+export interface GenerateOptions extends FigmaCodexConfig {
+  projectRoot?: string;
+}
+
+export function generate(options: GenerateOptions): void {
+  const projectRoot = options.projectRoot ?? process.cwd();
+
+  // Resolve include patterns to base directories then scan recursively
+  const figmaFiles: string[] = [];
+  for (const pattern of options.include) {
+    // Extract the literal prefix before the first '*' as the base directory to walk.
+    // Patterns starting with '*' (e.g. '**/*.figma.tsx') fall back to projectRoot.
+    // Patterns like 'src/components/**/*.figma.tsx' correctly resolve to 'src/components/'.
+    const starIdx = pattern.indexOf('*');
+    const baseDir =
+      starIdx > 0
+        ? isAbsolute(pattern.slice(0, starIdx))
+          ? pattern.slice(0, starIdx).replace(/\/$/, '')
+          : join(projectRoot, pattern.slice(0, starIdx).replace(/\/$/, ''))
+        : projectRoot;
+    const found = findFigmaFiles(baseDir);
+    figmaFiles.push(...found);
+  }
+
+  if (figmaFiles.length === 0) {
+    console.warn(
+      '[figma-codex] No .figma.tsx files found. Check your include patterns.',
+    );
+    return;
+  }
+
+  const components: Record<string, ComponentEntry> = {};
+
+  for (const filePath of figmaFiles) {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const parsed = parseFigmaFile(content, filePath);
+      const entry = resolveComponent(parsed, options);
+      components[entry.name] = entry;
+      console.log(`[figma-codex] ✓ ${entry.name} (${entry.type})`);
+    } catch (err) {
+      if (err instanceof ParseError) {
+        console.warn(`[figma-codex] ⚠ Skipping ${filePath}: ${err.message}`);
+      } else {
+        console.warn(`[figma-codex] ⚠ Skipping ${filePath}: ${String(err)}`);
+      }
+    }
+  }
+
+  if (Object.keys(components).length === 0) {
+    throw new Error('[figma-codex] No components successfully parsed.');
+  }
+
+  writeManifest(
+    components,
+    { packageName: options.packageName, outputPath: options.outputPath },
+    projectRoot,
+  );
+  console.log(
+    `[figma-codex] Generated ${Object.keys(components).length} components → ${options.outputPath}`,
+  );
+}
+
+// CLI entry point
+const currentFile = fileURLToPath(import.meta.url);
+if (process.argv[1] && resolve(process.argv[1]) === resolve(currentFile)) {
+  try {
+    const config = loadConfig();
+    generate({ ...config, projectRoot: process.cwd() });
+  } catch (err) {
+    console.error(String(err));
+    process.exit(1);
+  }
+}

package/src/figma-codex/parser.ts

@@ -0,0 +1,138 @@
+export class ParseError extends Error {
+  constructor(
+    message: string,
+    public readonly filePath: string,
+  ) {
+    super(`ParseError: ${message} (${filePath})`);
+    this.name = 'ParseError';
+  }
+}
+
+export interface ParsedFigmaFile {
+  filePath: string;
+  importStyle: 'named' | 'namespace';
+  componentName: string;
+  importSource: string;
+  connectSubComponent?: string;
+  figmaUrl: string;
+  figmaFileKey: string;
+  figmaNodeId: string;
+  example: string;
+  propsMapping: Record<string, string>;
+}
+
+function parseNodeId(url: string): string {
+  const match = url.match(/node-id=([^&'"]+)/);
+  if (!match) return '';
+  return match[1].replace(/-/g, ':');
+}
+
+function parseFileKey(url: string): string {
+  const match = url.match(/figma\.com\/design\/([^/?]+)/);
+  return match?.[1] ?? '';
+}
+
+function extractExample(content: string): string {
+  const exampleIdx = content.indexOf('example:');
+  if (exampleIdx === -1) return '';
+
+  const arrowIdx = content.indexOf('=>', exampleIdx);
+  if (arrowIdx === -1) return '';
+
+  const afterArrow = content.slice(arrowIdx + 2).trimStart();
+
+  if (afterArrow.startsWith('(')) {
+    // Multi-line: track balanced parens
+    let depth = 0;
+    let i = 0;
+    for (; i < afterArrow.length; i++) {
+      if (afterArrow[i] === '(') depth++;
+      else if (afterArrow[i] === ')') {
+        depth--;
+        if (depth === 0) break;
+      }
+    }
+    const inner = afterArrow.slice(1, i).trim();
+    return inner;
+  } else {
+    // Single-line: grab to end of line, strip trailing comma
+    const lineEnd = afterArrow.indexOf('\n');
+    const line = lineEnd === -1 ? afterArrow : afterArrow.slice(0, lineEnd);
+    return line.replace(/,\s*$/, '').trim();
+  }
+}
+
+function extractPropsMapping(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  const propsBlockMatch = content.match(/props:\s*\{([^}]+)\}/);
+  if (!propsBlockMatch) return result;
+
+  const block = propsBlockMatch[1];
+  const propNames = block.match(/(\w+)\s*:/g);
+  if (propNames) {
+    for (const p of propNames) {
+      result[p.replace(':', '').trim()] = 'figma.enum';
+    }
+  }
+  return result;
+}
+
+export function parseFigmaFile(
+  content: string,
+  filePath: string,
+): ParsedFigmaFile {
+  // Try namespace import: import * as X from './path'
+  const nsMatch = content.match(
+    /import\s+\*\s+as\s+(\w+)\s+from\s+['"]([^'"]+)['"]/,
+  );
+  // Try named import: import { X } from './path'  (skip figma import itself)
+  const namedMatches = [
+    ...content.matchAll(/import\s+\{\s*(\w+)\s*\}\s+from\s+['"]([^'"]+)['"]/g),
+  ];
+  // Filter out the figma import itself
+  const namedMatch = namedMatches.find(
+    (m) => !m[2].includes('figma') && !m[2].includes('@figma'),
+  );
+
+  if (!nsMatch && !namedMatch) {
+    throw new ParseError('No component import found', filePath);
+  }
+
+  const connectMatch = content.match(
+    /figma\.connect\(\s*(\w+)(?:\.(\w+))?\s*,\s*['"]([^'"]+)['"]/,
+  );
+  if (!connectMatch) {
+    throw new ParseError('No figma.connect() call found', filePath);
+  }
+
+  const figmaUrl = connectMatch[3];
+  const connectSubComponent = connectMatch[2];
+
+  if (nsMatch) {
+    return {
+      filePath,
+      importStyle: 'namespace',
+      componentName: nsMatch[1],
+      importSource: nsMatch[2],
+      connectSubComponent,
+      figmaUrl,
+      figmaFileKey: parseFileKey(figmaUrl),
+      figmaNodeId: parseNodeId(figmaUrl),
+      example: extractExample(content),
+      propsMapping: extractPropsMapping(content),
+    };
+  }
+
+  return {
+    filePath,
+    importStyle: 'named',
+    componentName: namedMatch![1],
+    importSource: namedMatch![2],
+    connectSubComponent,
+    figmaUrl,
+    figmaFileKey: parseFileKey(figmaUrl),
+    figmaNodeId: parseNodeId(figmaUrl),
+    example: extractExample(content),
+    propsMapping: extractPropsMapping(content),
+  };
+}