@duytransipher/gitnexus 1.4.6-sipher.0

package/dist/config/ignore-service.js

@@ -0,0 +1,284 @@
+import ignore from 'ignore';
+import fs from 'fs/promises';
+import nodePath from 'path';
+const DEFAULT_IGNORE_LIST = new Set([
+    // Version Control
+    '.git',
+    '.svn',
+    '.hg',
+    '.bzr',
+    // IDEs & Editors
+    '.idea',
+    '.vscode',
+    '.vs',
+    '.eclipse',
+    '.settings',
+    '.DS_Store',
+    'Thumbs.db',
+    // Dependencies
+    'node_modules',
+    'bower_components',
+    'jspm_packages',
+    'vendor', // PHP/Go
+    // 'packages' removed - commonly used for monorepo source code (lerna, pnpm, yarn workspaces)
+    'venv',
+    '.venv',
+    'env',
+    '.env',
+    '__pycache__',
+    '.pytest_cache',
+    '.mypy_cache',
+    'site-packages',
+    '.tox',
+    'eggs',
+    '.eggs',
+    'lib64',
+    'parts',
+    'sdist',
+    'wheels',
+    // Build Outputs
+    'dist',
+    'build',
+    'out',
+    'output',
+    'bin',
+    'obj',
+    'target', // Java/Rust
+    '.next',
+    '.nuxt',
+    '.output',
+    '.vercel',
+    '.netlify',
+    '.serverless',
+    '_build',
+    'public/build',
+    '.parcel-cache',
+    '.turbo',
+    '.svelte-kit',
+    // Test & Coverage
+    'coverage',
+    '.nyc_output',
+    'htmlcov',
+    '.coverage',
+    '__tests__', // Often just test files
+    '__mocks__',
+    '.jest',
+    // Logs & Temp
+    'logs',
+    'log',
+    'tmp',
+    'temp',
+    'cache',
+    '.cache',
+    '.tmp',
+    '.temp',
+    // Generated/Compiled
+    '.generated',
+    'generated',
+    'auto-generated',
+    '.terraform',
+    '.serverless',
+    // Documentation (optional - might want to keep)
+    // 'docs',
+    // 'documentation',
+    // Misc
+    '.husky',
+    '.github', // GitHub config, not code
+    '.circleci',
+    '.gitlab',
+    'fixtures', // Test fixtures
+    'snapshots', // Jest snapshots
+    '__snapshots__',
+]);
+const IGNORED_EXTENSIONS = new Set([
+    // Images
+    '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.webp', '.bmp', '.tiff', '.tif',
+    '.psd', '.ai', '.sketch', '.fig', '.xd',
+    // Archives
+    '.zip', '.tar', '.gz', '.rar', '.7z', '.bz2', '.xz', '.tgz',
+    // Binary/Compiled
+    '.exe', '.dll', '.so', '.dylib', '.a', '.lib', '.o', '.obj',
+    '.class', '.jar', '.war', '.ear',
+    '.pyc', '.pyo', '.pyd',
+    '.beam', // Erlang
+    '.wasm', // WebAssembly - important!
+    '.node', // Native Node addons
+    // Documents
+    '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+    '.odt', '.ods', '.odp',
+    // Media
+    '.mp4', '.mp3', '.wav', '.mov', '.avi', '.mkv', '.flv', '.wmv',
+    '.ogg', '.webm', '.flac', '.aac', '.m4a',
+    // Fonts
+    '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    // Databases
+    '.db', '.sqlite', '.sqlite3', '.mdb', '.accdb',
+    // Minified/Bundled files
+    '.min.js', '.min.css', '.bundle.js', '.chunk.js',
+    // Source maps (debug files, not source)
+    '.map',
+    // Lock files (handled separately, but also here)
+    '.lock',
+    // Certificates & Keys (security - don't index!)
+    '.pem', '.key', '.crt', '.cer', '.p12', '.pfx',
+    // Data files (often large/binary)
+    '.csv', '.tsv', '.parquet', '.avro', '.feather',
+    '.npy', '.npz', '.pkl', '.pickle', '.h5', '.hdf5',
+    // Misc binary
+    '.bin', '.dat', '.data', '.raw',
+    '.iso', '.img', '.dmg',
+]);
+// Files to ignore by exact name
+const IGNORED_FILES = new Set([
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'composer.lock',
+    'Gemfile.lock',
+    'poetry.lock',
+    'Cargo.lock',
+    'go.sum',
+    '.gitignore',
+    '.gitattributes',
+    '.npmrc',
+    '.yarnrc',
+    '.editorconfig',
+    '.prettierrc',
+    '.prettierignore',
+    '.eslintignore',
+    '.dockerignore',
+    'Thumbs.db',
+    '.DS_Store',
+    'LICENSE',
+    'LICENSE.md',
+    'LICENSE.txt',
+    'CHANGELOG.md',
+    'CHANGELOG',
+    'CONTRIBUTING.md',
+    'CODE_OF_CONDUCT.md',
+    'SECURITY.md',
+    '.env',
+    '.env.local',
+    '.env.development',
+    '.env.production',
+    '.env.test',
+    '.env.example',
+]);
+// NOTE: Negation patterns in .gitnexusignore (e.g. `!vendor/`) cannot override
+// entries in DEFAULT_IGNORE_LIST — this is intentional. The hardcoded list protects
+// against indexing directories that are almost never source code (node_modules, .git, etc.).
+// Users who need to include such directories should remove them from the hardcoded list.
+export const shouldIgnorePath = (filePath) => {
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    const parts = normalizedPath.split('/');
+    const fileName = parts[parts.length - 1];
+    const fileNameLower = fileName.toLowerCase();
+    // Check if any path segment is in ignore list
+    for (const part of parts) {
+        if (DEFAULT_IGNORE_LIST.has(part)) {
+            return true;
+        }
+    }
+    // Check exact filename matches
+    if (IGNORED_FILES.has(fileName) || IGNORED_FILES.has(fileNameLower)) {
+        return true;
+    }
+    // Check extension
+    const lastDotIndex = fileNameLower.lastIndexOf('.');
+    if (lastDotIndex !== -1) {
+        const ext = fileNameLower.substring(lastDotIndex);
+        if (IGNORED_EXTENSIONS.has(ext))
+            return true;
+        // Handle compound extensions like .min.js, .bundle.js
+        const secondLastDot = fileNameLower.lastIndexOf('.', lastDotIndex - 1);
+        if (secondLastDot !== -1) {
+            const compoundExt = fileNameLower.substring(secondLastDot);
+            if (IGNORED_EXTENSIONS.has(compoundExt))
+                return true;
+        }
+    }
+    // Ignore hidden files (starting with .)
+    if (fileName.startsWith('.') && fileName !== '.') {
+        // But allow some important config files
+        const allowedDotFiles = ['.env', '.gitignore']; // Already in IGNORED_FILES, so this is redundant
+        // Actually, let's NOT ignore all dot files - many are important configs
+        // Just rely on the explicit lists above
+    }
+    // Ignore files that look like generated/bundled code
+    if (fileNameLower.includes('.bundle.') ||
+        fileNameLower.includes('.chunk.') ||
+        fileNameLower.includes('.generated.') ||
+        fileNameLower.endsWith('.d.ts')) { // TypeScript declaration files
+        return true;
+    }
+    return false;
+};
+/** Check if a directory name is in the hardcoded ignore list */
+export const isHardcodedIgnoredDirectory = (name) => {
+    return DEFAULT_IGNORE_LIST.has(name);
+};
+export const loadIgnoreRules = async (repoPath, options) => {
+    const ig = ignore();
+    let hasRules = false;
+    // Allow users to bypass .gitignore parsing (e.g. when .gitignore accidentally excludes source files)
+    const skipGitignore = options?.noGitignore ?? !!process.env.GITNEXUS_NO_GITIGNORE;
+    const filenames = skipGitignore
+        ? ['.gitnexusignore']
+        : ['.gitignore', '.gitnexusignore'];
+    for (const filename of filenames) {
+        try {
+            const content = await fs.readFile(nodePath.join(repoPath, filename), 'utf-8');
+            ig.add(content);
+            hasRules = true;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOENT') {
+                console.warn(`  Warning: could not read ${filename}: ${err.message}`);
+            }
+        }
+    }
+    return hasRules ? ig : null;
+};
+/**
+ * Create a glob-compatible ignore filter combining:
+ * - .gitignore / .gitnexusignore patterns (via `ignore` package)
+ * - Hardcoded DEFAULT_IGNORE_LIST, IGNORED_EXTENSIONS, IGNORED_FILES
+ *
+ * Returns an IgnoreLike object for glob's `ignore` option,
+ * enabling directory-level pruning during traversal.
+ */
+export const createIgnoreFilter = async (repoPath, options) => {
+    const ig = await loadIgnoreRules(repoPath, options);
+    return {
+        ignored(p) {
+            // path-scurry's Path.relative() returns POSIX paths on all platforms,
+            // which is what the `ignore` package expects. No explicit normalization needed.
+            const rel = p.relative();
+            if (!rel)
+                return false;
+            // Check .gitignore / .gitnexusignore patterns
+            if (ig && ig.ignores(rel))
+                return true;
+            // Fall back to hardcoded rules
+            return shouldIgnorePath(rel);
+        },
+        childrenIgnored(p) {
+            // Fast path: check directory name against hardcoded list.
+            // Note: dot-directories (.git, .vscode, etc.) are primarily excluded by
+            // glob's `dot: false` option in filesystem-walker.ts. This check is
+            // defense-in-depth — do not remove `dot: false` assuming this covers it.
+            if (DEFAULT_IGNORE_LIST.has(p.name))
+                return true;
+            // Check against .gitignore / .gitnexusignore patterns.
+            // Test both bare path and path with trailing slash to handle
+            // bare-name patterns (e.g. `local`) and dir-only patterns (e.g. `local/`).
+            if (ig) {
+                const rel = p.relative();
+                if (rel && (ig.ignores(rel) || ig.ignores(rel + '/')))
+                    return true;
+            }
+            return false;
+        },
+    };
+};

package/dist/config/supported-languages.d.ts

@@ -0,0 +1,15 @@
+export declare enum SupportedLanguages {
+    JavaScript = "javascript",
+    TypeScript = "typescript",
+    Python = "python",
+    Java = "java",
+    C = "c",
+    CPlusPlus = "cpp",
+    CSharp = "csharp",
+    Go = "go",
+    Ruby = "ruby",
+    Rust = "rust",
+    PHP = "php",
+    Kotlin = "kotlin",
+    Swift = "swift"
+}

package/dist/config/supported-languages.js

@@ -0,0 +1,16 @@
+export var SupportedLanguages;
+(function (SupportedLanguages) {
+    SupportedLanguages["JavaScript"] = "javascript";
+    SupportedLanguages["TypeScript"] = "typescript";
+    SupportedLanguages["Python"] = "python";
+    SupportedLanguages["Java"] = "java";
+    SupportedLanguages["C"] = "c";
+    SupportedLanguages["CPlusPlus"] = "cpp";
+    SupportedLanguages["CSharp"] = "csharp";
+    SupportedLanguages["Go"] = "go";
+    SupportedLanguages["Ruby"] = "ruby";
+    SupportedLanguages["Rust"] = "rust";
+    SupportedLanguages["PHP"] = "php";
+    SupportedLanguages["Kotlin"] = "kotlin";
+    SupportedLanguages["Swift"] = "swift";
+})(SupportedLanguages || (SupportedLanguages = {}));

package/dist/core/augmentation/engine.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Augmentation Engine
+ *
+ * Lightweight, fast-path enrichment of search patterns with knowledge graph context.
+ * Designed to be called from platform hooks (Claude Code PreToolUse, Cursor beforeShellExecution)
+ * when an agent runs grep/glob/search.
+ *
+ * Performance target: <500ms cold start, <200ms warm.
+ *
+ * Design decisions:
+ * - Uses only BM25 search (no semantic/embedding) for speed
+ * - Clusters used internally for ranking, NEVER in output
+ * - Output is pure relationships: callers, callees, process participation
+ * - Graceful failure: any error → return empty string
+ */
+/**
+ * Augment a search pattern with knowledge graph context.
+ *
+ * 1. BM25 search for the pattern
+ * 2. For top matches, fetch callers/callees/processes
+ * 3. Rank by internal cluster cohesion (not exposed)
+ * 4. Format as structured text block
+ *
+ * Returns empty string on any error (graceful failure).
+ */
+export declare function augment(pattern: string, cwd?: string): Promise<string>;

package/dist/core/augmentation/engine.js

@@ -0,0 +1,240 @@
+/**
+ * Augmentation Engine
+ *
+ * Lightweight, fast-path enrichment of search patterns with knowledge graph context.
+ * Designed to be called from platform hooks (Claude Code PreToolUse, Cursor beforeShellExecution)
+ * when an agent runs grep/glob/search.
+ *
+ * Performance target: <500ms cold start, <200ms warm.
+ *
+ * Design decisions:
+ * - Uses only BM25 search (no semantic/embedding) for speed
+ * - Clusters used internally for ranking, NEVER in output
+ * - Output is pure relationships: callers, callees, process participation
+ * - Graceful failure: any error → return empty string
+ */
+import path from 'path';
+import { listRegisteredRepos } from '../../storage/repo-manager.js';
+/**
+ * Find the best matching repo for a given working directory.
+ * Matches by checking if cwd is within the repo's path.
+ */
+async function findRepoForCwd(cwd) {
+    try {
+        const entries = await listRegisteredRepos({ validate: true });
+        const resolved = path.resolve(cwd);
+        // Normalize to lowercase on Windows (drive letters can differ: D: vs d:)
+        const isWindows = process.platform === 'win32';
+        const normalizedCwd = isWindows ? resolved.toLowerCase() : resolved;
+        const sep = path.sep;
+        // Find the LONGEST matching repo path (most specific match wins)
+        let bestMatch = null;
+        let bestLen = 0;
+        for (const entry of entries) {
+            const repoResolved = path.resolve(entry.path);
+            const normalizedRepo = isWindows ? repoResolved.toLowerCase() : repoResolved;
+            // Check if cwd is inside repo OR repo is inside cwd
+            // Must match at a path separator boundary to avoid false positives
+            // (e.g. /projects/gitnexusv2 should NOT match /projects/gitnexus)
+            let matched = false;
+            if (normalizedCwd === normalizedRepo) {
+                matched = true;
+            }
+            else if (normalizedCwd.startsWith(normalizedRepo + sep)) {
+                matched = true;
+            }
+            else if (normalizedRepo.startsWith(normalizedCwd + sep)) {
+                matched = true;
+            }
+            if (matched && normalizedRepo.length > bestLen) {
+                bestMatch = entry;
+                bestLen = normalizedRepo.length;
+            }
+        }
+        if (!bestMatch)
+            return null;
+        return {
+            name: bestMatch.name,
+            storagePath: bestMatch.storagePath,
+            lbugPath: path.join(bestMatch.storagePath, 'lbug'),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Augment a search pattern with knowledge graph context.
+ *
+ * 1. BM25 search for the pattern
+ * 2. For top matches, fetch callers/callees/processes
+ * 3. Rank by internal cluster cohesion (not exposed)
+ * 4. Format as structured text block
+ *
+ * Returns empty string on any error (graceful failure).
+ */
+export async function augment(pattern, cwd) {
+    if (!pattern || pattern.length < 3)
+        return '';
+    const workDir = cwd || process.cwd();
+    try {
+        const repo = await findRepoForCwd(workDir);
+        if (!repo)
+            return '';
+        // Lazy-load lbug adapter (skip unnecessary init)
+        const { initLbug, executeQuery, isLbugReady } = await import('../../mcp/core/lbug-adapter.js');
+        const { searchFTSFromLbug } = await import('../search/bm25-index.js');
+        const repoId = repo.name.toLowerCase();
+        // Init LadybugDB if not already
+        if (!isLbugReady(repoId)) {
+            await initLbug(repoId, repo.lbugPath);
+        }
+        // Step 1: BM25 search (fast, no embeddings)
+        const bm25Results = await searchFTSFromLbug(pattern, 10, repoId);
+        if (bm25Results.length === 0)
+            return '';
+        // Step 2: Map BM25 file results to symbols
+        const symbolMatches = [];
+        for (const result of bm25Results.slice(0, 5)) {
+            const escaped = result.filePath.replace(/'/g, "''");
+            try {
+                const symbols = await executeQuery(repoId, `
+          MATCH (n) WHERE n.filePath = '${escaped}'
+          AND n.name CONTAINS '${pattern.replace(/'/g, "''").split(/\s+/)[0]}'
+          RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
+          LIMIT 3
+        `);
+                for (const sym of symbols) {
+                    symbolMatches.push({
+                        nodeId: sym.id || sym[0],
+                        name: sym.name || sym[1],
+                        type: sym.type || sym[2],
+                        filePath: sym.filePath || sym[3],
+                        score: result.score,
+                    });
+                }
+            }
+            catch { /* skip */ }
+        }
+        if (symbolMatches.length === 0)
+            return '';
+        // Step 3: Batch-fetch callers/callees/processes/cohesion for top matches
+        // Uses batched WHERE n.id IN [...] queries instead of per-symbol queries
+        const uniqueSymbols = symbolMatches.slice(0, 5).filter((sym, i, arr) => arr.findIndex(s => s.nodeId === sym.nodeId) === i);
+        if (uniqueSymbols.length === 0)
+            return '';
+        const idList = uniqueSymbols.map(s => `'${s.nodeId.replace(/'/g, "''")}'`).join(', ');
+        // Batch fetch callers
+        const callersMap = new Map();
+        try {
+            const rows = await executeQuery(repoId, `
+        MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(n)
+        WHERE n.id IN [${idList}]
+        RETURN n.id AS targetId, caller.name AS name
+        LIMIT 15
+      `);
+            for (const r of rows) {
+                const tid = r.targetId || r[0];
+                const name = r.name || r[1];
+                if (tid && name) {
+                    if (!callersMap.has(tid))
+                        callersMap.set(tid, []);
+                    callersMap.get(tid).push(name);
+                }
+            }
+        }
+        catch { /* skip */ }
+        // Batch fetch callees
+        const calleesMap = new Map();
+        try {
+            const rows = await executeQuery(repoId, `
+        MATCH (n)-[:CodeRelation {type: 'CALLS'}]->(callee)
+        WHERE n.id IN [${idList}]
+        RETURN n.id AS sourceId, callee.name AS name
+        LIMIT 15
+      `);
+            for (const r of rows) {
+                const sid = r.sourceId || r[0];
+                const name = r.name || r[1];
+                if (sid && name) {
+                    if (!calleesMap.has(sid))
+                        calleesMap.set(sid, []);
+                    calleesMap.get(sid).push(name);
+                }
+            }
+        }
+        catch { /* skip */ }
+        // Batch fetch processes
+        const processesMap = new Map();
+        try {
+            const rows = await executeQuery(repoId, `
+        MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
+        WHERE n.id IN [${idList}]
+        RETURN n.id AS nodeId, p.heuristicLabel AS label, r.step AS step, p.stepCount AS stepCount
+      `);
+            for (const r of rows) {
+                const nid = r.nodeId || r[0];
+                const label = r.label || r[1];
+                const step = r.step || r[2];
+                const stepCount = r.stepCount || r[3];
+                if (nid && label) {
+                    if (!processesMap.has(nid))
+                        processesMap.set(nid, []);
+                    processesMap.get(nid).push(`${label} (step ${step}/${stepCount})`);
+                }
+            }
+        }
+        catch { /* skip */ }
+        // Batch fetch cohesion
+        const cohesionMap = new Map();
+        try {
+            const rows = await executeQuery(repoId, `
+        MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
+        WHERE n.id IN [${idList}]
+        RETURN n.id AS nodeId, c.cohesion AS cohesion
+      `);
+            for (const r of rows) {
+                const nid = r.nodeId || r[0];
+                const coh = r.cohesion ?? r[1] ?? 0;
+                if (nid)
+                    cohesionMap.set(nid, coh);
+            }
+        }
+        catch { /* skip */ }
+        // Assemble enriched results
+        const enriched = [];
+        for (const sym of uniqueSymbols) {
+            enriched.push({
+                name: sym.name,
+                filePath: sym.filePath,
+                callers: (callersMap.get(sym.nodeId) || []).slice(0, 3),
+                callees: (calleesMap.get(sym.nodeId) || []).slice(0, 3),
+                processes: processesMap.get(sym.nodeId) || [],
+                cohesion: cohesionMap.get(sym.nodeId) || 0,
+            });
+        }
+        if (enriched.length === 0)
+            return '';
+        // Step 4: Rank by cohesion (internal signal) and format
+        enriched.sort((a, b) => b.cohesion - a.cohesion);
+        const lines = [`[GitNexus] ${enriched.length} related symbols found:`, ''];
+        for (const item of enriched) {
+            lines.push(`${item.name} (${item.filePath})`);
+            if (item.callers.length > 0) {
+                lines.push(`  Called by: ${item.callers.join(', ')}`);
+            }
+            if (item.callees.length > 0) {
+                lines.push(`  Calls: ${item.callees.join(', ')}`);
+            }
+            if (item.processes.length > 0) {
+                lines.push(`  Flows: ${item.processes.join(', ')}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n').trim();
+    }
+    catch {
+        // Graceful failure — never break the original tool
+        return '';
+    }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Embedder Module
+ *
+ * Singleton factory for transformers.js embedding pipeline.
+ * Handles model loading, caching, and both single and batch embedding operations.
+ *
+ * Uses snowflake-arctic-embed-xs by default (22M params, 384 dims, ~90MB)
+ */
+import { type FeatureExtractionPipeline } from '@huggingface/transformers';
+import { type EmbeddingConfig, type ModelProgress } from './types.js';
+/**
+ * Progress callback type for model loading
+ */
+export type ModelProgressCallback = (progress: ModelProgress) => void;
+/**
+ * Get the current device being used for inference
+ */
+export declare const getCurrentDevice: () => "dml" | "cuda" | "cpu" | "wasm" | null;
+/**
+ * Initialize the embedding model
+ * Uses singleton pattern - only loads once, subsequent calls return cached instance
+ *
+ * @param onProgress - Optional callback for model download progress
+ * @param config - Optional configuration override
+ * @param forceDevice - Force a specific device
+ * @returns Promise resolving to the embedder pipeline
+ */
+export declare const initEmbedder: (onProgress?: ModelProgressCallback, config?: Partial<EmbeddingConfig>, forceDevice?: "dml" | "cuda" | "cpu" | "wasm") => Promise<FeatureExtractionPipeline>;
+/**
+ * Check if the embedder is initialized and ready
+ */
+export declare const isEmbedderReady: () => boolean;
+/**
+ * Get the embedder instance (throws if not initialized)
+ */
+export declare const getEmbedder: () => FeatureExtractionPipeline;
+/**
+ * Embed a single text string
+ *
+ * @param text - Text to embed
+ * @returns Float32Array of embedding vector (384 dimensions)
+ */
+export declare const embedText: (text: string) => Promise<Float32Array>;
+/**
+ * Embed multiple texts in a single batch
+ * More efficient than calling embedText multiple times
+ *
+ * @param texts - Array of texts to embed
+ * @returns Array of Float32Array embedding vectors
+ */
+export declare const embedBatch: (texts: string[]) => Promise<Float32Array[]>;
+/**
+ * Convert Float32Array to regular number array (for LadybugDB storage)
+ */
+export declare const embeddingToArray: (embedding: Float32Array) => number[];
+/**
+ * Cleanup the embedder (free memory)
+ * Call this when done with embeddings
+ */
+export declare const disposeEmbedder: () => Promise<void>;