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

package/scanner/cli.ts

@@ -6,11 +6,11 @@
  * that the Figma plugin uses to create components.
  *
  * Usage (consumer project, after `pnpm add -D inkbridge && pnpm exec inkbridge setup`):
- *   pnpm figma:scan                   — run scanner manually
- *   GET /api/figma/scan-components    — called automatically by the Figma plugin
+ *   pnpm inkbridge:scan               — run scanner manually
+ *   GET /api/inkbridge/scan-components    — called automatically by the Figma plugin
  *
  * Usage (monorepo dev):
- *   npx tsx tools/figma-plugin-tailwind-tokens/scanner/cli.ts
+ *   npx tsx tools/figma-plugin/scanner/cli.ts
  */
 
 import * as fs from 'fs';
@@ -22,8 +22,9 @@ import { extractColorTokens, extractPaletteTokens, TAILWIND_SPACING, inferLayout
 import { collectAllClasses } from './class-collector';
 import { buildStyleMap } from './style-map';
 import { readTokenSourceMap } from './css-token-reader';
-import type { ComponentDefinitions, ScannerConfig, LayoutInfo, ResponsiveInfo, ColorSchemeInfo, IconImportSpec, IconRegistryEntry } from './types';
-import type { TokenSourceMode } from '../src/token-source';
+import type { ComponentDefinitions, ScannerConfig, ResponsiveInfo, IconImportSpec, IconRegistryEntry, ComponentAnalysis, JsxNode, AtomicKind } from './types';
+import type { TokenSourceMode } from '../src/tokens/token-source';
+import { inferSafeTextOverridePropKeys } from '../src/components/symbol-instance-policy';
 
 // ============================================================================
 // CLI flags
@@ -56,6 +57,14 @@ const DEFAULT_CONFIG: ScannerConfig = {
 
 const COMPONENT_DEFS_SCHEMA_VERSION = 1;
 
+type GraphMeta = {
+  kind: AtomicKind;
+  usesCount: number;
+  usedByCount: number;
+  isLeaf: boolean;
+  symbolCandidate: boolean;
+};
+
 // ============================================================================
 // Main
 // ============================================================================
@@ -77,7 +86,9 @@ async function main() {
     const styleMap = await buildStyleMap(allClasses);
     const iconRegistry = await buildIconRegistry(scanner.getIconRegistry());
 
-    // Enrich each analysis with layout, responsive, and color-scheme info
+    const graphMetaByName = buildGraphMetadata(analyses);
+
+    // Enrich each analysis with layout, responsive, color-scheme, and graph metadata
     const enriched = analyses.map(analysis => {
       const classes = getAllClassesFromAnalysis(analysis);
       const layout = inferLayout(classes);
@@ -88,8 +99,21 @@ async function main() {
       );
       const responsive: ResponsiveInfo = { breakpoints, hasResponsiveVisibility };
       const colorScheme = groupClassesByColorScheme(classes);
-
-      return { analysis, layout, responsive, colorScheme };
+      const graphMeta = graphMetaByName.get(analysis.name);
+      const safeTextOverrideProps = inferSafeTextOverridePropKeys(analysis);
+
+      return {
+        analysis,
+        layout,
+        responsive,
+        colorScheme,
+        kind: graphMeta?.kind,
+        usesCount: graphMeta?.usesCount,
+        usedByCount: graphMeta?.usedByCount,
+        isLeaf: graphMeta?.isLeaf,
+        symbolCandidate: graphMeta?.symbolCandidate,
+        safeTextOverrideProps: safeTextOverrideProps.length > 0 ? safeTextOverrideProps : undefined,
+      };
     });
 
     // Build output
@@ -116,13 +140,23 @@ async function main() {
       });
     }
 
-    // Write to JSON file
-    const defaultOutputPath = 'tools/figma-plugin-tailwind-tokens/component-definitions.json';
+    // Write to JSON file. Default matches the consumer-side path used by
+    // the generated `scan-components` API route (see
+    // `templates/scan-components-route.ts`), so a manual
+    // `pnpm inkbridge:scan` and a plugin-triggered scan land the JSON in
+    // the same place. The path lives under `.inkbridge/` at the consumer
+    // project root; in this repo the scanner is also used internally
+    // (e.g. by regression fixtures) and the same path applies.
+    const defaultOutputPath = '.inkbridge/component-definitions.json';
     const outputPath = CLI_OUTPUT
       ? path.resolve(process.cwd(), CLI_OUTPUT)
       : path.resolve(process.cwd(), defaultOutputPath);
     fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-    fs.writeFileSync(outputPath, JSON.stringify(finalOutput, null, 2));
+    // Compact JSON (no pretty-print). The scan output is only read
+    // programmatically by the plugin runtime — the indentation cost was
+    // ~30% of the file size for no functional benefit. If you need to
+    // hand-inspect it, pipe through `jq` (`jq . component-definitions.json`).
+    fs.writeFileSync(outputPath, JSON.stringify(finalOutput));
 
     // Print summary
     console.log('✅ Scanned components:\n');
@@ -193,12 +227,109 @@ async function main() {
     console.log(`\n📦 Output written to: ${outputPath}`);
     console.log(`   ${analyses.length} components, ${totalStories} stories, ${colorTokens.length} color tokens`);
 
+    if (analyses.length === 0 || totalStories === 0) {
+      printEmptyScanDiagnostic({
+        config,
+        componentCount: analyses.length,
+        storyCount: totalStories,
+      });
+    }
+
   } catch (err) {
     console.error('❌ Scanner failed:', err);
     process.exit(1);
   }
 }
 
+/**
+ * Print actionable hints when the scan returns 0 components or 0 stories.
+ * Walks the configured component paths looking for story-like files
+ * (`*.stories.ts`, `*.stories.tsx`, `*.stories.jsx`, `*.stories.js`,
+ * `*.stories.mdx`) and names what it found vs what the scanner was
+ * looking for. Better than a silent "0 stories" line.
+ */
+function printEmptyScanDiagnostic(opts: {
+  config: ScannerConfig;
+  componentCount: number;
+  storyCount: number;
+}): void {
+  const { config, componentCount, storyCount } = opts;
+  const cwd = process.cwd();
+  const STORY_EXTS = ['.stories.tsx', '.stories.ts', '.stories.jsx', '.stories.js', '.stories.mdx'];
+  const componentExts = ['.tsx'];
+  const found: { stories: string[]; components: string[] } = { stories: [], components: [] };
+
+  function walk(dir: string, depth: number): void {
+    if (depth > 8) return;
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch (_e) { return; }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.next' || entry.name === '.git' || entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full, depth + 1);
+      } else if (entry.isFile()) {
+        const rel = path.relative(cwd, full);
+        if (STORY_EXTS.some(ext => entry.name.endsWith(ext))) {
+          found.stories.push(rel);
+        } else if (componentExts.some(ext => entry.name.endsWith(ext))) {
+          // Only count files that aren't tests / index barrels
+          if (!entry.name.endsWith('.test.tsx') && entry.name !== 'index.tsx') {
+            found.components.push(rel);
+          }
+        }
+      }
+    }
+  }
+
+  for (const cp of config.componentPaths) {
+    const abs = path.resolve(cwd, cp);
+    if (fs.existsSync(abs)) walk(abs, 0);
+  }
+
+  console.log('');
+  if (componentCount === 0) {
+    console.log('⚠️  No components matched. Scanner looked under:');
+    for (const cp of config.componentPaths) {
+      const abs = path.resolve(cwd, cp);
+      const exists = fs.existsSync(abs);
+      console.log(`     - ${cp}  ${exists ? '' : '(missing)'}`);
+    }
+    if (found.components.length > 0) {
+      console.log('');
+      console.log(`   Found ${found.components.length} .tsx file(s) but none qualified as components. Check`);
+      console.log('   `inkbridge.config.json` — `componentPaths`, `exclude`, and `onlyWithStories`.');
+    }
+  } else if (storyCount === 0) {
+    console.log(`⚠️  Found ${componentCount} component(s) but 0 stories.`);
+    console.log('   Scanner pairs `<Component>.tsx` with `<Component>.stories.tsx`');
+    console.log('   or `<Component>.stories.ts` in the same folder.');
+    if (found.stories.length > 0) {
+      const wrongExt = found.stories.filter(f => f.endsWith('.stories.jsx') || f.endsWith('.stories.js') || f.endsWith('.stories.mdx'));
+      if (wrongExt.length > 0) {
+        console.log('');
+        console.log('   Found story files with unsupported extensions:');
+        for (const f of wrongExt.slice(0, 10)) console.log(`     - ${f}`);
+        if (wrongExt.length > 10) console.log(`     … and ${wrongExt.length - 10} more`);
+        console.log('   Rename to `.stories.tsx` (preferred) or `.stories.ts`.');
+      } else {
+        console.log('');
+        console.log('   Story files exist but none are co-located with a component:');
+        for (const f of found.stories.slice(0, 10)) console.log(`     - ${f}`);
+        if (found.stories.length > 10) console.log(`     … and ${found.stories.length - 10} more`);
+        console.log('   Move each story next to its component, or update');
+        console.log('   `inkbridge.config.json:componentPaths` to include the story folder.');
+      }
+    } else {
+      console.log('');
+      console.log('   No story files found anywhere under the component paths.');
+      console.log('   Add one (e.g. `src/components/Button/Button.stories.tsx`) and re-run.');
+    }
+  }
+  console.log('');
+}
+
 /**
  * Extract all classes from any component analysis type
  */
@@ -226,6 +357,204 @@ function getAllClassesFromAnalysis(analysis: import('./types').ComponentAnalysis
   return classes;
 }
 
+type StructureMetrics = {
+  elementCount: number;
+  componentNodeCount: number;
+  maxDepth: number;
+};
+
+function normalizeComponentName(name: string): string {
+  return String(name || '')
+    .replace(/[^a-zA-Z0-9]/g, '')
+    .toLowerCase();
+}
+
+function collectStoryRefsFromJsxTree(node: JsxNode | undefined, out: Set<string>): void {
+  if (!node || node.type !== 'element') return;
+  const tagName = String(node.tagName || '');
+  const isComponent = !!node.isComponent || /^[A-Z]/.test(tagName);
+  if (isComponent && tagName) {
+    out.add(tagName);
+  }
+  for (let i = 0; i < node.children.length; i++) {
+    collectStoryRefsFromJsxTree(node.children[i], out);
+  }
+}
+
+function collectStructureMetricsFromJsxTree(node: JsxNode | undefined, depth: number, metrics: StructureMetrics): void {
+  if (!node || node.type !== 'element') return;
+  metrics.elementCount++;
+  metrics.maxDepth = Math.max(metrics.maxDepth, depth);
+  if (node.isComponent || /^[A-Z]/.test(String(node.tagName || ''))) {
+    metrics.componentNodeCount++;
+  }
+  for (let i = 0; i < node.children.length; i++) {
+    collectStructureMetricsFromJsxTree(node.children[i], depth + 1, metrics);
+  }
+}
+
+function collectStoryComponentRefs(analysis: ComponentAnalysis): Set<string> {
+  const refs = new Set<string>();
+  const stories = analysis.stories || [];
+  for (let i = 0; i < stories.length; i++) {
+    const story = stories[i];
+    const instances = story.instances || [];
+    for (let j = 0; j < instances.length; j++) {
+      const ref = String(instances[j]?.componentName || '').trim();
+      if (ref) refs.add(ref);
+    }
+    collectStoryRefsFromJsxTree(story.jsxTree, refs);
+  }
+  return refs;
+}
+
+function collectStoryStructureMetrics(analysis: ComponentAnalysis): StructureMetrics {
+  const metrics: StructureMetrics = { elementCount: 0, componentNodeCount: 0, maxDepth: 0 };
+  const stories = analysis.stories || [];
+  for (let i = 0; i < stories.length; i++) {
+    const perStory: StructureMetrics = { elementCount: 0, componentNodeCount: 0, maxDepth: 0 };
+    collectStructureMetricsFromJsxTree(stories[i].jsxTree, 1, perStory);
+    metrics.elementCount = Math.max(metrics.elementCount, perStory.elementCount);
+    metrics.componentNodeCount = Math.max(metrics.componentNodeCount, perStory.componentNodeCount);
+    metrics.maxDepth = Math.max(metrics.maxDepth, perStory.maxDepth);
+  }
+  return metrics;
+}
+
+function createAnalysisResolver(analyses: ComponentAnalysis[]): (refName: string) => string | null {
+  const byName = new Map<string, string>();
+  const byNormalized = new Map<string, string[]>();
+
+  for (let i = 0; i < analyses.length; i++) {
+    const name = analyses[i].name;
+    if (!name) continue;
+    byName.set(name, name);
+    const normalized = normalizeComponentName(name);
+    const list = byNormalized.get(normalized) || [];
+    list.push(name);
+    byNormalized.set(normalized, list);
+  }
+
+  return function resolve(refName: string): string | null {
+    const ref = String(refName || '').trim();
+    if (!ref) return null;
+    if (byName.has(ref)) return byName.get(ref) || null;
+
+    const normalized = normalizeComponentName(ref);
+    const direct = byNormalized.get(normalized);
+    if (direct && direct.length === 1) return direct[0];
+    return null;
+  };
+}
+
+function inferAtomicKind(
+  analysis: ComponentAnalysis,
+  metrics: StructureMetrics,
+  usesCount: number,
+  usedByCount: number
+): AtomicKind {
+  const hasStory = !!analysis.hasStory;
+  const isLeaf = usesCount === 0;
+  const classCount = getAllClassesFromAnalysis(analysis).length;
+  const isPrimitiveType = analysis.type === 'cva' || analysis.type === 'state';
+  const hasComposition = usesCount > 0 || metrics.componentNodeCount > 0;
+  const isHighComplexity =
+    metrics.maxDepth >= 5
+    || metrics.elementCount >= 24
+    || (hasComposition && metrics.elementCount >= 16)
+    || usesCount >= 2;
+
+  if (!hasStory && usedByCount === 0 && isLeaf) {
+    return 'utility';
+  }
+
+  if (isPrimitiveType) {
+    return 'atom';
+  }
+
+  if (isLeaf && usedByCount > 0 && metrics.maxDepth <= 3 && metrics.elementCount <= 10) {
+    return 'atom';
+  }
+
+  if (isHighComplexity) {
+    return 'organism';
+  }
+
+  if (analysis.type === 'compound' || hasComposition || usedByCount > 0) {
+    return 'molecule';
+  }
+
+  if (isLeaf && classCount > 0 && metrics.maxDepth <= 2) {
+    return 'atom';
+  }
+
+  return 'other';
+}
+
+function isSymbolCandidate(kind: AtomicKind, analysis: ComponentAnalysis, usedByCount: number): boolean {
+  if (analysis.type === 'cva' || analysis.type === 'state') {
+    return kind === 'atom' || kind === 'molecule';
+  }
+  if (analysis.type === 'compound') {
+    return kind === 'molecule' || kind === 'atom';
+  }
+  if (analysis.type === 'simple') {
+    return (kind === 'atom' || kind === 'molecule') && usedByCount > 0;
+  }
+  return false;
+}
+
+function buildGraphMetadata(analyses: ComponentAnalysis[]): Map<string, GraphMeta> {
+  const outgoing = new Map<string, Set<string>>();
+  const incoming = new Map<string, Set<string>>();
+  const metricsByName = new Map<string, StructureMetrics>();
+  const resolveAnalysisName = createAnalysisResolver(analyses);
+
+  for (let i = 0; i < analyses.length; i++) {
+    const analysis = analyses[i];
+    outgoing.set(analysis.name, new Set<string>());
+    incoming.set(analysis.name, new Set<string>());
+    metricsByName.set(analysis.name, collectStoryStructureMetrics(analysis));
+  }
+
+  for (let i = 0; i < analyses.length; i++) {
+    const analysis = analyses[i];
+    const refs = collectStoryComponentRefs(analysis);
+    const from = outgoing.get(analysis.name);
+    if (!from) continue;
+    refs.forEach((refName) => {
+      const target = resolveAnalysisName(refName);
+      if (!target || target === analysis.name) return;
+      from.add(target);
+      const targetIncoming = incoming.get(target);
+      if (targetIncoming) targetIncoming.add(analysis.name);
+    });
+  }
+
+  const out = new Map<string, GraphMeta>();
+  for (let i = 0; i < analyses.length; i++) {
+    const analysis = analyses[i];
+    const usesCount = outgoing.get(analysis.name)?.size || 0;
+    const usedByCount = incoming.get(analysis.name)?.size || 0;
+    const isLeaf = usesCount === 0;
+    const metrics = metricsByName.get(analysis.name) || {
+      elementCount: 0,
+      componentNodeCount: 0,
+      maxDepth: 0,
+    };
+    const kind = inferAtomicKind(analysis, metrics, usesCount, usedByCount);
+    out.set(analysis.name, {
+      kind,
+      usesCount,
+      usedByCount,
+      isLeaf,
+      symbolCandidate: isSymbolCandidate(kind, analysis, usedByCount),
+    });
+  }
+
+  return out;
+}
+
 /**
  * Extract component paths from Storybook's stories globs.
  * e.g. "../src/**\/\*.stories.@(ts|tsx)" → ["src"]
@@ -304,8 +633,8 @@ async function buildIconRegistry(imports: Record<string, IconImportSpec>): Promi
     const spec = imports[localName];
     if (!spec) continue;
     try {
-      const mod = await import(spec.module);
-      const IconComponent = (mod as any)[spec.exportName];
+      const mod = (await import(spec.module)) as Record<string, React.ComponentType<{ size?: number; color?: string }>>;
+      const IconComponent = mod[spec.exportName];
       if (!IconComponent) continue;
       const element = React.createElement(IconComponent, { size: 24, color: '#000' });
       let svg = renderToStaticMarkup(element);