@codemcp/workflows-core 3.1.16

package/test/unit/project-docs-manager.test.ts

@@ -0,0 +1,337 @@
+/**
+ * Unit tests for ProjectDocsManager
+ *
+ * Tests project documentation management functionality
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { TestAccess } from '../utils/test-access.js';
+import { ProjectDocsManager } from '@codemcp/workflows-core';
+import { TemplateManager } from '@codemcp/workflows-core';
+import { mkdir, writeFile, rmdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+// Mock TemplateManager
+vi.mock('../../src/template-manager.js');
+
+describe('ProjectDocsManager', () => {
+  let projectDocsManager: ProjectDocsManager;
+  let testProjectPath: string;
+  let mockTemplateManager: vi.Mocked<TemplateManager>;
+
+  beforeEach(async () => {
+    // Create a temporary directory for test project
+    testProjectPath = join(tmpdir(), `project-test-${Date.now()}`);
+    await mkdir(testProjectPath, { recursive: true });
+
+    // Mock TemplateManager
+    mockTemplateManager = {
+      getDefaults: vi.fn().mockReturnValue({
+        architecture: 'arc42',
+        requirements: 'ears',
+        design: 'comprehensive',
+      }),
+      validateOptions: vi.fn(),
+      loadTemplate: vi.fn(),
+      getAvailableTemplates: vi.fn(),
+    } as Partial<TemplateManager>;
+
+    projectDocsManager = new ProjectDocsManager();
+    TestAccess.injectMock(
+      projectDocsManager,
+      'templateManager',
+      mockTemplateManager
+    );
+  });
+
+  afterEach(async () => {
+    // Clean up test directory
+    try {
+      await rmdir(testProjectPath, { recursive: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('getDocsPath', () => {
+    it('should return correct docs path', () => {
+      const docsPath = projectDocsManager.getDocsPath(testProjectPath);
+      expect(docsPath).toBe(join(testProjectPath, '.vibe', 'docs'));
+    });
+  });
+
+  describe('getDocumentPaths', () => {
+    it('should return correct document paths', () => {
+      const paths = projectDocsManager.getDocumentPaths(testProjectPath);
+
+      expect(paths.architecture).toBe(
+        join(testProjectPath, '.vibe', 'docs', 'architecture.md')
+      );
+      expect(paths.requirements).toBe(
+        join(testProjectPath, '.vibe', 'docs', 'requirements.md')
+      );
+      expect(paths.design).toBe(
+        join(testProjectPath, '.vibe', 'docs', 'design.md')
+      );
+    });
+  });
+
+  describe('getProjectDocsInfo', () => {
+    it('should return info when no documents exist', async () => {
+      const info = await projectDocsManager.getProjectDocsInfo(testProjectPath);
+
+      expect(info.architecture.exists).toBe(false);
+      expect(info.requirements.exists).toBe(false);
+      expect(info.design.exists).toBe(false);
+      expect(info.architecture.path).toBe(
+        join(testProjectPath, '.vibe', 'docs', 'architecture.md')
+      );
+    });
+
+    it('should return info when documents exist', async () => {
+      // Create docs directory and files
+      const docsPath = join(testProjectPath, '.vibe', 'docs');
+      await mkdir(docsPath, { recursive: true });
+      await writeFile(join(docsPath, 'architecture.md'), '# Architecture');
+      await writeFile(join(docsPath, 'requirements.md'), '# Requirements');
+
+      const info = await projectDocsManager.getProjectDocsInfo(testProjectPath);
+
+      expect(info.architecture.exists).toBe(true);
+      expect(info.requirements.exists).toBe(true);
+      expect(info.design.exists).toBe(false);
+    });
+  });
+
+  describe('createProjectDocs', () => {
+    beforeEach(() => {
+      // Setup template manager mocks
+      mockTemplateManager.loadTemplate.mockImplementation(
+        async (type, template) => {
+          return {
+            content: `# Test ${type} template (${template})\n\nTest content for ${type}.`,
+          };
+        }
+      );
+    });
+
+    it('should create all documents with default templates', async () => {
+      const result =
+        await projectDocsManager.createProjectDocs(testProjectPath);
+
+      expect(result.created).toEqual([
+        'architecture.md',
+        'requirements.md',
+        'design.md',
+      ]);
+      expect(result.skipped).toEqual([]);
+
+      // Verify template manager was called with defaults
+      expect(mockTemplateManager.loadTemplate).toHaveBeenCalledWith(
+        'architecture',
+        'arc42'
+      );
+      expect(mockTemplateManager.loadTemplate).toHaveBeenCalledWith(
+        'requirements',
+        'ears'
+      );
+      expect(mockTemplateManager.loadTemplate).toHaveBeenCalledWith(
+        'design',
+        'comprehensive'
+      );
+
+      // Verify files were created
+      const docsPath = join(testProjectPath, '.vibe', 'docs');
+      const archContent = await readFile(
+        join(docsPath, 'architecture.md'),
+        'utf-8'
+      );
+      expect(archContent).toContain('Test architecture template (arc42)');
+    });
+
+    it('should create documents with custom templates', async () => {
+      const options = {
+        architecture: 'freestyle' as const,
+        requirements: 'freestyle' as const,
+        design: 'freestyle' as const,
+      };
+
+      const result = await projectDocsManager.createProjectDocs(
+        testProjectPath,
+        options
+      );
+
+      expect(result.created).toEqual([
+        'architecture.md',
+        'requirements.md',
+        'design.md',
+      ]);
+      expect(result.skipped).toEqual([]);
+
+      // Verify template manager was called with custom options
+      expect(mockTemplateManager.loadTemplate).toHaveBeenCalledWith(
+        'architecture',
+        'freestyle'
+      );
+      expect(mockTemplateManager.loadTemplate).toHaveBeenCalledWith(
+        'requirements',
+        'freestyle'
+      );
+      expect(mockTemplateManager.loadTemplate).toHaveBeenCalledWith(
+        'design',
+        'freestyle'
+      );
+    });
+
+    it('should skip existing documents', async () => {
+      // Create docs directory and one existing file
+      const docsPath = join(testProjectPath, '.vibe', 'docs');
+      await mkdir(docsPath, { recursive: true });
+      await writeFile(
+        join(docsPath, 'architecture.md'),
+        '# Existing Architecture'
+      );
+
+      const result =
+        await projectDocsManager.createProjectDocs(testProjectPath);
+
+      expect(result.created).toEqual(['requirements.md', 'design.md']);
+      expect(result.skipped).toEqual(['architecture.md']);
+
+      // Verify existing file wasn't overwritten
+      const archContent = await readFile(
+        join(docsPath, 'architecture.md'),
+        'utf-8'
+      );
+      expect(archContent).toBe('# Existing Architecture');
+    });
+
+    it('should handle template with additional files', async () => {
+      mockTemplateManager.loadTemplate.mockImplementation(
+        async (type, template) => {
+          if (type === 'architecture' && template === 'arc42') {
+            return {
+              content: '# Arc42 Template\n\nSee images/diagram.png',
+              additionalFiles: [
+                {
+                  relativePath: 'images/diagram.png',
+                  content: Buffer.from('fake-image-data'),
+                },
+              ],
+            };
+          }
+          return {
+            content: `# Test ${type} template (${template})`,
+          };
+        }
+      );
+
+      const result =
+        await projectDocsManager.createProjectDocs(testProjectPath);
+
+      expect(result.created).toEqual([
+        'architecture.md',
+        'requirements.md',
+        'design.md',
+      ]);
+
+      // Verify additional file was created
+      const imagePath = join(
+        testProjectPath,
+        '.vibe',
+        'docs',
+        'images',
+        'diagram.png'
+      );
+      const imageContent = await readFile(imagePath);
+      expect(imageContent).toEqual(Buffer.from('fake-image-data'));
+    });
+
+    it('should handle template loading errors', async () => {
+      mockTemplateManager.loadTemplate.mockRejectedValue(
+        new Error('Template not found')
+      );
+
+      // The method should throw when template loading fails
+      await expect(
+        projectDocsManager.createProjectDocs(testProjectPath)
+      ).rejects.toThrow('Template not found');
+    });
+  });
+
+  describe('getVariableSubstitutions', () => {
+    it('should return correct variable substitutions', () => {
+      const substitutions =
+        projectDocsManager.getVariableSubstitutions(testProjectPath);
+
+      expect(substitutions).toEqual({
+        $ARCHITECTURE_DOC: join(
+          testProjectPath,
+          '.vibe',
+          'docs',
+          'architecture.md'
+        ),
+        $REQUIREMENTS_DOC: join(
+          testProjectPath,
+          '.vibe',
+          'docs',
+          'requirements.md'
+        ),
+        $DESIGN_DOC: join(testProjectPath, '.vibe', 'docs', 'design.md'),
+      });
+    });
+  });
+
+  describe('readDocument', () => {
+    it('should return path to existing document', async () => {
+      // Create docs directory and file
+      const docsPath = join(testProjectPath, '.vibe', 'docs');
+      await mkdir(docsPath, { recursive: true });
+      await writeFile(join(docsPath, 'architecture.md'), '# Test Architecture');
+
+      const path = await projectDocsManager.readDocument(
+        testProjectPath,
+        'architecture'
+      );
+      expect(path).toContain('architecture.md');
+      expect(path).toContain('.vibe/docs');
+    });
+
+    it('should throw error for non-existent document', async () => {
+      await expect(
+        projectDocsManager.readDocument(testProjectPath, 'architecture')
+      ).rejects.toThrow('architecture document not found');
+    });
+  });
+
+  describe('allDocumentsExist', () => {
+    it('should return false when no documents exist', async () => {
+      const result =
+        await projectDocsManager.allDocumentsExist(testProjectPath);
+      expect(result).toBe(false);
+    });
+
+    it('should return false when some documents exist', async () => {
+      const docsPath = join(testProjectPath, '.vibe', 'docs');
+      await mkdir(docsPath, { recursive: true });
+      await writeFile(join(docsPath, 'architecture.md'), '# Architecture');
+
+      const result =
+        await projectDocsManager.allDocumentsExist(testProjectPath);
+      expect(result).toBe(false);
+    });
+
+    it('should return true when all documents exist', async () => {
+      const docsPath = join(testProjectPath, '.vibe', 'docs');
+      await mkdir(docsPath, { recursive: true });
+      await writeFile(join(docsPath, 'architecture.md'), '# Architecture');
+      await writeFile(join(docsPath, 'requirements.md'), '# Requirements');
+      await writeFile(join(docsPath, 'design.md'), '# Design');
+
+      const result =
+        await projectDocsManager.allDocumentsExist(testProjectPath);
+      expect(result).toBe(true);
+    });
+  });
+});

package/test/unit/state-machine-loader.test.ts

@@ -0,0 +1,234 @@
+/**
+ * Unit tests for StateMachineLoader
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { StateMachineLoader } from '@codemcp/workflows-core';
+
+// Mock global URL constructor
+global.URL = vi.fn().mockImplementation(() => ({
+  pathname: '/mock/src/state-machine-loader.ts',
+})) as typeof URL;
+
+// Mock import.meta.url
+vi.stubGlobal('import.meta', {
+  url: 'file:///mock/src/state-machine-loader.ts',
+});
+
+// Create a mock state machine object
+const mockStateMachine = {
+  name: 'Test State Machine',
+  description: 'Test state machine for unit tests',
+  initial_state: 'idle',
+  states: {
+    idle: {
+      description: 'Idle state',
+      default_instructions:
+        'Starting idle state. Wait for user input and analyze requests.',
+      transitions: [
+        {
+          trigger: 'new_feature_request',
+          to: 'requirements',
+          instructions: 'Start requirements analysis',
+          transition_reason: 'New feature request detected',
+        },
+      ],
+    },
+    requirements: {
+      description: 'Requirements state',
+      default_instructions:
+        'Starting requirements analysis. Gather and document user requirements.',
+      transitions: [],
+    },
+  },
+};
+
+// Mock modules
+vi.mock('fs', () => {
+  return {
+    default: {
+      existsSync: vi.fn(),
+      readFileSync: vi.fn(),
+    },
+    existsSync: vi.fn(),
+    readFileSync: vi.fn(),
+  };
+});
+
+vi.mock('path', () => {
+  return {
+    default: {
+      resolve: vi.fn(p => p),
+      join: vi.fn((...paths) => paths.join('/')),
+      dirname: vi.fn(p => {
+        if (!p) return '';
+        const lastSlash = p.lastIndexOf('/');
+        return lastSlash >= 0 ? p.substring(0, lastSlash) : p;
+      }),
+    },
+    resolve: vi.fn(p => p),
+    join: vi.fn((...paths) => paths.join('/')),
+    dirname: vi.fn(p => {
+      if (!p) return '';
+      const lastSlash = p.lastIndexOf('/');
+      return lastSlash >= 0 ? p.substring(0, lastSlash) : p;
+    }),
+  };
+});
+
+// Properly mock js-yaml with a default export
+vi.mock('js-yaml', () => {
+  return {
+    default: {
+      load: vi.fn(() => mockStateMachine),
+      dump: vi.fn(() => 'mocked yaml content'),
+    },
+    load: vi.fn(() => mockStateMachine),
+    dump: vi.fn(() => 'mocked yaml content'),
+  };
+});
+
+// Silence logger
+vi.mock('../../src/logger.ts', () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    child: () => ({
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    }),
+  }),
+}));
+
+// Import mocked modules
+import fs from 'node:fs';
+
+describe('StateMachineLoader', () => {
+  let stateMachineLoader: StateMachineLoader;
+
+  beforeEach(() => {
+    // Reset mocks
+    vi.resetAllMocks();
+
+    // Create a new instance for each test
+    stateMachineLoader = new StateMachineLoader();
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  describe('loadStateMachine', () => {
+    it('should load custom state machine file if it exists', () => {
+      // Mock fs.existsSync to return true for custom file
+      vi.mocked(fs.existsSync).mockImplementation(p => {
+        return String(p) === 'project/.vibe/workflow.yaml';
+      });
+
+      // Mock fs.readFileSync to return valid YAML content
+      vi.mocked(fs.readFileSync).mockReturnValue('valid yaml content');
+
+      const result = stateMachineLoader.loadStateMachine('project');
+
+      expect(fs.existsSync).toHaveBeenCalledWith('project/.vibe/workflow.yaml');
+      expect(fs.readFileSync).toHaveBeenCalledWith(
+        'project/.vibe/workflow.yaml',
+        'utf8'
+      );
+      expect(result).toBeDefined();
+      expect(result.name).toBe('Test State Machine');
+    });
+
+    it('should load default state machine file if custom file does not exist', () => {
+      // Mock fs.existsSync to return false for all paths
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+
+      // Mock fs.readFileSync to return valid YAML content
+      vi.mocked(fs.readFileSync).mockReturnValue('valid yaml content');
+
+      const result = stateMachineLoader.loadStateMachine('project');
+
+      expect(fs.existsSync).toHaveBeenCalledWith('project/.vibe/workflow.yaml');
+      expect(fs.existsSync).toHaveBeenCalledWith('project/.vibe/workflow.yml');
+
+      // The path might be absolute or relative depending on the environment
+      expect(fs.readFileSync).toHaveBeenCalled();
+      expect(vi.mocked(fs.readFileSync).mock.calls[0][0]).toMatch(
+        /.*resources\/workflows\/waterfall\.yaml$/
+      );
+      expect(vi.mocked(fs.readFileSync).mock.calls[0][1]).toBe('utf8');
+      expect(result).toBeDefined();
+      expect(result.name).toBe('Test State Machine');
+    });
+  });
+
+  describe('loadFromFile', () => {
+    it('should load and validate state machine from file', () => {
+      // Mock fs.readFileSync to return valid YAML content
+      vi.mocked(fs.readFileSync).mockReturnValue('valid yaml content');
+
+      const result = stateMachineLoader.loadFromFile('test-file.yaml');
+
+      expect(fs.readFileSync).toHaveBeenCalledWith('test-file.yaml', 'utf8');
+      expect(result).toBeDefined();
+      expect(result.name).toBe('Test State Machine');
+    });
+
+    it('should throw error if file cannot be loaded', () => {
+      // Mock fs.readFileSync to throw error
+      vi.mocked(fs.readFileSync).mockImplementation(() => {
+        throw new Error('File not found');
+      });
+
+      expect(() =>
+        stateMachineLoader.loadFromFile('invalid-file.yaml')
+      ).toThrow('Failed to load state machine: File not found');
+    });
+  });
+
+  describe('getTransitionInstructions', () => {
+    beforeEach(() => {
+      // Load state machine
+      vi.mocked(fs.readFileSync).mockReturnValue('valid yaml content');
+      stateMachineLoader.loadFromFile('test-file.yaml');
+    });
+
+    it('should return transition instructions for modeled transition', () => {
+      const result = stateMachineLoader.getTransitionInstructions(
+        'idle',
+        'requirements',
+        'new_feature_request'
+      );
+
+      expect(result).toEqual({
+        instructions: 'Start requirements analysis',
+        transitionReason: 'New feature request detected',
+        isModeled: true,
+      });
+    });
+
+    it('should return default instructions when no modeled transition exists', () => {
+      const result = stateMachineLoader.getTransitionInstructions(
+        'requirements',
+        'idle'
+      );
+
+      expect(result).toEqual({
+        instructions:
+          'Starting idle state. Wait for user input and analyze requests.',
+        transitionReason: 'Direct transition to idle phase',
+        isModeled: false,
+      });
+    });
+
+    it('should throw error if no transition found', () => {
+      expect(() =>
+        stateMachineLoader.getTransitionInstructions('requirements', 'unknown')
+      ).toThrow('Target state "unknown" not found');
+    });
+  });
+});