@codragraph/cli 1.6.2

package/dist/core/embeddings/types.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Embedding Pipeline Types
+ *
+ * Type definitions for the embedding generation and semantic search system.
+ */
+export declare const LABEL_FUNCTION: "Function";
+export declare const LABEL_METHOD: "Method";
+export declare const LABEL_CONSTRUCTOR: "Constructor";
+export declare const LABEL_CLASS: "Class";
+export declare const LABEL_INTERFACE: "Interface";
+export declare const LABEL_STRUCT: "Struct";
+export declare const LABEL_ENUM: "Enum";
+export declare const LABEL_TRAIT: "Trait";
+export declare const LABEL_IMPL: "Impl";
+export declare const LABEL_MACRO: "Macro";
+export declare const LABEL_NAMESPACE: "Namespace";
+export declare const LABEL_TYPE_ALIAS: "TypeAlias";
+export declare const LABEL_TYPEDEF: "Typedef";
+export declare const LABEL_CONST: "Const";
+export declare const LABEL_PROPERTY: "Property";
+export declare const LABEL_RECORD: "Record";
+export declare const LABEL_UNION: "Union";
+export declare const LABEL_STATIC: "Static";
+export declare const LABEL_VARIABLE: "Variable";
+export declare const LABEL_CODE_ELEMENT: "CodeElement";
+export declare const CHUNK_MODE_AST_FUNCTION: "ast-function";
+export declare const CHUNK_MODE_AST_DECLARATION: "ast-declaration";
+export declare const CHUNK_MODE_CHARACTER: "character";
+export declare const STRUCTURAL_TEXT_MODE_NONE: "none";
+export declare const STRUCTURAL_TEXT_MODE_DECLARATION: "declaration";
+export interface ChunkingRule {
+    mode: typeof CHUNK_MODE_AST_FUNCTION | typeof CHUNK_MODE_AST_DECLARATION | typeof CHUNK_MODE_CHARACTER;
+    includePrefix: boolean;
+    includeSuffix: boolean;
+    groupFields: boolean;
+    structuralTextMode: typeof STRUCTURAL_TEXT_MODE_NONE | typeof STRUCTURAL_TEXT_MODE_DECLARATION;
+}
+/**
+ * Node labels that need chunking (have code body, potentially long)
+ */
+export declare const CHUNKABLE_LABELS: readonly ["Function", "Method", "Constructor", "Class", "Interface", "Struct", "Enum", "Trait", "Impl", "Macro", "Namespace"];
+/**
+ * Node labels that are short (no chunking needed, embed directly)
+ */
+export declare const SHORT_LABELS: readonly ["TypeAlias", "Typedef", "Const", "Property", "Record", "Union", "Static", "Variable"];
+/**
+ * All embeddable labels (union of CHUNKABLE + SHORT)
+ */
+export declare const EMBEDDABLE_LABELS: readonly ["Function", "Method", "Constructor", "Class", "Interface", "Struct", "Enum", "Trait", "Impl", "Macro", "Namespace", "TypeAlias", "Typedef", "Const", "Property", "Record", "Union", "Static", "Variable"];
+export type EmbeddableLabel = (typeof EMBEDDABLE_LABELS)[number];
+/**
+ * Check if a label should be embedded
+ */
+export declare const isEmbeddableLabel: (label: string) => label is EmbeddableLabel;
+/**
+ * Check if a label needs chunking
+ */
+export declare const isChunkableLabel: (label: string) => boolean;
+/**
+ * Check if a label is a short type (no chunking)
+ */
+export declare const isShortLabel: (label: string) => boolean;
+/**
+ * Node labels that have structural names (methods/fields) extractable via AST.
+ * Only labels that consume methodNames/fieldNames in their embedding text should
+ * be listed here — extra entries trigger wasted AST parses with no effect on output.
+ */
+export declare const STRUCTURAL_LABELS: ReadonlySet<string>;
+/**
+ * Node labels that have isExported column in their schema
+ */
+export declare const LABELS_WITH_EXPORTED: ReadonlySet<string>;
+/**
+ * Labels that need special chunking and/or structural text semantics.
+ * Any chunkable label omitted here intentionally falls back to characterChunk
+ * plus generateCodeBodyText (for example Enum/Trait/Impl/Macro/Namespace).
+ */
+type ChunkableLabel = (typeof CHUNKABLE_LABELS)[number];
+export declare const CHUNKING_RULES: Readonly<Partial<Record<ChunkableLabel, ChunkingRule>>>;
+/**
+ * Embedding pipeline phases
+ */
+export type EmbeddingPhase = 'idle' | 'loading-model' | 'embedding' | 'indexing' | 'ready' | 'error';
+/**
+ * Progress information for the embedding pipeline
+ */
+export interface EmbeddingProgress {
+    phase: EmbeddingPhase;
+    percent: number;
+    modelDownloadPercent?: number;
+    nodesProcessed?: number;
+    totalNodes?: number;
+    currentBatch?: number;
+    totalBatches?: number;
+    error?: string;
+}
+/**
+ * Configuration for the embedding pipeline
+ */
+export interface EmbeddingConfig {
+    /** Model identifier for transformers.js (local) or the HTTP endpoint model name */
+    modelId: string;
+    /** Number of nodes to embed in each batch */
+    batchSize: number;
+    /** Embedding vector dimensions */
+    dimensions: number;
+    /** Device to use for inference: 'auto' tries GPU first (DirectML on Windows, CUDA on Linux), falls back to CPU */
+    device: 'auto' | 'dml' | 'cuda' | 'cpu' | 'wasm';
+    /** Maximum characters of code snippet to include */
+    maxSnippetLength: number;
+    /** Maximum code chunk size in characters (for chunking long code) */
+    chunkSize: number;
+    /** Overlap between chunks in characters */
+    overlap: number;
+    /** Maximum description length in characters */
+    maxDescriptionLength: number;
+}
+/**
+ * Default embedding configuration
+ * Uses snowflake-arctic-embed-xs for browser efficiency
+ * Tries WebGPU first (fast), user can choose WASM fallback if unavailable
+ */
+export declare const DEFAULT_EMBEDDING_CONFIG: EmbeddingConfig;
+/**
+ * Result from semantic search
+ */
+export interface SemanticSearchResult {
+    nodeId: string;
+    name: string;
+    label: string;
+    filePath: string;
+    distance: number;
+    startLine?: number;
+    endLine?: number;
+}
+/**
+ * Node data for embedding (minimal structure from LadybugDB query)
+ */
+export interface EmbeddableNode {
+    id: string;
+    name: string;
+    label: string;
+    filePath: string;
+    content: string;
+    startLine?: number;
+    endLine?: number;
+    isExported?: boolean;
+    description?: string;
+    parameterCount?: number;
+    returnType?: string;
+    repoName?: string;
+    serverName?: string;
+    methodNames?: string[];
+    fieldNames?: string[];
+}
+/**
+ * Cached embedding entry restored from LadybugDB before a graph rebuild
+ */
+export interface CachedEmbedding {
+    nodeId: string;
+    chunkIndex: number;
+    startLine: number;
+    endLine: number;
+    embedding: number[];
+    contentHash?: string;
+}
+/**
+ * Context info for embedding pipeline (repo/server metadata enrichment)
+ */
+export interface EmbeddingContext {
+    repoName?: string;
+    serverName?: string;
+}
+/**
+ * Model download progress from transformers.js
+ */
+export interface ModelProgress {
+    status: 'initiate' | 'download' | 'progress' | 'done' | 'ready';
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+}
+export interface ChunkSearchRow {
+    nodeId: string;
+    chunkIndex: number;
+    startLine: number;
+    endLine: number;
+    distance: number;
+}
+export interface BestChunkMatch {
+    chunkIndex: number;
+    startLine: number;
+    endLine: number;
+    distance: number;
+}
+/**
+ * Deduplicate vector search chunk results by nodeId,
+ * keeping the chunk with smallest distance for each node.
+ */
+export declare const dedupBestChunks: (rows: ChunkSearchRow[], limit?: number) => Map<string, BestChunkMatch>;
+/**
+ * Fetch vector-search chunks until we have enough unique nodeIds
+ * or can tell the result set is exhausted.
+ */
+export declare const collectBestChunks: (limit: number, fetchRows: (fetchLimit: number) => Promise<ChunkSearchRow[]>, maxFetch?: number) => Promise<Map<string, BestChunkMatch>>;
+export {};

package/dist/core/embeddings/types.js

@@ -0,0 +1,200 @@
+/**
+ * Embedding Pipeline Types
+ *
+ * Type definitions for the embedding generation and semantic search system.
+ */
+export const LABEL_FUNCTION = 'Function';
+export const LABEL_METHOD = 'Method';
+export const LABEL_CONSTRUCTOR = 'Constructor';
+export const LABEL_CLASS = 'Class';
+export const LABEL_INTERFACE = 'Interface';
+export const LABEL_STRUCT = 'Struct';
+export const LABEL_ENUM = 'Enum';
+export const LABEL_TRAIT = 'Trait';
+export const LABEL_IMPL = 'Impl';
+export const LABEL_MACRO = 'Macro';
+export const LABEL_NAMESPACE = 'Namespace';
+export const LABEL_TYPE_ALIAS = 'TypeAlias';
+export const LABEL_TYPEDEF = 'Typedef';
+export const LABEL_CONST = 'Const';
+export const LABEL_PROPERTY = 'Property';
+export const LABEL_RECORD = 'Record';
+export const LABEL_UNION = 'Union';
+export const LABEL_STATIC = 'Static';
+export const LABEL_VARIABLE = 'Variable';
+export const LABEL_CODE_ELEMENT = 'CodeElement';
+export const CHUNK_MODE_AST_FUNCTION = 'ast-function';
+export const CHUNK_MODE_AST_DECLARATION = 'ast-declaration';
+// CHUNK_MODE_CHARACTER exists for type completeness but is a no-op in CHUNKING_RULES —
+// omit the entry entirely to get character fallback via chunker.ts dispatch.
+export const CHUNK_MODE_CHARACTER = 'character';
+export const STRUCTURAL_TEXT_MODE_NONE = 'none';
+export const STRUCTURAL_TEXT_MODE_DECLARATION = 'declaration';
+/**
+ * Node labels that need chunking (have code body, potentially long)
+ */
+export const CHUNKABLE_LABELS = [
+    LABEL_FUNCTION,
+    LABEL_METHOD,
+    LABEL_CONSTRUCTOR,
+    LABEL_CLASS,
+    LABEL_INTERFACE,
+    LABEL_STRUCT,
+    LABEL_ENUM,
+    LABEL_TRAIT,
+    LABEL_IMPL,
+    LABEL_MACRO,
+    LABEL_NAMESPACE,
+];
+/**
+ * Node labels that are short (no chunking needed, embed directly)
+ */
+export const SHORT_LABELS = [
+    LABEL_TYPE_ALIAS,
+    LABEL_TYPEDEF,
+    LABEL_CONST,
+    LABEL_PROPERTY,
+    LABEL_RECORD,
+    LABEL_UNION,
+    LABEL_STATIC,
+    LABEL_VARIABLE,
+];
+/**
+ * All embeddable labels (union of CHUNKABLE + SHORT)
+ */
+export const EMBEDDABLE_LABELS = [...CHUNKABLE_LABELS, ...SHORT_LABELS];
+/**
+ * Check if a label should be embedded
+ */
+export const isEmbeddableLabel = (label) => EMBEDDABLE_LABELS.includes(label);
+/**
+ * Check if a label needs chunking
+ */
+export const isChunkableLabel = (label) => CHUNKABLE_LABELS.includes(label);
+/**
+ * Check if a label is a short type (no chunking)
+ */
+export const isShortLabel = (label) => SHORT_LABELS.includes(label);
+/**
+ * Node labels that have structural names (methods/fields) extractable via AST.
+ * Only labels that consume methodNames/fieldNames in their embedding text should
+ * be listed here — extra entries trigger wasted AST parses with no effect on output.
+ */
+export const STRUCTURAL_LABELS = new Set([
+    LABEL_CLASS,
+    LABEL_STRUCT,
+    LABEL_INTERFACE,
+]);
+/**
+ * Node labels that have isExported column in their schema
+ */
+export const LABELS_WITH_EXPORTED = new Set([
+    LABEL_FUNCTION,
+    LABEL_CLASS,
+    LABEL_INTERFACE,
+    LABEL_METHOD,
+    LABEL_CODE_ELEMENT,
+]);
+export const CHUNKING_RULES = {
+    [LABEL_FUNCTION]: {
+        mode: CHUNK_MODE_AST_FUNCTION,
+        includePrefix: true,
+        includeSuffix: true,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
+    [LABEL_METHOD]: {
+        mode: CHUNK_MODE_AST_FUNCTION,
+        includePrefix: true,
+        includeSuffix: true,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
+    [LABEL_CONSTRUCTOR]: {
+        mode: CHUNK_MODE_AST_FUNCTION,
+        includePrefix: true,
+        includeSuffix: true,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
+    [LABEL_CLASS]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: true,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+    },
+    [LABEL_INTERFACE]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+    },
+    [LABEL_STRUCT]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: true,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+    },
+};
+/**
+ * Default embedding configuration
+ * Uses snowflake-arctic-embed-xs for browser efficiency
+ * Tries WebGPU first (fast), user can choose WASM fallback if unavailable
+ */
+export const DEFAULT_EMBEDDING_CONFIG = {
+    modelId: 'Snowflake/snowflake-arctic-embed-xs',
+    batchSize: 16,
+    dimensions: 384,
+    device: 'auto',
+    maxSnippetLength: 500,
+    chunkSize: 1200,
+    overlap: 120,
+    maxDescriptionLength: 150,
+};
+/**
+ * Deduplicate vector search chunk results by nodeId,
+ * keeping the chunk with smallest distance for each node.
+ */
+export const dedupBestChunks = (rows, limit) => {
+    const best = new Map();
+    for (const row of rows) {
+        const existing = best.get(row.nodeId);
+        if (!existing || row.distance < existing.distance) {
+            best.set(row.nodeId, {
+                chunkIndex: row.chunkIndex,
+                startLine: row.startLine,
+                endLine: row.endLine,
+                distance: row.distance,
+            });
+        }
+        if (limit !== undefined && best.size >= limit)
+            break;
+    }
+    return best;
+};
+const DEFAULT_FETCH_MULTIPLIER = 4;
+const DEFAULT_FETCH_BUFFER = 8;
+const DEFAULT_MAX_FETCH = 200;
+/**
+ * Fetch vector-search chunks until we have enough unique nodeIds
+ * or can tell the result set is exhausted.
+ */
+export const collectBestChunks = async (limit, fetchRows, maxFetch = DEFAULT_MAX_FETCH) => {
+    if (limit <= 0)
+        return new Map();
+    let fetchLimit = Math.max(limit * DEFAULT_FETCH_MULTIPLIER, limit + DEFAULT_FETCH_BUFFER);
+    let previousFetchLimit = 0;
+    while (fetchLimit > previousFetchLimit) {
+        const rows = await fetchRows(fetchLimit);
+        const bestChunks = dedupBestChunks(rows, limit);
+        if (bestChunks.size >= limit || rows.length < fetchLimit) {
+            return bestChunks;
+        }
+        previousFetchLimit = fetchLimit;
+        fetchLimit = fetchLimit >= maxFetch ? fetchLimit * 2 : Math.min(maxFetch, fetchLimit * 2);
+    }
+    return new Map();
+};

package/dist/core/git-staleness.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Git working tree vs index commit staleness (used by MCP resources, group status, etc.).
+ * Lives in core/ so application code does not depend on the MCP package layer.
+ */
+import { type CwdMatch } from '../storage/repo-manager.js';
+export interface StalenessInfo {
+    isStale: boolean;
+    commitsBehind: number;
+    hint?: string;
+}
+/**
+ * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
+ */
+export declare function checkStaleness(repoPath: string, lastCommit: string): StalenessInfo;
+/**
+ * Resolve a working directory against the global registry. Returns:
+ *   - `match: 'path'`              when `cwd` is inside a registered entry's path
+ *   - `match: 'sibling-by-remote'` when `cwd` lives in a different on-disk clone
+ *                                   of the same repo (same `remoteUrl`)
+ *   - `match: 'none'`              when neither match applies
+ *
+ * For sibling-by-remote matches, the caller's HEAD and the drift vs the
+ * indexed `lastCommit` are also returned so the MCP layer can warn
+ * before serving silently-stale answers (issue: silent graph drift
+ * across sibling clones).
+ *
+ * `path` matches deliberately use the longest-prefix rule so a cwd
+ * inside a sub-path of a registered repo still matches that repo, not
+ * a coincidentally-aliased shorter entry.
+ */
+export declare function checkCwdMatch(cwd: string): Promise<CwdMatch>;

package/dist/core/git-staleness.js

@@ -0,0 +1,137 @@
+/**
+ * Git working tree vs index commit staleness (used by MCP resources, group status, etc.).
+ * Lives in core/ so application code does not depend on the MCP package layer.
+ */
+import { execFileSync } from 'node:child_process';
+import path from 'path';
+import { readRegistry } from '../storage/repo-manager.js';
+import { getGitRoot, getCurrentCommit, getRemoteUrl } from '../storage/git.js';
+/**
+ * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
+ */
+export function checkStaleness(repoPath, lastCommit) {
+    try {
+        const result = execFileSync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        const commitsBehind = parseInt(result, 10) || 0;
+        if (commitsBehind > 0) {
+            return {
+                isStale: true,
+                commitsBehind,
+                hint: `⚠️ Index is ${commitsBehind} commit${commitsBehind > 1 ? 's' : ''} behind HEAD. Run analyze tool to update.`,
+            };
+        }
+        return { isStale: false, commitsBehind: 0 };
+    }
+    catch {
+        return { isStale: false, commitsBehind: 0 };
+    }
+}
+/**
+ * Compare a sibling-clone HEAD against an indexed `lastCommit`. Returns
+ * `undefined` when the indexed commit is not reachable from the sibling
+ * (e.g. divergent branches, shallow clone, missing ref). The caller
+ * should treat `undefined` as "drift unknown" rather than "no drift".
+ */
+function commitsAheadOfIndexed(siblingPath, indexedCommit) {
+    if (!indexedCommit)
+        return undefined;
+    try {
+        const result = execFileSync('git', ['rev-list', '--count', `${indexedCommit}..HEAD`], {
+            cwd: siblingPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return parseInt(result, 10) || 0;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve a working directory against the global registry. Returns:
+ *   - `match: 'path'`              when `cwd` is inside a registered entry's path
+ *   - `match: 'sibling-by-remote'` when `cwd` lives in a different on-disk clone
+ *                                   of the same repo (same `remoteUrl`)
+ *   - `match: 'none'`              when neither match applies
+ *
+ * For sibling-by-remote matches, the caller's HEAD and the drift vs the
+ * indexed `lastCommit` are also returned so the MCP layer can warn
+ * before serving silently-stale answers (issue: silent graph drift
+ * across sibling clones).
+ *
+ * `path` matches deliberately use the longest-prefix rule so a cwd
+ * inside a sub-path of a registered repo still matches that repo, not
+ * a coincidentally-aliased shorter entry.
+ */
+export async function checkCwdMatch(cwd) {
+    const entries = await readRegistry();
+    if (entries.length === 0)
+        return { match: 'none' };
+    const isWin = process.platform === 'win32';
+    const norm = (p) => (isWin ? path.resolve(p).toLowerCase() : path.resolve(p));
+    const sep = path.sep;
+    const cwdResolved = path.resolve(cwd);
+    const cwdNorm = norm(cwdResolved);
+    // 1) Path-based match (longest prefix wins, boundary-safe).
+    let bestPath;
+    let bestLen = -1;
+    for (const e of entries) {
+        const p = norm(e.path);
+        if (cwdNorm === p || cwdNorm.startsWith(p + sep)) {
+            if (p.length > bestLen) {
+                bestPath = e;
+                bestLen = p.length;
+            }
+        }
+    }
+    if (bestPath)
+        return { match: 'path', entry: bestPath };
+    // 2) Sibling-by-remote: locate the cwd's git root, get its remote
+    //    URL, and look for any registered entry with the same fingerprint.
+    const cwdGitRoot = getGitRoot(cwdResolved);
+    if (!cwdGitRoot)
+        return { match: 'none' };
+    const cwdRemote = getRemoteUrl(cwdGitRoot);
+    if (!cwdRemote)
+        return { match: 'none' };
+    const sibling = entries.find((e) => e.remoteUrl === cwdRemote && norm(e.path) !== norm(cwdGitRoot));
+    if (!sibling)
+        return { match: 'none' };
+    const cwdHead = getCurrentCommit(cwdGitRoot) || undefined;
+    const drift = commitsAheadOfIndexed(cwdGitRoot, sibling.lastCommit);
+    // Same commit on both clones → still report match=sibling-by-remote
+    // (the relationship is real and useful to callers like list_repos /
+    // future tooling) but leave `hint` unset: there's nothing to warn
+    // about, and `maybeWarnSiblingDrift` already short-circuits this
+    // case independently. Surfacing a no-op hint would force callers
+    // to second-guess whether they need to display it.
+    let hint;
+    if (cwdHead && cwdHead === sibling.lastCommit) {
+        hint = undefined;
+    }
+    else if (drift && drift > 0) {
+        hint =
+            `⚠️ Index for "${sibling.name}" was built at ${sibling.path}; ` +
+                `your cwd (${cwdGitRoot}) is a sibling clone that is ${drift} commit${drift > 1 ? 's' : ''} ` +
+                `ahead of the indexed commit. Results may be stale or incorrect — re-run \`codragraph analyze\` ` +
+                `to refresh the index.`;
+    }
+    else {
+        hint =
+            `⚠️ Index for "${sibling.name}" was built at ${sibling.path}; ` +
+                `your cwd (${cwdGitRoot}) is a sibling clone whose HEAD differs from the indexed commit. ` +
+                `Results may be stale or incorrect — re-run \`codragraph analyze\` to refresh the index.`;
+    }
+    return {
+        match: 'sibling-by-remote',
+        entry: sibling,
+        cwdGitRoot,
+        cwdHead,
+        drift,
+        hint,
+    };
+}

package/dist/core/graph/graph.d.ts

@@ -0,0 +1,2 @@
+import { KnowledgeGraph } from './types.js';
+export declare const createKnowledgeGraph: () => KnowledgeGraph;