codegraph-java 0.1.0

package/dist/ui-server/highlight/index.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SLICE_CACHE_LINES = exports.SLICE_CACHE_LIMIT = exports.MAX_HIGHLIGHT_CHARS = exports.MAX_HIGHLIGHT_LINES = exports.TOKEN_CLASSES = exports.isHighlightable = exports.grammarFor = exports.COMPONENT_LANGUAGES = void 0;
+exports.clearHighlightCache = clearHighlightCache;
+exports.highlightCacheStats = highlightCacheStats;
+exports.highlightLines = highlightLines;
+const syntax_tokens_1 = require("../../extraction/syntax-tokens");
+const languages_1 = require("./languages");
+var languages_2 = require("./languages");
+Object.defineProperty(exports, "COMPONENT_LANGUAGES", { enumerable: true, get: function () { return languages_2.COMPONENT_LANGUAGES; } });
+Object.defineProperty(exports, "grammarFor", { enumerable: true, get: function () { return languages_2.grammarFor; } });
+Object.defineProperty(exports, "isHighlightable", { enumerable: true, get: function () { return languages_2.isHighlightable; } });
+var syntax_tokens_2 = require("../../extraction/syntax-tokens");
+Object.defineProperty(exports, "TOKEN_CLASSES", { enumerable: true, get: function () { return syntax_tokens_2.SYNTAX_TOKEN_CLASSES; } });
+/**
+ * Lines above this are not classified.
+ *
+ * Matches `MAX_SOURCE_LINES`, so anything the source endpoint will serve, this
+ * will try to classify.
+ */
+exports.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.
+ */
+exports.MAX_HIGHLIGHT_CHARS = 600_000;
+/** Classified slices kept in memory. Most are one symbol's body. */
+exports.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.
+ */
+exports.SLICE_CACHE_LINES = 20_000;
+/** Class name → its index in {@link SYNTAX_TOKEN_CLASSES}, which is what the wire carries. */
+const CLASS_ID = Object.fromEntries(syntax_tokens_1.SYNTAX_TOKEN_CLASSES.map((name, index) => [name, index]));
+/**
+ * Classes that are never merged with their neighbour.
+ *
+ * Every identifier-shaped token has to stay claimable on its own — the overlay
+ * wraps exactly one of them as a call-site link, and two merged into one token
+ * would underline both or neither.
+ */
+const UNMERGEABLE = new Set([
+    'ident',
+    'type',
+    'def',
+]);
+/* -------------------------------------------------------------- the cache -- */
+const sliceCache = new Map();
+let cachedLines = 0;
+function cacheGet(key) {
+    const hit = sliceCache.get(key);
+    // Re-insert so the map's insertion order is a recency order and the first
+    // key is always the coldest.
+    if (hit) {
+        sliceCache.delete(key);
+        sliceCache.set(key, hit);
+    }
+    return hit;
+}
+function cachePut(key, value) {
+    sliceCache.set(key, value);
+    cachedLines += value.lines.length;
+    while (sliceCache.size > exports.SLICE_CACHE_LIMIT ||
+        (cachedLines > exports.SLICE_CACHE_LINES && sliceCache.size > 1)) {
+        const oldest = sliceCache.keys().next();
+        if (oldest.done)
+            break;
+        cachedLines -= sliceCache.get(oldest.value)?.lines.length ?? 0;
+        sliceCache.delete(oldest.value);
+    }
+}
+/** Drop everything cached. Tests use it; nothing in the server needs to. */
+function clearHighlightCache() {
+    sliceCache.clear();
+    cachedLines = 0;
+}
+/** What the slice cache is holding — for tests, and for anyone diagnosing it. */
+function highlightCacheStats() {
+    return { entries: sliceCache.size, lines: cachedLines };
+}
+/**
+ * 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.
+ */
+async function highlightLines(lines, options = {}) {
+    const grammar = (0, languages_1.grammarFor)(options.language);
+    const key = options.cacheKey ? `${grammar ?? '-'} ${options.cacheKey}` : null;
+    if (key) {
+        const hit = cacheGet(key);
+        if (hit)
+            return hit;
+    }
+    const result = await highlightUncached(lines, options.language ?? null, grammar);
+    if (key)
+        cachePut(key, result);
+    return result;
+}
+async function highlightUncached(lines, language, grammar) {
+    if (!grammar) {
+        return plain(lines, null, 'No syntax grammar covers this file type.');
+    }
+    if (lines.length > exports.MAX_HIGHLIGHT_LINES) {
+        return plain(lines, grammar, `Too many lines to highlight (over ${exports.MAX_HIGHLIGHT_LINES}).`);
+    }
+    const text = lines.join('\n');
+    if (text.length > exports.MAX_HIGHLIGHT_CHARS) {
+        return plain(lines, grammar, 'Too much text on too few lines to highlight (minified?).');
+    }
+    const tokenized = await (0, syntax_tokens_1.tokenizeSource)(text, language);
+    if (!tokenized || tokenized.spans.length === 0) {
+        return plain(lines, grammar, `The ${grammar} grammar is not available in this build.`);
+    }
+    return {
+        engine: 'tree-sitter',
+        grammar: tokenized.grammars.join('+') || grammar,
+        classes: syntax_tokens_1.SYNTAX_TOKEN_CLASSES,
+        lines: toWireLines(lines, text, tokenized.spans),
+    };
+}
+function plain(lines, grammar, reason) {
+    return {
+        engine: 'plain',
+        grammar,
+        classes: syntax_tokens_1.SYNTAX_TOKEN_CLASSES,
+        lines: lines.map(atomizePlain),
+        ...(reason ? { reason } : {}),
+    };
+}
+/* -------------------------------------------------------- spans to lines -- */
+/**
+ * Cut the classifier's spans into one token list per source line.
+ *
+ * The classifier answers over the whole slice, in string offsets, and leaves
+ * the gaps between spans unclassified — those are whitespace and the layout
+ * separators no grammar names. Here they become plain tokens, multi-line spans
+ * (a block comment, a heredoc) are split at the newlines, and every line ends
+ * up with a token list whose texts concatenate back to exactly that line.
+ *
+ * One entry per line, always: the code block indexes rows positionally, so a
+ * short answer would render every line below it against the wrong source.
+ */
+function toWireLines(lines, text, spans) {
+    const pieces = [];
+    let cursor = 0;
+    for (const span of spans) {
+        if (span.end <= cursor)
+            continue;
+        const start = Math.max(span.start, cursor);
+        if (start > cursor)
+            pieces.push({ start: cursor, end: start, cls: 'other' });
+        pieces.push({ start, end: span.end, cls: span.cls });
+        cursor = span.end;
+    }
+    if (cursor < text.length)
+        pieces.push({ start: cursor, end: text.length, cls: 'other' });
+    const out = [];
+    let lineStart = 0;
+    let first = 0;
+    for (const line of lines) {
+        const lineEnd = lineStart + line.length;
+        const row = [];
+        while (first < pieces.length && pieces[first].end <= lineStart)
+            first += 1;
+        for (let i = first; i < pieces.length; i++) {
+            const piece = pieces[i];
+            if (piece.start >= lineEnd)
+                break;
+            const from = Math.max(piece.start, lineStart);
+            const to = Math.min(piece.end, lineEnd);
+            if (to > from)
+                pushPiece(row, text.slice(from, to), piece.cls);
+        }
+        out.push(row);
+        lineStart = lineEnd + 1; // the '\n' the join put back
+    }
+    return out;
+}
+/* ---------------------------------------------------------- atomisation -- */
+/**
+ * An identifier, in the loosest sense every indexed language agrees on.
+ *
+ * The high range is there because `\w` is ASCII-only in JavaScript and a symbol
+ * name can be Chinese, Japanese or Cyrillic; a call site in those repositories
+ * has to be linkable too.
+ */
+const IDENT = /[A-Za-z_$À-￿][\w$À-￿]*/g;
+/**
+ * Add one classified run to a line, splitting it into identifier atoms.
+ *
+ * This is the step that makes the graph's call-site links independent of how a
+ * grammar chose to chunk a line: the viewer has to be able to wrap exactly
+ * `withLock` in `this.mutex.withLock`, and giving it identifier-sized atoms up
+ * front means the overlay only ever *claims* a token, never re-cuts one.
+ *
+ * Comments and strings are left whole on purpose: no edge points inside one,
+ * and a doc comment split into forty atoms is forty times the wire bytes for
+ * nothing.
+ */
+function pushPiece(row, text, cls) {
+    if (cls === 'comment' || cls === 'string') {
+        push(row, cls, text);
+        return;
+    }
+    splitIdentifiers(row, text, cls);
+}
+function atomizePlain(line) {
+    const out = [];
+    splitIdentifiers(out, line, 'other');
+    return out;
+}
+/**
+ * Emit `text` as alternating non-identifier and identifier runs.
+ *
+ * An identifier inside a run the grammar called a keyword keeps the keyword
+ * class — `func` should still carry its weight — while the overlay's matcher
+ * looks at a token's *text*, not its class, so a language whose grammar calls a
+ * declared type name something unexpected still links.
+ */
+function splitIdentifiers(out, text, cls) {
+    if (text === '')
+        return;
+    IDENT.lastIndex = 0;
+    let at = 0;
+    let match;
+    while ((match = IDENT.exec(text)) !== null) {
+        if (match.index > at)
+            push(out, gapClass(cls), text.slice(at, match.index));
+        push(out, cls === 'other' ? 'ident' : cls, match[0]);
+        at = match.index + match[0].length;
+    }
+    if (at < text.length)
+        push(out, gapClass(cls), text.slice(at));
+}
+/** The class for the non-identifier remainder of a run. */
+function gapClass(cls) {
+    return UNMERGEABLE.has(cls) ? 'other' : cls;
+}
+/** Append, merging into the previous token when it carries the same class. */
+function push(out, cls, text) {
+    if (text === '')
+        return;
+    const id = CLASS_ID[cls];
+    const last = out[out.length - 1];
+    if (last && last[0] === id && !UNMERGEABLE.has(cls)) {
+        last[1] += text;
+        return;
+    }
+    out.push([id, text]);
+}
+//# sourceMappingURL=index.js.map

package/dist/ui-server/highlight/index.js.map

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

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

@@ -0,0 +1,36 @@
+/**
+ * Which engine language a file's source is classified with (CG-57).
+ *
+ * There is no second grammar table any more. The viewer reads a file with the
+ * grammar the *engine* parsed it with, so this is a question about coverage
+ * rather than about mapping: a language the extractor has a tree-sitter grammar
+ * for classifies; one it does not renders plain, with its identifiers still
+ * split out so the graph's call-site links land exactly as they do everywhere
+ * else. Highlighting is the part that degrades, never the linking.
+ *
+ * The three single-file-component formats are the exception worth naming. A
+ * `.svelte`, `.vue` or `.astro` file has no grammar of its own here — the
+ * extractors pull the `<script>` block out and hand it to TypeScript or
+ * JavaScript — and the classifier does exactly the same thing, so a component's
+ * code is read by the grammar its symbols came from while the surrounding
+ * markup stays plain.
+ */
+import type { Language } from '../../types';
+/**
+ * Formats whose source is classified through their embedded script blocks.
+ *
+ * Kept beside `syntaxRegionsFor`, which decides where those blocks are — this
+ * list only has to agree about *which* formats have them.
+ */
+export declare const COMPONENT_LANGUAGES: readonly Language[];
+/**
+ * The grammar a file of this language is read with, or null when it has none.
+ *
+ * Accepts the raw string off a `FileRecord` rather than a `Language`, because
+ * an index written by an older engine can hold a language this build has since
+ * renamed, and a viewer must not throw over that.
+ */
+export declare function grammarFor(language: string | undefined | null): string | null;
+/** Whether a file of this language classifies at all. For tests and diagnostics. */
+export declare function isHighlightable(language: string | undefined | null): boolean;
+//# sourceMappingURL=languages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"languages.d.ts","sourceRoot":"","sources":["../../../src/ui-server/highlight/languages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,QAAQ,EAA+B,CAAC;AAEnF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK7E;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAE5E"}

package/dist/ui-server/highlight/languages.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Which engine language a file's source is classified with (CG-57).
+ *
+ * There is no second grammar table any more. The viewer reads a file with the
+ * grammar the *engine* parsed it with, so this is a question about coverage
+ * rather than about mapping: a language the extractor has a tree-sitter grammar
+ * for classifies; one it does not renders plain, with its identifiers still
+ * split out so the graph's call-site links land exactly as they do everywhere
+ * else. Highlighting is the part that degrades, never the linking.
+ *
+ * The three single-file-component formats are the exception worth naming. A
+ * `.svelte`, `.vue` or `.astro` file has no grammar of its own here — the
+ * extractors pull the `<script>` block out and hand it to TypeScript or
+ * JavaScript — and the classifier does exactly the same thing, so a component's
+ * code is read by the grammar its symbols came from while the surrounding
+ * markup stays plain.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPONENT_LANGUAGES = void 0;
+exports.grammarFor = grammarFor;
+exports.isHighlightable = isHighlightable;
+const grammars_1 = require("../../extraction/grammars");
+/**
+ * Formats whose source is classified through their embedded script blocks.
+ *
+ * Kept beside `syntaxRegionsFor`, which decides where those blocks are — this
+ * list only has to agree about *which* formats have them.
+ */
+exports.COMPONENT_LANGUAGES = ['svelte', 'vue', 'astro'];
+/**
+ * The grammar a file of this language is read with, or null when it has none.
+ *
+ * Accepts the raw string off a `FileRecord` rather than a `Language`, because
+ * an index written by an older engine can hold a language this build has since
+ * renamed, and a viewer must not throw over that.
+ */
+function grammarFor(language) {
+    if (!language)
+        return null;
+    const lang = language;
+    if (exports.COMPONENT_LANGUAGES.includes(lang))
+        return 'typescript';
+    return (0, grammars_1.hasTreeSitterGrammar)(lang) ? lang : null;
+}
+/** Whether a file of this language classifies at all. For tests and diagnostics. */
+function isHighlightable(language) {
+    return grammarFor(language) !== null;
+}
+//# sourceMappingURL=languages.js.map

package/dist/ui-server/highlight/languages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"languages.js","sourceRoot":"","sources":["../../../src/ui-server/highlight/languages.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAoBH,gCAKC;AAGD,0CAEC;AA3BD,wDAAiE;AAEjE;;;;;GAKG;AACU,QAAA,mBAAmB,GAAwB,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAEnF;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,QAAmC;IAC5D,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,IAAI,GAAG,QAAoB,CAAC;IAClC,IAAI,2BAAmB,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,YAAY,CAAC;IAC5D,OAAO,IAAA,+BAAoB,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED,oFAAoF;AACpF,SAAgB,eAAe,CAAC,QAAmC;IACjE,OAAO,UAAU,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;AACvC,CAAC"}

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

@@ -0,0 +1,92 @@
+/**
+ * The `cg ui` server.
+ *
+ * A loopback-only `node:http` server that hands the browser the built viewer
+ * (`dist/viewer/`) and, through the JSON API mounted on the `api` seam below
+ * (`./api`), a view of one indexed project. No framework, no new dependency: it
+ * answers GET, serves files, and refuses everything else.
+ *
+ * It is a reader with one exception, added deliberately and scoped as narrowly
+ * as it could be: `POST`/`DELETE /api/trails` saves and removes the reader's own
+ * named trails, as JSON files under `.codegraph/ui/trails/`. Nothing else it
+ * serves has a side effect, no other path accepts a write, and `--read-only`
+ * turns even that one off. See `security.ts` for what a write has to carry.
+ *
+ * The interesting part is not the routing, it is the boundary in `security.ts`.
+ * Read that first.
+ */
+import * as http from 'http';
+export { ViewerMissingError } from './assets';
+export { BROWSER_ENV, DEFAULT_PORT_ATTEMPTS, DEFAULT_UI_PORT, LOOPBACK_ADDRESS, VIEWER_PATH_ENV, } from './constants';
+export { ALLOWED_METHODS, READ_METHODS, WRITE_HEADER, WRITE_METHODS, PathRefusalError, isAllowedHost, isAllowedOrigin, isSafeRequestPath, isWriteMethod, isWriteRequest, resolveProjectFile, resolveStaticAsset, } from './security';
+export { browserOpenCommand, openBrowser } from './open-browser';
+export { contentTypeFor, cacheControlFor } from './static';
+export { createGraphApi, GraphSession, ApiError } from './api';
+export type { GraphApi, GraphApiOptions } from './api';
+/**
+ * Everything a request handler needs, already validated.
+ */
+export interface UiRequestContext {
+    /** Percent-decoded path portion of the request URL, always starting with `/`. */
+    pathname: string;
+    /** Parsed query string. */
+    query: URLSearchParams;
+    /** Absolute path of the indexed project this server is reading. */
+    projectRoot: string;
+    /**
+     * The request method. `GET` or `HEAD` for every read; `POST` or `DELETE`
+     * only for a request that already passed {@link isWriteRequest}, which is
+     * `/api/trails` and nothing else.
+     */
+    method: string;
+}
+/**
+ * A handler mounted under `/api/`. Returns `true` when it answered the request
+ * (i.e. wrote a response), `false` to fall through to a 404.
+ *
+ * This is the seam the JSON API plugs into. Everything it reads out of — or
+ * writes into — the user's repository must go through `resolveProjectFile`;
+ * see `security.ts`.
+ */
+export type UiApiHandler = (req: http.IncomingMessage, res: http.ServerResponse, ctx: UiRequestContext) => boolean | Promise<boolean>;
+export interface UiServerOptions {
+    /** Absolute path of the indexed project to read. */
+    projectRoot: string;
+    /**
+     * Port to bind. `0` lets the OS choose. Defaults to {@link DEFAULT_UI_PORT}.
+     */
+    port?: number;
+    /**
+     * Try the next port when the requested one is taken (default `true`).
+     *
+     * The CLI turns this OFF for an explicit `--port`: a scripted invocation that
+     * silently lands somewhere else is worse than one that says the port is busy.
+     */
+    portFallback?: boolean;
+    /** How many ports to try in total. Defaults to {@link DEFAULT_PORT_ATTEMPTS}. */
+    maxPortAttempts?: number;
+    /** Directory of built viewer assets. Defaults to the shipped `dist/viewer/`. */
+    viewerDir?: string;
+    /** Optional read-only JSON API mounted under `/api/`. */
+    api?: UiApiHandler;
+}
+export interface UiServerHandle {
+    /** The port actually bound (may differ from the requested one — see fallback). */
+    port: number;
+    /** The URL to open. */
+    url: string;
+    /** Directory being served as the viewer. */
+    viewerDir: string;
+    /** The underlying server, for tests and for callers that want raw events. */
+    server: http.Server;
+    /** Stop listening and drop live connections. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Start the viewer server.
+ *
+ * Resolves once the socket is bound, so the caller can print a URL that is
+ * already answering.
+ */
+export declare function startUiServer(options: UiServerOptions): Promise<UiServerHandle>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui-server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAiB7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC/D,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAGvD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,KAAK,EAAE,eAAe,CAAC;IACvB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,GAAG,EAAE,gBAAgB,KAClB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;IACpB,4DAA4D;IAC5D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiCD;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAsDrF"}