specweave 0.22.12 → 0.22.14

package/dist/src/living-docs/fs-id-allocator.d.ts

@@ -0,0 +1,149 @@
+/**
+ * FS-ID Allocator - Intelligent Feature ID allocation with chronological placement
+ *
+ * Allocates FS-XXX IDs for external work items based on creation date,
+ * attempting chronological insertion while preventing collisions.
+ *
+ * Features:
+ * - Chronological ID allocation based on work item creation date
+ * - Gap filling (insert FS-011E between FS-010 and FS-020)
+ * - Append mode fallback (max ID + 1)
+ * - Collision detection (checks both FS-XXX and FS-XXXE)
+ * - Archive-aware (scans both active and archived features)
+ */
+import { type ExternalItemMetadata } from '../core/types/origin-metadata.js';
+/**
+ * Feature metadata extracted from living docs
+ */
+export interface FeatureMetadata {
+    /** Feature ID (e.g., "FS-042", "FS-042E") */
+    id: string;
+    /** Feature creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Origin (internal | external) */
+    origin: 'internal' | 'external';
+    /** External ID if external origin */
+    externalId?: string;
+    /** Path to feature folder */
+    path: string;
+}
+/**
+ * External work item to be allocated an FS-ID
+ */
+export interface ExternalWorkItem {
+    /** External ID (e.g., "GH-#638", "JIRA-SPEC-789") */
+    externalId: string;
+    /** Work item title */
+    title: string;
+    /** Creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** External URL */
+    externalUrl: string;
+}
+/**
+ * ID allocation result
+ */
+export interface AllocationResult {
+    /** Allocated FS-ID (e.g., "FS-042E") */
+    id: string;
+    /** Allocation strategy used */
+    strategy: 'chronological-insert' | 'append' | 'first';
+    /** Reason for allocation decision */
+    reason: string;
+    /** Numeric ID value */
+    number: number;
+}
+/**
+ * FS-ID Allocator
+ *
+ * Intelligently allocates Feature IDs with chronological placement
+ */
+export declare class FSIdAllocator {
+    private projectRoot;
+    private specsPath;
+    private archivePath;
+    private existingFeatures;
+    private scanned;
+    constructor(projectRoot: string);
+    /**
+     * Scan existing FS-IDs (both active and archived)
+     *
+     * CRITICAL: Archives are scanned to prevent ID reuse
+     */
+    scanExistingIds(): Promise<void>;
+    /**
+     * Scan directory for FS-XXX folders
+     */
+    private scanDirectory;
+    /**
+     * Parse feature metadata from README.md frontmatter
+     */
+    private parseFeatureMetadata;
+    /**
+     * Allocate FS-ID for external work item with chronological placement
+     *
+     * Algorithm:
+     * 1. Sort existing IDs by creation date
+     * 2. Find chronological insertion point based on work item creation date
+     * 3. Check for ID gaps between consecutive features
+     * 4. If gap exists, allocate next ID in gap (e.g., FS-011E between FS-010 and FS-020)
+     * 5. If no gap, append to end (max ID + 1 with E suffix)
+     *
+     * @param workItem - External work item to allocate ID for
+     * @returns Allocation result with ID and strategy
+     */
+    allocateId(workItem: ExternalWorkItem): Promise<AllocationResult>;
+    /**
+     * Check if ID has collision (exact match or variant)
+     *
+     * @param id - FS-ID to check (e.g., "FS-042" or "FS-042E")
+     * @returns True if collision exists
+     *
+     * @example
+     * // Given existing IDs: FS-010, FS-011E, FS-020
+     * hasCollision('FS-011')  // true (FS-011E exists)
+     * hasCollision('FS-011E') // true (exact match)
+     * hasCollision('FS-012')  // false
+     */
+    hasCollision(id: string): boolean;
+    /**
+     * Get maximum numeric ID value (ignoring E suffix)
+     *
+     * @returns Maximum ID number
+     */
+    getMaxId(): number;
+    /**
+     * Extract numeric part from FS-ID
+     *
+     * @param id - FS-ID (e.g., "FS-042" or "FS-042E")
+     * @returns Numeric part (e.g., 42)
+     */
+    private extractNumber;
+    /**
+     * Get all existing feature IDs (sorted by creation date)
+     *
+     * @returns Array of feature metadata sorted chronologically
+     */
+    getExistingFeatures(): FeatureMetadata[];
+    /**
+     * Get allocation statistics
+     */
+    getStats(): {
+        total: number;
+        active: number;
+        archived: number;
+        internal: number;
+        external: number;
+        maxId: number;
+    };
+    /**
+     * Create feature folder with README.md and metadata
+     *
+     * @param fsId - Feature ID (e.g., "FS-042E")
+     * @param workItem - External work item metadata
+     * @param metadata - External item metadata for origin tracking
+     * @returns Path to created feature folder
+     */
+    createFeatureFolder(fsId: string, workItem: ExternalWorkItem, metadata: ExternalItemMetadata): Promise<string>;
+}
+//# sourceMappingURL=fs-id-allocator.d.ts.map

package/dist/src/living-docs/fs-id-allocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-id-allocator.d.ts","sourceRoot":"","sources":["../../../src/living-docs/fs-id-allocator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAgB,KAAK,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAE3F;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IAEX,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAElB,mCAAmC;IACnC,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;IAEhC,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IAEnB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IAEd,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAElB,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IAEX,+BAA+B;IAC/B,QAAQ,EAAE,sBAAsB,GAAG,QAAQ,GAAG,OAAO,CAAC;IAEtD,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IAEf,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAA2C;IACnE,OAAO,CAAC,OAAO,CAAkB;gBAErB,WAAW,EAAE,MAAM;IAM/B;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBtC;;OAEG;YACW,aAAa;IAqB3B;;OAEG;YACW,oBAAoB;IA4ClC;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAyFvE;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAcjC;;;;OAIG;IACH,QAAQ,IAAI,MAAM;IASlB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;OAIG;IACH,mBAAmB,IAAI,eAAe,EAAE;IAMxC;;OAEG;IACH,QAAQ,IAAI;QACV,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;KACf;IAaD;;;;;;;OAOG;IACG,mBAAmB,CACvB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC;CAuDnB"}

package/dist/src/living-docs/fs-id-allocator.js

@@ -0,0 +1,325 @@
+/**
+ * FS-ID Allocator - Intelligent Feature ID allocation with chronological placement
+ *
+ * Allocates FS-XXX IDs for external work items based on creation date,
+ * attempting chronological insertion while preventing collisions.
+ *
+ * Features:
+ * - Chronological ID allocation based on work item creation date
+ * - Gap filling (insert FS-011E between FS-010 and FS-020)
+ * - Append mode fallback (max ID + 1)
+ * - Collision detection (checks both FS-XXX and FS-XXXE)
+ * - Archive-aware (scans both active and archived features)
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import matter from 'gray-matter';
+import { formatOrigin } from '../core/types/origin-metadata.js';
+/**
+ * FS-ID Allocator
+ *
+ * Intelligently allocates Feature IDs with chronological placement
+ */
+export class FSIdAllocator {
+    constructor(projectRoot) {
+        this.existingFeatures = new Map();
+        this.scanned = false;
+        this.projectRoot = projectRoot;
+        this.specsPath = path.join(projectRoot, '.specweave/docs/internal/specs');
+        this.archivePath = path.join(projectRoot, '.specweave/docs/_archive/specs');
+    }
+    /**
+     * Scan existing FS-IDs (both active and archived)
+     *
+     * CRITICAL: Archives are scanned to prevent ID reuse
+     */
+    async scanExistingIds() {
+        this.existingFeatures.clear();
+        // Scan active features
+        if (await fs.pathExists(this.specsPath)) {
+            await this.scanDirectory(this.specsPath, 'active');
+        }
+        // Scan archived features (CRITICAL - prevents ID reuse)
+        if (await fs.pathExists(this.archivePath)) {
+            await this.scanDirectory(this.archivePath, 'archived');
+        }
+        this.scanned = true;
+    }
+    /**
+     * Scan directory for FS-XXX folders
+     */
+    async scanDirectory(dirPath, source) {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            // Match FS-XXX or FS-XXXE pattern
+            const match = entry.name.match(/^(FS-\d{3}E?)$/);
+            if (!match)
+                continue;
+            const fsId = match[1];
+            const featurePath = path.join(dirPath, entry.name);
+            // Try to parse feature metadata from README.md
+            const metadata = await this.parseFeatureMetadata(featurePath, fsId);
+            if (metadata) {
+                this.existingFeatures.set(fsId, metadata);
+            }
+        }
+    }
+    /**
+     * Parse feature metadata from README.md frontmatter
+     */
+    async parseFeatureMetadata(featurePath, fsId) {
+        // Try FEATURE.md first, then README.md
+        const possibleFiles = ['FEATURE.md', 'README.md', 'feature.md', 'readme.md'];
+        for (const filename of possibleFiles) {
+            const filePath = path.join(featurePath, filename);
+            if (await fs.pathExists(filePath)) {
+                try {
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    const parsed = matter(content);
+                    const frontmatter = parsed.data;
+                    // Normalize timestamp (remove milliseconds for consistency)
+                    // gray-matter parses ISO 8601 timestamps as Date objects, not strings
+                    const rawTimestamp = frontmatter.created || frontmatter.createdAt || new Date(0);
+                    const timestamp = rawTimestamp instanceof Date ? rawTimestamp.toISOString() : rawTimestamp;
+                    const normalizedTimestamp = timestamp.replace(/\.\d{3}Z$/, 'Z');
+                    return {
+                        id: fsId,
+                        createdAt: normalizedTimestamp,
+                        origin: fsId.endsWith('E') ? 'external' : 'internal',
+                        externalId: frontmatter.external_id || frontmatter.externalId,
+                        path: featurePath
+                    };
+                }
+                catch (error) {
+                    // Continue to next file
+                    continue;
+                }
+            }
+        }
+        // Fallback: create minimal metadata if no file found
+        return {
+            id: fsId,
+            createdAt: new Date(0).toISOString(), // Epoch (will sort to beginning)
+            origin: fsId.endsWith('E') ? 'external' : 'internal',
+            path: featurePath
+        };
+    }
+    /**
+     * Allocate FS-ID for external work item with chronological placement
+     *
+     * Algorithm:
+     * 1. Sort existing IDs by creation date
+     * 2. Find chronological insertion point based on work item creation date
+     * 3. Check for ID gaps between consecutive features
+     * 4. If gap exists, allocate next ID in gap (e.g., FS-011E between FS-010 and FS-020)
+     * 5. If no gap, append to end (max ID + 1 with E suffix)
+     *
+     * @param workItem - External work item to allocate ID for
+     * @returns Allocation result with ID and strategy
+     */
+    async allocateId(workItem) {
+        if (!this.scanned) {
+            await this.scanExistingIds();
+        }
+        // Handle empty case (first feature)
+        if (this.existingFeatures.size === 0) {
+            return {
+                id: 'FS-001E',
+                strategy: 'first',
+                reason: 'First external feature in project',
+                number: 1
+            };
+        }
+        // Sort features by creation date
+        const sortedFeatures = Array.from(this.existingFeatures.values()).sort((a, b) => {
+            return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+        });
+        // Find chronological insertion point
+        const workItemDate = new Date(workItem.createdAt).getTime();
+        let insertionIndex = sortedFeatures.findIndex(f => new Date(f.createdAt).getTime() > workItemDate);
+        // If work item is after all existing features, append
+        if (insertionIndex === -1) {
+            const maxId = this.getMaxId();
+            const nextNumber = maxId + 1;
+            const nextId = `FS-${String(nextNumber).padStart(3, '0')}E`;
+            // Check for collision
+            if (this.hasCollision(nextId)) {
+                throw new Error(`ID collision: ${nextId} already exists`);
+            }
+            return {
+                id: nextId,
+                strategy: 'append',
+                reason: `Work item created after all existing features (${new Date(workItem.createdAt).toISOString()})`,
+                number: nextNumber
+            };
+        }
+        // Try chronological insertion into gap
+        const beforeFeature = insertionIndex > 0 ? sortedFeatures[insertionIndex - 1] : null;
+        const afterFeature = sortedFeatures[insertionIndex];
+        if (beforeFeature && afterFeature) {
+            const beforeNumber = this.extractNumber(beforeFeature.id);
+            const afterNumber = this.extractNumber(afterFeature.id);
+            // Check if there's a gap (at least 2 numbers apart)
+            if (afterNumber - beforeNumber > 1) {
+                // Allocate next ID after beforeFeature
+                const nextNumber = beforeNumber + 1;
+                const nextId = `FS-${String(nextNumber).padStart(3, '0')}E`;
+                // Check for collision
+                if (!this.hasCollision(nextId)) {
+                    return {
+                        id: nextId,
+                        strategy: 'chronological-insert',
+                        reason: `Inserted chronologically between ${beforeFeature.id} (${beforeFeature.createdAt}) and ${afterFeature.id} (${afterFeature.createdAt})`,
+                        number: nextNumber
+                    };
+                }
+            }
+        }
+        // Fallback: append to end if gap insertion failed
+        const maxId = this.getMaxId();
+        const nextNumber = maxId + 1;
+        const nextId = `FS-${String(nextNumber).padStart(3, '0')}E`;
+        // Check for collision
+        if (this.hasCollision(nextId)) {
+            throw new Error(`ID collision: ${nextId} already exists`);
+        }
+        return {
+            id: nextId,
+            strategy: 'append',
+            reason: 'Gap insertion not possible, appended to end',
+            number: nextNumber
+        };
+    }
+    /**
+     * Check if ID has collision (exact match or variant)
+     *
+     * @param id - FS-ID to check (e.g., "FS-042" or "FS-042E")
+     * @returns True if collision exists
+     *
+     * @example
+     * // Given existing IDs: FS-010, FS-011E, FS-020
+     * hasCollision('FS-011')  // true (FS-011E exists)
+     * hasCollision('FS-011E') // true (exact match)
+     * hasCollision('FS-012')  // false
+     */
+    hasCollision(id) {
+        // Exact match
+        if (this.existingFeatures.has(id)) {
+            return true;
+        }
+        // Variant match (check both FS-XXX and FS-XXXE)
+        const number = this.extractNumber(id);
+        const internalId = `FS-${String(number).padStart(3, '0')}`;
+        const externalId = `FS-${String(number).padStart(3, '0')}E`;
+        return this.existingFeatures.has(internalId) || this.existingFeatures.has(externalId);
+    }
+    /**
+     * Get maximum numeric ID value (ignoring E suffix)
+     *
+     * @returns Maximum ID number
+     */
+    getMaxId() {
+        if (this.existingFeatures.size === 0) {
+            return 0;
+        }
+        const numbers = Array.from(this.existingFeatures.keys()).map(id => this.extractNumber(id));
+        return Math.max(...numbers);
+    }
+    /**
+     * Extract numeric part from FS-ID
+     *
+     * @param id - FS-ID (e.g., "FS-042" or "FS-042E")
+     * @returns Numeric part (e.g., 42)
+     */
+    extractNumber(id) {
+        const match = id.match(/^FS-(\d{3,})E?$/);
+        if (!match) {
+            throw new Error(`Invalid FS-ID format: ${id}`);
+        }
+        return parseInt(match[1], 10);
+    }
+    /**
+     * Get all existing feature IDs (sorted by creation date)
+     *
+     * @returns Array of feature metadata sorted chronologically
+     */
+    getExistingFeatures() {
+        return Array.from(this.existingFeatures.values()).sort((a, b) => {
+            return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+        });
+    }
+    /**
+     * Get allocation statistics
+     */
+    getStats() {
+        const features = Array.from(this.existingFeatures.values());
+        return {
+            total: features.length,
+            active: features.filter(f => !f.path.includes('/_archive/')).length,
+            archived: features.filter(f => f.path.includes('/_archive/')).length,
+            internal: features.filter(f => f.origin === 'internal').length,
+            external: features.filter(f => f.origin === 'external').length,
+            maxId: this.getMaxId()
+        };
+    }
+    /**
+     * Create feature folder with README.md and metadata
+     *
+     * @param fsId - Feature ID (e.g., "FS-042E")
+     * @param workItem - External work item metadata
+     * @param metadata - External item metadata for origin tracking
+     * @returns Path to created feature folder
+     */
+    async createFeatureFolder(fsId, workItem, metadata) {
+        // Create folder path
+        const featurePath = path.join(this.specsPath, fsId);
+        await fs.ensureDir(featurePath);
+        // Generate README.md with frontmatter
+        const originBadge = formatOrigin(metadata);
+        // Build frontmatter lines (only include defined optional fields)
+        const frontmatterLines = [
+            `id: ${fsId}`,
+            `title: ${workItem.title}`,
+            `created: ${workItem.createdAt}`,
+            `origin: external`,
+            `source: ${metadata.source}`,
+            `external_id: ${metadata.external_id}`,
+            `external_url: ${metadata.external_url}`,
+            `imported_at: ${metadata.imported_at}`
+        ];
+        // Only add optional fields if explicitly defined
+        if (metadata.external_title !== undefined) {
+            frontmatterLines.push(`external_title: ${metadata.external_title}`);
+        }
+        if (metadata.format_preservation !== undefined) {
+            frontmatterLines.push(`format_preservation: ${metadata.format_preservation}`);
+        }
+        const readmeContent = `---
+${frontmatterLines.join('\n')}
+---
+
+# ${workItem.title}
+
+**Origin**: ${originBadge}
+
+## Description
+
+Imported from external work item.
+
+## User Stories
+
+User stories will be added here during import.
+
+## Status
+
+- **Created**: ${workItem.createdAt}
+- **Imported**: ${metadata.imported_at}
+`;
+        const readmePath = path.join(featurePath, 'README.md');
+        await fs.writeFile(readmePath, readmeContent);
+        return featurePath;
+    }
+}
+//# sourceMappingURL=fs-id-allocator.js.map

package/dist/src/living-docs/fs-id-allocator.js.map

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

package/dist/src/living-docs/id-registry.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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
+ */
+/**
+ * Registry entry metadata
+ */
+export interface RegistryEntry {
+    /** Feature ID (e.g., "FS-042E") */
+    id: string;
+    /** Registration timestamp (ISO 8601) */
+    registeredAt: string;
+    /** External ID if external origin */
+    externalId?: string;
+    /** External URL */
+    externalUrl?: string;
+    /** Origin type */
+    origin: 'internal' | 'external';
+}
+/**
+ * Registry data structure
+ */
+export interface RegistryData {
+    /** Map of FS-ID to metadata */
+    entries: Record<string, RegistryEntry>;
+    /** Last updated timestamp */
+    lastUpdated: string;
+    /** Registry version */
+    version: number;
+}
+/**
+ * ID Registry with atomic file-based locking
+ */
+export declare class IDRegistry {
+    private registryPath;
+    private lockPath;
+    private lockTimeout;
+    private retryDelay;
+    constructor(projectRoot: string);
+    /**
+     * 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
+     */
+    registerID(fsId: string, entry: Omit<RegistryEntry, 'id'>): Promise<void>;
+    /**
+     * Check if ID exists in registry
+     *
+     * @param fsId - Feature ID to check
+     * @returns True if ID is registered
+     */
+    hasID(fsId: string): Promise<boolean>;
+    /**
+     * Get registry entry
+     *
+     * @param fsId - Feature ID to retrieve
+     * @returns Registry entry or null if not found
+     */
+    getEntry(fsId: string): Promise<RegistryEntry | null>;
+    /**
+     * Get all registered IDs
+     *
+     * @returns Array of all registered Feature IDs
+     */
+    getAllIDs(): Promise<string[]>;
+    /**
+     * Acquire lock file with timeout and retry
+     *
+     * @throws Error if lock cannot be acquired within timeout
+     */
+    private acquireLock;
+    /**
+     * Release lock file
+     */
+    private releaseLock;
+    /**
+     * Get lock file age in milliseconds
+     *
+     * @returns Lock age or Infinity if lock doesn't exist
+     */
+    private getLockAge;
+    /**
+     * Read registry from disk
+     *
+     * @returns Registry data
+     */
+    private readRegistry;
+    /**
+     * Write registry to disk atomically
+     *
+     * @param registry - Registry data to write
+     */
+    private writeRegistry;
+    /**
+     * 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
+     */
+    private detectCollision;
+    /**
+     * Sleep for specified milliseconds
+     *
+     * @param ms - Milliseconds to sleep
+     */
+    private sleep;
+}
+//# sourceMappingURL=id-registry.d.ts.map

package/dist/src/living-docs/id-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-registry.d.ts","sourceRoot":"","sources":["../../../src/living-docs/id-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IAEX,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IAErB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,kBAAkB;IAClB,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAEvC,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IAEpB,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,UAAU,CAAe;gBAErB,WAAW,EAAE,MAAM;IAK/B;;;;;;OAMG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B/E;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK3C;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAK3D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKpC;;;;OAIG;YACW,WAAW;IAoCzB;;OAEG;YACW,WAAW;IAWzB;;;;OAIG;YACW,UAAU;IAUxB;;;;OAIG;YACW,YAAY;IAiB1B;;;;OAIG;YACW,aAAa;IAW3B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,eAAe;IA4BvB;;;;OAIG;IACH,OAAO,CAAC,KAAK;CAGd"}