ai-prompt-guide-mcp 1.0.0

package/dist/tools/__tests__/create-document-workflow-regression.test.js

@@ -0,0 +1,655 @@
+/**
+ * Comprehensive regression tests for create-document workflow Stage 2.5
+ *
+ * Tests the complete enhanced document discovery system including:
+ * - Multi-factor relevance scoring
+ * - Enhanced keyword extraction with frontmatter support
+ * - Structured broken reference detection
+ * - Factor-based explanation generation
+ * - Fingerprint-based performance optimization
+ * - Integration between all enhanced components
+ *
+ * This test suite ensures that the Stage 1-4 enhancements work correctly
+ * in the complete create-document workflow, providing regression protection.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { processSuggestions } from '../create/suggestion-generator.js';
+// Mock the utilities module
+vi.mock('../../shared/utilities.js', () => ({
+    getDocumentManager: vi.fn(),
+    analyzeDocumentSuggestions: vi.fn(),
+    analyzeNamespacePatterns: vi.fn()
+}));
+import { getDocumentManager, analyzeDocumentSuggestions, analyzeNamespacePatterns } from '../../shared/utilities.js';
+// Type the mocked functions
+const mockGetDocumentManager = getDocumentManager;
+const mockAnalyzeDocumentSuggestions = analyzeDocumentSuggestions;
+const mockAnalyzeNamespacePatterns = analyzeNamespacePatterns;
+// Test data builders for realistic scenarios
+const createMockFingerprint = (overrides = {}) => ({
+    keywords: ['test', 'document', 'content'],
+    lastModified: new Date('2023-12-01T10:00:00Z'),
+    contentHash: 'test-hash',
+    namespace: 'test',
+    ...overrides
+});
+const createMockDocumentManager = () => {
+    const mockManager = {
+        listDocuments: vi.fn(),
+        getDocument: vi.fn(),
+        getDocumentContent: vi.fn(),
+        getSectionContent: vi.fn(),
+        addDocument: vi.fn(),
+        updateDocument: vi.fn(),
+        deleteDocument: vi.fn(),
+        archiveDocument: vi.fn(),
+        createSection: vi.fn(),
+        updateSection: vi.fn(),
+        deleteSection: vi.fn(),
+        moveDocument: vi.fn(),
+        renameDocument: vi.fn(),
+        // Enhanced methods for fingerprint support
+        listDocumentFingerprints: vi.fn()
+    };
+    return mockManager;
+};
+describe('Create Document Workflow Stage 2.5 - Regression Tests', () => {
+    let tempDir;
+    let mockManager;
+    beforeEach(async () => {
+        // Create temporary directory for test files
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'create-document-workflow-regression-test-'));
+        // Configure MCP_WORKSPACE_PATH for fsio PathHandler to use temp directory
+        process.env['MCP_WORKSPACE_PATH'] = tempDir;
+        mockManager = createMockDocumentManager();
+        vi.clearAllMocks();
+        // Default successful mocks
+        mockGetDocumentManager.mockResolvedValue(mockManager);
+        mockAnalyzeNamespacePatterns.mockResolvedValue({
+            common_sections: ['Overview', 'Getting Started'],
+            frequent_links: ['/api/auth.md'],
+            typical_tasks: ['Setup authentication']
+        });
+    });
+    afterEach(async () => {
+        // Clean up temporary directory and all its contents
+        try {
+            await fs.rm(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore if directory doesn't exist
+        }
+    });
+    describe('Enhanced Multi-Factor Relevance Scoring', () => {
+        it('should return suggestions with factor-based explanations', async () => {
+            const enhancedSuggestions = {
+                related_documents: [
+                    {
+                        path: '/api/auth/oauth.md',
+                        title: 'OAuth 2.0 Implementation',
+                        namespace: 'api/auth',
+                        reason: 'Strong keyword overlap with same namespace structure',
+                        relevance: 0.95
+                    },
+                    {
+                        path: '/api/auth/jwt.md',
+                        title: 'JWT Token Management',
+                        namespace: 'api/auth',
+                        reason: 'Good keyword overlap with related namespace structure',
+                        relevance: 0.73
+                    },
+                    {
+                        path: '/guides/security.md',
+                        title: 'Security Best Practices',
+                        namespace: 'guides',
+                        reason: 'Shared keywords with recent updates',
+                        relevance: 0.47
+                    }
+                ],
+                broken_references: []
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(enhancedSuggestions);
+            const result = await processSuggestions('api/auth', 'OAuth 2.0 Client Authentication', '---\nkeywords: [oauth, authentication, jwt, api, security]\n---\n\nImplementation guide for OAuth 2.0 client authentication flow with JWT tokens.');
+            expect(result.stage).toBe('smart_suggestions');
+            const smartResult = result;
+            // Verify enhanced factor-based explanations
+            expect(smartResult.suggestions.related_documents).toHaveLength(3);
+            const oauthDoc = smartResult.suggestions.related_documents[0];
+            expect(oauthDoc).toEqual(expect.objectContaining({
+                path: '/api/auth/oauth.md',
+                title: 'OAuth 2.0 Implementation',
+                namespace: 'api/auth',
+                reason: 'Strong keyword overlap with same namespace structure',
+                relevance: 0.95
+            }));
+            // Verify factor-based reasons explain actual contributing factors
+            expect(oauthDoc?.reason).toMatch(/keyword overlap/);
+            expect(oauthDoc?.reason).toMatch(/namespace/);
+            const jwtDoc = smartResult.suggestions.related_documents[1];
+            expect(jwtDoc?.reason).toMatch(/keyword overlap/);
+            expect(jwtDoc?.reason).toMatch(/namespace/);
+            const securityDoc = smartResult.suggestions.related_documents[2];
+            expect(securityDoc?.reason).toMatch(/keywords/);
+            expect(securityDoc?.reason).toMatch(/recent/);
+        });
+        it('should handle enhanced keyword extraction from frontmatter', async () => {
+            const frontmatterEnhancedSuggestions = {
+                related_documents: [
+                    {
+                        path: '/api/auth.md',
+                        title: 'Authentication API',
+                        namespace: 'api',
+                        reason: 'Explicit keyword matches in api namespace',
+                        relevance: 0.88
+                    }
+                ],
+                broken_references: []
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(frontmatterEnhancedSuggestions);
+            const result = await processSuggestions('api/guides', 'User Authentication Guide', '---\nkeywords: [authentication, users, api, security, login]\ndescription: Complete guide for user authentication\n---\n\n# User Authentication\n\nThis guide covers **important** authentication concepts.');
+            const smartResult = result;
+            // Verify frontmatter keywords are recognized
+            const authDoc = smartResult.suggestions.related_documents[0];
+            expect(authDoc?.reason).toMatch(/explicit keyword matches/i);
+            expect(authDoc?.relevance).toBeGreaterThan(0.8); // High relevance from explicit keywords
+        });
+        it('should demonstrate namespace affinity scoring', async () => {
+            const namespaceAffinitySuggestions = {
+                related_documents: [
+                    {
+                        path: '/specs/auth-api.md',
+                        title: 'Authentication API Specification',
+                        namespace: 'specs',
+                        reason: 'Good keyword overlap with same namespace',
+                        relevance: 0.82
+                    },
+                    {
+                        path: '/specs/setup.md',
+                        title: 'API Setup Guide',
+                        namespace: 'specs',
+                        reason: 'Shared keywords with same namespace structure',
+                        relevance: 0.78
+                    },
+                    {
+                        path: '/reviews/auth.md',
+                        title: 'Authentication Review',
+                        namespace: 'reviews',
+                        reason: 'Shared keywords',
+                        relevance: 0.35
+                    }
+                ],
+                broken_references: []
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(namespaceAffinitySuggestions);
+            const result = await processSuggestions('specs', 'Authentication Implementation', 'Guide for implementing authentication in API applications');
+            const smartResult = result;
+            // Verify namespace affinity is reflected in relevance and explanations
+            const specDoc1 = smartResult.suggestions.related_documents.find(d => d.path === '/specs/auth-api.md');
+            const specDoc2 = smartResult.suggestions.related_documents.find(d => d.path === '/specs/setup.md');
+            const reviewDoc = smartResult.suggestions.related_documents.find(d => d.namespace === 'reviews');
+            // Same namespace documents should have higher relevance
+            expect(specDoc1?.relevance).toBeGreaterThan(reviewDoc?.relevance ?? 0);
+            expect(specDoc2?.relevance).toBeGreaterThan(reviewDoc?.relevance ?? 0);
+            // Explanations should reflect namespace relationships
+            expect(specDoc1?.reason).toMatch(/same namespace|namespace/);
+            expect(specDoc2?.reason).toMatch(/same namespace|namespace structure/);
+            expect(reviewDoc?.reason).not.toMatch(/same namespace/); // Different namespace
+        });
+        it('should demonstrate recency boost in scoring', async () => {
+            const recentUpdatesSuggestions = {
+                related_documents: [
+                    {
+                        path: '/guides/latest-auth.md',
+                        title: 'Latest Authentication Methods',
+                        namespace: 'guides',
+                        reason: 'Shared keywords with recent updates',
+                        relevance: 0.65
+                    },
+                    {
+                        path: '/guides/old-auth.md',
+                        title: 'Authentication Overview',
+                        namespace: 'guides',
+                        reason: 'Shared keywords',
+                        relevance: 0.52
+                    }
+                ],
+                broken_references: []
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(recentUpdatesSuggestions);
+            const result = await processSuggestions('guides', 'Modern Authentication', 'Overview of modern authentication approaches');
+            const smartResult = result;
+            // Verify recency boost is reflected
+            const recentDoc = smartResult.suggestions.related_documents.find(d => d.path === '/guides/latest-auth.md');
+            const oldDoc = smartResult.suggestions.related_documents.find(d => d.path === '/guides/old-auth.md');
+            expect(recentDoc?.relevance).toBeGreaterThan(oldDoc?.relevance ?? 0);
+            expect(recentDoc?.reason).toMatch(/recent/);
+            expect(oldDoc?.reason).not.toMatch(/recent/);
+        });
+    });
+    describe('Structured Broken Reference Detection', () => {
+        it('should detect and classify all types of broken references', async () => {
+            const comprehensiveBrokenRefs = {
+                related_documents: [],
+                broken_references: [
+                    // Missing document type
+                    {
+                        reference: '@/missing/document.md',
+                        type: 'missing_document',
+                        documentPath: '/missing/document.md',
+                        reason: 'Document not found: /missing/document.md'
+                    },
+                    // Missing document with section
+                    {
+                        reference: '@/missing/doc.md#section',
+                        type: 'missing_document',
+                        documentPath: '/missing/doc.md',
+                        sectionSlug: 'section',
+                        reason: 'Document not found: /missing/doc.md'
+                    },
+                    // Missing section in existing document
+                    {
+                        reference: '@/api/auth.md#nonexistent-section',
+                        type: 'missing_section',
+                        documentPath: '/api/auth.md',
+                        sectionSlug: 'nonexistent-section',
+                        reason: "Section 'nonexistent-section' not found in document /api/auth.md"
+                    },
+                    // Malformed reference
+                    {
+                        reference: '@malformed-ref',
+                        type: 'malformed',
+                        reason: 'Failed to parse reference: Invalid reference format'
+                    },
+                    // Relative reference converted to absolute
+                    {
+                        reference: '@relative-doc',
+                        type: 'missing_document',
+                        documentPath: '/relative-doc.md',
+                        reason: 'Document not found: /relative-doc.md'
+                    }
+                ]
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(comprehensiveBrokenRefs);
+            const result = await processSuggestions('api', 'Reference Test Document', 'Document with various reference types: @/missing/document.md @/api/auth.md#nonexistent-section @malformed-ref @relative-doc');
+            const smartResult = result;
+            expect(smartResult.suggestions.broken_references).toHaveLength(5);
+            // Verify missing document type
+            const missingDocRefs = smartResult.suggestions.broken_references.filter(ref => ref.type === 'missing_document');
+            expect(missingDocRefs).toHaveLength(3);
+            for (const ref of missingDocRefs) {
+                expect(ref.documentPath).toBeDefined();
+                expect(ref.reason).toContain('Document not found');
+            }
+            // Verify missing section type
+            const missingSectionRefs = smartResult.suggestions.broken_references.filter(ref => ref.type === 'missing_section');
+            expect(missingSectionRefs).toHaveLength(1);
+            const missingSectionRef = missingSectionRefs[0];
+            expect(missingSectionRef?.documentPath).toBe('/api/auth.md');
+            expect(missingSectionRef?.sectionSlug).toBe('nonexistent-section');
+            expect(missingSectionRef?.reason).toContain("Section 'nonexistent-section' not found");
+            // Verify malformed type
+            const malformedRefs = smartResult.suggestions.broken_references.filter(ref => ref.type === 'malformed');
+            expect(malformedRefs).toHaveLength(1);
+            const malformedRef = malformedRefs[0];
+            expect(malformedRef?.reason).toContain('Failed to parse reference');
+            expect(malformedRef?.documentPath).toBeUndefined(); // Malformed refs may not have valid paths
+            // Verify all references have required fields
+            for (const ref of smartResult.suggestions.broken_references) {
+                expect(ref.reference).toBeDefined();
+                expect(ref.type).toBeOneOf(['missing_document', 'missing_section', 'malformed']);
+                expect(ref.reason).toBeDefined();
+                expect(typeof ref.reason).toBe('string');
+                expect(ref.reason.length).toBeGreaterThan(0);
+            }
+        });
+        it('should handle complex broken reference scenarios with shared reference system', async () => {
+            const complexBrokenRefs = {
+                related_documents: [],
+                broken_references: [
+                    {
+                        reference: '@/api/v1/deprecated.md',
+                        type: 'missing_document',
+                        documentPath: '/api/v1/deprecated.md',
+                        reason: 'Document not found: /api/v1/deprecated.md'
+                    },
+                    {
+                        reference: '@/config/settings.md#database',
+                        type: 'missing_section',
+                        documentPath: '/config/settings.md',
+                        sectionSlug: 'database',
+                        reason: "Section 'database' not found in document /config/settings.md"
+                    },
+                    {
+                        reference: '@invalid-format-[test]',
+                        type: 'malformed',
+                        reason: 'Failed to parse reference: Invalid reference format'
+                    }
+                ]
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(complexBrokenRefs);
+            const result = await processSuggestions('api', 'Migration Guide', 'Migration guide with references: @/api/v1/deprecated.md @/config/settings.md#database @invalid-format-[test]');
+            const smartResult = result;
+            // Verify comprehensive broken reference handling
+            expect(smartResult.suggestions.broken_references).toHaveLength(3);
+            // Check specific reference by path
+            const deprecatedRef = smartResult.suggestions.broken_references.find(ref => ref.reference === '@/api/v1/deprecated.md');
+            expect(deprecatedRef).toEqual(expect.objectContaining({
+                reference: '@/api/v1/deprecated.md',
+                type: 'missing_document',
+                documentPath: '/api/v1/deprecated.md',
+                reason: 'Document not found: /api/v1/deprecated.md'
+            }));
+            // Check section-specific reference
+            const sectionRef = smartResult.suggestions.broken_references.find(ref => ref.reference === '@/config/settings.md#database');
+            expect(sectionRef).toEqual(expect.objectContaining({
+                reference: '@/config/settings.md#database',
+                type: 'missing_section',
+                documentPath: '/config/settings.md',
+                sectionSlug: 'database',
+                reason: "Section 'database' not found in document /config/settings.md"
+            }));
+            // Check malformed reference
+            const malformedRef = smartResult.suggestions.broken_references.find(ref => ref.reference === '@invalid-format-[test]');
+            expect(malformedRef?.type).toBe('malformed');
+        });
+    });
+    describe('Integration and Performance Regression Tests', () => {
+        it('should handle fingerprint-based optimization without degrading results', async () => {
+            // Mock manager with fingerprint support
+            const mockManagerWithFingerprints = createMockDocumentManager();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            mockManagerWithFingerprints.listDocumentFingerprints = vi.fn().mockResolvedValue([
+                createMockFingerprint({
+                    keywords: ['authentication', 'oauth', 'api'],
+                    namespace: 'api/auth',
+                    contentHash: 'fingerprint1'
+                }),
+                createMockFingerprint({
+                    keywords: ['security', 'auth', 'tokens'],
+                    namespace: 'security',
+                    contentHash: 'fingerprint2'
+                })
+            ]);
+            mockGetDocumentManager.mockResolvedValue(mockManagerWithFingerprints);
+            const fingerprintOptimizedSuggestions = {
+                related_documents: [
+                    {
+                        path: '/api/auth/oauth.md',
+                        title: 'OAuth Implementation',
+                        namespace: 'api/auth',
+                        reason: 'Strong keyword overlap with same namespace structure (fingerprint-optimized)',
+                        relevance: 0.91
+                    },
+                    {
+                        path: '/security/tokens.md',
+                        title: 'Token Security',
+                        namespace: 'security',
+                        reason: 'Good keyword overlap',
+                        relevance: 0.67
+                    }
+                ],
+                broken_references: []
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(fingerprintOptimizedSuggestions);
+            const startTime = Date.now();
+            const result = await processSuggestions('api/auth', 'OAuth Authentication', '---\nkeywords: [oauth, authentication, api, security]\n---\n\nOAuth 2.0 authentication implementation');
+            const duration = Date.now() - startTime;
+            const smartResult = result;
+            // Verify results are not degraded by optimization
+            expect(smartResult.suggestions.related_documents).toHaveLength(2);
+            expect(smartResult.suggestions.related_documents[0]?.relevance).toBeGreaterThan(0.9);
+            // Verify performance characteristics (should complete quickly)
+            expect(duration).toBeLessThan(100); // Should complete in reasonable time
+            // Note: In this test, we're mocking the analyzeDocumentSuggestions function,
+            // so the actual fingerprint optimization happens inside that mocked function.
+            // The test verifies the results are as expected from fingerprint optimization.
+            // The actual fingerprint method calls would be tested in the document-analysis tests.
+        });
+        it('should gracefully fall back when fingerprint optimization fails', async () => {
+            // Mock manager with failing fingerprint support
+            const mockManagerWithFailingFingerprints = createMockDocumentManager();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            mockManagerWithFailingFingerprints.listDocumentFingerprints = vi.fn().mockRejectedValue(new Error('Fingerprint system unavailable'));
+            mockGetDocumentManager.mockResolvedValue(mockManagerWithFailingFingerprints);
+            const fallbackSuggestions = {
+                related_documents: [
+                    {
+                        path: '/api/auth.md',
+                        title: 'Authentication API',
+                        namespace: 'api',
+                        reason: 'Related documentation in api (fallback analysis)',
+                        relevance: 0.75
+                    }
+                ],
+                broken_references: []
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(fallbackSuggestions);
+            const result = await processSuggestions('api', 'API Authentication', 'Authentication guide for API applications');
+            const smartResult = result;
+            // Verify graceful fallback
+            expect(smartResult.suggestions.related_documents).toHaveLength(1);
+            expect(smartResult.suggestions.related_documents[0]?.reason).toContain('fallback');
+            expect(result.stage).toBe('smart_suggestions'); // Should still complete successfully
+        });
+        it('should maintain backward compatibility with existing create-document behavior', async () => {
+            // Test with minimal/basic suggestions that would come from original implementation
+            const basicCompatibilitySuggestions = {
+                related_documents: [
+                    {
+                        path: '/api/docs.md',
+                        title: 'API Documentation',
+                        namespace: 'api',
+                        reason: 'Related documentation in api',
+                        relevance: 0.6
+                    }
+                ],
+                broken_references: []
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(basicCompatibilitySuggestions);
+            const result = await processSuggestions('api', 'Simple API Guide', 'Basic API documentation');
+            // Verify basic compatibility structure
+            expect(result.stage).toBe('smart_suggestions');
+            const smartResult = result;
+            expect(smartResult.suggestions).toHaveProperty('related_documents');
+            expect(smartResult.suggestions).toHaveProperty('broken_references');
+            expect(smartResult.namespace_patterns).toHaveProperty('common_sections');
+            expect(smartResult.next_step).toContain("create: true");
+            expect(smartResult.example).toEqual({
+                namespace: 'api',
+                title: 'Simple API Guide',
+                overview: 'Basic API documentation',
+                create: true
+            });
+            // Should work with simple suggestions
+            expect(smartResult.suggestions.related_documents[0]).toEqual(expect.objectContaining({
+                path: '/api/docs.md',
+                title: 'API Documentation',
+                namespace: 'api',
+                reason: 'Related documentation in api',
+                relevance: 0.6
+            }));
+        });
+        it('should handle concurrent suggestion analysis efficiently', async () => {
+            const mockSuggestions = {
+                related_documents: [
+                    {
+                        path: '/test/doc.md',
+                        title: 'Test Document',
+                        namespace: 'test',
+                        reason: 'Test documentation',
+                        relevance: 0.5
+                    }
+                ],
+                broken_references: []
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(mockSuggestions);
+            // Simulate multiple parallel calls to test concurrency
+            const promises = Array.from({ length: 3 }, (_, i) => processSuggestions(`namespace-${i}`, `Document ${i}`, `Overview for document ${i}`));
+            const startTime = Date.now();
+            const results = await Promise.all(promises);
+            const duration = Date.now() - startTime;
+            // All should complete successfully
+            expect(results).toHaveLength(3);
+            results.forEach((result, i) => {
+                expect(result.stage).toBe('smart_suggestions');
+                const smartResult = result;
+                expect(smartResult.example.namespace).toBe(`namespace-${i}`);
+            });
+            // Should handle concurrency efficiently
+            expect(duration).toBeLessThan(500); // Reasonable time for 3 parallel operations
+            // Verify all analysis calls were made
+            expect(mockAnalyzeDocumentSuggestions).toHaveBeenCalledTimes(3);
+        });
+    });
+    describe('Real-World Integration Scenarios', () => {
+        it('should handle comprehensive real-world scenario with all enhancements', async () => {
+            const comprehensiveScenario = {
+                related_documents: [
+                    {
+                        path: '/api/auth/oauth2.md',
+                        title: 'OAuth 2.0 Complete Guide',
+                        namespace: 'api/auth',
+                        reason: 'Explicit keyword matches with same namespace structure and recent updates',
+                        relevance: 0.97
+                    },
+                    {
+                        path: '/api/auth/jwt-tokens.md',
+                        title: 'JWT Token Management',
+                        namespace: 'api/auth',
+                        reason: 'Strong keyword overlap with same namespace structure',
+                        relevance: 0.89
+                    },
+                    {
+                        path: '/api/specs/auth-endpoints.md',
+                        title: 'Authentication API Endpoints',
+                        namespace: 'api/specs',
+                        reason: 'Good keyword overlap with related namespace structure',
+                        relevance: 0.81
+                    },
+                    {
+                        path: '/security/best-practices.md',
+                        title: 'Authentication Security',
+                        namespace: 'security',
+                        reason: 'Shared keywords with recent updates',
+                        relevance: 0.58
+                    },
+                    {
+                        path: '/frontend/auth-integration.md',
+                        title: 'Frontend Auth Integration',
+                        namespace: 'frontend',
+                        reason: 'Cross-referenced documentation with shared keywords',
+                        relevance: 0.67
+                    }
+                ],
+                broken_references: [
+                    {
+                        reference: '@/api/auth/deprecated-flow.md',
+                        type: 'missing_document',
+                        documentPath: '/api/auth/deprecated-flow.md',
+                        reason: 'Document not found: /api/auth/deprecated-flow.md'
+                    },
+                    {
+                        reference: '@/config/oauth-settings.md#client-config',
+                        type: 'missing_section',
+                        documentPath: '/config/oauth-settings.md',
+                        sectionSlug: 'client-config',
+                        reason: "Section 'client-config' not found in document /config/oauth-settings.md"
+                    }
+                ]
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(comprehensiveScenario);
+            const result = await processSuggestions('api/auth', 'OAuth 2.0 Client Implementation', '---\nkeywords: [oauth2, authentication, client, jwt, security, api]\ndescription: Complete implementation guide\n---\n\n# OAuth 2.0 Client Implementation\n\nThis guide covers **OAuth 2.0** client implementation with **JWT tokens**.\n\nSee @/api/auth/deprecated-flow.md for old approach and @/config/oauth-settings.md#client-config for configuration.');
+            const smartResult = result;
+            // Verify comprehensive suggestions
+            expect(smartResult.suggestions.related_documents).toHaveLength(5);
+            expect(smartResult.suggestions.broken_references).toHaveLength(2);
+            // Verify high-relevance documents with factor explanations
+            const oauthDoc = smartResult.suggestions.related_documents.find(d => d.path === '/api/auth/oauth2.md');
+            expect(oauthDoc?.relevance).toBeGreaterThan(0.95);
+            expect(oauthDoc?.reason).toMatch(/explicit keyword matches/i);
+            expect(oauthDoc?.reason).toMatch(/same namespace/i);
+            expect(oauthDoc?.reason).toMatch(/recent/i);
+            // Verify namespace affinity progression
+            const sameNamespace = smartResult.suggestions.related_documents.filter(d => d.namespace === 'api/auth');
+            const relatedNamespace = smartResult.suggestions.related_documents.filter(d => d.namespace === 'api/specs');
+            const differentNamespace = smartResult.suggestions.related_documents.filter(d => d.namespace === 'security');
+            expect(sameNamespace.every(d => d.relevance > 0.8)).toBe(true);
+            expect(relatedNamespace.every(d => d.relevance > 0.7)).toBe(true);
+            expect(differentNamespace.every(d => d.relevance < 0.7)).toBe(true);
+            // Verify structured broken references
+            const missingDoc = smartResult.suggestions.broken_references.find(r => r.type === 'missing_document');
+            const missingSection = smartResult.suggestions.broken_references.find(r => r.type === 'missing_section');
+            expect(missingDoc?.documentPath).toBe('/api/auth/deprecated-flow.md');
+            expect(missingSection?.documentPath).toBe('/config/oauth-settings.md');
+            expect(missingSection?.sectionSlug).toBe('client-config');
+            // Verify cross-referenced documentation scoring
+            const frontendDoc = smartResult.suggestions.related_documents.find(d => d.namespace === 'frontend');
+            expect(frontendDoc?.reason).toMatch(/cross-referenced/i);
+        });
+        it('should handle edge cases and degraded scenarios gracefully', async () => {
+            const edgeCaseScenarios = {
+                related_documents: [
+                    {
+                        path: '/edge/minimal.md',
+                        title: 'Minimal Document',
+                        namespace: 'edge',
+                        reason: 'Related documentation in edge',
+                        relevance: 0.21 // Just above threshold
+                    }
+                ],
+                broken_references: [
+                    {
+                        reference: '@incomplete-ref',
+                        type: 'malformed',
+                        reason: 'Failed to parse reference: Incomplete reference format'
+                    }
+                ]
+            };
+            mockAnalyzeDocumentSuggestions.mockResolvedValue(edgeCaseScenarios);
+            const result = await processSuggestions('edge', 'Edge Case Test', 'Document with minimal content and @incomplete-ref');
+            const smartResult = result;
+            // Should handle minimal results gracefully
+            expect(smartResult.suggestions.related_documents).toHaveLength(1);
+            expect(smartResult.suggestions.broken_references).toHaveLength(1);
+            expect(smartResult.stage).toBe('smart_suggestions');
+            // Should provide valid recovery guidance
+            expect(smartResult.next_step).toContain("create: true");
+            expect(smartResult.example).toEqual({
+                namespace: 'edge',
+                title: 'Edge Case Test',
+                overview: 'Document with minimal content and @incomplete-ref',
+                create: true
+            });
+        });
+    });
+    describe('Error Handling and Recovery', () => {
+        it('should handle analysis failures with partial results', async () => {
+            // Simulate partial failure scenario
+            mockAnalyzeDocumentSuggestions.mockRejectedValue(new Error('Analysis failed'));
+            const result = await processSuggestions('test', 'Test Document', 'Test content');
+            // Should return error fallback with recovery guidance
+            expect(result.stage).toBe('error_fallback');
+            const errorResult = result;
+            expect(errorResult.error).toBe('Failed to analyze suggestions');
+            expect(errorResult.details).toContain('Analysis failed');
+            expect(errorResult.recovery_steps).toContain("Call again with 'create: true' to skip suggestions and create the document");
+            expect(errorResult.example).toEqual({
+                namespace: 'test',
+                title: 'Test Document',
+                overview: 'Test content',
+                create: true
+            });
+        });
+        it('should provide helpful guidance when document manager fails', async () => {
+            mockGetDocumentManager.mockRejectedValue(new Error('Document manager initialization failed'));
+            const result = await processSuggestions('test', 'Test Document', 'Test content');
+            const errorResult = result;
+            expect(errorResult.details).toContain('Document manager initialization failed');
+            expect(errorResult.help).toContain('You can still proceed with document creation');
+        });
+    });
+});
+//# sourceMappingURL=create-document-workflow-regression.test.js.map