popeye-cli 2.1.0 → 2.2.0

package/tests/pipeline/skills/constitution-generator.test.ts

@@ -0,0 +1,201 @@
+/**
+ * Constitution generator tests — deterministic template generation, skip logic.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  generateConstitution,
+  shouldSkipConstitution,
+  getTechStackSection,
+  getArchitectureRules,
+  getCodeQualityRules,
+  getConstraintsSection,
+} from '../../../src/pipeline/skills/constitution-generator.js';
+import type { ConstitutionContext } from '../../../src/pipeline/skills/types.js';
+
+const TEST_DIR = join(process.cwd(), '.test-constitution-gen');
+const SKILLS_DIR = join(TEST_DIR, 'skills');
+
+function makeContext(overrides: Partial<ConstitutionContext> = {}): ConstitutionContext {
+  return {
+    language: 'python',
+    projectName: 'TestProject',
+    techStack: {
+      language: 'Python 3.11+',
+      backend: 'FastAPI',
+      database: 'PostgreSQL',
+      orm: 'SQLAlchemy',
+      testing: 'Pytest',
+    },
+    expandedSpec: 'Build a REST API',
+    skillsDir: SKILLS_DIR,
+    ...overrides,
+  };
+}
+
+describe('constitution-generator', () => {
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+    mkdirSync(SKILLS_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+  });
+
+  describe('shouldSkipConstitution', () => {
+    it('should return false when constitution does not exist', () => {
+      expect(shouldSkipConstitution(SKILLS_DIR)).toBe(false);
+    });
+
+    it('should return true when constitution already exists', () => {
+      writeFileSync(join(SKILLS_DIR, 'POPEYE_CONSTITUTION.md'), 'existing');
+      expect(shouldSkipConstitution(SKILLS_DIR)).toBe(true);
+    });
+  });
+
+  describe('generateConstitution', () => {
+    it('should create POPEYE_CONSTITUTION.md', () => {
+      generateConstitution(makeContext());
+      const path = join(SKILLS_DIR, 'POPEYE_CONSTITUTION.md');
+      expect(existsSync(path)).toBe(true);
+    });
+
+    it('should include project name in header', () => {
+      generateConstitution(makeContext());
+      const content = readFileSync(join(SKILLS_DIR, 'POPEYE_CONSTITUTION.md'), 'utf-8');
+      expect(content).toContain('# Project Constitution: TestProject');
+    });
+
+    it('should include tech stack section', () => {
+      generateConstitution(makeContext());
+      const content = readFileSync(join(SKILLS_DIR, 'POPEYE_CONSTITUTION.md'), 'utf-8');
+      expect(content).toContain('## Tech Stack');
+      expect(content).toContain('FastAPI');
+      expect(content).toContain('PostgreSQL');
+      expect(content).toContain('SQLAlchemy');
+    });
+
+    it('should include governance rules', () => {
+      generateConstitution(makeContext());
+      const content = readFileSync(join(SKILLS_DIR, 'POPEYE_CONSTITUTION.md'), 'utf-8');
+      expect(content).toContain('## Governance Rules');
+      expect(content).toContain('Consensus threshold: 0.95');
+      expect(content).toContain('immutable once stored');
+      expect(content).toContain('No placeholder content');
+    });
+
+    it('should include immutability notice', () => {
+      generateConstitution(makeContext());
+      const content = readFileSync(join(SKILLS_DIR, 'POPEYE_CONSTITUTION.md'), 'utf-8');
+      expect(content).toContain('## Immutability');
+      expect(content).toContain('MUST NOT be modified during pipeline execution');
+    });
+
+    it('should not overwrite existing constitution', () => {
+      writeFileSync(join(SKILLS_DIR, 'POPEYE_CONSTITUTION.md'), 'hand-written content');
+      generateConstitution(makeContext());
+      const content = readFileSync(join(SKILLS_DIR, 'POPEYE_CONSTITUTION.md'), 'utf-8');
+      expect(content).toBe('hand-written content');
+    });
+
+    it('should include session guidance when provided', () => {
+      generateConstitution(makeContext({ sessionGuidance: 'Focus on security' }));
+      const content = readFileSync(join(SKILLS_DIR, 'POPEYE_CONSTITUTION.md'), 'utf-8');
+      expect(content).toContain('Focus on security');
+    });
+
+    it('should create skills dir if it does not exist', () => {
+      rmSync(SKILLS_DIR, { recursive: true });
+      expect(existsSync(SKILLS_DIR)).toBe(false);
+      generateConstitution(makeContext());
+      expect(existsSync(SKILLS_DIR)).toBe(true);
+    });
+  });
+
+  describe('getTechStackSection', () => {
+    it('should list all available tech stack fields', () => {
+      const section = getTechStackSection({
+        language: 'Python 3.11+',
+        backend: 'FastAPI',
+        database: 'PostgreSQL',
+        orm: 'SQLAlchemy',
+        testing: 'Pytest',
+      });
+      expect(section).toContain('- Language: Python 3.11+');
+      expect(section).toContain('- Framework: FastAPI');
+      expect(section).toContain('- Database: PostgreSQL');
+      expect(section).toContain('- ORM: SQLAlchemy');
+      expect(section).toContain('- Testing: Pytest');
+    });
+
+    it('should skip undefined fields', () => {
+      const section = getTechStackSection({ language: 'Python 3.11+' });
+      expect(section).toContain('- Language: Python 3.11+');
+      expect(section).not.toContain('Framework');
+      expect(section).not.toContain('Database');
+    });
+  });
+
+  describe('getArchitectureRules', () => {
+    it('should include FastAPI async rule for FastAPI projects', () => {
+      const rules = getArchitectureRules({ backend: 'FastAPI' });
+      expect(rules).toContain('async/await');
+    });
+
+    it('should include SQLAlchemy rule for SQLAlchemy projects', () => {
+      const rules = getArchitectureRules({ orm: 'SQLAlchemy' });
+      expect(rules).toContain('SQLAlchemy ORM');
+    });
+
+    it('should include Python-specific rules', () => {
+      const rules = getArchitectureRules({ language: 'Python 3.11+' });
+      expect(rules).toContain('PEP8');
+      expect(rules).toContain('python-dotenv');
+    });
+
+    it('should include TypeScript-specific rules', () => {
+      const rules = getArchitectureRules({ language: 'TypeScript 5.x' });
+      expect(rules).toContain('strict mode');
+    });
+
+    it('should provide generic rules when no tech matches', () => {
+      const rules = getArchitectureRules({});
+      expect(rules).toContain('Environment variables');
+    });
+  });
+
+  describe('getCodeQualityRules', () => {
+    it('should include file size limit', () => {
+      const rules = getCodeQualityRules();
+      expect(rules).toContain('500 lines');
+    });
+
+    it('should include test requirements', () => {
+      const rules = getCodeQualityRules();
+      expect(rules).toContain('Unit tests');
+    });
+  });
+
+  describe('getConstraintsSection', () => {
+    it('should include Python constraints for python language', () => {
+      const section = getConstraintsSection('python');
+      expect(section).toContain('Python 3.11+');
+      expect(section).toContain('venv');
+    });
+
+    it('should include TypeScript constraints for typescript', () => {
+      const section = getConstraintsSection('typescript');
+      expect(section).toContain('Node.js 18+');
+      expect(section).toContain('ESM');
+    });
+
+    it('should include session guidance when provided', () => {
+      const section = getConstraintsSection('python', 'Focus on security');
+      expect(section).toContain('Session-Specific Guidance');
+      expect(section).toContain('Focus on security');
+    });
+  });
+});

package/tests/pipeline/skills/generator.test.ts

@@ -0,0 +1,213 @@
+/**
+ * Skill generator tests — prompt building, parsing, rendering, skip logic.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  shouldGenerateSkill,
+  buildSkillGenPrompt,
+  parseSkillPrompts,
+  renderSkillMarkdown,
+  writeGenerationMarker,
+} from '../../../src/pipeline/skills/generator.js';
+import type { SkillGenerationContext } from '../../../src/pipeline/skills/types.js';
+import type { RepoSnapshot } from '../../../src/pipeline/types.js';
+
+const TEST_DIR = join(process.cwd(), '.test-skill-generator');
+const SKILLS_DIR = join(TEST_DIR, 'skills');
+
+function makeSnapshot(): RepoSnapshot {
+  return {
+    snapshot_id: 'test-snap',
+    timestamp: new Date().toISOString(),
+    tree_summary: '',
+    config_files: [],
+    languages_detected: [],
+    scripts: {},
+    env_files: [],
+    migrations_present: false,
+    ports_entrypoints: [],
+    total_files: 0,
+    total_lines: 0,
+  };
+}
+
+function makeContext(overrides: Partial<SkillGenerationContext> = {}): SkillGenerationContext {
+  return {
+    language: 'python',
+    expandedSpec: 'Build a REST API for task management',
+    snapshot: makeSnapshot(),
+    activeRoles: ['DISPATCHER', 'ARCHITECT', 'BACKEND_PROGRAMMER', 'DB_EXPERT'],
+    skillsDir: SKILLS_DIR,
+    projectName: 'TestProject',
+    ...overrides,
+  };
+}
+
+describe('generator', () => {
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+    mkdirSync(SKILLS_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+  });
+
+  describe('shouldGenerateSkill', () => {
+    it('should return true when no .md file exists', () => {
+      expect(shouldGenerateSkill(SKILLS_DIR, 'BACKEND_PROGRAMMER')).toBe(true);
+    });
+
+    it('should return false when .md file already exists', () => {
+      writeFileSync(join(SKILLS_DIR, 'BACKEND_PROGRAMMER.md'), 'existing content');
+      expect(shouldGenerateSkill(SKILLS_DIR, 'BACKEND_PROGRAMMER')).toBe(false);
+    });
+
+    it('should check per-role independently', () => {
+      writeFileSync(join(SKILLS_DIR, 'ARCHITECT.md'), 'existing');
+      expect(shouldGenerateSkill(SKILLS_DIR, 'ARCHITECT')).toBe(false);
+      expect(shouldGenerateSkill(SKILLS_DIR, 'BACKEND_PROGRAMMER')).toBe(true);
+    });
+  });
+
+  describe('buildSkillGenPrompt', () => {
+    it('should include project name and tech stack', () => {
+      const prompt = buildSkillGenPrompt(
+        makeContext(),
+        ['BACKEND_PROGRAMMER'],
+        { backend: 'FastAPI', language: 'Python 3.11+' },
+      );
+      expect(prompt).toContain('TestProject');
+      expect(prompt).toContain('FastAPI');
+      expect(prompt).toContain('Python 3.11+');
+    });
+
+    it('should include role descriptions', () => {
+      const prompt = buildSkillGenPrompt(
+        makeContext(),
+        ['BACKEND_PROGRAMMER', 'DB_EXPERT'],
+        { backend: 'FastAPI' },
+      );
+      expect(prompt).toContain('BACKEND_PROGRAMMER');
+      expect(prompt).toContain('DB_EXPERT');
+    });
+
+    it('should include session guidance when present', () => {
+      const prompt = buildSkillGenPrompt(
+        makeContext({ sessionGuidance: 'Focus on security' }),
+        ['BACKEND_PROGRAMMER'],
+        { backend: 'FastAPI' },
+      );
+      expect(prompt).toContain('Focus on security');
+    });
+
+    it('should include expanded spec', () => {
+      const prompt = buildSkillGenPrompt(
+        makeContext({ expandedSpec: 'Build a REST API with auth' }),
+        ['BACKEND_PROGRAMMER'],
+        { backend: 'FastAPI' },
+      );
+      expect(prompt).toContain('Build a REST API with auth');
+    });
+  });
+
+  describe('parseSkillPrompts', () => {
+    it('should parse valid JSON response', () => {
+      const response = JSON.stringify({
+        BACKEND_PROGRAMMER: 'You are the Backend Programmer for MyProject.',
+        DB_EXPERT: 'You are the DB Expert for MyProject.',
+      });
+      const result = parseSkillPrompts(response, ['BACKEND_PROGRAMMER', 'DB_EXPERT']);
+      expect(result.BACKEND_PROGRAMMER).toContain('Backend Programmer');
+      expect(result.DB_EXPERT).toContain('DB Expert');
+    });
+
+    it('should extract JSON from markdown code fences', () => {
+      const response = '```json\n{"BACKEND_PROGRAMMER": "You are the Backend Programmer."}\n```';
+      const result = parseSkillPrompts(response, ['BACKEND_PROGRAMMER']);
+      expect(result.BACKEND_PROGRAMMER).toContain('Backend Programmer');
+    });
+
+    it('should return empty for malformed JSON', () => {
+      const result = parseSkillPrompts('not json at all', ['BACKEND_PROGRAMMER']);
+      expect(Object.keys(result)).toHaveLength(0);
+    });
+
+    it('should skip roles not in expectedRoles', () => {
+      const response = JSON.stringify({
+        BACKEND_PROGRAMMER: 'Valid prompt for backend.',
+        FRONTEND_PROGRAMMER: 'Should be ignored.',
+      });
+      const result = parseSkillPrompts(response, ['BACKEND_PROGRAMMER']);
+      expect(result.BACKEND_PROGRAMMER).toBeDefined();
+      expect(result.FRONTEND_PROGRAMMER).toBeUndefined();
+    });
+
+    it('should skip prompts shorter than 10 chars', () => {
+      const response = JSON.stringify({
+        BACKEND_PROGRAMMER: 'Short',
+      });
+      const result = parseSkillPrompts(response, ['BACKEND_PROGRAMMER']);
+      expect(result.BACKEND_PROGRAMMER).toBeUndefined();
+    });
+  });
+
+  describe('renderSkillMarkdown', () => {
+    it('should produce valid YAML frontmatter format', () => {
+      const md = renderSkillMarkdown(
+        'BACKEND_PROGRAMMER',
+        'You are the Backend Programmer.',
+        ['follow_architecture', 'must_follow_master_plan'],
+        ['endpoints', 'services'],
+        ['ARCHITECT'],
+      );
+
+      expect(md).toMatch(/^---\n/);
+      expect(md).toContain('role: BACKEND_PROGRAMMER');
+      expect(md).toContain('version: 1.0-project');
+      expect(md).toContain('  - endpoints');
+      expect(md).toContain('  - services');
+      expect(md).toContain('  - follow_architecture');
+      expect(md).toContain('  - must_follow_master_plan');
+      expect(md).toContain('depends_on:');
+      expect(md).toContain('  - ARCHITECT');
+      expect(md).toContain('You are the Backend Programmer.');
+    });
+
+    it('should omit depends_on when empty', () => {
+      const md = renderSkillMarkdown(
+        'DISPATCHER',
+        'You are the Dispatcher.',
+        ['governance'],
+        ['phase_transition'],
+        [],
+      );
+      expect(md).not.toContain('depends_on:');
+    });
+  });
+
+  describe('writeGenerationMarker', () => {
+    it('should write valid JSON marker file', () => {
+      const marker = {
+        timestamp: '2026-02-22T14:30:00Z',
+        pipelineVersion: '1.0',
+        activeRoles: ['DISPATCHER', 'BACKEND_PROGRAMMER'],
+        techStack: { backend: 'FastAPI' },
+        aiGenerated: true,
+      };
+      writeGenerationMarker(SKILLS_DIR, marker);
+
+      const markerPath = join(SKILLS_DIR, '.popeye-skills-generated.json');
+      expect(existsSync(markerPath)).toBe(true);
+
+      const content = JSON.parse(readFileSync(markerPath, 'utf-8'));
+      expect(content.pipelineVersion).toBe('1.0');
+      expect(content.aiGenerated).toBe(true);
+      expect(content.activeRoles).toContain('BACKEND_PROGRAMMER');
+      expect(content.techStack.backend).toBe('FastAPI');
+    });
+  });
+});

package/tests/pipeline/skills/role-map.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Role map tests — role selection, tech stack inference, template constraints.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  getActiveRoles,
+  inferTechStack,
+  getTemplateConstraints,
+  SUPPORT_ROLES,
+  IMPLEMENTATION_ROLES,
+} from '../../../src/pipeline/skills/role-map.js';
+import type { RepoSnapshot } from '../../../src/pipeline/types.js';
+import type { OutputLanguage } from '../../../src/types/project.js';
+
+function makeSnapshot(overrides: Partial<RepoSnapshot> = {}): RepoSnapshot {
+  return {
+    snapshot_id: 'test-snap',
+    timestamp: new Date().toISOString(),
+    tree_summary: '',
+    config_files: [],
+    languages_detected: [],
+    scripts: {},
+    env_files: [],
+    migrations_present: false,
+    ports_entrypoints: [],
+    total_files: 0,
+    total_lines: 0,
+    ...overrides,
+  };
+}
+
+describe('role-map', () => {
+  describe('getActiveRoles', () => {
+    it('should include support roles for all languages', () => {
+      const languages: OutputLanguage[] = ['python', 'typescript', 'fullstack', 'website', 'all'];
+      for (const lang of languages) {
+        const roles = getActiveRoles(lang);
+        for (const support of SUPPORT_ROLES) {
+          expect(roles).toContain(support);
+        }
+      }
+    });
+
+    it('should include DB_EXPERT for python', () => {
+      const roles = getActiveRoles('python');
+      expect(roles).toContain('DB_EXPERT');
+      expect(roles).toContain('BACKEND_PROGRAMMER');
+      expect(roles).not.toContain('FRONTEND_PROGRAMMER');
+    });
+
+    it('should include FRONTEND_PROGRAMMER for typescript (not BACKEND_PROGRAMMER)', () => {
+      const roles = getActiveRoles('typescript');
+      expect(roles).toContain('FRONTEND_PROGRAMMER');
+      expect(roles).toContain('UI_UX_SPECIALIST');
+      expect(roles).not.toContain('BACKEND_PROGRAMMER');
+      expect(roles).not.toContain('DB_EXPERT');
+    });
+
+    it('should include both FE and BE for fullstack', () => {
+      const roles = getActiveRoles('fullstack');
+      expect(roles).toContain('DB_EXPERT');
+      expect(roles).toContain('BACKEND_PROGRAMMER');
+      expect(roles).toContain('FRONTEND_PROGRAMMER');
+      expect(roles).toContain('UI_UX_SPECIALIST');
+      expect(roles).not.toContain('WEBSITE_PROGRAMMER');
+    });
+
+    it('should include website and marketing roles for website', () => {
+      const roles = getActiveRoles('website');
+      expect(roles).toContain('WEBSITE_PROGRAMMER');
+      expect(roles).toContain('UI_UX_SPECIALIST');
+      expect(roles).toContain('MARKETING_EXPERT');
+      expect(roles).toContain('SOCIAL_EXPERT');
+      expect(roles).not.toContain('BACKEND_PROGRAMMER');
+    });
+
+    it('should include all implementation roles for all', () => {
+      const roles = getActiveRoles('all');
+      for (const impl of IMPLEMENTATION_ROLES) {
+        expect(roles).toContain(impl);
+      }
+    });
+  });
+
+  describe('inferTechStack', () => {
+    it('should return language defaults when no signals', () => {
+      const ts = inferTechStack('python');
+      expect(ts.backend).toBe('FastAPI');
+      expect(ts.database).toBe('PostgreSQL');
+      expect(ts.orm).toBe('SQLAlchemy');
+      expect(ts.testing).toBe('Pytest');
+      expect(ts.language).toBe('Python 3.11+');
+    });
+
+    it('should detect FastAPI from snapshot key_fields', () => {
+      const snapshot = makeSnapshot({
+        config_files: [{
+          path: 'pyproject.toml',
+          type: 'toml',
+          content_hash: 'abc',
+          key_fields: { dependencies: ['fastapi', 'uvicorn'] },
+        }],
+      });
+      const ts = inferTechStack('python', snapshot);
+      expect(ts.backend).toBe('FastAPI');
+    });
+
+    it('should detect Django from snapshot key_fields', () => {
+      const snapshot = makeSnapshot({
+        config_files: [{
+          path: 'requirements.txt',
+          type: 'txt',
+          content_hash: 'abc',
+          key_fields: { packages: ['django', 'django-rest-framework'] },
+        }],
+      });
+      const ts = inferTechStack('python', snapshot);
+      expect(ts.backend).toBe('Django');
+    });
+
+    it('should detect framework from expanded spec when snapshot has no deps', () => {
+      const ts = inferTechStack('python', makeSnapshot(), 'Build a Django REST API');
+      expect(ts.backend).toBe('Django');
+    });
+
+    it('should prioritize snapshot over spec mentions', () => {
+      const snapshot = makeSnapshot({
+        config_files: [{
+          path: 'pyproject.toml',
+          type: 'toml',
+          content_hash: 'abc',
+          key_fields: { dependencies: ['fastapi'] },
+        }],
+      });
+      const ts = inferTechStack('python', snapshot, 'Build a Django API');
+      // Snapshot has fastapi, spec mentions Django — snapshot wins
+      expect(ts.backend).toBe('FastAPI');
+    });
+
+    it('should return typescript defaults', () => {
+      const ts = inferTechStack('typescript');
+      expect(ts.frontend).toBe('React + Vite');
+      expect(ts.testing).toBe('Vitest');
+      expect(ts.language).toBe('TypeScript 5.x');
+    });
+
+    it('should detect Next.js from snapshot', () => {
+      const snapshot = makeSnapshot({
+        config_files: [{
+          path: 'package.json',
+          type: 'json',
+          content_hash: 'abc',
+          key_fields: { dependencies: { next: '^14.0.0', react: '^18.0.0' } },
+        }],
+      });
+      const ts = inferTechStack('typescript', snapshot);
+      expect(ts.frontend).toBe('Next.js');
+    });
+  });
+
+  describe('getTemplateConstraints', () => {
+    it('should always include governance constraints', () => {
+      const constraints = getTemplateConstraints('BACKEND_PROGRAMMER', {});
+      expect(constraints).toContain('must_follow_master_plan');
+      expect(constraints).toContain('must_follow_architecture');
+      expect(constraints).toContain('conflicts_require_change_request');
+    });
+
+    it('should add FastAPI constraints for backend with FastAPI', () => {
+      const constraints = getTemplateConstraints('BACKEND_PROGRAMMER', {
+        backend: 'FastAPI',
+        testing: 'Pytest',
+      });
+      expect(constraints).toContain('fastapi_async_required');
+      expect(constraints).toContain('pydantic_validation');
+      expect(constraints).toContain('pytest_testing');
+    });
+
+    it('should add React constraints for frontend', () => {
+      const constraints = getTemplateConstraints('FRONTEND_PROGRAMMER', {
+        frontend: 'React + Vite',
+        testing: 'Vitest',
+      });
+      expect(constraints).toContain('react_component_pattern');
+      expect(constraints).toContain('component_testing');
+    });
+
+    it('should return only governance constraints for roles without tech constraints', () => {
+      const constraints = getTemplateConstraints('DISPATCHER', {});
+      expect(constraints).toEqual([
+        'must_follow_master_plan',
+        'must_follow_architecture',
+        'conflicts_require_change_request',
+      ]);
+    });
+  });
+});