@saluzi/codegraph 0.1.0 → 0.2.0

package/dist/sync/git-hooks.js

@@ -1,223 +0,0 @@
-"use strict";
-/**
- * Git Sync Hooks
- *
- * When the live file watcher is disabled (e.g. on WSL2 `/mnt/*` drives,
- * see watch-policy.ts), the CodeGraph index would otherwise go stale until
- * the user runs `codegraph sync` by hand. As an opt-in alternative, we can
- * install git hooks that refresh the index after the operations that change
- * files on disk: commit, merge (covers `git pull`), and checkout.
- *
- * The hooks run `codegraph sync` in the background so they never block git,
- * and are guarded by `command -v codegraph` so they no-op cleanly when the
- * CLI isn't on PATH. Our snippet is delimited by marker comments so install
- * is idempotent and removal preserves any user-authored hook content.
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SYNC_HOOKS = void 0;
-exports.isGitRepo = isGitRepo;
-exports.installGitSyncHook = installGitSyncHook;
-exports.removeGitSyncHook = removeGitSyncHook;
-exports.isSyncHookInstalled = isSyncHookInstalled;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
-const MARKER_BEGIN = '# >>> codegraph sync hook >>>';
-const MARKER_END = '# <<< codegraph sync hook <<<';
-/** Hooks installed by default: commit, merge (git pull), and checkout. */
-exports.DEFAULT_SYNC_HOOKS = ['post-commit', 'post-merge', 'post-checkout'];
-/**
- * Whether `projectRoot` is inside a git working tree. Returns false if git
- * isn't installed or the path isn't a repo.
- */
-function isGitRepo(projectRoot) {
-    try {
-        const out = (0, child_process_1.execFileSync)('git', ['rev-parse', '--is-inside-work-tree'], {
-            cwd: projectRoot,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
-        return out === 'true';
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Resolve the git hooks directory for a project, honoring `core.hooksPath`
- * and git worktrees. Returns an absolute path, or null when not a repo.
- */
-function gitHooksDir(projectRoot) {
-    try {
-        const out = (0, child_process_1.execFileSync)('git', ['rev-parse', '--git-path', 'hooks'], {
-            cwd: projectRoot,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
-        if (!out)
-            return null;
-        return path.isAbsolute(out) ? out : path.resolve(projectRoot, out);
-    }
-    catch {
-        return null;
-    }
-}
-/** The shell snippet (between markers) injected into each hook. */
-function markerBlock() {
-    return [
-        MARKER_BEGIN,
-        '# Keeps the CodeGraph index fresh while the live file watcher is off',
-        '# (e.g. WSL2 /mnt drives). Runs in the background so it never blocks git.',
-        '# Managed by codegraph; remove with `codegraph uninit` or delete this block.',
-        'if command -v codegraph >/dev/null 2>&1; then',
-        '  ( codegraph sync >/dev/null 2>&1 & ) >/dev/null 2>&1',
-        'fi',
-        MARKER_END,
-    ].join('\n');
-}
-/** Remove our marker block (and the marker lines) from hook content. */
-function stripMarkerBlock(content) {
-    const lines = content.split('\n');
-    const kept = [];
-    let inBlock = false;
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (trimmed === MARKER_BEGIN) {
-            inBlock = true;
-            continue;
-        }
-        if (trimmed === MARKER_END) {
-            inBlock = false;
-            continue;
-        }
-        if (!inBlock)
-            kept.push(line);
-    }
-    return kept.join('\n');
-}
-/** Whether a hook body is just a shebang / blank lines (i.e. only ever ours). */
-function isEffectivelyEmpty(content) {
-    return content
-        .split('\n')
-        .map((l) => l.trim())
-        .every((l) => l.length === 0 || l.startsWith('#!'));
-}
-function chmodExecutable(file) {
-    try {
-        fs.chmodSync(file, 0o755);
-    }
-    catch {
-        /* chmod is a no-op / unsupported on some platforms (e.g. Windows) */
-    }
-}
-/**
- * Install (or update) the CodeGraph sync hooks in a git repository.
- * Idempotent: re-running replaces our marker block rather than duplicating
- * it, and any user-authored hook content is preserved.
- */
-function installGitSyncHook(projectRoot, hooks = exports.DEFAULT_SYNC_HOOKS) {
-    const hooksDir = gitHooksDir(projectRoot);
-    if (!hooksDir) {
-        return { installed: [], hooksDir: null, skipped: 'not a git repository' };
-    }
-    try {
-        fs.mkdirSync(hooksDir, { recursive: true });
-    }
-    catch {
-        return { installed: [], hooksDir, skipped: 'could not access the git hooks directory' };
-    }
-    const block = markerBlock();
-    const installed = [];
-    for (const hook of hooks) {
-        const file = path.join(hooksDir, hook);
-        let content;
-        if (fs.existsSync(file)) {
-            // Strip any prior block, then re-append the current one.
-            const base = stripMarkerBlock(fs.readFileSync(file, 'utf8')).replace(/\s*$/, '');
-            content = base.length > 0
-                ? `${base}\n\n${block}\n`
-                : `#!/bin/sh\n${block}\n`;
-        }
-        else {
-            content = `#!/bin/sh\n${block}\n`;
-        }
-        fs.writeFileSync(file, content);
-        chmodExecutable(file);
-        installed.push(hook);
-    }
-    return { installed, hooksDir };
-}
-/**
- * Remove the CodeGraph sync hooks. Strips only our marker block; deletes the
- * hook file entirely when nothing but a shebang remains, otherwise rewrites
- * the user's content untouched.
- */
-function removeGitSyncHook(projectRoot, hooks = exports.DEFAULT_SYNC_HOOKS) {
-    const hooksDir = gitHooksDir(projectRoot);
-    if (!hooksDir) {
-        return { installed: [], hooksDir: null, skipped: 'not a git repository' };
-    }
-    const removed = [];
-    for (const hook of hooks) {
-        const file = path.join(hooksDir, hook);
-        if (!fs.existsSync(file))
-            continue;
-        const original = fs.readFileSync(file, 'utf8');
-        if (!original.includes(MARKER_BEGIN))
-            continue;
-        const stripped = stripMarkerBlock(original);
-        if (isEffectivelyEmpty(stripped)) {
-            fs.unlinkSync(file);
-        }
-        else {
-            fs.writeFileSync(file, `${stripped.replace(/\s*$/, '')}\n`);
-            chmodExecutable(file);
-        }
-        removed.push(hook);
-    }
-    return { installed: removed, hooksDir };
-}
-/** Whether any CodeGraph sync hook is currently installed. */
-function isSyncHookInstalled(projectRoot, hooks = exports.DEFAULT_SYNC_HOOKS) {
-    const hooksDir = gitHooksDir(projectRoot);
-    if (!hooksDir)
-        return false;
-    return hooks.some((hook) => {
-        const file = path.join(hooksDir, hook);
-        return fs.existsSync(file) && fs.readFileSync(file, 'utf8').includes(MARKER_BEGIN);
-    });
-}
-//# sourceMappingURL=git-hooks.js.map

package/dist/sync/index.d.ts

@@ -1,25 +0,0 @@
-/**
- * Sync Module
- *
- * Provides synchronization functionality for keeping the code graph
- * up-to-date with file system changes.
- *
- * Components:
- * - FileWatcher: Debounced fs.watch that auto-triggers sync on file changes
- * - Watch policy: decides when the watcher must be disabled (e.g. WSL2 /mnt)
- * - Git sync hooks: opt-in commit/merge/checkout hooks when watching is off
- * - Content hashing for change detection (in extraction module)
- * - Incremental reindexing (in extraction module)
- */
-export { FileWatcher, WatchOptions } from './watcher'
-export { watchDisabledReason, detectWsl } from './watch-policy'
-export {
-  installGitSyncHook,
-  removeGitSyncHook,
-  isSyncHookInstalled,
-  isGitRepo,
-  DEFAULT_SYNC_HOOKS,
-  type GitHookName,
-  type GitHookResult,
-} from './git-hooks'
-//# sourceMappingURL=index.d.ts.map

package/dist/sync/index.js

@@ -1,28 +0,0 @@
-"use strict";
-/**
- * Sync Module
- *
- * Provides synchronization functionality for keeping the code graph
- * up-to-date with file system changes.
- *
- * Components:
- * - FileWatcher: Debounced fs.watch that auto-triggers sync on file changes
- * - Watch policy: decides when the watcher must be disabled (e.g. WSL2 /mnt)
- * - Git sync hooks: opt-in commit/merge/checkout hooks when watching is off
- * - Content hashing for change detection (in extraction module)
- * - Incremental reindexing (in extraction module)
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SYNC_HOOKS = exports.isGitRepo = exports.isSyncHookInstalled = exports.removeGitSyncHook = exports.installGitSyncHook = exports.detectWsl = exports.watchDisabledReason = exports.FileWatcher = void 0;
-var watcher_1 = require("./watcher");
-Object.defineProperty(exports, "FileWatcher", { enumerable: true, get: function () { return watcher_1.FileWatcher; } });
-var watch_policy_1 = require("./watch-policy");
-Object.defineProperty(exports, "watchDisabledReason", { enumerable: true, get: function () { return watch_policy_1.watchDisabledReason; } });
-Object.defineProperty(exports, "detectWsl", { enumerable: true, get: function () { return watch_policy_1.detectWsl; } });
-var git_hooks_1 = require("./git-hooks");
-Object.defineProperty(exports, "installGitSyncHook", { enumerable: true, get: function () { return git_hooks_1.installGitSyncHook; } });
-Object.defineProperty(exports, "removeGitSyncHook", { enumerable: true, get: function () { return git_hooks_1.removeGitSyncHook; } });
-Object.defineProperty(exports, "isSyncHookInstalled", { enumerable: true, get: function () { return git_hooks_1.isSyncHookInstalled; } });
-Object.defineProperty(exports, "isGitRepo", { enumerable: true, get: function () { return git_hooks_1.isGitRepo; } });
-Object.defineProperty(exports, "DEFAULT_SYNC_HOOKS", { enumerable: true, get: function () { return git_hooks_1.DEFAULT_SYNC_HOOKS; } });
-//# sourceMappingURL=index.js.map

package/dist/sync/watch-policy.d.ts

@@ -1,51 +0,0 @@
-/**
- * Watch Policy
- *
- * Decides whether the live file watcher should run for a given project.
- *
- * Native recursive `fs.watch` is pathologically slow on WSL2 `/mnt/*`
- * drives (NTFS exposed over the 9p/drvfs bridge): setting up the recursive
- * watch walks the directory tree, and every readdir/stat crosses the
- * Windows boundary. Inside an MCP server this stalls the event loop during
- * startup long enough to blow past host handshake timeouts (opencode's 30s),
- * so the tools never appear. See issue #199.
- *
- * This module centralizes the on/off decision so the watcher, the MCP
- * server (for diagnostics), and the installer all agree.
- */
-/**
- * Detect whether the current process is running under WSL (Windows
- * Subsystem for Linux). Result is cached after the first call.
- *
- * Checks the WSL-specific env vars first (no I/O), then falls back to
- * `/proc/version`, which contains "microsoft" on WSL kernels.
- */
-export declare function detectWsl(): boolean
-/**
- * Inputs that can be overridden in tests so the decision is deterministic
- * without touching real env vars or `/proc/version`.
- */
-export interface WatchProbe {
-  /** Defaults to `process.env`. */
-  env?: NodeJS.ProcessEnv
-  /** Defaults to `detectWsl()`. */
-  isWsl?: boolean
-}
-/**
- * Decide whether the file watcher should be disabled for a project, and why.
- *
- * Returns a short human-readable reason when watching should be skipped, or
- * `null` when it should run normally.
- *
- * Precedence (first match wins):
- *  1. `CODEGRAPH_NO_WATCH=1`    → off  (explicit opt-out always wins)
- *  2. `CODEGRAPH_FORCE_WATCH=1` → on   (overrides auto-detection)
- *  3. WSL2 + `/mnt/*` drive     → off  (recursive fs.watch is too slow; #199)
- */
-export declare function watchDisabledReason(
-  projectRoot: string,
-  probe?: WatchProbe,
-): string | null
-/** Test-only: reset the cached WSL detection. */
-export declare function __resetWslCacheForTests(): void
-//# sourceMappingURL=watch-policy.d.ts.map

package/dist/sync/watch-policy.js

@@ -1,124 +0,0 @@
-"use strict";
-/**
- * Watch Policy
- *
- * Decides whether the live file watcher should run for a given project.
- *
- * Native recursive `fs.watch` is pathologically slow on WSL2 `/mnt/*`
- * drives (NTFS exposed over the 9p/drvfs bridge): setting up the recursive
- * watch walks the directory tree, and every readdir/stat crosses the
- * Windows boundary. Inside an MCP server this stalls the event loop during
- * startup long enough to blow past host handshake timeouts (opencode's 30s),
- * so the tools never appear. See issue #199.
- *
- * This module centralizes the on/off decision so the watcher, the MCP
- * server (for diagnostics), and the installer all agree.
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.detectWsl = detectWsl;
-exports.watchDisabledReason = watchDisabledReason;
-exports.__resetWslCacheForTests = __resetWslCacheForTests;
-const fs = __importStar(require("fs"));
-const utils_1 = require("../utils");
-let wslChecked = false;
-let wslValue = false;
-/**
- * Detect whether the current process is running under WSL (Windows
- * Subsystem for Linux). Result is cached after the first call.
- *
- * Checks the WSL-specific env vars first (no I/O), then falls back to
- * `/proc/version`, which contains "microsoft" on WSL kernels.
- */
-function detectWsl() {
-    if (wslChecked)
-        return wslValue;
-    wslChecked = true;
-    if (process.platform !== 'linux') {
-        wslValue = false;
-        return wslValue;
-    }
-    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) {
-        wslValue = true;
-        return wslValue;
-    }
-    try {
-        const version = fs.readFileSync('/proc/version', 'utf8').toLowerCase();
-        wslValue = version.includes('microsoft') || version.includes('wsl');
-    }
-    catch {
-        wslValue = false;
-    }
-    return wslValue;
-}
-/**
- * True for WSL Windows-drive mounts like `/mnt/c` or `/mnt/d/project`.
- * Deliberately matches only single-letter drive mounts, so genuinely fast
- * Linux mounts such as `/mnt/wsl/...` are not flagged.
- */
-function isWindowsDriveMount(projectRoot) {
-    return /^\/mnt\/[a-z](\/|$)/i.test((0, utils_1.normalizePath)(projectRoot));
-}
-/**
- * Decide whether the file watcher should be disabled for a project, and why.
- *
- * Returns a short human-readable reason when watching should be skipped, or
- * `null` when it should run normally.
- *
- * Precedence (first match wins):
- *  1. `CODEGRAPH_NO_WATCH=1`    → off  (explicit opt-out always wins)
- *  2. `CODEGRAPH_FORCE_WATCH=1` → on   (overrides auto-detection)
- *  3. WSL2 + `/mnt/*` drive     → off  (recursive fs.watch is too slow; #199)
- */
-function watchDisabledReason(projectRoot, probe = {}) {
-    const env = probe.env ?? process.env;
-    if (env.CODEGRAPH_NO_WATCH === '1') {
-        return 'CODEGRAPH_NO_WATCH=1 is set';
-    }
-    if (env.CODEGRAPH_FORCE_WATCH === '1') {
-        return null;
-    }
-    const isWsl = probe.isWsl ?? detectWsl();
-    if (isWsl && isWindowsDriveMount(projectRoot)) {
-        return 'project is on a WSL2 /mnt/ drive, where recursive fs.watch is too slow to be reliable';
-    }
-    return null;
-}
-/** Test-only: reset the cached WSL detection. */
-function __resetWslCacheForTests() {
-    wslChecked = false;
-    wslValue = false;
-}
-//# sourceMappingURL=watch-policy.js.map

package/dist/sync/watcher.d.ts

@@ -1,83 +0,0 @@
-/**
- * File Watcher
- *
- * Watches the project directory for file changes and triggers
- * debounced sync operations to keep the code graph up-to-date.
- *
- * Uses Node.js native fs.watch with recursive mode (macOS FSEvents,
- * Windows ReadDirectoryChangesW, Linux inotify on Node 19+).
- */
-/**
- * Options for the file watcher
- */
-export interface WatchOptions {
-  /**
-   * Debounce delay in milliseconds.
-   * After the last file change, wait this long before triggering sync.
-   * Default: 2000ms
-   */
-  debounceMs?: number
-  /**
-   * Callback when a sync completes (for logging/diagnostics).
-   */
-  onSyncComplete?: (result: {
-    filesChanged: number
-    durationMs: number
-  }) => void
-  /**
-   * Callback when a sync errors (for logging/diagnostics).
-   */
-  onSyncError?: (error: Error) => void
-}
-/**
- * FileWatcher monitors a project directory for changes and triggers
- * debounced sync operations via a provided callback.
- *
- * Design goals:
- * - Minimal resource usage (native OS file events, no polling)
- * - Debounced to avoid thrashing on rapid saves
- * - Filters to supported source files by extension
- * - Ignores .codegraph/ directory changes
- */
-export declare class FileWatcher {
-  private watcher
-  private debounceTimer
-  private hasChanges
-  private syncing
-  private stopped
-  private readonly projectRoot
-  private readonly debounceMs
-  private readonly syncFn
-  private readonly onSyncComplete?
-  private readonly onSyncError?
-  constructor(
-    projectRoot: string,
-    syncFn: () => Promise<{
-      filesChanged: number
-      durationMs: number
-    }>,
-    options?: WatchOptions,
-  )
-  /**
-   * Start watching for file changes.
-   * Returns true if watching started successfully, false otherwise.
-   */
-  start(): boolean
-  /**
-   * Stop watching for file changes.
-   */
-  stop(): void
-  /**
-   * Whether the watcher is currently active.
-   */
-  isActive(): boolean
-  /**
-   * Schedule a debounced sync.
-   */
-  private scheduleSync
-  /**
-   * Flush pending changes by running sync.
-   */
-  private flush
-}
-//# sourceMappingURL=watcher.d.ts.map