@planu/cli 0.88.1 → 0.90.1

package/dist/engine/doc-generator.test.js

@@ -0,0 +1,961 @@
+// SpecForge — Documentation Generator Engine Tests
+import { describe, it, expect } from 'vitest';
+import { generateDocs, generateDocument, generateDiagram } from './doc-generator.js';
+// === Helper factories ===
+function makeKnowledge(overrides = {}) {
+    return {
+        projectId: 'proj-1',
+        projectPath: '/home/user/my-project',
+        locale: 'en',
+        experienceLevel: 'intermediate',
+        language: 'typescript',
+        framework: 'express',
+        packageManager: 'npm',
+        buildCommand: 'npm run build',
+        testCommand: 'npm test',
+        stack: ['typescript', 'express', 'postgresql'],
+        database: 'postgresql',
+        architecture: {
+            primary: 'layered',
+            secondary: ['clean-architecture'],
+            layers: [
+                {
+                    name: 'API',
+                    directories: ['src/routes'],
+                    responsibility: 'HTTP handling',
+                    dependsOn: ['Service'],
+                    neverDependsOn: ['Database'],
+                },
+                {
+                    name: 'Service',
+                    directories: ['src/services'],
+                    responsibility: 'Business logic',
+                    dependsOn: ['Database'],
+                    neverDependsOn: [],
+                },
+                {
+                    name: 'Database',
+                    directories: ['src/db'],
+                    responsibility: 'Data access',
+                    dependsOn: [],
+                    neverDependsOn: ['API'],
+                },
+            ],
+            boundaries: [
+                {
+                    name: 'Auth Module',
+                    directories: ['src/auth'],
+                    publicApi: ['src/auth/index.ts'],
+                    internalOnly: ['src/auth/internal.ts'],
+                },
+            ],
+            communicationPatterns: ['REST', 'Events'],
+            deploymentUnits: ['docker', 'vercel'],
+        },
+        apps: [
+            { name: 'web', path: 'apps/web', type: 'frontend', language: 'typescript', framework: 'react' },
+            { name: 'api', path: 'apps/api', type: 'backend', language: 'typescript', framework: 'express' },
+        ],
+        conventions: { 'naming-files': 'kebab-case', 'naming-variables': 'camelCase' },
+        layers: ['routes', 'services', 'db'],
+        environments: ['development', 'staging', 'production'],
+        apiContracts: [
+            { type: 'openapi', path: 'openapi.yaml', endpoints: ['GET /users', 'POST /users'] },
+        ],
+        specLocation: 'docs/sdd/specs',
+        envSetup: {
+            projectId: 'proj-1',
+            variables: [
+                { name: 'DATABASE_URL', service: 'PostgreSQL', required: true, sensitive: true, description: 'DB conn string', howToGet: 'Create DB', environments: ['development'] },
+                { name: 'PORT', service: 'App', required: false, sensitive: false, description: 'Port', howToGet: 'Set port', environments: ['development'] },
+            ],
+            missing: [],
+            security: {
+                gitignoreHasEnv: true,
+                noSecretsInCode: true,
+                noEnvInGit: true,
+                noSecretsInLogs: true,
+                usesSecretManager: false,
+                issues: [
+                    { severity: 'warning', issue: 'No secret manager', fix: 'Use Vault or AWS Secrets Manager' },
+                ],
+            },
+            setupSteps: [],
+        },
+        linting: {
+            projectId: 'proj-1',
+            language: 'typescript',
+            detectedLinters: [],
+            missingRecommended: [],
+            rulesConflicts: [],
+            customRulesFromProject: [],
+            maturityScore: 0.5,
+        },
+        availableMcps: [],
+        docsRegistry: {},
+        qualityProfile: {
+            enabledCategories: ['solid', 'clean-code'],
+            customRules: [],
+            principles: ['SOLID', 'DRY'],
+            strictness: 'standard',
+        },
+        lastAnalyzed: '2025-01-01T00:00:00Z',
+        ...overrides,
+    };
+}
+function makeSpec(overrides = {}) {
+    return {
+        id: 'SPEC-001',
+        title: 'User Authentication',
+        slug: 'user-auth',
+        type: 'feature',
+        scope: 'feature',
+        status: 'done',
+        difficulty: 3,
+        risk: 'medium',
+        projectId: 'proj-1',
+        createdAt: '2025-01-01T00:00:00Z',
+        updatedAt: '2025-01-15T00:00:00Z',
+        huPath: '/tmp/HU.md',
+        fichaTecnicaPath: '/tmp/FICHA-TECNICA.md',
+        estimation: {
+            devHours: 8,
+            reviewHours: 1.6,
+            recommendedModel: 'mixed',
+            tokensOpus: 10000,
+            tokensSonnet: 20000,
+            apiCostUsd: 0.21,
+            hourlyRate: 65,
+            humanCostUsd: 624,
+            totalCostUsd: 624.21,
+            tokenOptimization: { mode: 'local', reasoning: 'test', estimatedTokens: 15000, savings: '~50%' },
+        },
+        actuals: { devHours: 8, reviewHours: 2, tokensOpus: 10000, tokensSonnet: 20000, apiCostUsd: 0.21, humanCostUsd: 650, totalCostUsd: 650.21, completedAt: '2025-01-15T00:00:00Z', notes: 'done' },
+        target: 'backend',
+        tags: ['auth'],
+        dependencies: [],
+        blockedBy: [],
+        gitBranch: 'feat/auth',
+        impactAnalysis: null,
+        ...overrides,
+    };
+}
+// === Tests for generateDocs ===
+describe('generateDocs', () => {
+    it('generates documents for multiple types', () => {
+        const knowledge = makeKnowledge();
+        const specs = [makeSpec()];
+        const result = generateDocs(['readme', 'setup-guide'], knowledge, specs);
+        expect(result.documents).toHaveLength(2);
+        expect(result.message).toContain('2 document(s)');
+        expect(result.message).toContain('readme, setup-guide');
+    });
+    it('generates a single document', () => {
+        const knowledge = makeKnowledge();
+        const result = generateDocs(['readme'], knowledge);
+        expect(result.documents).toHaveLength(1);
+        expect(result.message).toContain('1 document(s)');
+    });
+    it('defaults to empty specs and developer audience', () => {
+        const knowledge = makeKnowledge();
+        const result = generateDocs(['faq'], knowledge);
+        expect(result.documents).toHaveLength(1);
+        expect(result.documents[0].audience).toBe('developer');
+    });
+    it('handles empty types array', () => {
+        const knowledge = makeKnowledge();
+        const result = generateDocs([], knowledge, []);
+        expect(result.documents).toHaveLength(0);
+        expect(result.message).toContain('0 document(s)');
+    });
+    it('generates all 14 document types', () => {
+        const knowledge = makeKnowledge();
+        const specs = [makeSpec()];
+        const allTypes = [
+            'user-guide', 'api-reference', 'readme', 'setup-guide',
+            'changelog', 'onboarding', 'faq', 'architecture-doc',
+            'deployment-guide', 'database-doc', 'help-articles',
+            'release-notes', 'runbook', 'security-doc',
+        ];
+        const result = generateDocs([...allTypes], knowledge, specs);
+        expect(result.documents).toHaveLength(14);
+    });
+});
+// === Tests for generateDocument ===
+describe('generateDocument', () => {
+    describe('unsupported type', () => {
+        it('returns fallback for unknown type', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('unknown-type', knowledge, [], 'developer', 'en');
+            expect(doc.title).toContain('Unsupported');
+            expect(doc.content).toContain('not yet supported');
+            expect(doc.sections).toEqual([]);
+            expect(doc.diagrams).toEqual([]);
+            expect(doc.relatedSpecs).toEqual([]);
+            expect(doc.audience).toBe('developer');
+        });
+    });
+    describe('readme', () => {
+        it('generates readme with project name from path', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('readme', knowledge, [], 'developer', 'en');
+            expect(doc.type).toBe('readme');
+            expect(doc.title).toContain('my-project');
+            expect(doc.path).toBe('README.md');
+            expect(doc.content).toContain('typescript');
+            expect(doc.content).toContain('express');
+            expect(doc.sections.length).toBeGreaterThanOrEqual(5);
+        });
+        it('handles project path with no trailing slash', () => {
+            const knowledge = makeKnowledge({ projectPath: '/single' });
+            const doc = generateDocument('readme', knowledge, [], 'developer', 'en');
+            expect(doc.title).toContain('single');
+        });
+        it('includes tech stack with framework, database, package manager', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('readme', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('Framework');
+            expect(doc.content).toContain('express');
+            expect(doc.content).toContain('Database');
+            expect(doc.content).toContain('postgresql');
+            expect(doc.content).toContain('Package Manager');
+            expect(doc.content).toContain('npm');
+        });
+        it('omits framework if null', () => {
+            const knowledge = makeKnowledge({ framework: null });
+            const doc = generateDocument('readme', knowledge, [], 'developer', 'en');
+            // Intro should not have "built with"
+            expect(doc.sections[0].content).not.toContain('built with');
+        });
+        it('omits database if unknown', () => {
+            const knowledge = makeKnowledge({ database: 'unknown' });
+            const doc = generateDocument('readme', knowledge, [], 'developer', 'en');
+            expect(doc.sections[0].content).not.toContain('Uses unknown');
+        });
+        it('omits packageManager if null', () => {
+            const knowledge = makeKnowledge({ packageManager: null });
+            const doc = generateDocument('readme', knowledge, [], 'developer', 'en');
+            // tech stack section should not contain Package Manager
+            const techSection = doc.sections.find((s) => s.title === 'Tech Stack');
+            expect(techSection.content).not.toContain('Package Manager');
+        });
+        it('includes getting started with install, build, test commands', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('readme', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('npm install');
+            expect(doc.content).toContain('npm run build');
+            expect(doc.content).toContain('npm test');
+        });
+        it('omits build and test commands if null', () => {
+            const knowledge = makeKnowledge({ buildCommand: null, testCommand: null });
+            const doc = generateDocument('readme', knowledge, [], 'developer', 'en');
+            const devSection = doc.sections.find((s) => s.title === 'Development');
+            expect(devSection.content).not.toContain('Build');
+            expect(devSection.content).not.toContain('Test');
+        });
+        it('sets audience from parameter', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('readme', knowledge, [], 'ops', 'en');
+            expect(doc.audience).toBe('ops');
+        });
+    });
+    describe('setup-guide', () => {
+        it('generates setup guide with all sections', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.type).toBe('setup-guide');
+            expect(doc.path).toBe('docs/setup-guide.md');
+            expect(doc.sections.length).toBeGreaterThanOrEqual(6);
+            expect(doc.content).toContain('Prerequisites');
+            expect(doc.content).toContain('Installation');
+            expect(doc.content).toContain('Environment Variables');
+            expect(doc.content).toContain('Database Setup');
+            expect(doc.content).toContain('Running the Project');
+            expect(doc.content).toContain('Verifying Setup');
+        });
+        it('shows database setup when known', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('postgresql');
+        });
+        it('shows no database message when unknown', () => {
+            const knowledge = makeKnowledge({ database: 'unknown' });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('No database configured');
+        });
+        it('shows env vars table when variables exist', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('DATABASE_URL');
+            expect(doc.content).toContain('PostgreSQL');
+            expect(doc.content).toContain('Required variables');
+        });
+        it('shows simple env message when no variables', () => {
+            const knowledge = makeKnowledge({
+                envSetup: {
+                    projectId: 'proj-1',
+                    variables: [],
+                    missing: [],
+                    security: { gitignoreHasEnv: true, noSecretsInCode: true, noEnvInGit: true, noSecretsInLogs: true, usesSecretManager: false, issues: [] },
+                    setupSteps: [],
+                },
+            });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('cp .env.example .env');
+        });
+        it('includes prerequisites for known languages', () => {
+            const knowledge = makeKnowledge({ language: 'python' });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('Python 3.10+');
+        });
+        it('uses fallback prerequisites for unknown language', () => {
+            const knowledge = makeKnowledge({ language: 'haskell' });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('haskell');
+            expect(doc.content).toContain('latest stable');
+        });
+        it('includes install command for known package managers', () => {
+            const knowledge = makeKnowledge({ packageManager: 'pnpm' });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('pnpm install');
+        });
+        it('falls back for unknown package manager', () => {
+            const knowledge = makeKnowledge({ packageManager: 'mega-pm' });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('mega-pm install');
+        });
+        it('handles null packageManager in installation', () => {
+            const knowledge = makeKnowledge({ packageManager: null });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).not.toContain('Install dependencies');
+        });
+        it('renders verify section with build and test commands', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('Build succeeds');
+            expect(doc.content).toContain('Tests pass');
+        });
+        it('renders running section with build command replacement', () => {
+            const knowledge = makeKnowledge({ buildCommand: 'npm run build' });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('npm run dev');
+        });
+        it('renders running section fallback when no build command', () => {
+            const knowledge = makeKnowledge({ buildCommand: null });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('npm run dev');
+        });
+    });
+    describe('architecture-doc', () => {
+        it('generates architecture doc with layers and diagrams', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('architecture-doc', knowledge, [], 'developer', 'en');
+            expect(doc.type).toBe('architecture-doc');
+            expect(doc.path).toBe('docs/architecture.md');
+            expect(doc.content).toContain('layered');
+            expect(doc.content).toContain('API');
+            expect(doc.content).toContain('Service');
+            expect(doc.content).toContain('Database');
+            expect(doc.diagrams).toHaveLength(2);
+        });
+        it('includes secondary patterns when present', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('architecture-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('clean-architecture');
+        });
+        it('omits secondary patterns line when empty', () => {
+            const knowledge = makeKnowledge();
+            knowledge.architecture.secondary = [];
+            const doc = generateDocument('architecture-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).not.toContain('Secondary patterns:');
+        });
+        it('shows layer dependencies', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('architecture-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('Depends on:** Service');
+        });
+        it('shows foundation layer when no dependencies', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('architecture-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('foundation layer');
+        });
+        it('shows never depends on when present', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('architecture-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('NEVER depends on');
+        });
+        it('includes boundaries section when present', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('architecture-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('Module Boundaries');
+            expect(doc.content).toContain('Auth Module');
+            expect(doc.content).toContain('Public API');
+        });
+        it('omits boundaries when empty', () => {
+            const knowledge = makeKnowledge();
+            knowledge.architecture.boundaries = [];
+            const doc = generateDocument('architecture-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).not.toContain('Module Boundaries');
+        });
+        it('handles boundary with no public API', () => {
+            const knowledge = makeKnowledge();
+            knowledge.architecture.boundaries = [
+                { name: 'Utils', directories: ['src/utils'], publicApi: [], internalOnly: [] },
+            ];
+            const doc = generateDocument('architecture-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('Utils');
+        });
+    });
+    describe('api-reference', () => {
+        it('generates API reference with contracts', () => {
+            const knowledge = makeKnowledge();
+            const specs = [makeSpec()];
+            const doc = generateDocument('api-reference', knowledge, specs, 'developer', 'en');
+            expect(doc.type).toBe('api-reference');
+            expect(doc.path).toBe('docs/api-reference.md');
+            expect(doc.content).toContain('OPENAPI');
+            expect(doc.content).toContain('GET /users');
+        });
+        it('uses framework in overview when present', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('api-reference', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('express');
+        });
+        it('falls back to language when no framework', () => {
+            const knowledge = makeKnowledge({ framework: null });
+            const doc = generateDocument('api-reference', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('typescript');
+        });
+        it('shows no contracts message when empty', () => {
+            const knowledge = makeKnowledge({ apiContracts: [] });
+            const doc = generateDocument('api-reference', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('No formal API contracts detected');
+        });
+        it('shows endpoint list when contract has endpoints', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('api-reference', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('Endpoints:');
+        });
+        it('shows auto-detected message when no endpoints', () => {
+            const knowledge = makeKnowledge({
+                apiContracts: [{ type: 'rest-informal', endpoints: [] }],
+            });
+            const doc = generateDocument('api-reference', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('auto-detected from code');
+        });
+        it('filters related specs for backend/fullstack targets', () => {
+            const backendSpec = makeSpec({ id: 'SPEC-001', target: 'backend' });
+            const frontendSpec = makeSpec({ id: 'SPEC-002', target: 'frontend' });
+            const fullstackSpec = makeSpec({ id: 'SPEC-003', target: 'fullstack' });
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('api-reference', knowledge, [backendSpec, frontendSpec, fullstackSpec], 'developer', 'en');
+            expect(doc.relatedSpecs).toContain('SPEC-001');
+            expect(doc.relatedSpecs).toContain('SPEC-003');
+            expect(doc.relatedSpecs).not.toContain('SPEC-002');
+        });
+        it('includes contract path when present', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('api-reference', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('openapi.yaml');
+        });
+        it('omits contract path when not present', () => {
+            const knowledge = makeKnowledge({
+                apiContracts: [{ type: 'rest-informal', endpoints: ['GET /health'] }],
+            });
+            const doc = generateDocument('api-reference', knowledge, [], 'developer', 'en');
+            expect(doc.content).not.toContain('Schema:');
+        });
+    });
+    describe('user-guide', () => {
+        it('generates user guide', () => {
+            const knowledge = makeKnowledge();
+            const specs = [makeSpec()];
+            const doc = generateDocument('user-guide', knowledge, specs, 'end-user', 'en');
+            expect(doc.type).toBe('user-guide');
+            expect(doc.path).toBe('docs/user-guide.md');
+            expect(doc.content).toContain('my-project');
+            expect(doc.relatedSpecs).toContain('SPEC-001');
+        });
+        it('shows done specs as features', () => {
+            const specs = [makeSpec({ status: 'done' })];
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('user-guide', knowledge, specs, 'end-user', 'en');
+            expect(doc.content).toContain('User Authentication');
+        });
+        it('shows fallback when no specs', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('user-guide', knowledge, [], 'end-user', 'en');
+            expect(doc.content).toContain('Feature list will be populated');
+        });
+        it('filters only done specs for feature list', () => {
+            const doneSpec = makeSpec({ id: 'SPEC-001', status: 'done', title: 'Done Feature' });
+            const draftSpec = makeSpec({ id: 'SPEC-002', status: 'draft', title: 'Draft Feature' });
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('user-guide', knowledge, [doneSpec, draftSpec], 'end-user', 'en');
+            expect(doc.content).toContain('Done Feature');
+            expect(doc.content).not.toContain('Draft Feature');
+        });
+    });
+    describe('changelog', () => {
+        it('generates changelog with categorized specs', () => {
+            const done = makeSpec({ status: 'done', type: 'feature' });
+            const implementing = makeSpec({ id: 'SPEC-002', status: 'implementing', type: 'bugfix', title: 'Fix Bug' });
+            const approved = makeSpec({ id: 'SPEC-003', status: 'approved', type: 'refactor', title: 'Refactor' });
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('changelog', knowledge, [done, implementing, approved], 'developer', 'en');
+            expect(doc.type).toBe('changelog');
+            expect(doc.path).toBe('CHANGELOG.md');
+            expect(doc.content).toContain('Completed');
+            expect(doc.content).toContain('In Progress');
+            expect(doc.content).toContain('Planned');
+        });
+        it('omits sections for empty categories', () => {
+            const done = makeSpec({ status: 'done' });
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('changelog', knowledge, [done], 'developer', 'en');
+            expect(doc.content).toContain('Completed');
+            expect(doc.content).not.toContain('In Progress');
+            expect(doc.content).not.toContain('Planned');
+        });
+        it('handles empty specs', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('changelog', knowledge, [], 'developer', 'en');
+            expect(doc.type).toBe('changelog');
+            expect(doc.sections).toHaveLength(0);
+        });
+        it('uses completedAt date if present in actuals', () => {
+            const done = makeSpec({
+                status: 'done',
+                actuals: { completedAt: '2025-06-01', devHours: 5, reviewHours: 1, tokensOpus: 0, tokensSonnet: 0, apiCostUsd: 0, humanCostUsd: 0, totalCostUsd: 0, notes: '' },
+            });
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('changelog', knowledge, [done], 'developer', 'en');
+            expect(doc.content).toContain('2025-06-01');
+        });
+        it('falls back to updatedAt when no actuals', () => {
+            const done = makeSpec({ status: 'done', actuals: null, updatedAt: '2025-03-01T00:00:00Z' });
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('changelog', knowledge, [done], 'developer', 'en');
+            expect(doc.content).toContain('2025-03-01');
+        });
+    });
+    describe('onboarding', () => {
+        it('generates onboarding guide', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('onboarding', knowledge, [], 'developer', 'en');
+            expect(doc.type).toBe('onboarding');
+            expect(doc.path).toBe('docs/onboarding.md');
+            expect(doc.content).toContain('Welcome');
+            expect(doc.content).toContain('typescript');
+            expect(doc.content).toContain('express');
+            expect(doc.content).toContain('layered');
+        });
+        it('omits framework when null', () => {
+            const knowledge = makeKnowledge({ framework: null });
+            const doc = generateDocument('onboarding', knowledge, [], 'developer', 'en');
+            expect(doc.content).not.toContain('using **null**');
+        });
+        it('includes build and test commands in first day setup', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('onboarding', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('npm run build');
+            expect(doc.content).toContain('npm test');
+        });
+        it('omits build/test steps when null', () => {
+            const knowledge = makeKnowledge({ buildCommand: null, testCommand: null });
+            const doc = generateDocument('onboarding', knowledge, [], 'developer', 'en');
+            expect(doc.content).not.toContain('verify the build');
+            expect(doc.content).not.toContain('verify tests pass');
+        });
+    });
+    describe('faq', () => {
+        it('generates FAQ', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('faq', knowledge, [], 'developer', 'en');
+            expect(doc.type).toBe('faq');
+            expect(doc.path).toBe('docs/faq.md');
+            expect(doc.content).toContain('Frequently Asked Questions');
+            expect(doc.content).toContain('typescript');
+        });
+        it('includes framework in language question', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('faq', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('with express');
+        });
+        it('omits framework when null', () => {
+            const knowledge = makeKnowledge({ framework: null });
+            const doc = generateDocument('faq', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('typescript.');
+        });
+        it('shows database info when known', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('faq', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('postgresql');
+        });
+        it('shows no database message when unknown', () => {
+            const knowledge = makeKnowledge({ database: 'unknown' });
+            const doc = generateDocument('faq', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('No database is configured yet');
+        });
+        it('shows test command when present', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('faq', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('npm test');
+        });
+        it('shows no test command message when null', () => {
+            const knowledge = makeKnowledge({ testCommand: null });
+            const doc = generateDocument('faq', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('No test command is configured yet');
+        });
+    });
+    describe('database-doc', () => {
+        it('generates database doc with known database', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('database-doc', knowledge, [], 'developer', 'en');
+            expect(doc.type).toBe('database-doc');
+            expect(doc.path).toBe('docs/database.md');
+            expect(doc.content).toContain('postgresql');
+            expect(doc.content).toContain('Connection');
+            expect(doc.content).toContain('Migrations');
+            expect(doc.content).toContain('Schema');
+            expect(doc.diagrams).toHaveLength(1);
+        });
+        it('generates minimal doc when database unknown', () => {
+            const knowledge = makeKnowledge({ database: 'unknown' });
+            const doc = generateDocument('database-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('No database is configured');
+            expect(doc.content).not.toContain('Connection');
+            expect(doc.diagrams).toHaveLength(0);
+        });
+    });
+    describe('deployment-guide', () => {
+        it('generates deployment guide for deployment units', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('deployment-guide', knowledge, [], 'ops', 'en');
+            expect(doc.type).toBe('deployment-guide');
+            expect(doc.path).toBe('docs/deployment.md');
+            expect(doc.content).toContain('docker');
+            expect(doc.content).toContain('vercel');
+            expect(doc.content).toContain('Rollback');
+            expect(doc.diagrams).toHaveLength(1);
+        });
+        it('includes specific deployment instructions for known units', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('deployment-guide', knowledge, [], 'ops', 'en');
+            expect(doc.content).toContain('docker build');
+            expect(doc.content).toContain('vercel');
+        });
+        it('includes fallback for unknown deployment unit', () => {
+            const knowledge = makeKnowledge();
+            knowledge.architecture.deploymentUnits = ['custom-target'];
+            const doc = generateDocument('deployment-guide', knowledge, [], 'ops', 'en');
+            expect(doc.content).toContain('custom-target');
+            expect(doc.content).toContain('document your steps here');
+        });
+        it('covers all known deployment unit instructions', () => {
+            const units = ['docker', 'docker-compose', 'vercel', 'railway', 'netlify', 'fly.io', 'manual'];
+            for (const unit of units) {
+                const knowledge = makeKnowledge();
+                knowledge.architecture.deploymentUnits = [unit];
+                const doc = generateDocument('deployment-guide', knowledge, [], 'ops', 'en');
+                expect(doc.content).toContain(unit);
+            }
+        });
+    });
+    describe('help-articles', () => {
+        it('generates help articles from done specs', () => {
+            const specs = [makeSpec({ status: 'done' })];
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('help-articles', knowledge, specs, 'end-user', 'en');
+            expect(doc.type).toBe('help-articles');
+            expect(doc.path).toBe('docs/help.md');
+            expect(doc.content).toContain('User Authentication');
+            expect(doc.relatedSpecs).toContain('SPEC-001');
+        });
+        it('limits to 10 done specs', () => {
+            const specs = Array.from({ length: 15 }, (_, i) => makeSpec({ id: `SPEC-${String(i).padStart(3, '0')}`, status: 'done', title: `Feature ${i}` }));
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('help-articles', knowledge, specs, 'end-user', 'en');
+            // Help center + up to 10 articles
+            expect(doc.sections.length).toBeLessThanOrEqual(11);
+        });
+        it('generates help center section even with no done specs', () => {
+            const specs = [makeSpec({ status: 'draft' })];
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('help-articles', knowledge, specs, 'end-user', 'en');
+            expect(doc.sections).toHaveLength(1);
+            expect(doc.sections[0].title).toBe('Help Center');
+        });
+    });
+    describe('release-notes', () => {
+        it('generates release notes grouped by type', () => {
+            const feature = makeSpec({ id: 'SPEC-001', type: 'feature', status: 'done', title: 'New Feature' });
+            const bugfix = makeSpec({ id: 'SPEC-002', type: 'bugfix', status: 'done', title: 'Fix Bug' });
+            const refactor = makeSpec({ id: 'SPEC-003', type: 'refactor', status: 'done', title: 'Refactor Code' });
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('release-notes', knowledge, [feature, bugfix, refactor], 'stakeholder', 'en');
+            expect(doc.type).toBe('release-notes');
+            expect(doc.path).toBe('docs/release-notes.md');
+            expect(doc.content).toContain('New Features');
+            expect(doc.content).toContain('Bug Fixes');
+            expect(doc.content).toContain('Improvements');
+        });
+        it('omits empty type sections', () => {
+            const feature = makeSpec({ type: 'feature', status: 'done' });
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('release-notes', knowledge, [feature], 'stakeholder', 'en');
+            expect(doc.content).toContain('New Features');
+            expect(doc.content).not.toContain('Bug Fixes');
+            expect(doc.content).not.toContain('Improvements');
+        });
+        it('only includes done specs', () => {
+            const draft = makeSpec({ status: 'draft', type: 'feature', title: 'Draft' });
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('release-notes', knowledge, [draft], 'stakeholder', 'en');
+            expect(doc.content).not.toContain('Draft');
+            expect(doc.relatedSpecs).toHaveLength(0);
+        });
+    });
+    describe('runbook', () => {
+        it('generates runbook', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('runbook', knowledge, [], 'ops', 'en');
+            expect(doc.type).toBe('runbook');
+            expect(doc.path).toBe('docs/runbook.md');
+            expect(doc.content).toContain('Service Overview');
+            expect(doc.content).toContain('Health Checks');
+            expect(doc.content).toContain('Common Issues');
+            expect(doc.content).toContain('Escalation');
+            expect(doc.content).toContain('typescript');
+            expect(doc.content).toContain('express');
+            expect(doc.content).toContain('postgresql');
+        });
+        it('shows none for framework when null', () => {
+            const knowledge = makeKnowledge({ framework: null });
+            const doc = generateDocument('runbook', knowledge, [], 'ops', 'en');
+            expect(doc.content).toContain('Framework: none');
+        });
+    });
+    describe('security-doc', () => {
+        it('generates security doc', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('security-doc', knowledge, [], 'developer', 'en');
+            expect(doc.type).toBe('security-doc');
+            expect(doc.path).toBe('docs/security.md');
+            expect(doc.content).toContain('Security Overview');
+            expect(doc.content).toContain('Authentication & Authorization');
+            expect(doc.content).toContain('Data Protection');
+            expect(doc.content).toContain('Reporting Vulnerabilities');
+        });
+        it('shows positive security checks', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('security-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('.env in .gitignore: Yes');
+            expect(doc.content).toContain('No .env committed to git: Yes');
+            expect(doc.content).toContain('No secrets in code: Yes');
+        });
+        it('shows negative security checks', () => {
+            const knowledge = makeKnowledge({
+                envSetup: {
+                    projectId: 'proj-1',
+                    variables: [],
+                    missing: [],
+                    security: {
+                        gitignoreHasEnv: false,
+                        noSecretsInCode: false,
+                        noEnvInGit: false,
+                        noSecretsInLogs: true,
+                        usesSecretManager: true,
+                        issues: [],
+                    },
+                    setupSteps: [],
+                },
+            });
+            const doc = generateDocument('security-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('FIX IMMEDIATELY');
+            expect(doc.content).toContain('REMOVE FROM GIT');
+            expect(doc.content).toContain('Needs review');
+            expect(doc.content).toContain('Uses secret manager: Yes');
+        });
+        it('shows security issues when present', () => {
+            const knowledge = makeKnowledge();
+            const doc = generateDocument('security-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain('Issues');
+            expect(doc.content).toContain('WARNING');
+            expect(doc.content).toContain('No secret manager');
+        });
+        it('omits issues section when no issues', () => {
+            const knowledge = makeKnowledge({
+                envSetup: {
+                    projectId: 'proj-1',
+                    variables: [],
+                    missing: [],
+                    security: {
+                        gitignoreHasEnv: true,
+                        noSecretsInCode: true,
+                        noEnvInGit: true,
+                        noSecretsInLogs: true,
+                        usesSecretManager: true,
+                        issues: [],
+                    },
+                    setupSteps: [],
+                },
+            });
+            const doc = generateDocument('security-doc', knowledge, [], 'developer', 'en');
+            expect(doc.content).not.toContain('### Issues');
+        });
+    });
+});
+// === Tests for generateDiagram ===
+describe('generateDiagram', () => {
+    it('generates architecture diagram', () => {
+        const knowledge = makeKnowledge();
+        const diagram = generateDiagram('architecture', knowledge);
+        expect(diagram.type).toBe('architecture');
+        expect(diagram.format).toBe('mermaid');
+        expect(diagram.content).toContain('graph TB');
+        expect(diagram.content).toContain('API');
+        expect(diagram.content).toContain('Service');
+        expect(diagram.description).toContain('layered');
+    });
+    it('generates component diagram', () => {
+        const knowledge = makeKnowledge();
+        const diagram = generateDiagram('component', knowledge);
+        expect(diagram.type).toBe('component');
+        expect(diagram.content).toContain('graph LR');
+        expect(diagram.content).toContain('web');
+        expect(diagram.content).toContain('api');
+        // frontend -> backend connection
+        expect(diagram.content).toContain('-->');
+        expect(diagram.description).toContain('2 app(s)');
+    });
+    it('generates data-flow diagram with database', () => {
+        const knowledge = makeKnowledge();
+        const diagram = generateDiagram('data-flow', knowledge);
+        expect(diagram.type).toBe('data-flow');
+        expect(diagram.content).toContain('graph LR');
+        expect(diagram.content).toContain('DB[(postgresql)]');
+    });
+    it('generates data-flow diagram without database', () => {
+        const knowledge = makeKnowledge({ database: 'unknown' });
+        const diagram = generateDiagram('data-flow', knowledge);
+        expect(diagram.content).not.toContain('DB[(');
+        expect(diagram.content).not.toContain('Logic --> DB');
+    });
+    it('generates sequence diagram with spec', () => {
+        const knowledge = makeKnowledge();
+        const spec = makeSpec();
+        const diagram = generateDiagram('sequence', knowledge, spec);
+        expect(diagram.type).toBe('sequence');
+        expect(diagram.content).toContain('sequenceDiagram');
+        expect(diagram.content).toContain('User Authentication');
+        expect(diagram.title).toContain('User Authentication');
+    });
+    it('generates sequence diagram without spec', () => {
+        const knowledge = makeKnowledge();
+        const diagram = generateDiagram('sequence', knowledge);
+        expect(diagram.content).toContain('Request Flow');
+        expect(diagram.title).toContain('Request Flow');
+    });
+    it('generates ER diagram', () => {
+        const knowledge = makeKnowledge();
+        const diagram = generateDiagram('er', knowledge);
+        expect(diagram.type).toBe('er');
+        expect(diagram.content).toContain('erDiagram');
+        expect(diagram.content).toContain('USERS');
+        expect(diagram.description).toContain('postgresql');
+    });
+    it('generates state-machine diagram with spec', () => {
+        const knowledge = makeKnowledge();
+        const spec = makeSpec();
+        const diagram = generateDiagram('state-machine', knowledge, spec);
+        expect(diagram.type).toBe('state-machine');
+        expect(diagram.content).toContain('stateDiagram-v2');
+        expect(diagram.content).toContain('draft');
+        expect(diagram.content).toContain('approved');
+    });
+    it('generates state-machine diagram without spec', () => {
+        const knowledge = makeKnowledge();
+        const diagram = generateDiagram('state-machine', knowledge);
+        expect(diagram.content).toContain('Created');
+        expect(diagram.content).toContain('Active');
+        expect(diagram.content).not.toContain('draft');
+    });
+    it('generates dependency diagram with allowed and forbidden deps', () => {
+        const knowledge = makeKnowledge();
+        const diagram = generateDiagram('dependency', knowledge);
+        expect(diagram.type).toBe('dependency');
+        expect(diagram.content).toContain('graph TD');
+        expect(diagram.content).toContain('-.->'); // allowed dep
+        expect(diagram.content).toContain('-.-x'); // forbidden dep
+    });
+    it('generates deployment diagram', () => {
+        const knowledge = makeKnowledge();
+        const diagram = generateDiagram('deployment', knowledge);
+        expect(diagram.type).toBe('deployment');
+        expect(diagram.content).toContain('graph LR');
+        expect(diagram.content).toContain('Dev');
+        expect(diagram.content).toContain('Git');
+        expect(diagram.content).toContain('docker');
+        expect(diagram.content).toContain('vercel');
+        expect(diagram.description).toContain('2 target(s)');
+    });
+    it('returns placeholder for unsupported diagram type', () => {
+        const knowledge = makeKnowledge();
+        const diagram = generateDiagram('unknown-type', knowledge);
+        expect(diagram.content).toContain('Not yet implemented');
+        expect(diagram.description).toContain('placeholder');
+    });
+});
+// === Tests for getInstallCommand coverage (various package managers) ===
+describe('getInstallCommand coverage via setup-guide', () => {
+    const managers = [
+        { pm: 'npm', expected: 'npm install' },
+        { pm: 'pnpm', expected: 'pnpm install' },
+        { pm: 'yarn', expected: 'yarn' },
+        { pm: 'bun', expected: 'bun install' },
+        { pm: 'pip', expected: 'pip install -r requirements.txt' },
+        { pm: 'poetry', expected: 'poetry install' },
+        { pm: 'uv', expected: 'uv sync' },
+        { pm: 'pipenv', expected: 'pipenv install' },
+        { pm: 'cargo', expected: 'cargo build' },
+        { pm: 'go-mod', expected: 'go mod download' },
+        { pm: 'composer', expected: 'composer install' },
+        { pm: 'bundler', expected: 'bundle install' },
+        { pm: 'pub', expected: 'flutter pub get' },
+        { pm: 'mix', expected: 'mix deps.get' },
+        { pm: 'spm', expected: 'swift package resolve' },
+    ];
+    for (const { pm, expected } of managers) {
+        it(`returns correct command for ${pm}`, () => {
+            const knowledge = makeKnowledge({ packageManager: pm });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain(expected);
+        });
+    }
+});
+// === Tests for various prerequisite languages ===
+describe('buildPrerequisitesSection coverage via setup-guide', () => {
+    const langs = [
+        { lang: 'typescript', expected: 'Node.js 18+' },
+        { lang: 'javascript', expected: 'Node.js 18+' },
+        { lang: 'python', expected: 'Python 3.10+' },
+        { lang: 'go', expected: 'Go 1.21+' },
+        { lang: 'rust', expected: 'Rust 1.70+' },
+        { lang: 'java', expected: 'Java 17+' },
+        { lang: 'kotlin', expected: 'Kotlin 1.9+' },
+        { lang: 'php', expected: 'PHP 8.2+' },
+        { lang: 'ruby', expected: 'Ruby 3.2+' },
+        { lang: 'swift', expected: 'Xcode 15+' },
+        { lang: 'dart', expected: 'Dart 3.0+' },
+        { lang: 'csharp', expected: '.NET 8+' },
+    ];
+    for (const { lang, expected } of langs) {
+        it(`shows correct prerequisite for ${lang}`, () => {
+            const knowledge = makeKnowledge({ language: lang });
+            const doc = generateDocument('setup-guide', knowledge, [], 'developer', 'en');
+            expect(doc.content).toContain(expected);
+        });
+    }
+});
+//# sourceMappingURL=doc-generator.test.js.map