dsh-gitnexus-plus 0.0.0-stage → 0.1.2

package/lib/gitnexus/commands.js

@@ -0,0 +1,185 @@
+/**
+ * The maintenance commands this plugin hands to the operator.
+ *
+ * WHY THE TEXT STILL EXISTS AFTER THE BUTTONS
+ * -------------------------------------------
+ * A first revision spawned `gitnexus analyze` directly from the plugin and exposed
+ * it as a button. That was wrong: a plugin that spawns processes bypasses the host's
+ * permission system. The correction was not "never run it" but "run it through
+ * `ctx.shell`", which is what the analyze runner does. The exact command is still the
+ * deliverable here because it is what the confirmation shows, what a failed run can
+ * be reproduced with, and what an operator can paste when the deployment has no
+ * shell executor at all. The two must not drift: the runner builds its argv from the
+ * same decisions this module documents.
+ *
+ * WHAT MAKES THE COMMANDS NON-OBVIOUS
+ * -----------------------------------
+ * A bare `gitnexus analyze` does **not** work in every deployment, and the failures
+ * are silent-ish. Measured on this machine, under a confined DSH process:
+ *
+ *   - `ensureHeap` re-spawns the CLI with a larger heap over piped stdio, which a
+ *     confined sandbox denies (`spawn EPERM`). `GITNEXUS_MEMORY=off` suppresses the
+ *     respawn; `NODE_OPTIONS` supplies the heap it was trying to obtain.
+ *   - The FTS extension installs itself out-of-process and fails the same way.
+ *     `--skip-fts` builds the index without it.
+ *   - The global registry write (`~/.gitnexus/registry.json`) is outside the
+ *     workspace and may be denied. `GITNEXUS_HOME` redirects it.
+ *
+ * `--index-only` on both commands is deliberate and not a sandbox workaround:
+ * the default `analyze` also rewrites AGENTS.md, CLAUDE.md and agent skill files
+ * inside the repository. A maintenance button must not edit the working tree.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+/** Heap the CLI is given, matching what `ensureHeap` would have asked for. */
+const HEAP_MB = 8192;
+/**
+ * Where this plugin keeps GitNexus's global registry for one repository.
+ *
+ * `GITNEXUS_HOME` is normally `~/.gitnexus`, outside a confined host's writable
+ * scope. Pointing it at a directory inside the project's own `.gitnexus/` keeps the
+ * registry write next to the index and inside the workspace — which is the scope the
+ * operator already granted. The analysis itself still writes `.gitnexus/lbug`; this
+ * only moves the global registry side effect.
+ */
+export function defaultGitnexusHome(repoPath) {
+    return path.join(repoPath, '.gitnexus', 'plugin-home');
+}
+/**
+ * Whether this index says content-level FTS is available.
+ *
+ * A missing manifest, a legacy manifest, or a status other than `available` all mean
+ * "do not attempt FTS". The read is synchronous because both the maintenance-command
+ * builder and the analyze runner are synchronous; the manifest is a few kilobytes.
+ */
+export function ftsAvailable(repoPath) {
+    for (const name of ['gitnexus.json', 'meta.json']) {
+        try {
+            const raw = JSON.parse(readFileSync(path.join(repoPath, '.gitnexus', name), 'utf8'));
+            // The first manifest that parses is authoritative; falling through to the
+            // legacy copy on a `disabled-by-flag` status could resurrect a contradictory
+            // `available` from a stale `meta.json`.
+            return raw.capabilities?.fts?.status === 'available';
+        }
+        catch {
+            /* try the other manifest name */
+        }
+    }
+    return false;
+}
+/**
+ * The effective `--skip-fts` decision for one repository.
+ *
+ * `false` (the default) means **automatic**: skip FTS when the index does not have
+ * it, so a refresh in a confined process does not die trying to install an extension
+ * out-of-process. `true` forces the flag. There is deliberately no "force FTS on":
+ * that is a repair action (`gitnexus analyze --repair-fts`), not an incremental
+ * refresh, and hiding a repair behind a config boolean would mislead.
+ *
+ * The alternative — a static default — was measured wrong in both directions: `true`
+ * forces a 21x full rebuild on an index that already has FTS, while `false` makes the
+ * refresh fail with `spawn EPERM` on an index that does not.
+ */
+export function effectiveSkipFts(repoPath, configured) {
+    return configured || !ftsAvailable(repoPath);
+}
+/**
+ * Build the two commands for a repository.
+ *
+ * Pure, because the exact text is the deliverable — a reviewer should be able to
+ * assert on it without spawning anything.
+ *
+ * WHY `--skip-fts` IS NOT A DEFAULT
+ * ---------------------------------
+ * It was one, on the reasoning that the FTS extension installs out-of-process and a
+ * confined process denies that (`spawn EPERM`). Measured on a 39-file repository,
+ * that reasoning is wrong in the case that matters:
+ *
+ *   index has FTS + `--skip-fts`   179.22 s   full DB wipe + bulk COPY
+ *   index has FTS, no flag           8.57 s   FTS fails to load, degrades cleanly
+ *   index has no FTS + `--skip-fts`  8.25 s   changed=0, 39 rows preserved
+ *   same, warm                       6.56 s
+ *
+ * Disabling a search index the store already has forces GitNexus to rebuild the
+ * whole graph store, which is the exact opposite of incremental — a 21x penalty on
+ * the one transition an operator is most likely to hit. Letting FTS fail on its own
+ * costs nothing: it prints a warning and indexes anyway.
+ *
+ * The flag remains available for the case it was written for, where the extension
+ * file is *absent* and the install itself is what fails.
+ */
+export function maintenanceCommands(repoPath, options = {}) {
+    const resolved = {
+        platform: options.platform ?? process.platform,
+        skipFts: options.skipFts === true,
+        memoryOff: options.memoryOff !== false,
+        gitnexusHome: options.gitnexusHome ?? null,
+    };
+    const { platform, skipFts, memoryOff, gitnexusHome } = resolved;
+    const common = ['analyze', '--index-only'];
+    if (skipFts)
+        common.push('--skip-fts');
+    const quote = (value) => platform === 'win32' ? `'${value.replace(/'/g, "''")}'` : `'${value.replace(/'/g, "'\\''")}'`;
+    /** Environment assignments, in the syntax of the operator's shell. */
+    const envPrefix = () => {
+        const pairs = [];
+        if (memoryOff)
+            pairs.push(['GITNEXUS_MEMORY', 'off']);
+        pairs.push(['NODE_OPTIONS', `--max-old-space-size=${HEAP_MB}`]);
+        if (gitnexusHome !== null && gitnexusHome !== '')
+            pairs.push(['GITNEXUS_HOME', gitnexusHome]);
+        if (platform === 'win32') {
+            return `${pairs.map(([k, v]) => `$env:${k}=${quote(v)}`).join('; ')}; `;
+        }
+        return `${pairs.map(([k, v]) => `${k}=${quote(v)}`).join(' ')} `;
+    };
+    const line = (extra) => {
+        const args = [...common, ...extra, quote(repoPath)];
+        return `gitnexus ${args.join(' ')}`;
+    };
+    return [
+        {
+            mode: 'init',
+            label: '初始化索引',
+            when: '该项目还没有 .gitnexus 索引时使用。',
+            argv: line([]),
+            shell: envPrefix() + line([]),
+            destructive: false,
+            caveat: skipFts
+                ? '--skip-fts 会让一个已有 FTS 的索引清库重建（实测 179s vs 8.5s），非必要不要加。'
+                : // The measured range, not the best case. An earlier wording said "秒级（约 7s）"
+                    // on the strength of a no-change run; five changed files on the same repository
+                    // took 171 s. Understating this is how an operator concludes the button hung.
+                    '耗时随改动量增长：无改动约 7s，5 个文件实测约 171s。日志会写 changed/added/deleted。',
+        },
+        {
+            mode: 'full',
+            label: '强制全量重构',
+            when: '增量刷新卡死或结果反常时的逃生舱。重建图与 FTS，耗时数分钟；未变更文件的解析产物仍会复用。',
+            argv: line(['--force']),
+            shell: envPrefix() + line(['--force']),
+            destructive: true,
+            caveat: '--force 重建图与 FTS，未变更文件的解析产物仍会复用。',
+        },
+    ];
+}
+/**
+ * A one-line explanation of why the environment prefix is there at all, for the
+ * panel to show under the commands rather than leaving them looking arbitrary.
+ */
+export function commandRationale(options) {
+    const notes = [];
+    if (options.memoryOff) {
+        notes.push('GITNEXUS_MEMORY=off：阻止 CLI 用管道 stdio 重启自身（受限环境下会 EPERM）。');
+    }
+    notes.push(`NODE_OPTIONS=--max-old-space-size=${HEAP_MB}：补上它本想通过重启获得的那份堆。`);
+    if (options.skipFts) {
+        notes.push('--skip-fts：FTS 扩展需在子进程安装，受限环境下会失败。');
+    }
+    if (options.gitnexusHome !== null && options.gitnexusHome !== '') {
+        notes.push(`GITNEXUS_HOME=${options.gitnexusHome}：把全局注册表写入重定向到受控目录。`);
+    }
+    notes.push('--index-only：不会改动仓库内的 AGENTS.md / CLAUDE.md / skills 文件。');
+    return notes;
+}
+//# sourceMappingURL=commands.js.map

package/lib/gitnexus/commands.js.map

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

package/lib/gitnexus/coverage.d.ts

@@ -0,0 +1,340 @@
+/**
+ * Index-coverage and large-file monitoring for one repository.
+ *
+ * The question this answers is not "how big is this repo" but "what did
+ * `analyze` silently leave out, and does that change how much I should trust the
+ * index?". GitNexus tells the operator, on stderr, once:
+ *
+ *     Skipped 3 large files (>512KB, likely generated/vendored)
+ *       - dist/app.min.js
+ *       ...and 2 more (set GITNEXUS_VERBOSE=1 to list them all)
+ *
+ * That is the whole surface. It is not returned, not persisted, not queryable,
+ * and gone once the terminal scrolls. `scanRepository` turns it into data; this
+ * module turns it into a judgement — including the case that matters most, where
+ * one minified bundle dominates a language's byte share and makes the index look
+ * far more complete than it is.
+ */
+import { type IndexStats } from './index-meta.js';
+import { type CapSource } from './scan.js';
+import { type ClassifiedLanguage, type LanguageRow, type LanguageAggregate } from './languages.js';
+import { type ActivityInfo } from './git-activity.js';
+import { type ToolchainStatus } from './toolchain.js';
+/**
+ * Re-exported so a consumer of the report can name these without also depending on
+ * the module that produces them. They are **not** redeclared here: an earlier draft
+ * of this file declared its own `ActivityInfo` and `LanguageRow`, which collided with
+ * the real ones — two structurally different interfaces under one name, and the
+ * compiler reported the mismatch as an assignment failure at the very end of
+ * `analyzeCoverage` rather than where the wrong guess was made.
+ */
+export type { CapSource, ClassifiedLanguage, LanguageRow, ActivityInfo };
+export type { LanguageClass } from './languages.js';
+export type { ActivityAuthor, ActivityBranch, ActivityFile, ActivityHistogram, ActivityTotals, ActivityWindow, FileVerdict, HistogramBucket, } from './git-activity.js';
+/**
+ * What a byte-level probe concluded about one oversized file.
+ *
+ * `binary` is decided before `suspect`: a first revision tested only "no newlines ⇒
+ * one enormous line", which flagged every binary asset as minified.
+ */
+export interface FileShape {
+    /** Machine data, not text at all. */
+    binary: boolean;
+    /** Minified: text, but written as one enormous line. */
+    suspect: boolean;
+    /** Characters per line (meaningless when binary). */
+    avgLineLength: number;
+    estimatedLines: number | null;
+    sampledBytes: number;
+}
+/**
+ * The report's shape.
+ *
+ * These are declared rather than left to inference because the report is the
+ * plugin's contract: the same object is returned by the `gitnexus_coverage` tool,
+ * served by `GET /api/gitnexus/coverage`, and printed by the CLI.
+ *
+ * They were JSDoc typedefs first. Renaming the file to `.ts` did not carry them
+ * over — JSDoc annotations are only *used* by the compiler in `.js` files under
+ * `checkJs`, and in a `.ts` file they are documentation. So the migration is where
+ * these become real: `export interface` is what lets `format.ts`, the CLI and the
+ * route name a field instead of seeing `object`.
+ */
+export interface RepoInfo {
+    /** Absolute repository root. */
+    path: string;
+    name: string;
+    /** Where `.gitnexus` lives. */
+    storagePath: string;
+    /** Whether a manifest was found. */
+    indexed: boolean;
+    /** Whether GitNexus's own registry lists it. */
+    registered: boolean;
+    /** Which manifest was read. */
+    metaFile: string | null;
+    /** ISO timestamp. */
+    indexedAt: string | null;
+    /** Commit the index was built at. */
+    lastCommit: string | null;
+    branch: string | null;
+    remoteUrl: string | null;
+    /** Raw stats block from the manifest. */
+    stats: IndexStats | null;
+    graphEmbeddings: number | null;
+}
+export interface GraphInfo {
+    files: number;
+    nodes: number;
+    edges: number;
+    communities: number;
+    processes: number;
+    embeddings: number;
+    edgesPerNode: number;
+}
+/** Commit counts on either side of `indexed...HEAD`. */
+export interface AheadBehind {
+    /** Commits the index has that HEAD does not — non-zero means a split history. */
+    behind: number;
+    /** Commits HEAD has that the index does not — how far the index lags. */
+    ahead: number;
+}
+export type StalenessState = 'current' | 'behind' | 'diverged' | 'unknown';
+export interface StalenessInfo {
+    state: StalenessState;
+    indexedCommit: string | null;
+    headCommit: string | null;
+    branch: string | null;
+    /** Null when git could not be asked — distinct from a clean tree (`0`). */
+    dirtyCount: number | null;
+    aheadBehind: AheadBehind | null;
+    gitAvailable: boolean;
+}
+export interface ProvenanceInfo {
+    schemaFingerprint: string | null;
+    contentRetention: string | null;
+    ftsProfile: string | null;
+    analysisFeatures: unknown;
+    crossLanguageProperties: number;
+    runnerCliVersion: string | null;
+}
+/** Where the effective size cap came from — re-exported from `scan.ts`. */
+export interface CapInfo {
+    bytes: number;
+    text: string;
+    source: CapSource;
+    defaultBytes: number;
+    defaultText: string;
+    maxBytes: number;
+    maxText: string;
+    recordedInIndex: boolean;
+}
+export interface Totals {
+    scanned: number;
+    selected: number;
+    large: number;
+    suppressedDeclarations: number;
+    indexedInGraph: number;
+    largeBytes: number;
+    scannedBytes: number;
+}
+/** The language identity attached to a file — the shape `classifyFile` returns. */
+export type LanguageTag = ClassifiedLanguage;
+export interface LargeFile {
+    path: string;
+    size: number;
+    sizeText: string;
+    shareOfScanned: number;
+    /**
+     * Never null: `classifyFile` always places a file, falling back to an `other`
+     * class rather than declining. An earlier declaration made this nullable, which
+     * was not a safer type but a wrong one — it forced five null guards onto call
+     * sites for a value that cannot be null.
+     */
+    language: ClassifiedLanguage;
+    shareOfLanguage: number;
+    /**
+     * Null when the probe budget was exhausted, so the reader is never told a file is
+     * fine when it was simply not examined.
+     */
+    minified: FileShape | null;
+    /** A boolean, not a label: it is consumed as `if (entry.generatedHint)`. */
+    generatedHint: boolean;
+}
+export interface Attribution {
+    oversizeCount: number;
+    oversizeBytes: number;
+    oversizeShareOfScanned: number;
+}
+export interface IndexInfo {
+    uncoveredCount: number;
+    uncoveredSample: Array<{
+        path: string;
+        size: number;
+    }>;
+    staleCount: number;
+    staleSample: string[];
+    dirtyPaths: string[];
+}
+export type WarningLevel = 'warn' | 'info';
+export interface ReportWarning {
+    level: WarningLevel;
+    code: string;
+    message: string;
+    evidence: Record<string, unknown>;
+}
+/**
+ * The language breakdown as this report shapes it: the aggregate plus the oversized
+ * files held out of it, so a reader can see which files the percentages exclude.
+ */
+export type LanguageBreakdown = LanguageAggregate & {
+    largeExcluded: LanguageRow[];
+};
+export interface AnalyzerInfo {
+    gitnexusVersion: string | null;
+    /**
+     * Whether the scan reused GitNexus's own primitives or the local fallback.
+     *
+     * A union, not a number: an earlier JSDoc declaration said `number` while the
+     * implementation compared it against the string `'gitnexus'`. The compiler found
+     * that the moment this became a real type.
+     */
+    primitives: 'gitnexus' | 'fallback';
+}
+/**
+ * Receiver members the resolver could not type, as GitNexus records them.
+ *
+ * While any of these exist, `impact`/`context` answer with a lower bound rather
+ * than an exact set — which is why the report surfaces the count next to every
+ * other number rather than burying it.
+ */
+export interface GraphQuality {
+    totalSites: number;
+    counts: Record<string, number>;
+}
+/**
+ * One entry of the manifest's `capabilities` block: whether a query surface is live,
+ * which implementation backs it, and why it is not live when it is not.
+ */
+export interface CapabilityEntry {
+    status?: string;
+    skipReason?: string;
+    /** The implementation behind the surface, e.g. `ladybugdb`, `ladybugdb-fts`. */
+    provider?: string;
+    /** Anything else the manifest records, preserved rather than dropped. */
+    [key: string]: unknown;
+}
+/**
+ * Narrow the manifest's `capabilities` block.
+ *
+ * The manifest is JSON written by another tool, so at the boundary it is
+ * `Record<string, unknown>` and has to be **checked** rather than asserted. A cast
+ * here would move the failure from "a missing field renders as undefined" to "a
+ * malformed manifest crashes the panel", which is the wrong trade for data this
+ * plugin does not control.
+ *
+ * WHAT THE NARROWING IS AND IS NOT FOR
+ * ------------------------------------
+ * Its job is to make the JSON safe to *read*, not to decide which fields exist. A
+ * first version listed the two fields it expected and rebuilt each entry from just
+ * those, which silently dropped `provider` — a field the panel renders, and the
+ * reason it showed `unknown` for two surfaces that were available. So the original
+ * entry is spread first and only the validated fields are overwritten: something
+ * this plugin has not heard of yet survives, instead of being deleted by a checklist.
+ */
+export declare function readCapabilities(raw: Record<string, unknown> | null | undefined): Record<string, CapabilityEntry>;
+/**
+ * Narrow the manifest's `unresolvedReceiverMembers` block.
+ *
+ * Returns null rather than a zero-filled object when the field is absent: an index
+ * written before this was recorded must render as "not recorded", not as "no untyped
+ * receivers", because those are opposite claims about how much to trust the graph.
+ */
+export declare function readGraphQuality(raw: unknown): GraphQuality | null;
+export interface CoverageReport {
+    repo: RepoInfo;
+    analyzer: AnalyzerInfo;
+    cap: CapInfo;
+    totals: Totals;
+    largeFiles: LargeFile[];
+    attribution: Attribution;
+    index: IndexInfo;
+    graph: GraphInfo | null;
+    capabilities: Record<string, CapabilityEntry>;
+    staleness: StalenessInfo;
+    provenance: ProvenanceInfo | null;
+    graphQuality: GraphQuality | null;
+    warnings: ReportWarning[];
+    languages: LanguageBreakdown | null;
+    activity: ActivityInfo | null;
+    /**
+     * Whether GitNexus itself is present on this machine.
+     *
+     * Reported rather than thrown, because "no GitNexus" is a state the panel has to act
+     * on: it is the difference between showing an index and offering to produce one, and
+     * only the report can carry that distinction. The probe only stats the filesystem, so
+     * filling this costs nothing on the hot path.
+     */
+    toolchain: ToolchainStatus | null;
+}
+/**
+ * Judge what kind of file this is from the head of its bytes.
+ *
+ * Reads only the head: a bundle megabytes wide on one line is identifiable from
+ * any prefix, and reading it whole to decide would cost exactly what the size cap
+ * exists to avoid.
+ *
+ * BINARY IS CHECKED FIRST, AND THAT ORDER IS THE WHOLE POINT
+ * ---------------------------------------------------------
+ * A first revision tested only "no newlines ⇒ one enormous line", which flagged
+ * every binary asset as minified. Measured on a real repository: a 380 MB `.glb`
+ * model and a 30 MB `.glb` reported "single-line ≈ 399 230 584 chars" — absurd on
+ * its face, and worse than absurd in effect, because it told the reader that 97 %
+ * of the repository's skipped bytes were compressed *source*. They were 3D assets
+ * that could never have held a symbol.
+ *
+ * A binary file has few newlines for a reason that has nothing to do with
+ * minification, so no line-length statistic over it means anything. The test is
+ * git's own: a NUL byte in the head means binary. A control-byte ratio backs it up
+ * for machine formats that happen to avoid NUL.
+ *
+ * The extrapolation is deliberately crude — newline density in the head is assumed
+ * to hold for the rest — and only ever produces a *warning*, never an exclusion.
+ *
+ * @param {string} absolutePath
+ * @param {number} size
+ * @returns {Promise<FileShape>}
+ */
+export declare function judgeMinified(absolutePath: string, size: number): Promise<FileShape>;
+/**
+ * @param {string} filePath repo-relative
+ * @returns {boolean} whether the path conventionally denotes build output
+ */
+export declare function looksGenerated(filePath: string): boolean;
+/** @param {number} bytes */
+export declare function formatBytes(bytes: number): string;
+/** Options for {@link analyzeCoverage}. */
+export interface AnalyzeOptions {
+    /** Environment to read GitNexus settings from. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Set false to skip the per-language breakdown (it costs a full re-walk). */
+    includeLanguages?: boolean;
+    /** Set false to skip reading git history. */
+    includeActivity?: boolean;
+    /** How far back the activity window reaches. */
+    activitySinceDays?: number;
+    /** Cap on commits read for the activity window. */
+    activityMaxCommits?: number;
+    /** How many oversized files may be probed for minification before giving up. */
+    minifiedSampleLimit?: number;
+    /** Where the plugin installs GitNexus, so the probe finds that copy too. */
+    toolchain?: {
+        managedPrefix?: string;
+    };
+}
+/**
+ * Build the full coverage report for a repository.
+ *
+ * @param repoPath absolute repository root
+ */
+export declare function analyzeCoverage(repoPath: string, options?: AnalyzeOptions): Promise<CoverageReport>;
+//# sourceMappingURL=coverage.d.ts.map

package/lib/gitnexus/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/gitnexus/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAsD,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACtG,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAE3E;;;;;;;GAOG;AACH,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;AACzE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,WAAW,EACX,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAW3B;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,UAAU,EAAE,OAAO,CAAC;IACpB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qBAAqB;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qCAAqC;IACrC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yCAAyC;IACzC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,cAAc,CAAC;IACtB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,2EAA2E;AAE3E,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,MAAM;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB,EAAE,MAAM,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,kBAAkB,CAAC;AAE7C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,SAAS;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG;IAAE,aAAa,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC;AAErF,MAAM,WAAW,YAAY;IAC3B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;;;OAMG;IACH,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAcjH;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAWlE;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC9C,SAAS,EAAE,aAAa,CAAC;IACzB,UAAU,EAAE,cAAc,GAAG,IAAI,CAAC;IAClC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B;;;;;;;OAOG;IACH,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CA2D1F;AAsBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD;AASD,4BAA4B;AAC5B,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,6CAA6C;IAC7C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gFAAgF;IAChF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,SAAS,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAkWzB"}