@zuvia-software-solutions/code-mapper 1.4.0

package/dist/cli/refresh.js

@@ -0,0 +1,165 @@
+// code-mapper/src/cli/refresh.ts
+/**
+ * @file refresh.ts
+ * @description CLI command for incremental refresh — re-indexes only files
+ * changed since the last commit. Reuses the same RefreshCoordinator + child
+ * process architecture as the MCP server's auto-refresh.
+ *
+ * Usage: code-mapper refresh [--scope unstaged|staged|committed]
+ */
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { RefreshCoordinator } from '../core/incremental/refresh-coordinator.js';
+import { toRepoId, toRepoRoot, toDbPath, toRelativeFilePath, } from '../core/incremental/types.js';
+import { getStoragePaths, loadMeta, saveMeta, } from '../storage/repo-manager.js';
+import { getCurrentCommit, getGitRoot, isGitRepo } from '../storage/git.js';
+import { initLbug, closeLbug, getLbugStats, executeQuery } from '../core/lbug/lbug-adapter.js';
+export const refreshCommand = async (options) => {
+    const cwd = process.cwd();
+    // Find repo root
+    if (!isGitRepo(cwd)) {
+        console.error('Not a git repository.');
+        process.exit(1);
+    }
+    const repoRoot = getGitRoot(cwd);
+    if (!repoRoot) {
+        console.error('Could not determine git root.');
+        process.exit(1);
+    }
+    const { storagePath, lbugPath } = getStoragePaths(repoRoot);
+    const meta = await loadMeta(storagePath);
+    if (!meta) {
+        console.error('No Code Mapper index found. Run: code-mapper analyze');
+        process.exit(1);
+    }
+    const repoName = path.basename(repoRoot);
+    const scope = options?.scope || 'committed';
+    // Get changed files based on scope
+    let diffArgs;
+    let description;
+    switch (scope) {
+        case 'unstaged':
+            diffArgs = ['diff', '--name-status'];
+            description = 'unstaged changes';
+            break;
+        case 'staged':
+            diffArgs = ['diff', '--staged', '--name-status'];
+            description = 'staged changes';
+            break;
+        case 'committed':
+        default:
+            // Changes since last indexed commit
+            if (!meta.lastCommit) {
+                console.error('No previous commit recorded. Run: code-mapper analyze');
+                process.exit(1);
+            }
+            diffArgs = ['diff', '--name-status', `${meta.lastCommit}..HEAD`];
+            description = `changes since ${meta.lastCommit.slice(0, 7)}`;
+            break;
+    }
+    let diffOutput;
+    try {
+        diffOutput = execFileSync('git', diffArgs, {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (err) {
+        console.error(`Git diff failed: ${err.message}`);
+        process.exit(1);
+    }
+    if (!diffOutput) {
+        console.log('No changes detected. Index is up to date.');
+        return;
+    }
+    // Parse diff into DirtyFileEntry[]
+    const entries = [];
+    for (const line of diffOutput.split('\n')) {
+        if (!line)
+            continue;
+        const [status, ...pathParts] = line.split('\t');
+        const filePath = pathParts.join('\t');
+        if (!filePath)
+            continue;
+        let changeKind;
+        if (status === 'D')
+            changeKind = 'deleted';
+        else if (status === 'A')
+            changeKind = 'created';
+        else
+            changeKind = 'modified';
+        try {
+            entries.push({
+                relativePath: toRelativeFilePath(filePath),
+                changeKind,
+            });
+        }
+        catch {
+            // Skip invalid paths
+        }
+    }
+    if (entries.length === 0) {
+        console.log('No supported files changed. Index is up to date.');
+        return;
+    }
+    console.log(`Refreshing ${entries.length} file(s) (${description})...`);
+    // Initialize LadybugDB, query existing paths, then close before child fork
+    const repoId = repoName.toLowerCase();
+    let existingPaths = [];
+    try {
+        await initLbug(lbugPath);
+        const rows = await executeQuery('MATCH (f:File) RETURN f.filePath AS filePath');
+        existingPaths = rows.map((r) => String(r.filePath ?? ''));
+        await closeLbug();
+    }
+    catch (err) {
+        console.error(`Failed to open index: ${err.message}`);
+        process.exit(1);
+    }
+    // Run incremental refresh via the coordinator
+    const coordinator = new RefreshCoordinator();
+    const t0 = Date.now();
+    try {
+        const result = await coordinator.refresh({
+            id: toRepoId(repoId),
+            repoRoot: toRepoRoot(repoRoot),
+            dbPath: toDbPath(lbugPath),
+            storagePath,
+        }, entries, existingPaths, 60_000);
+        const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+        console.log(`Refreshed ${result.filesProcessed} file(s) in ${elapsed}s`);
+        // Update metadata with current commit
+        if (scope === 'committed' || scope === 'staged') {
+            try {
+                await initLbug(lbugPath);
+                const currentCommitHash = getCurrentCommit(repoRoot);
+                const stats = await getLbugStats();
+                await saveMeta(storagePath, {
+                    repoPath: repoRoot,
+                    lastCommit: currentCommitHash,
+                    indexedAt: new Date().toISOString(),
+                    stats: {
+                        files: meta.stats?.files ?? 0,
+                        nodes: stats.nodes ?? meta.stats?.nodes ?? 0,
+                        edges: stats.edges ?? meta.stats?.edges ?? 0,
+                        communities: meta.stats?.communities ?? 0,
+                        processes: meta.stats?.processes ?? 0,
+                        embeddings: meta.stats?.embeddings ?? 0,
+                    },
+                });
+            }
+            catch { }
+        }
+    }
+    catch (err) {
+        console.error(`Refresh failed: ${err.message}`);
+        process.exit(1);
+    }
+    finally {
+        try {
+            await closeLbug();
+        }
+        catch { }
+    }
+};

package/dist/cli/serve.d.ts

@@ -0,0 +1,5 @@
+/** @file serve.ts @description Starts the HTTP REST API server for browser-based access */
+export declare const serveCommand: (options?: {
+    port?: string;
+    host?: string;
+}) => Promise<void>;

package/dist/cli/serve.js

@@ -0,0 +1,8 @@
+// code-mapper/src/cli/serve.ts
+/** @file serve.ts @description Starts the HTTP REST API server for browser-based access */
+import { createServer } from '../server/api.js';
+export const serveCommand = async (options) => {
+    const port = Number(options?.port ?? 4747);
+    const host = options?.host ?? '127.0.0.1';
+    await createServer(port, host);
+};

package/dist/cli/setup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file setup.ts
+ * @description One-time global MCP configuration writer. Detects installed AI editors
+ * and writes MCP config so the Code Mapper server is available in all projects
+ */
+export declare const setupCommand: () => Promise<void>;

package/dist/cli/setup.js

@@ -0,0 +1,218 @@
+// code-mapper/src/cli/setup.ts
+/**
+ * @file setup.ts
+ * @description One-time global MCP configuration writer. Detects installed AI editors
+ * and writes MCP config so the Code Mapper server is available in all projects
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+import { getGlobalDir } from '../storage/repo-manager.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/** Get the MCP server entry for all editors (Windows uses cmd /c for npx) */
+function getMcpEntry() {
+    if (process.platform === 'win32') {
+        return {
+            command: 'cmd',
+            args: ['/c', 'npx', '-y', 'code-mapper@latest', 'mcp'],
+        };
+    }
+    return {
+        command: 'npx',
+        args: ['-y', 'code-mapper@latest', 'mcp'],
+    };
+}
+/** Merge code-mapper entry into an existing MCP config JSON object */
+function mergeMcpConfig(existing) {
+    if (!existing || typeof existing !== 'object') {
+        existing = {};
+    }
+    if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
+        existing.mcpServers = {};
+    }
+    existing.mcpServers['code-mapper'] = getMcpEntry();
+    return existing;
+}
+/** Read a JSON file, returning null if it doesn't exist or is invalid */
+async function readJsonFile(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Write JSON to a file, creating parent directories if needed */
+async function writeJsonFile(filePath, data) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+/** Check if a directory exists */
+async function dirExists(dirPath) {
+    try {
+        const stat = await fs.stat(dirPath);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// Editor-specific setup
+async function setupCursor(result) {
+    const cursorDir = path.join(os.homedir(), '.cursor');
+    if (!(await dirExists(cursorDir))) {
+        result.skipped.push('Cursor (not installed)');
+        return;
+    }
+    const mcpPath = path.join(cursorDir, 'mcp.json');
+    try {
+        const existing = await readJsonFile(mcpPath);
+        const updated = mergeMcpConfig(existing);
+        await writeJsonFile(mcpPath, updated);
+        result.configured.push('Cursor');
+    }
+    catch (err) {
+        result.errors.push(`Cursor: ${err.message}`);
+    }
+}
+async function setupClaudeCode(result) {
+    const claudeDir = path.join(os.homedir(), '.claude');
+    const hasClaude = await dirExists(claudeDir);
+    if (!hasClaude) {
+        result.skipped.push('Claude Code (not installed)');
+        return;
+    }
+    // Claude Code uses claude mcp add for configuration
+    console.log('');
+    console.log('  Claude Code detected. Run this command to add Code Mapper MCP:');
+    console.log('');
+    console.log('    claude mcp add code-mapper -- npx -y code-mapper mcp');
+    console.log('');
+    result.configured.push('Claude Code (MCP manual step printed)');
+}
+/** Install Code Mapper hooks to ~/.claude/settings.json, merging without overwriting existing hooks */
+async function installClaudeCodeHooks(result) {
+    const claudeDir = path.join(os.homedir(), '.claude');
+    if (!(await dirExists(claudeDir)))
+        return;
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    // Source hooks bundled within the code-mapper package
+    const pluginHooksPath = path.join(__dirname, '..', '..', 'hooks', 'claude');
+    // Copy unified hook script to ~/.claude/hooks/code-mapper/
+    const destHooksDir = path.join(claudeDir, 'hooks', 'code-mapper');
+    try {
+        await fs.mkdir(destHooksDir, { recursive: true });
+        const src = path.join(pluginHooksPath, 'code-mapper-hook.cjs');
+        const dest = path.join(destHooksDir, 'code-mapper-hook.cjs');
+        try {
+            let content = await fs.readFile(src, 'utf-8');
+            // Inject resolved CLI path so the copied hook can find the CLI
+            // even when no longer inside the npm package tree
+            const resolvedCli = path.join(__dirname, '..', 'cli', 'index.js');
+            const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
+            const jsonCli = JSON.stringify(normalizedCli);
+            content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = ${jsonCli};`);
+            await fs.writeFile(dest, content, 'utf-8');
+        }
+        catch {
+            // Hook script not found in source — skip
+        }
+        const hookPath = path.join(destHooksDir, 'code-mapper-hook.cjs').replace(/\\/g, '/');
+        const hookCmd = `node "${hookPath.replace(/"/g, '\\"')}"`;
+        // Merge hook config into ~/.claude/settings.json
+        const existing = await readJsonFile(settingsPath) || {};
+        if (!existing.hooks)
+            existing.hooks = {};
+        function ensureHookEntry(eventName, matcher, timeout, statusMessage) {
+            if (!existing.hooks[eventName])
+                existing.hooks[eventName] = [];
+            const hasHook = existing.hooks[eventName].some((h) => h.hooks?.some(hh => hh.command?.includes('code-mapper-hook')));
+            if (!hasHook) {
+                existing.hooks[eventName].push({
+                    matcher,
+                    hooks: [{ type: 'command', command: hookCmd, timeout, statusMessage }],
+                });
+            }
+        }
+        ensureHookEntry('PreToolUse', 'Grep|Glob|Bash', 10, 'Enriching with Code Mapper graph context...');
+        ensureHookEntry('PostToolUse', 'Bash', 10, 'Checking Code Mapper index freshness...');
+        await writeJsonFile(settingsPath, existing);
+        result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
+    }
+    catch (err) {
+        result.errors.push(`Claude Code hooks: ${err.message}`);
+    }
+}
+async function setupOpenCode(result) {
+    const opencodeDir = path.join(os.homedir(), '.config', 'opencode');
+    if (!(await dirExists(opencodeDir))) {
+        result.skipped.push('OpenCode (not installed)');
+        return;
+    }
+    const configPath = path.join(opencodeDir, 'config.json');
+    try {
+        const existing = await readJsonFile(configPath);
+        const config = existing || {};
+        if (!config.mcp)
+            config.mcp = {};
+        config.mcp['code-mapper'] = getMcpEntry();
+        await writeJsonFile(configPath, config);
+        result.configured.push('OpenCode');
+    }
+    catch (err) {
+        result.errors.push(`OpenCode: ${err.message}`);
+    }
+}
+// Main command
+export const setupCommand = async () => {
+    console.log('');
+    console.log('  Code Mapper Setup');
+    console.log('  ==============');
+    console.log('');
+    // Ensure global directory exists
+    const globalDir = getGlobalDir();
+    await fs.mkdir(globalDir, { recursive: true });
+    const result = {
+        configured: [],
+        skipped: [],
+        errors: [],
+    };
+    // Detect and configure each editor's MCP
+    await setupCursor(result);
+    await setupClaudeCode(result);
+    await setupOpenCode(result);
+    await installClaudeCodeHooks(result);
+    // Print results
+    if (result.configured.length > 0) {
+        console.log('  Configured:');
+        for (const name of result.configured) {
+            console.log(`    + ${name}`);
+        }
+    }
+    if (result.skipped.length > 0) {
+        console.log('');
+        console.log('  Skipped:');
+        for (const name of result.skipped) {
+            console.log(`    - ${name}`);
+        }
+    }
+    if (result.errors.length > 0) {
+        console.log('');
+        console.log('  Errors:');
+        for (const err of result.errors) {
+            console.log(`    ! ${err}`);
+        }
+    }
+    console.log('');
+    console.log('  Summary:');
+    console.log(`    MCP configured for: ${result.configured.join(', ') || 'none'}`);
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    1. cd into any git repo');
+    console.log('    2. Run: code-mapper analyze');
+    console.log('    3. Open the repo in your editor — MCP is ready!');
+    console.log('');
+};

package/dist/cli/status.d.ts

@@ -0,0 +1,2 @@
+/** @file status.ts @description Shows the indexing status of the current repository */
+export declare const statusCommand: () => Promise<void>;

package/dist/cli/status.js

@@ -0,0 +1,33 @@
+// code-mapper/src/cli/status.ts
+/** @file status.ts @description Shows the indexing status of the current repository */
+import { findRepo, getStoragePaths, hasKuzuIndex } from '../storage/repo-manager.js';
+import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
+export const statusCommand = async () => {
+    const cwd = process.cwd();
+    if (!isGitRepo(cwd)) {
+        console.log('Not a git repository.');
+        return;
+    }
+    const repo = await findRepo(cwd);
+    if (!repo) {
+        // Check if there's a stale KuzuDB index that needs migration
+        const repoRoot = getGitRoot(cwd) ?? cwd;
+        const { storagePath } = getStoragePaths(repoRoot);
+        if (await hasKuzuIndex(storagePath)) {
+            console.log('Repository has a stale KuzuDB index from a previous version.');
+            console.log('Run: code-mapper analyze   (rebuilds the index with LadybugDB)');
+        }
+        else {
+            console.log('Repository not indexed.');
+            console.log('Run: code-mapper analyze');
+        }
+        return;
+    }
+    const currentCommit = getCurrentCommit(repo.repoPath);
+    const isUpToDate = currentCommit === repo.meta.lastCommit;
+    console.log(`Repository: ${repo.repoPath}`);
+    console.log(`Indexed: ${new Date(repo.meta.indexedAt).toLocaleString()}`);
+    console.log(`Indexed commit: ${repo.meta.lastCommit?.slice(0, 7)}`);
+    console.log(`Current commit: ${currentCommit?.slice(0, 7)}`);
+    console.log(`Status: ${isUpToDate ? '✅ up-to-date' : '⚠️ stale (re-run code-mapper analyze)'}`);
+};

package/dist/cli/tool.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file tool.ts
+ * @description Direct CLI tool commands (query, context, impact, cypher). Bypasses MCP
+ * entirely and invokes LocalBackend directly for minimal overhead. Output goes to stderr
+ * because LadybugDB's native module captures stdout at the OS level during init
+ */
+export declare function queryCommand(queryText: string, options?: {
+    repo?: string;
+    context?: string;
+    goal?: string;
+    limit?: string;
+    content?: boolean;
+}): Promise<void>;
+export declare function contextCommand(name: string, options?: {
+    repo?: string;
+    file?: string;
+    uid?: string;
+    content?: boolean;
+}): Promise<void>;
+export declare function impactCommand(target: string, options?: {
+    direction?: string;
+    repo?: string;
+    depth?: string;
+    includeTests?: boolean;
+}): Promise<void>;
+export declare function cypherCommand(query: string, options?: {
+    repo?: string;
+}): Promise<void>;

package/dist/cli/tool.js

@@ -0,0 +1,87 @@
+// code-mapper/src/cli/tool.ts
+/**
+ * @file tool.ts
+ * @description Direct CLI tool commands (query, context, impact, cypher). Bypasses MCP
+ * entirely and invokes LocalBackend directly for minimal overhead. Output goes to stderr
+ * because LadybugDB's native module captures stdout at the OS level during init
+ */
+import { LocalBackend } from '../mcp/local/local-backend.js';
+let _backend = null;
+async function getBackend() {
+    if (_backend)
+        return _backend;
+    _backend = new LocalBackend();
+    const ok = await _backend.init();
+    if (!ok) {
+        console.error('Code Mapper: No indexed repositories found. Run: code-mapper analyze');
+        process.exit(1);
+    }
+    return _backend;
+}
+function output(data) {
+    const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+    // stderr because LadybugDB captures stdout at OS level
+    process.stderr.write(text + '\n');
+    // Force exit — LadybugDB native module crashes on cleanup (mutex error)
+    // and prevents the process from exiting. This is safe because CLI is
+    // single-shot: once output is written, we're done.
+    setTimeout(() => process.exit(0), 50);
+}
+export async function queryCommand(queryText, options) {
+    if (!queryText?.trim()) {
+        console.error('Usage: code-mapper query <search_query>');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('query', {
+        query: queryText,
+        task_context: options?.context,
+        goal: options?.goal,
+        limit: options?.limit ? parseInt(options.limit) : undefined,
+        include_content: options?.content ?? false,
+        repo: options?.repo,
+    });
+    output(result);
+}
+export async function contextCommand(name, options) {
+    if (!name?.trim() && !options?.uid) {
+        console.error('Usage: code-mapper context <symbol_name> [--uid <uid>] [--file <path>]');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('context', {
+        name: name || undefined,
+        uid: options?.uid,
+        file_path: options?.file,
+        include_content: options?.content ?? false,
+        repo: options?.repo,
+    });
+    output(result);
+}
+export async function impactCommand(target, options) {
+    if (!target?.trim()) {
+        console.error('Usage: code-mapper impact <symbol_name> [--direction upstream|downstream]');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('impact', {
+        target,
+        direction: options?.direction || 'upstream',
+        maxDepth: options?.depth ? parseInt(options.depth) : undefined,
+        includeTests: options?.includeTests ?? false,
+        repo: options?.repo,
+    });
+    output(result);
+}
+export async function cypherCommand(query, options) {
+    if (!query?.trim()) {
+        console.error('Usage: code-mapper cypher <cypher_query>');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('cypher', {
+        query,
+        repo: options?.repo,
+    });
+    output(result);
+}

package/dist/config/ignore-service.d.ts

@@ -0,0 +1,32 @@
+/** @file ignore-service.ts @description Hardcoded and user-configurable ignore rules for file/directory filtering during repo traversal */
+import { type Ignore } from 'ignore';
+import type { Path } from 'path-scurry';
+/**
+ * Check whether a file path should be ignored based on hardcoded rules
+ * @param filePath - Relative or absolute file path to check
+ * @returns true if the path matches any ignore rule
+ */
+export declare const shouldIgnorePath: (filePath: string) => boolean;
+/** Check if a directory name is in the hardcoded ignore list */
+export declare const isHardcodedIgnoredDirectory: (name: string) => boolean;
+/** Options for loadIgnoreRules */
+export interface IgnoreOptions {
+    /** Skip .gitignore parsing, only read .code-mapperignore. Defaults to CODE_MAPPER_NO_GITIGNORE env var */
+    noGitignore?: boolean;
+}
+/**
+ * Load .gitignore and .code-mapperignore rules from the repo root
+ * @param repoPath - Absolute path to the repository root
+ * @returns An `ignore` instance with all patterns, or null if no files found
+ */
+export declare const loadIgnoreRules: (repoPath: string, options?: IgnoreOptions) => Promise<Ignore | null>;
+/**
+ * Create a glob-compatible ignore filter combining .gitignore/.code-mapperignore
+ * patterns with hardcoded ignore lists
+ * @param repoPath - Absolute path to the repository root
+ * @returns An IgnoreLike object for glob's `ignore` option with directory-level pruning
+ */
+export declare const createIgnoreFilter: (repoPath: string, options?: IgnoreOptions) => Promise<{
+    ignored(p: Path): boolean;
+    childrenIgnored(p: Path): boolean;
+}>;