specweave 0.22.13 → 0.23.0

package/dist/src/living-docs/id-registry.js

@@ -0,0 +1,230 @@
+/**
+ * ID Registry - Atomic Feature ID registration with collision detection
+ *
+ * Provides thread-safe ID registration using file-based locking to prevent
+ * race conditions during concurrent imports.
+ *
+ * Features:
+ * - File-based locking for atomic updates
+ * - Collision detection (checks both FS-XXX and FS-XXXE)
+ * - JSON-based persistent storage
+ * - Automatic lock cleanup with timeout
+ */
+import fs from 'fs-extra';
+import path from 'path';
+/**
+ * ID Registry with atomic file-based locking
+ */
+export class IDRegistry {
+    constructor(projectRoot) {
+        this.lockTimeout = 30000; // 30 seconds
+        this.retryDelay = 100; // 100ms
+        this.registryPath = path.join(projectRoot, '.specweave/.id-registry.json');
+        this.lockPath = path.join(projectRoot, '.specweave/.id-registry.lock');
+    }
+    /**
+     * Register a new Feature ID atomically
+     *
+     * @param fsId - Feature ID to register (e.g., "FS-042E")
+     * @param entry - Registry entry metadata
+     * @throws Error if collision detected or lock acquisition fails
+     */
+    async registerID(fsId, entry) {
+        // Acquire lock with timeout
+        await this.acquireLock();
+        try {
+            // Read current registry
+            const registry = await this.readRegistry();
+            // Check for collision (exact match or variant)
+            const collision = this.detectCollision(fsId, registry);
+            if (collision) {
+                throw new Error(`ID collision: ${fsId} conflicts with ${collision}`);
+            }
+            // Add new entry
+            registry.entries[fsId] = {
+                id: fsId,
+                ...entry
+            };
+            registry.lastUpdated = new Date().toISOString();
+            registry.version++;
+            // Write atomically
+            await this.writeRegistry(registry);
+        }
+        finally {
+            // Always release lock
+            await this.releaseLock();
+        }
+    }
+    /**
+     * Check if ID exists in registry
+     *
+     * @param fsId - Feature ID to check
+     * @returns True if ID is registered
+     */
+    async hasID(fsId) {
+        const registry = await this.readRegistry();
+        return fsId in registry.entries;
+    }
+    /**
+     * Get registry entry
+     *
+     * @param fsId - Feature ID to retrieve
+     * @returns Registry entry or null if not found
+     */
+    async getEntry(fsId) {
+        const registry = await this.readRegistry();
+        return registry.entries[fsId] || null;
+    }
+    /**
+     * Get all registered IDs
+     *
+     * @returns Array of all registered Feature IDs
+     */
+    async getAllIDs() {
+        const registry = await this.readRegistry();
+        return Object.keys(registry.entries);
+    }
+    /**
+     * Acquire lock file with timeout and retry
+     *
+     * @throws Error if lock cannot be acquired within timeout
+     */
+    async acquireLock() {
+        const startTime = Date.now();
+        // Ensure lock directory exists
+        await fs.ensureDir(path.dirname(this.lockPath));
+        while (true) {
+            try {
+                // Try to create lock file exclusively
+                await fs.writeFile(this.lockPath, Date.now().toString(), { flag: 'wx' });
+                return; // Lock acquired
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST') {
+                    throw error; // Unexpected error
+                }
+                // Lock exists, check timeout
+                const elapsed = Date.now() - startTime;
+                if (elapsed > this.lockTimeout) {
+                    // Check if lock is stale
+                    const lockAge = await this.getLockAge();
+                    if (lockAge > this.lockTimeout) {
+                        // Stale lock, force remove
+                        await fs.remove(this.lockPath);
+                        continue; // Retry
+                    }
+                    throw new Error(`Lock acquisition timeout after ${elapsed}ms`);
+                }
+                // Wait and retry
+                await this.sleep(this.retryDelay);
+            }
+        }
+    }
+    /**
+     * Release lock file
+     */
+    async releaseLock() {
+        try {
+            await fs.remove(this.lockPath);
+        }
+        catch (error) {
+            // Ignore if lock doesn't exist (already released)
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Get lock file age in milliseconds
+     *
+     * @returns Lock age or Infinity if lock doesn't exist
+     */
+    async getLockAge() {
+        try {
+            const lockContent = await fs.readFile(this.lockPath, 'utf-8');
+            const lockTime = parseInt(lockContent, 10);
+            return Date.now() - lockTime;
+        }
+        catch (error) {
+            return Infinity; // Lock doesn't exist
+        }
+    }
+    /**
+     * Read registry from disk
+     *
+     * @returns Registry data
+     */
+    async readRegistry() {
+        try {
+            const content = await fs.readFile(this.registryPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Registry doesn't exist, return empty
+                return {
+                    entries: {},
+                    lastUpdated: new Date().toISOString(),
+                    version: 1
+                };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Write registry to disk atomically
+     *
+     * @param registry - Registry data to write
+     */
+    async writeRegistry(registry) {
+        await fs.ensureDir(path.dirname(this.registryPath));
+        // Write to temp file first
+        const tempPath = `${this.registryPath}.tmp`;
+        await fs.writeFile(tempPath, JSON.stringify(registry, null, 2));
+        // Atomic rename
+        await fs.rename(tempPath, this.registryPath);
+    }
+    /**
+     * Detect ID collision (exact match or variant)
+     *
+     * @param fsId - ID to check (e.g., "FS-042E")
+     * @param registry - Current registry
+     * @returns Conflicting ID or null if no collision
+     *
+     * @example
+     * // Given registry: {FS-042: {...}}
+     * detectCollision('FS-042E', registry) // Returns: 'FS-042'
+     * detectCollision('FS-043', registry)  // Returns: null
+     */
+    detectCollision(fsId, registry) {
+        // Exact match
+        if (fsId in registry.entries) {
+            return fsId;
+        }
+        // Extract numeric part
+        const match = fsId.match(/^FS-(\d{3,})E?$/);
+        if (!match) {
+            throw new Error(`Invalid FS-ID format: ${fsId}`);
+        }
+        const number = parseInt(match[1], 10);
+        const internalId = `FS-${String(number).padStart(3, '0')}`;
+        const externalId = `FS-${String(number).padStart(3, '0')}E`;
+        // Check variant
+        if (internalId !== fsId && internalId in registry.entries) {
+            return internalId;
+        }
+        if (externalId !== fsId && externalId in registry.entries) {
+            return externalId;
+        }
+        return null; // No collision
+    }
+    /**
+     * Sleep for specified milliseconds
+     *
+     * @param ms - Milliseconds to sleep
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=id-registry.js.map

package/dist/src/living-docs/id-registry.js.map

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

package/dist/src/progress/us-progress-tracker.d.ts

@@ -0,0 +1,68 @@
+/**
+ * User Story Progress Tracking
+ *
+ * Calculates task completion statistics grouped by User Story.
+ * Provides per-US and aggregate completion percentages.
+ */
+import { type Task, type TasksByUserStory } from '../generators/spec/task-parser.js';
+/**
+ * Progress statistics for a single User Story
+ */
+export interface USProgress {
+    usId: string;
+    totalTasks: number;
+    completedTasks: number;
+    inProgressTasks: number;
+    pendingTasks: number;
+    percentage: number;
+    tasks: Task[];
+}
+/**
+ * Aggregate progress across all User Stories
+ */
+export interface AggregateProgress {
+    totalTasks: number;
+    completedTasks: number;
+    inProgressTasks: number;
+    pendingTasks: number;
+    percentage: number;
+    byUserStory: Map<string, USProgress>;
+    orphanTasks: Task[];
+}
+/**
+ * Calculate task completion statistics for a single User Story
+ */
+export declare function calculateUSProgress(usId: string, tasks: Task[]): USProgress;
+/**
+ * Calculate aggregate progress across all User Stories
+ */
+export declare function calculateAggregateProgress(tasksByUS: TasksByUserStory): AggregateProgress;
+/**
+ * Calculate progress from tasks.md file
+ */
+export declare function calculateProgressFromTasksFile(tasksPath: string): Promise<AggregateProgress>;
+/**
+ * Format US progress as string
+ */
+export declare function formatUSProgress(progress: USProgress, includePercentage?: boolean): string;
+/**
+ * Format aggregate progress as string
+ */
+export declare function formatAggregateProgress(progress: AggregateProgress): string;
+/**
+ * Get progress bar visualization
+ */
+export declare function getProgressBar(percentage: number, width?: number): string;
+/**
+ * Get color indicator based on percentage
+ */
+export declare function getProgressColor(percentage: number): 'green' | 'yellow' | 'red';
+/**
+ * Sort User Stories by completion percentage (descending)
+ */
+export declare function sortUSByCompletion(progressMap: Map<string, USProgress>): USProgress[];
+/**
+ * Sort User Stories by US-ID (ascending)
+ */
+export declare function sortUSByID(progressMap: Map<string, USProgress>): USProgress[];
+//# sourceMappingURL=us-progress-tracker.d.ts.map

package/dist/src/progress/us-progress-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"us-progress-tracker.d.ts","sourceRoot":"","sources":["../../../src/progress/us-progress-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAsC,KAAK,IAAI,EAAE,KAAK,gBAAgB,EAAmB,MAAM,mCAAmC,CAAC;AAE1I;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,WAAW,EAAE,IAAI,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,UAAU,CAmB3E;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,gBAAgB,GAAG,iBAAiB,CA0CzF;AAED;;GAEG;AACH,wBAAsB,8BAA8B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAGlG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,EAAE,iBAAiB,GAAE,OAAc,GAAG,MAAM,CAGhG;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAE3E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,MAAM,CAI7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAI/E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,UAAU,EAAE,CAErF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,UAAU,EAAE,CAM7E"}

package/dist/src/progress/us-progress-tracker.js

@@ -0,0 +1,120 @@
+/**
+ * User Story Progress Tracking
+ *
+ * Calculates task completion statistics grouped by User Story.
+ * Provides per-US and aggregate completion percentages.
+ */
+import { parseTasksWithUSLinks } from '../generators/spec/task-parser.js';
+/**
+ * Calculate task completion statistics for a single User Story
+ */
+export function calculateUSProgress(usId, tasks) {
+    const totalTasks = tasks.length;
+    const completedTasks = tasks.filter((t) => t.status === 'completed').length;
+    const inProgressTasks = tasks.filter((t) => t.status === 'in_progress').length;
+    const pendingTasks = tasks.filter((t) => t.status === 'pending' || t.status === 'transferred' || t.status === 'canceled').length;
+    const percentage = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+    return {
+        usId,
+        totalTasks,
+        completedTasks,
+        inProgressTasks,
+        pendingTasks,
+        percentage,
+        tasks,
+    };
+}
+/**
+ * Calculate aggregate progress across all User Stories
+ */
+export function calculateAggregateProgress(tasksByUS) {
+    const byUserStory = new Map();
+    let totalTasks = 0;
+    let completedTasks = 0;
+    let inProgressTasks = 0;
+    let pendingTasks = 0;
+    // Calculate per-US progress
+    for (const [usId, tasks] of Object.entries(tasksByUS)) {
+        if (usId === 'orphan' || usId === 'unknown')
+            continue; // Skip special keys
+        const usProgress = calculateUSProgress(usId, tasks);
+        byUserStory.set(usId, usProgress);
+        totalTasks += usProgress.totalTasks;
+        completedTasks += usProgress.completedTasks;
+        inProgressTasks += usProgress.inProgressTasks;
+        pendingTasks += usProgress.pendingTasks;
+    }
+    // Identify orphan tasks (tasks without userStory field)
+    const orphanTasks = tasksByUS['orphan'] || tasksByUS['unknown'] || [];
+    if (orphanTasks.length > 0) {
+        totalTasks += orphanTasks.length;
+        completedTasks += orphanTasks.filter((t) => t.status === 'completed').length;
+        inProgressTasks += orphanTasks.filter((t) => t.status === 'in_progress').length;
+        pendingTasks += orphanTasks.filter((t) => t.status === 'pending' || t.status === 'transferred' || t.status === 'canceled').length;
+    }
+    const percentage = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+    return {
+        totalTasks,
+        completedTasks,
+        inProgressTasks,
+        pendingTasks,
+        percentage,
+        byUserStory,
+        orphanTasks,
+    };
+}
+/**
+ * Calculate progress from tasks.md file
+ */
+export async function calculateProgressFromTasksFile(tasksPath) {
+    const tasksByUS = await parseTasksWithUSLinks(tasksPath);
+    return calculateAggregateProgress(tasksByUS);
+}
+/**
+ * Format US progress as string
+ */
+export function formatUSProgress(progress, includePercentage = true) {
+    const percentStr = includePercentage ? ` (${progress.percentage}%)` : '';
+    return `${progress.usId}: ${progress.completedTasks}/${progress.totalTasks} tasks${percentStr}`;
+}
+/**
+ * Format aggregate progress as string
+ */
+export function formatAggregateProgress(progress) {
+    return `Overall: ${progress.completedTasks}/${progress.totalTasks} tasks (${progress.percentage}%)`;
+}
+/**
+ * Get progress bar visualization
+ */
+export function getProgressBar(percentage, width = 20) {
+    const filledChars = Math.round((percentage / 100) * width);
+    const emptyChars = width - filledChars;
+    return '█'.repeat(filledChars) + '░'.repeat(emptyChars);
+}
+/**
+ * Get color indicator based on percentage
+ */
+export function getProgressColor(percentage) {
+    if (percentage >= 80)
+        return 'green';
+    if (percentage >= 50)
+        return 'yellow';
+    return 'red';
+}
+/**
+ * Sort User Stories by completion percentage (descending)
+ */
+export function sortUSByCompletion(progressMap) {
+    return Array.from(progressMap.values()).sort((a, b) => b.percentage - a.percentage);
+}
+/**
+ * Sort User Stories by US-ID (ascending)
+ */
+export function sortUSByID(progressMap) {
+    return Array.from(progressMap.values()).sort((a, b) => {
+        const aNum = parseInt(a.usId.replace('US-', ''));
+        const bNum = parseInt(b.usId.replace('US-', ''));
+        return aNum - bNum;
+    });
+}
+//# sourceMappingURL=us-progress-tracker.js.map

package/dist/src/progress/us-progress-tracker.js.map

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

package/dist/src/sync/external-item-sync-service.d.ts

@@ -0,0 +1,150 @@
+/**
+ * External Item Sync Service
+ *
+ * Handles synchronization with external tools (GitHub, JIRA, ADO) while
+ * preserving original item format and preventing unintended modifications.
+ *
+ * Key Features:
+ * - Comment-based updates for external items (format preservation)
+ * - Full sync for internal items (title, description, ACs)
+ * - Format preservation validation
+ * - External title immutability
+ *
+ * Part of increment 0047-us-task-linkage (T-034B)
+ */
+import type { Logger } from '../utils/logger.js';
+/**
+ * Task completion data for sync
+ */
+export interface TaskCompletionData {
+    /** Task ID (e.g., "T-034") */
+    taskId: string;
+    /** Feature ID (e.g., "FS-047") */
+    featureId: string;
+    /** User Story ID (e.g., "US-009") */
+    usId: string;
+    /** Acceptance criteria satisfied by this task */
+    satisfiesACs: string[];
+    /** Completed tasks count */
+    completedTasks: number;
+    /** Total tasks count */
+    totalTasks: number;
+    /** Completion percentage */
+    percentage: number;
+    /** Living docs URL */
+    livingDocsUrl?: string;
+    /** Task title */
+    taskTitle: string;
+    /** Task status */
+    status: 'completed' | 'in_progress' | 'pending';
+}
+/**
+ * Sync options
+ */
+export interface SyncOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** External tool (github, jira, ado) */
+    externalTool?: 'github' | 'jira' | 'ado';
+    /** Force full sync (ignore format_preservation flag) */
+    forceFullSync?: boolean;
+    /** Dry run (don't actually sync, just log what would happen) */
+    dryRun?: boolean;
+    /** Logger instance */
+    logger?: Logger;
+}
+/**
+ * Sync result
+ */
+export interface SyncResult {
+    /** Success flag */
+    success: boolean;
+    /** Sync mode used */
+    mode: 'comment-only' | 'full-sync' | 'skipped';
+    /** Reason for mode selection */
+    reason: string;
+    /** Comment posted (if comment-only mode) */
+    comment?: string;
+    /** Fields updated (if full-sync mode) */
+    updatedFields?: string[];
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * External Item Sync Service
+ *
+ * Routes sync operations based on format_preservation flag.
+ * External items (format_preservation=true) → comment-only sync
+ * Internal items (format_preservation=false) → full sync
+ */
+export declare class ExternalItemSyncService {
+    private logger;
+    private validator;
+    constructor(options?: {
+        logger?: Logger;
+    });
+    /**
+     * Sync task completion to external tool
+     *
+     * Routes to comment-only or full sync based on format_preservation flag
+     *
+     * @param completionData - Task completion data
+     * @param options - Sync options
+     * @returns Sync result
+     */
+    syncTaskCompletion(completionData: TaskCompletionData, options: SyncOptions): Promise<SyncResult>;
+    /**
+     * Get format_preservation flag from living docs User Story file
+     *
+     * @param usId - User Story ID (e.g., "US-009")
+     * @param featureId - Feature ID (e.g., "FS-047")
+     * @param projectRoot - Project root directory
+     * @returns True if format preservation enabled
+     */
+    private getFormatPreservation;
+    /**
+     * Find User Story file in living docs
+     *
+     * @param projectRoot - Project root
+     * @param featureId - Feature ID (e.g., "FS-047")
+     * @param usId - User Story ID (e.g., "US-009")
+     * @returns Path to US file or null if not found
+     */
+    private findUSFile;
+    /**
+     * Get all project directories in specs
+     *
+     * @param specsDir - Specs directory
+     * @returns Array of project directory paths
+     */
+    private getProjectDirs;
+    /**
+     * Comment-only sync: Post completion update as comment
+     *
+     * Does NOT modify external item title, description, or acceptance criteria.
+     * Only posts a comment with task completion status.
+     *
+     * @param completionData - Task completion data
+     * @param options - Sync options
+     * @returns Sync result
+     */
+    private commentOnlySync;
+    /**
+     * Full sync: Update external item title, description, ACs
+     *
+     * Used for internal items or when format preservation disabled.
+     *
+     * @param completionData - Task completion data
+     * @param options - Sync options
+     * @returns Sync result
+     */
+    private fullSync;
+    /**
+     * Format completion comment for external tool
+     *
+     * @param data - Task completion data
+     * @returns Formatted comment
+     */
+    private formatCompletionComment;
+}
+//# sourceMappingURL=external-item-sync-service.d.ts.map

package/dist/src/sync/external-item-sync-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-item-sync-service.d.ts","sourceRoot":"","sources":["../../../src/sync/external-item-sync-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAMjD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IAEf,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAElB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IAEb,iDAAiD;IACjD,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB,4BAA4B;IAC5B,cAAc,EAAE,MAAM,CAAC;IAEvB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IAEnB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IAEnB,sBAAsB;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAElB,kBAAkB;IAClB,MAAM,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IAEzC,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,mBAAmB;IACnB,OAAO,EAAE,OAAO,CAAC;IAEjB,qBAAqB;IACrB,IAAI,EAAE,cAAc,GAAG,WAAW,GAAG,SAAS,CAAC;IAE/C,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IAEf,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAA8B;gBAEnC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAK7C;;;;;;;;OAQG;IACG,kBAAkB,CACtB,cAAc,EAAE,kBAAkB,EAClC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC;IAoCtB;;;;;;;OAOG;YACW,qBAAqB;IA2BnC;;;;;;;OAOG;YACW,UAAU;IA2BxB;;;;;OAKG;YACW,cAAc;IAa5B;;;;;;;;;OASG;YACW,eAAe;IA6B7B;;;;;;;;OAQG;YACW,QAAQ;IAwDtB;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;CAahC"}