ai-prompt-guide-mcp 1.0.0

package/dist/shared/__tests__/addressing-system.batch-cache.test.js

@@ -0,0 +1,306 @@
+/**
+ * Tests for batch-scoped caching in addressing system
+ *
+ * This test suite verifies that the AddressCache:
+ * 1. Only caches within batch scope (not persistent)
+ * 2. Clears cache after batch operations
+ * 3. Provides batch statistics for debugging
+ * 4. Handles errors gracefully
+ * 5. Maintains backward compatibility
+ */
+import { describe, test, expect, beforeEach } from 'vitest';
+import { parseDocumentAddress, parseSectionAddress, parseTaskAddress, ToolIntegration, invalidateAddressCache } from '../addressing-system.js';
+// Import internal cache accessor for testing (will be added)
+import { getGlobalAddressCache } from '../addressing-system.js';
+describe('AddressCache - Batch-Scoped Caching', () => {
+    beforeEach(() => {
+        // Clear batch cache before each test
+        const cache = getGlobalAddressCache();
+        cache.clearBatch();
+    });
+    describe('Batch-scoped caching behavior', () => {
+        test('should cache document addresses within batch scope', () => {
+            const cache = getGlobalAddressCache();
+            // First parse - should create entry
+            const addr1 = parseDocumentAddress('/test/doc1.md');
+            const stats1 = cache.getBatchStats();
+            expect(stats1.size).toBe(1);
+            expect(stats1.keys).toContain('/test/doc1.md');
+            // Second parse - should return cached entry (no factory call)
+            const addr2 = parseDocumentAddress('/test/doc1.md');
+            const stats2 = cache.getBatchStats();
+            expect(stats2.size).toBe(1); // Same size, cached
+            // Verify same address returned
+            expect(addr1.path).toBe(addr2.path);
+            expect(addr1.cacheKey).toBe(addr2.cacheKey);
+        });
+        test('should cache section addresses within batch scope', () => {
+            const cache = getGlobalAddressCache();
+            const contextDoc = '/test/context.md';
+            // Parse multiple sections
+            parseSectionAddress('section1', contextDoc);
+            parseSectionAddress('section2', contextDoc);
+            parseSectionAddress('#section3', contextDoc);
+            const stats = cache.getBatchStats();
+            expect(stats.size).toBeGreaterThan(0); // Should have cached entries
+            // Re-parse first section - should use cache
+            const section1a = parseSectionAddress('section1', contextDoc);
+            const section1b = parseSectionAddress('section1', contextDoc);
+            expect(section1a.slug).toBe(section1b.slug);
+        });
+        test('should cache task addresses within batch scope', () => {
+            const cache = getGlobalAddressCache();
+            const contextDoc = '/test/tasks.md';
+            // Parse tasks
+            const task1 = parseTaskAddress('setup-database', contextDoc);
+            const task2 = parseTaskAddress('setup-database', contextDoc);
+            // Should return cached result
+            expect(task1.slug).toBe(task2.slug);
+            expect(task1.fullPath).toBe(task2.fullPath);
+            const stats = cache.getBatchStats();
+            expect(stats.size).toBeGreaterThan(0);
+        });
+        test('should clear cache after batch completes', () => {
+            const cache = getGlobalAddressCache();
+            // Populate cache
+            parseDocumentAddress('/test/doc1.md');
+            parseDocumentAddress('/test/doc2.md');
+            parseSectionAddress('overview', '/test/doc1.md');
+            const statsBefore = cache.getBatchStats();
+            expect(statsBefore.size).toBeGreaterThan(0);
+            // Clear batch
+            cache.clearBatch();
+            const statsAfter = cache.getBatchStats();
+            expect(statsAfter.size).toBe(0);
+            expect(statsAfter.keys).toEqual([]);
+        });
+        test('should not persist cache across batches', () => {
+            const cache = getGlobalAddressCache();
+            // Batch 1
+            parseDocumentAddress('/test/doc1.md');
+            const stats1 = cache.getBatchStats();
+            expect(stats1.size).toBeGreaterThan(0);
+            // Clear batch
+            cache.clearBatch();
+            // Batch 2
+            parseDocumentAddress('/test/doc2.md');
+            const stats2 = cache.getBatchStats();
+            // Should only have doc2, not doc1
+            expect(stats2.size).toBe(1);
+            expect(stats2.keys).not.toContain('/test/doc1.md');
+        });
+    });
+    describe('Batch statistics and debugging', () => {
+        test('should provide accurate batch statistics', () => {
+            const cache = getGlobalAddressCache();
+            // Empty cache
+            const emptyStats = cache.getBatchStats();
+            expect(emptyStats.size).toBe(0);
+            expect(emptyStats.keys).toEqual([]);
+            // Add entries
+            parseDocumentAddress('/test/doc1.md');
+            parseDocumentAddress('/test/doc2.md');
+            parseSectionAddress('overview', '/test/doc1.md');
+            const populatedStats = cache.getBatchStats();
+            expect(populatedStats.size).toBeGreaterThan(0);
+            expect(Array.isArray(populatedStats.keys)).toBe(true);
+            expect(populatedStats.keys.length).toBe(populatedStats.size);
+        });
+        test('should track all cache keys correctly', () => {
+            const cache = getGlobalAddressCache();
+            const doc1 = '/test/doc1.md';
+            const doc2 = '/test/doc2.md';
+            parseDocumentAddress(doc1);
+            parseDocumentAddress(doc2);
+            const stats = cache.getBatchStats();
+            expect(stats.keys).toContain(doc1);
+            expect(stats.keys).toContain(doc2);
+        });
+        test('should handle multiple cache types in statistics', () => {
+            const cache = getGlobalAddressCache();
+            // Mix of documents and sections
+            parseDocumentAddress('/test/doc1.md');
+            parseSectionAddress('section1', '/test/doc1.md');
+            parseSectionAddress('#section2', '/test/doc1.md');
+            const stats = cache.getBatchStats();
+            expect(stats.size).toBeGreaterThan(0);
+            // All keys should be unique
+            const uniqueKeys = new Set(stats.keys);
+            expect(uniqueKeys.size).toBe(stats.keys.length);
+        });
+    });
+    describe('Error handling with batch cache', () => {
+        test('should handle cache errors gracefully', () => {
+            // Invalid address should throw, not corrupt cache
+            expect(() => parseDocumentAddress('')).toThrow();
+            // Cache should still work after error
+            const addr = parseDocumentAddress('/test/doc.md');
+            expect(addr.path).toBe('/test/doc.md');
+            const cache = getGlobalAddressCache();
+            const stats = cache.getBatchStats();
+            expect(stats.size).toBeGreaterThan(0);
+        });
+        test('should clear cache even if errors occurred', () => {
+            const cache = getGlobalAddressCache();
+            // Add some valid entries
+            parseDocumentAddress('/test/doc1.md');
+            // Try invalid entry
+            try {
+                parseDocumentAddress('');
+            }
+            catch {
+                // Expected error
+            }
+            // Clear should work regardless
+            cache.clearBatch();
+            const stats = cache.getBatchStats();
+            expect(stats.size).toBe(0);
+        });
+        test('should handle concurrent parsing without corruption', () => {
+            const cache = getGlobalAddressCache();
+            // Parse multiple addresses rapidly
+            const docs = ['/test/doc1.md', '/test/doc2.md', '/test/doc3.md'];
+            docs.forEach(doc => parseDocumentAddress(doc));
+            const stats = cache.getBatchStats();
+            expect(stats.size).toBe(docs.length);
+            // All should be parseable again
+            docs.forEach(doc => {
+                const addr = parseDocumentAddress(doc);
+                expect(addr.path).toBe(doc);
+            });
+        });
+    });
+    describe('Backward compatibility', () => {
+        test('should maintain same address parsing behavior', () => {
+            // Document parsing
+            const doc = parseDocumentAddress('/test/doc.md');
+            expect(doc.path).toBe('/test/doc.md');
+            expect(doc.slug).toBe('doc');
+            expect(doc.namespace).toBe('test');
+            // Section parsing
+            const section = parseSectionAddress('overview', '/test/doc.md');
+            expect(section.slug).toBe('overview');
+            expect(section.fullPath).toBe('/test/doc.md#overview');
+            // Task parsing
+            const task = parseTaskAddress('setup', '/test/tasks.md');
+            expect(task.slug).toBe('setup');
+            expect(task.isTask).toBe(true);
+        });
+        test('should support all existing address formats', () => {
+            // Test all section reference formats
+            const formats = [
+                { input: 'section', context: '/test/doc.md', expected: 'section' },
+                { input: '#section', context: '/test/doc.md', expected: 'section' },
+                { input: '/test/doc.md#section', context: undefined, expected: 'section' }
+            ];
+            formats.forEach(({ input, context, expected }) => {
+                const addr = parseSectionAddress(input, context);
+                expect(addr.slug).toBe(expected);
+            });
+        });
+        test('should support hierarchical addressing', () => {
+            // Hierarchical section
+            const hierarchical = parseSectionAddress('api/authentication/jwt', '/test/api.md');
+            expect(hierarchical.slug).toBe('api/authentication/jwt');
+            expect(hierarchical.fullPath).toBe('/test/api.md#api/authentication/jwt');
+            // Should be cached
+            const cached = parseSectionAddress('api/authentication/jwt', '/test/api.md');
+            expect(cached.slug).toBe(hierarchical.slug);
+            // Verify cache has the entry
+            const cache = getGlobalAddressCache();
+            const stats = cache.getBatchStats();
+            expect(stats.size).toBeGreaterThan(0);
+        });
+        test('should maintain cache invalidation behavior', () => {
+            // Parse document and sections
+            parseDocumentAddress('/test/doc.md');
+            parseSectionAddress('section1', '/test/doc.md');
+            const cache = getGlobalAddressCache();
+            const statsBefore = cache.getBatchStats();
+            expect(statsBefore.size).toBeGreaterThan(0);
+            // Invalidate should still work (clears batch cache for document)
+            invalidateAddressCache('/test/doc.md');
+            // Can still parse addresses
+            const addr = parseDocumentAddress('/test/doc.md');
+            expect(addr.path).toBe('/test/doc.md');
+        });
+    });
+    describe('Tool integration with batch cache', () => {
+        test('should support ToolIntegration.clearBatchCache', () => {
+            const cache = getGlobalAddressCache();
+            // Populate cache via ToolIntegration
+            ToolIntegration.validateAndParse({
+                document: '/test/doc.md',
+                section: 'overview'
+            });
+            const statsBefore = cache.getBatchStats();
+            expect(statsBefore.size).toBeGreaterThan(0);
+            // Clear via ToolIntegration
+            ToolIntegration.clearBatchCache();
+            const statsAfter = cache.getBatchStats();
+            expect(statsAfter.size).toBe(0);
+        });
+        test('should clear cache between batch operations', () => {
+            const cache = getGlobalAddressCache();
+            // Batch 1
+            ToolIntegration.validateAndParse({
+                document: '/test/doc1.md',
+                section: 'section1'
+            });
+            const stats1 = cache.getBatchStats();
+            expect(stats1.size).toBeGreaterThan(0);
+            // Clear batch
+            ToolIntegration.clearBatchCache();
+            // Batch 2
+            ToolIntegration.validateAndParse({
+                document: '/test/doc2.md',
+                section: 'section2'
+            });
+            const stats2 = cache.getBatchStats();
+            // Should not contain doc1
+            expect(stats2.keys).not.toContain('/test/doc1.md');
+        });
+    });
+    describe('Performance characteristics', () => {
+        test('should cache repeated address parsing efficiently', () => {
+            // Parse same address multiple times
+            const iterations = 100;
+            const docPath = '/test/heavy-doc.md';
+            for (let i = 0; i < iterations; i++) {
+                parseDocumentAddress(docPath);
+            }
+            // Cache should only have one entry despite 100 parses
+            const cache = getGlobalAddressCache();
+            const stats = cache.getBatchStats();
+            expect(stats.size).toBe(1);
+            expect(stats.keys).toContain(docPath);
+        });
+        test('should handle batch operations without memory leak', () => {
+            const cache = getGlobalAddressCache();
+            // Simulate multiple batch cycles
+            for (let batch = 0; batch < 10; batch++) {
+                // Create batch entries
+                for (let i = 0; i < 10; i++) {
+                    parseDocumentAddress(`/test/batch${batch}/doc${i}.md`);
+                }
+                // Clear batch
+                cache.clearBatch();
+            }
+            // Final cache should be empty (no persistent accumulation)
+            const finalStats = cache.getBatchStats();
+            expect(finalStats.size).toBe(0);
+        });
+        test('should not have size limit like LRU cache', () => {
+            const cache = getGlobalAddressCache();
+            // Create many entries in single batch (no eviction expected)
+            const largeCount = 50;
+            for (let i = 0; i < largeCount; i++) {
+                parseDocumentAddress(`/test/doc${i}.md`);
+            }
+            const stats = cache.getBatchStats();
+            // Should have all entries (no eviction at 1000 or any limit)
+            expect(stats.size).toBe(largeCount);
+        });
+    });
+});
+//# sourceMappingURL=addressing-system.batch-cache.test.js.map

package/dist/shared/__tests__/addressing-system.batch-cache.test.js.map

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

package/dist/shared/__tests__/addressing-system.hierarchical.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * TDD-first tests for hierarchical addressing system enhancements
+ * Phase 3: These tests verify parseSectionAddress and parseTaskAddress support hierarchical slugs
+ */
+export {};
+//# sourceMappingURL=addressing-system.hierarchical.test.d.ts.map

package/dist/shared/__tests__/addressing-system.hierarchical.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressing-system.hierarchical.test.d.ts","sourceRoot":"","sources":["../../../src/shared/__tests__/addressing-system.hierarchical.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/shared/__tests__/addressing-system.hierarchical.test.js

@@ -0,0 +1,205 @@
+/**
+ * TDD-first tests for hierarchical addressing system enhancements
+ * Phase 3: These tests verify parseSectionAddress and parseTaskAddress support hierarchical slugs
+ */
+import { describe, test, expect, beforeAll, afterAll } from 'vitest';
+import { parseSectionAddress, parseTaskAddress, InvalidAddressError, ToolIntegration } from '../addressing-system.js';
+import { normalizeSlugPath } from '../slug-utils.js';
+import { initializeGlobalCache, getGlobalCache } from '../../document-cache.js';
+// Test data setup - documents root for testing
+const docsRoot = '/tmp/claude/test-docs-addressing';
+beforeAll(async () => {
+    // Initialize the global cache for addressing system tests
+    initializeGlobalCache(docsRoot);
+});
+afterAll(() => {
+    // Clean up after tests
+    const cache = getGlobalCache();
+    cache.clear();
+});
+describe('Addressing System - Hierarchical Support', () => {
+    describe('normalizeHierarchicalSlug helper', () => {
+        test('should normalize hierarchical path components', () => {
+            // Test hierarchical path normalization using slug-utils
+            const result = normalizeSlugPath('api//authentication///jwt-tokens');
+            expect(result).toBe('api/authentication/jwt-tokens');
+        });
+        test('should handle # prefix removal for hierarchical paths', () => {
+            // Test that # prefix is properly removed before normalization
+            const input = '#api/authentication/jwt-tokens';
+            const withoutHash = input.startsWith('#') ? input.substring(1) : input;
+            const result = normalizeSlugPath(withoutHash);
+            expect(result).toBe('api/authentication/jwt-tokens');
+        });
+        test('should handle flat slugs without modification', () => {
+            // Test that simple flat slugs are not broken by hierarchical processing
+            const result = normalizeSlugPath('authentication');
+            expect(result).toBe('authentication');
+        });
+        test('should handle edge cases gracefully', () => {
+            // Test various edge cases
+            expect(normalizeSlugPath('')).toBe('');
+            expect(normalizeSlugPath('///')).toBe('');
+            expect(normalizeSlugPath('api/')).toBe('api');
+            expect(normalizeSlugPath('/api')).toBe('api');
+        });
+    });
+    describe('parseSectionAddress with hierarchical paths', () => {
+        test('should parse simple hierarchical paths with context document', async () => {
+            // Test: 'api/authentication' with context document
+            const result = parseSectionAddress('api/authentication', '/docs/api.md');
+            expect(result.document.path).toBe('/docs/api.md');
+            expect(result.slug).toBe('api/authentication');
+            expect(result.fullPath).toBe('/docs/api.md#api/authentication');
+            expect(result.cacheKey).toBe('api/authentication|/docs/api.md');
+        });
+        test('should parse hierarchical paths with # prefix', async () => {
+            // Test: '#api/authentication/jwt-tokens' with context document
+            const result = parseSectionAddress('#api/authentication/jwt-tokens', '/docs/api.md');
+            expect(result.document.path).toBe('/docs/api.md');
+            expect(result.slug).toBe('api/authentication/jwt-tokens');
+            expect(result.fullPath).toBe('/docs/api.md#api/authentication/jwt-tokens');
+            expect(result.cacheKey).toBe('#api/authentication/jwt-tokens|/docs/api.md');
+        });
+        test('should parse full document+hierarchical paths', async () => {
+            // Test: '/docs/api.md#api/authentication/tokens' format
+            const result = parseSectionAddress('/docs/api.md#api/authentication/tokens');
+            expect(result.document.path).toBe('/docs/api.md');
+            expect(result.slug).toBe('api/authentication/tokens');
+            expect(result.fullPath).toBe('/docs/api.md#api/authentication/tokens');
+            expect(result.cacheKey).toBe('/docs/api.md#api/authentication/tokens|');
+        });
+        test('should normalize hierarchical path components', async () => {
+            // Test normalization of paths with extra slashes and case issues
+            const result = parseSectionAddress('#api//authentication///jwt-tokens', '/docs/api.md');
+            expect(result.slug).toBe('api/authentication/jwt-tokens');
+            expect(result.fullPath).toBe('/docs/api.md#api/authentication/jwt-tokens');
+        });
+        test('should handle deeply nested hierarchical paths', async () => {
+            // Test deep hierarchical nesting
+            const deepPath = 'specs/api/forms/authentication/login/validation';
+            const result = parseSectionAddress(deepPath, '/docs/specs.md');
+            expect(result.slug).toBe(deepPath);
+            expect(result.fullPath).toBe(`/docs/specs.md#${deepPath}`);
+        });
+        test('should maintain backward compatibility with flat slugs', async () => {
+            // Test that existing flat addressing still works perfectly
+            const result = parseSectionAddress('authentication', '/docs/api.md');
+            expect(result.slug).toBe('authentication');
+            expect(result.fullPath).toBe('/docs/api.md#authentication');
+            expect(result.cacheKey).toBe('authentication|/docs/api.md');
+        });
+        test('should handle mixed flat and hierarchical in same operation', async () => {
+            // Test that both patterns can coexist
+            const flatResult = parseSectionAddress('overview', '/docs/api.md');
+            const hierarchicalResult = parseSectionAddress('api/authentication/overview', '/docs/api.md');
+            expect(flatResult.slug).toBe('overview');
+            expect(hierarchicalResult.slug).toBe('api/authentication/overview');
+            expect(flatResult.document.path).toBe(hierarchicalResult.document.path);
+        });
+        test('should handle edge cases for hierarchical paths', async () => {
+            // Test various edge cases that could break hierarchical parsing
+            // Empty hierarchical segment
+            await expect(async () => parseSectionAddress('#/', '/docs/api.md')).rejects.toThrow(InvalidAddressError);
+            // Multiple # characters
+            const multiHashResult = parseSectionAddress('/docs/api.md#section#with#hash', undefined);
+            expect(multiHashResult.slug).toBe('section#with#hash');
+            // Very long hierarchical path
+            const longPath = 'a/b/c/d/e/f/g/h/i/j';
+            const longResult = parseSectionAddress(longPath, '/docs/test.md');
+            expect(longResult.slug).toBe(longPath);
+        });
+        test('should throw appropriate errors for invalid hierarchical paths', async () => {
+            // Test error handling for invalid cases
+            await expect(async () => parseSectionAddress('#', '/docs/api.md')).rejects.toThrow(InvalidAddressError);
+            await expect(async () => parseSectionAddress('api/auth', undefined)).rejects.toThrow(InvalidAddressError);
+            await expect(async () => parseSectionAddress('#api/auth')).rejects.toThrow(InvalidAddressError);
+        });
+    });
+    describe('parseTaskAddress with hierarchical paths', () => {
+        test('should parse hierarchical task addresses', async () => {
+            // Test that parseTaskAddress works with hierarchical paths
+            const result = parseTaskAddress('setup/backend/database-migration', '/docs/tasks.md');
+            expect(result.document.path).toBe('/docs/tasks.md');
+            expect(result.slug).toBe('setup/backend/database-migration');
+            expect(result.fullPath).toBe('/docs/tasks.md#setup/backend/database-migration');
+            expect(result.isTask).toBe(true);
+            expect(result.cacheKey).toBe('task:setup/backend/database-migration|/docs/tasks.md');
+        });
+        test('should handle hierarchical task addresses with # prefix', async () => {
+            // Test hierarchical task parsing with # prefix
+            const result = parseTaskAddress('#project/frontend/setup-authentication', '/docs/project.md');
+            expect(result.slug).toBe('project/frontend/setup-authentication');
+            expect(result.isTask).toBe(true);
+            expect(result.fullPath).toBe('/docs/project.md#project/frontend/setup-authentication');
+        });
+    });
+    describe('SectionAddress with hierarchical slugs', () => {
+        test('should create proper cache keys for hierarchical addresses', async () => {
+            // Test that cache keys are properly formed for hierarchical addresses
+            const result = parseSectionAddress('api/auth/tokens', '/docs/api.md');
+            expect(result.cacheKey).toBe('api/auth/tokens|/docs/api.md');
+            expect(typeof result.cacheKey).toBe('string');
+            expect(result.cacheKey.length).toBeGreaterThan(0);
+        });
+        test('should create correct fullPath with hierarchical slugs', async () => {
+            // Test fullPath formatting for hierarchical addresses
+            const testCases = [
+                {
+                    input: 'api/authentication',
+                    context: '/docs/api.md',
+                    expected: '/docs/api.md#api/authentication'
+                },
+                {
+                    input: '#specs/api/forms',
+                    context: '/docs/specs.md',
+                    expected: '/docs/specs.md#specs/api/forms'
+                },
+                {
+                    input: '/docs/backend.md#database/migrations/setup',
+                    context: undefined,
+                    expected: '/docs/backend.md#database/migrations/setup'
+                }
+            ];
+            for (const testCase of testCases) {
+                const result = parseSectionAddress(testCase.input, testCase.context);
+                expect(result.fullPath).toBe(testCase.expected);
+            }
+        });
+    });
+    describe('ToolIntegration.validateAndParse with hierarchical support', () => {
+        test('should handle hierarchical section parsing in tool integration', async () => {
+            // Test that ToolIntegration can handle hierarchical addresses
+            const result = ToolIntegration.validateAndParse({
+                document: '/docs/api.md',
+                section: 'api/authentication/jwt-tokens'
+            });
+            expect(result.addresses.document.path).toBe('/docs/api.md');
+            expect(result.addresses.section?.slug).toBe('api/authentication/jwt-tokens');
+            expect(result.addresses.section?.fullPath).toBe('/docs/api.md#api/authentication/jwt-tokens');
+        });
+        test('should maintain backward compatibility in tool integration', async () => {
+            // Test that flat addressing still works through ToolIntegration
+            const result = ToolIntegration.validateAndParse({
+                document: '/docs/api.md',
+                section: 'authentication'
+            });
+            expect(result.addresses.section?.slug).toBe('authentication');
+            expect(result.addresses.section?.fullPath).toBe('/docs/api.md#authentication');
+        });
+        test('should handle mixed addressing patterns in tool integration', async () => {
+            // Test that tools can work with both patterns simultaneously
+            const flatResult = ToolIntegration.validateAndParse({
+                document: '/docs/api.md',
+                section: 'overview'
+            });
+            const hierarchicalResult = ToolIntegration.validateAndParse({
+                document: '/docs/api.md',
+                section: 'api/endpoints/users'
+            });
+            expect(flatResult.addresses.section?.slug).toBe('overview');
+            expect(hierarchicalResult.addresses.section?.slug).toBe('api/endpoints/users');
+        });
+    });
+});
+//# sourceMappingURL=addressing-system.hierarchical.test.js.map

package/dist/shared/__tests__/addressing-system.hierarchical.test.js.map

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

package/dist/shared/__tests__/addressing-system.lru.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tests for LRU cache implementation in addressing system
+ * These tests verify that the cache correctly maintains access order and evicts least recently used items
+ */
+export {};
+//# sourceMappingURL=addressing-system.lru.test.d.ts.map

package/dist/shared/__tests__/addressing-system.lru.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressing-system.lru.test.d.ts","sourceRoot":"","sources":["../../../src/shared/__tests__/addressing-system.lru.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}