@grafema/util 0.3.0-beta

package/dist/core/CoverageAnalyzer.js

@@ -0,0 +1,199 @@
+/**
+ * CoverageAnalyzer - Calculates analysis coverage for a project
+ *
+ * Determines which files in a project have been analyzed and categorizes
+ * files into three groups:
+ * - Analyzed: Files that appear as MODULE nodes in the graph
+ * - Unsupported: Files with extensions that no indexer can handle
+ * - Unreachable: Files with supported extensions but not in the graph
+ *
+ * Usage:
+ *   const analyzer = new CoverageAnalyzer(graphBackend, '/path/to/project');
+ *   const result = await analyzer.analyze();
+ */
+import { readdirSync, existsSync, lstatSync } from 'fs';
+import { join, relative, extname } from 'path';
+/**
+ * Supported file extensions by language
+ */
+const JS_SUPPORTED = ['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx'];
+const RUST_SUPPORTED = ['.rs'];
+const SUPPORTED_EXTENSIONS = new Set([...JS_SUPPORTED, ...RUST_SUPPORTED]);
+/**
+ * Known code file extensions (for scanning)
+ * Files with these extensions are considered source code
+ */
+const CODE_EXTENSIONS = new Set([
+    // Supported
+    ...JS_SUPPORTED,
+    ...RUST_SUPPORTED,
+    // Unsupported but tracked
+    '.go', '.kt', '.java', '.py', '.rb', '.php', '.c', '.cpp', '.h', '.hpp',
+    '.cs', '.swift', '.scala', '.sql', '.graphql', '.gql',
+]);
+/**
+ * Directories to always skip during scanning
+ */
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.grafema',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    '.next',
+    '.nuxt',
+    '__pycache__',
+    'target', // Rust
+    'vendor',
+]);
+/**
+ * CoverageAnalyzer calculates what percentage of a codebase has been analyzed.
+ */
+export class CoverageAnalyzer {
+    graph;
+    projectPath;
+    constructor(graph, projectPath) {
+        this.graph = graph;
+        this.projectPath = projectPath;
+    }
+    /**
+     * Analyze the project and return coverage statistics
+     */
+    async analyze() {
+        // Step 1: Get all MODULE nodes from the graph
+        const analyzedFiles = await this.getAnalyzedFiles();
+        const analyzedSet = new Set(analyzedFiles);
+        // Step 2: Scan project for all code files
+        const allCodeFiles = this.scanProjectFiles();
+        // Step 3: Categorize files
+        const unsupportedByExt = {};
+        const unreachableByExt = {};
+        const unreachableFiles = [];
+        for (const file of allCodeFiles) {
+            if (analyzedSet.has(file)) {
+                continue; // Already analyzed
+            }
+            const ext = extname(file).toLowerCase();
+            if (SUPPORTED_EXTENSIONS.has(ext)) {
+                // Supported but not in graph = unreachable
+                unreachableFiles.push(file);
+                if (!unreachableByExt[ext]) {
+                    unreachableByExt[ext] = [];
+                }
+                unreachableByExt[ext].push(file);
+            }
+            else {
+                // Not supported = unsupported
+                if (!unsupportedByExt[ext]) {
+                    unsupportedByExt[ext] = [];
+                }
+                unsupportedByExt[ext].push(file);
+            }
+        }
+        // Calculate counts
+        const unsupportedCount = Object.values(unsupportedByExt)
+            .reduce((sum, files) => sum + files.length, 0);
+        const unreachableCount = unreachableFiles.length;
+        const analyzedCount = analyzedFiles.length;
+        const total = analyzedCount + unsupportedCount + unreachableCount;
+        // Calculate percentages (handle division by zero)
+        const percentages = {
+            analyzed: total > 0 ? Math.round((analyzedCount / total) * 100) : 0,
+            unsupported: total > 0 ? Math.round((unsupportedCount / total) * 100) : 0,
+            unreachable: total > 0 ? Math.round((unreachableCount / total) * 100) : 0,
+        };
+        return {
+            projectPath: this.projectPath,
+            total,
+            analyzed: {
+                count: analyzedCount,
+                files: analyzedFiles,
+            },
+            unsupported: {
+                count: unsupportedCount,
+                byExtension: unsupportedByExt,
+            },
+            unreachable: {
+                count: unreachableCount,
+                files: unreachableFiles,
+                byExtension: unreachableByExt,
+            },
+            percentages,
+        };
+    }
+    /**
+     * Get list of analyzed files from the graph (MODULE nodes)
+     */
+    async getAnalyzedFiles() {
+        const files = [];
+        // Use queryNodes with type: 'MODULE'
+        for await (const node of this.graph.queryNodes({ type: 'MODULE' })) {
+            if (node.file) {
+                // Store relative path for consistency
+                const relativePath = node.file.startsWith(this.projectPath)
+                    ? relative(this.projectPath, node.file)
+                    : node.file;
+                files.push(relativePath);
+            }
+        }
+        return files;
+    }
+    /**
+     * Scan project directory for all code files
+     * Respects common ignore patterns (node_modules, .git, etc.)
+     */
+    scanProjectFiles() {
+        const files = [];
+        this.walkDirectory(this.projectPath, files);
+        return files;
+    }
+    /**
+     * Recursively walk directory and collect code files
+     */
+    walkDirectory(dir, files, depth = 0) {
+        // Safety: limit recursion depth
+        if (depth > 20)
+            return;
+        if (!existsSync(dir))
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return; // Skip directories we can't read
+        }
+        for (const entry of entries) {
+            // Skip hidden files and directories
+            if (entry.startsWith('.'))
+                continue;
+            // Skip known non-source directories
+            if (SKIP_DIRS.has(entry))
+                continue;
+            const fullPath = join(dir, entry);
+            // Skip symlinks to avoid infinite loops
+            try {
+                const stat = lstatSync(fullPath);
+                if (stat.isSymbolicLink())
+                    continue;
+                if (stat.isDirectory()) {
+                    this.walkDirectory(fullPath, files, depth + 1);
+                }
+                else if (stat.isFile()) {
+                    const ext = extname(entry).toLowerCase();
+                    if (CODE_EXTENSIONS.has(ext)) {
+                        // Store relative path
+                        files.push(relative(this.projectPath, fullPath));
+                    }
+                }
+            }
+            catch {
+                // Skip files we can't stat
+                continue;
+            }
+        }
+    }
+}
+//# sourceMappingURL=CoverageAnalyzer.js.map

package/dist/core/CoverageAnalyzer.js.map

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

package/dist/core/FileExplainer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * FileExplainer - Show what nodes exist in a file for discovery
+ *
+ * Purpose: Help users discover what nodes exist in the graph for a file,
+ * displaying semantic IDs so users can query them.
+ *
+ * This addresses the core UX problem: users can't find nodes because
+ * semantic IDs are opaque (e.g., "src/app.ts->fetchData->try#0->VARIABLE->response").
+ * This tool shows what's in the graph so users know what they can query.
+ *
+ * @see _tasks/REG-177/006-don-revised-plan.md for design rationale
+ */
+import type { GraphBackend, BaseNodeRecord } from '@grafema/types';
+/**
+ * Result of explaining a file's graph contents
+ */
+export interface FileExplainResult {
+    /** The file path that was explained */
+    file: string;
+    /** Whether the file has been analyzed */
+    status: 'ANALYZED' | 'NOT_ANALYZED';
+    /** All nodes in the graph for this file, enhanced with context */
+    nodes: EnhancedNode[];
+    /** Node counts grouped by type */
+    byType: Record<string, number>;
+    /** Total number of nodes in the file */
+    totalCount: number;
+}
+/**
+ * A node record enhanced with scope context information.
+ *
+ * The context field provides human-readable information about
+ * where the node appears (e.g., "inside try block", "catch parameter").
+ */
+export interface EnhancedNode extends BaseNodeRecord {
+    /** Human-readable context about the node's scope */
+    context?: string;
+}
+/**
+ * FileExplainer class - explains what nodes exist in a file's graph.
+ *
+ * Use this when:
+ * - User can't find a variable/function they expect to be in the graph
+ * - User wants to understand what's been analyzed for a file
+ * - User needs semantic IDs to construct queries
+ *
+ * Example:
+ * ```typescript
+ * const explainer = new FileExplainer(graphBackend);
+ * const result = await explainer.explain('src/app.ts');
+ *
+ * if (result.status === 'NOT_ANALYZED') {
+ *   console.log('File not in graph. Run: grafema analyze');
+ * } else {
+ *   for (const node of result.nodes) {
+ *     console.log(`[${node.type}] ${node.name}`);
+ *     console.log(`  ID: ${node.id}`);
+ *     if (node.context) {
+ *       console.log(`  Context: ${node.context}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class FileExplainer {
+    private graph;
+    constructor(graph: GraphBackend);
+    /**
+     * Explain what nodes exist in the graph for a file.
+     *
+     * @param filePath - The file path to explain (relative or absolute)
+     * @returns FileExplainResult with all nodes, grouped by type, with context
+     */
+    explain(filePath: string): Promise<FileExplainResult>;
+    /**
+     * Query graph for all nodes in a file
+     *
+     * Note: The server-side file filter may not work correctly in all cases,
+     * so we also filter client-side to ensure only nodes from the requested file are returned.
+     */
+    private getNodesForFile;
+    /**
+     * Group nodes by type, counting occurrences
+     */
+    private groupByType;
+    /**
+     * Enhance nodes with human-readable scope context.
+     *
+     * Detects patterns in semantic IDs like:
+     * - "file->func->try#0->VARIABLE->x" → "inside try block"
+     * - "file->func->catch#0->VARIABLE->error" → "inside catch block"
+     */
+    private enhanceWithContext;
+    /**
+     * Detect scope context from semantic ID patterns.
+     *
+     * Returns human-readable context string or undefined if no special scope.
+     */
+    private detectScopeContext;
+}
+//# sourceMappingURL=FileExplainer.d.ts.map

package/dist/core/FileExplainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileExplainer.d.ts","sourceRoot":"","sources":["../../src/core/FileExplainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAc,MAAM,gBAAgB,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC;IACpC,kEAAkE;IAClE,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,YAAY;IAEvC;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0B3D;;;;;OAKG;YACW,eAAe;IAc7B;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;CAQ3B"}

package/dist/core/FileExplainer.js

@@ -0,0 +1,140 @@
+/**
+ * FileExplainer - Show what nodes exist in a file for discovery
+ *
+ * Purpose: Help users discover what nodes exist in the graph for a file,
+ * displaying semantic IDs so users can query them.
+ *
+ * This addresses the core UX problem: users can't find nodes because
+ * semantic IDs are opaque (e.g., "src/app.ts->fetchData->try#0->VARIABLE->response").
+ * This tool shows what's in the graph so users know what they can query.
+ *
+ * @see _tasks/REG-177/006-don-revised-plan.md for design rationale
+ */
+/**
+ * Scope patterns to detect from semantic IDs.
+ * Order matters - more specific patterns should come first.
+ */
+const SCOPE_PATTERNS = [
+    { pattern: /->catch#\d+->/, context: 'inside catch block' },
+    { pattern: /->try#\d+->/, context: 'inside try block' },
+    { pattern: /->if#\d+->/, context: 'inside conditional' },
+    { pattern: /->else#\d+->/, context: 'inside else block' },
+    { pattern: /->for#\d+->/, context: 'inside loop' },
+    { pattern: /->while#\d+->/, context: 'inside loop' },
+    { pattern: /->switch#\d+->/, context: 'inside switch' },
+];
+/**
+ * FileExplainer class - explains what nodes exist in a file's graph.
+ *
+ * Use this when:
+ * - User can't find a variable/function they expect to be in the graph
+ * - User wants to understand what's been analyzed for a file
+ * - User needs semantic IDs to construct queries
+ *
+ * Example:
+ * ```typescript
+ * const explainer = new FileExplainer(graphBackend);
+ * const result = await explainer.explain('src/app.ts');
+ *
+ * if (result.status === 'NOT_ANALYZED') {
+ *   console.log('File not in graph. Run: grafema analyze');
+ * } else {
+ *   for (const node of result.nodes) {
+ *     console.log(`[${node.type}] ${node.name}`);
+ *     console.log(`  ID: ${node.id}`);
+ *     if (node.context) {
+ *       console.log(`  Context: ${node.context}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class FileExplainer {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    /**
+     * Explain what nodes exist in the graph for a file.
+     *
+     * @param filePath - The file path to explain (relative or absolute)
+     * @returns FileExplainResult with all nodes, grouped by type, with context
+     */
+    async explain(filePath) {
+        // Query graph for all nodes in this file
+        const nodes = await this.getNodesForFile(filePath);
+        // Group by type
+        const byType = this.groupByType(nodes);
+        // Enhance with context from semantic ID parsing
+        const enhanced = this.enhanceWithContext(nodes);
+        // Sort nodes: by type, then by name
+        enhanced.sort((a, b) => {
+            const typeCompare = a.type.localeCompare(b.type);
+            if (typeCompare !== 0)
+                return typeCompare;
+            return (a.name || '').localeCompare(b.name || '');
+        });
+        return {
+            file: filePath,
+            status: nodes.length > 0 ? 'ANALYZED' : 'NOT_ANALYZED',
+            nodes: enhanced,
+            byType,
+            totalCount: nodes.length,
+        };
+    }
+    /**
+     * Query graph for all nodes in a file
+     *
+     * Note: The server-side file filter may not work correctly in all cases,
+     * so we also filter client-side to ensure only nodes from the requested file are returned.
+     */
+    async getNodesForFile(filePath) {
+        const filter = { file: filePath };
+        const nodes = [];
+        for await (const node of this.graph.queryNodes(filter)) {
+            // Client-side filter as backup (server filter may not work correctly)
+            if (node.file === filePath) {
+                nodes.push(node);
+            }
+        }
+        return nodes;
+    }
+    /**
+     * Group nodes by type, counting occurrences
+     */
+    groupByType(nodes) {
+        const counts = {};
+        for (const node of nodes) {
+            const type = node.type || 'UNKNOWN';
+            counts[type] = (counts[type] || 0) + 1;
+        }
+        return counts;
+    }
+    /**
+     * Enhance nodes with human-readable scope context.
+     *
+     * Detects patterns in semantic IDs like:
+     * - "file->func->try#0->VARIABLE->x" → "inside try block"
+     * - "file->func->catch#0->VARIABLE->error" → "inside catch block"
+     */
+    enhanceWithContext(nodes) {
+        return nodes.map((node) => {
+            const context = this.detectScopeContext(node.id);
+            return context ? { ...node, context } : { ...node };
+        });
+    }
+    /**
+     * Detect scope context from semantic ID patterns.
+     *
+     * Returns human-readable context string or undefined if no special scope.
+     */
+    detectScopeContext(semanticId) {
+        for (const { pattern, context } of SCOPE_PATTERNS) {
+            if (pattern.test(semanticId)) {
+                return context;
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=FileExplainer.js.map

package/dist/core/FileExplainer.js.map

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

package/dist/core/FileOverview.d.ts

@@ -0,0 +1,124 @@
+/**
+ * FileOverview - Get a structured overview of all entities in a file.
+ *
+ * Purpose: Show what a file contains and how its parts relate to each other.
+ * Unlike FileExplainer (which lists ALL nodes flat), FileOverview shows only
+ * meaningful entities (functions, classes, variables) with their key relationships
+ * (calls, extends, assigned-from).
+ *
+ * Unlike the context command (which shows ONE node's full neighborhood),
+ * FileOverview shows ALL entities at file level with curated edges.
+ *
+ * Use this when:
+ * - AI agent needs to understand a file before diving deeper
+ * - User wants a table-of-contents of a file with relationships
+ * - Quick orientation before using get_context on specific nodes
+ *
+ * @example
+ * ```typescript
+ * const overview = new FileOverview(backend);
+ * const result = await overview.getOverview('/abs/path/to/file.js');
+ * // result.functions[0].calls -> ["express", "Router"]
+ * ```
+ *
+ * @see REG-412
+ */
+import type { GraphBackend } from '@grafema/types';
+export interface ImportInfo {
+    id: string;
+    source: string;
+    specifiers: string[];
+}
+export interface ExportInfo {
+    id: string;
+    name: string;
+    isDefault: boolean;
+}
+export interface FunctionOverview {
+    id: string;
+    name: string;
+    line?: number;
+    async: boolean;
+    params?: string[];
+    calls: string[];
+    returnType?: string;
+    signature?: string;
+}
+export interface ClassOverview {
+    id: string;
+    name: string;
+    line?: number;
+    extends?: string;
+    exported: boolean;
+    methods: FunctionOverview[];
+}
+export interface VariableOverview {
+    id: string;
+    name: string;
+    line?: number;
+    kind: string;
+    assignedFrom?: string;
+}
+export interface FileOverviewResult {
+    file: string;
+    status: 'ANALYZED' | 'NOT_ANALYZED';
+    imports: ImportInfo[];
+    exports: ExportInfo[];
+    classes: ClassOverview[];
+    functions: FunctionOverview[];
+    variables: VariableOverview[];
+}
+export declare class FileOverview {
+    private graph;
+    constructor(graph: GraphBackend);
+    /**
+     * Get structured overview of a file's entities and relationships.
+     *
+     * @param filePath - Absolute file path (after realpath resolution)
+     * @param options - Optional: { includeEdges: boolean }
+     * @returns FileOverviewResult
+     */
+    getOverview(filePath: string, options?: {
+        includeEdges?: boolean;
+    }): Promise<FileOverviewResult>;
+    /**
+     * Find the MODULE node for the given file path.
+     * Complexity: O(1) - server-side filtered query
+     */
+    private findModuleNode;
+    /**
+     * Get direct children of MODULE node that are "interesting" types.
+     * Complexity: O(C) where C = total CONTAINS edges from MODULE
+     */
+    private getTopLevelEntities;
+    /**
+     * Build ImportInfo from an IMPORT node.
+     * Data read directly from node record fields.
+     * Complexity: O(1)
+     */
+    private buildImportInfo;
+    /**
+     * Build ExportInfo from an EXPORT node.
+     * Data read directly from node record fields.
+     * Complexity: O(1)
+     */
+    private buildExportInfo;
+    /**
+     * Build FunctionOverview from a FUNCTION node.
+     * When includeEdges=true, resolves calls via findCallsInFunction.
+     * Complexity: Without edges O(1), with edges O(S + C)
+     */
+    private buildFunctionOverview;
+    /**
+     * Build ClassOverview from a CLASS node.
+     * Fetches EXTENDS edge and methods via CONTAINS.
+     * Complexity: Without edges O(M), with edges O(M * (S + C))
+     */
+    private buildClassOverview;
+    /**
+     * Build VariableOverview from a VARIABLE or CONSTANT node.
+     * Complexity: Without edges O(1), with edges O(1)
+     */
+    private buildVariableOverview;
+}
+//# sourceMappingURL=FileOverview.d.ts.map

package/dist/core/FileOverview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileOverview.d.ts","sourceRoot":"","sources":["../../src/core/FileOverview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAA8B,MAAM,gBAAgB,CAAC;AAM/E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC;IACpC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAaD,qBAAa,YAAY;IACX,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,YAAY;IAEvC;;;;;;OAMG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAO,GACvC,OAAO,CAAC,kBAAkB,CAAC;IAgE9B;;;OAGG;YACW,cAAc;IAY5B;;;OAGG;YACW,mBAAmB;IAkBjC;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAmBvB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;OAIG;YACW,qBAAqB;IA2DnC;;;;OAIG;YACW,kBAAkB;IAoDhC;;;OAGG;YACW,qBAAqB;CA0BpC"}