ai-prompt-guide-mcp 1.0.0

package/dist/shared/path-utilities.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Path manipulation utilities
+ */
+/**
+ * Convert a file system path to a namespace
+ */
+export declare function pathToNamespace(docPath: string): string;
+/**
+ * Convert a document path to a slug
+ * Enhanced to support hierarchical path-to-slug conversion
+ */
+export declare function pathToSlug(docPath: string): string;
+//# sourceMappingURL=path-utilities.d.ts.map

package/dist/shared/path-utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utilities.d.ts","sourceRoot":"","sources":["../../src/shared/path-utilities.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAiBvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAalD"}

package/dist/shared/path-utilities.js

@@ -0,0 +1,39 @@
+/**
+ * Path manipulation utilities
+ */
+/**
+ * Convert a file system path to a namespace
+ */
+export function pathToNamespace(docPath) {
+    // Convert document path to namespace (e.g., "/api/specs/auth.md" → "api/specs")
+    const parts = docPath.split('/').filter(part => part !== '' && part !== '.');
+    if (parts.length === 0) {
+        return 'root';
+    }
+    // Remove .md extension from the last part if it's a file
+    const lastPart = parts[parts.length - 1];
+    // eslint-disable-next-line @typescript-eslint/prefer-optional-chain
+    if (lastPart != null && lastPart.endsWith('.md')) {
+        parts.pop(); // Remove the file part to get folder namespace
+    }
+    // Return 'root' for root-level documents instead of empty string
+    const namespace = parts.join('/');
+    return namespace === '' ? 'root' : namespace;
+}
+/**
+ * Convert a document path to a slug
+ * Enhanced to support hierarchical path-to-slug conversion
+ */
+export function pathToSlug(docPath) {
+    const parts = docPath.split('/').filter(part => part !== '' && part !== '.');
+    if (parts.length === 0) {
+        return '';
+    }
+    const fileName = parts[parts.length - 1];
+    // eslint-disable-next-line @typescript-eslint/prefer-optional-chain
+    if (fileName != null && fileName.endsWith('.md')) {
+        return fileName.slice(0, -3); // Remove .md extension
+    }
+    return fileName ?? '';
+}
+//# sourceMappingURL=path-utilities.js.map

package/dist/shared/path-utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utilities.js","sourceRoot":"","sources":["../../src/shared/path-utilities.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,gFAAgF;IAChF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC;IAC7E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,yDAAyD;IACzD,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,oEAAoE;IACpE,IAAI,QAAQ,IAAI,IAAI,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,+CAA+C;IAC9D,CAAC;IAED,iEAAiE;IACjE,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC;IAC7E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,oEAAoE;IACpE,IAAI,QAAQ,IAAI,IAAI,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,uBAAuB;IACvD,CAAC;IAED,OAAO,QAAQ,IAAI,EAAE,CAAC;AACxB,CAAC"}

package/dist/shared/reference-extractor.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Reference extraction system for unified @reference handling
+ *
+ * This module provides a standardized approach to extracting and normalizing
+ * @references from document content, replacing scattered reference/link handling
+ * throughout the codebase.
+ *
+ * Key Features:
+ * - Regex-based extraction of all @reference formats
+ * - Path normalization with .md extension handling
+ * - Context-aware relative path resolution
+ * - Type-safe interfaces for structured reference data
+ */
+/**
+ * Normalized reference with resolved paths and optional section targeting
+ *
+ * @example Basic document reference
+ * ```typescript
+ * {
+ *   originalRef: '@/api/auth',
+ *   resolvedPath: '/api/auth.md',
+ *   documentPath: '/api/auth.md',
+ *   sectionSlug: undefined
+ * }
+ * ```
+ *
+ * @example Section-targeted reference
+ * ```typescript
+ * {
+ *   originalRef: '@/api/auth.md#overview',
+ *   resolvedPath: '/api/auth.md#overview',
+ *   documentPath: '/api/auth.md',
+ *   sectionSlug: 'overview'
+ * }
+ * ```
+ */
+export interface NormalizedReference {
+    /** Original @reference text as found in content */
+    readonly originalRef: string;
+    /** Fully resolved path with section if specified */
+    readonly resolvedPath: string;
+    /** Document path portion only (no section) */
+    readonly documentPath: string;
+    /** Section slug if reference targets a specific section */
+    readonly sectionSlug?: string | undefined;
+}
+/**
+ * Reference extraction and normalization system
+ *
+ * Provides unified handling of @reference extraction and path resolution
+ * across the document management system.
+ */
+export declare class ReferenceExtractor {
+    /** Regex pattern for extracting @references in all supported formats */
+    private static readonly REFERENCE_PATTERN;
+    /**
+     * Extract all @references from content using standardized regex pattern
+     *
+     * Supports formats:
+     * - @#section (within-document)
+     * - @/path/doc.md (cross-document)
+     * - @/path/doc (cross-document, will add .md)
+     * - @/path/doc.md#section (cross-document with section)
+     *
+     * @param content - Document content to extract references from
+     * @returns Array of reference strings found in content
+     *
+     * @example Basic extraction
+     * ```typescript
+     * const extractor = new ReferenceExtractor();
+     * const refs = extractor.extractReferences(
+     *   'See @/api/auth.md#overview and @#local-section for details.'
+     * );
+     * // Returns: ['@/api/auth.md#overview', '@#local-section']
+     * ```
+     */
+    extractReferences(content: string): string[];
+    /**
+     * Normalize references to resolved paths with context-aware resolution
+     *
+     * Handles path resolution, .md extension addition, and section parsing
+     * relative to the provided context document path.
+     *
+     * @param refs - Array of reference strings to normalize
+     * @param contextPath - Current document path for relative resolution
+     * @returns Array of normalized reference objects
+     *
+     * @example Reference normalization
+     * ```typescript
+     * const extractor = new ReferenceExtractor();
+     * const normalized = extractor.normalizeReferences(
+     *   ['@/api/auth', '@#overview', '@/docs/guide.md#setup'],
+     *   '/current/doc.md'
+     * );
+     * ```
+     */
+    normalizeReferences(refs: string[], contextPath: string): NormalizedReference[];
+    /**
+     * Normalize a single reference string to structured reference data
+     *
+     * @param ref - Reference string to normalize
+     * @param contextPath - Current document path for resolution
+     * @returns Normalized reference object
+     */
+    private normalizeReference;
+    /**
+     * Normalize document path by ensuring absolute path and .md extension
+     *
+     * @param docPath - Document path to normalize
+     * @returns Normalized absolute document path
+     */
+    private normalizeDocumentPath;
+    /**
+     * Ensure path starts with / for absolute addressing
+     *
+     * @param path - Path to make absolute
+     * @returns Absolute path starting with /
+     */
+    private ensureAbsolutePath;
+}
+//# sourceMappingURL=reference-extractor.d.ts.map

package/dist/shared/reference-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-extractor.d.ts","sourceRoot":"","sources":["../../src/shared/reference-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,wEAAwE;IACxE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAgE;IAEzG;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAsB5C;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,mBAAmB,EAAE;IA8B/E;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAuD1B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;CAe3B"}

package/dist/shared/reference-extractor.js

@@ -0,0 +1,195 @@
+/**
+ * Reference extraction system for unified @reference handling
+ *
+ * This module provides a standardized approach to extracting and normalizing
+ * @references from document content, replacing scattered reference/link handling
+ * throughout the codebase.
+ *
+ * Key Features:
+ * - Regex-based extraction of all @reference formats
+ * - Path normalization with .md extension handling
+ * - Context-aware relative path resolution
+ * - Type-safe interfaces for structured reference data
+ */
+import { titleToSlug } from '../slug.js';
+/**
+ * Reference extraction and normalization system
+ *
+ * Provides unified handling of @reference extraction and path resolution
+ * across the document management system.
+ */
+export class ReferenceExtractor {
+    /** Regex pattern for extracting @references in all supported formats */
+    static REFERENCE_PATTERN = /@(?:\/[^\s\]),;:!?]+(?:#[^\s\]),;:!?]*)?|#[^\s\]),;:!?]*)/g;
+    /**
+     * Extract all @references from content using standardized regex pattern
+     *
+     * Supports formats:
+     * - @#section (within-document)
+     * - @/path/doc.md (cross-document)
+     * - @/path/doc (cross-document, will add .md)
+     * - @/path/doc.md#section (cross-document with section)
+     *
+     * @param content - Document content to extract references from
+     * @returns Array of reference strings found in content
+     *
+     * @example Basic extraction
+     * ```typescript
+     * const extractor = new ReferenceExtractor();
+     * const refs = extractor.extractReferences(
+     *   'See @/api/auth.md#overview and @#local-section for details.'
+     * );
+     * // Returns: ['@/api/auth.md#overview', '@#local-section']
+     * ```
+     */
+    extractReferences(content) {
+        // Input validation
+        if (typeof content !== 'string') {
+            return [];
+        }
+        // Extract all matches using regex
+        const matches = content.match(ReferenceExtractor.REFERENCE_PATTERN);
+        if (matches == null) {
+            return [];
+        }
+        // Clean up trailing punctuation and return unique references
+        const cleanedMatches = matches.map(match => {
+            // Remove trailing punctuation that might be captured
+            return match.replace(/[.!?]+$/, '');
+        });
+        return [...new Set(cleanedMatches)];
+    }
+    /**
+     * Normalize references to resolved paths with context-aware resolution
+     *
+     * Handles path resolution, .md extension addition, and section parsing
+     * relative to the provided context document path.
+     *
+     * @param refs - Array of reference strings to normalize
+     * @param contextPath - Current document path for relative resolution
+     * @returns Array of normalized reference objects
+     *
+     * @example Reference normalization
+     * ```typescript
+     * const extractor = new ReferenceExtractor();
+     * const normalized = extractor.normalizeReferences(
+     *   ['@/api/auth', '@#overview', '@/docs/guide.md#setup'],
+     *   '/current/doc.md'
+     * );
+     * ```
+     */
+    normalizeReferences(refs, contextPath) {
+        // Input validation
+        if (!Array.isArray(refs)) {
+            return [];
+        }
+        if (typeof contextPath !== 'string' || contextPath.trim() === '') {
+            throw new Error('Context path is required for reference normalization');
+        }
+        const normalizedContextPath = this.ensureAbsolutePath(contextPath);
+        const results = [];
+        for (const ref of refs) {
+            if (typeof ref !== 'string' || ref.trim() === '') {
+                continue;
+            }
+            try {
+                const normalized = this.normalizeReference(ref, normalizedContextPath);
+                results.push(normalized);
+            }
+            catch (error) {
+                // Skip invalid references but continue processing others
+                console.warn(`Failed to normalize reference "${ref}":`, error);
+            }
+        }
+        return results;
+    }
+    /**
+     * Normalize a single reference string to structured reference data
+     *
+     * @param ref - Reference string to normalize
+     * @param contextPath - Current document path for resolution
+     * @returns Normalized reference object
+     */
+    normalizeReference(ref, contextPath) {
+        const trimmed = ref.trim();
+        // Remove @ prefix for processing
+        if (!trimmed.startsWith('@')) {
+            throw new Error(`Invalid reference format: ${ref} (must start with @)`);
+        }
+        const refContent = trimmed.slice(1);
+        // Handle within-document references (@#section)
+        if (refContent.startsWith('#')) {
+            const sectionSlug = refContent.slice(1);
+            return {
+                originalRef: ref,
+                resolvedPath: `${contextPath}#${sectionSlug}`,
+                documentPath: contextPath,
+                sectionSlug: sectionSlug !== '' ? titleToSlug(sectionSlug) : undefined
+            };
+        }
+        // Handle cross-document references (@/path/doc or @/path/doc#section)
+        const hashIndex = refContent.indexOf('#');
+        let documentPath;
+        let sectionSlug;
+        if (hashIndex === -1) {
+            // No section specified
+            documentPath = refContent;
+            sectionSlug = undefined;
+        }
+        else {
+            // Section specified
+            documentPath = refContent.slice(0, hashIndex);
+            const sectionPart = refContent.slice(hashIndex + 1);
+            sectionSlug = sectionPart !== '' ? titleToSlug(sectionPart) : undefined;
+        }
+        // Normalize document path
+        const normalizedDocPath = this.normalizeDocumentPath(documentPath);
+        // Build resolved path
+        const resolvedPath = sectionSlug != null
+            ? `${normalizedDocPath}#${sectionSlug}`
+            : normalizedDocPath;
+        return {
+            originalRef: ref,
+            resolvedPath,
+            documentPath: normalizedDocPath,
+            sectionSlug
+        };
+    }
+    /**
+     * Normalize document path by ensuring absolute path and .md extension
+     *
+     * @param docPath - Document path to normalize
+     * @returns Normalized absolute document path
+     */
+    normalizeDocumentPath(docPath) {
+        if (docPath === '') {
+            throw new Error('Document path cannot be empty');
+        }
+        // Ensure absolute path
+        let normalized = this.ensureAbsolutePath(docPath);
+        // Add .md extension if missing
+        if (!normalized.endsWith('.md')) {
+            normalized = `${normalized}.md`;
+        }
+        return normalized;
+    }
+    /**
+     * Ensure path starts with / for absolute addressing
+     *
+     * @param path - Path to make absolute
+     * @returns Absolute path starting with /
+     */
+    ensureAbsolutePath(path) {
+        const trimmed = path.trim();
+        if (trimmed === '') {
+            return '/';
+        }
+        // Ensure path starts with /
+        if (!trimmed.startsWith('/')) {
+            return `/${trimmed}`;
+        }
+        // Remove duplicate slashes
+        return trimmed.replace(/\/+/g, '/');
+    }
+}
+//# sourceMappingURL=reference-extractor.js.map

package/dist/shared/reference-extractor.js.map

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

package/dist/shared/reference-loader.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Reference loading system for hierarchical content loading
+ *
+ * This module provides recursive loading of documents and their references
+ * to build hierarchical content structures with cycle detection and depth limits.
+ *
+ * Key Features:
+ * - Recursive reference loading with depth control
+ * - Cycle detection to prevent infinite loops
+ * - Hierarchical content organization
+ * - Integration with existing DocumentManager
+ * - Namespace-aware content loading
+ */
+import type { DocumentManager } from '../document-manager.js';
+import type { NormalizedReference } from './reference-extractor.js';
+/**
+ * Hierarchical content structure for nested reference loading
+ *
+ * @example Basic hierarchical content
+ * ```typescript
+ * {
+ *   path: '/api/auth.md',
+ *   title: 'Authentication Guide',
+ *   content: 'Authentication overview...',
+ *   depth: 0,
+ *   namespace: 'api',
+ *   children: [
+ *     {
+ *       path: '/api/tokens.md',
+ *       title: 'Token Management',
+ *       content: 'Token details...',
+ *       depth: 1,
+ *       namespace: 'api',
+ *       children: []
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export interface HierarchicalContent {
+    /** Document path */
+    readonly path: string;
+    /** Document title from metadata */
+    readonly title: string;
+    /** Document content (full or section-specific) */
+    readonly content: string;
+    /** Nesting depth in hierarchy (0 = root) */
+    readonly depth: number;
+    /** Document namespace for organization */
+    readonly namespace: string;
+    /** Nested referenced documents */
+    readonly children: HierarchicalContent[];
+}
+/**
+ * Reference loading system with hierarchical content organization
+ *
+ * Provides recursive loading of documents and their references
+ * with intelligent cycle detection and depth management.
+ */
+export declare class ReferenceLoader {
+    private readonly extractor;
+    private readonly MAX_TOTAL_NODES;
+    private readonly DEFAULT_TIMEOUT_MS;
+    constructor();
+    /**
+     * Load references recursively to build hierarchical content structure
+     *
+     * Processes normalized references and loads their target documents,
+     * recursively processing nested references up to specified depth.
+     *
+     * @param refs - Array of normalized references to load
+     * @param manager - DocumentManager for loading documents
+     * @param maxDepth - Maximum recursion depth (default: 3)
+     * @param currentDepth - Current recursion depth (default: 0)
+     * @param visitedPaths - Set of visited paths for cycle detection (internal use)
+     * @param totalNodesLoaded - Node count tracker across all branches (internal use)
+     * @param startTime - Operation start timestamp for timeout tracking (internal use)
+     * @returns Promise resolving to hierarchical content array
+     *
+     * @example Basic reference loading
+     * ```typescript
+     * const loader = new ReferenceLoader();
+     * const extractor = new ReferenceExtractor();
+     *
+     * const refs = extractor.normalizeReferences(
+     *   ['@/api/auth.md', '@/api/tokens.md'],
+     *   '/current/doc.md'
+     * );
+     *
+     * const hierarchy = await loader.loadReferences(refs, manager, 2);
+     * ```
+     */
+    loadReferences(refs: NormalizedReference[], manager: DocumentManager, maxDepth?: number, currentDepth?: number, visitedPaths?: Set<string>, totalNodesLoaded?: {
+        count: number;
+    }, startTime?: number): Promise<HierarchicalContent[]>;
+    /**
+     * Load a single reference with cycle detection
+     *
+     * @param ref - Normalized reference to load
+     * @param manager - DocumentManager for loading
+     * @param maxDepth - Maximum recursion depth
+     * @param currentDepth - Current recursion depth
+     * @param visitedPaths - Set of already visited paths for cycle detection
+     * @param nodeTracker - Node count tracker across all branches
+     * @param startTime - Operation start timestamp for timeout tracking
+     * @returns Promise resolving to hierarchical content or null if skipped
+     */
+    private loadSingleReference;
+    /**
+     * Load references from content string with automatic extraction
+     *
+     * Convenience method that combines reference extraction and loading
+     * in a single operation.
+     *
+     * @param content - Content to extract references from
+     * @param contextPath - Context document path for resolution
+     * @param manager - DocumentManager for loading
+     * @param maxDepth - Maximum recursion depth (default: 3)
+     * @returns Promise resolving to hierarchical content array
+     *
+     * @example Direct content loading
+     * ```typescript
+     * const loader = new ReferenceLoader();
+     * const content = 'See @/api/auth.md and @/api/tokens.md for details.';
+     *
+     * const hierarchy = await loader.loadReferencesFromContent(
+     *   content,
+     *   '/current/doc.md',
+     *   manager
+     * );
+     * ```
+     */
+    loadReferencesFromContent(content: string, contextPath: string, manager: DocumentManager, maxDepth?: number): Promise<HierarchicalContent[]>;
+    /**
+     * Get flattened list of all documents in hierarchy
+     *
+     * Utility method to extract all document paths from hierarchical content
+     * for analysis or batch operations.
+     *
+     * @param hierarchy - Hierarchical content array
+     * @returns Array of document paths in depth-first order
+     *
+     * @example Flatten hierarchy
+     * ```typescript
+     * const hierarchy = await loader.loadReferences(refs, manager);
+     * const allPaths = loader.flattenHierarchy(hierarchy);
+     * // Returns: ['/api/auth.md', '/api/tokens.md', '/api/errors.md']
+     * ```
+     */
+    flattenHierarchy(hierarchy: HierarchicalContent[]): string[];
+    /**
+     * Get hierarchy statistics for analysis
+     *
+     * @param hierarchy - Hierarchical content array
+     * @returns Statistics about the hierarchy structure
+     */
+    getHierarchyStats(hierarchy: HierarchicalContent[]): {
+        totalDocuments: number;
+        maxDepth: number;
+        namespaces: string[];
+    };
+}
+//# sourceMappingURL=reference-loader.d.ts.map

package/dist/shared/reference-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-loader.d.ts","sourceRoot":"","sources":["../../src/shared/reference-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAQpE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,mBAAmB;IAClC,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CAC1C;AAED;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;;IAM5C;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,cAAc,CAClB,IAAI,EAAE,mBAAmB,EAAE,EAC3B,OAAO,EAAE,eAAe,EACxB,QAAQ,GAAE,MAAU,EACpB,YAAY,GAAE,MAAU,EACxB,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,gBAAgB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EACpC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAqEjC;;;;;;;;;;;OAWG;YACW,mBAAmB;IA8FjC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,yBAAyB,CAC7B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,eAAe,EACxB,QAAQ,GAAE,MAAU,GACnB,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAWjC;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,SAAS,EAAE,mBAAmB,EAAE,GAAG,MAAM,EAAE;IAc5D;;;;;OAKG;IACH,iBAAiB,CAAC,SAAS,EAAE,mBAAmB,EAAE,GAAG;QACnD,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,EAAE,CAAC;KACtB;CAsBF"}