uilint-duplicates 0.2.27

package/dist/index.d.ts

@@ -0,0 +1,783 @@
+/**
+ * Core types for code chunking and embeddings
+ */
+type ChunkKind = "component" | "hook" | "function" | "jsx-fragment" | "jsx-section" | "component-summary" | "function-section" | "function-summary";
+interface ChunkMetadata {
+    /** Props/parameters for components and hooks */
+    props?: string[];
+    /** React hooks used in the chunk */
+    hooks?: string[];
+    /** JSX element tags used */
+    jsxElements?: string[];
+    /** Import dependencies */
+    imports?: string[];
+    /** Whether the chunk is exported */
+    isExported?: boolean;
+    /** Whether it's a default export */
+    isDefaultExport?: boolean;
+}
+interface CodeChunk {
+    /** Unique identifier (hash of content + location) */
+    id: string;
+    /** Absolute file path */
+    filePath: string;
+    /** Start line number (1-indexed) */
+    startLine: number;
+    /** End line number (1-indexed) */
+    endLine: number;
+    /** Start column */
+    startColumn: number;
+    /** End column */
+    endColumn: number;
+    /** Type of code chunk */
+    kind: ChunkKind;
+    /** Name of the function/component/hook (null if anonymous) */
+    name: string | null;
+    /** Raw source code content */
+    content: string;
+    /** Extracted metadata */
+    metadata: ChunkMetadata;
+    /** Parent chunk ID (for sub-chunks like jsx-section) */
+    parentId?: string;
+    /** Section index within parent (for ordering) */
+    sectionIndex?: number;
+    /** Human-readable section label (e.g., "header", "form-fields") */
+    sectionLabel?: string;
+}
+interface ChunkingOptions {
+    /** Minimum number of lines for a chunk (default: 3) */
+    minLines?: number;
+    /** Maximum lines before splitting a component (default: 100) */
+    maxLines?: number;
+    /** Whether to include anonymous functions (default: false) */
+    includeAnonymous?: boolean;
+    /** Chunk kinds to extract (default: all) */
+    kinds?: ChunkKind[];
+    /** Strategy for splitting large chunks (default: "jsx-children") */
+    splitStrategy?: "jsx-children" | "line-based" | "none";
+}
+
+/**
+ * Code chunker - extracts meaningful code units from TypeScript/TSX files
+ *
+ * Uses @typescript-eslint/typescript-estree for parsing.
+ * Supports splitting large components into smaller, embeddable chunks.
+ */
+
+/**
+ * Parse a file and extract code chunks
+ */
+declare function chunkFile(filePath: string, content: string, options?: ChunkingOptions): CodeChunk[];
+interface EmbeddingInputOptions {
+    /** Maximum characters for the embedding input (default: 6000) */
+    maxChars?: number;
+}
+/**
+ * Prepare chunk content for embedding by enriching with context
+ */
+declare function prepareEmbeddingInput(chunk: CodeChunk, options?: EmbeddingInputOptions): string;
+
+/**
+ * Ollama Embedding Client
+ *
+ * Uses Ollama's /api/embed endpoint to generate text embeddings.
+ * Follows the patterns from uilint-core's OllamaClient.
+ */
+interface EmbeddingOptions {
+    /** Ollama embedding model (default: nomic-embed-text) */
+    model?: string;
+    /** Ollama server URL (default: http://localhost:11434) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 60000) */
+    timeout?: number;
+    /** Batch size for embedding multiple texts (default: 10) */
+    batchSize?: number;
+}
+interface EmbeddingResult {
+    /** The embedding vector */
+    embedding: number[];
+    /** The model used */
+    model: string;
+    /** Number of tokens in the input (if available) */
+    promptTokens?: number;
+}
+declare class OllamaEmbeddingClient {
+    private baseUrl;
+    private model;
+    private timeout;
+    private batchSize;
+    constructor(options?: EmbeddingOptions);
+    /**
+     * Generate embedding for a single text
+     */
+    embed(text: string): Promise<EmbeddingResult>;
+    /**
+     * Generate embeddings for multiple texts
+     * Automatically batches large inputs
+     */
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    /**
+     * Embed a batch directly (no chunking)
+     */
+    private embedBatchDirect;
+    /**
+     * Check if Ollama is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Check if the embedding model is available
+     */
+    isModelAvailable(): Promise<boolean>;
+    /**
+     * Pull the embedding model if not available
+     */
+    ensureModel(): Promise<void>;
+    /**
+     * Get the embedding dimension for the current model
+     * (Requires generating a test embedding)
+     */
+    getEmbeddingDimension(): Promise<number>;
+    /**
+     * Get the current model name
+     */
+    getModel(): string;
+    /**
+     * Set the model name
+     */
+    setModel(model: string): void;
+}
+declare function getOllamaEmbeddingClient(options?: EmbeddingOptions): OllamaEmbeddingClient;
+
+/**
+ * Vector Store
+ *
+ * File-based vector storage with cosine similarity search.
+ * Uses binary Float32 format for efficient storage.
+ */
+interface SimilarityResult {
+    /** Chunk ID */
+    id: string;
+    /** Cosine similarity score (0-1) */
+    score: number;
+    /** Distance (1 - score) */
+    distance: number;
+}
+interface VectorStoreOptions {
+    /** Expected dimension of vectors (validated on add) */
+    dimension?: number;
+}
+declare class VectorStore {
+    private vectors;
+    private dimension;
+    private idIndex;
+    constructor(options?: VectorStoreOptions);
+    /**
+     * Add a vector to the store
+     */
+    add(id: string, vector: number[]): void;
+    /**
+     * Add multiple vectors at once
+     */
+    addBatch(items: Array<{
+        id: string;
+        vector: number[];
+    }>): void;
+    /**
+     * Remove a vector from the store
+     */
+    remove(id: string): boolean;
+    /**
+     * Get a vector by ID
+     */
+    get(id: string): number[] | null;
+    /**
+     * Check if a vector exists
+     */
+    has(id: string): boolean;
+    /**
+     * Find the most similar vectors to a query vector
+     */
+    findSimilar(query: number[], k?: number, threshold?: number): SimilarityResult[];
+    /**
+     * Get the number of vectors in the store
+     */
+    size(): number;
+    /**
+     * Get the dimension of vectors
+     */
+    getDimension(): number | null;
+    /**
+     * Get all IDs
+     */
+    getIds(): string[];
+    /**
+     * Clear all vectors
+     */
+    clear(): void;
+    /**
+     * Save the vector store to disk
+     *
+     * Format:
+     * - embeddings.bin: Binary Float32 vectors
+     * - ids.json: Ordered array of IDs matching vector positions
+     */
+    save(dirPath: string): Promise<void>;
+    /**
+     * Load the vector store from disk
+     */
+    load(dirPath: string): Promise<void>;
+    /**
+     * Iterate over all vectors
+     */
+    entries(): IterableIterator<[string, number[]]>;
+    /**
+     * Get stats about the store
+     */
+    getStats(): {
+        size: number;
+        dimension: number | null;
+        memoryBytes: number;
+    };
+}
+
+/**
+ * Types for the index module
+ */
+
+/**
+ * Metadata stored for each chunk in the metadata store
+ */
+interface StoredChunkMetadata {
+    /** Absolute file path */
+    filePath: string;
+    /** Start line number (1-indexed) */
+    startLine: number;
+    /** End line number (1-indexed) */
+    endLine: number;
+    /** Start column */
+    startColumn: number;
+    /** End column */
+    endColumn: number;
+    /** Type of code chunk */
+    kind: ChunkKind;
+    /** Name of the function/component/hook (null if anonymous) */
+    name: string | null;
+    /** Hash of the content for change detection */
+    contentHash: string;
+    /** Extracted metadata */
+    metadata: ChunkMetadata;
+}
+/**
+ * Manifest for the index
+ */
+interface IndexManifest {
+    /** Version of the index format */
+    version: number;
+    /** Timestamp when the index was created */
+    createdAt: string;
+    /** Timestamp when the index was last updated */
+    updatedAt: string;
+    /** Number of chunks in the index */
+    chunkCount: number;
+    /** Number of files indexed */
+    fileCount: number;
+    /** Embedding model used */
+    embeddingModel: string;
+    /** Vector dimension */
+    dimension: number;
+}
+
+/**
+ * Metadata Store
+ *
+ * JSON-based storage for chunk metadata (file paths, line numbers, etc.)
+ */
+
+declare class MetadataStore {
+    private chunks;
+    /**
+     * Add or update chunk metadata
+     */
+    set(id: string, metadata: StoredChunkMetadata): void;
+    /**
+     * Add multiple chunks at once
+     */
+    setBatch(items: Array<{
+        id: string;
+        metadata: StoredChunkMetadata;
+    }>): void;
+    /**
+     * Get chunk metadata by ID
+     */
+    get(id: string): StoredChunkMetadata | null;
+    /**
+     * Check if a chunk exists
+     */
+    has(id: string): boolean;
+    /**
+     * Remove chunk metadata
+     */
+    remove(id: string): boolean;
+    /**
+     * Remove all chunks for a given file path
+     */
+    removeByFilePath(filePath: string): string[];
+    /**
+     * Get all chunks for a given file path
+     */
+    getByFilePath(filePath: string): Array<{
+        id: string;
+        metadata: StoredChunkMetadata;
+    }>;
+    /**
+     * Get chunk by content hash
+     */
+    getByContentHash(contentHash: string): {
+        id: string;
+        metadata: StoredChunkMetadata;
+    } | null;
+    /**
+     * Get chunk at a specific location
+     */
+    getAtLocation(filePath: string, line: number): {
+        id: string;
+        metadata: StoredChunkMetadata;
+    } | null;
+    /**
+     * Get all unique file paths
+     */
+    getFilePaths(): string[];
+    /**
+     * Get number of chunks
+     */
+    size(): number;
+    /**
+     * Clear all metadata
+     */
+    clear(): void;
+    /**
+     * Iterate over all chunks
+     */
+    entries(): IterableIterator<[string, StoredChunkMetadata]>;
+    /**
+     * Get all IDs
+     */
+    getIds(): string[];
+    /**
+     * Save to disk
+     */
+    save(dirPath: string): Promise<void>;
+    /**
+     * Load from disk
+     */
+    load(dirPath: string): Promise<void>;
+    /**
+     * Filter chunks by kind
+     */
+    filterByKind(kind: string): Array<{
+        id: string;
+        metadata: StoredChunkMetadata;
+    }>;
+    /**
+     * Search by name (case-insensitive partial match)
+     */
+    searchByName(query: string): Array<{
+        id: string;
+        metadata: StoredChunkMetadata;
+    }>;
+}
+
+/**
+ * Incremental Indexer
+ *
+ * Combines chunker, embedding client, and storage to build and update
+ * the semantic index incrementally.
+ */
+
+interface IndexerOptions {
+    /** Embedding model to use */
+    model?: string;
+    /** Ollama server URL */
+    baseUrl?: string;
+    /** Glob patterns to include (default: **\/*.{ts,tsx,js,jsx}) */
+    include?: string[];
+    /** Glob patterns to exclude */
+    exclude?: string[];
+    /** Chunking options */
+    chunking?: ChunkingOptions;
+    /** Progress callback */
+    onProgress?: (message: string, current?: number, total?: number) => void;
+}
+interface IndexUpdateResult {
+    /** Number of files added */
+    added: number;
+    /** Number of files modified */
+    modified: number;
+    /** Number of files deleted */
+    deleted: number;
+    /** Total chunks in index */
+    totalChunks: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+declare class IncrementalIndexer {
+    private vectorStore;
+    private metadataStore;
+    private fileTracker;
+    private embeddingClient;
+    private projectRoot;
+    private indexDir;
+    private options;
+    private manifest;
+    constructor(projectRoot: string, options?: IndexerOptions);
+    /**
+     * Get the include patterns
+     */
+    private getIncludePatterns;
+    /**
+     * Get the exclude patterns
+     */
+    private getExcludePatterns;
+    /**
+     * Find all files to index
+     */
+    private findFiles;
+    /**
+     * Load existing index from disk
+     */
+    load(): Promise<void>;
+    /**
+     * Save index to disk
+     */
+    save(): Promise<void>;
+    /**
+     * Index all files from scratch
+     */
+    indexAll(force?: boolean): Promise<IndexUpdateResult>;
+    /**
+     * Update index incrementally
+     */
+    update(): Promise<IndexUpdateResult>;
+    /**
+     * Process file changes
+     */
+    private processChanges;
+    /**
+     * Get index statistics
+     */
+    getStats(): {
+        totalFiles: number;
+        totalChunks: number;
+        indexSizeBytes: number;
+        manifest: IndexManifest | null;
+    };
+    /**
+     * Get the vector store (for queries)
+     */
+    getVectorStore(): VectorStore;
+    /**
+     * Get the metadata store (for queries)
+     */
+    getMetadataStore(): MetadataStore;
+    /**
+     * Check if index exists
+     */
+    hasIndex(): boolean;
+}
+/**
+ * Create an indexer for a project
+ */
+declare function createIndexer(projectRoot: string, options?: IndexerOptions): IncrementalIndexer;
+
+/**
+ * Query API for semantic duplicate detection
+ *
+ * High-level API for indexing, finding duplicates, and semantic search.
+ */
+
+interface IndexOptions {
+    /** Embedding model to use */
+    model?: string;
+    /** Ollama server URL */
+    baseUrl?: string;
+    /** Glob patterns to exclude */
+    exclude?: string[];
+    /** Force reindex from scratch */
+    force?: boolean;
+    /** Progress callback */
+    onProgress?: (message: string, current?: number, total?: number) => void;
+}
+interface FindDuplicatesOptions$1 {
+    /** Path to search (defaults to current directory) */
+    path?: string;
+    /** Minimum similarity threshold (0-1). Default: 0.85 */
+    threshold?: number;
+    /** Minimum group size. Default: 2 */
+    minGroupSize?: number;
+    /** Filter by kind: component, hook, function */
+    kind?: ChunkKind;
+}
+interface SearchOptions {
+    /** Path to search (defaults to current directory) */
+    path?: string;
+    /** Number of results to return. Default: 10 */
+    top?: number;
+    /** Minimum similarity threshold. Default: 0.5 */
+    threshold?: number;
+    /** Embedding model to use */
+    model?: string;
+    /** Ollama server URL */
+    baseUrl?: string;
+}
+interface SimilarLocationOptions extends SearchOptions {
+    /** File path containing the code */
+    filePath: string;
+    /** Line number in the file */
+    line: number;
+}
+interface DuplicateGroupMember {
+    /** File path */
+    filePath: string;
+    /** Start line */
+    startLine: number;
+    /** End line */
+    endLine: number;
+    /** Chunk name (component/function/hook name) */
+    name: string | null;
+    /** Kind of code */
+    kind: ChunkKind;
+    /** Similarity score (1.0 for the reference member) */
+    score: number;
+}
+interface DuplicateGroup$1 {
+    /** Members of the duplicate group */
+    members: DuplicateGroupMember[];
+    /** Average similarity between all group members */
+    avgSimilarity: number;
+    /** The kind of code in this group */
+    kind: ChunkKind;
+}
+interface SearchResult {
+    /** File path */
+    filePath: string;
+    /** Start line */
+    startLine: number;
+    /** End line */
+    endLine: number;
+    /** Chunk name */
+    name: string | null;
+    /** Kind of code */
+    kind: ChunkKind;
+    /** Similarity score */
+    score: number;
+}
+/**
+ * Clear the indexer cache for a path.
+ */
+declare function clearIndexerCache(path?: string): void;
+/**
+ * Index a directory for semantic duplicate detection.
+ * Creates or updates the index at .uilint/.duplicates-index/
+ */
+declare function indexDirectory(path: string, options?: IndexOptions): Promise<IndexUpdateResult>;
+/**
+ * Find semantic duplicate groups in the indexed codebase.
+ */
+declare function findDuplicates(options?: FindDuplicatesOptions$1): Promise<DuplicateGroup$1[]>;
+/**
+ * Search for code semantically similar to a text query.
+ */
+declare function searchSimilar(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+/**
+ * Find code similar to a specific location (file:line).
+ */
+declare function findSimilarAtLocation(options: SimilarLocationOptions): Promise<SearchResult[]>;
+/**
+ * Check if an index exists for the given path.
+ */
+declare function hasIndex(path?: string): boolean;
+/**
+ * Get index statistics.
+ */
+declare function getIndexStats(path?: string): Promise<{
+    totalFiles: number;
+    totalChunks: number;
+    indexSizeBytes: number;
+    embeddingModel: string | null;
+    lastUpdated: string | null;
+}>;
+
+/**
+ * Duplicate Finder
+ *
+ * Finds groups of semantically similar code chunks using the vector index.
+ */
+
+interface DuplicateMember {
+    /** Chunk ID */
+    id: string;
+    /** Chunk metadata */
+    metadata: StoredChunkMetadata;
+    /** Similarity score to the group centroid/first member */
+    score: number;
+}
+interface DuplicateGroup {
+    /** Members of the duplicate group */
+    members: DuplicateMember[];
+    /** Average similarity between all group members */
+    avgSimilarity: number;
+    /** The kind of code in this group (component, hook, function) */
+    kind: ChunkKind;
+}
+interface FindDuplicatesOptions {
+    /** Minimum cosine similarity threshold (0-1). Default: 0.85 */
+    threshold?: number;
+    /** Minimum group size. Default: 2 */
+    minGroupSize?: number;
+    /** Filter by chunk kind */
+    kind?: ChunkKind;
+    /** Exclude specific file paths */
+    excludePaths?: string[];
+}
+/**
+ * Find groups of semantically similar code.
+ *
+ * Algorithm:
+ * 1. Iterate through all chunks
+ * 2. For each unprocessed chunk, find similar chunks above threshold
+ * 3. Group similar chunks together
+ * 4. Mark all grouped chunks as processed
+ * 5. Sort groups by size and similarity
+ */
+declare function findDuplicateGroups(vectorStore: VectorStore, metadataStore: MetadataStore, options?: FindDuplicatesOptions): DuplicateGroup[];
+/**
+ * Find similar code to a given location (file:line).
+ */
+declare function findSimilarToLocation(vectorStore: VectorStore, metadataStore: MetadataStore, filePath: string, line: number, options?: {
+    top?: number;
+    threshold?: number;
+}): SimilarityResult[];
+/**
+ * Search for code similar to a text query.
+ * Requires embedding the query first.
+ */
+declare function findSimilarToQuery(vectorStore: VectorStore, queryEmbedding: number[], options?: {
+    top?: number;
+    threshold?: number;
+}): SimilarityResult[];
+
+/**
+ * Duplicate Scorer
+ *
+ * Provides scoring functions for ranking duplicate code groups.
+ */
+
+interface DuplicateScore {
+    /** Embedding cosine similarity (0-1) */
+    similarity: number;
+    /** Ratio of code size similarity (0-1) */
+    sizeRatio: number;
+    /** Weighted combined score */
+    combinedScore: number;
+}
+/**
+ * Calculate the size ratio between two code chunks.
+ * Returns a value between 0 and 1 where 1 means identical size.
+ */
+declare function calculateSizeRatio(chunk1: StoredChunkMetadata, chunk2: StoredChunkMetadata): number;
+/**
+ * Calculate a combined duplicate score.
+ */
+declare function calculateDuplicateScore(similarity: number, chunk1: StoredChunkMetadata, chunk2: StoredChunkMetadata): DuplicateScore;
+/**
+ * Calculate the average similarity of a duplicate group.
+ */
+declare function calculateGroupAverageSimilarity(similarities: number[]): number;
+/**
+ * Sort duplicate groups by relevance.
+ * Groups are sorted by: member count (desc), then average similarity (desc).
+ */
+declare function sortDuplicateGroups<T extends {
+    avgSimilarity: number;
+    members: unknown[];
+}>(groups: T[]): T[];
+
+/**
+ * File Tracker
+ *
+ * Tracks file content hashes for incremental updates.
+ * Uses xxhash for fast hashing (following uilint-eslint patterns).
+ */
+/**
+ * Hash content using xxhash (async) or djb2 (sync fallback)
+ */
+declare function hashContent(content: string): Promise<string>;
+/**
+ * Synchronous hash for when async is not possible
+ */
+declare function hashContentSync(content: string): string;
+interface FileHashEntry {
+    /** xxhash of file content */
+    contentHash: string;
+    /** Last modification time in ms */
+    mtimeMs: number;
+    /** IDs of chunks from this file */
+    chunkIds: string[];
+}
+interface HashStore {
+    version: number;
+    files: Record<string, FileHashEntry>;
+}
+interface FileChange {
+    path: string;
+    type: "added" | "modified" | "deleted";
+    oldHash?: string;
+    newHash?: string;
+}
+declare class FileTracker {
+    private store;
+    /**
+     * Get the hash entry for a file
+     */
+    getEntry(filePath: string): FileHashEntry | null;
+    /**
+     * Set the hash entry for a file
+     */
+    setEntry(filePath: string, entry: FileHashEntry): void;
+    /**
+     * Remove the hash entry for a file
+     */
+    removeEntry(filePath: string): boolean;
+    /**
+     * Get all tracked file paths
+     */
+    getTrackedFiles(): string[];
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Detect changes between current files and stored hashes
+     */
+    detectChanges(files: string[]): Promise<FileChange[]>;
+    /**
+     * Update stored hash for a file
+     */
+    updateFile(filePath: string, content: string, chunkIds: string[]): Promise<void>;
+    /**
+     * Save to disk
+     */
+    save(dirPath: string): Promise<void>;
+    /**
+     * Load from disk
+     */
+    load(dirPath: string): Promise<void>;
+    /**
+     * Get stats
+     */
+    getStats(): {
+        trackedFiles: number;
+    };
+}
+
+export { type ChunkKind, type ChunkMetadata, type ChunkingOptions, type CodeChunk, type DuplicateGroup$1 as DuplicateGroup, type DuplicateGroupMember, type DuplicateMember, type DuplicateScore, type EmbeddingOptions, type EmbeddingResult, type FileChange, type FileHashEntry, FileTracker, type FindDuplicatesOptions$1 as FindDuplicatesOptions, type HashStore, IncrementalIndexer, type IndexManifest, type IndexOptions, type IndexUpdateResult, type IndexerOptions, type DuplicateGroup as InternalDuplicateGroup, type FindDuplicatesOptions as InternalFindDuplicatesOptions, MetadataStore, OllamaEmbeddingClient, type SearchOptions, type SearchResult, type SimilarLocationOptions, type SimilarityResult, type StoredChunkMetadata, VectorStore, type VectorStoreOptions, calculateDuplicateScore, calculateGroupAverageSimilarity, calculateSizeRatio, chunkFile, clearIndexerCache, createIndexer, findDuplicateGroups, findDuplicates, findSimilarAtLocation, findSimilarToLocation, findSimilarToQuery, getIndexStats, getOllamaEmbeddingClient, hasIndex, hashContent, hashContentSync, indexDirectory, prepareEmbeddingInput, searchSimilar, sortDuplicateGroups };