cognitive-core 0.1.0 → 0.2.0

package/tests/memory/reflexion.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { ReflexionMemory } from '../../src/memory/reflexion.js';
+import type { ReflexionEpisode } from '../../src/types/memory.js';
+import { createSqlitePersistence } from '../../src/persistence/index.js';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+function createSampleEpisode(overrides?: Partial<ReflexionEpisode>): ReflexionEpisode {
+  return {
+    id: overrides?.id ?? crypto.randomUUID(),
+    trajectoryId: overrides?.trajectoryId ?? `traj-${crypto.randomUUID()}`,
+    taskSummary: overrides?.taskSummary ?? 'Fix the typescript import error',
+    outcome: overrides?.outcome ?? 'success',
+    selfCritique: overrides?.selfCritique ?? 'Completed efficiently in 2 steps',
+    keyInsights: overrides?.keyInsights ?? ['Tools used: ReadFile, EditFile'],
+    strategyAssessment: overrides?.strategyAssessment ?? 'Succeeded without playbook guidance',
+    suggestedPlaybookUpdates: overrides?.suggestedPlaybookUpdates ?? [],
+    domain: overrides?.domain ?? 'typescript',
+    createdAt: overrides?.createdAt ?? new Date(),
+  };
+}
+
+describe('ReflexionMemory', () => {
+  let tempDir: string;
+  let memory: ReflexionMemory;
+  let persistence: any;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'atlas-reflexion-test-'));
+    persistence = createSqlitePersistence({ baseDir: tempDir });
+    await persistence.init();
+    memory = new ReflexionMemory(persistence);
+    await memory.init();
+  });
+
+  afterEach(async () => {
+    await memory.close();
+    persistence.close();
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe('add and get', () => {
+    it('should store and retrieve a reflexion episode', async () => {
+      const episode = createSampleEpisode();
+      await memory.add(episode);
+
+      const retrieved = await memory.get(episode.id);
+      expect(retrieved).toBeDefined();
+      expect(retrieved?.taskSummary).toBe('Fix the typescript import error');
+      expect(retrieved?.outcome).toBe('success');
+      expect(retrieved?.keyInsights).toHaveLength(1);
+    });
+
+    it('should return undefined for non-existent id', async () => {
+      const result = await memory.get('non-existent');
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('getByTrajectory', () => {
+    it('should find an episode by trajectory ID', async () => {
+      const trajectoryId = 'specific-trajectory-id';
+      const episode = createSampleEpisode({ trajectoryId });
+      await memory.add(episode);
+
+      const retrieved = await memory.getByTrajectory(trajectoryId);
+      expect(retrieved).toBeDefined();
+      expect(retrieved?.trajectoryId).toBe(trajectoryId);
+      expect(retrieved?.id).toBe(episode.id);
+    });
+
+    it('should return undefined for non-existent trajectory', async () => {
+      await memory.add(createSampleEpisode());
+
+      const result = await memory.getByTrajectory('no-such-trajectory');
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('getRecent', () => {
+    it('should return episodes sorted by most recent first', async () => {
+      const ep1 = createSampleEpisode({
+        taskSummary: 'First task',
+        createdAt: new Date('2025-01-01'),
+      });
+      const ep2 = createSampleEpisode({
+        taskSummary: 'Second task',
+        createdAt: new Date('2025-06-01'),
+      });
+      const ep3 = createSampleEpisode({
+        taskSummary: 'Third task',
+        createdAt: new Date('2025-03-01'),
+      });
+
+      await memory.add(ep1);
+      await memory.add(ep2);
+      await memory.add(ep3);
+
+      const recent = await memory.getRecent({ k: 3 });
+      expect(recent).toHaveLength(3);
+      expect(recent[0].taskSummary).toBe('Second task');
+      expect(recent[1].taskSummary).toBe('Third task');
+      expect(recent[2].taskSummary).toBe('First task');
+    });
+
+    it('should limit results to k', async () => {
+      for (let i = 0; i < 5; i++) {
+        await memory.add(createSampleEpisode({ taskSummary: `Task ${i}` }));
+      }
+
+      const recent = await memory.getRecent({ k: 2 });
+      expect(recent).toHaveLength(2);
+    });
+
+    it('should filter by domain', async () => {
+      await memory.add(createSampleEpisode({ domain: 'typescript' }));
+      await memory.add(createSampleEpisode({ domain: 'python' }));
+      await memory.add(createSampleEpisode({ domain: 'typescript' }));
+
+      const results = await memory.getRecent({ domain: 'typescript' });
+      expect(results).toHaveLength(2);
+      expect(results.every((ep) => ep.domain === 'typescript')).toBe(true);
+    });
+
+    it('should filter by outcome', async () => {
+      await memory.add(createSampleEpisode({ outcome: 'success' }));
+      await memory.add(createSampleEpisode({ outcome: 'failure' }));
+      await memory.add(createSampleEpisode({ outcome: 'success' }));
+      await memory.add(createSampleEpisode({ outcome: 'partial' }));
+
+      const failures = await memory.getRecent({ outcome: 'failure' });
+      expect(failures).toHaveLength(1);
+      expect(failures[0].outcome).toBe('failure');
+
+      const successes = await memory.getRecent({ outcome: 'success' });
+      expect(successes).toHaveLength(2);
+    });
+
+    it('should combine domain and outcome filters', async () => {
+      await memory.add(createSampleEpisode({ domain: 'typescript', outcome: 'success' }));
+      await memory.add(createSampleEpisode({ domain: 'typescript', outcome: 'failure' }));
+      await memory.add(createSampleEpisode({ domain: 'python', outcome: 'success' }));
+
+      const results = await memory.getRecent({
+        domain: 'typescript',
+        outcome: 'failure',
+      });
+      expect(results).toHaveLength(1);
+      expect(results[0].domain).toBe('typescript');
+      expect(results[0].outcome).toBe('failure');
+    });
+  });
+
+  describe('count', () => {
+    it('should return correct count', async () => {
+      expect(await memory.count()).toBe(0);
+
+      await memory.add(createSampleEpisode());
+      expect(await memory.count()).toBe(1);
+
+      await memory.add(createSampleEpisode());
+      expect(await memory.count()).toBe(2);
+    });
+  });
+});

package/tests/memory/skill-exporter.test.ts

@@ -0,0 +1,475 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { existsSync } from 'node:fs';
+import { PlaybookLibrary, createPlaybookLibrary } from '../../src/memory/playbook.js';
+import {
+  compilePlaybookToSkill,
+  exportPlaybooksAsSkills,
+  exportPlaybookAsSkill,
+} from '../../src/memory/skill-exporter.js';
+import { createSqlitePersistence } from '../../src/persistence/index.js';
+import type { Playbook } from '../../src/types/playbook.js';
+
+function createSamplePlaybook(overrides?: Partial<Playbook>): Playbook {
+  return {
+    id: `playbook-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    name: 'fix-type-error',
+    applicability: {
+      situations: ['Debugging TypeScript type errors'],
+      triggers: ['TS2322', 'Type mismatch'],
+      antiPatterns: ['Simple typo that can be fixed inline'],
+      domains: ['typescript', 'code'],
+    },
+    guidance: {
+      strategy: 'Analyze the error message and trace back to the source type definition',
+      tactics: [
+        'Read the full error message carefully',
+        'Identify the expected vs actual types',
+        'Check the variable declaration and type narrowing',
+      ],
+      steps: ['npm run typecheck', 'Locate the error source', 'Fix the type mismatch'],
+      codeExample: 'const value: string = getData() as string;',
+    },
+    verification: {
+      successIndicators: ['Build passes', 'No type errors remain'],
+      failureIndicators: ['Same error persists', 'New type errors appear'],
+      rollbackStrategy: 'Revert the type change and try a different approach',
+    },
+    evolution: {
+      version: '1.2.0',
+      createdFrom: ['traj-001', 'traj-002'],
+      failures: [],
+      refinements: [
+        {
+          context: 'monorepo',
+          addition: 'Also check workspace symlinks and shared type definitions',
+          source: 'failure',
+          addedAt: new Date(),
+        },
+        {
+          context: 'ESM modules',
+          addition: 'Verify type definitions are exported in package.json exports map',
+          source: 'success',
+          addedAt: new Date(),
+        },
+      ],
+      successCount: 8,
+      failureCount: 2,
+    },
+    provenance: {
+      origin: 'extracted',
+      recordedAt: new Date(),
+    },
+    confidence: 0.85,
+    complexity: 'moderate',
+    estimatedEffort: 3,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+describe('compilePlaybookToSkill', () => {
+  it('should produce valid SKILL.md with frontmatter and body', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+
+    // Check frontmatter boundaries
+    expect(content.startsWith('---\n')).toBe(true);
+    expect(content.indexOf('---', 4)).toBeGreaterThan(4);
+
+    // Check required frontmatter fields
+    expect(content).toContain('name: fix-type-error');
+    expect(content).toContain('description:');
+  });
+
+  it('should include name in frontmatter', () => {
+    const playbook = createSamplePlaybook({ name: 'my-custom-skill' });
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('name: my-custom-skill');
+  });
+
+  it('should build description from situations and triggers', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('Debugging TypeScript type errors');
+    expect(content).toContain('TS2322');
+    expect(content).toContain('Domains: typescript, code');
+  });
+
+  it('should include metadata block with version and complexity', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('metadata:');
+    expect(content).toContain('version: "1.2.0"');
+    expect(content).toContain('complexity: "moderate"');
+  });
+
+  it('should include confidence in metadata when includeStats is true', () => {
+    const playbook = createSamplePlaybook({ confidence: 0.85 });
+    const content = compilePlaybookToSkill(playbook, { includeStats: true });
+    expect(content).toContain('confidence: "0.85"');
+  });
+
+  it('should include success rate for playbooks with reliable stats', () => {
+    const playbook = createSamplePlaybook();
+    // 8 successes, 2 failures = 0.80 rate, 10 total >= 3 min
+    const content = compilePlaybookToSkill(playbook, { includeStats: true });
+    expect(content).toContain('success-rate: "0.80"');
+  });
+
+  it('should include strategy section', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('## Strategy');
+    expect(content).toContain('Analyze the error message and trace back to the source type definition');
+  });
+
+  it('should include tactics as bullet list', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('## Tactics');
+    expect(content).toContain('- Read the full error message carefully');
+    expect(content).toContain('- Identify the expected vs actual types');
+  });
+
+  it('should include numbered steps', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('## Steps');
+    expect(content).toContain('1. npm run typecheck');
+    expect(content).toContain('2. Locate the error source');
+  });
+
+  it('should include code example in fenced block', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('## Example');
+    expect(content).toContain('```');
+    expect(content).toContain('const value: string = getData() as string;');
+  });
+
+  it('should include anti-patterns section', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('## When NOT to use this');
+    expect(content).toContain('- Simple typo that can be fixed inline');
+  });
+
+  it('should include triggers section', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('## Triggers');
+    expect(content).toContain('- TS2322');
+    expect(content).toContain('- Type mismatch');
+  });
+
+  it('should include verification section', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('## Verification');
+    expect(content).toContain('**Success looks like:**');
+    expect(content).toContain('- Build passes');
+    expect(content).toContain('**Failure looks like:**');
+    expect(content).toContain('- Same error persists');
+    expect(content).toContain('**Rollback:**');
+  });
+
+  it('should include refinements as context-specific notes', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('## Context-specific notes');
+    expect(content).toContain('**monorepo:**');
+    expect(content).toContain('Also check workspace symlinks');
+    expect(content).toContain('**ESM modules:**');
+  });
+
+  it('should omit optional sections when disabled', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook, {
+      includeStats: false,
+      includeRefinements: false,
+      includeAntiPatterns: false,
+      includeVerification: false,
+    });
+
+    expect(content).not.toContain('confidence:');
+    expect(content).not.toContain('success-rate:');
+    expect(content).not.toContain('## Context-specific notes');
+    expect(content).not.toContain('## When NOT to use this');
+    expect(content).not.toContain('## Verification');
+  });
+
+  it('should omit steps section when no steps', () => {
+    const playbook = createSamplePlaybook({
+      guidance: {
+        strategy: 'Do the thing',
+        tactics: ['Step one'],
+      },
+    });
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).not.toContain('## Steps');
+  });
+
+  it('should omit code example section when no example', () => {
+    const playbook = createSamplePlaybook({
+      guidance: {
+        strategy: 'Do the thing',
+        tactics: ['Step one'],
+      },
+    });
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).not.toContain('## Example');
+  });
+
+  it('should include compatibility from domains', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('compatibility: Applicable to typescript, code projects');
+  });
+
+  it('should include provenance origin in metadata', () => {
+    const playbook = createSamplePlaybook({
+      provenance: { origin: 'curated', curatedBy: 'team@example.com', recordedAt: new Date() },
+    });
+    const content = compilePlaybookToSkill(playbook);
+    expect(content).toContain('origin: "curated"');
+    expect(content).toContain('author: "team@example.com"');
+  });
+
+  it('should include extra metadata when provided', () => {
+    const playbook = createSamplePlaybook();
+    const content = compilePlaybookToSkill(playbook, {
+      extraMetadata: { 'exported-by': 'cognitive-core' },
+    });
+    expect(content).toContain('exported-by: "cognitive-core"');
+  });
+
+  it('should truncate description at 1024 chars', () => {
+    const playbook = createSamplePlaybook({
+      applicability: {
+        situations: [
+          'A'.repeat(500),
+          'B'.repeat(500),
+        ],
+        triggers: ['C'.repeat(100)],
+        antiPatterns: [],
+        domains: ['test'],
+      },
+    });
+    const content = compilePlaybookToSkill(playbook);
+    // Find the description line
+    const lines = content.split('\n');
+    const descIdx = lines.findIndex((l) => l.trim().startsWith('description:'));
+    const descValueLine = lines[descIdx + 1]; // The >- continuation line
+    // The actual value should be <= 1024 chars
+    expect(descValueLine.trim().length).toBeLessThanOrEqual(1024);
+  });
+});
+
+describe('exportPlaybooksAsSkills', () => {
+  let tempDir: string;
+  let outputDir: string;
+  let library: PlaybookLibrary;
+  let persistence: any;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'atlas-skill-export-'));
+    outputDir = join(tempDir, 'skills-output');
+    persistence = createSqlitePersistence({ baseDir: tempDir });
+    await persistence.init();
+    library = createPlaybookLibrary(persistence);
+    await library.init();
+  });
+
+  afterEach(async () => {
+    await library.close();
+    persistence.close();
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('should export playbooks as SKILL.md directories', async () => {
+    await library.add(createSamplePlaybook({ name: 'skill-one' }));
+    await library.add(createSamplePlaybook({ name: 'skill-two' }));
+
+    const result = await exportPlaybooksAsSkills(library, outputDir);
+
+    expect(result.exported).toBe(2);
+    expect(result.errors).toHaveLength(0);
+    expect(existsSync(join(outputDir, 'skill-one', 'SKILL.md'))).toBe(true);
+    expect(existsSync(join(outputDir, 'skill-two', 'SKILL.md'))).toBe(true);
+  });
+
+  it('should write valid SKILL.md content to files', async () => {
+    await library.add(createSamplePlaybook({ name: 'check-content' }));
+
+    await exportPlaybooksAsSkills(library, outputDir);
+
+    const content = await readFile(
+      join(outputDir, 'check-content', 'SKILL.md'),
+      'utf-8'
+    );
+    expect(content).toContain('name: check-content');
+    expect(content).toContain('## Strategy');
+  });
+
+  it('should filter by minimum confidence', async () => {
+    await library.add(createSamplePlaybook({ name: 'high', confidence: 0.9 }));
+    await library.add(createSamplePlaybook({ name: 'low', confidence: 0.3 }));
+
+    const result = await exportPlaybooksAsSkills(library, outputDir, {
+      minConfidence: 0.5,
+    });
+
+    expect(result.exported).toBe(1);
+    expect(result.skills[0].name).toBe('high');
+  });
+
+  it('should filter by domain', async () => {
+    await library.add(
+      createSamplePlaybook({
+        name: 'ts-skill',
+        applicability: {
+          situations: ['TS stuff'],
+          triggers: [],
+          antiPatterns: [],
+          domains: ['typescript'],
+        },
+      })
+    );
+    await library.add(
+      createSamplePlaybook({
+        name: 'py-skill',
+        applicability: {
+          situations: ['Python stuff'],
+          triggers: [],
+          antiPatterns: [],
+          domains: ['python'],
+        },
+      })
+    );
+
+    const result = await exportPlaybooksAsSkills(library, outputDir, {
+      domains: ['typescript'],
+    });
+
+    expect(result.exported).toBe(1);
+    expect(result.skills[0].name).toBe('ts-skill');
+  });
+
+  it('should filter by origin', async () => {
+    await library.add(
+      createSamplePlaybook({
+        name: 'curated-one',
+        provenance: { origin: 'curated', recordedAt: new Date() },
+      })
+    );
+    await library.add(
+      createSamplePlaybook({
+        name: 'extracted-one',
+        provenance: { origin: 'extracted', recordedAt: new Date() },
+      })
+    );
+
+    const result = await exportPlaybooksAsSkills(library, outputDir, {
+      origins: ['curated'],
+    });
+
+    expect(result.exported).toBe(1);
+    expect(result.skills[0].name).toBe('curated-one');
+  });
+
+  it('should filter by minimum uses', async () => {
+    const used = createSamplePlaybook({ name: 'well-used' });
+    const unused = createSamplePlaybook({
+      name: 'unused',
+      evolution: {
+        version: '1.0.0',
+        createdFrom: [],
+        failures: [],
+        refinements: [],
+        successCount: 0,
+        failureCount: 0,
+      },
+    });
+    await library.add(used);
+    await library.add(unused);
+
+    // The sample playbook has successCount: 8, failureCount: 2 (= 10 uses)
+    const result = await exportPlaybooksAsSkills(library, outputDir, {
+      minUses: 5,
+    });
+
+    expect(result.exported).toBe(1);
+    expect(result.skills[0].name).toBe('well-used');
+  });
+
+  it('should return exported skill objects with content', async () => {
+    await library.add(createSamplePlaybook({ name: 'my-skill' }));
+
+    const result = await exportPlaybooksAsSkills(library, outputDir);
+
+    expect(result.skills).toHaveLength(1);
+    expect(result.skills[0].name).toBe('my-skill');
+    expect(result.skills[0].dirName).toBe('my-skill');
+    expect(result.skills[0].content).toContain('name: my-skill');
+    expect(result.skills[0].sourcePlaybookId).toBeTruthy();
+  });
+
+  it('should create output directory if it does not exist', async () => {
+    const nested = join(outputDir, 'deep', 'nested');
+    await library.add(createSamplePlaybook({ name: 'nested-skill' }));
+
+    await exportPlaybooksAsSkills(library, nested);
+
+    expect(existsSync(join(nested, 'nested-skill', 'SKILL.md'))).toBe(true);
+  });
+
+  it('should handle empty library gracefully', async () => {
+    const result = await exportPlaybooksAsSkills(library, outputDir);
+
+    expect(result.exported).toBe(0);
+    expect(result.errors).toHaveLength(0);
+    expect(result.skills).toHaveLength(0);
+  });
+});
+
+describe('exportPlaybookAsSkill', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'atlas-skill-single-'));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('should export a single playbook to a SKILL.md file', async () => {
+    const playbook = createSamplePlaybook({ name: 'single-export' });
+    const result = await exportPlaybookAsSkill(playbook, tempDir);
+
+    expect(result.name).toBe('single-export');
+    expect(existsSync(join(tempDir, 'single-export', 'SKILL.md'))).toBe(true);
+
+    const content = await readFile(
+      join(tempDir, 'single-export', 'SKILL.md'),
+      'utf-8'
+    );
+    expect(content).toContain('name: single-export');
+    expect(content).toContain('## Strategy');
+  });
+
+  it('should pass options through to the compiler', async () => {
+    const playbook = createSamplePlaybook();
+    const result = await exportPlaybookAsSkill(playbook, tempDir, {
+      includeAntiPatterns: false,
+      includeVerification: false,
+    });
+
+    expect(result.content).not.toContain('## When NOT to use this');
+    expect(result.content).not.toContain('## Verification');
+  });
+});

package/tests/memory/system.test.ts

@@ -2,17 +2,21 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { MemorySystem, createMemorySystem } from '../../src/memory/system.js';
 import { createTrajectory, createStep, createTask, successOutcome, failureOutcome } from '../../src/types/index.js';
 import { createPlaybook } from '../../src/types/playbook.js';
+import { createSqlitePersistence } from '../../src/persistence/index.js';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 
 describe('MemorySystem', () => {
   let memory: MemorySystem;
   let testDir: string;
+  let persistence: any;
 
   beforeEach(async () => {
     testDir = path.join(process.cwd(), '.test-memory-system-' + Date.now());
     await fs.mkdir(testDir, { recursive: true });
-    memory = createMemorySystem(testDir, {
+    persistence = createSqlitePersistence({ baseDir: testDir });
+    await persistence.init();
+    memory = createMemorySystem(persistence, testDir, {
       maxExperiences: 4,
       maxStrategies: 3,
     });
@@ -21,6 +25,7 @@ describe('MemorySystem', () => {
 
   afterEach(async () => {
     await memory.close();
+    persistence.close();
     await fs.rm(testDir, { recursive: true, force: true });
   });