@colbymchenry/codegraph 1.0.1 → 1.1.0

package/dist/sync/watcher.d.ts

@@ -30,6 +30,16 @@
  * events are dropped before any sync is scheduled. Either way the watcher's
  * scope matches the indexer's (#276 / #407).
  */
+import * as fs from 'fs';
+/**
+ * Indirection over `fs.watch` so tests can inject a fake that throws or emits
+ * `EMFILE`/`ENFILE` deterministically (real watch-resource exhaustion can't be
+ * provoked reliably, and `fs.watch` is a non-configurable property so it can't
+ * be spied). Production always uses the real `fs.watch`.
+ */
+type WatchFn = typeof fs.watch;
+/** @internal Test-only seam to inject a fake fs.watch implementation. */
+export declare function __setFsWatchForTests(fn: WatchFn | null): void;
 /**
  * Options for the file watcher
  */
@@ -51,6 +61,14 @@ export interface WatchOptions {
      * Callback when a sync errors (for logging/diagnostics).
      */
     onSyncError?: (error: Error) => void;
+    /**
+     * Callback fired ONCE when live watching degrades permanently and auto-sync
+     * is disabled — OS watch-resource exhaustion (EMFILE/ENFILE), or a write lock
+     * held past the retry budget. The string is an actionable, human-readable
+     * reason. Lets a host (MCP server, daemon, CLI) tell the user that the index
+     * will no longer auto-update instead of silently serving stale results.
+     */
+    onDegraded?: (reason: string) => void;
     /**
      * Test-only. When true, `start()` installs NO OS-level fs.watch — the
      * watcher is "inert" and only the {@link __emitWatchEventForTests} /
@@ -111,6 +129,22 @@ export declare class FileWatcher {
     private dirWatchers;
     /** Set once the per-directory watch cap is hit, so we log only once. */
     private dirCapWarned;
+    /**
+     * Set once the Linux inotify watch limit (ENOSPC) is hit. Double duty: we
+     * warn only once, AND we stop attempting new directory watches for the rest
+     * of the session — once the kernel budget is exhausted every further
+     * `inotify_add_watch` fails too, so trying the rest of the tree is pure
+     * waste. NON-fatal (does not degrade): installed watches keep working.
+     */
+    private inotifyLimitWarned;
+    /**
+     * One-way latch: the reason live watching was permanently disabled at runtime
+     * (watch-resource exhaustion, or lock contention past the retry budget), or
+     * null while healthy. Set by {@link degrade}; cleared only by a fresh start().
+     */
+    private degradedReason;
+    /** Consecutive lock-contention retries for watcher-triggered syncs. */
+    private lockRetryCount;
     /** Test-only inert mode: started, but with no OS watcher installed. */
     private inert;
     private debounceTimer;
@@ -152,6 +186,7 @@ export declare class FileWatcher {
     private readonly syncFn;
     private readonly onSyncComplete?;
     private readonly onSyncError?;
+    private readonly onDegraded?;
     private readonly inertForTests;
     constructor(projectRoot: string, syncFn: () => Promise<{
         filesChanged: number;
@@ -211,6 +246,31 @@ export declare class FileWatcher {
      * dir-only ignore rule like `build/` matches.
      */
     private shouldIgnoreDir;
+    /**
+     * Permanently disable live watching after a terminal runtime failure
+     * (watch-resource exhaustion, or lock contention past the retry budget).
+     * Idempotent: logs one actionable warning, fires {@link WatchOptions.onDegraded}
+     * once, and stops the watcher. A subsequent start() clears the latch.
+     */
+    private degrade;
+    /**
+     * Warn ONCE that the Linux inotify watch budget is exhausted (ENOSPC), and
+     * stop adding new watches for the rest of this session — every further
+     * `inotify_add_watch` would fail too, so walking the rest of the tree is
+     * waste. Unlike {@link degrade} this is NON-fatal: the watches already
+     * installed keep firing, and `codegraph sync` covers the unwatched remainder.
+     * The message names the kernel knob to raise (`fs.inotify.max_user_watches`).
+     */
+    private warnInotifyLimit;
+    /**
+     * Whether live watching has degraded permanently (until the next start()).
+     * Distinct from {@link isActive}: a degraded watcher is inactive, but an
+     * inactive watcher is not necessarily degraded (it may simply be stopped or
+     * never started). Hosts use this to tell the user auto-sync is off.
+     */
+    isDegraded(): boolean;
+    /** The reason live watching degraded, or null if it is healthy. */
+    getDegradedReason(): string | null;
     /**
      * Stop watching for file changes.
      */
@@ -238,9 +298,15 @@ export declare class FileWatcher {
      */
     waitUntilReady(timeoutMs?: number): Promise<void>;
     /**
-     * Schedule a debounced sync.
+     * Schedule a normal debounced sync after a source edit.
      */
     private scheduleSync;
+    /**
+     * Schedule a retry after a recoverable sync failure (lock contention). Kept
+     * separate from {@link scheduleSync} so prolonged contention backs off
+     * exponentially instead of hammering the lock every debounce cycle.
+     */
+    private scheduleRetrySync;
     /**
      * Flush pending changes by running sync.
      *
@@ -280,4 +346,5 @@ export declare class FileWatcher {
  * test runtime, where the registry is intentionally not populated).
  */
 export declare function __emitWatchEventForTests(projectRoot: string, relPath: string): boolean;
+export {};
 //# sourceMappingURL=watcher.d.ts.map

package/dist/telemetry/index.d.ts

@@ -28,8 +28,6 @@ export type LifecycleEvent = 'install' | 'index' | 'uninstall';
 /** Coarse buckets — exact counts are deliberately not collected. */
 export declare function bucketFileCount(n: number): '<100' | '100-1k' | '1k-10k' | '10k+';
 export declare function bucketDuration(ms: number): '<10s' | '10-60s' | '1-5m' | '5m+';
-/** Collapse a backend identifier (e.g. `node-sqlite`) to the schema's enum. */
-export declare function backendKind(backend: string): 'native' | 'wasm';
 /**
  * Shared "a full index completed" event (CLI init/index + installer local
  * init): language names and coarse buckets only — never paths, file names,
@@ -39,7 +37,6 @@ export declare function recordIndexEvent(cg: {
     getStats(): {
         filesByLanguage: Record<string, number>;
     };
-    getBackend(): string;
 }, result: {
     filesIndexed: number;
     durationMs: number;

package/dist/utils.d.ts

@@ -57,12 +57,25 @@ export declare function isConfigLeafNode(node: {
  * (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): string | null;
+export declare function validatePathWithinRoot(projectRoot: string, filePath: string, options?: {
+    allowSymlinkEscape?: boolean;
+}): string | null;
 /**
  * Validate that a path is a safe project root directory.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colbymchenry/codegraph",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
   "bin": {
     "codegraph": "npm-shim.js"
@@ -15,12 +15,12 @@
     "./package.json": "./package.json"
   },
   "optionalDependencies": {
-    "@colbymchenry/codegraph-darwin-arm64": "1.0.1",
-    "@colbymchenry/codegraph-darwin-x64": "1.0.1",
-    "@colbymchenry/codegraph-linux-arm64": "1.0.1",
-    "@colbymchenry/codegraph-linux-x64": "1.0.1",
-    "@colbymchenry/codegraph-win32-arm64": "1.0.1",
-    "@colbymchenry/codegraph-win32-x64": "1.0.1"
+    "@colbymchenry/codegraph-darwin-arm64": "1.1.0",
+    "@colbymchenry/codegraph-darwin-x64": "1.1.0",
+    "@colbymchenry/codegraph-linux-arm64": "1.1.0",
+    "@colbymchenry/codegraph-linux-x64": "1.1.0",
+    "@colbymchenry/codegraph-win32-arm64": "1.1.0",
+    "@colbymchenry/codegraph-win32-x64": "1.1.0"
   },
   "files": [
     "npm-shim.js",