@kjerneverk/riotplan-catalyst 1.0.0-dev.0

package/src/types.ts

@@ -0,0 +1,140 @@
+/**
+ * TypeScript interfaces for the catalyst system
+ * @packageDocumentation
+ */
+
+import type { FacetType } from '@/schema/schemas';
+
+/**
+ * Content loaded from a single facet file
+ */
+export interface FacetContent {
+  /** Filename without path (e.g., "testing.md") */
+  filename: string;
+  /** Full content of the file */
+  content: string;
+}
+
+/**
+ * Container for all loaded facet content from a catalyst
+ * Each facet type maps to an array of file contents
+ */
+export interface CatalystFacets {
+  /** Guiding questions for idea exploration and shaping */
+  questions?: FacetContent[];
+  /** Constraints and rules the plan must satisfy */
+  constraints?: FacetContent[];
+  /** Templates for expected deliverables (press release, 6-pager, etc.) */
+  outputTemplates?: FacetContent[];
+  /** Context about the domain, organization, or technology */
+  domainKnowledge?: FacetContent[];
+  /** Guidance on how to run the planning process */
+  processGuidance?: FacetContent[];
+  /** Post-creation validation checks */
+  validationRules?: FacetContent[];
+}
+
+/**
+ * Parsed catalyst.yml manifest
+ */
+export interface CatalystManifest {
+  /** Catalyst identifier (NPM package name) */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Description of what this catalyst provides */
+  description: string;
+  /** Semver version */
+  version: string;
+  /** Declaration of which facets this catalyst provides */
+  facets?: {
+    questions?: boolean;
+    constraints?: boolean;
+    outputTemplates?: boolean;
+    domainKnowledge?: boolean;
+    processGuidance?: boolean;
+    validationRules?: boolean;
+  };
+}
+
+/**
+ * A fully loaded catalyst with manifest and all facet content
+ */
+export interface Catalyst {
+  /** Parsed manifest from catalyst.yml */
+  manifest: CatalystManifest;
+  /** Loaded content for each facet type */
+  facets: CatalystFacets;
+  /** Absolute path to the catalyst directory */
+  directoryPath: string;
+}
+
+/**
+ * Result of loading a catalyst - either success or error
+ */
+export interface CatalystLoadResult {
+  success: boolean;
+  catalyst?: Catalyst;
+  error?: string;
+  warnings?: string[];
+}
+
+/**
+ * Options for loading a catalyst
+ */
+export interface CatalystLoadOptions {
+  /** Whether to validate the manifest strictly */
+  strict?: boolean;
+  /** Whether to warn about declared but missing facets */
+  warnOnMissingFacets?: boolean;
+  /** Whether to warn about present but undeclared facets */
+  warnOnUndeclaredFacets?: boolean;
+}
+
+/**
+ * Mapping from facet type to directory name on disk
+ */
+export type FacetDirectoryMap = Record<FacetType, string>;
+
+/**
+ * Plan manifest stored in plan.yaml
+ */
+export interface PlanManifest {
+  /** Plan identifier */
+  id: string;
+  /** Human-readable title */
+  title: string;
+  /** Ordered list of catalyst IDs */
+  catalysts?: string[];
+  /** ISO timestamp of creation */
+  created?: string;
+  /** Extensible metadata */
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Content with source attribution (used in merged catalysts)
+ */
+export interface AttributedContent {
+  /** The actual content */
+  content: string;
+  /** ID of the source catalyst */
+  sourceId: string;
+  /** Original filename (for reference) */
+  filename?: string;
+}
+
+/**
+ * Merged catalysts with source tracking
+ */
+export interface MergedCatalyst {
+  /** Ordered list of catalyst IDs that were merged */
+  catalystIds: string[];
+  /** Merged facets with source attribution */
+  facets: Record<string, AttributedContent[] | undefined>;
+  /** Metadata about each catalyst's contribution */
+  contributions: Map<string, {
+    facetTypes: string[];
+    contentCount: number;
+  }>;
+}

package/tests/catalyst-loader.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect } from 'vitest';
+import { join } from 'node:path';
+import { 
+  loadCatalyst, 
+  loadCatalystSafe,
+  resolveCatalysts,
+} from '@/loader/catalyst-loader';
+
+const FIXTURES_DIR = join(__dirname, 'fixtures');
+const COMPLETE_CATALYST = join(FIXTURES_DIR, 'complete-catalyst');
+const PARTIAL_CATALYST = join(FIXTURES_DIR, 'partial-catalyst');
+const INVALID_CATALYST = join(FIXTURES_DIR, 'invalid-catalyst');
+
+describe('loadCatalyst', () => {
+  describe('loading complete catalyst', () => {
+    it('loads a catalyst with all facets', async () => {
+      const catalyst = await loadCatalyst(COMPLETE_CATALYST);
+      
+      expect(catalyst.manifest.id).toBe('@test/complete-catalyst');
+      expect(catalyst.manifest.name).toBe('Complete Test Catalyst');
+      expect(catalyst.manifest.version).toBe('1.0.0');
+      expect(catalyst.directoryPath).toBe(COMPLETE_CATALYST);
+    });
+
+    it('loads all six facet types', async () => {
+      const catalyst = await loadCatalyst(COMPLETE_CATALYST);
+      
+      expect(catalyst.facets.questions).toBeDefined();
+      expect(catalyst.facets.constraints).toBeDefined();
+      expect(catalyst.facets.outputTemplates).toBeDefined();
+      expect(catalyst.facets.domainKnowledge).toBeDefined();
+      expect(catalyst.facets.processGuidance).toBeDefined();
+      expect(catalyst.facets.validationRules).toBeDefined();
+    });
+
+    it('loads multiple files per facet', async () => {
+      const catalyst = await loadCatalyst(COMPLETE_CATALYST);
+      
+      // Questions has 2 files: exploration.md and shaping.md
+      expect(catalyst.facets.questions).toHaveLength(2);
+      expect(catalyst.facets.questions?.map(f => f.filename).sort()).toEqual([
+        'exploration.md',
+        'shaping.md',
+      ]);
+      
+      // Constraints has 2 files
+      expect(catalyst.facets.constraints).toHaveLength(2);
+    });
+
+    it('loads file content correctly', async () => {
+      const catalyst = await loadCatalyst(COMPLETE_CATALYST);
+      
+      const exploration = catalyst.facets.questions?.find(
+        f => f.filename === 'exploration.md'
+      );
+      
+      expect(exploration).toBeDefined();
+      expect(exploration?.content).toContain('Exploration Questions');
+      expect(exploration?.content).toContain('What problem are you trying to solve?');
+    });
+  });
+
+  describe('loading partial catalyst', () => {
+    it('loads a catalyst with only some facets', async () => {
+      const catalyst = await loadCatalyst(PARTIAL_CATALYST);
+      
+      expect(catalyst.manifest.id).toBe('@test/partial-catalyst');
+      expect(catalyst.manifest.version).toBe('1.0.0-dev.0');
+    });
+
+    it('loads only declared facets', async () => {
+      const catalyst = await loadCatalyst(PARTIAL_CATALYST);
+      
+      // Only questions and constraints are present
+      expect(catalyst.facets.questions).toBeDefined();
+      expect(catalyst.facets.constraints).toBeDefined();
+      
+      // Other facets should be undefined
+      expect(catalyst.facets.outputTemplates).toBeUndefined();
+      expect(catalyst.facets.domainKnowledge).toBeUndefined();
+      expect(catalyst.facets.processGuidance).toBeUndefined();
+      expect(catalyst.facets.validationRules).toBeUndefined();
+    });
+
+    it('handles missing facets gracefully', async () => {
+      const catalyst = await loadCatalyst(PARTIAL_CATALYST);
+      
+      // Should not throw, just have undefined facets
+      expect(catalyst).toBeDefined();
+      expect(catalyst.facets).toBeDefined();
+    });
+  });
+
+  describe('error handling', () => {
+    it('throws error for missing manifest', async () => {
+      await expect(loadCatalyst(INVALID_CATALYST)).rejects.toThrow(
+        'Catalyst manifest not found'
+      );
+    });
+
+    it('throws error for non-existent directory', async () => {
+      await expect(loadCatalyst('/nonexistent/path')).rejects.toThrow(
+        'Catalyst directory not found'
+      );
+    });
+
+    it('throws error for invalid manifest', async () => {
+      // Create a test with invalid YAML by using a temp directory
+      // For now, we'll skip this test as it requires temp file creation
+      // This would be tested in integration tests
+    });
+  });
+
+  describe('path resolution', () => {
+    it('resolves relative paths', async () => {
+      const catalyst = await loadCatalyst('./tests/fixtures/complete-catalyst');
+      expect(catalyst.manifest.id).toBe('@test/complete-catalyst');
+    });
+
+    it('resolves absolute paths', async () => {
+      const catalyst = await loadCatalyst(COMPLETE_CATALYST);
+      expect(catalyst.manifest.id).toBe('@test/complete-catalyst');
+    });
+
+    it('stores absolute path in catalyst', async () => {
+      const catalyst = await loadCatalyst('./tests/fixtures/complete-catalyst');
+      expect(catalyst.directoryPath).toContain('tests/fixtures/complete-catalyst');
+      expect(catalyst.directoryPath).not.toContain('./');
+    });
+  });
+});
+
+describe('loadCatalystSafe', () => {
+  it('returns success result for valid catalyst', async () => {
+    const result = await loadCatalystSafe(COMPLETE_CATALYST);
+    
+    expect(result.success).toBe(true);
+    expect(result.catalyst).toBeDefined();
+    expect(result.error).toBeUndefined();
+  });
+
+  it('returns error result for invalid catalyst', async () => {
+    const result = await loadCatalystSafe(INVALID_CATALYST);
+    
+    expect(result.success).toBe(false);
+    expect(result.catalyst).toBeUndefined();
+    expect(result.error).toBeDefined();
+    expect(result.error).toContain('manifest not found');
+  });
+
+  it('returns error result for non-existent directory', async () => {
+    const result = await loadCatalystSafe('/nonexistent/path');
+    
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('not found');
+  });
+});
+
+describe('resolveCatalysts', () => {
+  it('resolves multiple catalysts', async () => {
+    const catalysts = await resolveCatalysts(
+      ['./tests/fixtures/complete-catalyst', './tests/fixtures/partial-catalyst'],
+      process.cwd()
+    );
+    
+    expect(catalysts).toHaveLength(2);
+    expect(catalysts[0].manifest.id).toBe('@test/complete-catalyst');
+    expect(catalysts[1].manifest.id).toBe('@test/partial-catalyst');
+  });
+
+  it('resolves relative to base path', async () => {
+    const catalysts = await resolveCatalysts(
+      ['complete-catalyst', 'partial-catalyst'],
+      join(process.cwd(), 'tests/fixtures')
+    );
+    
+    expect(catalysts).toHaveLength(2);
+  });
+
+  it('throws error if any catalyst fails to load', async () => {
+    await expect(
+      resolveCatalysts(
+        ['./tests/fixtures/complete-catalyst', '/nonexistent'],
+        process.cwd()
+      )
+    ).rejects.toThrow('Failed to load catalyst');
+  });
+
+  it('returns empty array for empty identifiers', async () => {
+    const catalysts = await resolveCatalysts([], process.cwd());
+    expect(catalysts).toEqual([]);
+  });
+
+  it('preserves order of catalysts', async () => {
+    const catalysts = await resolveCatalysts(
+      ['./tests/fixtures/partial-catalyst', './tests/fixtures/complete-catalyst'],
+      process.cwd()
+    );
+    
+    expect(catalysts[0].manifest.id).toBe('@test/partial-catalyst');
+    expect(catalysts[1].manifest.id).toBe('@test/complete-catalyst');
+  });
+});
+
+describe('facet loading details', () => {
+  it('only loads .md files', async () => {
+    const catalyst = await loadCatalyst(COMPLETE_CATALYST);
+    
+    // All loaded files should end with .md
+    for (const facetContent of Object.values(catalyst.facets)) {
+      if (facetContent) {
+        for (const file of facetContent) {
+          expect(file.filename).toMatch(/\.md$/);
+        }
+      }
+    }
+  });
+
+  it('loads file content as strings', async () => {
+    const catalyst = await loadCatalyst(COMPLETE_CATALYST);
+    
+    for (const facetContent of Object.values(catalyst.facets)) {
+      if (facetContent) {
+        for (const file of facetContent) {
+          expect(typeof file.content).toBe('string');
+          expect(file.content.length).toBeGreaterThan(0);
+        }
+      }
+    }
+  });
+
+  it('preserves file content exactly', async () => {
+    const catalyst = await loadCatalyst(COMPLETE_CATALYST);
+    
+    const testing = catalyst.facets.constraints?.find(
+      f => f.filename === 'testing.md'
+    );
+    
+    expect(testing?.content).toContain('# Testing Constraints');
+    expect(testing?.content).toContain('Every plan must include a testing step');
+    expect(testing?.content).toContain('Coverage threshold: 80%');
+  });
+});

package/tests/facet-merger.test.ts

@@ -0,0 +1,311 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { join } from 'node:path';
+import { loadCatalyst } from '@/loader/catalyst-loader';
+import {
+  mergeCatalysts,
+  renderFacet,
+  renderAllFacets,
+  summarizeMerge,
+} from '@/merger/facet-merger';
+
+const FIXTURES_DIR = join(__dirname, 'fixtures');
+const COMPLETE_CATALYST = join(FIXTURES_DIR, 'complete-catalyst');
+const PARTIAL_CATALYST = join(FIXTURES_DIR, 'partial-catalyst');
+
+let completeCatalyst: Awaited<ReturnType<typeof loadCatalyst>>;
+let partialCatalyst: Awaited<ReturnType<typeof loadCatalyst>>;
+
+beforeAll(async () => {
+  completeCatalyst = await loadCatalyst(COMPLETE_CATALYST);
+  partialCatalyst = await loadCatalyst(PARTIAL_CATALYST);
+});
+
+describe('mergeCatalysts', () => {
+  describe('merging single catalyst', () => {
+    it('merges a single catalyst (passthrough)', () => {
+      const merged = mergeCatalysts([completeCatalyst]);
+      
+      expect(merged.catalystIds).toEqual(['@test/complete-catalyst']);
+      expect(merged.facets.questions).toBeDefined();
+      expect(merged.facets.constraints).toBeDefined();
+    });
+
+    it('preserves source attribution', () => {
+      const merged = mergeCatalysts([completeCatalyst]);
+      
+      const questions = merged.facets.questions;
+      expect(questions).toBeDefined();
+      for (const item of questions || []) {
+        expect(item.sourceId).toBe('@test/complete-catalyst');
+      }
+    });
+
+    it('tracks contribution metadata', () => {
+      const merged = mergeCatalysts([completeCatalyst]);
+      
+      const contrib = merged.contributions.get('@test/complete-catalyst');
+      expect(contrib).toBeDefined();
+      expect(contrib?.facetTypes).toContain('questions');
+      expect(contrib?.facetTypes).toContain('constraints');
+      expect(contrib?.contentCount).toBeGreaterThan(0);
+    });
+  });
+
+  describe('merging multiple catalysts', () => {
+    it('merges two catalysts in order', () => {
+      const merged = mergeCatalysts([completeCatalyst, partialCatalyst]);
+      
+      expect(merged.catalystIds).toEqual([
+        '@test/complete-catalyst',
+        '@test/partial-catalyst',
+      ]);
+    });
+
+    it('preserves order of content', () => {
+      const merged = mergeCatalysts([completeCatalyst, partialCatalyst]);
+      
+      const questions = merged.facets.questions;
+      expect(questions).toBeDefined();
+      
+      // First items should be from complete-catalyst
+      const firstFromComplete = questions?.filter(
+        q => q.sourceId === '@test/complete-catalyst'
+      );
+      const firstFromPartial = questions?.filter(
+        q => q.sourceId === '@test/partial-catalyst'
+      );
+      
+      // Complete catalyst content should come first
+      if (firstFromComplete && firstFromPartial && firstFromComplete.length > 0) {
+        const completeIndex = questions?.indexOf(firstFromComplete[0]) || -1;
+        const partialIndex = questions?.indexOf(firstFromPartial[0]) || -1;
+        expect(completeIndex).toBeLessThan(partialIndex);
+      }
+    });
+
+    it('merges overlapping facets (same facet type)', () => {
+      const merged = mergeCatalysts([completeCatalyst, partialCatalyst]);
+      
+      // Both catalysts have questions
+      const questions = merged.facets.questions;
+      expect(questions).toBeDefined();
+      expect(questions!.length).toBeGreaterThan(0);
+      
+      // Should include content from both
+      const fromComplete = questions?.some(q => q.sourceId === '@test/complete-catalyst');
+      const fromPartial = questions?.some(q => q.sourceId === '@test/partial-catalyst');
+      
+      expect(fromComplete).toBe(true);
+      expect(fromPartial).toBe(true);
+    });
+
+    it('handles catalysts with different facets', () => {
+      const merged = mergeCatalysts([completeCatalyst, partialCatalyst]);
+      
+      // Complete has all facets, partial has only questions and constraints
+      expect(merged.facets.outputTemplates).toBeDefined();
+      expect(merged.facets.domainKnowledge).toBeDefined();
+      expect(merged.facets.processGuidance).toBeDefined();
+      expect(merged.facets.validationRules).toBeDefined();
+    });
+
+    it('tracks contributions from multiple catalysts', () => {
+      const merged = mergeCatalysts([completeCatalyst, partialCatalyst]);
+      
+      expect(merged.contributions.size).toBe(2);
+      
+      const completeContrib = merged.contributions.get('@test/complete-catalyst');
+      const partialContrib = merged.contributions.get('@test/partial-catalyst');
+      
+      expect(completeContrib).toBeDefined();
+      expect(partialContrib).toBeDefined();
+      expect(completeContrib?.contentCount).toBeGreaterThan(0);
+      expect(partialContrib?.contentCount).toBeGreaterThan(0);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles empty array of catalysts', () => {
+      const merged = mergeCatalysts([]);
+      
+      expect(merged.catalystIds).toEqual([]);
+      expect(merged.facets).toEqual({});
+      expect(merged.contributions.size).toBe(0);
+    });
+
+    it('handles catalysts with no facets', () => {
+      // This would require a catalyst with no facet directories
+      // For now, we'll test with existing catalysts
+      const merged = mergeCatalysts([partialCatalyst]);
+      
+      // Partial catalyst only has questions and constraints
+      expect(merged.facets.outputTemplates).toBeUndefined();
+      expect(merged.facets.domainKnowledge).toBeUndefined();
+    });
+
+    it('skips facets that are undefined in all catalysts', () => {
+      // Create scenario with no output templates
+      const merged = mergeCatalysts([partialCatalyst]);
+      
+      // No facet type should be present if no catalyst provides it
+      for (const [key, value] of Object.entries(merged.facets)) {
+        if (value === undefined) {
+          expect(value).toBeUndefined();
+        }
+      }
+    });
+  });
+
+  describe('content preservation', () => {
+    it('preserves exact content from source files', () => {
+      const merged = mergeCatalysts([completeCatalyst]);
+      
+      const questions = merged.facets.questions;
+      expect(questions).toBeDefined();
+      
+      // Should have content from exploration.md
+      const exploration = questions?.find(q => q.filename === 'exploration.md');
+      expect(exploration).toBeDefined();
+      expect(exploration?.content).toContain('Exploration Questions');
+    });
+
+    it('preserves filename information', () => {
+      const merged = mergeCatalysts([completeCatalyst]);
+      
+      const questions = merged.facets.questions;
+      expect(questions).toBeDefined();
+      
+      for (const item of questions || []) {
+        expect(item.filename).toBeDefined();
+        expect(item.filename).toMatch(/\.md$/);
+      }
+    });
+  });
+});
+
+describe('renderFacet', () => {
+  it('renders a facet with source attribution', () => {
+    const merged = mergeCatalysts([completeCatalyst, partialCatalyst]);
+    
+    const rendered = renderFacet(merged, 'questions');
+    
+    expect(rendered).toContain('From @test/complete-catalyst:');
+    expect(rendered).toContain('From @test/partial-catalyst:');
+  });
+
+  it('includes content in rendered output', () => {
+    const merged = mergeCatalysts([completeCatalyst]);
+    
+    const rendered = renderFacet(merged, 'constraints');
+    
+    expect(rendered).toContain('Testing');
+    expect(rendered).toContain('Documentation');
+  });
+
+  it('returns empty string for missing facet', () => {
+    const merged = mergeCatalysts([partialCatalyst]);
+    
+    const rendered = renderFacet(merged, 'outputTemplates');
+    
+    expect(rendered).toBe('');
+  });
+
+  it('separates sources with blank lines', () => {
+    const merged = mergeCatalysts([completeCatalyst, partialCatalyst]);
+    
+    const rendered = renderFacet(merged, 'questions');
+    
+    // Should have blank line between sources
+    expect(rendered).toContain('\n\nFrom @test/partial-catalyst:');
+  });
+
+  it('handles single catalyst without extra blank lines', () => {
+    const merged = mergeCatalysts([completeCatalyst]);
+    
+    const rendered = renderFacet(merged, 'questions');
+    
+    // Should start with source header, no leading blank line
+    expect(rendered).toMatch(/^From @test\/complete-catalyst:/);
+  });
+});
+
+describe('renderAllFacets', () => {
+  it('renders all facet types', () => {
+    const merged = mergeCatalysts([completeCatalyst]);
+    
+    const rendered = renderAllFacets(merged);
+    
+    expect(rendered.questions).toBeDefined();
+    expect(rendered.constraints).toBeDefined();
+    expect(rendered.outputTemplates).toBeDefined();
+    expect(rendered.domainKnowledge).toBeDefined();
+    expect(rendered.processGuidance).toBeDefined();
+    expect(rendered.validationRules).toBeDefined();
+  });
+
+  it('returns all facets as strings', () => {
+    const merged = mergeCatalysts([completeCatalyst]);
+    
+    const rendered = renderAllFacets(merged);
+    
+    for (const value of Object.values(rendered)) {
+      expect(typeof value).toBe('string');
+    }
+  });
+
+  it('includes empty strings for missing facets', () => {
+    const merged = mergeCatalysts([partialCatalyst]);
+    
+    const rendered = renderAllFacets(merged);
+    
+    expect(rendered.outputTemplates).toBe('');
+    expect(rendered.domainKnowledge).toBe('');
+  });
+});
+
+describe('summarizeMerge', () => {
+  it('summarizes a single catalyst', () => {
+    const merged = mergeCatalysts([completeCatalyst]);
+    
+    const summary = summarizeMerge(merged);
+    
+    expect(summary).toContain('Merged 1 catalyst');
+    expect(summary).toContain('@test/complete-catalyst');
+  });
+
+  it('summarizes multiple catalysts', () => {
+    const merged = mergeCatalysts([completeCatalyst, partialCatalyst]);
+    
+    const summary = summarizeMerge(merged);
+    
+    expect(summary).toContain('Merged 2 catalyst');
+    expect(summary).toContain('@test/complete-catalyst');
+    expect(summary).toContain('@test/partial-catalyst');
+  });
+
+  it('includes facet types in summary', () => {
+    const merged = mergeCatalysts([completeCatalyst]);
+    
+    const summary = summarizeMerge(merged);
+    
+    expect(summary).toContain('Facets:');
+    expect(summary).toContain('Questions');
+    expect(summary).toContain('Constraints');
+  });
+
+  it('includes content count in summary', () => {
+    const merged = mergeCatalysts([completeCatalyst]);
+    
+    const summary = summarizeMerge(merged);
+    
+    expect(summary).toContain('Content items:');
+  });
+
+  it('handles empty merge', () => {
+    const merged = mergeCatalysts([]);
+    
+    const summary = summarizeMerge(merged);
+    
+    expect(summary).toBe('No catalysts merged');
+  });
+});

package/tests/fixtures/complete-catalyst/catalyst.yml

@@ -0,0 +1,11 @@
+id: "@test/complete-catalyst"
+name: Complete Test Catalyst
+description: A test catalyst with all facets for testing purposes
+version: "1.0.0"
+facets:
+  questions: true
+  constraints: true
+  outputTemplates: true
+  domainKnowledge: true
+  processGuidance: true
+  validationRules: true