@lzehrung/codegraph 3.0.1 → 3.1.1

package/dist/mcp/index-readiness.js.map

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

package/dist/mcp/project-watcher.d.ts

@@ -0,0 +1,125 @@
+import { type AgentSession } from "../agent/session.js";
+/** Quiet time after the last file event before the burst counts as settled. */
+export declare const DEFAULT_MCP_WATCH_DEBOUNCE_MS = 500;
+/** Idle time without a tool call before the watcher pauses. */
+export declare const DEFAULT_MCP_WATCH_IDLE_MS: number;
+/**
+ * Minimum time from the end of one background refresh to the start of the next. Defaults to the session's own
+ * freshness-check interval.
+ */
+export declare const DEFAULT_MCP_WATCH_MIN_REFRESH_INTERVAL_MS = 5000;
+/** The part of `fs.FSWatcher` the project watcher uses. */
+export type ProjectWatchHandle = {
+    close(): void;
+    unref(): unknown;
+    on(event: "error", listener: (error: Error) => void): unknown;
+};
+/** Seam for tests; the default is `fs.watch`. */
+export type ProjectWatchFactory = (directory: string, options: {
+    recursive: boolean;
+}, listener: (eventType: string, filename: string | null) => void) => ProjectWatchHandle;
+export type ProjectWatcher = {
+    /**
+     * Per-directory mode: re-reads `listFiles` and adds or closes watches. Recursive mode: opens the root handle again
+     * once the root directory exists, after the handle was lost with it.
+     */
+    refreshDirectories: () => Promise<void>;
+    /** Closes every handle and cancels the pending settle timer. Safe to call twice. */
+    close: () => void;
+};
+export type ProjectWatcherOptions = {
+    root: string;
+    /**
+     * Called synchronously for every event outside an ignored directory, for every watch error, and when a watched
+     * directory is removed.
+     */
+    onChange: () => void;
+    /** Called once, `debounceMs` after the last event. */
+    onSettled: () => void;
+    /** Discovered project files. Read only in per-directory mode. */
+    listFiles: () => Promise<readonly string[]>;
+    /**
+     * The directory that the session writes its disk cache to (`resolveCacheLocation`). One inside the project is ignored
+     * as `.codegraph` is, so that the server's own cache writes wake nothing.
+     */
+    cacheDirectory?: string | undefined;
+    /** Defaults to {@link DEFAULT_MCP_WATCH_DEBOUNCE_MS}. */
+    debounceMs?: number | undefined;
+    /** Defaults to `process.platform`. */
+    platform?: NodeJS.Platform | undefined;
+    /** Defaults to `fs.watch`. */
+    watch?: ProjectWatchFactory | undefined;
+    /** Defaults to `console.error`. */
+    log?: ((message: string) => void) | undefined;
+};
+/**
+ * Watches the project for file changes. Windows and macOS use one recursive handle on the root. Other platforms
+ * use one non-recursive handle per directory that holds a listed file, because Node walks the whole tree for
+ * `recursive: true` there, `node_modules` included, and can exhaust inotify watches.
+ * A directory that appears later gets its handle from the event that reports it, not from the next file list. No list
+ * names a directory that holds only a placeholder such as `.gitkeep`, yet its first source file must raise an event.
+ * The same goes for a directory that a list named for a while: once its last source file is deleted, a placeholder may
+ * remain, and a source file added again must raise an event. So a handle that no list names stays, with the handles of
+ * the directories above it, until its directory is removed. At most `MAX_RETAINED_DIRECTORIES` of them stay at once,
+ * and the refresh closes the ones that were opened longest ago when more qualify. A handle that was lost with its
+ * directory is closed (see `namesWatchedDirectory`), and `refreshDirectories` opens it again once the directory exists.
+ * The watcher is a hint: a missed event costs speed, never correctness, because the session's pull check stays
+ * the authority.
+ */
+export declare function startProjectWatcher(options: ProjectWatcherOptions): ProjectWatcher;
+export type WatchControllerOptions = {
+    root: string;
+    /**
+     * Runs `operation` once every operation that rebuilds the session's index or writes its artifacts has ended, and
+     * keeps the next one waiting until it ends. The MCP handlers pass the lock that `refresh_index`, `artifact_build`,
+     * and the SQLite rebuild take. A background refresh that overlapped one of them would leave the file signatures of
+     * whichever build ended last, whatever snapshot the session serves. The same goes for a read of the file list for
+     * the per-directory watches, because the first read of a session that nothing has loaded records file signatures.
+     */
+    runExclusive: (operation: () => Promise<void>) => Promise<void>;
+    /** The directory that the session writes its disk cache to; see {@link ProjectWatcherOptions.cacheDirectory}. */
+    cacheDirectory?: string | undefined;
+    /** Defaults to {@link DEFAULT_MCP_WATCH_DEBOUNCE_MS}. */
+    debounceMs?: number | undefined;
+    /** Defaults to {@link DEFAULT_MCP_WATCH_MIN_REFRESH_INTERVAL_MS}. */
+    minRefreshIntervalMs?: number | undefined;
+    /** Pauses the watcher after this long without `noteActivity`. Defaults to 30 minutes; 0 never pauses. */
+    idleMs?: number | undefined;
+    /** Starts without watching; the first `noteActivity` opens the watches, as after an idle pause. */
+    startPaused?: boolean | undefined;
+    platform?: NodeJS.Platform | undefined;
+    watch?: ProjectWatchFactory | undefined;
+    log?: ((message: string) => void) | undefined;
+};
+export type WatchController = {
+    /** Records a tool call: resets the idle timer, and after an idle pause reopens the watches. */
+    noteActivity: () => void;
+    /**
+     * Closes every handle and cancels every timer. Safe to call twice. The promise settles once the background refresh
+     * that was running and every read of the file list that had started have ended, and never rejects. A refresh that
+     * still waits for its turn then checks and rebuilds nothing, and a read that still waits reads nothing. Neither can
+     * be cancelled once it runs, so a caller that releases the session waits for them first: one that outlives the
+     * release keeps writing the cache and restores the file signatures that the release dropped.
+     */
+    close: () => Promise<void>;
+};
+/** Throws unless `value` is a whole number of milliseconds that a timer accepts. */
+export declare function assertMcpWatchMs(name: string, value: number | undefined): void;
+/**
+ * Turns file events into background refreshes of an MCP-owned session.
+ * - Every event clears the session's cached freshness result at once (`markChanged`). It also cancels the refresh
+ *   and the rerun that an earlier burst scheduled, so that none starts while events still arrive. A refresh that
+ *   already waits for its turn of `runExclusive` gives the turn up when it comes: the burst that the event belongs to
+ *   starts its own refresh when it settles.
+ * - A settled burst starts a refresh, no sooner than `minRefreshIntervalMs` after the previous one ended.
+ * - One refresh runs at a time. A settled burst during it sets one rerun flag. Its freshness check, invalidation, and
+ *   rebuild run in one turn of `runExclusive`, so they never overlap an explicit refresh or an artifact build. Every
+ *   read of the file list for the per-directory watches takes a turn as well.
+ * - After `idleMs` without `noteActivity` the watches close, and a refresh that waits for its turn gives it up. The
+ *   next `noteActivity` reopens them and calls `markChanged`, so the pull check sees every edit made during the pause.
+ * - `close` ends the watching for good. The refresh that is running finishes, and so does every read of the file list
+ *   that has started. `close` returns a promise for them, so that the owner of the session can release the session
+ *   after them. A read that still waits for its turn gives it up.
+ */
+export declare function createWatchController(session: AgentSession, options: WatchControllerOptions): WatchController;
+//# sourceMappingURL=project-watcher.d.ts.map

package/dist/mcp/project-watcher.d.ts.map

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