@fragments-sdk/context 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,62 @@
+# @fragments-sdk/context
+
+Code intelligence and RAG primitives for codebase indexing and search.
+
+## Modules
+
+### Chunking (`@fragments-sdk/context/chunking`)
+
+Split source files into semantically meaningful chunks for embedding.
+
+- **`chunkFile(content, filePath, language)`** — Auto-selects AST or line-based chunking
+- **`chunkByAST(content, filePath, language, grammar)`** — Tree-sitter AST-aware chunking (preserves functions, classes, etc.)
+- **`chunkByLines(content, filePath, language)`** — Sliding-window fallback
+
+AST chunking supports: TypeScript, TSX, JavaScript, Python, Go, Rust, Java.
+
+```ts
+import { chunkFile } from "@fragments-sdk/context/chunking";
+
+const chunks = await chunkFile(code, "src/auth.ts", "typescript");
+// Each chunk has: content, filePath, startLine, endLine, language, symbolName?, scopeChain?
+```
+
+### Embeddings (`@fragments-sdk/context/embeddings`)
+
+Generate code-optimized embeddings via Voyage AI.
+
+- **`generateEmbeddings(texts, options)`** — Batch embed with `voyage-code-3`
+- **`rerankResults(query, documents, options)`** — Cross-encoder reranking with `rerank-2.5`
+
+```ts
+import { generateEmbeddings } from "@fragments-sdk/context/embeddings";
+
+const vectors = await generateEmbeddings(chunks.map(c => c.content), {
+  apiKey: process.env.VOYAGE_API_KEY!,
+  inputType: "document",
+});
+```
+
+### Search (`@fragments-sdk/context/search`)
+
+Post-retrieval utilities for combining and deduplicating results.
+
+- **`reciprocalRankFusion(resultSets)`** — Merge multiple ranked lists (e.g. vector + keyword)
+- **`deduplicateChunks(chunks)`** — Remove near-duplicate results
+
+### Indexing (`@fragments-sdk/context/indexing`)
+
+File filtering, change detection, and language detection.
+
+- **`shouldIndexFile(path, size)`** — Filter by extension, size, ignored dirs
+- **`detectLanguage(path)`** — Map file extension to language name
+- **`resolveChanges(oldFiles, newFiles)`** — Diff two file trees for incremental re-indexing
+- **`hashContent(content)`** — Content hashing for change detection
+
+## Install
+
+```sh
+pnpm add @fragments-sdk/context
+```
+
+Requires Node.js 18+. Tree-sitter WASM grammars are included as dependencies.

package/dist/chunk-3FEHRHFQ.js

@@ -0,0 +1,103 @@
+// src/citations/document-builder.ts
+function buildCitationDocuments(chunks, options) {
+  const documents = [];
+  const documentMap = [];
+  const byFile = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    const existing = byFile.get(chunk.filePath);
+    if (existing) {
+      existing.push(chunk);
+    } else {
+      byFile.set(chunk.filePath, [chunk]);
+    }
+  }
+  for (const [filePath, fileChunks] of byFile) {
+    const docIndex = documents.length;
+    const contentBlocks = fileChunks.map((chunk) => ({
+      type: "text",
+      text: chunk.content
+    }));
+    const contextLines = fileChunks.map((chunk, i) => {
+      const parts = [`Block ${i}: lines ${chunk.startLine}-${chunk.endLine} (${chunk.language})`];
+      if (chunk.symbolName) parts.push(`symbol: ${chunk.symbolName}`);
+      return parts.join(", ");
+    });
+    documents.push({
+      type: "document",
+      source: { type: "content", content: contentBlocks },
+      title: filePath,
+      context: contextLines.join("\n"),
+      citations: { enabled: true }
+    });
+    documentMap.push({
+      documentIndex: docIndex,
+      filePath,
+      sourceType: "code",
+      chunks: fileChunks.map((chunk, i) => ({
+        blockIndex: i,
+        startLine: chunk.startLine,
+        endLine: chunk.endLine,
+        language: chunk.language,
+        symbolName: chunk.symbolName,
+        score: chunk.score
+      }))
+    });
+  }
+  if (options?.additionalDocuments) {
+    for (const doc of options.additionalDocuments) {
+      if (!doc.content.trim()) continue;
+      const docIndex = documents.length;
+      documents.push({
+        type: "document",
+        source: {
+          type: "text",
+          media_type: "text/plain",
+          data: doc.content
+        },
+        title: doc.title,
+        citations: { enabled: true }
+      });
+      documentMap.push({
+        documentIndex: docIndex,
+        filePath: doc.title,
+        sourceType: "plaintext",
+        chunks: []
+      });
+    }
+  }
+  return { documents, documentMap };
+}
+
+// src/citations/resolver.ts
+function resolveCitation(raw, documentMap, citationIndex, textOffset) {
+  const mapping = documentMap[raw.document_index];
+  const base = {
+    index: citationIndex,
+    citedText: raw.cited_text,
+    documentTitle: raw.document_title,
+    filePath: mapping?.filePath ?? raw.document_title ?? "unknown",
+    sourceType: mapping?.sourceType ?? "plaintext",
+    textOffset
+  };
+  if (raw.type === "content_block_location" && mapping?.sourceType === "code" && raw.start_block_index != null) {
+    const chunk = mapping.chunks[raw.start_block_index];
+    if (chunk) {
+      base.startLine = chunk.startLine;
+      base.endLine = chunk.endLine;
+      base.language = chunk.language;
+      base.symbolName = chunk.symbolName;
+    }
+  }
+  return base;
+}
+function resolveCitations(raws, documentMap, textOffsets) {
+  return raws.map(
+    (raw, i) => resolveCitation(raw, documentMap, i + 1, textOffsets[i] ?? 0)
+  );
+}
+
+export {
+  buildCitationDocuments,
+  resolveCitation,
+  resolveCitations
+};

package/dist/chunk-KKABP4K4.js

@@ -0,0 +1,228 @@
+// src/generate/index.ts
+var PLACEHOLDER_PATTERNS = [
+  /^\w+ component is needed$/i,
+  /^Alternative component is more appropriate$/i,
+  /^Use \w+ when you need/i
+];
+function filterPlaceholders(items) {
+  if (!items) return [];
+  return items.filter(
+    (item) => !PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(item.trim()))
+  );
+}
+function generateContext(segments, options = {}, blocks) {
+  const format = options.format ?? "markdown";
+  const compact = options.compact ?? false;
+  const include = {
+    props: options.include?.props ?? true,
+    variants: options.include?.variants ?? true,
+    usage: options.include?.usage ?? true,
+    relations: options.include?.relations ?? false,
+    code: options.include?.code ?? false
+  };
+  const sorted = [...segments].sort((a, b) => {
+    const catCompare = a.meta.category.localeCompare(b.meta.category);
+    if (catCompare !== 0) return catCompare;
+    return a.meta.name.localeCompare(b.meta.name);
+  });
+  if (format === "json") {
+    return generateJsonContext(sorted, include, compact, blocks);
+  }
+  return generateMarkdownContext(sorted, include, compact, blocks);
+}
+function generateMarkdownContext(segments, include, compact, blocks) {
+  const lines = [];
+  lines.push("# Design System Reference");
+  lines.push("");
+  lines.push("## Quick Reference");
+  lines.push("");
+  lines.push("| Component | Category | Use For |");
+  lines.push("|-----------|----------|---------|");
+  for (const segment of segments) {
+    const filteredWhen = filterPlaceholders(segment.usage.when);
+    const useFor = filteredWhen.slice(0, 2).join(", ") || segment.meta.description;
+    lines.push(`| ${segment.meta.name} | ${segment.meta.category} | ${truncate(useFor, 50)} |`);
+  }
+  lines.push("");
+  if (compact) {
+    const content2 = lines.join("\n");
+    return { content: content2, tokenEstimate: estimateTokens(content2) };
+  }
+  lines.push("## Components");
+  lines.push("");
+  for (const segment of segments) {
+    lines.push(`### ${segment.meta.name}`);
+    lines.push("");
+    const statusParts = [`**Category:** ${segment.meta.category}`];
+    if (segment.meta.status) {
+      statusParts.push(`**Status:** ${segment.meta.status}`);
+    }
+    lines.push(statusParts.join(" | "));
+    lines.push("");
+    if (segment.meta.description) {
+      lines.push(segment.meta.description);
+      lines.push("");
+    }
+    const whenFiltered = filterPlaceholders(segment.usage.when);
+    const whenNotFiltered = filterPlaceholders(segment.usage.whenNot);
+    if (include.usage && (whenFiltered.length > 0 || whenNotFiltered.length > 0)) {
+      if (whenFiltered.length > 0) {
+        lines.push("**When to use:**");
+        for (const when of whenFiltered) {
+          lines.push(`- ${when}`);
+        }
+        lines.push("");
+      }
+      if (whenNotFiltered.length > 0) {
+        lines.push("**When NOT to use:**");
+        for (const whenNot of whenNotFiltered) {
+          lines.push(`- ${whenNot}`);
+        }
+        lines.push("");
+      }
+    }
+    if (include.props && Object.keys(segment.props).length > 0) {
+      lines.push("**Props:**");
+      for (const [name, prop] of Object.entries(segment.props)) {
+        lines.push(`- \`${name}\`: ${formatPropType(prop)}${prop.required ? " (required)" : ""}`);
+      }
+      lines.push("");
+    }
+    if (include.variants && segment.variants.length > 0) {
+      const variantNames = segment.variants.map((v) => v.name).join(", ");
+      lines.push(`**Variants:** ${variantNames}`);
+      lines.push("");
+      if (include.code) {
+        for (const variant of segment.variants) {
+          if (variant.code) {
+            lines.push(`*${variant.name}:*`);
+            lines.push("```tsx");
+            lines.push(variant.code);
+            lines.push("```");
+            lines.push("");
+          }
+        }
+      }
+    }
+    if (include.relations && segment.relations && segment.relations.length > 0) {
+      lines.push("**Related:**");
+      for (const relation of segment.relations) {
+        lines.push(`- ${relation.component} (${relation.relationship}): ${relation.note}`);
+      }
+      lines.push("");
+    }
+    lines.push("---");
+    lines.push("");
+  }
+  if (blocks && blocks.length > 0) {
+    lines.push("## Blocks");
+    lines.push("");
+    lines.push("Composition patterns showing how components wire together.");
+    lines.push("");
+    for (const block of blocks) {
+      lines.push(`### ${block.name}`);
+      lines.push("");
+      lines.push(block.description);
+      lines.push("");
+      lines.push(`**Category:** ${block.category}`);
+      lines.push(`**Components:** ${block.components.join(", ")}`);
+      if (block.tags && block.tags.length > 0) {
+        lines.push(`**Tags:** ${block.tags.join(", ")}`);
+      }
+      lines.push("");
+      lines.push("```tsx");
+      lines.push(block.code);
+      lines.push("```");
+      lines.push("");
+      lines.push("---");
+      lines.push("");
+    }
+  }
+  const content = lines.join("\n");
+  return { content, tokenEstimate: estimateTokens(content) };
+}
+function generateJsonContext(segments, include, compact, blocks) {
+  const categories = [...new Set(segments.map((s) => s.meta.category))].sort();
+  const components = {};
+  for (const segment of segments) {
+    const component = {
+      category: segment.meta.category,
+      description: segment.meta.description
+    };
+    if (segment.meta.status) {
+      component.status = segment.meta.status;
+    }
+    if (!compact) {
+      if (include.usage) {
+        const whenFiltered = filterPlaceholders(segment.usage.when);
+        const whenNotFiltered = filterPlaceholders(segment.usage.whenNot);
+        if (whenFiltered.length > 0) component.whenToUse = whenFiltered;
+        if (whenNotFiltered.length > 0) component.whenNotToUse = whenNotFiltered;
+      }
+      if (include.props && Object.keys(segment.props).length > 0) {
+        component.props = {};
+        for (const [name, prop] of Object.entries(segment.props)) {
+          component.props[name] = {
+            type: formatPropType(prop),
+            description: prop.description
+          };
+          if (prop.required) component.props[name].required = true;
+          if (prop.default !== void 0) component.props[name].default = prop.default;
+        }
+      }
+      if (include.variants && segment.variants.length > 0) {
+        component.variants = segment.variants.map((v) => v.name);
+      }
+      if (include.relations && segment.relations && segment.relations.length > 0) {
+        component.relations = segment.relations.map((r) => ({
+          component: r.component,
+          relationship: r.relationship,
+          note: r.note
+        }));
+      }
+    }
+    components[segment.meta.name] = component;
+  }
+  const blocksMap = blocks && blocks.length > 0 ? Object.fromEntries(blocks.map((b) => [b.name, {
+    description: b.description,
+    category: b.category,
+    components: b.components,
+    code: b.code,
+    tags: b.tags
+  }])) : void 0;
+  const output = {
+    version: "1.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    summary: {
+      totalComponents: segments.length,
+      categories,
+      ...blocksMap && { totalBlocks: blocks.length }
+    },
+    components,
+    ...blocksMap && { blocks: blocksMap }
+  };
+  const content = JSON.stringify(output, null, 2);
+  return { content, tokenEstimate: estimateTokens(content) };
+}
+function formatPropType(prop) {
+  if (prop.type === "enum" && prop.values) {
+    return prop.values.map((v) => `"${v}"`).join(" | ");
+  }
+  if (prop.default !== void 0) {
+    return `${prop.type} (default: ${JSON.stringify(prop.default)})`;
+  }
+  return prop.type;
+}
+function truncate(str, maxLength) {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + "...";
+}
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+export {
+  PLACEHOLDER_PATTERNS,
+  filterPlaceholders,
+  generateContext
+};

package/dist/citations/index.d.ts

@@ -0,0 +1,94 @@
+import { a as ScoredChunk } from '../types-B7duBj6U.js';
+
+interface CitationDocumentBlock {
+    type: "document";
+    source: {
+        type: "content";
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+    } | {
+        type: "text";
+        media_type: "text/plain";
+        data: string;
+    };
+    title?: string | null;
+    context?: string | null;
+    citations: {
+        enabled: true;
+    };
+}
+interface ChunkMapping {
+    /** Position in the content array of the document block. */
+    blockIndex: number;
+    startLine: number;
+    endLine: number;
+    language: string;
+    symbolName?: string;
+    score: number;
+}
+interface DocumentMapping {
+    /** Index of this document in the documents array sent to Anthropic. */
+    documentIndex: number;
+    filePath: string;
+    sourceType: "code" | "plaintext";
+    chunks: ChunkMapping[];
+}
+interface ResolvedCitation {
+    /** 1-indexed display number. */
+    index: number;
+    citedText: string;
+    documentTitle: string | null;
+    filePath: string;
+    sourceType: "code" | "plaintext";
+    startLine?: number;
+    endLine?: number;
+    language?: string;
+    symbolName?: string;
+    /** Character position in the response text where this citation appears. */
+    textOffset: number;
+}
+interface CitationDocumentOptions {
+    /** Extra plain-text documents to include (e.g. spec content, commit history). */
+    additionalDocuments?: Array<{
+        title: string;
+        content: string;
+    }>;
+}
+interface RawCitation {
+    type: "content_block_location" | "char_location";
+    cited_text: string;
+    document_index: number;
+    document_title: string | null;
+    start_block_index?: number;
+    end_block_index?: number;
+    start_char_index?: number;
+    end_char_index?: number;
+}
+
+interface BuildResult {
+    documents: CitationDocumentBlock[];
+    documentMap: DocumentMapping[];
+}
+/**
+ * Converts deduplicated ScoredChunk[] into Anthropic-compatible citation
+ * document blocks with a mapping table for resolving raw citations back
+ * to source file/line metadata.
+ *
+ * Pipeline position: after deduplicateChunks() → before Anthropic API call.
+ */
+declare function buildCitationDocuments(chunks: ScoredChunk[], options?: CitationDocumentOptions): BuildResult;
+
+/**
+ * Resolves a single raw Anthropic citation against the document map,
+ * producing a fully enriched ResolvedCitation with file/line metadata.
+ */
+declare function resolveCitation(raw: RawCitation, documentMap: DocumentMapping[], citationIndex: number, textOffset: number): ResolvedCitation;
+/**
+ * Batch-resolves an array of raw citations. Auto-increments citation index
+ * starting from 1.
+ */
+declare function resolveCitations(raws: RawCitation[], documentMap: DocumentMapping[], textOffsets: number[]): ResolvedCitation[];
+
+export { type ChunkMapping, type CitationDocumentBlock, type CitationDocumentOptions, type DocumentMapping, type RawCitation, type ResolvedCitation, buildCitationDocuments, resolveCitation, resolveCitations };

package/dist/citations/index.js

@@ -0,0 +1,10 @@
+import {
+  buildCitationDocuments,
+  resolveCitation,
+  resolveCitations
+} from "../chunk-3FEHRHFQ.js";
+export {
+  buildCitationDocuments,
+  resolveCitation,
+  resolveCitations
+};

package/dist/generate/index.d.ts

@@ -0,0 +1,43 @@
+import { CompiledSegment, CompiledBlock } from '../types/index.js';
+
+/**
+ * Context generation for AI agents.
+ *
+ * Generates AI-ready context documents from compiled fragment data.
+ */
+
+/**
+ * Placeholder patterns to filter out from usage text.
+ */
+declare const PLACEHOLDER_PATTERNS: RegExp[];
+/**
+ * Filter out placeholder text from usage arrays
+ */
+declare function filterPlaceholders(items: string[] | undefined): string[];
+/**
+ * Options for context generation
+ */
+interface ContextOptions {
+    format?: "markdown" | "json";
+    include?: {
+        props?: boolean;
+        variants?: boolean;
+        usage?: boolean;
+        relations?: boolean;
+        code?: boolean;
+    };
+    compact?: boolean;
+}
+/**
+ * Result of context generation
+ */
+interface ContextResult {
+    content: string;
+    tokenEstimate: number;
+}
+/**
+ * Generate AI-ready context from compiled segments and optional blocks
+ */
+declare function generateContext(segments: CompiledSegment[], options?: ContextOptions, blocks?: CompiledBlock[]): ContextResult;
+
+export { type ContextOptions, type ContextResult, PLACEHOLDER_PATTERNS, filterPlaceholders, generateContext };

package/dist/generate/index.js

@@ -0,0 +1,10 @@
+import {
+  PLACEHOLDER_PATTERNS,
+  filterPlaceholders,
+  generateContext
+} from "../chunk-KKABP4K4.js";
+export {
+  PLACEHOLDER_PATTERNS,
+  filterPlaceholders,
+  generateContext
+};

package/dist/index.d.ts

@@ -1,4 +1,8 @@
+export { AIMetadata, CompiledBlock, CompiledSegment, CompiledSegmentsFile, CompiledTokenData, CompiledTokenEntry, ComponentRelation, PropDefinition, SegmentContract, SegmentGenerated, SegmentMeta, SegmentUsage, 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';
-export { FusedResult, RankedResult, ScoredChunk, SearchResult, deduplicateChunks, reciprocalRankFusion } from './search/index.js';
+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';

package/dist/index.js

@@ -22,19 +22,35 @@ import {
   getTreeSitterGrammar,
   shouldIndexFile
 } from "./chunk-JFV27WLV.js";
+import {
+  PLACEHOLDER_PATTERNS,
+  filterPlaceholders,
+  generateContext
+} from "./chunk-KKABP4K4.js";
+import {
+  buildCitationDocuments,
+  resolveCitation,
+  resolveCitations
+} from "./chunk-3FEHRHFQ.js";
 export {
   AST_SUPPORTED_LANGUAGES,
   INDEXABLE_EXTENSIONS,
+  PLACEHOLDER_PATTERNS,
+  buildCitationDocuments,
   chunkByAST,
   chunkByLines,
   chunkFile,
   deduplicateChunks,
   detectLanguage,
+  filterPlaceholders,
+  generateContext,
   generateEmbeddings,
   getTreeSitterGrammar,
   hashContent,
   reciprocalRankFusion,
   rerankResults,
   resolveChanges,
+  resolveCitation,
+  resolveCitations,
   shouldIndexFile
 };

package/dist/search/index.d.ts

@@ -1,40 +1,5 @@
-interface SearchResult {
-    /** Unique identifier for the result. */
-    id: string;
-    /** Rank position in the result list (0-indexed). */
-    rank: number;
-    /** Optional score from the search system. */
-    score?: number;
-}
-interface RankedResult extends SearchResult {
-    /** The content or document associated with this result. */
-    content: string;
-    /** File path of the source. */
-    filePath: string;
-    /** Start line in the source file. */
-    startLine: number;
-    /** End line in the source file. */
-    endLine: number;
-}
-interface FusedResult {
-    /** Unique identifier for the result. */
-    id: string;
-    /** Fused RRF score across all result sets. */
-    fusedScore: number;
-    /** Which result sets contributed to this result. */
-    sources: string[];
-}
-interface ScoredChunk {
-    id: string;
-    content: string;
-    filePath: string;
-    startLine: number;
-    endLine: number;
-    language: string;
-    score: number;
-    symbolName?: string;
-    chunkType?: string;
-}
+import { S as SearchResult, F as FusedResult, a as ScoredChunk } from '../types-B7duBj6U.js';
+export { R as RankedResult } from '../types-B7duBj6U.js';
 
 /**
  * Reciprocal Rank Fusion (RRF) — merges multiple ranked result lists
@@ -61,4 +26,4 @@ declare function reciprocalRankFusion(resultSets: Array<{
  */
 declare function deduplicateChunks(chunks: ScoredChunk[]): ScoredChunk[];
 
-export { type FusedResult, type RankedResult, type ScoredChunk, type SearchResult, deduplicateChunks, reciprocalRankFusion };
+export { FusedResult, ScoredChunk, SearchResult, deduplicateChunks, reciprocalRankFusion };

package/dist/types/index.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Compiled fragment types — shared between CLI and MCP packages.
+ *
+ * These are the JSON-serializable types used in fragments.json and consumed
+ * by AI agents, MCP servers, and context generators.
+ */
+/**
+ * Component metadata
+ */
+interface SegmentMeta {
+    name: string;
+    description: string;
+    category: string;
+    tags?: string[];
+    status?: "stable" | "beta" | "deprecated" | "experimental";
+    since?: string;
+    figma?: string;
+    figmaProps?: Record<string, unknown>;
+}
+/**
+ * Usage guidelines for AI agents and developers
+ */
+interface SegmentUsage {
+    when: string[];
+    whenNot: string[];
+    guidelines?: string[];
+    accessibility?: string[];
+}
+/**
+ * Definition for a single prop
+ */
+interface PropDefinition {
+    type: string;
+    values?: readonly string[];
+    default?: unknown;
+    description: string;
+    required?: boolean;
+    constraints?: string[];
+    typeDetails?: Record<string, unknown>;
+    controlType?: string;
+    controlOptions?: {
+        min?: number;
+        max?: number;
+        step?: number;
+        presetColors?: string[];
+    };
+}
+/**
+ * Relationship to another component
+ */
+interface ComponentRelation {
+    component: string;
+    relationship: string;
+    note: string;
+}
+/**
+ * Agent-optimized contract metadata
+ */
+interface SegmentContract {
+    propsSummary?: string[];
+    a11yRules?: string[];
+    bans?: Array<{
+        pattern: string;
+        message: string;
+    }>;
+    scenarioTags?: string[];
+}
+/**
+ * Provenance tracking for generated segments
+ */
+interface SegmentGenerated {
+    source: "storybook" | "manual" | "ai";
+    sourceFile?: string;
+    confidence?: number;
+    timestamp?: string;
+}
+/**
+ * AI-specific metadata
+ */
+interface AIMetadata {
+    compositionPattern?: "compound" | "simple" | "controlled";
+    subComponents?: string[];
+    requiredChildren?: string[];
+    commonPatterns?: string[];
+}
+/**
+ * Compiled segment data (JSON-serializable for AI consumption)
+ */
+interface CompiledSegment {
+    filePath: string;
+    meta: SegmentMeta;
+    usage: SegmentUsage;
+    props: Record<string, PropDefinition>;
+    relations?: ComponentRelation[];
+    variants: Array<{
+        name: string;
+        description: string;
+        code?: string;
+        figma?: string;
+        args?: Record<string, unknown>;
+    }>;
+    contract?: SegmentContract;
+    ai?: AIMetadata;
+    _generated?: SegmentGenerated;
+}
+/**
+ * Compiled block data (JSON-serializable for AI consumption)
+ */
+interface CompiledBlock {
+    filePath: string;
+    name: string;
+    description: string;
+    category: string;
+    components: string[];
+    code: string;
+    tags?: string[];
+}
+/**
+ * A single token entry in the compiled output
+ */
+interface CompiledTokenEntry {
+    name: string;
+    description?: string;
+}
+/**
+ * Compiled token data stored in fragments.json
+ */
+interface CompiledTokenData {
+    prefix: string;
+    total: number;
+    categories: Record<string, CompiledTokenEntry[]>;
+}
+/**
+ * The compiled fragments.json structure
+ */
+interface CompiledSegmentsFile {
+    version: string;
+    generatedAt: string;
+    packageName?: string;
+    segments: Record<string, CompiledSegment>;
+    blocks?: Record<string, CompiledBlock>;
+    tokens?: CompiledTokenData;
+    /** @deprecated Use blocks instead */
+    recipes?: Record<string, CompiledBlock>;
+}
+/**
+ * Theme identifier
+ */
+type Theme = "light" | "dark";
+/**
+ * Verification result
+ */
+interface VerifyResult {
+    verdict: "pass" | "fail" | "error";
+    matches: boolean;
+    diffPercentage: number;
+    screenshot: string;
+    baseline: string;
+    diffImage?: string;
+    notes: string[];
+    error?: string;
+    timing: {
+        renderMs: number;
+        captureMs: number;
+        diffMs: number;
+        totalMs: number;
+    };
+}
+
+export type { AIMetadata, CompiledBlock, CompiledSegment, CompiledSegmentsFile, CompiledTokenData, CompiledTokenEntry, ComponentRelation, PropDefinition, SegmentContract, SegmentGenerated, SegmentMeta, SegmentUsage, Theme, VerifyResult };

package/dist/types-B7duBj6U.d.ts

@@ -0,0 +1,39 @@
+interface SearchResult {
+    /** Unique identifier for the result. */
+    id: string;
+    /** Rank position in the result list (0-indexed). */
+    rank: number;
+    /** Optional score from the search system. */
+    score?: number;
+}
+interface RankedResult extends SearchResult {
+    /** The content or document associated with this result. */
+    content: string;
+    /** File path of the source. */
+    filePath: string;
+    /** Start line in the source file. */
+    startLine: number;
+    /** End line in the source file. */
+    endLine: number;
+}
+interface FusedResult {
+    /** Unique identifier for the result. */
+    id: string;
+    /** Fused RRF score across all result sets. */
+    fusedScore: number;
+    /** Which result sets contributed to this result. */
+    sources: string[];
+}
+interface ScoredChunk {
+    id: string;
+    content: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    language: string;
+    score: number;
+    symbolName?: string;
+    chunkType?: string;
+}
+
+export type { FusedResult as F, RankedResult as R, SearchResult as S, ScoredChunk as a };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/context",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Code intelligence and RAG primitives for design system and codebase indexing",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,6 +26,18 @@
     "./indexing": {
       "types": "./dist/indexing/index.d.ts",
       "import": "./dist/indexing/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./generate": {
+      "types": "./dist/generate/index.d.ts",
+      "import": "./dist/generate/index.js"
+    },
+    "./citations": {
+      "types": "./dist/citations/index.d.ts",
+      "import": "./dist/citations/index.js"
     }
   },
   "publishConfig": {
@@ -38,7 +50,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "lint": "eslint src",
-    "test": "vitest run",
+    "test": "vitest run --passWithNoTests",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"
   },