@fragments-sdk/cli 0.6.0 → 0.7.0

package/dist/{viewer-R3Q6WAMJ.js → viewer-SUFOISZM.js}

@@ -6,10 +6,10 @@ import {
   findStorybookDir,
   generatePreviewModule,
   loadConfig
-} from "./chunk-SSLQXHNX.js";
+} from "./chunk-CVXKXVOY.js";
 import {
   generateContext
-} from "./chunk-Q7GOHVOK.js";
+} from "./chunk-TJ34N7C7.js";
 import {
   BRAND
 } from "./chunk-6JBGU74P.js";
@@ -240,7 +240,7 @@ var sharedRenderPool = null;
 var browserPoolModule = null;
 async function getSharedRenderPool() {
   if (!browserPoolModule) {
-    browserPoolModule = await import("./service-F3E4JJM7.js");
+    browserPoolModule = await import("./service-T2L7VLTE.js");
   }
   if (!sharedRenderPool) {
     sharedRenderPool = new browserPoolModule.BrowserPool({
@@ -469,7 +469,7 @@ function segmentsPlugin(options) {
             const address = _server.httpServer?.address();
             const port = typeof address === "object" && address ? address.port : 6006;
             const renderViewport = viewport || { width: 800, height: 600 };
-            const { FigmaClient, bufferToBase64Url } = await import("./service-F3E4JJM7.js");
+            const { FigmaClient, bufferToBase64Url } = await import("./service-T2L7VLTE.js");
             const figmaClient = new FigmaClient({
               accessToken: figmaToken
             });
@@ -560,7 +560,7 @@ function segmentsPlugin(options) {
               );
               return;
             }
-            const { FigmaClient } = await import("./service-F3E4JJM7.js");
+            const { FigmaClient } = await import("./service-T2L7VLTE.js");
             const figmaClient = new FigmaClient({ accessToken: figmaToken });
             const { fileKey, nodeId } = figmaClient.parseUrl(figmaUrl);
             const figmaDesignProps = await figmaClient.getNodeProperties(
@@ -601,7 +601,7 @@ function segmentsPlugin(options) {
               }));
               return;
             }
-            const { getSharedTokenRegistry } = await import("./service-F3E4JJM7.js");
+            const { getSharedTokenRegistry } = await import("./service-T2L7VLTE.js");
             const registry = getSharedTokenRegistry();
             if (!registry.isInitialized()) {
               await registry.initialize(config.tokens, projectRoot);
@@ -661,7 +661,7 @@ function segmentsPlugin(options) {
               }));
               return;
             }
-            const { getSharedTokenRegistry } = await import("./service-F3E4JJM7.js");
+            const { getSharedTokenRegistry } = await import("./service-T2L7VLTE.js");
             const registry = getSharedTokenRegistry();
             if (!registry.isInitialized()) {
               await registry.initialize(config.tokens, projectRoot);
@@ -723,7 +723,7 @@ function segmentsPlugin(options) {
               res.end(JSON.stringify({ error: "Could not resolve segment file path" }));
               return;
             }
-            const { getSharedTokenRegistry } = await import("./service-F3E4JJM7.js");
+            const { getSharedTokenRegistry } = await import("./service-T2L7VLTE.js");
             const registry = getSharedTokenRegistry();
             if (!registry.isInitialized()) {
               await registry.initialize(config.tokens, projectRoot);
@@ -849,7 +849,7 @@ function segmentsPlugin(options) {
             }
             const { writeFile, mkdir } = await import("fs/promises");
             const { join: join2 } = await import("path");
-            const { BRAND: BRAND2 } = await import("./core-SKRPJQZG.js");
+            const { BRAND: BRAND2 } = await import("./core-W2HYIQW6.js");
             const fragmentsDir = join2(projectRoot, BRAND2.dataDir, BRAND2.componentsDir);
             await mkdir(fragmentsDir, { recursive: true });
             const fragmentPath = join2(
@@ -904,7 +904,7 @@ function segmentsPlugin(options) {
             const {
               getSharedTokenRegistry,
               generateTokenPatches
-            } = await import("./service-F3E4JJM7.js");
+            } = await import("./service-T2L7VLTE.js");
             const registry = getSharedTokenRegistry();
             if (!registry.isInitialized()) {
               await registry.initialize(config.tokens, projectRoot);
@@ -1566,7 +1566,7 @@ async function loadFullSegmentForCompare(_server, _segmentFiles, componentName,
   }
 }
 async function compareImages(image1Base64, image2Base64, threshold) {
-  const { DiffEngine, base64UrlToBuffer, bufferToBase64Url } = await import("./service-F3E4JJM7.js");
+  const { DiffEngine, base64UrlToBuffer, bufferToBase64Url } = await import("./service-T2L7VLTE.js");
   const { PNG } = await import("pngjs");
   const buffer1 = base64UrlToBuffer(image1Base64);
   const buffer2 = base64UrlToBuffer(image2Base64);
@@ -1819,4 +1819,4 @@ export {
   createDevServer,
   segmentsPlugin
 };
-//# sourceMappingURL=viewer-R3Q6WAMJ.js.map
+//# sourceMappingURL=viewer-SUFOISZM.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "CLI, MCP server, and dev tools for Fragments design system",
   "repository": {
     "type": "git",
@@ -65,7 +65,7 @@
     "vite": "^6.0.0",
     "vite-plugin-svgr": "^4.5.0",
     "zod": "^3.24.1",
-    "@fragments-sdk/context": "0.2.0"
+    "@fragments-sdk/context": "0.3.0"
   },
   "devDependencies": {
     "@types/babel__generator": "^7.6.8",

package/src/bin.ts

@@ -35,6 +35,7 @@ import { add } from './commands/add.js';
 import { linkFigma, linkStorybook } from './commands/link/index.js';
 import { enhance } from './commands/enhance.js';
 import { scan } from './commands/scan.js';
+import { graph } from './commands/graph.js';
 
 // Import existing commands that were already extracted
 import { runScreenshotCommand } from './screenshot.js';
@@ -844,6 +845,28 @@ program
     }
   });
 
+// ============================================================================
+// GRAPH COMMAND
+// ============================================================================
+program
+  .command('graph')
+  .description('Query the component relationship graph')
+  .argument('[component]', 'Component name (optional)')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('-m, --mode <mode>', 'Query mode: health, dependencies, dependents, impact, path, composition, alternatives, islands')
+  .option('-t, --target <component>', 'Target component for path mode')
+  .option('--edge-types <types>', 'Comma-separated edge types to filter by')
+  .option('--depth <number>', 'Max traversal depth for impact mode', parseInt)
+  .option('--format <format>', 'Output format: table, json, dot', 'table')
+  .action(async (component, options) => {
+    try {
+      await graph(component, options);
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
 // ============================================================================
 // TEST COMMAND
 // ============================================================================

package/src/build.ts

@@ -24,6 +24,8 @@ import {
   resolveComponentSourcePath,
   type AutoDetectedPropDefinition,
 } from "./core/auto-props.js";
+import { buildComponentGraph } from "./core/graph-extractor.js";
+import { serializeGraph } from "@fragments-sdk/context/graph";
 
 type CompiledProp = CompiledSegment["props"][string];
 
@@ -295,6 +297,46 @@ export async function buildSegments(
     }
   }
 
+  // Build component graph for AI structural queries
+  // Derive component directory from configDir (typically src/components/)
+  const componentDir = resolve(configDir, "src", "components");
+  let graphData: ReturnType<typeof serializeGraph> | undefined;
+  try {
+    const graphResult = await buildComponentGraph(segments, blocks, componentDir);
+
+    // Auto-enrich segments with detected metadata
+    for (const [name, segment] of Object.entries(segments)) {
+      const detected = graphResult.autoDetected.get(name);
+      if (!detected) continue;
+
+      if (!segment.ai) segment.ai = {};
+      if (!segment.ai.subComponents && detected.subComponents) {
+        segment.ai.subComponents = detected.subComponents;
+      }
+      if (!segment.ai.compositionPattern && detected.compositionPattern) {
+        segment.ai.compositionPattern = detected.compositionPattern;
+      }
+      if (!segment.ai.commonPatterns && detected.commonPatterns) {
+        segment.ai.commonPatterns = detected.commonPatterns;
+      }
+      if (!segment.ai.requiredChildren && detected.requiredChildren) {
+        segment.ai.requiredChildren = detected.requiredChildren;
+      }
+    }
+
+    // Report drift warnings
+    for (const w of graphResult.warnings) {
+      warnings.push({ file: "graph", warning: w });
+    }
+
+    graphData = serializeGraph(graphResult.graph);
+  } catch (error) {
+    warnings.push({
+      file: "graph",
+      warning: `Graph extraction failed: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+
   const output: CompiledSegmentsFile = {
     version: "1.0.0",
     generatedAt: new Date().toISOString(),
@@ -302,6 +344,7 @@ export async function buildSegments(
     segments,
     ...(Object.keys(blocks).length > 0 && { blocks }),
     ...(tokens && { tokens }),
+    ...(graphData && { graph: graphData }),
   };
 
   const outputPath = resolve(configDir, config.outFile ?? BRAND.outFile);

package/src/commands/graph.ts

@@ -0,0 +1,274 @@
+/**
+ * `fragments graph` — query the component relationship graph from the CLI.
+ *
+ * Loads fragments.json, instantiates the ComponentGraphEngine, and runs
+ * the requested query mode. Output formats: table (colored terminal), json, dot.
+ */
+
+import pc from 'picocolors';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { CompiledSegmentsFile } from '../core/index.js';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import {
+  ComponentGraphEngine,
+  deserializeGraph,
+} from '@fragments-sdk/context/graph';
+import type { GraphEdgeType } from '@fragments-sdk/context/graph';
+
+export interface GraphCommandOptions {
+  config?: string;
+  mode?: string;
+  target?: string;
+  edgeTypes?: string;
+  depth?: number;
+  format?: 'table' | 'json' | 'dot';
+}
+
+export async function graph(
+  component: string | undefined,
+  options: GraphCommandOptions,
+): Promise<void> {
+  const { config, configDir } = await loadConfig(options.config);
+  const outputPath = resolve(configDir, config.outFile ?? BRAND.outFile);
+
+  let data: CompiledSegmentsFile;
+  try {
+    const content = await readFile(outputPath, 'utf-8');
+    data = JSON.parse(content) as CompiledSegmentsFile;
+  } catch {
+    console.error(
+      pc.red(`Error: Could not load ${BRAND.outFile}. Run \`${BRAND.cliCommand} build\` first.`),
+    );
+    process.exit(1);
+  }
+
+  if (!data.graph) {
+    console.error(
+      pc.red(`Error: No graph data in ${BRAND.outFile}. Rebuild with the latest CLI.`),
+    );
+    process.exit(1);
+  }
+
+  const graph = deserializeGraph(data.graph);
+  const blocks = data.blocks
+    ? Object.fromEntries(
+        Object.entries(data.blocks).map(([k, v]) => [k, { components: v.components }]),
+      )
+    : undefined;
+  const engine = new ComponentGraphEngine(graph, blocks);
+
+  const mode = options.mode ?? (component ? 'dependencies' : 'health');
+  const format = options.format ?? 'table';
+  const edgeTypes = options.edgeTypes
+    ? (options.edgeTypes.split(',') as GraphEdgeType[])
+    : undefined;
+
+  // Validate component exists for modes that require it
+  const needsComponent = ['dependencies', 'dependents', 'impact', 'path', 'composition', 'alternatives'];
+  if (needsComponent.includes(mode) && !component) {
+    console.error(pc.red(`Error: "${mode}" mode requires a component name.`));
+    process.exit(1);
+  }
+  if (component && !engine.hasNode(component)) {
+    console.error(pc.red(`Error: Component "${component}" not found in graph.`));
+    process.exit(1);
+  }
+
+  switch (mode) {
+    case 'health': {
+      const health = engine.getHealth();
+      if (format === 'json') {
+        console.log(JSON.stringify(health, null, 2));
+        return;
+      }
+
+      console.log(pc.bold('\nComponent Graph Health\n'));
+      console.log(`  ${pc.cyan('Nodes:')}     ${health.nodeCount}`);
+      console.log(`  ${pc.cyan('Edges:')}     ${health.edgeCount}`);
+      console.log(`  ${pc.cyan('Avg degree:')} ${health.averageDegree}`);
+      console.log(`  ${pc.cyan('Islands:')}   ${health.connectedComponents.length}`);
+      console.log(`  ${pc.cyan('Coverage:')}  ${health.compositionCoverage}% in blocks`);
+      console.log(`  ${pc.cyan('Orphans:')}   ${health.orphans.length > 0 ? health.orphans.join(', ') : pc.green('none')}`);
+
+      if (health.hubs.length > 0) {
+        console.log(`\n  ${pc.bold('Top hubs:')}`);
+        for (const hub of health.hubs.slice(0, 5)) {
+          console.log(`    ${pc.yellow(hub.name)} — ${hub.degree} connections`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case 'dependencies': {
+      const deps = engine.dependencies(component!, edgeTypes);
+      if (format === 'json') {
+        console.log(JSON.stringify({ component, dependencies: deps }, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nDependencies of ${component}\n`));
+      if (deps.length === 0) {
+        console.log('  No outgoing dependencies.');
+      } else {
+        for (const dep of deps) {
+          console.log(`  ${pc.yellow(dep.target)} ${pc.dim(`(${dep.type})`)}${dep.note ? ` — ${dep.note}` : ''}`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case 'dependents': {
+      const deps = engine.dependents(component!, edgeTypes);
+      if (format === 'json') {
+        console.log(JSON.stringify({ component, dependents: deps }, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nDependents of ${component}\n`));
+      if (deps.length === 0) {
+        console.log('  No incoming dependents.');
+      } else {
+        for (const dep of deps) {
+          console.log(`  ${pc.yellow(dep.source)} ${pc.dim(`(${dep.type})`)}${dep.note ? ` — ${dep.note}` : ''}`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case 'impact': {
+      const result = engine.impact(component!, options.depth ?? 3);
+      if (format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nImpact analysis: ${component}\n`));
+      console.log(`  ${pc.red(`${result.totalAffected}`)} affected components, ${pc.red(`${result.affectedBlocks.length}`)} affected blocks\n`);
+
+      if (result.affected.length > 0) {
+        console.log(`  ${pc.bold('Affected components:')}`);
+        for (const entry of result.affected) {
+          const indent = '  '.repeat(entry.depth + 1);
+          console.log(`${indent}${pc.yellow(entry.component)} ${pc.dim(`(depth ${entry.depth}, via ${entry.edgeType})`)}`);
+        }
+      }
+
+      if (result.affectedBlocks.length > 0) {
+        console.log(`\n  ${pc.bold('Affected blocks:')} ${result.affectedBlocks.join(', ')}`);
+      }
+      console.log();
+      break;
+    }
+
+    case 'path': {
+      if (!options.target) {
+        console.error(pc.red('Error: --target is required for path mode.'));
+        process.exit(1);
+      }
+
+      const result = engine.path(component!, options.target);
+      if (format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nPath: ${component} → ${options.target}\n`));
+      if (!result.found) {
+        console.log(`  ${pc.red('No path found.')}`);
+      } else {
+        console.log(`  ${result.path.map(n => pc.yellow(n)).join(pc.dim(' → '))}`);
+        if (result.edges.length > 0) {
+          console.log(`  ${pc.dim(`(${result.edges.map(e => e.type).join(' → ')})`)}`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case 'composition': {
+      const tree = engine.composition(component!);
+      if (format === 'json') {
+        console.log(JSON.stringify(tree, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nComposition: ${component}\n`));
+      console.log(`  ${pc.cyan('Pattern:')}    ${tree.compositionPattern ?? 'unknown'}`);
+      if (tree.parent) {
+        console.log(`  ${pc.cyan('Parent:')}     ${tree.parent}`);
+      }
+      if (tree.subComponents.length > 0) {
+        console.log(`  ${pc.cyan('Sub-components:')}`);
+        for (const sub of tree.subComponents) {
+          const isRequired = tree.requiredChildren.includes(sub);
+          console.log(`    ${pc.yellow(sub)}${isRequired ? pc.red(' (required)') : ''}`);
+        }
+      }
+      if (tree.siblings.length > 0) {
+        console.log(`  ${pc.cyan('Siblings:')}   ${tree.siblings.join(', ')}`);
+      }
+      if (tree.blocks.length > 0) {
+        console.log(`  ${pc.cyan('In blocks:')}  ${tree.blocks.join(', ')}`);
+      }
+      console.log();
+      break;
+    }
+
+    case 'alternatives': {
+      const alts = engine.alternatives(component!);
+      if (format === 'json') {
+        console.log(JSON.stringify({ component, alternatives: alts }, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nAlternatives for ${component}\n`));
+      if (alts.length === 0) {
+        console.log('  No known alternatives.');
+      } else {
+        for (const alt of alts) {
+          console.log(`  ${pc.yellow(alt.component)}${alt.note ? ` — ${alt.note}` : ''}`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case 'islands': {
+      const islands = engine.islands();
+      if (format === 'json') {
+        console.log(JSON.stringify({ islands }, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`\nConnected Islands (${islands.length})\n`));
+      for (let i = 0; i < islands.length; i++) {
+        console.log(`  ${pc.cyan(`Island ${i + 1}`)} (${islands[i].length} components): ${islands[i].join(', ')}`);
+      }
+      console.log();
+      break;
+    }
+
+    default:
+      console.error(pc.red(`Unknown mode: "${mode}". Valid: health, dependencies, dependents, impact, path, composition, alternatives, islands`));
+      process.exit(1);
+  }
+
+  // Graphviz dot output
+  if (format === 'dot') {
+    const lines = ['digraph ComponentGraph {', '  rankdir=LR;', '  node [shape=box, style=rounded];'];
+    for (const node of graph.nodes) {
+      lines.push(`  "${node.name}" [label="${node.name}\\n(${node.category})"];`);
+    }
+    for (const edge of graph.edges) {
+      const style = edge.type === 'alternative-to' ? 'dashed' : 'solid';
+      lines.push(`  "${edge.source}" -> "${edge.target}" [label="${edge.type}", style=${style}];`);
+    }
+    lines.push('}');
+    console.log(lines.join('\n'));
+  }
+}

package/src/core/composition.ts

@@ -1,4 +1,6 @@
 import type { CompiledSegment, RelationshipType } from "./types.js";
+import type { ComponentGraph } from "@fragments-sdk/context/graph";
+import { ComponentGraphEngine } from "@fragments-sdk/context/graph";
 
 // --- Public types ---
 
@@ -58,12 +60,16 @@ const CATEGORY_AFFINITIES: Record<string, string[]> = {
  * Returns warnings about missing relations, usage conflicts,
  * and suggestions for additional components.
  *
+ * When a ComponentGraph is provided via `options.graph`, the analysis is
+ * enhanced with graph-based dependency detection and block-based suggestions.
+ *
  * Browser-safe: no Node.js APIs used.
  */
 export function analyzeComposition(
   segments: Record<string, CompiledSegment>,
   componentNames: string[],
-  _context?: string
+  _context?: string,
+  options?: { graph?: ComponentGraph },
 ): CompositionAnalysis {
   const allNames = new Set(Object.keys(segments));
 
@@ -218,6 +224,63 @@ export function analyzeComposition(
     }
   }
 
+  // 6. Graph-enhanced analysis (when graph data is available)
+  if (options?.graph) {
+    const engine = new ComponentGraphEngine(options.graph);
+
+    // Add graph-based dependency warnings
+    for (const name of components) {
+      const deps = engine.dependencies(name, ["imports", "hook-depends"]);
+      for (const dep of deps) {
+        if (
+          !selectedSet.has(dep.target) &&
+          !suggestedSet.has(dep.target) &&
+          allNames.has(dep.target)
+        ) {
+          suggestions.push({
+            component: dep.target,
+            reason: `"${name}" ${dep.type === "hook-depends" ? "uses a hook from" : "imports"} "${dep.target}"`,
+            relationship: "composition",
+            sourceComponent: name,
+          });
+          suggestedSet.add(dep.target);
+        }
+      }
+    }
+
+    // Add block-based suggestions
+    for (const name of components) {
+      const blocks = engine.blocksUsing(name);
+      for (const blockName of blocks) {
+        // Find other components in this block that aren't selected
+        const blockComps = options.graph.edges
+          .filter(
+            (e) =>
+              e.type === "composes" &&
+              e.provenance === `block:${blockName}` &&
+              (e.source === name || e.target === name)
+          )
+          .map((e) => (e.source === name ? e.target : e.source));
+
+        for (const comp of blockComps) {
+          if (
+            !selectedSet.has(comp) &&
+            !suggestedSet.has(comp) &&
+            allNames.has(comp)
+          ) {
+            suggestions.push({
+              component: comp,
+              reason: `"${name}" and "${comp}" are used together in the "${blockName}" block`,
+              relationship: "composition",
+              sourceComponent: name,
+            });
+            suggestedSet.add(comp);
+          }
+        }
+      }
+    }
+  }
+
   return { components, unknown, warnings, suggestions, guidelines };
 }