codegraph-java 0.1.0

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

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * The wire shapes the viewer reads, and the rules for producing them.
+ *
+ * Two ideas run through this file:
+ *
+ * 1. **One round-trip per screen.** Every endpoint returns everything a screen
+ *    draws, in the spirit of `codegraph_explore`: the Symbol view never has to
+ *    ask a follow-up question to render a rail, a badge or a count.
+ * 2. **Capped lists, honest totals.** A symbol with 545 callers cannot ship 545
+ *    rows, but it must never claim it has fewer. Every capped list carries the
+ *    true `total` beside the `shown` slice, so the UI can say "+N more" rather
+ *    than quietly truncating.
+ *
+ * Nothing here reads the filesystem — that lives in `source.ts`, behind
+ * `resolveProjectFile`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPosixPath = exports.CALLER_EDGE_KINDS = exports.CONTAINER_KINDS = exports.TYPE_KINDS = exports.MAX_IMPORT_FILES = exports.MAX_OUTLINE_NODES = exports.MAX_OUTSIDE_INDEX_SAMPLES = exports.TEST_CALLER_BUDGET = exports.TEST_CALLER_HOPS = exports.BLAST_DEPTH = exports.MAX_TEST_FILES = exports.MAX_EDGES_PER_GROUP = exports.MAX_OUTGOING_GROUPS = exports.MAX_INCOMING_GROUPS = exports.UNCERTAIN_BELOW = exports.HUB_THRESHOLD = void 0;
+exports.toNodeRef = toNodeRef;
+exports.toNodeDetail = toNodeDetail;
+exports.toWireEdge = toWireEdge;
+exports.wireList = wireList;
+exports.groupRelations = groupRelations;
+exports.firstLine = firstLine;
+const query_utils_1 = require("../../search/query-utils");
+// =============================================================================
+// Caps and thresholds
+// =============================================================================
+/**
+ * Fan-in at or above which a symbol is a "hub" — changing it is a
+ * repo-wide event. Matches the threshold the Symbol view's `hub · N` badge
+ * uses (design spec §3.2).
+ */
+exports.HUB_THRESHOLD = 40;
+/**
+ * Below this resolution confidence an edge is a name-only guess. The viewer
+ * folds these away behind "Uncertain · N name-only matches, confidence < 0.6"
+ * rather than mixing them into the rails as if they were resolved.
+ */
+exports.UNCERTAIN_BELOW = 0.6;
+/** Caller groups (one per calling symbol) returned for a node. */
+exports.MAX_INCOMING_GROUPS = 300;
+/** Callee groups (one per called symbol) returned for a node. */
+exports.MAX_OUTGOING_GROUPS = 200;
+/** Edges kept inside a single group — one symbol calling another 400 times. */
+exports.MAX_EDGES_PER_GROUP = 40;
+/** Test files named in a node's test-caller summary (explore uses the same shape). */
+exports.MAX_TEST_FILES = 6;
+/**
+ * Dependency hops the blast-radius summary walks. Matches the depth
+ * `codegraph_explore` claims when it says "within 3 hops".
+ */
+exports.BLAST_DEPTH = 3;
+/** Caller hops walked looking for a test. Mirrors `codegraph_explore`'s "tests:" line. */
+exports.TEST_CALLER_HOPS = 3;
+/** `getCallers` lookups the test walk may spend, so a god-symbol can't stall a request. */
+exports.TEST_CALLER_BUDGET = 64;
+/** Unresolved references listed by name before the payload just counts them. */
+exports.MAX_OUTSIDE_INDEX_SAMPLES = 40;
+/** Symbols in a file outline. Beyond this the outline is truncated, not dropped. */
+exports.MAX_OUTLINE_NODES = 3000;
+/** Files listed in each direction of the File view's import rails. */
+exports.MAX_IMPORT_FILES = 300;
+const rel = (p) => p.replace(/\\/g, '/');
+exports.toPosixPath = rel;
+function toNodeRef(node) {
+    const file = rel(node.filePath);
+    const ref = {
+        id: node.id,
+        kind: node.kind,
+        name: node.name,
+        qualifiedName: node.qualifiedName,
+        file,
+        line: node.startLine,
+        endLine: node.endLine,
+        language: node.language,
+        test: (0, query_utils_1.isTestFile)(file),
+    };
+    if (node.signature)
+        ref.signature = node.signature;
+    if (node.isExported)
+        ref.exported = true;
+    return ref;
+}
+function toNodeDetail(node) {
+    const detail = {
+        ...toNodeRef(node),
+        startColumn: node.startColumn,
+        endColumn: node.endColumn,
+        lines: Math.max(1, node.endLine - node.startLine + 1),
+    };
+    if (node.docstring)
+        detail.docstring = node.docstring;
+    if (node.visibility)
+        detail.visibility = node.visibility;
+    if (node.isAsync)
+        detail.async = true;
+    if (node.isStatic)
+        detail.static = true;
+    if (node.isAbstract)
+        detail.abstract = true;
+    if (node.decorators?.length)
+        detail.decorators = node.decorators;
+    if (node.typeParameters?.length)
+        detail.typeParameters = node.typeParameters;
+    if (node.returnType)
+        detail.returnType = node.returnType;
+    return detail;
+}
+function toWireEdge(edge) {
+    const meta = (edge.metadata ?? {});
+    const wire = { kind: edge.kind };
+    if (typeof edge.line === 'number')
+        wire.line = edge.line;
+    if (typeof edge.column === 'number')
+        wire.col = edge.column;
+    if (typeof meta.confidence === 'number')
+        wire.confidence = meta.confidence;
+    if (typeof meta.resolvedBy === 'string')
+        wire.resolvedBy = meta.resolvedBy;
+    if (edge.provenance)
+        wire.provenance = edge.provenance;
+    if (typeof meta.synthesizedBy === 'string')
+        wire.synthesizedBy = meta.synthesizedBy;
+    if (typeof meta.via === 'string')
+        wire.via = meta.via;
+    if (typeof meta.registeredAt === 'string')
+        wire.registeredAt = meta.registeredAt;
+    if (meta.valueRef === true)
+        wire.valueRef = true;
+    return wire;
+}
+function wireList(items, total) {
+    return { total, shown: items.length, truncated: items.length < total, items };
+}
+/**
+ * Fold edges into one relation per counterpart symbol.
+ *
+ * @param edges     edges all sharing the focal node at one end
+ * @param endpoint  which end of each edge names the OTHER symbol
+ * @param nodes     batch-resolved endpoint nodes (never a lookup per edge)
+ */
+function groupRelations(edges, endpoint, nodes) {
+    const byNode = new Map();
+    for (const edge of edges) {
+        const id = endpoint(edge);
+        const bucket = byNode.get(id);
+        if (bucket)
+            bucket.push(edge);
+        else
+            byNode.set(id, [edge]);
+    }
+    const relations = [];
+    for (const [id, group] of byNode) {
+        const node = nodes.get(id);
+        // An edge whose endpoint is missing from `nodes` means the graph and the
+        // node table disagree — skip it rather than invent a row. Callers still see
+        // it in the totals they computed from the raw edge list.
+        if (!node)
+            continue;
+        const ordered = [...group].sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+        const wireEdges = ordered.slice(0, exports.MAX_EDGES_PER_GROUP).map(toWireEdge);
+        const edgeKinds = [];
+        for (const edge of ordered)
+            if (!edgeKinds.includes(edge.kind))
+                edgeKinds.push(edge.kind);
+        const lines = [
+            ...new Set(ordered.map((e) => e.line).filter((l) => typeof l === 'number' && l > 0)),
+        ].sort((a, b) => a - b);
+        let confidence = null;
+        let synthesized = false;
+        for (const edge of ordered) {
+            const value = edge.metadata?.confidence;
+            if (typeof value === 'number' && (confidence === null || value > confidence))
+                confidence = value;
+            if (edge.provenance === 'heuristic')
+                synthesized = true;
+        }
+        relations.push({
+            node: toNodeRef(node),
+            edgeKinds,
+            edges: wireEdges,
+            edgeCount: ordered.length,
+            lines,
+            confidence,
+            // No confidence recorded is NOT uncertain: tree-sitter edges extracted
+            // straight from the AST carry none precisely because they are certain.
+            uncertain: confidence !== null && confidence < exports.UNCERTAIN_BELOW,
+            synthesized,
+        });
+    }
+    return relations;
+}
+/** First call-site line of a relation, for line-anchored ordering. Unlined rows sort last. */
+function firstLine(relation) {
+    return relation.lines[0] ?? Number.MAX_SAFE_INTEGER;
+}
+/** Node kinds that count as "a type" for the Symbol view's "types used" chips. */
+exports.TYPE_KINDS = new Set([
+    'interface',
+    'type_alias',
+    'class',
+    'struct',
+    'enum',
+    'union',
+    'trait',
+    'protocol',
+]);
+/** Container kinds whose members the outline nests one level deeper. */
+exports.CONTAINER_KINDS = new Set([
+    'file',
+    'module',
+    'namespace',
+    'class',
+    'struct',
+    'interface',
+    'trait',
+    'protocol',
+    'enum',
+    'union',
+]);
+/** The four edge kinds `getCallers` treats as "reaches this symbol". */
+exports.CALLER_EDGE_KINDS = new Set([
+    'calls',
+    'references',
+    'imports',
+    'instantiates',
+    'navigates',
+]);
+//# sourceMappingURL=wire.js.map

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

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

package/dist/ui-server/assets.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Locating the built browser viewer on disk.
+ *
+ * The viewer is a static Vite build that ships inside the package, exactly like
+ * `schema.sql` and the tree-sitter grammars: emitted into `dist/viewer/`,
+ * copied wholesale by `scripts/build-bundle.sh`, packed by
+ * `scripts/pack-npm.sh`. So it is found the same way `db/index.ts` finds
+ * `schema.sql` — relative to `__dirname`, never to `process.cwd()`, which is
+ * whatever directory the user happened to be standing in.
+ *
+ * `dist/viewer`, NOT `dist/ui`: `src/ui/` is the engine's TERMINAL ui and tsc
+ * already compiles it to `dist/ui/`. See `ui/vite.config.ts`.
+ */
+import { VIEWER_PATH_ENV } from './constants';
+export { VIEWER_PATH_ENV };
+/**
+ * The viewer build is missing — the package was assembled without it, or the
+ * repo was built with `tsc` alone. Carries user-facing remediation rather than
+ * a stack trace, because the CLI prints `.message` verbatim.
+ */
+export declare class ViewerMissingError extends Error {
+    constructor(searched: readonly string[]);
+}
+/**
+ * Candidate locations for the viewer, most-specific first.
+ *
+ * 1. The `CODEGRAPH_VIEWER_PATH` override.
+ * 2. `<__dirname>/../viewer` — the shipped layout (`dist/ui-server/` →
+ *    `dist/viewer/`).
+ * 3. `<__dirname>/../../dist/viewer` — running the TypeScript straight out of
+ *    `src/` (vitest, tsx), where `__dirname` is `src/ui-server/`.
+ */
+export declare function viewerDirCandidates(): string[];
+/**
+ * Resolve the directory holding the built viewer.
+ *
+ * @throws {ViewerMissingError} when no candidate contains an `index.html`.
+ */
+export declare function resolveViewerDir(): string;
+//# sourceMappingURL=assets.d.ts.map

package/dist/ui-server/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../src/ui-server/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,QAAQ,EAAE,SAAS,MAAM,EAAE;CAUxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAO9C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAczC"}

package/dist/ui-server/assets.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Locating the built browser viewer on disk.
+ *
+ * The viewer is a static Vite build that ships inside the package, exactly like
+ * `schema.sql` and the tree-sitter grammars: emitted into `dist/viewer/`,
+ * copied wholesale by `scripts/build-bundle.sh`, packed by
+ * `scripts/pack-npm.sh`. So it is found the same way `db/index.ts` finds
+ * `schema.sql` — relative to `__dirname`, never to `process.cwd()`, which is
+ * whatever directory the user happened to be standing in.
+ *
+ * `dist/viewer`, NOT `dist/ui`: `src/ui/` is the engine's TERMINAL ui and tsc
+ * already compiles it to `dist/ui/`. See `ui/vite.config.ts`.
+ */
+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.ViewerMissingError = exports.VIEWER_PATH_ENV = void 0;
+exports.viewerDirCandidates = viewerDirCandidates;
+exports.resolveViewerDir = resolveViewerDir;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const constants_1 = require("./constants");
+Object.defineProperty(exports, "VIEWER_PATH_ENV", { enumerable: true, get: function () { return constants_1.VIEWER_PATH_ENV; } });
+/**
+ * The viewer build is missing — the package was assembled without it, or the
+ * repo was built with `tsc` alone. Carries user-facing remediation rather than
+ * a stack trace, because the CLI prints `.message` verbatim.
+ */
+class ViewerMissingError extends Error {
+    constructor(searched) {
+        super('The CodeGraph viewer assets are missing from this installation.\n' +
+            'Looked in:\n' +
+            searched.map((p) => `  ${p}`).join('\n') +
+            '\n\nIf you installed CodeGraph normally, reinstall it — the release bundle ' +
+            'ships the viewer.\nIf you are working from a source checkout, run: npm run build');
+        this.name = 'ViewerMissingError';
+    }
+}
+exports.ViewerMissingError = ViewerMissingError;
+/**
+ * Candidate locations for the viewer, most-specific first.
+ *
+ * 1. The `CODEGRAPH_VIEWER_PATH` override.
+ * 2. `<__dirname>/../viewer` — the shipped layout (`dist/ui-server/` →
+ *    `dist/viewer/`).
+ * 3. `<__dirname>/../../dist/viewer` — running the TypeScript straight out of
+ *    `src/` (vitest, tsx), where `__dirname` is `src/ui-server/`.
+ */
+function viewerDirCandidates() {
+    const override = process.env[constants_1.VIEWER_PATH_ENV]?.trim();
+    const candidates = [
+        path.join(__dirname, '..', 'viewer'),
+        path.join(__dirname, '..', '..', 'dist', 'viewer'),
+    ];
+    return override ? [path.resolve(override), ...candidates] : candidates;
+}
+/**
+ * Resolve the directory holding the built viewer.
+ *
+ * @throws {ViewerMissingError} when no candidate contains an `index.html`.
+ */
+function resolveViewerDir() {
+    const candidates = viewerDirCandidates();
+    for (const dir of candidates) {
+        try {
+            if (fs.statSync(path.join(dir, 'index.html')).isFile()) {
+                // realpath so the containment checks in `security.ts` compare like for
+                // like when the install lives behind a symlink (Homebrew, nvm, pnpm).
+                return fs.realpathSync(dir);
+            }
+        }
+        catch {
+            // Not here — try the next candidate.
+        }
+    }
+    throw new ViewerMissingError(candidates);
+}
+//# sourceMappingURL=assets.js.map

package/dist/ui-server/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../src/ui-server/assets.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCH,kDAOC;AAOD,4CAcC;AA7DD,uCAAyB;AACzB,2CAA6B;AAC7B,2CAA8C;AAErC,gGAFA,2BAAe,OAEA;AAExB;;;;GAIG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,QAA2B;QACrC,KAAK,CACH,mEAAmE;YACjE,cAAc;YACd,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YACxC,6EAA6E;YAC7E,kFAAkF,CACrF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAXD,gDAWC;AAED;;;;;;;;GAQG;AACH,SAAgB,mBAAmB;IACjC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,2BAAe,CAAC,EAAE,IAAI,EAAE,CAAC;IACtD,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC;KACnD,CAAC;IACF,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB;IAC9B,MAAM,UAAU,GAAG,mBAAmB,EAAE,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;gBACvD,uEAAuE;gBACvE,sEAAsE;gBACtE,OAAO,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,qCAAqC;QACvC,CAAC;IACH,CAAC;IACD,MAAM,IAAI,kBAAkB,CAAC,UAAU,CAAC,CAAC;AAC3C,CAAC"}

package/dist/ui-server/constants.d.ts

@@ -0,0 +1,32 @@
+/**
+ * User-facing constants for the `cg ui` server.
+ *
+ * Deliberately dependency-free so the CLI can import them for `--help` text
+ * without pulling `node:http` (and the rest of the server) into every
+ * invocation of every other subcommand. `ui-server/index.ts` re-exports them,
+ * so consumers have one import to reach for.
+ */
+/** The port `cg ui` asks for first. */
+export declare const DEFAULT_UI_PORT = 4747;
+/** How many consecutive ports to try before giving up. */
+export declare const DEFAULT_PORT_ATTEMPTS = 20;
+/**
+ * The only interface the server ever binds. Not configurable, on purpose: this
+ * process serves the user's source code, and a `--host` flag is one typo away
+ * from publishing it to the local network.
+ */
+export declare const LOOPBACK_ADDRESS = "127.0.0.1";
+/**
+ * Overrides which browser (if any) `cg ui` launches. `none` — or `0`,
+ * `false`, `off`, or an empty value — suppresses the launch entirely, the same
+ * as `--no-open`. Any other value is run as a command with the URL as its
+ * single argument.
+ */
+export declare const BROWSER_ENV = "CODEGRAPH_BROWSER";
+/**
+ * Development/test override for the directory served as the viewer. Point it at
+ * a directory containing an `index.html` to serve something other than the
+ * shipped build.
+ */
+export declare const VIEWER_PATH_ENV = "CODEGRAPH_VIEWER_PATH";
+//# sourceMappingURL=constants.d.ts.map

package/dist/ui-server/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/ui-server/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uCAAuC;AACvC,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,eAAe,0BAA0B,CAAC"}

package/dist/ui-server/constants.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * User-facing constants for the `cg ui` server.
+ *
+ * Deliberately dependency-free so the CLI can import them for `--help` text
+ * without pulling `node:http` (and the rest of the server) into every
+ * invocation of every other subcommand. `ui-server/index.ts` re-exports them,
+ * so consumers have one import to reach for.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIEWER_PATH_ENV = exports.BROWSER_ENV = exports.LOOPBACK_ADDRESS = exports.DEFAULT_PORT_ATTEMPTS = exports.DEFAULT_UI_PORT = void 0;
+/** The port `cg ui` asks for first. */
+exports.DEFAULT_UI_PORT = 4747;
+/** How many consecutive ports to try before giving up. */
+exports.DEFAULT_PORT_ATTEMPTS = 20;
+/**
+ * The only interface the server ever binds. Not configurable, on purpose: this
+ * process serves the user's source code, and a `--host` flag is one typo away
+ * from publishing it to the local network.
+ */
+exports.LOOPBACK_ADDRESS = '127.0.0.1';
+/**
+ * Overrides which browser (if any) `cg ui` launches. `none` — or `0`,
+ * `false`, `off`, or an empty value — suppresses the launch entirely, the same
+ * as `--no-open`. Any other value is run as a command with the URL as its
+ * single argument.
+ */
+exports.BROWSER_ENV = 'CODEGRAPH_BROWSER';
+/**
+ * Development/test override for the directory served as the viewer. Point it at
+ * a directory containing an `index.html` to serve something other than the
+ * shipped build.
+ */
+exports.VIEWER_PATH_ENV = 'CODEGRAPH_VIEWER_PATH';
+//# sourceMappingURL=constants.js.map

package/dist/ui-server/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/ui-server/constants.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,uCAAuC;AAC1B,QAAA,eAAe,GAAG,IAAI,CAAC;AAEpC,0DAA0D;AAC7C,QAAA,qBAAqB,GAAG,EAAE,CAAC;AAExC;;;;GAIG;AACU,QAAA,gBAAgB,GAAG,WAAW,CAAC;AAE5C;;;;;GAKG;AACU,QAAA,WAAW,GAAG,mBAAmB,CAAC;AAE/C;;;;GAIG;AACU,QAAA,eAAe,GAAG,uBAAuB,CAAC"}

package/dist/ui-server/highlight/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Server-side syntax classification for the viewer's code block.
+ *
+ * The classes come off the engine's OWN tree-sitter parse (CG-57). Until then
+ * the viewer ran a second highlighter — Shiki, plus 56 pruned TextMate grammars
+ * shipped beside the binary — over source the engine had already parsed with a
+ * real grammar. That is gone: one grammar set, one opinion about what a `.ts`
+ * file is, nothing extra in the bundle, and roughly an order of magnitude off
+ * the cost on the language that used to be worst (see below).
+ *
+ * Three properties are unchanged, because they are what make this safe to
+ * depend on:
+ *
+ * * **It never fails a request.** A grammar that will not load, a parse that
+ *   throws, a language nobody wrote a grammar for, a slice too big to be worth
+ *   parsing — every one of them answers `engine: 'plain'` with a reason and the
+ *   source still goes out. Highlighting is the part that degrades; nothing else
+ *   does.
+ * * **Identifiers survive whatever token boundaries the grammar chose.** Every
+ *   code token is split into identifier runs before it goes on the wire, which
+ *   is what lets the viewer wrap a call site as a link by *claiming a token*
+ *   rather than re-tokenising the line on top of the classifier's answer.
+ * * **The classification is a class name, not a colour.** The viewer paints
+ *   from CSS custom properties, so one token stream serves light and dark and
+ *   the design tokens live in exactly one place.
+ *
+ * ## Cost, measured
+ *
+ * On the dev Mac, 3 000 lines, cold (parse + classify + wire):
+ *
+ * | | TypeScript | Go | Python |
+ * |---|---|---|---|
+ * | Shiki (was) | ~700 ms | 43–57 ms | 35–47 ms |
+ * | tree-sitter (now) | 24–41 ms | ~30 ms | 25–29 ms |
+ *
+ * Rust, Ruby, PHP, C# and Swift all land between 14 and 27 ms on the same
+ * measurement. TypeScript's TextMate grammar was 5–7× every other one and the
+ * cost was regex *execution*, not compilation — nothing about the old module
+ * could have fixed it, and it is now the same order as everything else. The
+ * slice cache still exists, because a re-render (a theme flip, a resize,
+ * stepping back through the trail) should cost nothing at all, and because a
+ * whole-file view pages the same file repeatedly.
+ */
+export { COMPONENT_LANGUAGES, grammarFor, isHighlightable } from './languages';
+export { SYNTAX_TOKEN_CLASSES as TOKEN_CLASSES } from '../../extraction/syntax-tokens';
+/** One token on the wire: its class id, then its text. */
+export type WireToken = [number, string];
+export interface HighlightResult {
+    /** `tree-sitter` when a grammar produced the classes; `plain` when nothing did. */
+    engine: 'tree-sitter' | 'plain';
+    /** The grammar the source was read with, or null. */
+    grammar: string | null;
+    /** Class names, indexed by the first element of every {@link WireToken}. */
+    classes: readonly string[];
+    /** One entry per source line, in order. */
+    lines: WireToken[][];
+    /** Why the answer is plain, when it is. Absent on the happy path. */
+    reason?: string;
+}
+/**
+ * Lines above this are not classified.
+ *
+ * Matches `MAX_SOURCE_LINES`, so anything the source endpoint will serve, this
+ * will try to classify.
+ */
+export declare const MAX_HIGHLIGHT_LINES = 4000;
+/**
+ * Characters above this are not classified.
+ *
+ * The line cap alone does not bound the work: one minified bundle line can be
+ * two megabytes, and a parser walks it character by character. This is the
+ * guard that keeps a single request from wedging a single-threaded loopback
+ * server, and it is generous — 600 kB is far more source than any screen
+ * renders.
+ */
+export declare const MAX_HIGHLIGHT_CHARS = 600000;
+/** Classified slices kept in memory. Most are one symbol's body. */
+export declare const SLICE_CACHE_LIMIT = 96;
+/**
+ * Total cached lines, which is the bound that actually matters.
+ *
+ * The entry count alone does not bound memory: 96 slices of a symbol body is a
+ * megabyte, 96 whole 4 000-line files is two orders of magnitude more, and this
+ * process is a reader someone leaves open all day. Twenty thousand lines is
+ * roughly a working set of every symbol a session visits, or a handful of whole
+ * files, and the eviction is the same recency order.
+ */
+export declare const SLICE_CACHE_LINES = 20000;
+/** Drop everything cached. Tests use it; nothing in the server needs to. */
+export declare function clearHighlightCache(): void;
+/** What the slice cache is holding — for tests, and for anyone diagnosing it. */
+export declare function highlightCacheStats(): {
+    entries: number;
+    lines: number;
+};
+export interface HighlightOptions {
+    /** The engine's language for the file, e.g. `typescript`. */
+    language?: string | null;
+    /**
+     * A key that changes whenever the text does — the file's content hash plus
+     * the requested range. Omit it and the slice is classified every time.
+     */
+    cacheKey?: string;
+}
+/**
+ * Classify `lines` for the viewer's code block.
+ *
+ * Never throws and never rejects: every failure path returns a plain result
+ * carrying the reason, because the caller is serving source and the source is
+ * the part that matters.
+ */
+export declare function highlightLines(lines: readonly string[], options?: HighlightOptions): Promise<HighlightResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/ui-server/highlight/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ui-server/highlight/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAMH,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,oBAAoB,IAAI,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAEvF,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC;IAChC,qDAAqD;IACrD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4EAA4E;IAC5E,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,2CAA2C;IAC3C,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC;IACrB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,SAAU,CAAC;AAE3C,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAkDxC,4EAA4E;AAC5E,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAExE;AAID,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAW1B"}