@plures/praxis 1.2.13 → 1.2.41

package/src/__tests__/conversations.test.ts

@@ -0,0 +1,312 @@
+/**
+ * Tests for praxis-conversations subsystem
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  captureConversation,
+  loadConversation,
+  redactConversation,
+  redactText,
+  normalizeConversation,
+  classifyConversation,
+  generateCandidate,
+  applyGates,
+  candidatePassed,
+  emitToFS,
+  type Conversation,
+} from '../conversations/index.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRoot = path.resolve(__dirname, '..', '..');
+const fixturesDir = path.join(projectRoot, 'test/fixtures/conversations');
+
+describe('Conversations Subsystem', () => {
+  describe('Capture', () => {
+    it('should capture a conversation from input', () => {
+      const conversation = captureConversation({
+        turns: [
+          { role: 'user', content: 'Hello' },
+          { role: 'assistant', content: 'Hi there!' },
+        ],
+        metadata: {
+          source: 'test',
+        },
+      });
+
+      expect(conversation).toBeDefined();
+      expect(conversation.id).toBeDefined();
+      expect(conversation.turns).toHaveLength(2);
+      expect(conversation.metadata.source).toBe('test');
+      expect(conversation.redacted).toBe(false);
+      expect(conversation.normalized).toBe(false);
+    });
+
+    it('should load conversation from JSON', async () => {
+      const bugReportPath = path.join(fixturesDir, 'bug-report.json');
+      const content = await fs.readFile(bugReportPath, 'utf-8');
+      const conversation = loadConversation(content);
+
+      expect(conversation.id).toBe('test-conversation-1');
+      expect(conversation.turns).toHaveLength(3);
+      expect(conversation.metadata.source).toBe('github-copilot');
+    });
+  });
+
+  describe('Redaction', () => {
+    it('should redact email addresses', () => {
+      const text = 'Contact me at john.doe@example.com for more info';
+      const redacted = redactText(text);
+      
+      expect(redacted).toContain('[EMAIL_REDACTED]');
+      expect(redacted).not.toContain('john.doe@example.com');
+    });
+
+    it('should redact phone numbers', () => {
+      const text = 'Call me at 555-123-4567';
+      const redacted = redactText(text);
+      
+      expect(redacted).toContain('[PHONE_REDACTED]');
+      expect(redacted).not.toContain('555-123-4567');
+    });
+
+    it('should redact IP addresses', () => {
+      const text = 'Server IP is 192.168.1.100';
+      const redacted = redactText(text);
+      
+      expect(redacted).toContain('[IP_REDACTED]');
+      expect(redacted).not.toContain('192.168.1.100');
+    });
+
+    it('should redact conversation content', async () => {
+      const bugReportPath = path.join(fixturesDir, 'bug-report.json');
+      const content = await fs.readFile(bugReportPath, 'utf-8');
+      const conversation = loadConversation(content);
+      
+      const redacted = redactConversation(conversation);
+      
+      expect(redacted.redacted).toBe(true);
+      expect(redacted.turns[0].content).toContain('[EMAIL_REDACTED]');
+      expect(redacted.turns[0].content).not.toContain('test@example.com');
+    });
+  });
+
+  describe('Normalization', () => {
+    it('should normalize whitespace', () => {
+      const conversation = captureConversation({
+        turns: [
+          { role: 'user', content: 'Hello\r\n\r\n\r\nWorld\t\t\tTest' },
+        ],
+        metadata: {},
+      });
+      
+      const normalized = normalizeConversation(conversation);
+      
+      expect(normalized.normalized).toBe(true);
+      expect(normalized.turns[0].content).not.toContain('\r');
+      expect(normalized.turns[0].content).not.toContain('\t');
+    });
+
+    it('should normalize code blocks', () => {
+      const conversation = captureConversation({
+        turns: [
+          { role: 'user', content: '```JAVASCRIPT\nconst x = 1;\n```' },
+        ],
+        metadata: {},
+      });
+      
+      const normalized = normalizeConversation(conversation);
+      
+      expect(normalized.turns[0].content).toContain('```javascript');
+    });
+  });
+
+  describe('Classification', () => {
+    it('should classify bug report correctly', async () => {
+      const bugReportPath = path.join(fixturesDir, 'bug-report.json');
+      const content = await fs.readFile(bugReportPath, 'utf-8');
+      let conversation = loadConversation(content);
+      
+      conversation = classifyConversation(conversation);
+      
+      expect(conversation.classified).toBe(true);
+      expect(conversation.classification?.category).toBe('bug-report');
+      expect(conversation.classification?.confidence).toBeGreaterThan(0);
+    });
+
+    it('should classify feature request correctly', async () => {
+      const featurePath = path.join(fixturesDir, 'feature-request.json');
+      const content = await fs.readFile(featurePath, 'utf-8');
+      let conversation = loadConversation(content);
+      
+      conversation = classifyConversation(conversation);
+      
+      expect(conversation.classified).toBe(true);
+      expect(conversation.classification?.category).toBe('feature-request');
+    });
+
+    it('should classify question correctly', async () => {
+      const questionPath = path.join(fixturesDir, 'question.json');
+      const content = await fs.readFile(questionPath, 'utf-8');
+      let conversation = loadConversation(content);
+      
+      conversation = classifyConversation(conversation);
+      
+      expect(conversation.classified).toBe(true);
+      expect(conversation.classification?.category).toBe('question');
+    });
+  });
+
+  describe('Candidate Generation', () => {
+    it('should generate candidate from classified conversation', async () => {
+      const bugReportPath = path.join(fixturesDir, 'bug-report.json');
+      const content = await fs.readFile(bugReportPath, 'utf-8');
+      let conversation = loadConversation(content);
+      
+      conversation = classifyConversation(conversation);
+      const candidate = generateCandidate(conversation);
+      
+      expect(candidate).toBeDefined();
+      expect(candidate?.id).toBeDefined();
+      expect(candidate?.conversationId).toBe(conversation.id);
+      expect(candidate?.title).toContain('Bug Report');
+      expect(candidate?.body).toContain('Conversation Summary');
+      // Priority is medium by default unless confidence > 0.7
+      expect(['medium', 'high']).toContain(candidate?.metadata.priority);
+    });
+
+    it('should throw error if conversation not classified', () => {
+      const conversation = captureConversation({
+        turns: [{ role: 'user', content: 'test' }],
+        metadata: {},
+      });
+      
+      expect(() => generateCandidate(conversation)).toThrow();
+    });
+  });
+
+  describe('Gating', () => {
+    it('should pass gates for valid candidate', async () => {
+      const bugReportPath = path.join(fixturesDir, 'bug-report.json');
+      const content = await fs.readFile(bugReportPath, 'utf-8');
+      let conversation = loadConversation(content);
+      
+      conversation = classifyConversation(conversation);
+      const candidate = generateCandidate(conversation);
+      
+      if (candidate) {
+        const gated = applyGates(candidate);
+        
+        expect(gated.gateStatus).toBeDefined();
+        expect(gated.gateStatus?.gates).toHaveLength(4);
+        expect(candidatePassed(gated)).toBe(true);
+      }
+    });
+
+    it('should fail gate for short content', () => {
+      let conversation = captureConversation({
+        turns: [{ role: 'user', content: 'Hi' }],
+        metadata: {},
+      });
+      
+      conversation = classifyConversation(conversation);
+      const candidate = generateCandidate(conversation);
+      
+      if (candidate) {
+        const gated = applyGates(candidate);
+        const passed = candidatePassed(gated);
+        
+        expect(passed).toBe(false);
+        // Could fail on minimum-length or valid-title
+        expect(gated.gateStatus?.passed).toBe(false);
+      }
+    });
+  });
+
+  describe('Emitters', () => {
+    describe('FS Emitter', () => {
+      it('should emit candidate to filesystem', async () => {
+        const tmpDir = path.join(projectRoot, 'test/.tmp/emit-test');
+        
+        const bugReportPath = path.join(fixturesDir, 'bug-report.json');
+        const content = await fs.readFile(bugReportPath, 'utf-8');
+        let conversation = loadConversation(content);
+        
+        conversation = classifyConversation(conversation);
+        const candidate = generateCandidate(conversation);
+        
+        if (candidate) {
+          const gated = applyGates(candidate);
+          
+          const result = await emitToFS(gated, {
+            outputDir: tmpDir,
+          });
+          
+          expect(result.emitted).toBe(true);
+          expect(result.emissionResult?.success).toBe(true);
+          
+          // Verify file was created
+          const files = await fs.readdir(tmpDir);
+          expect(files.length).toBeGreaterThan(0);
+          
+          // Cleanup
+          await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+      });
+
+      it('should support dry run mode', async () => {
+        let conversation = captureConversation({
+          turns: [{ role: 'user', content: 'Test message for dry run mode' }],
+          metadata: {},
+        });
+        
+        conversation = classifyConversation(conversation);
+        const candidate = generateCandidate(conversation);
+        
+        if (candidate) {
+          const gated = applyGates(candidate);
+          
+          const result = await emitToFS(gated, {
+            outputDir: '/tmp/nonexistent',
+            dryRun: true,
+          });
+          
+          expect(result.emitted).toBe(true);
+          expect(result.emissionResult?.success).toBe(true);
+          expect(result.emissionResult?.externalId).toContain('fs://');
+        }
+      });
+    });
+  });
+
+  describe('Full Pipeline', () => {
+    it('should process conversation through full pipeline', async () => {
+      const bugReportPath = path.join(fixturesDir, 'bug-report.json');
+      const content = await fs.readFile(bugReportPath, 'utf-8');
+      let conversation = loadConversation(content);
+      
+      // Pipeline: redact -> normalize -> classify
+      conversation = redactConversation(conversation);
+      expect(conversation.redacted).toBe(true);
+      
+      conversation = normalizeConversation(conversation);
+      expect(conversation.normalized).toBe(true);
+      
+      conversation = classifyConversation(conversation);
+      expect(conversation.classified).toBe(true);
+      
+      // Generate and gate candidate
+      const candidate = generateCandidate(conversation);
+      expect(candidate).toBeDefined();
+      
+      if (candidate) {
+        const gated = applyGates(candidate);
+        expect(candidatePassed(gated)).toBe(true);
+      }
+    });
+  });
+});

package/src/__tests__/edge-cases.test.ts

@@ -488,7 +488,7 @@ describe('Edge Cases and Failure Paths', () => {
           if (events.some(TestEvent.is)) {
             const facts = [];
             for (let i = 0; i < 1000; i++) {
-              facts.push(TestFact.create({ index: i }));
+              facts.push({ tag: `TestFact-${i}`, payload: { index: i } });
             }
             return facts;
           }

package/src/__tests__/engine-dx.test.ts

@@ -0,0 +1,355 @@
+/**
+ * Tests for engine DX improvements:
+ *   1. eventTypes filter on RuleDescriptor
+ *   2. Atomic stepWithContext()
+ *   3. Fact deduplication + maxFacts
+ *   4. checkConstraints() convenience method
+ *   5. defineRule/defineModule type inference helpers
+ */
+import { describe, it, expect } from 'vitest';
+import { createPraxisEngine, PraxisRegistry, type PraxisFact, type PraxisEvent } from '../index.js';
+import type { RuleDescriptor, ConstraintDescriptor, PraxisModule } from '../core/rules.js';
+import { defineRule, defineConstraint, defineModule } from '../dsl/index.js';
+
+interface TestContext {
+  count: number;
+  name: string;
+  items: string[];
+}
+
+// ─── 1. eventTypes filter ──────────────────────────────────────────────────
+
+describe('eventTypes filter', () => {
+  it('rule with eventTypes only fires on matching events', () => {
+    const registry = new PraxisRegistry<TestContext>();
+    registry.registerRule({
+      id: 'count-rule',
+      description: 'Only fires on count.increment',
+      eventTypes: 'count.increment',
+      impl: (state) => [{ tag: 'count.incremented', payload: { count: state.context.count } }],
+    });
+    registry.registerRule({
+      id: 'catch-all',
+      description: 'Fires on everything',
+      impl: () => [{ tag: 'catch-all.fired', payload: {} }],
+    });
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 1, name: 'test', items: [] },
+      registry,
+    });
+
+    // Fire unrelated event — only catch-all should fire
+    const r1 = engine.step([{ tag: 'name.changed', payload: {} }]);
+    const tags1 = r1.state.facts.map(f => f.tag);
+    expect(tags1).toContain('catch-all.fired');
+    expect(tags1).not.toContain('count.incremented');
+
+    // Fire matching event — both should fire
+    engine.clearFacts();
+    const r2 = engine.step([{ tag: 'count.increment', payload: {} }]);
+    const tags2 = r2.state.facts.map(f => f.tag);
+    expect(tags2).toContain('catch-all.fired');
+    expect(tags2).toContain('count.incremented');
+  });
+
+  it('rule with eventTypes array matches any of the listed tags', () => {
+    const registry = new PraxisRegistry<TestContext>();
+    registry.registerRule({
+      id: 'multi-event',
+      description: 'Fires on count.increment or count.decrement',
+      eventTypes: ['count.increment', 'count.decrement'],
+      impl: () => [{ tag: 'multi.fired', payload: {} }],
+    });
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 0, name: '', items: [] },
+      registry,
+    });
+
+    // Match first
+    let r = engine.step([{ tag: 'count.increment', payload: {} }]);
+    expect(r.state.facts.some(f => f.tag === 'multi.fired')).toBe(true);
+
+    engine.clearFacts();
+
+    // Match second
+    r = engine.step([{ tag: 'count.decrement', payload: {} }]);
+    expect(r.state.facts.some(f => f.tag === 'multi.fired')).toBe(true);
+
+    engine.clearFacts();
+
+    // No match
+    r = engine.step([{ tag: 'other.event', payload: {} }]);
+    expect(r.state.facts.some(f => f.tag === 'multi.fired')).toBe(false);
+  });
+
+  it('empty events array skips rules with eventTypes', () => {
+    const registry = new PraxisRegistry<TestContext>();
+    registry.registerRule({
+      id: 'filtered-rule',
+      description: 'Needs specific event',
+      eventTypes: 'specific.event',
+      impl: () => [{ tag: 'filtered.fired', payload: {} }],
+    });
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 0, name: '', items: [] },
+      registry,
+    });
+
+    const r = engine.step([]);
+    expect(r.state.facts).toHaveLength(0);
+  });
+});
+
+// ─── 2. Atomic stepWithContext ──────────────────────────────────────────────
+
+describe('stepWithContext', () => {
+  it('updates context before rules evaluate', () => {
+    const registry = new PraxisRegistry<TestContext>();
+    registry.registerRule({
+      id: 'check-context',
+      description: 'Reads context.count',
+      impl: (state) => {
+        // This should see the UPDATED count, not the old one
+        return [{ tag: 'seen-count', payload: { count: state.context.count } }];
+      },
+    });
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 0, name: '', items: [] },
+      registry,
+    });
+
+    const result = engine.stepWithContext(
+      (ctx) => ({ ...ctx, count: 42 }),
+      [{ tag: 'test', payload: {} }]
+    );
+
+    const seenFact = result.state.facts.find(f => f.tag === 'seen-count');
+    expect(seenFact).toBeDefined();
+    expect((seenFact!.payload as any).count).toBe(42);
+  });
+
+  it('returns proper diagnostics from constraints', () => {
+    const registry = new PraxisRegistry<TestContext>();
+    registry.registerConstraint({
+      id: 'max-count',
+      description: 'Count must be <= 100',
+      impl: (state) => state.context.count <= 100 ? true : `Count too high: ${state.context.count}`,
+    });
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 0, name: '', items: [] },
+      registry,
+    });
+
+    const result = engine.stepWithContext(
+      (ctx) => ({ ...ctx, count: 200 }),
+      [{ tag: 'test', payload: {} }]
+    );
+
+    expect(result.diagnostics).toHaveLength(1);
+    expect(result.diagnostics[0].message).toContain('200');
+  });
+});
+
+// ─── 3. Fact deduplication ─────────────────────────────────────────────────
+
+describe('fact deduplication', () => {
+  it('last-write-wins deduplicates by tag (default)', () => {
+    const registry = new PraxisRegistry<TestContext>();
+    registry.registerRule({
+      id: 'counter',
+      description: 'Emits count fact',
+      impl: (state) => [{ tag: 'current-count', payload: { value: state.context.count } }],
+    });
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 1, name: '', items: [] },
+      registry,
+      // default factDedup is 'last-write-wins'
+    });
+
+    engine.step([{ tag: 'tick', payload: {} }]);
+    engine.updateContext(ctx => ({ ...ctx, count: 2 }));
+    engine.step([{ tag: 'tick', payload: {} }]);
+    engine.updateContext(ctx => ({ ...ctx, count: 3 }));
+    engine.step([{ tag: 'tick', payload: {} }]);
+
+    const facts = engine.getFacts();
+    const countFacts = facts.filter(f => f.tag === 'current-count');
+    // Should only have ONE current-count fact (the latest)
+    expect(countFacts).toHaveLength(1);
+    expect((countFacts[0].payload as any).value).toBe(3);
+  });
+
+  it('none mode accumulates all facts', () => {
+    const registry = new PraxisRegistry<TestContext>();
+    registry.registerRule({
+      id: 'counter',
+      description: 'Emits count fact',
+      impl: (state) => [{ tag: 'current-count', payload: { value: state.context.count } }],
+    });
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 1, name: '', items: [] },
+      registry,
+      factDedup: 'none',
+    });
+
+    engine.step([{ tag: 'tick', payload: {} }]);
+    engine.updateContext(ctx => ({ ...ctx, count: 2 }));
+    engine.step([{ tag: 'tick', payload: {} }]);
+
+    const countFacts = engine.getFacts().filter(f => f.tag === 'current-count');
+    expect(countFacts).toHaveLength(2);
+  });
+
+  it('maxFacts limits fact accumulation', () => {
+    const registry = new PraxisRegistry<TestContext>();
+    registry.registerRule({
+      id: 'emitter',
+      description: 'Emits unique fact each step',
+      impl: (state) => [{ tag: `fact-${state.context.count}`, payload: {} }],
+    });
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 0, name: '', items: [] },
+      registry,
+      factDedup: 'none',
+      maxFacts: 5,
+    });
+
+    for (let i = 0; i < 10; i++) {
+      engine.updateContext(ctx => ({ ...ctx, count: i }));
+      engine.step([{ tag: 'tick', payload: {} }]);
+    }
+
+    expect(engine.getFacts().length).toBeLessThanOrEqual(5);
+  });
+});
+
+// ─── 4. checkConstraints convenience ───────────────────────────────────────
+
+describe('checkConstraints', () => {
+  it('returns empty array when all constraints pass', () => {
+    const registry = new PraxisRegistry<TestContext>();
+    registry.registerConstraint({
+      id: 'positive-count',
+      description: 'Count must be positive',
+      impl: (state) => state.context.count >= 0,
+    });
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 5, name: '', items: [] },
+      registry,
+    });
+
+    expect(engine.checkConstraints()).toHaveLength(0);
+  });
+
+  it('returns violations without running rules', () => {
+    const registry = new PraxisRegistry<TestContext>();
+    let ruleRan = false;
+    registry.registerRule({
+      id: 'side-effect-detector',
+      description: 'Should NOT run during checkConstraints',
+      impl: () => {
+        ruleRan = true;
+        return [{ tag: 'should-not-appear', payload: {} }];
+      },
+    });
+    registry.registerConstraint({
+      id: 'has-name',
+      description: 'Name must not be empty',
+      impl: (state) => state.context.name.length > 0 ? true : 'Name is empty',
+    });
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 0, name: '', items: [] },
+      registry,
+    });
+
+    const violations = engine.checkConstraints();
+    expect(violations).toHaveLength(1);
+    expect(violations[0].message).toBe('Name is empty');
+    expect(ruleRan).toBe(false);
+    expect(engine.getFacts().some(f => f.tag === 'should-not-appear')).toBe(false);
+  });
+});
+
+// ─── 5. Type inference helpers ─────────────────────────────────────────────
+
+describe('type inference helpers', () => {
+  it('defineRule preserves eventTypes', () => {
+    const rule = defineRule<TestContext>({
+      id: 'typed-rule',
+      description: 'A typed rule with event filter',
+      eventTypes: ['sprint.update'],
+      impl: (state, _events) => {
+        // TypeScript should infer state.context as TestContext here
+        const _count: number = state.context.count;
+        return [];
+      },
+    });
+
+    expect(rule.id).toBe('typed-rule');
+    expect(rule.eventTypes).toEqual(['sprint.update']);
+  });
+
+  it('defineModule bundles rules and constraints with proper types', () => {
+    const mod = defineModule<TestContext>({
+      rules: [
+        {
+          id: 'mod-rule',
+          description: 'Module rule',
+          eventTypes: 'test.event',
+          impl: (state) => [{ tag: 'mod-fact', payload: { count: state.context.count } }],
+        },
+      ],
+      constraints: [
+        {
+          id: 'mod-constraint',
+          description: 'Module constraint',
+          impl: (state) => state.context.count >= 0,
+        },
+      ],
+    });
+
+    expect(mod.rules).toHaveLength(1);
+    expect(mod.constraints).toHaveLength(1);
+    expect(mod.rules[0].eventTypes).toBe('test.event');
+  });
+
+  it('defineRule + PraxisRegistry.registerModule round-trips correctly', () => {
+    const mod = defineModule<TestContext>({
+      rules: [
+        {
+          id: 'round-trip',
+          description: 'Test',
+          eventTypes: ['a', 'b'],
+          impl: () => [{ tag: 'ok', payload: {} }],
+        },
+      ],
+      constraints: [],
+    });
+
+    const registry = new PraxisRegistry<TestContext>();
+    registry.registerModule(mod);
+
+    const engine = createPraxisEngine<TestContext>({
+      initialContext: { count: 0, name: '', items: [] },
+      registry,
+    });
+
+    // Should NOT fire on unmatched event
+    let r = engine.step([{ tag: 'c', payload: {} }]);
+    expect(r.state.facts.some(f => f.tag === 'ok')).toBe(false);
+
+    // Should fire on matched event
+    r = engine.step([{ tag: 'a', payload: {} }]);
+    expect(r.state.facts.some(f => f.tag === 'ok')).toBe(true);
+  });
+});