@fragments-sdk/context 0.1.3 → 0.2.0

package/dist/indexing/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Compute a SHA-256 hash of the given content.
+ * Used for incremental indexing — only re-embed files whose hash has changed.
+ */
+declare function hashContent(content: string): string;
+
+interface FileEntry {
+    /** File path relative to repo root. */
+    filePath: string;
+    /** SHA-256 content hash. */
+    contentHash: string;
+    /** Optional: IDs of chunks generated from this file. */
+    chunkIds?: string[];
+}
+interface ChangedFiles {
+    /** Files that are new (not in old set). */
+    added: string[];
+    /** Files that exist in both but have different content hashes. */
+    modified: string[];
+    /** Files that were in old set but not in new set. */
+    deleted: string[];
+    /** Files that are unchanged. */
+    unchanged: string[];
+}
+/** Mapping from file extension to tree-sitter grammar name. */
+interface GrammarMapping {
+    extension: string;
+    language: string;
+    treeSitterGrammar: string;
+}
+
+/**
+ * Compare old and new file entry lists to determine which files were
+ * added, modified, deleted, or unchanged.
+ *
+ * Uses content hashes for comparison — two files with identical content
+ * are considered unchanged even if their metadata differs.
+ */
+declare function resolveChanges(oldEntries: FileEntry[], newEntries: FileEntry[]): ChangedFiles;
+
+declare const INDEXABLE_EXTENSIONS: Set<string>;
+declare function shouldIndexFile(path: string, size: number): boolean;
+/** Languages that have tree-sitter grammar support for AST chunking. */
+declare const AST_SUPPORTED_LANGUAGES: Set<string>;
+declare function detectLanguage(path: string): string;
+/**
+ * Get the tree-sitter grammar name for a file extension.
+ * Returns empty string if no grammar is available (falls back to line chunker).
+ */
+declare function getTreeSitterGrammar(path: string): string;
+
+export { AST_SUPPORTED_LANGUAGES, type ChangedFiles, type FileEntry, type GrammarMapping, INDEXABLE_EXTENSIONS, detectLanguage, getTreeSitterGrammar, hashContent, resolveChanges, shouldIndexFile };

package/dist/indexing/index.js

@@ -0,0 +1,20 @@
+import {
+  hashContent,
+  resolveChanges
+} from "../chunk-HINI3FCI.js";
+import {
+  AST_SUPPORTED_LANGUAGES,
+  INDEXABLE_EXTENSIONS,
+  detectLanguage,
+  getTreeSitterGrammar,
+  shouldIndexFile
+} from "../chunk-JFV27WLV.js";
+export {
+  AST_SUPPORTED_LANGUAGES,
+  INDEXABLE_EXTENSIONS,
+  detectLanguage,
+  getTreeSitterGrammar,
+  hashContent,
+  resolveChanges,
+  shouldIndexFile
+};

package/dist/search/index.d.ts

@@ -0,0 +1,29 @@
+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
+ * into a single ranking using the formula: score = sum(1 / (k + rank))
+ *
+ * This is a standard technique for combining results from different
+ * search systems (e.g., vector search + BM25 full-text search).
+ *
+ * @param resultSets - Array of result sets, each with a label and ranked results
+ * @param k - Smoothing constant (default: 60, as per the original RRF paper)
+ * @returns Fused results sorted by combined score (highest first)
+ */
+declare function reciprocalRankFusion(resultSets: Array<{
+    label: string;
+    results: SearchResult[];
+}>, k?: number): FusedResult[];
+
+/**
+ * Deduplicate and merge overlapping chunks from the same file.
+ *
+ * When hybrid search + reranking returns multiple chunks from the same file
+ * with overlapping line ranges, merge them into a single contiguous block
+ * to avoid redundancy in the LLM context window.
+ */
+declare function deduplicateChunks(chunks: ScoredChunk[]): ScoredChunk[];
+
+export { FusedResult, ScoredChunk, SearchResult, deduplicateChunks, reciprocalRankFusion };

package/dist/search/index.js

@@ -0,0 +1,8 @@
+import {
+  deduplicateChunks,
+  reciprocalRankFusion
+} from "../chunk-ZMBYQK43.js";
+export {
+  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.3",
+  "version": "0.2.0",
   "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": {