homegraph 1.5.1 → 1.5.2

package/dist/spec/mining/spec-extractor.js

@@ -1,369 +0,0 @@
-"use strict";
-/**
- * Spec file discovery and metadata extraction.
- *
- * Replaces `commit4spec/reverse_engineer/spec_extractor.py`.
- * Discovers spec files in a storage directory and extracts structured
- * metadata (title, subtitles, commit hash from commit-info.md).
- *
- * @module spec/mining/spec-extractor
- */
-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.extractMarkdownHeadings = extractMarkdownHeadings;
-exports.extractSpecMetadata = extractSpecMetadata;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const config_1 = require("../config");
-const utils_1 = require("../utils");
-const errors_1 = require("../../errors");
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const HEADING_RE = /^(#{1,6})\s+(.*)/;
-// ---------------------------------------------------------------------------
-// extractMarkdownHeadings
-// ---------------------------------------------------------------------------
-/**
- * Parse ATX headings from markdown content and build breadcrumb-path strings
- * with content previews.
- *
- * Algorithm (ported from `spec_extractor.py:50-88`):
- *
- * 1. Find all `#` … `######` headings (ATX-style) and their line positions.
- * 2. Walk through headings, maintaining a breadcrumb stack — pop until the
- *    stack is shorter than the current heading's level, then push the new
- *    heading text.
- * 3. For each heading, collect the "direct content" lines — non-heading,
- *    non-empty lines between this heading and the next heading of equal or
- *    higher level (or EOF).
- * 4. Skip headings that have sub-headings but no direct content.
- * 5. Build a display string: `breadcrumb_path - first_direct_content_line`.
- * 6. Strip `SPEC` suffix from level-1 (root) breadcrumb parts.
- * 7. Truncate the preview to `maxContentLen` characters, appending `…`
- *    when truncated.
- *
- * @param content       - Raw markdown string.
- * @param maxContentLen - Max characters for the content preview (default 200).
- * @returns Array of formatted heading strings.
- */
-function extractMarkdownHeadings(content, maxContentLen = 200) {
-    const lines = content.split('\n');
-    const headings = [];
-    for (let i = 0; i < lines.length; i++) {
-        const match = HEADING_RE.exec(lines[i]);
-        if (!match)
-            continue;
-        const text = match[2].trim();
-        if (!text)
-            continue;
-        headings.push({
-            lineIndex: i,
-            level: match[1].length,
-            text,
-        });
-    }
-    // Second pass: build breadcrumb and collect direct content.
-    const breadcrumb = [];
-    const result = [];
-    for (let hi = 0; hi < headings.length; hi++) {
-        const h = headings[hi];
-        // Adjust breadcrumb: pop until we're at the right depth.
-        while (breadcrumb.length >= h.level) {
-            breadcrumb.pop();
-        }
-        breadcrumb.push(h.text);
-        // Determine the end line of this heading's content section.
-        // The section ends at the next heading of equal or higher level (or EOF).
-        let endLine = lines.length;
-        for (let hj = hi + 1; hj < headings.length; hj++) {
-            const nextH = headings[hj];
-            if (nextH.level <= h.level) {
-                endLine = nextH.lineIndex;
-                break;
-            }
-        }
-        // Collect direct content: non-heading, non-empty lines within this section.
-        const directLines = [];
-        let hasSubHeadings = false;
-        for (let li = h.lineIndex + 1; li < endLine; li++) {
-            const line = lines[li].trim();
-            if (!line)
-                continue;
-            if (HEADING_RE.test(line)) {
-                hasSubHeadings = true;
-                continue;
-            }
-            directLines.push(line);
-        }
-        // Skip headings that only contain sub-headings (no direct text).
-        if (hasSubHeadings && directLines.length === 0) {
-            continue;
-        }
-        // Build the display path.
-        let display = breadcrumb.join(' → ');
-        // Strip trailing SPEC from level-1 (root) headings.
-        if (breadcrumb.length === 1) {
-            display = display.replace(/\s*SPEC\s*$/i, '');
-        }
-        // Append content preview (first direct line, truncated).
-        if (directLines.length > 0) {
-            let preview = directLines[0];
-            if (preview.length > maxContentLen) {
-                preview = preview.slice(0, maxContentLen) + '…';
-            }
-            display += ' - ' + preview;
-        }
-        result.push(display);
-    }
-    return result;
-}
-// ---------------------------------------------------------------------------
-// _findPrimaryDoc
-// ---------------------------------------------------------------------------
-/**
- * Find the primary spec document by trying each candidate name.
- *
- * Replaces the `{spec_dir}` placeholder in each candidate with `specDirName`,
- * then checks whether the resolved file exists in `specDirPath`.  Returns the
- * first match as `[resolvedName, absolutePath]`, or `null` when no candidate
- * matches.
- *
- * Ported from `spec_extractor.py:94-114`.
- */
-function _findPrimaryDoc(specDirPath, specDirName, candidates) {
-    for (const candidate of candidates) {
-        const resolved = candidate.replace(/\{spec_dir\}/g, specDirName);
-        const absPath = path.join(specDirPath, resolved);
-        if (fs.existsSync(absPath)) {
-            return [resolved, absPath];
-        }
-    }
-    return null;
-}
-// ---------------------------------------------------------------------------
-// Glob helper
-// ---------------------------------------------------------------------------
-/**
- * Simple glob-to-regex conversion for supplementary document matching.
- *
- * Only handles `*` (any non-separator characters) and literal text.
- * Does not support `**`, `?`, or character classes — sufficient for
- * patterns like `"*.md"` or `"changelog-*.md"`.
- */
-function globToRegex(glob) {
-    // Escape regex-special characters except *
-    let pattern = '';
-    for (const ch of glob) {
-        if (ch === '*') {
-            pattern += '[^/]*';
-        }
-        else if ('.+^${}()|[]\\'.includes(ch)) {
-            pattern += '\\' + ch;
-        }
-        else {
-            pattern += ch;
-        }
-    }
-    return new RegExp('^' + pattern + '$');
-}
-// ---------------------------------------------------------------------------
-// _buildMetadata
-// ---------------------------------------------------------------------------
-/**
- * Build `SpecMetadata` from raw spec content and supplementary documents.
- *
- * Ported from `spec_extractor.py:120-171`.
- *
- * 1. Extract a title from the first `# ` heading (stripping a trailing
- *    `SPEC` suffix); fallback to `specId`.
- * 2. Collect subtitles via `extractMarkdownHeadings`.
- * 3. Discover supplementary `.md` files in `specDirPath` that match
- *    `config.supplementaryGlobs` (excluding the primary doc) and merge
- *    their headings into the subtitle list.
- * 4. Resolve a commit hash from `commit-info.md` content in `specDirPath`
- *    (using `config.commitInfoCandidates`).
- */
-function _buildMetadata(specId, content, filePath, specDirPath, config) {
-    // ---- title ----
-    let title = specId;
-    const firstH1Match = content.match(/^#\s+(.*)/m);
-    if (firstH1Match && firstH1Match[1]) {
-        title = firstH1Match[1].trim().replace(/\s*SPEC\s*$/i, '');
-        if (!title) {
-            title = specId;
-        }
-    }
-    // ---- subtitles from primary doc ----
-    const subtitles = extractMarkdownHeadings(content);
-    // ---- supplementary docs ----
-    // Find the primary doc's filename so we can skip it.
-    const primaryDocName = path.basename(filePath);
-    let dirEntries;
-    try {
-        dirEntries = fs.readdirSync(specDirPath, { withFileTypes: true });
-    }
-    catch {
-        dirEntries = [];
-    }
-    const globRegexes = config.supplementaryGlobs.map((g) => globToRegex(g));
-    for (const entry of dirEntries) {
-        if (!entry.isFile())
-            continue;
-        if (!entry.name.endsWith('.md'))
-            continue;
-        if (entry.name === primaryDocName)
-            continue;
-        // Check if the file name matches any supplementary glob.
-        const matchesGlob = globRegexes.some((re) => re.test(entry.name));
-        if (!matchesGlob)
-            continue;
-        const suppPath = path.join(specDirPath, entry.name);
-        const suppContent = (0, utils_1.readFileContent)(suppPath);
-        if (suppContent === null)
-            continue;
-        const suppHeadings = extractMarkdownHeadings(suppContent);
-        for (const heading of suppHeadings) {
-            subtitles.push(heading);
-        }
-    }
-    // ---- commit hash ----
-    let commitHash = null;
-    for (const candidate of config.commitInfoCandidates) {
-        const ciPath = path.join(specDirPath, candidate);
-        const ciContent = (0, utils_1.readFileContent)(ciPath);
-        if (ciContent !== null) {
-            commitHash = (0, utils_1.parseCommitInfoMd)(ciContent);
-            break;
-        }
-    }
-    (0, errors_1.logDebug)('Built spec metadata', { specId, title, subtitleCount: subtitles.length, commitHash });
-    return {
-        specId,
-        title,
-        subtitles,
-        commitHash,
-        filePath,
-        type: 'directory',
-    };
-}
-// ---------------------------------------------------------------------------
-// extractSpecMetadata (public)
-// ---------------------------------------------------------------------------
-/**
- * Discover and extract metadata for a single spec, given its storage location
- * and directory name.
- *
- * Ported from `spec_extractor.py:177-237`.
- *
- * Two discovery branches are attempted in order:
- *
- * - **Flat-file**: checks `{specStoragePath}/{specDirName}.md`.  If it exists,
- *   reads it and produces metadata with `type: 'flat-file'`.
- * - **Directory**: checks `{specStoragePath}/{specDirName}/`.  If it exists,
- *   searches for a primary document using `config.discovery.primaryDocCandidates`,
- *   reads it, and produces metadata with `type: 'directory'`.
- *
- * Returns `null` when neither branch yields a readable spec.
- *
- * @param specStoragePath - Root directory where specs are stored.
- * @param specDirName     - Name of the spec (e.g. "spec03", "auth-module").
- * @param config          - Optional full `SpecConfig`; falls back to defaults
- *                          when omitted (discovery config resolved at call site).
- */
-function extractSpecMetadata(specStoragePath, specDirName, config) {
-    // Resolve discovery config — use provided config or the built-in defaults.
-    const discoveryConfig = config?.discovery ?? config_1.DEFAULT_CONFIG.discovery;
-    // Branch A: flat-file
-    const flatFilePath = path.join(specStoragePath, `${specDirName}.md`);
-    if (fs.existsSync(flatFilePath) && fs.statSync(flatFilePath).isFile()) {
-        const content = (0, utils_1.readFileContent)(flatFilePath);
-        if (content !== null) {
-            (0, errors_1.logDebug)('Discovered flat-file spec', { specDirName, path: flatFilePath });
-            // Build metadata manually for flat-file (no supplementary docs or
-            // commit-info in the same directory — those live alongside the flat
-            // file's parent, which is specStoragePath itself).
-            let title = specDirName;
-            const firstH1Match = content.match(/^#\s+(.*)/m);
-            if (firstH1Match && firstH1Match[1]) {
-                title = firstH1Match[1].trim().replace(/\s*SPEC\s*$/i, '');
-                if (!title)
-                    title = specDirName;
-            }
-            const subtitles = extractMarkdownHeadings(content);
-            // Attempt to read commit-info from specStoragePath for supplementary
-            // context (though flat-file specs rarely have one).
-            let commitHash = null;
-            for (const candidate of discoveryConfig.commitInfoCandidates) {
-                const ciPath = path.join(specStoragePath, candidate);
-                const ciContent = (0, utils_1.readFileContent)(ciPath);
-                if (ciContent !== null) {
-                    commitHash = (0, utils_1.parseCommitInfoMd)(ciContent);
-                    break;
-                }
-            }
-            return {
-                specId: specDirName,
-                title,
-                subtitles,
-                commitHash,
-                filePath: flatFilePath,
-                type: 'flat-file',
-            };
-        }
-    }
-    // Branch B: directory
-    const specDirPath = path.join(specStoragePath, specDirName);
-    if (fs.existsSync(specDirPath) && fs.statSync(specDirPath).isDirectory()) {
-        const primary = _findPrimaryDoc(specDirPath, specDirName, discoveryConfig.primaryDocCandidates);
-        if (primary) {
-            const [, primaryAbsPath] = primary;
-            const content = (0, utils_1.readFileContent)(primaryAbsPath);
-            if (content !== null) {
-                (0, errors_1.logDebug)('Discovered directory spec', { specDirName, primaryDoc: primaryAbsPath });
-                const meta = _buildMetadata(specDirName, content, primaryAbsPath, specDirPath, discoveryConfig);
-                return { ...meta, type: 'directory' };
-            }
-        }
-        // Directory exists but no primary doc was found or it was unreadable.
-        (0, errors_1.logWarn)('Spec directory exists but no primary doc found', {
-            specDirName,
-            specDirPath,
-            candidates: discoveryConfig.primaryDocCandidates,
-        });
-    }
-    return null;
-}
-//# sourceMappingURL=spec-extractor.js.map

package/dist/spec/mining/spec-extractor.js.map

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

package/dist/spec/utils.d.ts

@@ -1,167 +0,0 @@
-/**
- * Spec utility functions — replaces `file_utils.py`, `meta.py`, and
- * `truncate.py` from Python Commit4Spec.
- *
- * Covers file I/O, meta.json read/write, text/diff truncation, and budget
- * computation. All functions are synchronous and use Node.js built-ins.
- *
- * @module spec/utils
- */
-export interface SpecEntry {
-    specId: string;
-    entryType: 'directory' | 'file';
-    path: string;
-}
-export interface SpecMeta {
-    repoPath: string;
-    specStoragePath: string;
-    currentCommitID?: string;
-    createdAt?: string;
-    updatedAt: string;
-}
-export interface BudgetProfile {
-    tier: 'tiny' | 'small' | 'medium' | 'large' | 'vlarge';
-    maxFragments: number;
-    maxContents: number;
-    contentBudget: number;
-}
-/** Root directory for spec data, relative to the repository root. */
-export declare const SPEC_DATA_DIR = ".homegraph/commit4spec";
-/**
- * Read a UTF-8 file synchronously.
- *
- * Returns `null` for ENOENT (not found), EISDIR (is a directory), or EACCES
- * (permission denied). Other errors propagate.
- */
-export declare function readFileContent(filePath: string): string | null;
-/**
- * Write a UTF-8 file synchronously, creating parent directories as needed.
- *
- * Parent directories are created with `fs.mkdirSync({ recursive: true })`.
- * If the parent exists but is not a directory the underlying error propagates.
- */
-export declare function writeFileContent(filePath: string, content: string): void;
-/**
- * Parse commit-info.md content for a commit hash.
- *
- * Searches line by line for one of:
- * - `commit: HASH`
- * - `commit-id: HASH`
- * - `commit_id: HASH`
- * - a bare 40-char hex hash on its own line
- *
- * Returns the first matched hash (7–40 hex chars), or `null` if no hash is
- * found. Empty or whitespace-only input returns `null`.
- */
-export declare function parseCommitInfoMd(content: string): string | null;
-/**
- * Discover specs in a storage directory.
- *
- * A "spec" is any `.md` file OR any subdirectory. For `.md` files the
- * `specId` is the basename without the extension. For subdirectories the
- * `specId` is the directory name.
- *
- * Returns an empty array when `specStoragePath` does not exist or is not a
- * directory.
- */
-export declare function discoverSpecs(specStoragePath: string): SpecEntry[];
-/**
- * Resolve the database path.
- *
- * Priority:
- * 1. If `explicitDbPath` is given, return it as-is (no side effects).
- * 2. If `repoPath` is given, default to `{repoPath}/${SPEC_DATA_DIR}/commit4spec.db`
- *    and ensure `${SPEC_DATA_DIR}/.gitignore` exists containing `"*"`.
- * 3. If neither is given, return `"./commit4spec.db"`.
- */
-export declare function resolveDbPath(repoPath?: string, explicitDbPath?: string): string;
-/**
- * Read `${SPEC_DATA_DIR}/meta.json` from `repoPath`.
- *
- * Returns `null` when the file is missing, unreadable, or contains invalid
- * JSON or a JSON value that is not a plain object.
- */
-export declare function readMeta(repoPath: string): SpecMeta | null;
-/**
- * Write `${SPEC_DATA_DIR}/meta.json` to `repoPath`.
- *
- * If existing meta has a `createdAt` field it is preserved; otherwise a new
- * ISO-8601 timestamp is generated. `updatedAt` is always set to the current
- * time. The `${SPEC_DATA_DIR}` directory is created if it does not exist.
- *
- * Returns the full `SpecMeta` that was written.
- */
-export declare function writeMeta(repoPath: string, specStoragePath: string, currentCommitID?: string): SpecMeta;
-/**
- * Truncate a unified diff at a sensible boundary.
- *
- * The algorithm prefers semantic boundaries to keep diffs readable:
- *
- * 1. If the diff is shorter than `maxChars` (default 3800), return it unchanged.
- * 2. Try: find the **last** `@@` hunk header in the trailing 50% portion of
- *    the diff and cut right before it.
- * 3. Fallback: find the **last** newline in the trailing 80% portion and cut
- *    after it.
- * 4. Hard fallback: cut exactly at `maxChars`.
- *
- * Always appends `"  …(truncated)"` when truncation occurs.
- *
- * @param diff    - The unified diff text to truncate.
- * @param maxChars - Maximum allowed characters (including suffix). Default 3800.
- * @returns The (possibly truncated) diff text.
- */
-export declare function truncateCodeDiff(diff: string, maxChars?: number): string;
-/**
- * Truncate plain text with newline-awareness.
- *
- * When the text is longer than `maxChars`, it is cut at the last newline
- * found before `maxChars` (minus the suffix length). If no suitable newline
- * exists, a hard cut is made.
- *
- * The suffix `"  …(truncated)"` is appended only when truncation occurs.
- *
- * @param text     - The text to truncate.
- * @param maxChars - Maximum allowed characters (including suffix).
- * @returns The (possibly truncated) text.
- */
-export declare function truncateText(text: string, maxChars: number): string;
-/**
- * Truncate a subtitles array.
- *
- * 1. If the array has more than `maxEntries`, it is sliced to `maxEntries`.
- * 2. Each remaining entry that exceeds `maxChars` is individually truncated
- *    via `truncateText`.
- *
- * Entries that already fit within both limits are left unchanged.
- *
- * @param subtitles  - Array of subtitle strings.
- * @param maxChars   - Maximum characters per entry (including suffix).
- * @param maxEntries - Maximum number of entries to keep.
- * @returns The truncated subtitles array (always a new array).
- */
-export declare function truncateSubtitles(subtitles: string[], maxChars: number, maxEntries: number): string[];
-/**
- * Compute a budget profile based on spec and optional fragment counts.
- *
- * The profile determines how many fragments, contents, and characters the
- * pipeline should budget when building LLM prompts. Higher counts produce
- * tighter budgets to keep prompts manageable.
- *
- * Thresholds (matching `truncate.py:38-57`):
- *
- * | specCount | tier    | maxFragments | maxContents | contentBudget |
- * |-----------|---------|--------------|-------------|---------------|
- * | ≤ 3       | tiny    | 12           | 16          | 48000         |
- * | ≤ 8       | small   | 10           | 14          | 40000         |
- * | ≤ 15      | medium  | 8            | 12          | 32000         |
- * | ≤ 30      | large   | 6            | 10          | 24000         |
- * | > 30      | vlarge  | 0            | 0           | 16000         |
- *
- * The `vlarge` tier disables fragment/contents inclusion entirely (0 values).
- *
- * @param specCount     - Number of specs in the knowledge graph.
- * @param fragmentCount - (Unused) reserved for future per-fragment weighting.
- * @returns The budget profile for the given scale.
- */
-export declare function computeBudgetProfile(specCount: number, _fragmentCount?: number): BudgetProfile;
-//# sourceMappingURL=utils.d.ts.map

package/dist/spec/utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/spec/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,WAAW,GAAG,MAAM,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,qEAAqE;AACrE,eAAO,MAAM,aAAa,2BAA2B,CAAC;AAStD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAMxE;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuBhE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,EAAE,CA6BlE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAiChF;AAMD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CA8C1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,eAAe,CAAC,EAAE,MAAM,GACvB,QAAQ,CAyBV;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAa,GAAG,MAAM,CA6C9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBnE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAMV;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB,aAAa,CAcf"}