codegraph-java 0.1.0

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

@@ -0,0 +1,200 @@
+/**
+ * `GET /api/source?file=&from=&to=` — verbatim source, or an honest refusal.
+ *
+ * This is the one endpoint that reads the user's repository, so two rules
+ * govern it and neither is negotiable.
+ *
+ * **Every read goes through `resolveProjectFile`.** That is the chokepoint from
+ * `security.ts` — traversal, in-tree symlinks pointing out of the root,
+ * absolute paths, sensitive system directories. Without it,
+ * `?file=../../.ssh/id_rsa` is a credential leak over a port the user opened to
+ * read their own code.
+ *
+ * **A file that changed on disk since it was indexed is never sliced under the
+ * index's numbering.** The viewer asks for line ranges the *index* recorded; if
+ * the file moved on since, those ranges can point at a different symbol's body,
+ * which would be served under the requested name and look perfectly plausible.
+ * So the bytes are hashed and compared against `files.content_hash`, and on a
+ * mismatch the slice is omitted with `drift: true` — the same call
+ * `codegraph_node` makes when it says "changed on disk after the last index
+ * sync".
+ *
+ * A caller that has ALREADY decided the index's numbering is off — a viewer
+ * about to draw a drift banner — asks with `ondrift=current` and gets the
+ * file's CURRENT lines instead of nothing. That is the other half of
+ * `codegraph_node`'s behaviour (issue #1474): a drifted file is served whole
+ * and current rather than omitted, because current bytes are correct by
+ * construction. `showing` says which of the two came back, on every response,
+ * so nothing has to infer it from the presence of `lines`.
+ *
+ * Only files that are IN the index are served. That is a tighter boundary than
+ * the MCP tools take, and it costs the viewer nothing (it only ever renders
+ * indexed symbols) while making the drift verdict meaningful for every answer:
+ * there is always a hash to compare against.
+ */
+import type { FileRecord } from '../../types';
+import type { CodeGraph } from '../../index';
+import { type HighlightResult } from '../highlight';
+import { ApiError } from './respond';
+/**
+ * Largest file we will read to answer a source request.
+ *
+ * The whole file has to be read to hash it, so this bounds the work one request
+ * can cause. Well above the 1 MB ceiling extraction itself applies, so anything
+ * actually in the index is comfortably inside it.
+ */
+export declare const MAX_SOURCE_BYTES: number;
+/** Lines returned in one response. The Symbol view asks for windows, not files. */
+export declare const MAX_SOURCE_LINES = 4000;
+/**
+ * Look up a file record by a viewer-supplied path, WITHOUT validating it.
+ *
+ * Indexed paths are normalized to forward slashes at extraction time, so that
+ * is the form tried first; the platform-separator form is a fallback for an
+ * index written before that normalization.
+ *
+ * Callers that go on to READ the file must use {@link resolveRequestedFile}
+ * instead — it puts the path through the security chokepoint first. This one is
+ * for endpoints that only need the record (a drift flag on a path the index
+ * itself handed us).
+ */
+export declare function findIndexedFile(cg: CodeGraph, requested: string): {
+    record: FileRecord;
+    storedPath: string;
+} | null;
+/**
+ * Forward slashes and no leading `./` — the form indexed paths are stored in.
+ *
+ * A LEADING SLASH IS LEFT ALONE on purpose. Stripping it would quietly turn
+ * `/etc/passwd` into the project-relative `etc/passwd` and answer "not in this
+ * index" — reinterpreting the request instead of refusing it, and leaving the
+ * chokepoint's absolute-path rule with nothing to catch.
+ */
+export declare function toRequestPath(requested: string): string;
+/**
+ * Validate a viewer-supplied path, THEN look it up in the index.
+ *
+ * The order is the point. `resolveProjectFile` runs first, so a traversal, an
+ * absolute path or a sensitive system directory is refused as what it is,
+ * before the index is consulted — a 403 that says "outside the project", not a
+ * 404 that says "not indexed" and quietly depends on the index lookup missing.
+ * It also means the absolute path every reader uses has already been through
+ * the chokepoint by construction, rather than by remembering to call it.
+ *
+ * @throws {PathRefusalError} the path is not one we would ever read.
+ * @throws {ApiError} `not-found` when it is fine but not in the index.
+ */
+export declare function resolveRequestedFile(cg: CodeGraph, projectRoot: string, requested: string): {
+    record: FileRecord;
+    storedPath: string;
+    absolute: string;
+};
+export declare function notIndexedError(file: string): ApiError;
+/**
+ * Split source the way the index counted it.
+ *
+ * Rows are `\n`-delimited — that is how tree-sitter numbers them — so a CRLF
+ * file has the same line numbers here as in the graph. The trailing `\r` is
+ * dropped per line so it does not render as a stray glyph.
+ */
+export declare function splitLines(content: string): string[];
+/**
+ * The whole text of an INDEXED file, or `null` for anything unreadable.
+ *
+ * The dead code report's corroboration pass needs to count an identifier in a
+ * file's text, and this module is the only one in `api/` that opens a file — so
+ * the reader it uses lives here, behind the same chokepoint. Three refusals,
+ * all answering `null` rather than throwing, because the caller's rule is
+ * already "cannot read it → do not make the claim":
+ *
+ * - not in the index (the viewer never reads a file the graph does not know);
+ * - outside the project (`resolveProjectFile` throws; caught here);
+ * - bigger than `maxBytes`.
+ *
+ * Drift is deliberately NOT checked. The question being asked is "does anything
+ * in this file write this name", and the file's current bytes are the better
+ * answer to it than the bytes we indexed.
+ */
+export declare function readIndexedFileText(cg: CodeGraph, projectRoot: string, requested: string, maxBytes: number): string | null;
+/**
+ * Whether an indexed file has changed on disk since it was indexed — the same
+ * verdict `/api/source` returns, for endpoints that must *flag* drift without
+ * serving source (a symbol header, a file outline).
+ *
+ * Cheap first: size plus floored mtime is the identical freshness test the sync
+ * fast path uses, so an untouched file costs one `stat`. Only a stat mismatch
+ * pays for a hash, which is what keeps a `touch` or a checkout that rewrote
+ * identical bytes from reading as drift.
+ *
+ * Any failure answers `false`. A wrong "stale" flag would put a warning banner
+ * over correct source; the cases that would trip it (missing record, unreadable
+ * file) have their own handling in the endpoints that actually read.
+ */
+export declare function hasDriftedOnDisk(projectRoot: string, storedPath: string, record: FileRecord): boolean;
+/**
+ * The drift verdict AND the file's length, from one read.
+ *
+ * The whole-file view needs both before it draws anything: the drift banner,
+ * and the line count that fixes the height of the scrolling document (every
+ * line is a fixed 20px, so the total IS the layout). Asking
+ * {@link hasDriftedOnDisk} and then a source page would answer the first
+ * question against one read of the file and the second against another, which
+ * is exactly the window in which a file can change underneath the two.
+ *
+ * Unlike `hasDriftedOnDisk` there is no stat-only fast path: the bytes have to
+ * be read to be counted. That is the cost of knowing the length, and it is
+ * bounded by {@link MAX_SOURCE_BYTES} like every other read here.
+ */
+export declare function readFileShape(projectRoot: string, storedPath: string, record: FileRecord): {
+    drift: boolean;
+    totalLines: number | null;
+    reason?: string;
+};
+export interface SourceResult {
+    file: string;
+    language: string;
+    /** The file on disk differs from what was indexed. */
+    drift: boolean;
+    /**
+     * Which numbering the returned lines belong to.
+     *
+     * `'indexed'` — the file matches the index, so the two are the same thing.
+     * `'current'` — the file drifted and the caller asked for it anyway
+     * (`ondrift=current`): these are the bytes on disk right now, and NOTHING the
+     * graph holds about this file (symbol ranges, call-site lines, ports) lines
+     * up with them.
+     * `'none'` — the file drifted and no slice is served.
+     */
+    showing: 'indexed' | 'current' | 'none';
+    contentHash: string;
+    indexedAt: number;
+    generated: boolean;
+    totalLines: number | null;
+    from?: number;
+    to?: number;
+    lines?: string[];
+    truncated?: boolean;
+    reason?: string;
+    /**
+     * The same lines, classified for the code block — one entry per line, each a
+     * list of `[classId, text]` pairs indexed into `highlight.classes`.
+     *
+     * It rides with the slice rather than living behind its own endpoint because
+     * the two are only ever wanted together, and because a second round-trip
+     * would let the viewer paint unhighlighted source and then reflow it. Absent
+     * whenever `lines` is — a drifted file is not served at all.
+     */
+    highlight?: HighlightResult;
+}
+/**
+ * What to do when the file on disk no longer matches the index.
+ *
+ * `omit` (the default) is the safe answer for a caller that has not decided
+ * anything yet. `current` is for one that has: it is about to say, in the
+ * pixels, that these are the file's CURRENT lines and that nothing the graph
+ * holds about them applies.
+ */
+export type OnDrift = 'omit' | 'current';
+export declare function parseOnDrift(query: URLSearchParams): OnDrift;
+export declare function buildSource(cg: CodeGraph, projectRoot: string, query: URLSearchParams): Promise<SourceResult>;
+//# sourceMappingURL=source.d.ts.map

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

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

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

@@ -0,0 +1,419 @@
+"use strict";
+/**
+ * `GET /api/source?file=&from=&to=` — verbatim source, or an honest refusal.
+ *
+ * This is the one endpoint that reads the user's repository, so two rules
+ * govern it and neither is negotiable.
+ *
+ * **Every read goes through `resolveProjectFile`.** That is the chokepoint from
+ * `security.ts` — traversal, in-tree symlinks pointing out of the root,
+ * absolute paths, sensitive system directories. Without it,
+ * `?file=../../.ssh/id_rsa` is a credential leak over a port the user opened to
+ * read their own code.
+ *
+ * **A file that changed on disk since it was indexed is never sliced under the
+ * index's numbering.** The viewer asks for line ranges the *index* recorded; if
+ * the file moved on since, those ranges can point at a different symbol's body,
+ * which would be served under the requested name and look perfectly plausible.
+ * So the bytes are hashed and compared against `files.content_hash`, and on a
+ * mismatch the slice is omitted with `drift: true` — the same call
+ * `codegraph_node` makes when it says "changed on disk after the last index
+ * sync".
+ *
+ * A caller that has ALREADY decided the index's numbering is off — a viewer
+ * about to draw a drift banner — asks with `ondrift=current` and gets the
+ * file's CURRENT lines instead of nothing. That is the other half of
+ * `codegraph_node`'s behaviour (issue #1474): a drifted file is served whole
+ * and current rather than omitted, because current bytes are correct by
+ * construction. `showing` says which of the two came back, on every response,
+ * so nothing has to infer it from the presence of `lines`.
+ *
+ * Only files that are IN the index are served. That is a tighter boundary than
+ * the MCP tools take, and it costs the viewer nothing (it only ever renders
+ * indexed symbols) while making the drift verdict meaningful for every answer:
+ * there is always a hash to compare against.
+ */
+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.MAX_SOURCE_LINES = exports.MAX_SOURCE_BYTES = void 0;
+exports.findIndexedFile = findIndexedFile;
+exports.toRequestPath = toRequestPath;
+exports.resolveRequestedFile = resolveRequestedFile;
+exports.notIndexedError = notIndexedError;
+exports.splitLines = splitLines;
+exports.readIndexedFileText = readIndexedFileText;
+exports.hasDriftedOnDisk = hasDriftedOnDisk;
+exports.readFileShape = readFileShape;
+exports.parseOnDrift = parseOnDrift;
+exports.buildSource = buildSource;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const security_1 = require("../security");
+const highlight_1 = require("../highlight");
+const respond_1 = require("./respond");
+/**
+ * Largest file we will read to answer a source request.
+ *
+ * The whole file has to be read to hash it, so this bounds the work one request
+ * can cause. Well above the 1 MB ceiling extraction itself applies, so anything
+ * actually in the index is comfortably inside it.
+ */
+exports.MAX_SOURCE_BYTES = 8 * 1024 * 1024;
+/** Lines returned in one response. The Symbol view asks for windows, not files. */
+exports.MAX_SOURCE_LINES = 4000;
+/**
+ * Look up a file record by a viewer-supplied path, WITHOUT validating it.
+ *
+ * Indexed paths are normalized to forward slashes at extraction time, so that
+ * is the form tried first; the platform-separator form is a fallback for an
+ * index written before that normalization.
+ *
+ * Callers that go on to READ the file must use {@link resolveRequestedFile}
+ * instead — it puts the path through the security chokepoint first. This one is
+ * for endpoints that only need the record (a drift flag on a path the index
+ * itself handed us).
+ */
+function findIndexedFile(cg, requested) {
+    const posix = toRequestPath(requested);
+    const record = cg.getFile(posix);
+    if (record)
+        return { record, storedPath: posix };
+    const native = posix.split('/').join(path.sep);
+    if (native !== posix) {
+        const legacy = cg.getFile(native);
+        if (legacy)
+            return { record: legacy, storedPath: native };
+    }
+    return null;
+}
+/**
+ * Forward slashes and no leading `./` — the form indexed paths are stored in.
+ *
+ * A LEADING SLASH IS LEFT ALONE on purpose. Stripping it would quietly turn
+ * `/etc/passwd` into the project-relative `etc/passwd` and answer "not in this
+ * index" — reinterpreting the request instead of refusing it, and leaving the
+ * chokepoint's absolute-path rule with nothing to catch.
+ */
+function toRequestPath(requested) {
+    return requested.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/**
+ * Validate a viewer-supplied path, THEN look it up in the index.
+ *
+ * The order is the point. `resolveProjectFile` runs first, so a traversal, an
+ * absolute path or a sensitive system directory is refused as what it is,
+ * before the index is consulted — a 403 that says "outside the project", not a
+ * 404 that says "not indexed" and quietly depends on the index lookup missing.
+ * It also means the absolute path every reader uses has already been through
+ * the chokepoint by construction, rather than by remembering to call it.
+ *
+ * @throws {PathRefusalError} the path is not one we would ever read.
+ * @throws {ApiError} `not-found` when it is fine but not in the index.
+ */
+function resolveRequestedFile(cg, projectRoot, requested) {
+    const posix = toRequestPath(requested);
+    // Refusals happen here, ahead of everything.
+    const absolute = (0, security_1.resolveProjectFile)(projectRoot, posix);
+    const found = findIndexedFile(cg, posix);
+    if (!found)
+        throw notIndexedError(posix);
+    return { ...found, absolute };
+}
+function notIndexedError(file) {
+    return (0, respond_1.notFound)(`${file} is not in this CodeGraph index.`, 'The viewer only reads files the index knows about. If the file is new, ' +
+        'it appears after the next sync; if it is excluded (gitignored, generated, ' +
+        'or too large to parse), it will not appear at all.');
+}
+/**
+ * Split source the way the index counted it.
+ *
+ * Rows are `\n`-delimited — that is how tree-sitter numbers them — so a CRLF
+ * file has the same line numbers here as in the graph. The trailing `\r` is
+ * dropped per line so it does not render as a stray glyph.
+ */
+function splitLines(content) {
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.endsWith('\r'))
+            lines[i] = line.slice(0, -1);
+    }
+    // A file ending in a newline splits to a final empty string that is not a
+    // line of source. Every other trailing empty line IS one.
+    if (lines.length > 1 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+/**
+ * The whole text of an INDEXED file, or `null` for anything unreadable.
+ *
+ * The dead code report's corroboration pass needs to count an identifier in a
+ * file's text, and this module is the only one in `api/` that opens a file — so
+ * the reader it uses lives here, behind the same chokepoint. Three refusals,
+ * all answering `null` rather than throwing, because the caller's rule is
+ * already "cannot read it → do not make the claim":
+ *
+ * - not in the index (the viewer never reads a file the graph does not know);
+ * - outside the project (`resolveProjectFile` throws; caught here);
+ * - bigger than `maxBytes`.
+ *
+ * Drift is deliberately NOT checked. The question being asked is "does anything
+ * in this file write this name", and the file's current bytes are the better
+ * answer to it than the bytes we indexed.
+ */
+function readIndexedFileText(cg, projectRoot, requested, maxBytes) {
+    try {
+        const found = findIndexedFile(cg, requested);
+        if (!found)
+            return null;
+        const absolute = (0, security_1.resolveProjectFile)(projectRoot, found.storedPath);
+        const stats = fs.statSync(absolute);
+        if (!stats.isFile() || stats.size > maxBytes)
+            return null;
+        return fs.readFileSync(absolute, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether an indexed file has changed on disk since it was indexed — the same
+ * verdict `/api/source` returns, for endpoints that must *flag* drift without
+ * serving source (a symbol header, a file outline).
+ *
+ * Cheap first: size plus floored mtime is the identical freshness test the sync
+ * fast path uses, so an untouched file costs one `stat`. Only a stat mismatch
+ * pays for a hash, which is what keeps a `touch` or a checkout that rewrote
+ * identical bytes from reading as drift.
+ *
+ * Any failure answers `false`. A wrong "stale" flag would put a warning banner
+ * over correct source; the cases that would trip it (missing record, unreadable
+ * file) have their own handling in the endpoints that actually read.
+ */
+function hasDriftedOnDisk(projectRoot, storedPath, record) {
+    try {
+        const absolute = (0, security_1.resolveProjectFile)(projectRoot, storedPath);
+        const stats = fs.statSync(absolute);
+        if (stats.size === record.size && Math.floor(stats.mtimeMs) === Math.floor(record.modifiedAt)) {
+            return false;
+        }
+        if (stats.size > exports.MAX_SOURCE_BYTES)
+            return true;
+        const content = fs.readFileSync(absolute, 'utf-8');
+        return (0, crypto_1.createHash)('sha256').update(content).digest('hex') !== record.contentHash;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The drift verdict AND the file's length, from one read.
+ *
+ * The whole-file view needs both before it draws anything: the drift banner,
+ * and the line count that fixes the height of the scrolling document (every
+ * line is a fixed 20px, so the total IS the layout). Asking
+ * {@link hasDriftedOnDisk} and then a source page would answer the first
+ * question against one read of the file and the second against another, which
+ * is exactly the window in which a file can change underneath the two.
+ *
+ * Unlike `hasDriftedOnDisk` there is no stat-only fast path: the bytes have to
+ * be read to be counted. That is the cost of knowing the length, and it is
+ * bounded by {@link MAX_SOURCE_BYTES} like every other read here.
+ */
+function readFileShape(projectRoot, storedPath, record) {
+    let absolute;
+    try {
+        absolute = (0, security_1.resolveProjectFile)(projectRoot, storedPath);
+    }
+    catch {
+        // A refusal on a path the INDEX handed us is not a request to refuse — the
+        // caller already passed the chokepoint. Treat it as unreadable.
+        return { drift: false, totalLines: null };
+    }
+    try {
+        const stats = fs.statSync(absolute);
+        if (stats.size > exports.MAX_SOURCE_BYTES) {
+            return { drift: false, totalLines: null, reason: 'The file is too large to read here.' };
+        }
+        const content = fs.readFileSync(absolute, 'utf-8');
+        const drift = (0, crypto_1.createHash)('sha256').update(content).digest('hex') !== record.contentHash;
+        return {
+            drift,
+            totalLines: splitLines(content).length,
+            ...(drift
+                ? {
+                    reason: 'This file changed on disk after the last index sync, so the line ' +
+                        'numbers the graph holds no longer match it.',
+                }
+                : {}),
+        };
+    }
+    catch {
+        return {
+            drift: true,
+            totalLines: null,
+            reason: 'The file is in the index but could not be read from disk.',
+        };
+    }
+}
+/** Said once, so the two places that answer with current bytes cannot diverge. */
+const DRIFT_CURRENT_REASON = 'This file changed on disk after the last index sync. These are its current ' +
+    'lines; the indexed line ranges — symbol bodies, call sites, ports — no longer ' +
+    'match them. The next sync picks it up.';
+function parseOnDrift(query) {
+    const raw = query.get('ondrift');
+    if (raw === null || raw === '' || raw === 'omit')
+        return 'omit';
+    if (raw === 'current')
+        return 'current';
+    throw (0, respond_1.badRequest)(`Parameter "ondrift" must be "omit" or "current" (got "${raw}").`, 'Omit it to leave a drifted file unsliced; "current" serves the bytes on disk instead.');
+}
+async function buildSource(cg, projectRoot, query) {
+    const requested = (0, respond_1.textParam)(query, 'file');
+    // Refusal first, index lookup second — see `resolveRequestedFile`.
+    const { record, storedPath, absolute } = resolveRequestedFile(cg, projectRoot, requested);
+    const from = (0, respond_1.intParam)(query, 'from', { min: 1, max: 5_000_000, default: 1 });
+    const to = (0, respond_1.intParam)(query, 'to', { min: 1, max: 5_000_000, default: 0 });
+    if (to !== 0 && to < from) {
+        throw (0, respond_1.badRequest)(`Parameter "to" (${to}) must not be before "from" (${from}).`);
+    }
+    const onDrift = parseOnDrift(query);
+    const base = {
+        file: storedPath.replace(/\\/g, '/'),
+        language: record.language,
+        drift: false,
+        showing: 'indexed',
+        contentHash: record.contentHash,
+        indexedAt: record.indexedAt,
+        generated: record.generated === true,
+        totalLines: null,
+    };
+    let stats;
+    try {
+        stats = fs.statSync(absolute);
+    }
+    catch {
+        // Indexed but gone. That IS drift, and the strongest kind: nothing on disk
+        // corresponds to the ranges the graph holds — and `ondrift=current` has
+        // nothing to fall back to either.
+        return {
+            ...base,
+            drift: true,
+            showing: 'none',
+            reason: 'The file is in the index but no longer on disk.',
+        };
+    }
+    if (stats.size > exports.MAX_SOURCE_BYTES) {
+        throw (0, respond_1.badRequest)(`${base.file} is ${Math.round(stats.size / 1024 / 1024)} MB — too large to serve as source.`);
+    }
+    let content;
+    try {
+        content = fs.readFileSync(absolute, 'utf-8');
+    }
+    catch (err) {
+        throw new respond_1.ApiError('internal', `Could not read ${base.file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Byte-identical to extraction's `hashContent` (sha256 over the utf-8
+    // string). A touch or a checkout that rewrote the same bytes must not count
+    // as drift, which is exactly what hashing content rather than mtime buys.
+    const hash = (0, crypto_1.createHash)('sha256').update(content).digest('hex');
+    const drift = hash !== record.contentHash;
+    if (drift && onDrift === 'omit') {
+        return {
+            ...base,
+            drift: true,
+            showing: 'none',
+            reason: 'This file changed on disk after the last index sync, so the indexed line ' +
+                'ranges no longer reliably match. Source is omitted rather than risk showing ' +
+                "a different symbol's code; it returns after the next sync.",
+        };
+    }
+    const all = splitLines(content);
+    // Past the end of the file `from` names nothing, which is a caller bug worth
+    // surfacing rather than answering with the last line as if that were meant.
+    // `to` past the end is different — "line 30 to the end, whatever that is" is
+    // an ordinary way to ask, so it clamps.
+    //
+    // The exception is a drifted file the caller asked for anyway: it has already
+    // been told the numbering does not hold, and a save that SHORTENED the file
+    // between the length it was given and this read is an ordinary race, not a
+    // bug. Those get an empty slice.
+    if (from > all.length) {
+        if (!drift) {
+            throw (0, respond_1.badRequest)(`Parameter "from" (${from}) is past the end of ${base.file}, which has ${all.length} lines.`);
+        }
+        return {
+            ...base,
+            drift: true,
+            showing: 'current',
+            totalLines: all.length,
+            from,
+            to: from - 1,
+            lines: [],
+            truncated: false,
+            reason: DRIFT_CURRENT_REASON,
+        };
+    }
+    const start = from;
+    const requestedEnd = to === 0 ? all.length : Math.min(to, all.length);
+    const end = Math.min(requestedEnd, start + exports.MAX_SOURCE_LINES - 1);
+    const slice = all.slice(start - 1, end);
+    return {
+        ...base,
+        drift,
+        // The bytes are always the ones on disk. What changes with drift is what
+        // they can be *used* for: under `current` the caller must not map anything
+        // the index holds onto these numbers.
+        showing: drift ? 'current' : 'indexed',
+        ...(drift ? { reason: DRIFT_CURRENT_REASON } : {}),
+        totalLines: all.length,
+        from: start,
+        to: end,
+        lines: slice,
+        truncated: end < requestedEnd,
+        // Keyed on the hash of the bytes ACTUALLY BEING SERVED, so the cache is
+        // invalidated by the file changing rather than by a clock, and two viewers
+        // looking at the same symbol share one tokenisation. It must be the disk
+        // hash rather than the record's: on a drifted file those differ, and keying
+        // current lines under the indexed hash would serve the previous edit's
+        // colours over this one's text.
+        highlight: await (0, highlight_1.highlightLines)(slice, {
+            language: record.language,
+            cacheKey: `${hash}:${start}:${end}`,
+        }),
+    };
+}
+//# sourceMappingURL=source.js.map

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

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

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

@@ -0,0 +1,27 @@
+/**
+ * `GET /api/stats` — what this index is, and how much to trust it.
+ *
+ * The viewer's top bar shows a couple of numbers from here, but the reason the
+ * endpoint carries more than that is honesty: an index can be truncated
+ * (`state: "indexing"` after a killed run), built by an older extractor, or
+ * simply old. A reader that draws confident graphs over a half-built index is
+ * the failure mode worth designing against, so the state travels with the
+ * counts rather than being something the UI has to ask for separately.
+ */
+import type { CodeGraph } from '../../index';
+export interface WireBlastScale {
+    /** Most distinct dependents any symbol in the index has. Exact — one query. */
+    maxDirect: number;
+    /** Widest depth-{@link BLAST_DEPTH} radius found across the sampled symbols. */
+    maxWithinHops: number;
+    hops: number;
+    /** How many symbols were measured for `maxWithinHops`. */
+    sampled: number;
+    /** True whenever `maxWithinHops` came from a sample rather than every symbol. */
+    estimated: boolean;
+}
+export declare function blastScaleFor(cg: CodeGraph, projectRoot: string, edgeCount: number): WireBlastScale;
+/** Drop the memoised scale — for tests, which build a fresh index per case. */
+export declare function resetBlastScaleCache(): void;
+export declare function buildStats(cg: CodeGraph, projectRoot: string): unknown;
+//# sourceMappingURL=stats.d.ts.map