@saluzi/codegraph 0.2.0 → 0.2.1

package/dist/upgrade/update-check.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * Background update-availability check for long-lived servers (#1243).
+ *
+ * The recommended MCP config launches the LOCAL `codegraph` binary, so the
+ * server (and the prompt hook alongside it) silently stays on whatever version
+ * was last manually upgraded — users discover the drift only when something
+ * breaks. This module gives the running server *visibility* without changing
+ * behavior: a non-blocking check against the latest GitHub release, surfaced
+ * as a one-line notice (stderr log, MCP initialize instructions, and
+ * `codegraph_status`) telling the user to run `codegraph upgrade`.
+ *
+ * Invariants (mirrors the telemetry module's contract):
+ *   - Never stdout — stdio is the MCP protocol channel.
+ *   - Never blocking: the network refresh is fire-and-forget; every reader
+ *     (`getUpdateNotice`) is a cheap synchronous cache read, so the #172
+ *     respond-fast handshake contract holds.
+ *   - Fail silent: offline / rate-limited / disk-full all degrade to "no
+ *     notice", never an error, never a retry loop.
+ *   - Off is off: `CODEGRAPH_NO_UPDATE_CHECK` (dedicated) or `DO_NOT_TRACK`
+ *     (broad don't-phone-home convention — set by e.g. the Pro container's
+ *     data plane) suppresses the network call AND the notice entirely.
+ *
+ * The check itself reuses `resolveLatestVersion` — the GitHub release-redirect
+ * trick with the API fallback — so version resolution can't drift from what
+ * `codegraph upgrade` installs. Results are cached in `~/.codegraph/` (the
+ * same global state dir telemetry and the daemon registry use) with a 24h TTL
+ * on success and a 1h backoff after failure, shared across every proxy /
+ * daemon process on the machine.
+ */
+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.UPDATE_CHECK_FAILURE_BACKOFF_MS = exports.UPDATE_CHECK_TTL_MS = void 0;
+exports.updateCheckDisabled = updateCheckDisabled;
+exports.updateCheckCachePath = updateCheckCachePath;
+exports.readUpdateCheckCache = readUpdateCheckCache;
+exports.canonicalVersionTag = canonicalVersionTag;
+exports.formatUpdateNotice = formatUpdateNotice;
+exports.refreshUpdateCheck = refreshUpdateCheck;
+exports.getUpdateNotice = getUpdateNotice;
+exports.resetUpdateNoticeMemo = resetUpdateNoticeMemo;
+exports.checkForUpdateInBackground = checkForUpdateInBackground;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const index_1 = require("./index");
+const version_1 = require("../mcp/version");
+/** Re-check the release feed after this long (successful checks). */
+exports.UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+/** Back off this long after a failed check (offline, rate-limited). */
+exports.UPDATE_CHECK_FAILURE_BACKOFF_MS = 60 * 60 * 1000;
+/** Short network budget — the refresh is background work, not a handshake. */
+const UPDATE_CHECK_NETWORK_TIMEOUT_MS = 5000;
+function resolveDeps(deps = {}) {
+    return {
+        dir: deps.dir ?? path.join(os.homedir(), '.codegraph'),
+        env: deps.env ?? process.env,
+        now: deps.now ?? Date.now,
+        resolveLatest: deps.resolveLatest ?? (() => (0, index_1.resolveLatestVersion)(undefined, UPDATE_CHECK_NETWORK_TIMEOUT_MS)),
+        currentVersion: deps.currentVersion ?? version_1.CodeGraphPackageVersion,
+    };
+}
+function envTruthy(raw) {
+    return raw !== undefined && raw !== '' && raw !== '0' && raw.toLowerCase() !== 'false';
+}
+/**
+ * True when the update check must not run at all — no network call, no
+ * notice. `DO_NOT_TRACK` uses the same truthiness the telemetry opt-out does.
+ */
+function updateCheckDisabled(env = process.env) {
+    return envTruthy(env.CODEGRAPH_NO_UPDATE_CHECK) || envTruthy(env.DO_NOT_TRACK);
+}
+function updateCheckCachePath(dir) {
+    return path.join(dir, 'update-check.json');
+}
+function readUpdateCheckCache(dir) {
+    try {
+        const raw = fs.readFileSync(updateCheckCachePath(dir), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.lastAttemptAt !== 'number')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null; // missing / torn / unparseable — same as no cache
+    }
+}
+function writeUpdateCheckCache(dir, cache) {
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(updateCheckCachePath(dir), JSON.stringify(cache));
+    }
+    catch {
+        /* fail silent — a read-only home dir must not break the server */
+    }
+}
+/**
+ * Rebuild a canonical `vX.Y.Z[-pre]` tag from the PARSED semver fields, or
+ * null when the input isn't version-shaped. The notice ends up inside the MCP
+ * initialize instructions — agent-visible, system-prompt-adjacent text — and
+ * the `latest` value arrives from a network redirect via an on-disk cache, so
+ * only a reconstructed canonical string may ever be interpolated, never the
+ * raw value. (`parseSemver`'s regex is not end-anchored: a value like
+ * `1.2.3-x <arbitrary text>` parses "valid" while the raw string would carry
+ * the trailing text straight into every session's instructions.)
+ */
+function canonicalVersionTag(v) {
+    const s = (0, index_1.parseSemver)(v);
+    if (!s)
+        return null;
+    return `v${s.major}.${s.minor}.${s.patch}${s.pre ? `-${s.pre}` : ''}`;
+}
+/** One user-facing sentence; every surface (stderr, instructions, status) shows this. */
+function formatUpdateNotice(current, latest) {
+    return (`CodeGraph ${latest} is available (this server is running ` +
+        `${current}). Update with \`codegraph upgrade\`.`);
+}
+function noticeFrom(cache, d) {
+    if (!cache?.latest)
+        return null;
+    // A dev build whose package.json couldn't be read reports the sentinel
+    // version; any comparison against it would always claim an update.
+    if (d.currentVersion === '0.0.0-unknown')
+        return null;
+    // Canonicalize BOTH sides before comparing or rendering — a non-semver
+    // `latest` (garbage redirect, tampered cache) yields no notice at all
+    // rather than flowing into agent-visible text.
+    const latest = canonicalVersionTag(cache.latest);
+    const current = canonicalVersionTag(d.currentVersion);
+    if (!latest || !current)
+        return null;
+    return (0, index_1.isUpdateAvailable)(current, latest) ? formatUpdateNotice(current, latest) : null;
+}
+function cacheIsFresh(cache, nowMs) {
+    if (!cache)
+        return false;
+    if (cache.lastSuccessAt !== undefined && nowMs - cache.lastSuccessAt < exports.UPDATE_CHECK_TTL_MS) {
+        return true;
+    }
+    // No recent success: only the failure backoff holds the network call off.
+    return nowMs - cache.lastAttemptAt < exports.UPDATE_CHECK_FAILURE_BACKOFF_MS;
+}
+/**
+ * Ensure the on-disk cache is fresh (hitting the network only past the TTL /
+ * backoff) and return the current notice, or null. Never throws.
+ */
+async function refreshUpdateCheck(deps = {}) {
+    const d = resolveDeps(deps);
+    if (updateCheckDisabled(d.env))
+        return null;
+    const cached = readUpdateCheckCache(d.dir);
+    const nowMs = d.now();
+    if (cacheIsFresh(cached, nowMs))
+        return noticeFrom(cached, d);
+    try {
+        const latest = canonicalVersionTag(await d.resolveLatest());
+        // A response that isn't version-shaped is a failure, not a result —
+        // fall through to the backoff path and keep the previous known-good tag.
+        if (!latest)
+            throw new Error('release feed returned a non-version tag');
+        const next = { lastAttemptAt: nowMs, lastSuccessAt: nowMs, latest };
+        writeUpdateCheckCache(d.dir, next);
+        return noticeFrom(next, d);
+    }
+    catch {
+        // Record the attempt (starts the backoff) but KEEP the previous latest —
+        // a transient outage must not hide an already-known update.
+        const next = {
+            lastAttemptAt: nowMs,
+            lastSuccessAt: cached?.lastSuccessAt,
+            latest: cached?.latest,
+        };
+        writeUpdateCheckCache(d.dir, next);
+        return noticeFrom(next, d);
+    }
+}
+// Per-process memo so the sync read path (MCP initialize, codegraph_status)
+// touches the disk at most once a minute, not once per handshake.
+const NOTICE_MEMO_TTL_MS = 60 * 1000;
+let noticeMemo = null;
+/**
+ * The current update notice from the on-disk cache — synchronous and cheap
+ * (memoized disk read), safe on the initialize respond-fast path. When the
+ * cache has gone stale (e.g. a daemon that has been up for weeks), kicks a
+ * background refresh so the NEXT reader sees a current answer; this call
+ * still returns immediately from the stale cache.
+ */
+function getUpdateNotice(deps = {}) {
+    const d = resolveDeps(deps);
+    if (updateCheckDisabled(d.env))
+        return null;
+    const useMemo = deps.dir === undefined && deps.now === undefined;
+    const nowMs = d.now();
+    if (useMemo && noticeMemo && nowMs - noticeMemo.at < NOTICE_MEMO_TTL_MS) {
+        return noticeMemo.value;
+    }
+    const cached = readUpdateCheckCache(d.dir);
+    if (!cacheIsFresh(cached, nowMs)) {
+        void refreshUpdateCheck(deps).catch(() => { });
+    }
+    const value = noticeFrom(cached, d);
+    if (useMemo)
+        noticeMemo = { at: nowMs, value };
+    return value;
+}
+/** Test hook: clear the per-process memo. */
+function resetUpdateNoticeMemo() {
+    noticeMemo = null;
+}
+/**
+ * Fire-and-forget entry point for server startup: refresh the cache in the
+ * background and, if an update is available, emit ONE stderr line (stderr is
+ * the MCP-safe channel; hosts surface it in their server logs). Never throws,
+ * never blocks, never writes stdout.
+ */
+function checkForUpdateInBackground(deps = {}, log = (line) => process.stderr.write(line)) {
+    refreshUpdateCheck(deps)
+        .then((notice) => {
+        // The shared notice sentence starts with "CodeGraph …"; drop the word
+        // after the log tag so the line doesn't read "[CodeGraph] CodeGraph …".
+        if (notice)
+            log(`[CodeGraph] ${notice.replace(/^CodeGraph /, '')}\n`);
+    })
+        .catch(() => { });
+}
+//# sourceMappingURL=update-check.js.map

package/dist/upgrade/update-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.js","sourceRoot":"","sources":["../../src/upgrade/update-check.ts"],"names":[],"mappings":"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"}

package/dist/utils.d.ts

@@ -0,0 +1,224 @@
+/**
+ * CodeGraph Utilities
+ *
+ * Common utility functions for memory management, concurrency, batching,
+ * and security validation.
+ *
+ * @module utils
+ *
+ * @example
+ * ```typescript
+ * import { Mutex, processInBatches, MemoryMonitor, validatePathWithinRoot } from 'codegraph';
+ *
+ * // Use mutex for concurrent safety
+ * const mutex = new Mutex();
+ * await mutex.withLock(async () => {
+ *   await performCriticalOperation();
+ * });
+ *
+ * // Process items in batches to manage memory
+ * const results = await processInBatches(items, 100, async (item) => {
+ *   return await processItem(item);
+ * });
+ *
+ * // Monitor memory usage
+ * const monitor = new MemoryMonitor(512, (usage) => {
+ *   console.warn(`Memory usage exceeded 512MB: ${usage / 1024 / 1024}MB`);
+ * });
+ * monitor.start();
+ * ```
+ */
+/**
+ * Config "languages" whose nodes are pure key/value DATA lifted from a config
+ * file (e.g. Spring `application.{yml,properties}`), not source code.
+ */
+export declare const CONFIG_LEAF_LANGUAGES: ReadonlySet<string>;
+/**
+ * A config-leaf node is a single key lifted out of a pure config/data file —
+ * `kind: 'constant'` in a {@link CONFIG_LEAF_LANGUAGES} language. Its on-disk
+ * line is `key = <value>`, and that value is routinely a secret (DB password,
+ * API key, JDBC URL with embedded creds). CodeGraph must surface the KEY only
+ * and never read/return the value, or it pushes secrets into agent context
+ * unbidden — the value isn't needed for resolution, and an agent that genuinely
+ * needs it can read the file directly. (#383)
+ */
+export declare function isConfigLeafNode(node: {
+    kind: string;
+    language?: string;
+}): boolean;
+/**
+ * Validate that a file path stays within the project root, resolving symlinks.
+ *
+ * Two layers: a cheap lexical check that catches `../` traversal, then a
+ * realpath check that catches symlink escapes — an in-repo symlink whose
+ * logical path is inside the root but whose real target points outside it
+ * (issue #527). A symlink that stays within the root is still allowed, so
+ * legitimate in-tree symlinks keep working. Both content-serving read sinks
+ * (codegraph_node `includeCode`, codegraph_explore source) go through here, so
+ * this is the chokepoint that keeps out-of-root file contents from leaking.
+ *
+ * `allowSymlinkEscape` waives **only** the realpath-escape rejection (the
+ * lexical `../` guard still applies) for the INDEXING read path. The directory
+ * walk deliberately descends into in-root symlinks whose targets live outside
+ * the root (e.g. a `game/` symlink in a Dota custom-game tree, #935); discovery
+ * and the reader must agree, or every file the walk enumerated fails to index.
+ * Indexing only reads paths it just discovered, into a local index — it never
+ * serves them to an agent, so this does not widen the #527 leak surface. The
+ * content-serving sinks must never pass this flag.
+ *
+ * @param projectRoot - The project root directory
+ * @param filePath - The (relative or absolute) file path to validate
+ * @param options.allowSymlinkEscape - Follow in-root symlinks out of the root
+ *   (indexing read path only); defaults to the strict, leak-safe behavior.
+ * @returns The resolved absolute path (realpath when it exists), or null if it
+ *   escapes the root
+ */
+export declare function validatePathWithinRoot(projectRoot: string, filePath: string, options?: {
+    allowSymlinkEscape?: boolean;
+}): string | null;
+/**
+ * Validate that a path is a safe project root directory.
+ *
+ * Rejects sensitive system directories and ensures the path is
+ * a real, existing directory. Used at MCP and API entry points
+ * to prevent arbitrary directory access.
+ *
+ * @param dirPath - The path to validate
+ * @returns An error message if invalid, or null if valid
+ */
+export declare function validateProjectPath(dirPath: string): string | null;
+/**
+ * Safely parse JSON with a fallback value.
+ * Prevents crashes from corrupted database metadata.
+ */
+export declare function safeJsonParse<T>(value: string, fallback: T): T;
+/**
+ * Clamp a numeric value to a range.
+ * Used to enforce sane limits on MCP tool inputs.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Normalize a file path to use forward slashes.
+ * Fixes Windows backslash paths so glob matching works consistently.
+ */
+export declare function normalizePath(filePath: string): string;
+/**
+ * Cross-process file lock using a lock file with PID tracking.
+ *
+ * Prevents multiple processes (e.g., git hooks, CLI, MCP server) from
+ * writing to the same database simultaneously.
+ */
+export declare class FileLock {
+    private lockPath;
+    private held;
+    /** Locks older than this are considered stale regardless of PID status */
+    private static readonly STALE_TIMEOUT_MS;
+    constructor(lockPath: string);
+    /**
+     * Acquire the lock. Throws if the lock is held by another live process.
+     */
+    acquire(): void;
+    /**
+     * Release the lock
+     */
+    release(): void;
+    /**
+     * Execute a function while holding the lock
+     */
+    withLock<T>(fn: () => T): T;
+    /**
+     * Execute an async function while holding the lock
+     */
+    withLockAsync<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Check if a process is still running
+     */
+    private isProcessAlive;
+}
+/**
+ * Process items in batches to manage memory
+ *
+ * @param items - Array of items to process
+ * @param batchSize - Number of items per batch
+ * @param processor - Function to process each item
+ * @param onBatchComplete - Optional callback after each batch
+ * @returns Array of results
+ */
+export declare function processInBatches<T, R>(items: T[], batchSize: number, processor: (item: T, index: number) => Promise<R>, onBatchComplete?: (completed: number, total: number) => void): Promise<R[]>;
+/**
+ * Simple mutex lock for preventing concurrent operations
+ */
+export declare class Mutex {
+    private locked;
+    private waitQueue;
+    /**
+     * Acquire the lock
+     *
+     * @returns A release function to call when done
+     */
+    acquire(): Promise<() => void>;
+    /**
+     * Execute a function while holding the lock
+     */
+    withLock<T>(fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * Check if the lock is currently held
+     */
+    isLocked(): boolean;
+}
+/**
+ * Chunked file reader for large files
+ *
+ * Reads a file in chunks to avoid loading entire file into memory.
+ */
+export declare function readFileInChunks(filePath: string, chunkSize?: number): AsyncGenerator<string, void, undefined>;
+/**
+ * Debounce a function
+ *
+ * @param fn - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ */
+export declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle a function
+ *
+ * @param fn - Function to throttle
+ * @param limit - Minimum time between calls in milliseconds
+ * @returns Throttled function
+ */
+export declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * Estimate memory usage of an object (rough approximation)
+ *
+ * @param obj - Object to measure
+ * @returns Approximate size in bytes
+ */
+export declare function estimateSize(obj: unknown): number;
+/**
+ * Memory monitor for tracking usage during operations
+ */
+export declare class MemoryMonitor {
+    private checkInterval;
+    private peakUsage;
+    private threshold;
+    private onThresholdExceeded?;
+    constructor(thresholdMB?: number, onThresholdExceeded?: (usage: number) => void);
+    /**
+     * Start monitoring memory usage
+     */
+    start(intervalMs?: number): void;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    /**
+     * Get peak memory usage in bytes
+     */
+    getPeakUsage(): number;
+    /**
+     * Get current memory usage in bytes
+     */
+    getCurrentUsage(): number;
+}
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}