@fragments-sdk/context 0.2.0 → 0.3.1

package/dist/graph/index.js

@@ -0,0 +1,388 @@
+// src/graph/types.ts
+var GRAPH_EDGE_TYPES = [
+  "imports",
+  "hook-depends",
+  "renders",
+  "composes",
+  "parent-of",
+  "alternative-to",
+  "sibling-of"
+];
+var EDGE_TYPE_WEIGHTS = {
+  "imports": 1,
+  "hook-depends": 0.75,
+  "renders": 0.5,
+  "composes": 0.5,
+  "parent-of": 1,
+  "alternative-to": 1,
+  "sibling-of": 0.75
+};
+
+// src/graph/engine.ts
+var ComponentGraphEngine = class {
+  nodes;
+  outgoing;
+  incoming;
+  edges;
+  blockIndex;
+  health;
+  constructor(graph, blocks) {
+    this.nodes = /* @__PURE__ */ new Map();
+    this.outgoing = /* @__PURE__ */ new Map();
+    this.incoming = /* @__PURE__ */ new Map();
+    this.edges = graph.edges;
+    this.health = graph.health;
+    this.blockIndex = /* @__PURE__ */ new Map();
+    for (const node of graph.nodes) {
+      this.nodes.set(node.name, node);
+      this.outgoing.set(node.name, []);
+      this.incoming.set(node.name, []);
+    }
+    for (const edge of graph.edges) {
+      const out = this.outgoing.get(edge.source);
+      if (out) out.push(edge);
+      else this.outgoing.set(edge.source, [edge]);
+      const inc = this.incoming.get(edge.target);
+      if (inc) inc.push(edge);
+      else this.incoming.set(edge.target, [edge]);
+    }
+    if (blocks) {
+      for (const [blockName, block] of Object.entries(blocks)) {
+        for (const comp of block.components) {
+          const existing = this.blockIndex.get(comp);
+          if (existing) existing.push(blockName);
+          else this.blockIndex.set(comp, [blockName]);
+        }
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Core queries
+  // -------------------------------------------------------------------------
+  /** Get outgoing edges from a component, optionally filtered by edge type */
+  dependencies(component, edgeTypes) {
+    const edges = this.outgoing.get(component) ?? [];
+    if (!edgeTypes || edgeTypes.length === 0) return edges;
+    return edges.filter((e) => edgeTypes.includes(e.type));
+  }
+  /** Get incoming edges to a component, optionally filtered by edge type */
+  dependents(component, edgeTypes) {
+    const edges = this.incoming.get(component) ?? [];
+    if (!edgeTypes || edgeTypes.length === 0) return edges;
+    return edges.filter((e) => edgeTypes.includes(e.type));
+  }
+  /** BFS transitive closure — what's affected if this component changes */
+  impact(component, maxDepth = 3) {
+    const affected = [];
+    const visited = /* @__PURE__ */ new Set([component]);
+    const queue = [
+      { name: component, depth: 0, path: [component] }
+    ];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current.depth >= maxDepth) continue;
+      const deps = this.incoming.get(current.name) ?? [];
+      for (const edge of deps) {
+        if (visited.has(edge.source)) continue;
+        visited.add(edge.source);
+        const newPath = [...current.path, edge.source];
+        affected.push({
+          component: edge.source,
+          depth: current.depth + 1,
+          path: newPath,
+          edgeType: edge.type
+        });
+        queue.push({ name: edge.source, depth: current.depth + 1, path: newPath });
+      }
+    }
+    const affectedComponents = /* @__PURE__ */ new Set([component, ...affected.map((a) => a.component)]);
+    const affectedBlocks = /* @__PURE__ */ new Set();
+    for (const comp of affectedComponents) {
+      const blocks = this.blockIndex.get(comp);
+      if (blocks) {
+        for (const b of blocks) affectedBlocks.add(b);
+      }
+    }
+    return {
+      component,
+      affected,
+      affectedBlocks: [...affectedBlocks],
+      totalAffected: affected.length
+    };
+  }
+  /** BFS shortest path between two components (undirected) */
+  path(from, to) {
+    if (from === to) {
+      return { found: true, path: [from], edges: [] };
+    }
+    const visited = /* @__PURE__ */ new Set([from]);
+    const queue = [
+      { name: from, path: [from], edges: [] }
+    ];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      const allEdges = [
+        ...this.outgoing.get(current.name) ?? [],
+        ...this.incoming.get(current.name) ?? []
+      ];
+      for (const edge of allEdges) {
+        const neighbor = edge.source === current.name ? edge.target : edge.source;
+        if (visited.has(neighbor)) continue;
+        visited.add(neighbor);
+        const newPath = [...current.path, neighbor];
+        const newEdges = [...current.edges, edge];
+        if (neighbor === to) {
+          return { found: true, path: newPath, edges: newEdges };
+        }
+        queue.push({ name: neighbor, path: newPath, edges: newEdges });
+      }
+    }
+    return { found: false, path: [], edges: [] };
+  }
+  /** Connected components via BFS on undirected projection */
+  islands() {
+    const visited = /* @__PURE__ */ new Set();
+    const components = [];
+    for (const nodeName of this.nodes.keys()) {
+      if (visited.has(nodeName)) continue;
+      const island = [];
+      const queue = [nodeName];
+      visited.add(nodeName);
+      while (queue.length > 0) {
+        const current = queue.shift();
+        island.push(current);
+        const allEdges = [
+          ...this.outgoing.get(current) ?? [],
+          ...this.incoming.get(current) ?? []
+        ];
+        for (const edge of allEdges) {
+          const neighbor = edge.source === current ? edge.target : edge.source;
+          if (!visited.has(neighbor) && this.nodes.has(neighbor)) {
+            visited.add(neighbor);
+            queue.push(neighbor);
+          }
+        }
+      }
+      components.push(island.sort());
+    }
+    return components.sort((a, b) => b.length - a.length);
+  }
+  /** All components reachable within N hops (undirected) */
+  neighbors(component, maxHops = 1) {
+    const neighbors = [];
+    const visited = /* @__PURE__ */ new Set([component]);
+    const queue = [
+      { name: component, hops: 0 }
+    ];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current.hops >= maxHops) continue;
+      const allEdges = [
+        ...this.outgoing.get(current.name) ?? [],
+        ...this.incoming.get(current.name) ?? []
+      ];
+      for (const edge of allEdges) {
+        const neighbor = edge.source === current.name ? edge.target : edge.source;
+        if (visited.has(neighbor)) continue;
+        visited.add(neighbor);
+        neighbors.push({
+          component: neighbor,
+          hops: current.hops + 1,
+          edgeType: edge.type
+        });
+        queue.push({ name: neighbor, hops: current.hops + 1 });
+      }
+    }
+    return { component, neighbors };
+  }
+  // -------------------------------------------------------------------------
+  // Design-system queries
+  // -------------------------------------------------------------------------
+  /** Get the composition tree for a compound component */
+  composition(component) {
+    const node = this.nodes.get(component);
+    const subComponents = node?.subComponents ?? [];
+    const parentEdges = (this.outgoing.get(component) ?? []).filter((e) => e.type === "parent-of");
+    const requiredChildren = parentEdges.map((e) => e.target);
+    const childEdges = (this.incoming.get(component) ?? []).filter((e) => e.type === "parent-of");
+    const parent = childEdges.length > 0 ? childEdges[0].source : void 0;
+    const siblings = [];
+    if (parent) {
+      const parentOut = (this.outgoing.get(parent) ?? []).filter((e) => e.type === "parent-of");
+      for (const edge of parentOut) {
+        if (edge.target !== component) {
+          siblings.push(edge.target);
+        }
+      }
+    }
+    const siblingEdges = [
+      ...(this.outgoing.get(component) ?? []).filter((e) => e.type === "sibling-of"),
+      ...(this.incoming.get(component) ?? []).filter((e) => e.type === "sibling-of")
+    ];
+    for (const edge of siblingEdges) {
+      const sib = edge.source === component ? edge.target : edge.source;
+      if (!siblings.includes(sib)) siblings.push(sib);
+    }
+    return {
+      component,
+      compositionPattern: node?.compositionPattern,
+      subComponents,
+      requiredChildren,
+      parent,
+      siblings,
+      blocks: this.blockIndex.get(component) ?? []
+    };
+  }
+  /** Get alternative components */
+  alternatives(component) {
+    const alts = [];
+    for (const edge of this.outgoing.get(component) ?? []) {
+      if (edge.type === "alternative-to") {
+        alts.push({ component: edge.target, note: edge.note });
+      }
+    }
+    for (const edge of this.incoming.get(component) ?? []) {
+      if (edge.type === "alternative-to") {
+        alts.push({ component: edge.source, note: edge.note });
+      }
+    }
+    return alts;
+  }
+  /** Get blocks that use a component */
+  blocksUsing(component) {
+    return this.blockIndex.get(component) ?? [];
+  }
+  /** Extract an induced subgraph for a set of components */
+  subgraph(components) {
+    const componentSet = new Set(components);
+    const nodes = components.map((name) => this.nodes.get(name)).filter((n) => n !== void 0);
+    const edges = this.edges.filter(
+      (e) => componentSet.has(e.source) && componentSet.has(e.target)
+    );
+    return {
+      nodes,
+      edges,
+      health: computeHealthFromData(nodes, edges, this.blockIndex)
+    };
+  }
+  /** Return precomputed health metrics */
+  getHealth() {
+    return this.health;
+  }
+  /** Get a single node by name */
+  getNode(name) {
+    return this.nodes.get(name);
+  }
+  /** Check if a component exists in the graph */
+  hasNode(name) {
+    return this.nodes.has(name);
+  }
+};
+function computeHealthFromData(nodes, edges, blockIndex) {
+  const nodeNames = new Set(nodes.map((n) => n.name));
+  const degreeMap = /* @__PURE__ */ new Map();
+  for (const name of nodeNames) {
+    degreeMap.set(name, 0);
+  }
+  for (const edge of edges) {
+    degreeMap.set(edge.source, (degreeMap.get(edge.source) ?? 0) + 1);
+    degreeMap.set(edge.target, (degreeMap.get(edge.target) ?? 0) + 1);
+  }
+  const orphans = [];
+  for (const [name, degree] of degreeMap) {
+    if (degree === 0) orphans.push(name);
+  }
+  const hubs = [...degreeMap.entries()].map(([name, degree]) => ({ name, degree })).sort((a, b) => b.degree - a.degree).slice(0, 10);
+  let inBlock = 0;
+  if (blockIndex) {
+    for (const name of nodeNames) {
+      if ((blockIndex.get(name) ?? []).length > 0) inBlock++;
+    }
+  }
+  const compositionCoverage = nodeNames.size > 0 ? Math.round(inBlock / nodeNames.size * 100) : 0;
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const name of nodeNames) {
+    adjacency.set(name, /* @__PURE__ */ new Set());
+  }
+  for (const edge of edges) {
+    adjacency.get(edge.source)?.add(edge.target);
+    adjacency.get(edge.target)?.add(edge.source);
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const connectedComponents = [];
+  for (const name of nodeNames) {
+    if (visited.has(name)) continue;
+    const island = [];
+    const queue = [name];
+    visited.add(name);
+    while (queue.length > 0) {
+      const current = queue.shift();
+      island.push(current);
+      for (const neighbor of adjacency.get(current) ?? []) {
+        if (!visited.has(neighbor)) {
+          visited.add(neighbor);
+          queue.push(neighbor);
+        }
+      }
+    }
+    connectedComponents.push(island.sort());
+  }
+  connectedComponents.sort((a, b) => b.length - a.length);
+  const totalDegree = [...degreeMap.values()].reduce((sum, d) => sum + d, 0);
+  const averageDegree = nodeNames.size > 0 ? Math.round(totalDegree / nodeNames.size * 100) / 100 : 0;
+  return {
+    orphans: orphans.sort(),
+    hubs,
+    compositionCoverage,
+    connectedComponents,
+    averageDegree,
+    nodeCount: nodeNames.size,
+    edgeCount: edges.length
+  };
+}
+
+// src/graph/serialization.ts
+function serializeGraph(graph) {
+  return {
+    nodes: graph.nodes,
+    edges: graph.edges.map(serializeEdge),
+    health: graph.health
+  };
+}
+function deserializeGraph(serialized) {
+  return {
+    nodes: serialized.nodes,
+    edges: serialized.edges.map(deserializeEdge),
+    health: serialized.health
+  };
+}
+function serializeEdge(edge) {
+  const result = {
+    s: edge.source,
+    t: edge.target,
+    ty: edge.type,
+    w: edge.weight,
+    p: edge.provenance
+  };
+  if (edge.note) result.no = edge.note;
+  return result;
+}
+function deserializeEdge(edge) {
+  const result = {
+    source: edge.s,
+    target: edge.t,
+    type: edge.ty,
+    weight: edge.w,
+    provenance: edge.p
+  };
+  if (edge.no) result.note = edge.no;
+  return result;
+}
+export {
+  ComponentGraphEngine,
+  EDGE_TYPE_WEIGHTS,
+  GRAPH_EDGE_TYPES,
+  computeHealthFromData,
+  deserializeGraph,
+  serializeGraph
+};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { AIMetadata, CompiledBlock, CompiledSegment, CompiledSegmentsFile, CompiledTokenData, CompiledTokenEntry, ComponentRelation, PropDefinition, SegmentContract, SegmentGenerated, SegmentMeta, SegmentUsage, Theme, VerifyResult } from './types/index.js';
+export { AIMetadata, CompiledBlock, CompiledFragment, CompiledFragmentsFile, CompiledTokenData, CompiledTokenEntry, ComponentRelation, FragmentContract, FragmentGenerated, FragmentMeta, FragmentUsage, PropDefinition, Theme, VerifyResult } from './types/index.js';
 export { ContextOptions, ContextResult, PLACEHOLDER_PATTERNS, filterPlaceholders, generateContext } from './generate/index.js';
 export { ASTChunkerOptions, ChunkOptions, CodeChunk, chunkByAST, chunkByLines, chunkFile } from './chunking/index.js';
 export { EmbeddingOptions, EmbeddingResult, RerankOptions, RerankResult, generateEmbeddings, rerankResults } from './embeddings/voyage.js';
@@ -6,3 +6,6 @@ export { deduplicateChunks, reciprocalRankFusion } from './search/index.js';
 export { F as FusedResult, R as RankedResult, a as ScoredChunk, S as SearchResult } from './types-B7duBj6U.js';
 export { AST_SUPPORTED_LANGUAGES, ChangedFiles, FileEntry, GrammarMapping, INDEXABLE_EXTENSIONS, detectLanguage, getTreeSitterGrammar, hashContent, resolveChanges, shouldIndexFile } from './indexing/index.js';
 export { ChunkMapping, CitationDocumentBlock, CitationDocumentOptions, DocumentMapping, RawCitation, ResolvedCitation, buildCitationDocuments, resolveCitation, resolveCitations } from './citations/index.js';
+export { CLI_TOOL_EXTENSIONS, CliToolExtension, MCP_TOOL_DEFINITIONS, McpToolDefinition, McpToolParam, buildMcpTools, buildToolNames } from './mcp-tools/index.js';
+export { CLI_COMMANDS, CLI_COMMAND_CATEGORIES, CliCategoryInfo, CliCommandCategory, CliCommandDef, CliOptionDef } from './cli-commands/index.js';
+import './types-DOhSojcf.js';

package/dist/index.js

@@ -1,3 +1,13 @@
+import {
+  CLI_TOOL_EXTENSIONS,
+  MCP_TOOL_DEFINITIONS,
+  buildMcpTools,
+  buildToolNames
+} from "./chunk-HAJWPNLU.js";
+import {
+  CLI_COMMANDS,
+  CLI_COMMAND_CATEGORIES
+} from "./chunk-IQMVRBVF.js";
 import {
   chunkByAST,
   chunkByLines,
@@ -10,7 +20,7 @@ import {
 import {
   deduplicateChunks,
   reciprocalRankFusion
-} from "./chunk-ZMBYQK43.js";
+} from "./chunk-F3ZH5BUA.js";
 import {
   hashContent,
   resolveChanges
@@ -26,7 +36,7 @@ import {
   PLACEHOLDER_PATTERNS,
   filterPlaceholders,
   generateContext
-} from "./chunk-KKABP4K4.js";
+} from "./chunk-2UQY4VNM.js";
 import {
   buildCitationDocuments,
   resolveCitation,
@@ -34,9 +44,15 @@ import {
 } from "./chunk-3FEHRHFQ.js";
 export {
   AST_SUPPORTED_LANGUAGES,
+  CLI_COMMANDS,
+  CLI_COMMAND_CATEGORIES,
+  CLI_TOOL_EXTENSIONS,
   INDEXABLE_EXTENSIONS,
+  MCP_TOOL_DEFINITIONS,
   PLACEHOLDER_PATTERNS,
   buildCitationDocuments,
+  buildMcpTools,
+  buildToolNames,
   chunkByAST,
   chunkByLines,
   chunkFile,

package/dist/mcp-tools/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared MCP tool definitions for Fragments.
+ *
+ * Both @fragments-sdk/mcp (standalone) and @fragments-sdk/cli (full-featured)
+ * import from here, eliminating duplication of tool names, descriptions, and
+ * input schemas.
+ */
+interface McpToolParam {
+    type: string;
+    description: string;
+    enum?: string[];
+    items?: {
+        type: string;
+    };
+    properties?: Record<string, McpToolParam>;
+}
+interface McpToolDefinition {
+    /** Short key used to build the prefixed tool name, e.g. "discover" */
+    key: string;
+    description: string;
+    params: Record<string, McpToolParam>;
+    required?: string[];
+}
+/** Extra params only present in the CLI server (Playwright-backed) */
+interface CliToolExtension {
+    key: string;
+    /** Additional params merged into the base tool's inputSchema.properties */
+    params: Record<string, McpToolParam>;
+    /** Override the description (e.g. CLI render mentions baseline) */
+    description?: string;
+}
+declare const MCP_TOOL_DEFINITIONS: McpToolDefinition[];
+declare const CLI_TOOL_EXTENSIONS: CliToolExtension[];
+interface McpSdkTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Build a TOOL_NAMES map: `{ discover: "prefix_discover", ... }`
+ */
+declare function buildToolNames(prefix: string): Record<string, string>;
+/**
+ * Build MCP SDK `Tool[]` from shared definitions, optionally merging CLI
+ * extensions.
+ */
+declare function buildMcpTools(prefix: string, extensions?: CliToolExtension[]): McpSdkTool[];
+
+export { CLI_TOOL_EXTENSIONS, type CliToolExtension, MCP_TOOL_DEFINITIONS, type McpToolDefinition, type McpToolParam, buildMcpTools, buildToolNames };

package/dist/mcp-tools/index.js

@@ -0,0 +1,12 @@
+import {
+  CLI_TOOL_EXTENSIONS,
+  MCP_TOOL_DEFINITIONS,
+  buildMcpTools,
+  buildToolNames
+} from "../chunk-HAJWPNLU.js";
+export {
+  CLI_TOOL_EXTENSIONS,
+  MCP_TOOL_DEFINITIONS,
+  buildMcpTools,
+  buildToolNames
+};

package/dist/search/index.js

@@ -1,7 +1,7 @@
 import {
   deduplicateChunks,
   reciprocalRankFusion
-} from "../chunk-ZMBYQK43.js";
+} from "../chunk-F3ZH5BUA.js";
 export {
   deduplicateChunks,
   reciprocalRankFusion

package/dist/types/index.d.ts

@@ -1,3 +1,5 @@
+import { S as SerializedComponentGraph } from '../types-DOhSojcf.js';
+
 /**
  * Compiled fragment types — shared between CLI and MCP packages.
  *
@@ -7,7 +9,7 @@
 /**
  * Component metadata
  */
-interface SegmentMeta {
+interface FragmentMeta {
     name: string;
     description: string;
     category: string;
@@ -20,7 +22,7 @@ interface SegmentMeta {
 /**
  * Usage guidelines for AI agents and developers
  */
-interface SegmentUsage {
+interface FragmentUsage {
     when: string[];
     whenNot: string[];
     guidelines?: string[];
@@ -56,7 +58,7 @@ interface ComponentRelation {
 /**
  * Agent-optimized contract metadata
  */
-interface SegmentContract {
+interface FragmentContract {
     propsSummary?: string[];
     a11yRules?: string[];
     bans?: Array<{
@@ -66,9 +68,9 @@ interface SegmentContract {
     scenarioTags?: string[];
 }
 /**
- * Provenance tracking for generated segments
+ * Provenance tracking for generated fragments
  */
-interface SegmentGenerated {
+interface FragmentGenerated {
     source: "storybook" | "manual" | "ai";
     sourceFile?: string;
     confidence?: number;
@@ -84,12 +86,12 @@ interface AIMetadata {
     commonPatterns?: string[];
 }
 /**
- * Compiled segment data (JSON-serializable for AI consumption)
+ * Compiled fragment data (JSON-serializable for AI consumption)
  */
-interface CompiledSegment {
+interface CompiledFragment {
     filePath: string;
-    meta: SegmentMeta;
-    usage: SegmentUsage;
+    meta: FragmentMeta;
+    usage: FragmentUsage;
     props: Record<string, PropDefinition>;
     relations?: ComponentRelation[];
     variants: Array<{
@@ -99,9 +101,9 @@ interface CompiledSegment {
         figma?: string;
         args?: Record<string, unknown>;
     }>;
-    contract?: SegmentContract;
+    contract?: FragmentContract;
     ai?: AIMetadata;
-    _generated?: SegmentGenerated;
+    _generated?: FragmentGenerated;
 }
 /**
  * Compiled block data (JSON-serializable for AI consumption)
@@ -133,13 +135,15 @@ interface CompiledTokenData {
 /**
  * The compiled fragments.json structure
  */
-interface CompiledSegmentsFile {
+interface CompiledFragmentsFile {
     version: string;
     generatedAt: string;
     packageName?: string;
-    segments: Record<string, CompiledSegment>;
+    fragments: Record<string, CompiledFragment>;
     blocks?: Record<string, CompiledBlock>;
     tokens?: CompiledTokenData;
+    /** Component relationship graph for AI structural queries */
+    graph?: SerializedComponentGraph;
     /** @deprecated Use blocks instead */
     recipes?: Record<string, CompiledBlock>;
 }
@@ -167,4 +171,4 @@ interface VerifyResult {
     };
 }
 
-export type { AIMetadata, CompiledBlock, CompiledSegment, CompiledSegmentsFile, CompiledTokenData, CompiledTokenEntry, ComponentRelation, PropDefinition, SegmentContract, SegmentGenerated, SegmentMeta, SegmentUsage, Theme, VerifyResult };
+export type { AIMetadata, CompiledBlock, CompiledFragment, CompiledFragmentsFile, CompiledTokenData, CompiledTokenEntry, ComponentRelation, FragmentContract, FragmentGenerated, FragmentMeta, FragmentUsage, PropDefinition, Theme, VerifyResult };