@fragments-sdk/core 0.1.0

package/src/composition.test.ts

@@ -0,0 +1,262 @@
+import { describe, it, expect } from "vitest";
+import { analyzeComposition } from "./composition.js";
+import type { CompiledFragment } from "./types.js";
+
+function makeFragment(overrides: Partial<CompiledFragment> & { meta: CompiledFragment["meta"] }): CompiledFragment {
+  return {
+    filePath: "src/components/Test.tsx",
+    usage: { when: [], whenNot: [] },
+    props: {},
+    variants: [],
+    ...overrides,
+  };
+}
+
+const baseFragments: Record<string, CompiledFragment> = {
+  Button: makeFragment({
+    meta: { name: "Button", description: "A button", category: "actions", status: "stable" },
+    relations: [
+      { component: "IconButton", relationship: "alternative", note: "Use for icon-only actions" },
+      { component: "ButtonGroup", relationship: "composition", note: "Wrap multiple buttons" },
+    ],
+    usage: {
+      when: ["User needs to trigger an action"],
+      whenNot: ["Use Link for navigation"],
+    },
+  }),
+  IconButton: makeFragment({
+    meta: { name: "IconButton", description: "Icon-only button", category: "actions", status: "stable" },
+    relations: [
+      { component: "Button", relationship: "alternative", note: "Use for labeled actions" },
+    ],
+  }),
+  ButtonGroup: makeFragment({
+    meta: { name: "ButtonGroup", description: "Groups buttons", category: "actions", status: "stable" },
+    relations: [
+      { component: "Button", relationship: "child", note: "Contains buttons" },
+    ],
+  }),
+  TextField: makeFragment({
+    meta: { name: "TextField", description: "Text input", category: "forms", status: "stable" },
+    relations: [
+      { component: "Form", relationship: "parent", note: "Should be inside a Form" },
+      { component: "Label", relationship: "sibling", note: "Pair with a Label" },
+    ],
+    usage: {
+      when: ["User needs to enter text"],
+      whenNot: ["Use TextArea for multiline input"],
+    },
+  }),
+  Form: makeFragment({
+    meta: { name: "Form", description: "Form container", category: "forms", status: "stable" },
+  }),
+  Label: makeFragment({
+    meta: { name: "Label", description: "Form label", category: "forms", status: "stable" },
+  }),
+  Alert: makeFragment({
+    meta: { name: "Alert", description: "Feedback alert", category: "feedback", status: "stable" },
+  }),
+  Toast: makeFragment({
+    meta: { name: "Toast", description: "Toast notification", category: "feedback", status: "experimental" },
+  }),
+  OldButton: makeFragment({
+    meta: { name: "OldButton", description: "Use Button instead", category: "actions", status: "deprecated" },
+  }),
+  Link: makeFragment({
+    meta: { name: "Link", description: "Navigation link", category: "navigation", status: "stable" },
+    usage: {
+      when: ["User needs to navigate"],
+      whenNot: ["Use Button for actions"],
+    },
+  }),
+};
+
+describe("analyzeComposition", () => {
+  describe("name validation", () => {
+    it("should split components into found and unknown", () => {
+      const result = analyzeComposition(baseFragments, ["Button", "NonExistent", "TextField", "AlsoFake"]);
+      expect(result.components).toEqual(["Button", "TextField"]);
+      expect(result.unknown).toEqual(["NonExistent", "AlsoFake"]);
+    });
+
+    it("should handle all valid names", () => {
+      const result = analyzeComposition(baseFragments, ["Button", "TextField"]);
+      expect(result.components).toEqual(["Button", "TextField"]);
+      expect(result.unknown).toEqual([]);
+    });
+
+    it("should handle all unknown names", () => {
+      const result = analyzeComposition(baseFragments, ["Foo", "Bar"]);
+      expect(result.components).toEqual([]);
+      expect(result.unknown).toEqual(["Foo", "Bar"]);
+    });
+
+    it("should handle empty input", () => {
+      const result = analyzeComposition(baseFragments, []);
+      expect(result.components).toEqual([]);
+      expect(result.unknown).toEqual([]);
+      expect(result.warnings).toEqual([]);
+      expect(result.suggestions).toEqual([]);
+      expect(result.guidelines).toEqual([]);
+    });
+  });
+
+  describe("relation checks", () => {
+    it("should warn about missing parent", () => {
+      const result = analyzeComposition(baseFragments, ["TextField"]);
+      const parentWarning = result.warnings.find((w) => w.type === "missing_parent");
+      expect(parentWarning).toBeDefined();
+      expect(parentWarning!.component).toBe("TextField");
+      expect(parentWarning!.relatedComponent).toBe("Form");
+    });
+
+    it("should not warn about parent when parent is selected", () => {
+      const result = analyzeComposition(baseFragments, ["TextField", "Form"]);
+      const parentWarning = result.warnings.find((w) => w.type === "missing_parent");
+      expect(parentWarning).toBeUndefined();
+    });
+
+    it("should suggest missing children", () => {
+      const result = analyzeComposition(baseFragments, ["ButtonGroup"]);
+      const childSuggestion = result.suggestions.find(
+        (s) => s.component === "Button" && s.relationship === "child"
+      );
+      expect(childSuggestion).toBeDefined();
+      expect(childSuggestion!.sourceComponent).toBe("ButtonGroup");
+    });
+
+    it("should warn about missing composition peers", () => {
+      const result = analyzeComposition(baseFragments, ["Button"]);
+      const compWarning = result.warnings.find((w) => w.type === "missing_composition");
+      expect(compWarning).toBeDefined();
+      expect(compWarning!.component).toBe("Button");
+      expect(compWarning!.relatedComponent).toBe("ButtonGroup");
+    });
+
+    it("should not warn when composition peer is selected", () => {
+      const result = analyzeComposition(baseFragments, ["Button", "ButtonGroup"]);
+      const compWarning = result.warnings.find((w) => w.type === "missing_composition");
+      expect(compWarning).toBeUndefined();
+    });
+
+    it("should suggest missing siblings", () => {
+      const result = analyzeComposition(baseFragments, ["TextField", "Form"]);
+      const siblingSuggestion = result.suggestions.find(
+        (s) => s.component === "Label" && s.relationship === "sibling"
+      );
+      expect(siblingSuggestion).toBeDefined();
+      expect(siblingSuggestion!.sourceComponent).toBe("TextField");
+    });
+
+    it("should warn about redundant alternatives", () => {
+      const result = analyzeComposition(baseFragments, ["Button", "IconButton"]);
+      const altWarning = result.warnings.find((w) => w.type === "redundant_alternative");
+      expect(altWarning).toBeDefined();
+      expect(altWarning!.component).toBe("Button");
+      expect(altWarning!.relatedComponent).toBe("IconButton");
+    });
+
+    it("should not warn when only one alternative is selected", () => {
+      const result = analyzeComposition(baseFragments, ["Button"]);
+      const altWarning = result.warnings.find((w) => w.type === "redundant_alternative");
+      expect(altWarning).toBeUndefined();
+    });
+  });
+
+  describe("usage conflict checks", () => {
+    it("should emit guideline when whenNot mentions another selected component", () => {
+      const result = analyzeComposition(baseFragments, ["Button", "Link"]);
+      const conflict = result.guidelines.find(
+        (g) => g.component === "Link" && g.guideline.includes("Button")
+      );
+      expect(conflict).toBeDefined();
+    });
+
+    it("should not emit guideline when no conflict exists", () => {
+      const result = analyzeComposition(baseFragments, ["Button", "Alert"]);
+      expect(result.guidelines).toEqual([]);
+    });
+  });
+
+  describe("status warnings", () => {
+    it("should warn about deprecated components", () => {
+      const result = analyzeComposition(baseFragments, ["OldButton"]);
+      const depWarning = result.warnings.find((w) => w.type === "deprecated");
+      expect(depWarning).toBeDefined();
+      expect(depWarning!.component).toBe("OldButton");
+      expect(depWarning!.message).toContain("deprecated");
+    });
+
+    it("should warn about experimental components", () => {
+      const result = analyzeComposition(baseFragments, ["Toast"]);
+      const expWarning = result.warnings.find((w) => w.type === "experimental");
+      expect(expWarning).toBeDefined();
+      expect(expWarning!.component).toBe("Toast");
+      expect(expWarning!.message).toContain("experimental");
+    });
+
+    it("should not warn about stable components", () => {
+      const result = analyzeComposition(baseFragments, ["Button"]);
+      const statusWarnings = result.warnings.filter(
+        (w) => w.type === "deprecated" || w.type === "experimental"
+      );
+      expect(statusWarnings).toEqual([]);
+    });
+  });
+
+  describe("category gap analysis", () => {
+    it("should suggest feedback component when forms are selected without feedback", () => {
+      const result = analyzeComposition(baseFragments, ["TextField", "Form"]);
+      const gapSuggestion = result.suggestions.find(
+        (s) => s.relationship === "category_gap"
+      );
+      expect(gapSuggestion).toBeDefined();
+      expect(gapSuggestion!.component).toBe("Alert");
+      expect(gapSuggestion!.reason).toContain("feedback");
+    });
+
+    it("should suggest feedback component when actions are selected without feedback", () => {
+      const result = analyzeComposition(baseFragments, ["Button", "ButtonGroup"]);
+      const gapSuggestion = result.suggestions.find(
+        (s) => s.relationship === "category_gap"
+      );
+      expect(gapSuggestion).toBeDefined();
+      expect(gapSuggestion!.component).toBe("Alert");
+    });
+
+    it("should not suggest category gap when feedback is already present", () => {
+      const result = analyzeComposition(baseFragments, ["Button", "ButtonGroup", "Alert"]);
+      const gapSuggestion = result.suggestions.find(
+        (s) => s.relationship === "category_gap"
+      );
+      expect(gapSuggestion).toBeUndefined();
+    });
+
+    it("should prefer stable components over experimental in category gap suggestions", () => {
+      // Alert is stable, Toast is experimental — should pick Alert
+      const result = analyzeComposition(baseFragments, ["TextField", "Form"]);
+      const gapSuggestion = result.suggestions.find(
+        (s) => s.relationship === "category_gap"
+      );
+      expect(gapSuggestion?.component).toBe("Alert");
+    });
+  });
+
+  describe("deduplication", () => {
+    it("should not suggest the same component twice", () => {
+      const result = analyzeComposition(baseFragments, ["ButtonGroup", "Button"]);
+      const buttonSuggestions = result.suggestions.filter(
+        (s) => s.component === "Button"
+      );
+      // Button is already selected so it shouldn't be suggested
+      expect(buttonSuggestions).toEqual([]);
+    });
+  });
+
+  describe("context parameter", () => {
+    it("should accept optional context without error", () => {
+      const result = analyzeComposition(baseFragments, ["Button"], "building a form page");
+      expect(result.components).toEqual(["Button"]);
+    });
+  });
+});

package/src/composition.ts

@@ -0,0 +1,318 @@
+import type { CompiledFragment, RelationshipType } from "./types.js";
+import type { ComponentGraph } from "@fragments-sdk/context/graph";
+import { ComponentGraphEngine } from "@fragments-sdk/context/graph";
+
+// --- Public types ---
+
+export interface CompositionWarning {
+  type:
+    | "missing_parent"
+    | "missing_child"
+    | "missing_composition"
+    | "redundant_alternative"
+    | "deprecated"
+    | "experimental";
+  component: string;
+  message: string;
+  relatedComponent?: string;
+}
+
+export interface CompositionSuggestion {
+  component: string;
+  reason: string;
+  relationship: RelationshipType | "category_gap";
+  sourceComponent: string;
+}
+
+export interface CompositionGuideline {
+  component: string;
+  guideline: string;
+}
+
+export interface CompositionAnalysis {
+  /** The validated component names (filtered to those that exist) */
+  components: string[];
+
+  /** Components requested but not found in the registry */
+  unknown: string[];
+
+  /** Issues with the current selection */
+  warnings: CompositionWarning[];
+
+  /** Components to consider adding */
+  suggestions: CompositionSuggestion[];
+
+  /** Relevant usage guidelines for the selected components */
+  guidelines: CompositionGuideline[];
+}
+
+// --- Category affinities ---
+
+const CATEGORY_AFFINITIES: Record<string, string[]> = {
+  forms: ["feedback"],
+  actions: ["feedback"],
+};
+
+// --- Main function ---
+
+/**
+ * Analyzes a set of components as a composition group.
+ * 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(
+  fragments: Record<string, CompiledFragment>,
+  componentNames: string[],
+  _context?: string,
+  options?: { graph?: ComponentGraph },
+): CompositionAnalysis {
+  const allNames = new Set(Object.keys(fragments));
+
+  // 1. Validate names
+  const components: string[] = [];
+  const unknown: string[] = [];
+  for (const name of componentNames) {
+    if (allNames.has(name)) {
+      components.push(name);
+    } else {
+      unknown.push(name);
+    }
+  }
+
+  const selectedSet = new Set(components);
+  const warnings: CompositionWarning[] = [];
+  const suggestions: CompositionSuggestion[] = [];
+  const guidelines: CompositionGuideline[] = [];
+
+  // Track suggestions to avoid duplicates
+  const suggestedSet = new Set<string>();
+
+  for (const name of components) {
+    const fragment = fragments[name];
+
+    // 2. Relation checks
+    if (fragment.relations) {
+      for (const rel of fragment.relations) {
+        switch (rel.relationship) {
+          case "parent":
+            if (!selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "missing_parent",
+                component: name,
+                message: `"${name}" expects to be wrapped by "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component,
+              });
+            }
+            break;
+
+          case "child":
+            if (!selectedSet.has(rel.component) && !suggestedSet.has(rel.component)) {
+              suggestions.push({
+                component: rel.component,
+                reason: `"${name}" typically contains "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relationship: "child",
+                sourceComponent: name,
+              });
+              suggestedSet.add(rel.component);
+            }
+            break;
+
+          case "composition":
+            if (!selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "missing_composition",
+                component: name,
+                message: `"${name}" is typically used together with "${rel.component}"${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component,
+              });
+            }
+            break;
+
+          case "sibling":
+            if (!selectedSet.has(rel.component) && !suggestedSet.has(rel.component)) {
+              suggestions.push({
+                component: rel.component,
+                reason: `"${rel.component}" is a sibling of "${name}"${rel.note ? `: ${rel.note}` : ""}`,
+                relationship: "sibling",
+                sourceComponent: name,
+              });
+              suggestedSet.add(rel.component);
+            }
+            break;
+
+          case "alternative":
+            if (selectedSet.has(rel.component)) {
+              warnings.push({
+                type: "redundant_alternative",
+                component: name,
+                message: `"${name}" and "${rel.component}" are alternatives — using both may be redundant${rel.note ? `: ${rel.note}` : ""}`,
+                relatedComponent: rel.component,
+              });
+            }
+            break;
+        }
+      }
+    }
+
+    // 3. Usage conflict checks (whenNot)
+    if (fragment.usage?.whenNot) {
+      for (const whenNotEntry of fragment.usage.whenNot) {
+        const lower = whenNotEntry.toLowerCase();
+        for (const other of components) {
+          if (other !== name && lower.includes(other.toLowerCase())) {
+            guidelines.push({
+              component: name,
+              guideline: `Potential conflict with "${other}": ${whenNotEntry}`,
+            });
+          }
+        }
+      }
+    }
+
+    // 4. Status warnings
+    if (fragment.meta.status === "deprecated") {
+      warnings.push({
+        type: "deprecated",
+        component: name,
+        message: fragment.meta.description
+          ? `"${name}" is deprecated: ${fragment.meta.description}`
+          : `"${name}" is deprecated`,
+      });
+    } else if (fragment.meta.status === "experimental") {
+      warnings.push({
+        type: "experimental",
+        component: name,
+        message: `"${name}" is experimental and may change without notice`,
+      });
+    }
+  }
+
+  // 5. Category gap analysis
+  const selectedCategories = new Set(
+    components.map((name) => fragments[name].meta.category)
+  );
+
+  for (const [category, affinities] of Object.entries(CATEGORY_AFFINITIES)) {
+    if (!selectedCategories.has(category)) continue;
+
+    for (const neededCategory of affinities) {
+      if (selectedCategories.has(neededCategory)) continue;
+
+      // Find the best component from the needed category
+      const candidate = findBestCategoryCandidate(
+        fragments,
+        neededCategory,
+        selectedSet,
+        suggestedSet
+      );
+      if (candidate) {
+        suggestions.push({
+          component: candidate,
+          reason: `Compositions using "${category}" components often benefit from a "${neededCategory}" component`,
+          relationship: "category_gap",
+          sourceComponent: components.find(
+            (n) => fragments[n].meta.category === category
+          )!,
+        });
+        suggestedSet.add(candidate);
+      }
+    }
+  }
+
+  // 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 };
+}
+
+/**
+ * Find the best candidate component from a given category.
+ * Prefers stable components and avoids already-selected or already-suggested ones.
+ */
+function findBestCategoryCandidate(
+  fragments: Record<string, CompiledFragment>,
+  category: string,
+  selectedSet: Set<string>,
+  suggestedSet: Set<string>
+): string | null {
+  let best: string | null = null;
+  let bestScore = -1;
+
+  for (const [name, fragment] of Object.entries(fragments)) {
+    if (fragment.meta.category !== category) continue;
+    if (selectedSet.has(name) || suggestedSet.has(name)) continue;
+
+    const status = fragment.meta.status ?? "stable";
+    let score = 0;
+    if (status === "stable") score = 3;
+    else if (status === "beta") score = 2;
+    else if (status === "experimental") score = 1;
+    // deprecated gets 0
+
+    if (score > bestScore) {
+      bestScore = score;
+      best = name;
+    }
+  }
+
+  return best;
+}

package/src/constants.ts

@@ -0,0 +1,114 @@
+/**
+ * Brand constants for easy rebranding if domain availability requires it.
+ * All naming throughout the codebase should reference these constants.
+ */
+export const BRAND = {
+  /** Display name (e.g., "Fragments") */
+  name: "Fragments",
+
+  /** Lowercase name for file paths and CLI (e.g., "fragments") */
+  nameLower: "fragments",
+
+  /** File extension for fragment definition files (e.g., ".fragment.tsx") */
+  fileExtension: ".fragment.tsx",
+
+  /** Legacy file extension for segments (still supported for migration) */
+  legacyFileExtension: ".segment.tsx",
+
+  /** JSON file extension for compiled output */
+  jsonExtension: ".fragment.json",
+
+  /** Default output file name (e.g., "fragments.json") */
+  outFile: "fragments.json",
+
+  /** Config file name (e.g., "fragments.config.ts") */
+  configFile: "fragments.config.ts",
+
+  /** Legacy config file name (still supported for migration) */
+  legacyConfigFile: "segments.config.ts",
+
+  /** CLI command name (e.g., "fragments") */
+  cliCommand: "fragments",
+
+  /** Package scope (e.g., "@fragments") */
+  packageScope: "@fragments",
+
+  /** Directory for storing fragments, registry, and cache */
+  dataDir: ".fragments",
+
+  /** Components subdirectory within .fragments/ */
+  componentsDir: "components",
+
+  /** Registry file name */
+  registryFile: "registry.json",
+
+  /** Context file name (AI-ready markdown) */
+  contextFile: "context.md",
+
+  /** Screenshots subdirectory */
+  screenshotsDir: "screenshots",
+
+  /** Cache subdirectory (gitignored) */
+  cacheDir: "cache",
+
+  /** Diff output subdirectory (gitignored) */
+  diffDir: "diff",
+
+  /** Manifest filename */
+  manifestFile: "manifest.json",
+
+  /** Prefix for localStorage keys (e.g., "fragments-") */
+  storagePrefix: "fragments-",
+
+  /** Static viewer HTML file name */
+  viewerHtmlFile: "fragments-viewer.html",
+
+  /** MCP tool name prefix (e.g., "fragments_") */
+  mcpToolPrefix: "fragments_",
+
+  /** File extension for block definition files */
+  blockFileExtension: ".block.ts",
+
+  /** @deprecated Use blockFileExtension instead */
+  recipeFileExtension: ".recipe.ts",
+
+  /** Vite plugin namespace */
+  vitePluginNamespace: "fragments-core-shim",
+} as const;
+
+export type Brand = typeof BRAND;
+
+/**
+ * Default configuration values for the service.
+ * These can be overridden in fragments.config.ts
+ */
+export const DEFAULTS = {
+  /** Default viewport dimensions */
+  viewport: {
+    width: 1280,
+    height: 800,
+  },
+
+  /** Default diff threshold (percentage) */
+  diffThreshold: 5,
+
+  /** Browser pool size */
+  poolSize: 3,
+
+  /** Idle timeout before browser shutdown (ms) - 5 minutes */
+  idleTimeoutMs: 5 * 60 * 1000,
+
+  /** Delay after render before capture (ms) */
+  captureDelayMs: 100,
+
+  /** Font loading timeout (ms) */
+  fontTimeoutMs: 3000,
+
+  /** Default theme */
+  theme: "light" as const,
+
+  /** Dev server port */
+  port: 6006,
+} as const;
+
+export type Defaults = typeof DEFAULTS;

package/src/context.ts

@@ -0,0 +1,2 @@
+export { generateContext, filterPlaceholders, PLACEHOLDER_PATTERNS } from '@fragments-sdk/context/generate';
+export type { ContextOptions, ContextResult } from '@fragments-sdk/context/generate';