@fragments-sdk/context 0.2.0 → 0.3.0

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

@@ -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-U4V5NX67.js";
 import {
   chunkByAST,
   chunkByLines,
@@ -10,7 +20,7 @@ import {
 import {
   deduplicateChunks,
   reciprocalRankFusion
-} from "./chunk-ZMBYQK43.js";
+} from "./chunk-F3ZH5BUA.js";
 import {
   hashContent,
   resolveChanges
@@ -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.
  *
@@ -140,6 +142,8 @@ interface CompiledSegmentsFile {
     segments: Record<string, CompiledSegment>;
     blocks?: Record<string, CompiledBlock>;
     tokens?: CompiledTokenData;
+    /** Component relationship graph for AI structural queries */
+    graph?: SerializedComponentGraph;
     /** @deprecated Use blocks instead */
     recipes?: Record<string, CompiledBlock>;
 }

package/dist/types-DOhSojcf.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Component Graph data model — types for the design-system-semantic relationship graph.
+ *
+ * These types describe nodes (components), edges (relationships), and health
+ * metrics that together give AI agents structural understanding of a design system.
+ */
+type GraphEdgeType = 'imports' | 'hook-depends' | 'renders' | 'composes' | 'parent-of' | 'alternative-to' | 'sibling-of';
+declare const GRAPH_EDGE_TYPES: readonly GraphEdgeType[];
+/** Default weight for each edge type */
+declare const EDGE_TYPE_WEIGHTS: Record<GraphEdgeType, number>;
+interface ComponentNode {
+    name: string;
+    category: string;
+    status: string;
+    compositionPattern?: 'compound' | 'simple' | 'controlled';
+    subComponents?: string[];
+}
+interface GraphEdge {
+    source: string;
+    target: string;
+    type: GraphEdgeType;
+    weight: number;
+    note?: string;
+    /** Where this edge was detected from */
+    provenance: string;
+}
+interface GraphHealth {
+    /** Components with zero edges */
+    orphans: string[];
+    /** Top components by total degree (in + out) */
+    hubs: Array<{
+        name: string;
+        degree: number;
+    }>;
+    /** Percentage of components appearing in at least one block */
+    compositionCoverage: number;
+    /** Disconnected groups (BFS on undirected projection) */
+    connectedComponents: string[][];
+    /** Average degree across all nodes */
+    averageDegree: number;
+    /** Total node and edge counts */
+    nodeCount: number;
+    edgeCount: number;
+}
+interface ComponentGraph {
+    nodes: ComponentNode[];
+    edges: GraphEdge[];
+    health: GraphHealth;
+}
+interface ImpactResult {
+    /** The component that was changed */
+    component: string;
+    /** Components affected at each depth level */
+    affected: Array<{
+        component: string;
+        depth: number;
+        path: string[];
+        edgeType: GraphEdgeType;
+    }>;
+    /** Blocks that use the changed component or any affected component */
+    affectedBlocks: string[];
+    /** Total count of affected components */
+    totalAffected: number;
+}
+interface PathResult {
+    /** Whether a path exists */
+    found: boolean;
+    /** Nodes along the shortest path (including source and target) */
+    path: string[];
+    /** Edges along the shortest path */
+    edges: GraphEdge[];
+}
+interface NeighborResult {
+    /** The center component */
+    component: string;
+    /** All components reachable within maxHops */
+    neighbors: Array<{
+        component: string;
+        hops: number;
+        edgeType: GraphEdgeType;
+    }>;
+}
+interface CompositionTree {
+    /** The root component */
+    component: string;
+    /** Composition pattern */
+    compositionPattern?: 'compound' | 'simple' | 'controlled';
+    /** Direct sub-components */
+    subComponents: string[];
+    /** Sub-components that must be present */
+    requiredChildren: string[];
+    /** Parent component (if this is a sub-component) */
+    parent?: string;
+    /** Sibling components at the same level */
+    siblings: string[];
+    /** Blocks that use this component */
+    blocks: string[];
+}
+interface SerializedEdge {
+    /** source */
+    s: string;
+    /** target */
+    t: string;
+    /** type */
+    ty: GraphEdgeType;
+    /** weight */
+    w: number;
+    /** note (optional) */
+    no?: string;
+    /** provenance */
+    p: string;
+}
+interface SerializedComponentGraph {
+    nodes: ComponentNode[];
+    edges: SerializedEdge[];
+    health: GraphHealth;
+}
+
+export { type ComponentGraph as C, EDGE_TYPE_WEIGHTS as E, type GraphEdgeType as G, type ImpactResult as I, type NeighborResult as N, type PathResult as P, type SerializedComponentGraph as S, type GraphEdge as a, type CompositionTree as b, type GraphHealth as c, type ComponentNode as d, type SerializedEdge as e, GRAPH_EDGE_TYPES as f };

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@fragments-sdk/context",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Code intelligence and RAG primitives for design system and codebase indexing",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ConanMcN/fragments"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -38,6 +42,18 @@
     "./citations": {
       "types": "./dist/citations/index.d.ts",
       "import": "./dist/citations/index.js"
+    },
+    "./mcp-tools": {
+      "types": "./dist/mcp-tools/index.d.ts",
+      "import": "./dist/mcp-tools/index.js"
+    },
+    "./cli-commands": {
+      "types": "./dist/cli-commands/index.d.ts",
+      "import": "./dist/cli-commands/index.js"
+    },
+    "./graph": {
+      "types": "./dist/graph/index.d.ts",
+      "import": "./dist/graph/index.js"
     }
   },
   "publishConfig": {