@ltm-alpha/alpha-cs 1.6.0

package/dist/ui-server/api/events.js

@@ -0,0 +1,430 @@
+"use strict";
+/**
+ * `GET /api/events` — the viewer's live channel (server-sent events).
+ *
+ * Two questions the open browser cannot answer for itself, and one stream that
+ * answers both:
+ *
+ * - **"has the file I'm looking at changed on disk?"** — the drift banner. The
+ *   verdict itself comes from `/api/source` (it hashes the bytes); this stream
+ *   only says *when to ask again*, so the banner appears about a third of a
+ *   second after a save instead of on the next navigation.
+ * - **"has the index moved?"** — the live refresh. Something else (an agent's
+ *   MCP daemon, `codegraph sync`, a git hook) writes the graph; when it does,
+ *   every screen the viewer is showing is one round-trip out of date.
+ *
+ * ## This server watches. It never syncs.
+ *
+ * `codegraph ui` is read-only in every sense — the banner it prints says so —
+ * so the obvious implementation (run the engine's watcher, let it sync) is out.
+ * What is left is *observation*, from two independent directions:
+ *
+ * - the project tree, through the engine's own {@link FileWatcher} with a
+ *   notify-only `syncFn`. It never writes: the callback that would have run a
+ *   sync fans the changed paths out to the browser instead. Everything else
+ *   about it — the per-platform watch strategy, the indexer's ignore scope, the
+ *   adaptive debounce, the degrade latch — is behaviour we would otherwise have
+ *   had to write again, worse.
+ * - the index itself, through one non-recursive `fs.watch` on the data
+ *   directory. That is the only cross-process signal there is: the writer is a
+ *   different process, and the thing it changes is a file. A settled write is
+ *   followed by ONE cheap query (`getIndexRevision`), and only a revision that
+ *   actually moved becomes an event.
+ *
+ * **Nothing polls.** Both watchers are edge-triggered, and both start on the
+ * first subscriber and stop with the last one — a viewer nobody has open costs
+ * no watch descriptors, which matters on Linux where the strategy is
+ * per-directory.
+ *
+ * ## Boundary
+ *
+ * A long-lived response sits inside the loopback boundary exactly like every
+ * other route: `Host`, `Origin` and the GET-only rule are already enforced by
+ * `startUiServer` before this module is reached, and nothing here reads the
+ * repository — the paths it names came from the watcher and the index, and the
+ * viewer has to go back through `/api/source` (and therefore through
+ * `resolveProjectFile`) to see a byte of any of them.
+ */
+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.EventHub = exports.HEARTBEAT_MS = exports.MAX_EVENT_FILES = void 0;
+const fs = __importStar(require("fs"));
+const directory_1 = require("../../directory");
+const watcher_1 = require("../../sync/watcher");
+/**
+ * Paths carried in one event. `total` is always the real number — a burst of
+ * two thousand files still says two thousand, it just does not list them.
+ */
+exports.MAX_EVENT_FILES = 200;
+/** Comment frame keeping the connection (and the client's idea of it) alive. */
+exports.HEARTBEAT_MS = 25_000;
+/**
+ * Quiet window before an index write is treated as finished.
+ *
+ * A sync writes the WAL continuously, so the *end* of the writing is the signal
+ * — not its start. Long enough that a multi-second sync produces one event
+ * rather than a dozen.
+ */
+const INDEX_SETTLE_MS = 400;
+/**
+ * Ceiling on that quiet window. A sync large enough that the WAL never goes
+ * quiet for 400 ms would otherwise hold the first event until it finished; the
+ * cap makes the viewer refresh mid-way instead, which is still true — the graph
+ * really has moved — and costs one query.
+ */
+const INDEX_SETTLE_MAX_MS = 3_000;
+/**
+ * Debounce for source-file events. The watcher's own adaptive rule fires a lone
+ * save after `min(300, this)` ms of quiet and keeps the full window for a
+ * burst, so a single edit reaches the browser well inside the one-second bar
+ * while an agent rewriting forty files still arrives as one event.
+ */
+const SOURCE_DEBOUNCE_MS = 500;
+/**
+ * Fans filesystem and index changes out to every open viewer.
+ *
+ * One hub per server. It owns the watchers, and owns them lazily: they exist
+ * only while somebody is listening.
+ */
+class EventHub {
+    projectRoot;
+    session;
+    clients = new Set();
+    sourceWatcher = null;
+    indexWatcher = null;
+    indexTimer = null;
+    /** When the current settle window started, for the {@link INDEX_SETTLE_MAX_MS} cap. */
+    indexPendingSince = 0;
+    revision = null;
+    sourceUp = false;
+    indexUp = false;
+    degraded = null;
+    closed = false;
+    constructor(projectRoot, session) {
+        this.projectRoot = projectRoot;
+        this.session = session;
+    }
+    /**
+     * Attach one browser to the stream.
+     *
+     * Returns `true` in every case — the response is answered here, streaming or
+     * not — so it slots into the API's `switch` like any other endpoint.
+     */
+    subscribe(req, res, method) {
+        if (this.closed) {
+            // The server is shutting down. Answer, do not attach: a client that got a
+            // stream here would hold the socket open against `close()`.
+            res.writeHead(503, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Cache-Control': 'no-store',
+            });
+            res.end(method === 'HEAD' ? undefined : JSON.stringify({ error: 'Shutting down.', code: 'internal' }));
+            return true;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-store',
+            // Node would otherwise chunk small writes; an event that sits in a buffer
+            // is an event that did not happen.
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no',
+        });
+        if (method === 'HEAD') {
+            res.end();
+            return true;
+        }
+        // No keep-alive timeout on this socket: the server sets one globally so
+        // Ctrl-C does not wait on browser connections, and it would close a healthy
+        // stream between heartbeats.
+        res.socket?.setTimeout(0);
+        res.socket?.setNoDelay(true);
+        this.ensureWatching();
+        const client = {
+            res,
+            heartbeat: setInterval(() => {
+                // A comment frame. Not an event, so no client handler ever sees it —
+                // it exists to notice a socket the other end has already dropped.
+                if (!res.writableEnded)
+                    res.write(': ping\n\n');
+            }, exports.HEARTBEAT_MS),
+        };
+        // `unref` so a live stream never keeps the process alive on its own.
+        client.heartbeat.unref?.();
+        this.clients.add(client);
+        const drop = () => this.drop(client);
+        res.on('close', drop);
+        res.on('error', drop);
+        req.on('aborted', drop);
+        this.send(client, {
+            type: 'hello',
+            index: this.revision,
+            watching: { source: this.sourceUp, index: this.indexUp },
+            degraded: this.degraded,
+            heartbeatMs: exports.HEARTBEAT_MS,
+            at: Date.now(),
+        });
+        return true;
+    }
+    /** Number of attached clients — for tests and for the watchers' lifetime. */
+    get size() {
+        return this.clients.size;
+    }
+    /** Stop watching and end every open stream. Idempotent. */
+    close() {
+        this.closed = true;
+        this.stopWatching();
+        for (const client of [...this.clients]) {
+            clearInterval(client.heartbeat);
+            this.clients.delete(client);
+            try {
+                client.res.end();
+            }
+            catch {
+                /* the socket is already gone */
+            }
+        }
+    }
+    /* ------------------------------------------------------------ plumbing -- */
+    drop(client) {
+        if (!this.clients.delete(client))
+            return;
+        clearInterval(client.heartbeat);
+        if (this.clients.size === 0)
+            this.stopWatching();
+    }
+    send(client, event) {
+        if (client.res.writableEnded)
+            return;
+        try {
+            // `retry` on every frame is cheap and means a client that reconnects with
+            // the browser's own EventSource still backs off the way we asked.
+            client.res.write(`retry: 3000\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`);
+        }
+        catch {
+            this.drop(client);
+        }
+    }
+    broadcast(event) {
+        for (const client of [...this.clients])
+            this.send(client, event);
+    }
+    /* ------------------------------------------------------------ watching -- */
+    ensureWatching() {
+        if (this.closed)
+            return;
+        this.revision ??= this.probe();
+        this.startSourceWatcher();
+        this.startIndexWatcher();
+    }
+    stopWatching() {
+        if (this.indexTimer) {
+            clearTimeout(this.indexTimer);
+            this.indexTimer = null;
+        }
+        this.indexPendingSince = 0;
+        try {
+            this.indexWatcher?.close();
+        }
+        catch {
+            /* already closed */
+        }
+        this.indexWatcher = null;
+        this.indexUp = false;
+        this.sourceWatcher?.stop();
+        this.sourceWatcher = null;
+        this.sourceUp = false;
+    }
+    /**
+     * The project tree, through the engine's watcher with the sync taken out.
+     *
+     * The `syncFn` is the whole trick: the watcher calls it with exactly the
+     * paths it would have handed to a scoped sync (or `undefined` when the events
+     * could not describe the change), we announce them and report zero files
+     * changed. It succeeds every time, so the watcher's failure ladder — lock
+     * retries, backoff, the degrade latch — is only ever reached by the watch
+     * layer itself, which is precisely the part we do want.
+     */
+    startSourceWatcher() {
+        if (this.sourceWatcher)
+            return;
+        const watcher = new watcher_1.FileWatcher(this.projectRoot, async (paths) => {
+            this.announceChanged(paths);
+            return { filesChanged: 0, durationMs: 0 };
+        }, {
+            debounceMs: SOURCE_DEBOUNCE_MS,
+            onDegraded: (reason) => {
+                this.degraded = reason;
+                this.sourceUp = false;
+                this.broadcast({ type: 'degraded', reason, at: Date.now() });
+            },
+        });
+        this.sourceWatcher = watcher;
+        this.sourceUp = watcher.start();
+        if (!this.sourceUp) {
+            // Watching is off by policy (CODEGRAPH_NO_WATCH, a WSL2 /mnt drive) or
+            // the OS refused. The stream stays — the index watcher is independent —
+            // and `hello` already told the client which half is live.
+            this.sourceWatcher = null;
+        }
+    }
+    announceChanged(paths) {
+        const all = paths ?? [];
+        const files = all.slice(0, exports.MAX_EVENT_FILES);
+        this.broadcast({
+            type: 'changed',
+            files,
+            total: all.length,
+            truncated: files.length < all.length,
+            scan: paths === undefined,
+            at: Date.now(),
+        });
+    }
+    /**
+     * The index, through one watch on the data directory.
+     *
+     * Non-recursive and on the directory rather than the database file: SQLite
+     * writes land in `codegraph.db-wal`, and a full re-index REPLACES
+     * `codegraph.db` outright (a watch on the file itself would follow the
+     * unlinked inode and never fire again).
+     */
+    startIndexWatcher() {
+        if (this.indexWatcher)
+            return;
+        const dir = (0, directory_1.getAlphaCsDir)(this.projectRoot);
+        try {
+            const watcher = fs.watch(dir, { persistent: false }, () => this.scheduleProbe());
+            watcher.on('error', () => {
+                // The data directory went away, or the OS dropped the watch. Nothing to
+                // retry against — a client that reloads gets a fresh one.
+                this.indexUp = false;
+                this.indexWatcher = null;
+                try {
+                    watcher.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            });
+            this.indexWatcher = watcher;
+            this.indexUp = true;
+        }
+        catch {
+            this.indexUp = false;
+        }
+    }
+    /**
+     * Wait for the writing to stop, then look once.
+     *
+     * Re-armed by every write, so a sync that takes four seconds produces one
+     * probe at its end — except that {@link INDEX_SETTLE_MAX_MS} caps how long
+     * the first probe can be deferred, so a continuously-writing full index still
+     * refreshes the viewer while it runs.
+     */
+    scheduleProbe() {
+        if (this.closed)
+            return;
+        const now = Date.now();
+        if (this.indexPendingSince === 0)
+            this.indexPendingSince = now;
+        const remaining = Math.max(0, this.indexPendingSince + INDEX_SETTLE_MAX_MS - now);
+        if (this.indexTimer)
+            clearTimeout(this.indexTimer);
+        const timer = setTimeout(() => {
+            this.indexTimer = null;
+            this.indexPendingSince = 0;
+            this.checkIndex();
+        }, Math.min(INDEX_SETTLE_MS, remaining));
+        timer.unref?.();
+        this.indexTimer = timer;
+    }
+    /** One query. An unmoved revision is not an event. */
+    checkIndex() {
+        if (this.closed || this.clients.size === 0)
+            return;
+        const next = this.probe();
+        if (next === null)
+            return;
+        const previous = this.revision;
+        this.revision = next;
+        if (previous !== null &&
+            previous.lastIndexedAt === next.lastIndexedAt &&
+            previous.files === next.files) {
+            return;
+        }
+        // Everything re-indexed since the mark we were holding. A sync that only
+        // removed files names nothing here — which is why the revision comparison
+        // above, not this list, decides whether an event happens at all.
+        let files = [];
+        let total = 0;
+        const since = previous?.lastIndexedAt ?? null;
+        if (since !== null) {
+            try {
+                const changed = this.session.acquire().getFilesIndexedSince(since, exports.MAX_EVENT_FILES);
+                files = changed.paths;
+                total = changed.total;
+            }
+            catch {
+                /* the index went away between the probe and here — the event still stands */
+            }
+        }
+        this.broadcast({
+            type: 'index',
+            index: next,
+            files,
+            total: Math.max(total, files.length),
+            truncated: files.length < total,
+            at: Date.now(),
+        });
+    }
+    /**
+     * The current revision, or null when there is no readable index.
+     *
+     * A missing index is not an error here: `codegraph ui` refuses to start
+     * without one, but a user can delete `.alpha-cs/` with the viewer open, and
+     * every endpoint already says so in its own words when asked.
+     */
+    probe() {
+        try {
+            const cg = this.session.acquire();
+            const revision = cg.getIndexRevision();
+            return { lastIndexedAt: revision.lastIndexedAt, files: revision.fileCount };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.EventHub = EventHub;
+//# sourceMappingURL=events.js.map

package/dist/ui-server/api/events.js.map

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

package/dist/ui-server/api/file.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `GET /api/file/<path>` — the File view in one round-trip.
+ *
+ * Three panes: what imports this file, the file's own outline in source order,
+ * and what this file imports. All of it comes from four batched queries — the
+ * file's nodes, their `contains` edges, their `imports` edges in each
+ * direction — never a query per symbol.
+ *
+ * Two things worth knowing about `imports` edges before reading the mapping
+ * below. First, they point at the *symbol* that was imported, not at the file
+ * holding it, so file granularity means mapping each edge's endpoint through
+ * `nodes.file_path`. Second, plenty of them stay inside one file (an import
+ * declaration is a node in the importing file), so the same-file ones have to
+ * be dropped or every file appears to import itself.
+ *
+ * The rails would still read as broken without the third piece: imports that
+ * never resolved. A file importing `react`, `fs` and one local module would
+ * otherwise show a single row, silently implying the other two do not exist.
+ * They are listed separately, as what they are — outside the index.
+ */
+import type AlphaCodeSense from '../../index';
+import type { Node } from '../../types';
+import { type WireNodeRef } from './wire';
+/** A row in the file outline. */
+export interface WireOutlineEntry extends WireNodeRef {
+    /** Containing symbol within this file, or null for a top-level one. */
+    parentId: string | null;
+    /** Nesting depth from the top level of the file, starting at 0. */
+    depth: number;
+    /** Incoming / outgoing edge counts — the `← in  → out` column. */
+    fanIn: number;
+    fanOut: number;
+}
+/** One end of the File view's import rails. */
+export interface WireImportRow {
+    file: string;
+    test: boolean;
+    /** Which symbols the edges name, capped. */
+    symbols: Array<{
+        id: string;
+        name: string;
+        kind: string;
+        line: number;
+    }>;
+    symbolCount: number;
+}
+export declare function buildFile(cg: AlphaCodeSense, projectRoot: string, requested: string): unknown;
+/**
+ * A file's symbols in source order, nested under their container.
+ *
+ * Extracted so the whole-file source view (`/api/filecode`) draws the same rows
+ * as the outline view rather than a second, subtly different reading of the
+ * same `contains` edges — an outline rail whose line numbers disagreed with the
+ * source beside it would be worse than no rail.
+ *
+ * Four batched queries whatever the file holds: its nodes are already in hand,
+ * their `contains` edges, and fan-in / fan-out for the whole set at once.
+ *
+ * @returns the capped rows and the TRUE symbol count, which is what a header
+ *          has to print — see `wireList`.
+ */
+export declare function buildOutlineEntries(cg: AlphaCodeSense, nodes: readonly Node[]): {
+    entries: WireOutlineEntry[];
+    total: number;
+};
+//# sourceMappingURL=file.d.ts.map

package/dist/ui-server/api/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../../src/ui-server/api/file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,cAAc,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAQ,IAAI,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,QAAQ,CAAC;AAQhB,iCAAiC;AACjC,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,uEAAuE;IACvE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,4CAA4C;IAC5C,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAuG7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,SAAS,IAAI,EAAE,GACrB;IAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAgChD"}