codegraph-java 0.1.0

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

@@ -0,0 +1,86 @@
+/**
+ * `GET /api/entrypoints` — where to start reading a project you have never
+ * opened, and where a flow starts.
+ *
+ * The empty state, the resting search palette and the entry-points panel all
+ * have the same problem: a graph of thirteen thousand symbols and no obvious
+ * door. Four answers, every one of them derived from the graph rather than
+ * from a filename convention:
+ *
+ * - **Routes** — a request arriving from outside is the most literal entry a
+ *   codebase has. Straight from the routing manifest (`/api/routes`), and
+ *   absent for a project that is not a routed app. Carried with the file the
+ *   URL is REGISTERED in as well as the one that serves it, because a router
+ *   file is how a reader groups routes and the two are rarely the same file.
+ * - **Files that run something** — the engine records a statement at the top
+ *   level of a file as an edge out of the *file* node, so a CLI, a worker
+ *   entry or a build script has `calls` where a library module has none. That
+ *   is what makes `src/bin/codegraph.ts` the root of this repo's CLI flow.
+ *   Ranked by calls x how many other files they reach, so the file that both
+ *   runs and wires the project together outranks a registration table that
+ *   makes a hundred module-level calls into itself.
+ * - **Tests** — the other direction: not where the project starts, but what
+ *   already exercises it. Ranked by how many other files a test reaches, so
+ *   the suites that cross the most of the codebase come first.
+ * - **Hubs** — the most depended-on symbols. Not an entry in the "runs first"
+ *   sense; an entry in the sense that reading one tells you the most about
+ *   what the project is made of, and a change to one radiates furthest.
+ *
+ * Tests and fixtures are excluded from the two *reading* lists — "where do I
+ * start reading" never means a test — and the Tests list is built from the
+ * narrow {@link isTestPath}, not from {@link isTestFile}: an example, a
+ * benchmark or a fixture is not a test, and a heading that says "Tests" must
+ * not be quietly counting them.
+ */
+import type { CodeGraph } from '../../index';
+import { type WireRoute } from './routes';
+import { type WireList, type WireNodeRef } from './wire';
+export interface WireEntryFile extends WireNodeRef {
+    /** Calls and instantiations made at the top level of the file. */
+    calls: number;
+    /** Distinct other files this one's symbols reach. */
+    reaches: number;
+    /** Other files reaching into this one. Zero means nothing imports it. */
+    dependents: number;
+}
+export interface WireEntryTest extends WireNodeRef {
+    /** Distinct other files this test reaches — what it exercises. */
+    reaches: number;
+    /** References behind that reach. */
+    refs: number;
+}
+export interface WireEntryHub extends WireNodeRef {
+    /** Distinct symbols that depend on this one. */
+    dependents: number;
+}
+export interface WireEntryPoints {
+    /**
+     * Frameworks the resolver detected, e.g. `["go"]`, `["express"]`.
+     *
+     * The Routes section's header names them: a route list is a claim about a
+     * framework's conventions, and saying which one produced it is the
+     * difference between a fact and an assertion.
+     */
+    frameworks: string[];
+    routes: {
+        routed: boolean;
+        /** Every `route` node in the graph, resolved handler or not. */
+        routeCount: number;
+        items: WireList<WireRoute>;
+    };
+    /** `total` is a floor on these three — the server counts what its scan saw. */
+    files: WireList<WireEntryFile>;
+    tests: WireList<WireEntryTest>;
+    hubs: WireList<WireEntryHub>;
+    index: {
+        lastIndexedAt: number | null;
+        files: number;
+    };
+    timing: {
+        elapsedMs: number;
+        cached: boolean;
+    };
+}
+export declare function resetEntryPointsCache(): void;
+export declare function buildEntryPoints(cg: CodeGraph, query: URLSearchParams): WireEntryPoints;
+//# sourceMappingURL=entrypoints.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoints.d.ts","sourceRoot":"","sources":["../../../src/ui-server/api/entrypoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAEvD,OAAO,EAAoC,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AAwD3F,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE;QACN,MAAM,EAAE,OAAO,CAAC;QAChB,gEAAgE;QAChE,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;KAC5B,CAAC;IACF,+EAA+E;IAC/E,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC/B,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC/B,IAAI,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;IAC7B,KAAK,EAAE;QAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;CAChD;AAkBD,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAMD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,GAAG,eAAe,CA0CvF"}

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

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * `GET /api/entrypoints` — where to start reading a project you have never
+ * opened, and where a flow starts.
+ *
+ * The empty state, the resting search palette and the entry-points panel all
+ * have the same problem: a graph of thirteen thousand symbols and no obvious
+ * door. Four answers, every one of them derived from the graph rather than
+ * from a filename convention:
+ *
+ * - **Routes** — a request arriving from outside is the most literal entry a
+ *   codebase has. Straight from the routing manifest (`/api/routes`), and
+ *   absent for a project that is not a routed app. Carried with the file the
+ *   URL is REGISTERED in as well as the one that serves it, because a router
+ *   file is how a reader groups routes and the two are rarely the same file.
+ * - **Files that run something** — the engine records a statement at the top
+ *   level of a file as an edge out of the *file* node, so a CLI, a worker
+ *   entry or a build script has `calls` where a library module has none. That
+ *   is what makes `src/bin/codegraph.ts` the root of this repo's CLI flow.
+ *   Ranked by calls x how many other files they reach, so the file that both
+ *   runs and wires the project together outranks a registration table that
+ *   makes a hundred module-level calls into itself.
+ * - **Tests** — the other direction: not where the project starts, but what
+ *   already exercises it. Ranked by how many other files a test reaches, so
+ *   the suites that cross the most of the codebase come first.
+ * - **Hubs** — the most depended-on symbols. Not an entry in the "runs first"
+ *   sense; an entry in the sense that reading one tells you the most about
+ *   what the project is made of, and a change to one radiates furthest.
+ *
+ * Tests and fixtures are excluded from the two *reading* lists — "where do I
+ * start reading" never means a test — and the Tests list is built from the
+ * narrow {@link isTestPath}, not from {@link isTestFile}: an example, a
+ * benchmark or a fixture is not a test, and a heading that says "Tests" must
+ * not be quietly counting them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetEntryPointsCache = resetEntryPointsCache;
+exports.buildEntryPoints = buildEntryPoints;
+const respond_1 = require("./respond");
+const routes_1 = require("./routes");
+const query_utils_1 = require("../../search/query-utils");
+const wire_1 = require("./wire");
+/** Rows per derived list, and the default for `limit`. */
+const DEFAULT_LIMIT = 12;
+/**
+ * Route rows, and the default for `routes`.
+ *
+ * Separate from `limit` because routes are the one list whose useful length is
+ * set by the project rather than by the reader: a panel that groups 60 routes
+ * under four router files is legible, while 60 rows of "most depended on" is
+ * a wall. Both are honest — every list carries the real total.
+ */
+const DEFAULT_ROUTE_LIMIT = 60;
+const MAX_ROUTE_LIMIT = 300;
+/**
+ * Ranked rows examined before the test filter and the per-directory cap run.
+ *
+ * Fixed rather than a multiple of `limit` so the same project answers with the
+ * same rows whatever the caller asks for. It also means the `total` on the two
+ * derived lists is a FLOOR — "at least this many" — because the tests it skips
+ * are only recognisable in JavaScript (`isTestFile` reads directory shapes and
+ * CamelCase suffixes that do not survive translation into SQL). That is the
+ * honest reading, and the viewer prints the rows rather than the count.
+ */
+const SCAN_ROWS = 400;
+/**
+ * At most this many executable files from any one directory.
+ *
+ * Without it a repo with twenty one-off scripts in `scripts/` answers "where do
+ * I start" with twenty scripts, and the CLI everybody actually wants falls off
+ * the end. Two keeps a directory represented without letting it own the list.
+ */
+const MAX_FILES_PER_DIR = 2;
+/**
+ * Test files asked about per reach query.
+ *
+ * The reach query is driven from `nodes` by file path, so its cost is
+ * proportional to the files in the chunk rather than to the edge table — but a
+ * repo with ten thousand test files would still put ten thousand paths into
+ * one `json_each`. Chunking keeps every statement bounded WITHOUT capping the
+ * candidate list, which would silently drop test files from the ranking.
+ */
+const TEST_CHUNK = 500;
+/** Kinds that are never a useful hub row: a mention, a container, or a name. */
+const NON_HUB_KINDS = new Set([
+    'file',
+    'import',
+    'export',
+    'parameter',
+]);
+// =============================================================================
+// Cache
+// =============================================================================
+/**
+ * One answer per (project, index build, limits).
+ *
+ * Unlike `/api/source` and everything downstream of it, nothing here is read
+ * from disk: every field comes out of the index, so an answer is exactly as
+ * fresh as the index build it was keyed on. The Tests list is the reason it is
+ * worth caching at all — it asks a reach query per chunk of test files, and
+ * every screen in the viewer refetches this payload when the index moves.
+ */
+const CACHE_LIMIT = 8;
+const cache = new Map();
+function resetEntryPointsCache() {
+    cache.clear();
+}
+// =============================================================================
+// Build
+// =============================================================================
+function buildEntryPoints(cg, query) {
+    const started = Date.now();
+    const limit = (0, respond_1.intParam)(query, 'limit', { min: 1, max: 50, default: DEFAULT_LIMIT });
+    const routeLimit = (0, respond_1.intParam)(query, 'routes', {
+        min: 3,
+        max: MAX_ROUTE_LIMIT,
+        default: DEFAULT_ROUTE_LIMIT,
+    });
+    const stats = cg.getStats();
+    // JSON rather than a joined string: a project root can contain any character
+    // a separator might have picked, and this key is compared for equality only.
+    const key = JSON.stringify([
+        cg.getProjectRoot(),
+        cg.getLastIndexedAt() ?? 0,
+        stats.edgeCount,
+        stats.fileCount,
+        limit,
+        routeLimit,
+    ]);
+    const hit = cache.get(key);
+    if (hit) {
+        // Re-stamp rather than mutate: the body is shared with the next caller.
+        return { ...hit, timing: { elapsedMs: Date.now() - started, cached: true } };
+    }
+    const payload = {
+        frameworks: cg.getDetectedFrameworks(),
+        routes: routeEntries(cg, routeLimit),
+        files: executableFiles(cg, limit),
+        tests: testFiles(cg, limit),
+        hubs: hubs(cg, limit),
+        index: { lastIndexedAt: cg.getLastIndexedAt() ?? null, files: stats.fileCount },
+        timing: { elapsedMs: Date.now() - started, cached: false },
+    };
+    if (cache.size >= CACHE_LIMIT) {
+        const oldest = cache.keys().next();
+        if (!oldest.done)
+            cache.delete(oldest.value);
+    }
+    cache.set(key, payload);
+    return payload;
+}
+/**
+ * The routing manifest, trimmed to a starting-points list.
+ *
+ * `buildRoutes` is reused rather than re-derived so a route row means exactly
+ * the same thing here as on the routes endpoint — including its handler id and
+ * its registration site, which are what make the row navigable and groupable.
+ */
+function routeEntries(cg, limit) {
+    const manifest = (0, routes_1.buildRoutes)(cg, new URLSearchParams([['limit', String(limit)]]));
+    return {
+        routed: manifest.routed,
+        routeCount: manifest.routeCount,
+        // `shown` counts the rows; `truncated` is the manifest's own verdict on
+        // whether the window cut anything, and it is more trustworthy than
+        // comparing against `routeCount` (which counts URLs whose handler never
+        // resolved as well).
+        items: {
+            total: manifest.truncated ? Math.max(manifest.shown + 1, manifest.routeCount) : manifest.shown,
+            shown: manifest.shown,
+            truncated: manifest.truncated,
+            items: manifest.entries,
+        },
+    };
+}
+/**
+ * Files that do something on the way down, most first.
+ *
+ * Over-fetched before filtering, because the two things that shrink the list —
+ * tests and the per-directory cap — are only knowable after the rows come back,
+ * and a project whose noisiest module-level callers are all test files would
+ * otherwise answer with an empty list.
+ */
+function executableFiles(cg, limit) {
+    const ranked = cg.getTopCallingFiles(SCAN_ROWS);
+    const kept = [];
+    const perDir = new Map();
+    let eligible = 0;
+    for (const row of ranked) {
+        if ((0, query_utils_1.isTestFile)(row.filePath))
+            continue;
+        eligible += 1;
+        if (kept.length >= limit)
+            continue;
+        const dir = directoryOf(row.filePath);
+        const taken = perDir.get(dir) ?? 0;
+        if (taken >= MAX_FILES_PER_DIR)
+            continue;
+        const node = cg.getNode(row.nodeId);
+        if (!node)
+            continue;
+        perDir.set(dir, taken + 1);
+        kept.push({ node, calls: row.calls, reaches: row.reaches });
+    }
+    const dependents = cg.getFileDependentCounts(kept.map((k) => k.node.filePath));
+    const items = kept.map(({ node, calls, reaches }) => ({
+        ...(0, wire_1.toNodeRef)(node),
+        calls,
+        reaches,
+        dependents: dependents.get(node.filePath) ?? 0,
+    }));
+    // `eligible` counts every non-test file the scan saw: a floor, never an
+    // overstatement.
+    return (0, wire_1.wireList)(items, Math.max(eligible, items.length));
+}
+/**
+ * The suites that exercise the most of the project, widest first.
+ *
+ * Ranked by reach rather than by size or by module-level calls: a test's
+ * useful property is how much of the codebase runs when it does, and only Go,
+ * Rust and Java put that work inside functions where a "runs something at
+ * module level" ranking cannot see it at all.
+ *
+ * `total` is exact here — the candidate list is every test file in the index,
+ * decided in JavaScript before any query runs — which is why it is the one
+ * derived list whose count is not a floor. A test file that reaches nothing
+ * outside itself is left out on purpose: it exercises nothing this graph can
+ * name.
+ */
+function testFiles(cg, limit) {
+    const candidates = cg
+        .getFiles()
+        .map((file) => (0, wire_1.toPosixPath)(file.path))
+        .filter((path) => (0, query_utils_1.isTestPath)(path));
+    if (candidates.length === 0)
+        return (0, wire_1.wireList)([], 0);
+    const reach = new Map();
+    for (let i = 0; i < candidates.length; i += TEST_CHUNK) {
+        for (const [path, counts] of cg.getFileReachCounts(candidates.slice(i, i + TEST_CHUNK))) {
+            reach.set((0, wire_1.toPosixPath)(path), counts);
+        }
+    }
+    const ranked = [...reach.entries()]
+        .map(([path, counts]) => ({ path, ...counts }))
+        .sort((a, b) => b.reaches - a.reaches || b.refs - a.refs || a.path.localeCompare(b.path));
+    const top = ranked.slice(0, limit);
+    const nodes = new Map(cg.getFileNodes(top.map((row) => row.path)).map((n) => [(0, wire_1.toPosixPath)(n.filePath), n]));
+    const items = [];
+    for (const row of top) {
+        const node = nodes.get(row.path);
+        if (!node)
+            continue;
+        items.push({ ...(0, wire_1.toNodeRef)(node), reaches: row.reaches, refs: row.refs });
+    }
+    return (0, wire_1.wireList)(items, Math.max(ranked.length, items.length));
+}
+/** The most depended-on symbols, tests and non-navigable kinds removed. */
+function hubs(cg, limit) {
+    const ranked = cg.getTopDependedOn(SCAN_ROWS);
+    const items = [];
+    let eligible = 0;
+    for (const row of ranked) {
+        const node = cg.getNode(row.nodeId);
+        if (!node || NON_HUB_KINDS.has(node.kind) || (0, query_utils_1.isTestFile)(node.filePath))
+            continue;
+        eligible += 1;
+        if (items.length >= limit)
+            continue;
+        items.push({ ...(0, wire_1.toNodeRef)(node), dependents: row.dependents });
+    }
+    return (0, wire_1.wireList)(items, Math.max(eligible, items.length));
+}
+/** `src/bin/codegraph.ts` -> `src/bin`; a root file -> `.`. */
+function directoryOf(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const cut = normalized.lastIndexOf('/');
+    return cut < 0 ? '.' : normalized.slice(0, cut);
+}
+//# sourceMappingURL=entrypoints.js.map

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

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

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

@@ -0,0 +1,183 @@
+/**
+ * `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, `cg 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.
+ *
+ * `cg 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.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { GraphSession } from './session';
+/**
+ * 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.
+ */
+export declare const MAX_EVENT_FILES = 200;
+/** Comment frame keeping the connection (and the client's idea of it) alive. */
+export declare const HEARTBEAT_MS = 25000;
+export interface WireIndexRevision {
+    lastIndexedAt: number | null;
+    files: number;
+}
+/** Sent once, immediately, so a client knows what it is synchronised against. */
+export interface WireEventHello {
+    type: 'hello';
+    index: WireIndexRevision | null;
+    /** Which of the two observers actually came up. */
+    watching: {
+        source: boolean;
+        index: boolean;
+    };
+    /** Non-null when live watching has given up; the client must NOT start polling. */
+    degraded: string | null;
+    heartbeatMs: number;
+    at: number;
+}
+/** Source files changed on disk. The index has NOT caught up yet. */
+export interface WireEventChanged {
+    type: 'changed';
+    files: string[];
+    total: number;
+    truncated: boolean;
+    /**
+     * True when the change could not be described file by file (a directory
+     * removal, or a burst past the watcher's scoped ceiling). Treat any open file
+     * as possibly affected.
+     */
+    scan: boolean;
+    at: number;
+}
+/** The index moved: some other process finished writing the graph. */
+export interface WireEventIndex {
+    type: 'index';
+    index: WireIndexRevision;
+    /** Files this sync re-indexed, newest first. Empty when it only deleted. */
+    files: string[];
+    total: number;
+    truncated: boolean;
+    at: number;
+}
+/** Live watching has stopped for good. Sent once; the stream stays open. */
+export interface WireEventDegraded {
+    type: 'degraded';
+    reason: string;
+    at: number;
+}
+export type WireEvent = WireEventHello | WireEventChanged | WireEventIndex | WireEventDegraded;
+/**
+ * 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.
+ */
+export declare class EventHub {
+    private readonly projectRoot;
+    private readonly session;
+    private readonly clients;
+    private sourceWatcher;
+    private indexWatcher;
+    private indexTimer;
+    /** When the current settle window started, for the {@link INDEX_SETTLE_MAX_MS} cap. */
+    private indexPendingSince;
+    private revision;
+    private sourceUp;
+    private indexUp;
+    private degraded;
+    private closed;
+    constructor(projectRoot: string, session: GraphSession);
+    /**
+     * 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: IncomingMessage, res: ServerResponse, method: string): true;
+    /** Number of attached clients — for tests and for the watchers' lifetime. */
+    get size(): number;
+    /** Stop watching and end every open stream. Idempotent. */
+    close(): void;
+    private drop;
+    private send;
+    private broadcast;
+    private ensureWatching;
+    private stopWatching;
+    /**
+     * 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.
+     */
+    private startSourceWatcher;
+    private announceChanged;
+    /**
+     * 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).
+     */
+    private startIndexWatcher;
+    /**
+     * 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.
+     */
+    private scheduleProbe;
+    /** One query. An unmoved revision is not an event. */
+    private checkIndex;
+    /**
+     * The current revision, or null when there is no readable index.
+     *
+     * A missing index is not an error here: `cg ui` refuses to start
+     * without one, but a user can delete `.codegraph/` with the viewer open, and
+     * every endpoint already says so in its own words when asked.
+     */
+    private probe;
+}
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/ui-server/api/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AAI5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,gFAAgF;AAChF,eAAO,MAAM,YAAY,QAAS,CAAC;AA6BnC,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAChC,mDAAmD;IACnD,QAAQ,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAC9C,mFAAmF;IACnF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,iBAAiB,CAAC;IACzB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,MAAM,SAAS,GACjB,cAAc,GACd,gBAAgB,GAChB,cAAc,GACd,iBAAiB,CAAC;AAStB;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAE7C,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,UAAU,CAA8C;IAChE,uFAAuF;IACvF,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,MAAM,CAAS;gBAEX,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY;IAKtD;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IA8D1E,6EAA6E;IAC7E,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,2DAA2D;IAC3D,KAAK,IAAI,IAAI;IAgBb,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,YAAY;IAkBpB;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IA2B1B,OAAO,CAAC,eAAe;IAavB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAerB,sDAAsD;IACtD,OAAO,CAAC,UAAU;IAwClB;;;;;;OAMG;IACH,OAAO,CAAC,KAAK;CASd"}