cognitive-core 0.1.0 → 0.2.0

package/tests/learning/knowledge-extractor.test.ts

@@ -0,0 +1,491 @@
+import { describe, it, expect } from 'vitest';
+import {
+  KnowledgeExtractor,
+  createKnowledgeExtractor,
+} from '../../src/learning/knowledge-extractor.js';
+import type { AnalysisResult } from '../../src/learning/analyzer.js';
+import {
+  createTrajectory,
+  createTask,
+  createStep,
+  successOutcome,
+  failureOutcome,
+} from '../../src/types/index.js';
+import type { Trajectory } from '../../src/types/index.js';
+
+function makeTrajectory(overrides?: {
+  id?: string;
+  domain?: string;
+  success?: boolean;
+  steps?: Array<{ action: string; observation: string }>;
+  metadata?: Record<string, unknown>;
+}): Trajectory {
+  const rawSteps = overrides?.steps ?? [
+    { action: 'read file', observation: 'file contents loaded' },
+    { action: 'edit code', observation: 'code updated' },
+    { action: 'run tests', observation: 'tests passed' },
+  ];
+
+  const steps = rawSteps.map((s) =>
+    createStep({ action: s.action, observation: s.observation })
+  );
+
+  return createTrajectory({
+    id: overrides?.id ?? 'traj-test-1',
+    task: createTask({
+      domain: overrides?.domain ?? 'code',
+      description: 'test task',
+    }),
+    steps,
+    outcome: overrides?.success !== false
+      ? successOutcome('done')
+      : failureOutcome('failed'),
+    agentId: 'test-agent',
+    metadata: overrides?.metadata ?? {},
+  });
+}
+
+function makeAnalysis(overrides?: Partial<AnalysisResult>): AnalysisResult {
+  return {
+    success: true,
+    keySteps: [],
+    errorPatterns: [],
+    abstractable: false,
+    trainingExamples: [],
+    ...overrides,
+  };
+}
+
+describe('KnowledgeExtractor', () => {
+  let extractor: KnowledgeExtractor;
+
+  describe('factory', () => {
+    it('should create with createKnowledgeExtractor', () => {
+      const ex = createKnowledgeExtractor();
+      expect(ex).toBeInstanceOf(KnowledgeExtractor);
+    });
+
+    it('should accept custom config', () => {
+      const ex = createKnowledgeExtractor({ initialConfidence: 0.5 });
+      expect(ex).toBeInstanceOf(KnowledgeExtractor);
+    });
+  });
+
+  describe('extract (overall)', () => {
+    beforeEach(() => {
+      extractor = new KnowledgeExtractor();
+    });
+
+    it('should return ExtractedKnowledge shape', () => {
+      const trajectory = makeTrajectory();
+      const analysis = makeAnalysis();
+
+      const result = extractor.extract(trajectory, analysis);
+
+      expect(result).toHaveProperty('observations');
+      expect(result).toHaveProperty('entityUpdates');
+      expect(result).toHaveProperty('contradictions');
+      expect(result).toHaveProperty('links');
+      expect(result).toHaveProperty('playbookLinks');
+      expect(Array.isArray(result.observations)).toBe(true);
+      expect(result.contradictions).toEqual([]);
+    });
+
+    it('should extract nothing from simple trajectory with no patterns', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          { action: 'think about problem', observation: 'plan formed' },
+        ],
+      });
+      const analysis = makeAnalysis();
+
+      const result = extractor.extract(trajectory, analysis);
+      // No error patterns, no config files, no failure→recovery
+      expect(result.observations).toHaveLength(0);
+    });
+  });
+
+  // =========================================================================
+  // Strategy 1: Error Patterns
+  // =========================================================================
+
+  describe('Strategy 1: Error patterns', () => {
+    beforeEach(() => {
+      extractor = new KnowledgeExtractor();
+    });
+
+    it('should extract observations from error patterns with suggestedFix', () => {
+      const trajectory = makeTrajectory();
+      const analysis = makeAnalysis({
+        errorPatterns: [
+          {
+            type: 'syntax',
+            signature: 'SyntaxError: Unexpected token',
+            description: 'Missing semicolon',
+            count: 1,
+            suggestedFix: 'Add semicolon at end of line',
+            stepIndices: [0],
+          },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, analysis);
+      expect(result.observations.length).toBeGreaterThanOrEqual(1);
+
+      const errorObs = result.observations.find((o) =>
+        o.frontmatter.tags.includes('error-pattern')
+      );
+      expect(errorObs).toBeDefined();
+      expect(errorObs!.body).toContain('SyntaxError');
+      expect(errorObs!.body).toContain('Add semicolon');
+    });
+
+    it('should skip error patterns without suggestedFix', () => {
+      const trajectory = makeTrajectory();
+      const analysis = makeAnalysis({
+        errorPatterns: [
+          {
+            type: 'runtime',
+            signature: 'Error',
+            description: 'Something went wrong',
+            count: 1,
+            stepIndices: [0],
+            // no suggestedFix
+          },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, analysis);
+      const errorObs = result.observations.filter((o) =>
+        o.frontmatter.tags.includes('error-pattern')
+      );
+      expect(errorObs).toHaveLength(0);
+    });
+
+    it('should set domain from trajectory', () => {
+      const trajectory = makeTrajectory({ domain: 'web-dev' });
+      const analysis = makeAnalysis({
+        errorPatterns: [
+          {
+            type: 'build',
+            signature: 'webpack compilation error',
+            description: 'Module not found',
+            count: 1,
+            suggestedFix: 'Install the missing module',
+            stepIndices: [0],
+          },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, analysis);
+      const obs = result.observations.find((o) =>
+        o.frontmatter.tags.includes('error-pattern')
+      );
+      expect(obs!.frontmatter.domain).toContain('web-dev');
+    });
+  });
+
+  // =========================================================================
+  // Strategy 2: Config Facts
+  // =========================================================================
+
+  describe('Strategy 2: Config facts', () => {
+    beforeEach(() => {
+      extractor = new KnowledgeExtractor();
+    });
+
+    it('should detect config file references in step actions', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          {
+            action: 'cat package.json',
+            observation: '{"name": "my-app", "version": "1.2.3"}',
+          },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, makeAnalysis());
+      const configObs = result.observations.filter((o) =>
+        o.frontmatter.tags.includes('config')
+      );
+      expect(configObs.length).toBeGreaterThanOrEqual(1);
+      expect(configObs[0].body).toContain('package.json');
+    });
+
+    it('should extract version numbers', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          {
+            action: 'read tsconfig.json',
+            observation: 'typescript version: 5.3.2',
+          },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, makeAnalysis());
+      const configObs = result.observations.find((o) =>
+        o.body.includes('tsconfig')
+      );
+      expect(configObs).toBeDefined();
+      expect(configObs!.body).toContain('5.3.2');
+    });
+
+    it('should not duplicate config observations for the same file', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          { action: 'read package.json', observation: 'contents 1' },
+          { action: 'update package.json', observation: 'contents 2' },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, makeAnalysis());
+      const packageObs = result.observations.filter(
+        (o) =>
+          o.frontmatter.tags.includes('config') &&
+          o.body.includes('package.json')
+      );
+      expect(packageObs).toHaveLength(1);
+    });
+  });
+
+  // =========================================================================
+  // Strategy 3: Causal Chains
+  // =========================================================================
+
+  describe('Strategy 3: Causal chains', () => {
+    beforeEach(() => {
+      extractor = new KnowledgeExtractor();
+    });
+
+    it('should detect failure → recovery sequences', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          { action: 'npm install foo', observation: 'error: package not found' },
+          { action: 'npm install @org/foo', observation: 'installed successfully' },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, makeAnalysis());
+      const causalObs = result.observations.filter((o) =>
+        o.frontmatter.tags.includes('causal-chain')
+      );
+      expect(causalObs.length).toBeGreaterThanOrEqual(1);
+      expect(causalObs[0].body).toContain('Failed action');
+      expect(causalObs[0].body).toContain('Recovery action');
+    });
+
+    it('should create causal links', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          { action: 'run build', observation: 'error: types not found' },
+          { action: 'install @types/node', observation: 'installed' },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, makeAnalysis());
+      expect(result.links.length).toBeGreaterThanOrEqual(1);
+      expect(result.links[0].relation).toBe('led-to');
+      expect(result.links[0].layer).toBe('causal');
+    });
+
+    it('should not create causal chain when no recovery follows', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          { action: 'run build', observation: 'error: compilation failed' },
+          { action: 'run build again', observation: 'error: still failed' },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, makeAnalysis());
+      const causalObs = result.observations.filter((o) =>
+        o.frontmatter.tags.includes('causal-chain')
+      );
+      expect(causalObs).toHaveLength(0);
+    });
+
+    it('should look ahead up to 3 steps for recovery', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          { action: 'run test', observation: 'error: assertion failed' },
+          { action: 'read logs', observation: 'error details in log' },
+          { action: 'fix assertion', observation: 'error in fix' },
+          { action: 'fix properly', observation: 'all tests pass' },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, makeAnalysis());
+      // The first failure (step 0) should find recovery at step 3 (within 3-step lookahead)
+      const causalObs = result.observations.filter((o) =>
+        o.frontmatter.tags.includes('causal-chain')
+      );
+      // At least the first failure should find a recovery
+      expect(causalObs.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  // =========================================================================
+  // Strategy 4: Entity Identification
+  // =========================================================================
+
+  describe('Strategy 4: Entity identification', () => {
+    beforeEach(() => {
+      extractor = new KnowledgeExtractor();
+    });
+
+    it('should produce entity updates for known entities', () => {
+      const trajectory = makeTrajectory({
+        domain: 'web',
+        steps: [
+          {
+            action: 'configure vitest',
+            observation: 'error: vitest config invalid',
+          },
+          {
+            action: 'fix vitest config',
+            observation: 'vitest config fixed, tests pass',
+          },
+        ],
+      });
+      const analysis = makeAnalysis({
+        errorPatterns: [
+          {
+            type: 'config',
+            signature: 'vitest config error',
+            description: 'Invalid vitest configuration',
+            count: 1,
+            suggestedFix: 'Update vitest.config.ts',
+            stepIndices: [0],
+          },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, analysis, {
+        existingEntities: ['vitest'],
+      });
+
+      expect(result.entityUpdates.length).toBeGreaterThanOrEqual(1);
+      expect(result.entityUpdates[0].entityId).toBe('vitest');
+      expect(result.entityUpdates[0].trajectoryId).toBe(trajectory.id);
+    });
+
+    it('should skip entity updates when no existing entities', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          { action: 'use prisma', observation: 'error: prisma not configured' },
+        ],
+      });
+      const analysis = makeAnalysis({
+        errorPatterns: [
+          {
+            type: 'config',
+            signature: 'prisma error',
+            description: 'Prisma not configured',
+            count: 1,
+            suggestedFix: 'Run prisma init',
+            stepIndices: [0],
+          },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, analysis);
+      expect(result.entityUpdates).toHaveLength(0);
+    });
+
+    it('should not create updates for entities not mentioned in observations', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          { action: 'read readme', observation: 'readme content' },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, makeAnalysis(), {
+        existingEntities: ['prisma', 'react'],
+      });
+
+      expect(result.entityUpdates).toHaveLength(0);
+    });
+  });
+
+  // =========================================================================
+  // Cross-Reference: Playbook Links
+  // =========================================================================
+
+  describe('Playbook links', () => {
+    beforeEach(() => {
+      extractor = new KnowledgeExtractor();
+    });
+
+    it('should create playbook links from injectedPlaybooks metadata', () => {
+      const trajectory = makeTrajectory({
+        metadata: { injectedPlaybooks: ['pb-auth', 'pb-testing'] },
+        steps: [
+          {
+            action: 'read package.json',
+            observation: '{"name": "app"}',
+          },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, makeAnalysis());
+
+      // Should have playbook links for each observation × each playbook
+      if (result.observations.length > 0) {
+        expect(result.playbookLinks.length).toBe(
+          result.observations.length * 2
+        );
+        expect(result.playbookLinks[0].relation).toBe('supports');
+      }
+    });
+
+    it('should not create playbook links when no injectedPlaybooks', () => {
+      const trajectory = makeTrajectory({
+        steps: [
+          {
+            action: 'read package.json',
+            observation: '{"name": "app"}',
+          },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, makeAnalysis());
+      expect(result.playbookLinks).toHaveLength(0);
+    });
+  });
+
+  // =========================================================================
+  // Entity extraction from text
+  // =========================================================================
+
+  describe('entity extraction from text', () => {
+    beforeEach(() => {
+      extractor = new KnowledgeExtractor();
+    });
+
+    it('should extract known tool names from error patterns', () => {
+      const trajectory = makeTrajectory({ domain: 'web' });
+      const analysis = makeAnalysis({
+        errorPatterns: [
+          {
+            type: 'build',
+            signature: 'TypeScript error TS2307',
+            description: 'Cannot find module in React component',
+            count: 1,
+            suggestedFix: 'Install missing types',
+            stepIndices: [0],
+          },
+        ],
+      });
+
+      const result = extractor.extract(trajectory, analysis);
+      const obs = result.observations.find((o) =>
+        o.frontmatter.tags.includes('error-pattern')
+      );
+      expect(obs).toBeDefined();
+      // Should detect typescript and/or react
+      const entities = obs!.frontmatter.entities;
+      expect(
+        entities.includes('typescript') || entities.includes('react')
+      ).toBe(true);
+    });
+  });
+});

package/tests/learning/maintenance-scheduler.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  MaintenanceScheduler,
+  createMaintenanceScheduler,
+  type MaintenanceTask,
+} from '../../src/learning/maintenance-scheduler.js';
+
+function createTestTask(name: string, priority = 50): MaintenanceTask {
+  return {
+    name,
+    priority,
+    execute: async () => ({
+      taskName: name,
+      success: true,
+      durationMs: 1,
+    }),
+  };
+}
+
+describe('MaintenanceScheduler', () => {
+  let scheduler: MaintenanceScheduler;
+
+  beforeEach(() => {
+    scheduler = createMaintenanceScheduler({
+      mode: 'afterNBatches',
+      batchInterval: 3,
+    });
+  });
+
+  describe('task registration', () => {
+    it('should register and list tasks', () => {
+      scheduler.registerTask(createTestTask('task-a', 10));
+      scheduler.registerTask(createTestTask('task-b', 20));
+
+      const tasks = scheduler.getRegisteredTasks();
+      expect(tasks.length).toBe(2);
+      // Should be sorted by priority descending
+      expect(tasks[0].name).toBe('task-b');
+      expect(tasks[1].name).toBe('task-a');
+    });
+
+    it('should replace existing task with same name', () => {
+      scheduler.registerTask(createTestTask('task-a', 10));
+      scheduler.registerTask(createTestTask('task-a', 20));
+
+      const tasks = scheduler.getRegisteredTasks();
+      expect(tasks.length).toBe(1);
+      expect(tasks[0].priority).toBe(20);
+    });
+
+    it('should unregister tasks', () => {
+      scheduler.registerTask(createTestTask('task-a'));
+      scheduler.unregisterTask('task-a');
+      expect(scheduler.getRegisteredTasks().length).toBe(0);
+    });
+  });
+
+  describe('afterNBatches mode', () => {
+    it('should not trigger before batch interval', () => {
+      scheduler.registerTask(createTestTask('task-a'));
+      scheduler.onBatchComplete();
+      scheduler.onBatchComplete();
+      expect(scheduler.shouldRunMaintenance()).toBe(false);
+    });
+
+    it('should trigger at batch interval', () => {
+      scheduler.registerTask(createTestTask('task-a'));
+      scheduler.onBatchComplete();
+      scheduler.onBatchComplete();
+      scheduler.onBatchComplete();
+      expect(scheduler.shouldRunMaintenance()).toBe(true);
+    });
+
+    it('should reset counter after maintenance', async () => {
+      scheduler.registerTask(createTestTask('task-a'));
+      scheduler.onBatchComplete();
+      scheduler.onBatchComplete();
+      scheduler.onBatchComplete();
+
+      await scheduler.runMaintenance();
+      expect(scheduler.shouldRunMaintenance()).toBe(false);
+      expect(scheduler.getBatchesSinceLastMaintenance()).toBe(0);
+    });
+  });
+
+  describe('manual mode', () => {
+    it('should never auto-trigger in manual mode', () => {
+      const manual = createMaintenanceScheduler({ mode: 'manual' });
+      manual.registerTask(createTestTask('task-a'));
+      for (let i = 0; i < 100; i++) manual.onBatchComplete();
+      expect(manual.shouldRunMaintenance()).toBe(false);
+    });
+
+    it('should still allow forced maintenance', async () => {
+      const manual = createMaintenanceScheduler({ mode: 'manual' });
+      manual.registerTask(createTestTask('task-a'));
+
+      const result = await manual.runMaintenance({ force: true });
+      expect(result.ran).toBe(true);
+      expect(result.taskResults.length).toBe(1);
+    });
+  });
+
+  describe('periodic mode', () => {
+    it('should trigger after interval', () => {
+      const periodic = createMaintenanceScheduler({
+        mode: 'periodic',
+        intervalMs: 0, // Trigger immediately
+      });
+      periodic.registerTask(createTestTask('task-a'));
+      expect(periodic.shouldRunMaintenance()).toBe(true);
+    });
+  });
+
+  describe('deferDuringBatch', () => {
+    it('should defer maintenance during batch by default', () => {
+      scheduler.registerTask(createTestTask('task-a'));
+      scheduler.onBatchComplete();
+      scheduler.onBatchComplete();
+      scheduler.onBatchComplete();
+
+      scheduler.onBatchStart();
+      expect(scheduler.shouldRunMaintenance()).toBe(false);
+
+      scheduler.onBatchEnd();
+      expect(scheduler.shouldRunMaintenance()).toBe(true);
+    });
+
+    it('should skip if batch in progress (non-forced)', async () => {
+      scheduler.registerTask(createTestTask('task-a'));
+      scheduler.onBatchStart();
+
+      const result = await scheduler.runMaintenance();
+      expect(result.ran).toBe(false);
+      expect(result.skipReason).toBe('batch_in_progress');
+    });
+  });
+
+  describe('runMaintenance', () => {
+    it('should execute tasks in priority order', async () => {
+      const order: string[] = [];
+      scheduler.registerTask({
+        name: 'low',
+        priority: 10,
+        execute: async () => {
+          order.push('low');
+          return { taskName: 'low', success: true, durationMs: 1 };
+        },
+      });
+      scheduler.registerTask({
+        name: 'high',
+        priority: 100,
+        execute: async () => {
+          order.push('high');
+          return { taskName: 'high', success: true, durationMs: 1 };
+        },
+      });
+
+      await scheduler.runMaintenance({ force: true });
+      expect(order).toEqual(['high', 'low']);
+    });
+
+    it('should handle task failures gracefully', async () => {
+      scheduler.registerTask({
+        name: 'failing',
+        priority: 50,
+        execute: async () => { throw new Error('boom'); },
+      });
+
+      const result = await scheduler.runMaintenance({ force: true });
+      expect(result.ran).toBe(true);
+      expect(result.taskResults.length).toBe(1);
+      expect(result.taskResults[0].success).toBe(false);
+    });
+
+    it('should record cycle history', async () => {
+      scheduler.registerTask(createTestTask('task-a'));
+      await scheduler.runMaintenance({ force: true });
+      await scheduler.runMaintenance({ force: true });
+
+      const history = scheduler.getCycleHistory();
+      expect(history.length).toBe(2);
+    });
+
+    it('should skip if queue is empty (non-forced)', async () => {
+      const result = await scheduler.runMaintenance();
+      expect(result.ran).toBe(false);
+      expect(result.skipReason).toBe('queue_empty');
+    });
+  });
+});