@fragments-sdk/context 0.1.4 → 0.3.0

package/dist/chunk-U4V5NX67.js

@@ -0,0 +1,447 @@
+// src/cli-commands/index.ts
+var CLI_COMMAND_CATEGORIES = {
+  setup: {
+    label: "Setup",
+    description: "Initialize and scaffold your design system project."
+  },
+  build: {
+    label: "Build & Compile",
+    description: "Compile fragment files into machine-readable output."
+  },
+  dev: {
+    label: "Development",
+    description: "Development server and live preview tools."
+  },
+  quality: {
+    label: "Quality & Compliance",
+    description: "Validate, audit, and verify design system compliance."
+  },
+  visual: {
+    label: "Visual Testing",
+    description: "Screenshot capture, diff, and visual regression testing."
+  },
+  ai: {
+    label: "AI & Context",
+    description: "Generate AI-ready context and enhance documentation."
+  },
+  integration: {
+    label: "Integrations",
+    description: "Link Figma designs, Storybook stories, and external tools."
+  },
+  utility: {
+    label: "Utilities",
+    description: "Miscellaneous helpers and viewers."
+  }
+};
+var CLI_COMMANDS = [
+  // ── Setup ──
+  {
+    name: "init",
+    description: "Initialize fragments in a project (interactive by default)",
+    category: "setup",
+    usage: "fragments init [--yes] [--force]",
+    options: [
+      { flags: "--force", description: "Overwrite existing config" },
+      { flags: "-y, --yes", description: "Non-interactive mode \u2014 auto-detect and use defaults" }
+    ]
+  },
+  {
+    name: "add",
+    description: "Scaffold a new component with fragment file",
+    category: "setup",
+    usage: "fragments add [name] [options]",
+    argument: "[name]",
+    argumentDescription: 'Component name (e.g., "Button", "TextField")',
+    options: [
+      { flags: "-c, --category <category>", description: "Component category" },
+      { flags: "-d, --dir <directory>", description: "Output directory" },
+      { flags: "-t, --template <template>", description: "Template to use (action, form-input, layout, display)" },
+      { flags: "--no-component", description: "Only generate fragment file, skip component stub" }
+    ]
+  },
+  // ── Build ──
+  {
+    name: "build",
+    description: "Build compiled fragments.json and .fragments/ directory",
+    category: "build",
+    usage: "fragments build [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "-o, --output <path>", description: "Output file path" },
+      { flags: "--registry", description: "Also generate .fragments/registry.json and context.md" },
+      { flags: "--registry-only", description: "Only generate .fragments/ directory (skip fragments.json)" },
+      { flags: "--from-source", description: "Build from source code (zero-config, no fragment files needed)" },
+      { flags: "--skip-usage", description: "Skip usage analysis when building from source" },
+      { flags: "--skip-storybook", description: "Skip Storybook parsing when building from source" },
+      { flags: "-v, --verbose", description: "Verbose output" }
+    ]
+  },
+  {
+    name: "scan",
+    description: "Zero-config fragments.json generation from source code",
+    category: "build",
+    usage: "fragments scan [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "-o, --output <path>", description: "Output file path", default: "fragments.json" },
+      { flags: "--patterns <patterns...>", description: "Component file patterns to scan" },
+      { flags: "--barrel <files...>", description: "Barrel export files to parse" },
+      { flags: "--usage-dir <dir>", description: "Directory to scan for usage patterns" },
+      { flags: "--skip-usage", description: "Skip usage pattern analysis" },
+      { flags: "--skip-storybook", description: "Skip Storybook story parsing" },
+      { flags: "-v, --verbose", description: "Verbose output" }
+    ]
+  },
+  {
+    name: "generate",
+    description: "Generate fragment files from component source code",
+    category: "build",
+    usage: "fragments generate [component] [options]",
+    argument: "[component]",
+    argumentDescription: "Specific component name to generate (optional)",
+    options: [
+      { flags: "--force", description: "Overwrite existing fragment files" },
+      { flags: "--pattern <glob>", description: "Pattern for component files", default: "src/components/**/*.tsx" }
+    ]
+  },
+  {
+    name: "validate",
+    description: "Validate fragment files",
+    category: "build",
+    usage: "fragments validate [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--schema", description: "Validate fragment schema only" },
+      { flags: "--coverage", description: "Validate coverage only" }
+    ]
+  },
+  // ── Dev ──
+  {
+    name: "dev",
+    description: "Start the development server with live component rendering",
+    category: "dev",
+    usage: "fragments dev [options]",
+    options: [
+      { flags: "-p, --port <port>", description: "Port to run on", default: "6006" },
+      { flags: "--no-open", description: "Do not open browser" },
+      { flags: "--skip-setup", description: "Skip auto-setup (Storybook import, build, Figma link)" },
+      { flags: "--skip-storybook", description: "Skip auto-importing from Storybook" },
+      { flags: "--skip-figma", description: "Skip Figma link check" },
+      { flags: "--skip-build", description: "Skip auto-building fragments.json" }
+    ]
+  },
+  {
+    name: "list",
+    description: "List all discovered fragment files",
+    category: "dev",
+    usage: "fragments list [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" }
+    ]
+  },
+  {
+    name: "tokens",
+    description: "Discover and list design tokens from CSS/SCSS files",
+    category: "dev",
+    usage: "fragments tokens [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--json", description: "Output as JSON" },
+      { flags: "--categories", description: "Group tokens by category" },
+      { flags: "--theme <theme>", description: "Filter by theme name" },
+      { flags: "--category <category>", description: "Filter by category (color, spacing, typography, etc.)" },
+      { flags: "--verbose", description: "Show all tokens (no truncation)" }
+    ]
+  },
+  // ── Quality ──
+  {
+    name: "verify",
+    description: "Verify component compliance for CI pipelines",
+    category: "quality",
+    usage: "fragments verify [component] [options]",
+    argument: "[component]",
+    argumentDescription: "Component name to verify (optional, verifies all if omitted)",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--ci", description: "CI mode \u2014 output JSON and exit non-zero on failure" },
+      { flags: "--min-compliance <percent>", description: "Minimum compliance percentage", default: "80" },
+      { flags: "-p, --port <port>", description: "Dev server port", default: "6006" }
+    ]
+  },
+  {
+    name: "audit",
+    description: "Scan all fragments and show compliance metrics across the design system",
+    category: "quality",
+    usage: "fragments audit [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--json", description: "Output machine-readable JSON format" },
+      { flags: "--sort <field>", description: "Sort by field: compliance, name, hardcoded", default: "compliance" },
+      { flags: "-p, --port <port>", description: "Dev server port", default: "6006" }
+    ]
+  },
+  {
+    name: "a11y",
+    description: "Run accessibility checks on all component variants",
+    category: "quality",
+    usage: "fragments a11y [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--json", description: "Output results as JSON" },
+      { flags: "--ci", description: "CI mode (exit code 1 if any critical/serious violations)" },
+      { flags: "--component <name>", description: "Check specific component only" },
+      { flags: "-p, --port <port>", description: "Dev server port", default: "6006" }
+    ]
+  },
+  {
+    name: "test",
+    description: "Run interaction tests for fragments with play functions",
+    category: "quality",
+    usage: "fragments test [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--component <name>", description: "Filter by component name" },
+      { flags: "--tags <tags>", description: "Filter by tags (comma-separated)" },
+      { flags: "--grep <pattern>", description: "Filter by variant name pattern" },
+      { flags: "--exclude <pattern>", description: "Exclude tests matching pattern" },
+      { flags: "--parallel <count>", description: "Number of parallel browser contexts", default: "4" },
+      { flags: "--timeout <ms>", description: "Timeout per test in milliseconds", default: "30000" },
+      { flags: "--retries <count>", description: "Number of retries for failed tests", default: "0" },
+      { flags: "--bail", description: "Stop on first failure" },
+      { flags: "--browser <name>", description: "Browser to use (chromium, firefox, webkit)", default: "chromium" },
+      { flags: "--headed", description: "Run in headed mode (show browser)" },
+      { flags: "--a11y", description: "Run accessibility checks with axe-core" },
+      { flags: "--visual", description: "Capture screenshots for visual regression" },
+      { flags: "--update-snapshots", description: "Update visual snapshots" },
+      { flags: "--watch", description: "Watch mode \u2014 re-run on file changes" },
+      { flags: "--reporters <names>", description: "Reporters to use (console, junit, json)", default: "console" },
+      { flags: "-o, --output <dir>", description: "Output directory for results", default: "./test-results" },
+      { flags: "--server-url <url>", description: "URL of running dev server (skips starting server)" },
+      { flags: "-p, --port <port>", description: "Port for dev server", default: "6006" },
+      { flags: "--ci", description: "CI mode \u2014 non-interactive, exit with code 1 on failure" },
+      { flags: "--list", description: "List available tests without running them" }
+    ]
+  },
+  // ── Visual ──
+  {
+    name: "screenshot",
+    description: "Capture screenshots of component variants",
+    category: "visual",
+    usage: "fragments screenshot [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--component <name>", description: "Capture specific component only" },
+      { flags: "--variant <name>", description: "Capture specific variant only" },
+      { flags: "--theme <theme>", description: "Theme to capture (light/dark)", default: "light" },
+      { flags: "--update", description: "Update existing baselines" },
+      { flags: "--width <pixels>", description: "Viewport width" },
+      { flags: "--height <pixels>", description: "Viewport height" },
+      { flags: "--ci", description: "CI mode \u2014 no interactive prompts" }
+    ]
+  },
+  {
+    name: "diff",
+    description: "Compare current renders against baselines",
+    category: "visual",
+    usage: "fragments diff [component] [options]",
+    argument: "[component]",
+    argumentDescription: "Component name to diff (optional)",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--variant <name>", description: "Compare specific variant only" },
+      { flags: "--theme <theme>", description: "Theme to compare (light/dark)", default: "light" },
+      { flags: "--threshold <percent>", description: "Diff threshold percentage" },
+      { flags: "--ci", description: "CI mode \u2014 exit 1 on differences" },
+      { flags: "--open", description: "Open diff images" }
+    ]
+  },
+  {
+    name: "compare",
+    description: "Compare component renders against Figma designs",
+    category: "visual",
+    usage: "fragments compare [component] [options]",
+    argument: "[component]",
+    argumentDescription: "Component name to compare",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--variant <name>", description: "Compare specific variant" },
+      { flags: "--figma <url>", description: "Figma frame URL (uses fragment figma link if not provided)" },
+      { flags: "--threshold <percent>", description: "Diff threshold percentage", default: "1.0" },
+      { flags: "--all", description: "Compare all components with Figma links" },
+      { flags: "--output <dir>", description: "Save diff images to directory" },
+      { flags: "-p, --port <port>", description: "Dev server port", default: "6006" }
+    ]
+  },
+  {
+    name: "baseline",
+    description: "Manage visual regression baselines",
+    category: "visual",
+    usage: "fragments baseline <action> [component] [options]",
+    argument: "<action>",
+    argumentDescription: "Action to perform: update, list, delete",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--variant <name>", description: "Specific variant to update" },
+      { flags: "--all", description: "Update/delete all baselines" },
+      { flags: "--theme <theme>", description: "Theme for baseline (light/dark)", default: "light" },
+      { flags: "-p, --port <port>", description: "Dev server port", default: "6006" }
+    ]
+  },
+  {
+    name: "metrics",
+    description: "View compliance trends over time",
+    category: "visual",
+    usage: "fragments metrics [component] [options]",
+    argument: "[component]",
+    argumentDescription: "Component name (optional, shows system-wide if omitted)",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--days <number>", description: "Number of days to look back", default: "30" },
+      { flags: "--json", description: "Output JSON format" }
+    ]
+  },
+  // ── Graph ──
+  {
+    name: "graph",
+    description: "Query the component relationship graph for dependencies, impact analysis, and composition trees",
+    category: "ai",
+    usage: "fragments graph [component] [options]",
+    argument: "[component]",
+    argumentDescription: "Component name (optional, shows health dashboard if omitted)",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "-m, --mode <mode>", description: "Query mode: health, dependencies, dependents, impact, path, composition, alternatives, islands" },
+      { flags: "-t, --target <component>", description: "Target component for path mode" },
+      { flags: "--edge-types <types>", description: "Comma-separated edge types to filter by" },
+      { flags: "--depth <number>", description: "Max traversal depth for impact mode", default: "3" },
+      { flags: "--format <format>", description: "Output format: table, json, dot", default: "table" }
+    ]
+  },
+  // ── AI ──
+  {
+    name: "context",
+    description: "Generate AI-ready context for your design system",
+    category: "ai",
+    usage: "fragments context [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "-i, --input <path>", description: "Path to fragments.json (builds if not provided)" },
+      { flags: "-f, --format <format>", description: "Output format (markdown/json)", default: "markdown" },
+      { flags: "--compact", description: "Minimal output for token efficiency" },
+      { flags: "--code", description: "Include code examples" },
+      { flags: "--relations", description: "Include component relationships" },
+      { flags: "--tokens", description: "Only output token estimate" }
+    ]
+  },
+  {
+    name: "ai",
+    description: "Generate context optimized for AI assistants (Claude Desktop)",
+    category: "ai",
+    usage: "fragments ai [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--live", description: "Connect to running dev server for live data" },
+      { flags: "-p, --port <port>", description: "Dev server port", default: "6006" }
+    ]
+  },
+  {
+    name: "enhance",
+    description: "AI-powered documentation generation from codebase analysis",
+    category: "ai",
+    usage: "fragments enhance [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--component <name>", description: 'Enhance specific component (or "all")' },
+      { flags: "--yes", description: "Skip confirmation prompts" },
+      { flags: "--dry-run", description: "Only analyze, do not modify files" },
+      { flags: "--format <format>", description: "Output format: interactive, json, quiet, context", default: "interactive" },
+      { flags: "--provider <provider>", description: "AI provider: anthropic, openai (auto-detected from API key)" },
+      { flags: "--api-key <key>", description: "API key (or use ANTHROPIC_API_KEY/OPENAI_API_KEY env)" },
+      { flags: "--model <model>", description: "AI model to use" },
+      { flags: "--root <dir>", description: "Root directory to scan", default: "cwd" },
+      { flags: "--context-only", description: "Output context for IDE AI without calling API" }
+    ]
+  },
+  // ── Integration ──
+  {
+    name: "link figma",
+    description: "Interactive wizard to link Figma components to code",
+    category: "integration",
+    usage: "fragments link figma [figma-url] [options]",
+    argument: "[figma-url]",
+    argumentDescription: "Figma file URL to link components from",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "--auto", description: "Auto-link matching components without prompts" },
+      { flags: "--dry-run", description: "Show matches without updating files" },
+      { flags: "--no-variants", description: "Skip linking individual variants to their Figma frames" }
+    ]
+  },
+  {
+    name: "link storybook",
+    description: "Bootstrap fragments from existing Storybook stories",
+    category: "integration",
+    usage: "fragments link storybook [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to .storybook/main.* config" },
+      { flags: "-o, --out <dir>", description: "Output directory for fragment files" },
+      { flags: "--yes", description: "Skip confirmation prompts" },
+      { flags: "--dry-run", description: "Preview what would be generated without writing files" },
+      { flags: "--include <glob>", description: "Only process stories matching glob" },
+      { flags: "--exclude <glob>", description: "Skip stories matching glob" }
+    ]
+  },
+  {
+    name: "storygen",
+    description: "Generate Storybook stories from fragment definitions",
+    category: "integration",
+    usage: "fragments storygen [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "-o, --output <dir>", description: "Output directory", default: ".storybook/generated" },
+      { flags: "--watch", description: "Watch for segment changes and regenerate" },
+      { flags: "--format <format>", description: "Story format (csf3)", default: "csf3" }
+    ]
+  },
+  // ── Utility ──
+  {
+    name: "view",
+    description: "Generate a static HTML viewer for fragments.json",
+    category: "utility",
+    usage: "fragments view [options]",
+    options: [
+      { flags: "-i, --input <path>", description: "Path to fragments.json", default: "fragments.json" },
+      { flags: "-o, --output <path>", description: "Output HTML file path", default: "fragments-viewer.html" },
+      { flags: "--open", description: "Open in browser after generation" }
+    ]
+  },
+  {
+    name: "analyze",
+    description: "Analyze design system and generate report",
+    category: "utility",
+    usage: "fragments analyze [options]",
+    options: [
+      { flags: "-c, --config <path>", description: "Path to config file" },
+      { flags: "-f, --format <format>", description: "Output format (html/json/console)", default: "html" },
+      { flags: "-o, --output <path>", description: "Output file path" },
+      { flags: "--open", description: "Open report in browser after generation" },
+      { flags: "--ci", description: "CI mode \u2014 exit with code based on score" },
+      { flags: "--min-score <score>", description: "Minimum score to pass in CI mode" }
+    ]
+  },
+  {
+    name: "reset",
+    description: "Reset to initial state (delete all generated files)",
+    category: "utility",
+    usage: "fragments reset [options]",
+    options: [
+      { flags: "-y, --yes", description: "Skip confirmation prompt" },
+      { flags: "--dry-run", description: "Show what would be deleted without deleting" }
+    ]
+  }
+];
+
+export {
+  CLI_COMMAND_CATEGORIES,
+  CLI_COMMANDS
+};

package/dist/cli-commands/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CLI command metadata — single source of truth for bin.ts and docs.
+ *
+ * This file defines all CLI commands declaratively. bin.ts consumes the
+ * descriptions, and the docs site imports the full metadata to render the
+ * CLI reference page.
+ */
+interface CliOptionDef {
+    flags: string;
+    description: string;
+    default?: string;
+}
+interface CliCommandDef {
+    name: string;
+    description: string;
+    category: CliCommandCategory;
+    usage: string;
+    options: CliOptionDef[];
+    /** Optional positional argument (e.g., "[component]") */
+    argument?: string;
+    argumentDescription?: string;
+}
+type CliCommandCategory = 'setup' | 'build' | 'dev' | 'quality' | 'visual' | 'ai' | 'integration' | 'utility';
+interface CliCategoryInfo {
+    label: string;
+    description: string;
+}
+declare const CLI_COMMAND_CATEGORIES: Record<CliCommandCategory, CliCategoryInfo>;
+declare const CLI_COMMANDS: CliCommandDef[];
+
+export { CLI_COMMANDS, CLI_COMMAND_CATEGORIES, type CliCategoryInfo, type CliCommandCategory, type CliCommandDef, type CliOptionDef };

package/dist/cli-commands/index.js

@@ -0,0 +1,8 @@
+import {
+  CLI_COMMANDS,
+  CLI_COMMAND_CATEGORIES
+} from "../chunk-U4V5NX67.js";
+export {
+  CLI_COMMANDS,
+  CLI_COMMAND_CATEGORIES
+};

package/dist/generate/index.d.ts

@@ -1,4 +1,5 @@
 import { CompiledSegment, CompiledBlock } from '../types/index.js';
+import '../types-DOhSojcf.js';
 
 /**
  * Context generation for AI agents.

package/dist/graph/index.d.ts

@@ -0,0 +1,66 @@
+import { C as ComponentGraph, G as GraphEdgeType, a as GraphEdge, I as ImpactResult, P as PathResult, N as NeighborResult, b as CompositionTree, c as GraphHealth, d as ComponentNode, S as SerializedComponentGraph } from '../types-DOhSojcf.js';
+export { E as EDGE_TYPE_WEIGHTS, f as GRAPH_EDGE_TYPES, e as SerializedEdge } from '../types-DOhSojcf.js';
+
+/**
+ * ComponentGraphEngine — query engine for the design-system relationship graph.
+ *
+ * Provides BFS-based traversal, impact analysis, composition trees,
+ * alternative discovery, and health metrics. Operates on an in-memory
+ * adjacency list built from GraphEdge[].
+ */
+
+declare class ComponentGraphEngine {
+    private nodes;
+    private outgoing;
+    private incoming;
+    private edges;
+    private blockIndex;
+    private health;
+    constructor(graph: ComponentGraph, blocks?: Record<string, {
+        components: string[];
+    }>);
+    /** Get outgoing edges from a component, optionally filtered by edge type */
+    dependencies(component: string, edgeTypes?: GraphEdgeType[]): GraphEdge[];
+    /** Get incoming edges to a component, optionally filtered by edge type */
+    dependents(component: string, edgeTypes?: GraphEdgeType[]): GraphEdge[];
+    /** BFS transitive closure — what's affected if this component changes */
+    impact(component: string, maxDepth?: number): ImpactResult;
+    /** BFS shortest path between two components (undirected) */
+    path(from: string, to: string): PathResult;
+    /** Connected components via BFS on undirected projection */
+    islands(): string[][];
+    /** All components reachable within N hops (undirected) */
+    neighbors(component: string, maxHops?: number): NeighborResult;
+    /** Get the composition tree for a compound component */
+    composition(component: string): CompositionTree;
+    /** Get alternative components */
+    alternatives(component: string): Array<{
+        component: string;
+        note?: string;
+    }>;
+    /** Get blocks that use a component */
+    blocksUsing(component: string): string[];
+    /** Extract an induced subgraph for a set of components */
+    subgraph(components: string[]): ComponentGraph;
+    /** Return precomputed health metrics */
+    getHealth(): GraphHealth;
+    /** Get a single node by name */
+    getNode(name: string): ComponentNode | undefined;
+    /** Check if a component exists in the graph */
+    hasNode(name: string): boolean;
+}
+declare function computeHealthFromData(nodes: ComponentNode[], edges: GraphEdge[], blockIndex?: Map<string, string[]>): GraphHealth;
+
+/**
+ * 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.
+ */
+
+/** Serialize a ComponentGraph to compact JSON format */
+declare function serializeGraph(graph: ComponentGraph): SerializedComponentGraph;
+/** Deserialize a compact JSON graph back to full ComponentGraph */
+declare function deserializeGraph(serialized: SerializedComponentGraph): ComponentGraph;
+
+export { ComponentGraph, ComponentGraphEngine, ComponentNode, CompositionTree, GraphEdge, GraphEdgeType, GraphHealth, ImpactResult, NeighborResult, PathResult, SerializedComponentGraph, computeHealthFromData, deserializeGraph, serializeGraph };