cognitive-core 0.0.2 → 0.1.2

package/tests/types/trajectory.test.ts

@@ -0,0 +1,253 @@
+import { describe, it, expect } from 'vitest';
+import {
+  TrajectorySchema,
+  createTrajectory,
+  isSuccessful,
+  getKeySteps,
+  type Trajectory,
+} from '../../src/types/trajectory.js';
+import { createTask } from '../../src/types/task.js';
+import { createStep } from '../../src/types/step.js';
+import { successOutcome, failureOutcome } from '../../src/types/outcome.js';
+
+describe('Trajectory', () => {
+  const sampleTask = createTask({
+    id: 'task-1',
+    domain: 'code',
+    description: 'Write a hello world function',
+  });
+
+  const sampleSteps = [
+    createStep({
+      thought: 'I need to create a function',
+      action: 'write_code()',
+      observation: 'Function written',
+    }),
+    createStep({
+      action: 'run_tests()',
+      observation: 'Tests passed',
+    }),
+  ];
+
+  it('should validate a complete trajectory', () => {
+    const trajectory: Trajectory = {
+      id: 'traj-1',
+      task: sampleTask,
+      steps: sampleSteps,
+      outcome: successOutcome('function helloWorld() { return "hello"; }'),
+      agentId: 'claude-code',
+      timestamp: new Date(),
+      llmCalls: 5,
+      totalTokens: 1500,
+      wallTimeSeconds: 30,
+      metadata: { version: '1.0' },
+    };
+    const result = TrajectorySchema.parse(trajectory);
+    expect(result.id).toBe('traj-1');
+    expect(result.agentId).toBe('claude-code');
+    expect(result.llmCalls).toBe(5);
+    expect(result.totalTokens).toBe(1500);
+  });
+
+  it('should apply defaults for optional fields', () => {
+    const trajectory = TrajectorySchema.parse({
+      id: 'traj-2',
+      task: sampleTask,
+      steps: [],
+      outcome: { success: true },
+      agentId: 'test-agent',
+    });
+    expect(trajectory.llmCalls).toBe(0);
+    expect(trajectory.totalTokens).toBe(0);
+    expect(trajectory.wallTimeSeconds).toBe(0);
+    expect(trajectory.metadata).toEqual({});
+    expect(trajectory.timestamp).toBeInstanceOf(Date);
+  });
+
+  it('should allow empty steps array', () => {
+    const trajectory = TrajectorySchema.parse({
+      id: 'traj-3',
+      task: sampleTask,
+      steps: [],
+      outcome: failureOutcome('No steps taken'),
+      agentId: 'agent',
+    });
+    expect(trajectory.steps).toEqual([]);
+  });
+});
+
+describe('createTrajectory', () => {
+  const task = createTask({
+    domain: 'reasoning',
+    description: 'Solve a logic puzzle',
+  });
+
+  const steps = [
+    createStep({ action: 'analyze', observation: 'Found pattern' }),
+    createStep({ action: 'apply', observation: 'Applied rule' }),
+    createStep({ action: 'verify', observation: 'Correct' }),
+  ];
+
+  it('should create a trajectory with required fields', () => {
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('solved'),
+      agentId: 'reasoning-agent',
+    });
+    expect(trajectory.id).toBeDefined();
+    expect(trajectory.id.length).toBeGreaterThan(0);
+    expect(trajectory.task).toEqual(task);
+    expect(trajectory.steps).toHaveLength(3);
+    expect(trajectory.agentId).toBe('reasoning-agent');
+  });
+
+  it('should create a trajectory with custom id', () => {
+    const trajectory = createTrajectory({
+      id: 'custom-traj-id',
+      task,
+      steps: [],
+      outcome: failureOutcome('failed'),
+      agentId: 'agent',
+    });
+    expect(trajectory.id).toBe('custom-traj-id');
+  });
+
+  it('should create a trajectory with metrics', () => {
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome(42),
+      agentId: 'agent',
+      llmCalls: 10,
+      totalTokens: 5000,
+      wallTimeSeconds: 120,
+    });
+    expect(trajectory.llmCalls).toBe(10);
+    expect(trajectory.totalTokens).toBe(5000);
+    expect(trajectory.wallTimeSeconds).toBe(120);
+  });
+
+  it('should create a trajectory with metadata', () => {
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('done'),
+      agentId: 'agent',
+      metadata: { attempt: 2, model: 'gpt-4' },
+    });
+    expect(trajectory.metadata.attempt).toBe(2);
+    expect(trajectory.metadata.model).toBe('gpt-4');
+  });
+
+  it('should set timestamp to current time', () => {
+    const before = new Date();
+    const trajectory = createTrajectory({
+      task,
+      steps: [],
+      outcome: successOutcome('x'),
+      agentId: 'agent',
+    });
+    const after = new Date();
+    expect(trajectory.timestamp.getTime()).toBeGreaterThanOrEqual(before.getTime());
+    expect(trajectory.timestamp.getTime()).toBeLessThanOrEqual(after.getTime());
+  });
+});
+
+describe('isSuccessful', () => {
+  const task = createTask({ domain: 'test', description: 'test' });
+
+  it('should return true for successful trajectory', () => {
+    const trajectory = createTrajectory({
+      task,
+      steps: [],
+      outcome: successOutcome('done'),
+      agentId: 'agent',
+    });
+    expect(isSuccessful(trajectory)).toBe(true);
+  });
+
+  it('should return false for failed trajectory', () => {
+    const trajectory = createTrajectory({
+      task,
+      steps: [],
+      outcome: failureOutcome('error'),
+      agentId: 'agent',
+    });
+    expect(isSuccessful(trajectory)).toBe(false);
+  });
+});
+
+describe('getKeySteps', () => {
+  const task = createTask({ domain: 'test', description: 'test' });
+
+  it('should return steps above threshold', () => {
+    const steps = [
+      { ...createStep({ action: 'a', observation: 'o' }), attributionScore: 0.1 },
+      { ...createStep({ action: 'b', observation: 'o' }), attributionScore: 0.3 },
+      { ...createStep({ action: 'c', observation: 'o' }), attributionScore: 0.8 },
+      { ...createStep({ action: 'd', observation: 'o' }), attributionScore: 0.15 },
+    ];
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('x'),
+      agentId: 'agent',
+    });
+
+    const keySteps = getKeySteps(trajectory);
+    expect(keySteps).toHaveLength(3);
+    expect(keySteps[0].action).toBe('b');
+    expect(keySteps[1].action).toBe('c');
+    expect(keySteps[2].action).toBe('d');
+  });
+
+  it('should use custom threshold', () => {
+    const steps = [
+      { ...createStep({ action: 'a', observation: 'o' }), attributionScore: 0.4 },
+      { ...createStep({ action: 'b', observation: 'o' }), attributionScore: 0.6 },
+    ];
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('x'),
+      agentId: 'agent',
+    });
+
+    expect(getKeySteps(trajectory, 0.5)).toHaveLength(1);
+    expect(getKeySteps(trajectory, 0.3)).toHaveLength(2);
+    expect(getKeySteps(trajectory, 0.7)).toHaveLength(0);
+  });
+
+  it('should handle steps without attribution scores', () => {
+    const steps = [
+      createStep({ action: 'a', observation: 'o' }),
+      { ...createStep({ action: 'b', observation: 'o' }), attributionScore: 0.5 },
+    ];
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('x'),
+      agentId: 'agent',
+    });
+
+    const keySteps = getKeySteps(trajectory);
+    expect(keySteps).toHaveLength(1);
+    expect(keySteps[0].action).toBe('b');
+  });
+
+  it('should return empty array for trajectory with no key steps', () => {
+    const steps = [
+      { ...createStep({ action: 'a', observation: 'o' }), attributionScore: 0.05 },
+      { ...createStep({ action: 'b', observation: 'o' }), attributionScore: 0.1 },
+    ];
+    const trajectory = createTrajectory({
+      task,
+      steps,
+      outcome: successOutcome('x'),
+      agentId: 'agent',
+    });
+
+    expect(getKeySteps(trajectory)).toHaveLength(0);
+  });
+});

package/tests/utils/frontmatter.test.ts

@@ -0,0 +1,208 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseKnowledgeFrontmatter,
+  serializeKnowledgeFrontmatter,
+  serializeKnowledgeNote,
+  parseKnowledgeNote,
+} from '../../src/utils/frontmatter.js';
+import type { KnowledgeNoteFrontmatter } from '../../src/types/knowledge.js';
+
+describe('frontmatter', () => {
+  const sampleFrontmatter: KnowledgeNoteFrontmatter = {
+    id: 'k-prisma-schema-push',
+    type: 'observation',
+    domain: ['database', 'orm'],
+    entities: ['prisma', 'postgresql'],
+    tags: ['migration', 'schema-drift'],
+    confidence: 0.85,
+    source: {
+      origin: 'extracted',
+      trajectories: ['t-2025-01-15-abc', 't-2025-01-18-def'],
+      playbooks: ['playbook-prisma-setup'],
+    },
+    links: [
+      { target: 'k-prisma-migration-workflow', relation: 'related-to' },
+      { target: 'k-ts-enum-export', relation: 'co-occurred', layer: 'temporal' },
+    ],
+    created: '2025-01-15T10:30:00.000Z',
+    updated: '2025-01-18T14:00:00.000Z',
+    supersedes: null,
+  };
+
+  const sampleBody = '# Prisma requires schema push\n\nSome content here.';
+
+  describe('parseKnowledgeFrontmatter', () => {
+    it('parses valid frontmatter with all fields', () => {
+      const content = `---
+id: k-prisma-schema-push
+type: observation
+domain: [database, orm]
+entities: [prisma, postgresql]
+tags: [migration, schema-drift]
+confidence: 0.85
+source:
+  origin: extracted
+  trajectories:
+    - t-2025-01-15-abc
+    - t-2025-01-18-def
+  playbooks:
+    - playbook-prisma-setup
+links:
+  - target: k-prisma-migration-workflow
+    relation: related-to
+  - target: k-ts-enum-export
+    relation: co-occurred
+    layer: temporal
+created: "2025-01-15T10:30:00.000Z"
+updated: "2025-01-18T14:00:00.000Z"
+---
+
+# Prisma requires schema push
+
+Some content here.`;
+
+      const { frontmatter, body } = parseKnowledgeFrontmatter(content);
+
+      expect(frontmatter).not.toBeNull();
+      expect(frontmatter!.id).toBe('k-prisma-schema-push');
+      expect(frontmatter!.type).toBe('observation');
+      expect(frontmatter!.domain).toEqual(['database', 'orm']);
+      expect(frontmatter!.entities).toEqual(['prisma', 'postgresql']);
+      expect(frontmatter!.confidence).toBe(0.85);
+      expect(frontmatter!.source.origin).toBe('extracted');
+      expect(frontmatter!.source.trajectories).toHaveLength(2);
+      expect(frontmatter!.links).toHaveLength(2);
+      expect(frontmatter!.links[1].layer).toBe('temporal');
+      expect(body).toContain('# Prisma requires schema push');
+    });
+
+    it('returns null frontmatter for content without frontmatter', () => {
+      const { frontmatter, body } = parseKnowledgeFrontmatter(
+        '# Just a title\n\nSome content.'
+      );
+
+      expect(frontmatter).toBeNull();
+      expect(body).toBe('# Just a title\n\nSome content.');
+    });
+
+    it('returns null frontmatter for invalid YAML', () => {
+      const { frontmatter } = parseKnowledgeFrontmatter(
+        '---\n[invalid yaml\n---\nBody'
+      );
+
+      expect(frontmatter).toBeNull();
+    });
+
+    it('returns null frontmatter for missing required fields', () => {
+      const { frontmatter } = parseKnowledgeFrontmatter(
+        '---\ntitle: test\n---\nBody'
+      );
+
+      expect(frontmatter).toBeNull();
+    });
+
+    it('applies defaults for optional fields', () => {
+      const content = `---
+id: k-test
+type: observation
+confidence: 0.5
+source:
+  origin: agent-authored
+created: "2025-01-15T10:00:00.000Z"
+updated: "2025-01-15T10:00:00.000Z"
+---
+
+Body`;
+
+      const { frontmatter } = parseKnowledgeFrontmatter(content);
+
+      expect(frontmatter).not.toBeNull();
+      expect(frontmatter!.domain).toEqual([]);
+      expect(frontmatter!.entities).toEqual([]);
+      expect(frontmatter!.tags).toEqual([]);
+      expect(frontmatter!.links).toEqual([]);
+    });
+  });
+
+  describe('serializeKnowledgeFrontmatter', () => {
+    it('produces valid YAML frontmatter block', () => {
+      const output = serializeKnowledgeFrontmatter(sampleFrontmatter);
+
+      expect(output).toMatch(/^---\n/);
+      expect(output).toMatch(/---\n$/);
+      expect(output).toContain('id: k-prisma-schema-push');
+      expect(output).toContain('type: observation');
+      expect(output).toContain('confidence: 0.85');
+    });
+
+    it('omits empty arrays', () => {
+      const fm: KnowledgeNoteFrontmatter = {
+        ...sampleFrontmatter,
+        domain: [],
+        entities: [],
+        tags: [],
+        links: [],
+      };
+
+      const output = serializeKnowledgeFrontmatter(fm);
+
+      expect(output).not.toContain('domain:');
+      expect(output).not.toContain('entities:');
+      expect(output).not.toContain('tags:');
+      expect(output).not.toContain('links:');
+    });
+  });
+
+  describe('round-trip', () => {
+    it('serialize then parse produces equivalent frontmatter', () => {
+      const serialized = serializeKnowledgeFrontmatter(sampleFrontmatter);
+      const fullContent = `${serialized}\n${sampleBody}\n`;
+
+      const { frontmatter, body } = parseKnowledgeFrontmatter(fullContent);
+
+      expect(frontmatter).not.toBeNull();
+      expect(frontmatter!.id).toBe(sampleFrontmatter.id);
+      expect(frontmatter!.type).toBe(sampleFrontmatter.type);
+      expect(frontmatter!.domain).toEqual(sampleFrontmatter.domain);
+      expect(frontmatter!.entities).toEqual(sampleFrontmatter.entities);
+      expect(frontmatter!.confidence).toBe(sampleFrontmatter.confidence);
+      expect(frontmatter!.source).toEqual(sampleFrontmatter.source);
+      expect(frontmatter!.links).toEqual(sampleFrontmatter.links);
+      expect(body).toContain(sampleBody);
+    });
+  });
+
+  describe('parseKnowledgeNote', () => {
+    it('returns a full KnowledgeNote with filePath', () => {
+      const content = `${serializeKnowledgeFrontmatter(sampleFrontmatter)}\n${sampleBody}\n`;
+
+      const note = parseKnowledgeNote(content, 'knowledge/observations/k-prisma-schema-push.md');
+
+      expect(note).not.toBeNull();
+      expect(note!.frontmatter.id).toBe('k-prisma-schema-push');
+      expect(note!.body).toContain(sampleBody);
+      expect(note!.filePath).toBe('knowledge/observations/k-prisma-schema-push.md');
+    });
+
+    it('returns null for content without valid frontmatter', () => {
+      const note = parseKnowledgeNote('No frontmatter here.', 'test.md');
+      expect(note).toBeNull();
+    });
+  });
+
+  describe('serializeKnowledgeNote', () => {
+    it('produces complete markdown with frontmatter + body', () => {
+      const note = {
+        frontmatter: sampleFrontmatter,
+        body: sampleBody,
+        filePath: 'test.md',
+      };
+
+      const output = serializeKnowledgeNote(note);
+
+      expect(output).toMatch(/^---\n/);
+      expect(output).toContain('id: k-prisma-schema-push');
+      expect(output).toContain(sampleBody);
+    });
+  });
+});

package/tests/utils/similarity.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from 'vitest';
+import {
+  cosineSimilarity,
+  jaccardSimilarity,
+  ngramSimilarity,
+  textSimilarity,
+  tokenize,
+  findTopK,
+} from '../../src/utils/similarity.js';
+
+describe('cosineSimilarity', () => {
+  it('should return 1 for identical vectors', () => {
+    expect(cosineSimilarity([1, 0, 0], [1, 0, 0])).toBeCloseTo(1);
+    expect(cosineSimilarity([0.5, 0.5], [0.5, 0.5])).toBeCloseTo(1);
+  });
+
+  it('should return 0 for orthogonal vectors', () => {
+    expect(cosineSimilarity([1, 0], [0, 1])).toBeCloseTo(0);
+    expect(cosineSimilarity([1, 0, 0], [0, 1, 0])).toBeCloseTo(0);
+  });
+
+  it('should return -1 for opposite vectors', () => {
+    expect(cosineSimilarity([1, 0], [-1, 0])).toBeCloseTo(-1);
+  });
+
+  it('should handle arbitrary vectors', () => {
+    const a = [1, 2, 3];
+    const b = [4, 5, 6];
+    // dot = 1*4 + 2*5 + 3*6 = 32
+    // normA = sqrt(14), normB = sqrt(77)
+    const expected = 32 / (Math.sqrt(14) * Math.sqrt(77));
+    expect(cosineSimilarity(a, b)).toBeCloseTo(expected);
+  });
+
+  it('should return 0 for zero vectors', () => {
+    expect(cosineSimilarity([0, 0, 0], [1, 2, 3])).toBe(0);
+    expect(cosineSimilarity([1, 2, 3], [0, 0, 0])).toBe(0);
+  });
+
+  it('should throw for vectors of different lengths', () => {
+    expect(() => cosineSimilarity([1, 2], [1, 2, 3])).toThrow();
+  });
+});
+
+describe('tokenize', () => {
+  it('should split text into lowercase tokens', () => {
+    expect(tokenize('Hello World')).toEqual(['hello', 'world']);
+  });
+
+  it('should remove punctuation', () => {
+    expect(tokenize('Hello, world!')).toEqual(['hello', 'world']);
+  });
+
+  it('should handle multiple spaces', () => {
+    expect(tokenize('a   b  c')).toEqual(['a', 'b', 'c']);
+  });
+
+  it('should return empty array for empty string', () => {
+    expect(tokenize('')).toEqual([]);
+  });
+
+  it('should handle special characters', () => {
+    expect(tokenize("it's a test-case")).toEqual(['it', 's', 'a', 'test', 'case']);
+  });
+});
+
+describe('jaccardSimilarity', () => {
+  it('should return 1 for identical strings', () => {
+    expect(jaccardSimilarity('hello world', 'hello world')).toBe(1);
+  });
+
+  it('should return 0 for completely different strings', () => {
+    expect(jaccardSimilarity('abc', 'xyz')).toBe(0);
+  });
+
+  it('should handle partial overlap', () => {
+    // 'hello' appears in both
+    const sim = jaccardSimilarity('hello world', 'hello there');
+    expect(sim).toBeGreaterThan(0);
+    expect(sim).toBeLessThan(1);
+  });
+
+  it('should return 0 for empty strings', () => {
+    expect(jaccardSimilarity('', '')).toBe(0);
+    expect(jaccardSimilarity('hello', '')).toBe(0);
+  });
+
+  it('should be case insensitive', () => {
+    expect(jaccardSimilarity('HELLO', 'hello')).toBe(1);
+  });
+});
+
+describe('ngramSimilarity', () => {
+  it('should return 1 for identical strings', () => {
+    expect(ngramSimilarity('hello', 'hello')).toBe(1);
+  });
+
+  it('should return 0 for completely different strings', () => {
+    expect(ngramSimilarity('abc', 'xyz')).toBe(0);
+  });
+
+  it('should handle partial overlap', () => {
+    const sim = ngramSimilarity('hello', 'hella');
+    expect(sim).toBeGreaterThan(0);
+    expect(sim).toBeLessThan(1);
+  });
+
+  it('should use custom n-gram size', () => {
+    const sim2 = ngramSimilarity('hello', 'help', 2);
+    const sim3 = ngramSimilarity('hello', 'help', 3);
+    // Different n values give different results
+    expect(sim2).not.toBe(sim3);
+  });
+});
+
+describe('textSimilarity', () => {
+  it('should return 1 for identical text', () => {
+    expect(textSimilarity('hello world', 'hello world')).toBe(1);
+  });
+
+  it('should return 0 for completely different text', () => {
+    expect(textSimilarity('abc', 'xyz')).toBe(0);
+  });
+
+  it('should return intermediate values for partial matches', () => {
+    const sim = textSimilarity('fix the bug', 'debug the issue');
+    expect(sim).toBeGreaterThan(0);
+    expect(sim).toBeLessThan(1);
+  });
+});
+
+describe('findTopK', () => {
+  it('should find top-k items by string similarity', () => {
+    const items = [
+      { id: 1, text: 'hello world' },
+      { id: 2, text: 'hello there' },
+      { id: 3, text: 'goodbye world' },
+      { id: 4, text: 'completely different' },
+    ];
+
+    const results = findTopK('hello world', items, (item) => item.text, 2);
+    expect(results).toHaveLength(2);
+    expect(results[0].item.id).toBe(1); // Exact match
+    expect(results[0].score).toBe(1);
+  });
+
+  it('should find top-k items by vector similarity', () => {
+    const items = [
+      { id: 1, vec: [1, 0, 0] },
+      { id: 2, vec: [0.9, 0.1, 0] },
+      { id: 3, vec: [0, 1, 0] },
+      { id: 4, vec: [-1, 0, 0] },
+    ];
+
+    const results = findTopK([1, 0, 0], items, (item) => item.vec, 2);
+    expect(results).toHaveLength(2);
+    expect(results[0].item.id).toBe(1);
+    expect(results[1].item.id).toBe(2);
+  });
+
+  it('should handle items without vectors', () => {
+    const items = [
+      { id: 1, text: 'hello' },
+      { id: 2, text: undefined },
+      { id: 3, text: 'world' },
+    ];
+
+    const results = findTopK(
+      'hello',
+      items,
+      (item) => item.text,
+      3
+    );
+    expect(results).toHaveLength(3);
+    expect(results[2].score).toBe(0); // Item with undefined text
+  });
+
+  it('should return fewer items if k is larger than array', () => {
+    const items = [{ id: 1, text: 'hello' }];
+    const results = findTopK('hello', items, (item) => item.text, 10);
+    expect(results).toHaveLength(1);
+  });
+
+  it('should handle empty items array', () => {
+    const results = findTopK('hello', [], (item: { text: string }) => item.text, 5);
+    expect(results).toHaveLength(0);
+  });
+});