@usefragments/core 1.0.0

package/src/graph/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Component Graph Intelligence Layer — barrel exports.
+ */
+
+export type {
+  GraphEdgeType,
+  ComponentNode,
+  GraphEdge,
+  GraphHealth,
+  ComponentGraph,
+  ImpactResult,
+  PathResult,
+  NeighborResult,
+  CompositionTree,
+  SerializedEdge,
+  SerializedComponentGraph,
+} from './types.js';
+
+export {
+  GRAPH_EDGE_TYPES,
+  EDGE_TYPE_WEIGHTS,
+} from './types.js';
+
+export {
+  ComponentGraphEngine,
+  computeHealthFromData,
+} from './engine.js';
+
+export {
+  serializeGraph,
+  deserializeGraph,
+} from './serialization.js';

package/src/graph/serialization.ts

@@ -0,0 +1,55 @@
+/**
+ * Graph serialization — compact JSON format for fragments.json embedding.
+ *
+ * Edges use short keys (s, t, ty, w, no, p) to reduce JSON size.
+ * Round-trips through serialize → deserialize preserve all data.
+ */
+
+import type {
+  ComponentGraph,
+  GraphEdge,
+  SerializedComponentGraph,
+  SerializedEdge,
+} from './types.js';
+
+/** Serialize a ComponentGraph to compact JSON format */
+export function serializeGraph(graph: ComponentGraph): SerializedComponentGraph {
+  return {
+    nodes: graph.nodes,
+    edges: graph.edges.map(serializeEdge),
+    health: graph.health,
+  };
+}
+
+/** Deserialize a compact JSON graph back to full ComponentGraph */
+export function deserializeGraph(serialized: SerializedComponentGraph): ComponentGraph {
+  return {
+    nodes: serialized.nodes,
+    edges: serialized.edges.map(deserializeEdge),
+    health: serialized.health,
+  };
+}
+
+function serializeEdge(edge: GraphEdge): SerializedEdge {
+  const result: SerializedEdge = {
+    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: SerializedEdge): GraphEdge {
+  const result: GraphEdge = {
+    source: edge.s,
+    target: edge.t,
+    type: edge.ty,
+    weight: edge.w,
+    provenance: edge.p,
+  };
+  if (edge.no) result.note = edge.no;
+  return result;
+}

package/src/graph/types.ts

@@ -0,0 +1,178 @@
+/**
+ * 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.
+ */
+
+// ---------------------------------------------------------------------------
+// Edge types — design-system-semantic
+// ---------------------------------------------------------------------------
+
+export type GraphEdgeType =
+  | 'imports'           // A imports B in source code
+  | 'hook-depends'      // A calls useB() from B
+  | 'renders'           // A renders <B> in examples
+  | 'composes'          // A and B co-occur in a block
+  | 'parent-of'         // A should wrap B
+  | 'alternative-to'    // A can replace B
+  | 'sibling-of';       // A and B at same level
+
+export const GRAPH_EDGE_TYPES: readonly GraphEdgeType[] = [
+  'imports',
+  'hook-depends',
+  'renders',
+  'composes',
+  'parent-of',
+  'alternative-to',
+  'sibling-of',
+];
+
+/** Default weight for each edge type */
+export const EDGE_TYPE_WEIGHTS: Record<GraphEdgeType, number> = {
+  'imports': 1.0,
+  'hook-depends': 0.75,
+  'renders': 0.5,
+  'composes': 0.5,
+  'parent-of': 1.0,
+  'alternative-to': 1.0,
+  'sibling-of': 0.75,
+};
+
+// ---------------------------------------------------------------------------
+// Nodes
+// ---------------------------------------------------------------------------
+
+export interface ComponentNode {
+  name: string;
+  category: string;
+  status: string;
+  compositionPattern?: 'compound' | 'simple' | 'controlled' | 'wrapper';
+  subComponents?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Edges
+// ---------------------------------------------------------------------------
+
+export interface GraphEdge {
+  source: string;
+  target: string;
+  type: GraphEdgeType;
+  weight: number;
+  note?: string;
+  /** Where this edge was detected from */
+  provenance: string;
+}
+
+// ---------------------------------------------------------------------------
+// Health metrics
+// ---------------------------------------------------------------------------
+
+export 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;
+}
+
+// ---------------------------------------------------------------------------
+// Full graph
+// ---------------------------------------------------------------------------
+
+export interface ComponentGraph {
+  nodes: ComponentNode[];
+  edges: GraphEdge[];
+  health: GraphHealth;
+}
+
+// ---------------------------------------------------------------------------
+// Query results
+// ---------------------------------------------------------------------------
+
+export 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;
+}
+
+export 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[];
+}
+
+export interface NeighborResult {
+  /** The center component */
+  component: string;
+  /** All components reachable within maxHops */
+  neighbors: Array<{
+    component: string;
+    hops: number;
+    edgeType: GraphEdgeType;
+  }>;
+}
+
+export interface CompositionTree {
+  /** The root component */
+  component: string;
+  /** Composition pattern */
+  compositionPattern?: 'compound' | 'simple' | 'controlled' | 'wrapper';
+  /** Direct sub-components */
+  subComponents: string[];
+  /** Components that declare this component as their parent */
+  children: 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[];
+}
+
+// ---------------------------------------------------------------------------
+// Serialization (compact keys for JSON size)
+// ---------------------------------------------------------------------------
+
+export interface SerializedEdge {
+  /** source */
+  s: string;
+  /** target */
+  t: string;
+  /** type */
+  ty: GraphEdgeType;
+  /** weight */
+  w: number;
+  /** note (optional) */
+  no?: string;
+  /** provenance */
+  p: string;
+}
+
+export interface SerializedComponentGraph {
+  nodes: ComponentNode[];
+  edges: SerializedEdge[];
+  health: GraphHealth;
+}