cognitive-core 0.1.0 → 0.2.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/partitioned-store.test.ts

@@ -0,0 +1,230 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { PartitionedStore } from '../../src/utils/partitioned-store.js';
+import { mkdtemp, rm, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+interface TestItem {
+  id: string;
+  name: string;
+  domain?: string;
+}
+
+describe('PartitionedStore', () => {
+  let tempDir: string;
+  let store: PartitionedStore<TestItem>;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'atlas-partitioned-test-'));
+    store = new PartitionedStore<TestItem>(
+      tempDir,
+      'items',
+      (item) => item.domain || undefined,
+      { pretty: true },
+    );
+    await store.init();
+  });
+
+  afterEach(async () => {
+    await store.close();
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe('set and get', () => {
+    it('should store and retrieve items', async () => {
+      const item: TestItem = { id: 'a', name: 'alpha', domain: 'ts' };
+      store.set('a', item);
+
+      expect(store.get('a')).toEqual(item);
+    });
+
+    it('should route items to correct partition', async () => {
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      store.set('b', { id: 'b', name: 'beta', domain: 'py' });
+
+      expect(store.valuesInPartition('ts')).toHaveLength(1);
+      expect(store.valuesInPartition('ts')[0].name).toBe('alpha');
+      expect(store.valuesInPartition('py')).toHaveLength(1);
+      expect(store.valuesInPartition('py')[0].name).toBe('beta');
+    });
+
+    it('should put items without domain in _global partition', async () => {
+      store.set('a', { id: 'a', name: 'alpha' }); // no domain
+      expect(store.valuesInPartition('_global')).toHaveLength(1);
+    });
+
+    it('should return undefined for non-existent key', () => {
+      expect(store.get('missing')).toBeUndefined();
+    });
+
+    it('should move item to new partition when domain changes', () => {
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      expect(store.valuesInPartition('ts')).toHaveLength(1);
+
+      store.set('a', { id: 'a', name: 'alpha', domain: 'py' });
+      expect(store.valuesInPartition('ts')).toHaveLength(0);
+      expect(store.valuesInPartition('py')).toHaveLength(1);
+    });
+  });
+
+  describe('delete', () => {
+    it('should delete an item from its partition', () => {
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      expect(store.has('a')).toBe(true);
+
+      const deleted = store.delete('a');
+      expect(deleted).toBe(true);
+      expect(store.has('a')).toBe(false);
+      expect(store.size()).toBe(0);
+    });
+
+    it('should return false for non-existent key', () => {
+      expect(store.delete('missing')).toBe(false);
+    });
+  });
+
+  describe('has', () => {
+    it('should return true for existing items', () => {
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      expect(store.has('a')).toBe(true);
+    });
+
+    it('should return false for missing items', () => {
+      expect(store.has('missing')).toBe(false);
+    });
+  });
+
+  describe('values and valuesInPartition', () => {
+    it('should return all values across partitions', () => {
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      store.set('b', { id: 'b', name: 'beta', domain: 'py' });
+      store.set('c', { id: 'c', name: 'gamma' }); // global
+
+      const all = store.values();
+      expect(all).toHaveLength(3);
+    });
+
+    it('should return only values in a specific partition', () => {
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      store.set('b', { id: 'b', name: 'beta', domain: 'ts' });
+      store.set('c', { id: 'c', name: 'gamma', domain: 'py' });
+
+      expect(store.valuesInPartition('ts')).toHaveLength(2);
+      expect(store.valuesInPartition('py')).toHaveLength(1);
+      expect(store.valuesInPartition('unknown')).toHaveLength(0);
+    });
+  });
+
+  describe('keys, entries, size', () => {
+    it('should return all keys across partitions', () => {
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      store.set('b', { id: 'b', name: 'beta', domain: 'py' });
+
+      const keys = store.keys();
+      expect(keys).toContain('a');
+      expect(keys).toContain('b');
+      expect(keys).toHaveLength(2);
+    });
+
+    it('should return correct size across partitions', () => {
+      expect(store.size()).toBe(0);
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      store.set('b', { id: 'b', name: 'beta', domain: 'py' });
+      expect(store.size()).toBe(2);
+    });
+
+    it('should return all entries', () => {
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      store.set('b', { id: 'b', name: 'beta', domain: 'py' });
+
+      const entries = store.entries();
+      expect(entries).toHaveLength(2);
+      expect(entries.map(([k]) => k)).toContain('a');
+    });
+  });
+
+  describe('getPartitionNames', () => {
+    it('should list all partition names', () => {
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      store.set('b', { id: 'b', name: 'beta', domain: 'py' });
+
+      const names = store.getPartitionNames();
+      expect(names).toContain('_global');
+      expect(names).toContain('ts');
+      expect(names).toContain('py');
+    });
+  });
+
+  describe('persistence', () => {
+    it('should persist data across reloads', async () => {
+      store.set('a', { id: 'a', name: 'alpha', domain: 'ts' });
+      store.set('b', { id: 'b', name: 'beta', domain: 'py' });
+      await store.flush();
+      await store.close();
+
+      // Create new store instance
+      const store2 = new PartitionedStore<TestItem>(
+        tempDir,
+        'items',
+        (item) => item.domain || undefined,
+        { pretty: true },
+      );
+      await store2.init();
+
+      expect(store2.get('a')?.name).toBe('alpha');
+      expect(store2.get('b')?.name).toBe('beta');
+      expect(store2.size()).toBe(2);
+
+      await store2.close();
+    });
+  });
+
+  describe('migration from flat layout', () => {
+    it('should auto-migrate flat JSON files into partition subdirectories', async () => {
+      await store.close();
+
+      // Create a flat layout manually (files directly in collection dir)
+      const collectionDir = join(tempDir, 'migrated');
+      await mkdir(collectionDir, { recursive: true });
+
+      await writeFile(
+        join(collectionDir, 'item1.json'),
+        JSON.stringify({ id: 'item1', name: 'first', domain: 'ts' }),
+      );
+      await writeFile(
+        join(collectionDir, 'item2.json'),
+        JSON.stringify({ id: 'item2', name: 'second', domain: 'py' }),
+      );
+      await writeFile(
+        join(collectionDir, 'item3.json'),
+        JSON.stringify({ id: 'item3', name: 'third' }), // no domain → _global
+      );
+
+      // Create PartitionedStore on top of it
+      const migratingStore = new PartitionedStore<TestItem>(
+        tempDir,
+        'migrated',
+        (item) => item.domain || undefined,
+        { pretty: true },
+      );
+      await migratingStore.init();
+
+      // Flat files should have been migrated into subdirs
+      expect(migratingStore.get('item1')?.name).toBe('first');
+      expect(migratingStore.get('item2')?.name).toBe('second');
+      expect(migratingStore.get('item3')?.name).toBe('third');
+
+      expect(migratingStore.valuesInPartition('ts')).toHaveLength(1);
+      expect(migratingStore.valuesInPartition('py')).toHaveLength(1);
+      expect(migratingStore.valuesInPartition('_global')).toHaveLength(1);
+
+      // Verify subdirectories were created on disk
+      const entries = await readdir(collectionDir);
+      expect(entries).toContain('ts');
+      expect(entries).toContain('py');
+      expect(entries).toContain('_global');
+
+      await migratingStore.close();
+    });
+  });
+});