@plures/praxis 1.2.41 → 1.4.0

package/src/__tests__/mcp-server.test.ts

@@ -0,0 +1,310 @@
+/**
+ * Tests for Praxis MCP Server
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createPraxisMcpServer } from '../mcp/server.js';
+import { PraxisRegistry } from '../core/rules.js';
+import { RuleResult, fact } from '../core/rule-result.js';
+import type { PraxisModule } from '../core/rules.js';
+import type { Contract } from '../decision-ledger/types.js';
+
+// ─── Test Fixtures ──────────────────────────────────────────────────────────
+
+interface TestContext {
+  counter: number;
+  name: string;
+}
+
+const incrementContract: Contract = {
+  ruleId: 'test/increment',
+  behavior: 'Increments counter when increment event fires',
+  examples: [
+    { given: 'counter is 5', when: 'increment event fires', then: 'counter.incremented emitted with value 6' },
+  ],
+  invariants: ['Counter must always increase by 1'],
+};
+
+const testModule: PraxisModule<TestContext> = {
+  rules: [
+    {
+      id: 'test/increment',
+      description: 'Increments the counter',
+      eventTypes: 'counter.increment',
+      contract: incrementContract,
+      impl: (state, events) => {
+        const hasIncrement = events.some(e => e.tag === 'counter.increment');
+        if (!hasIncrement) return RuleResult.skip('No increment event');
+        return RuleResult.emit([
+          fact('counter.incremented', { value: state.context.counter + 1 }),
+        ]);
+      },
+    },
+    {
+      id: 'test/greet',
+      description: 'Emits greeting when greet event fires',
+      eventTypes: 'greet',
+      contract: {
+        ruleId: 'test/greet',
+        behavior: 'Emits greeting fact with name',
+        examples: [
+          { given: 'name is Alice', when: 'greet event fires', then: 'greeting emitted for Alice' },
+        ],
+        invariants: ['Greeting must include the name from context'],
+      },
+      impl: (state, events) => {
+        const hasGreet = events.some(e => e.tag === 'greet');
+        if (!hasGreet) return RuleResult.skip('No greet event');
+        return RuleResult.emit([
+          fact('greeting', { message: `Hello, ${state.context.name}!` }),
+        ]);
+      },
+    },
+  ],
+  constraints: [
+    {
+      id: 'test/positive-counter',
+      description: 'Counter must be non-negative',
+      contract: {
+        ruleId: 'test/positive-counter',
+        behavior: 'Ensures counter is never negative',
+        examples: [
+          { given: 'counter is 0', when: 'checked', then: 'passes' },
+          { given: 'counter is -1', when: 'checked', then: 'fails' },
+        ],
+        invariants: ['Counter >= 0'],
+      },
+      impl: (state) => {
+        if (state.context.counter < 0) return 'Counter must be non-negative';
+        return true;
+      },
+    },
+  ],
+};
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe('Praxis MCP Server', () => {
+  let registry: PraxisRegistry<TestContext>;
+
+  beforeEach(() => {
+    registry = new PraxisRegistry<TestContext>({
+      compliance: { enabled: false },
+    });
+    registry.registerModule(testModule);
+  });
+
+  describe('createPraxisMcpServer', () => {
+    it('should create a server with engine and mcpServer', () => {
+      const server = createPraxisMcpServer({
+        initialContext: { counter: 0, name: 'Test' },
+        registry,
+      });
+
+      expect(server).toBeDefined();
+      expect(server.engine).toBeDefined();
+      expect(server.mcpServer).toBeDefined();
+      expect(server.start).toBeInstanceOf(Function);
+    });
+
+    it('should accept custom name and version', () => {
+      const server = createPraxisMcpServer({
+        name: 'my-praxis',
+        version: '2.0.0',
+        initialContext: { counter: 0, name: 'Test' },
+        registry,
+      });
+
+      expect(server).toBeDefined();
+    });
+  });
+
+  describe('engine operations via MCP server', () => {
+    it('should expose a working engine that can step', () => {
+      const server = createPraxisMcpServer({
+        initialContext: { counter: 5, name: 'Alice' },
+        registry,
+      });
+
+      const result = server.engine.step([{ tag: 'counter.increment', payload: {} }]);
+      expect(result.state.facts).toContainEqual(
+        expect.objectContaining({ tag: 'counter.incremented', payload: { value: 6 } }),
+      );
+    });
+
+    it('should get current facts from engine', () => {
+      const server = createPraxisMcpServer({
+        initialContext: { counter: 0, name: 'Test' },
+        registry,
+        initialFacts: [{ tag: 'init', payload: { started: true } }],
+      });
+
+      const facts = server.engine.getFacts();
+      expect(facts).toContainEqual(
+        expect.objectContaining({ tag: 'init' }),
+      );
+    });
+
+    it('should handle rule evaluation via engine', () => {
+      const server = createPraxisMcpServer({
+        initialContext: { counter: 10, name: 'Bob' },
+        registry,
+      });
+
+      const rule = registry.getRule('test/greet');
+      expect(rule).toBeDefined();
+
+      const state = server.engine.getState();
+      const events = [{ tag: 'greet', payload: {} }];
+      const stateWithEvents = { ...state, events };
+      const result = rule!.impl(stateWithEvents as Parameters<typeof rule!.impl>[0], events);
+
+      expect(result).toBeInstanceOf(RuleResult);
+      const rr = result as RuleResult;
+      expect(rr.kind).toBe('emit');
+      expect(rr.facts).toContainEqual(
+        expect.objectContaining({ tag: 'greeting', payload: { message: 'Hello, Bob!' } }),
+      );
+    });
+
+    it('should skip rule when no matching events', () => {
+      const server = createPraxisMcpServer({
+        initialContext: { counter: 0, name: 'Test' },
+        registry,
+      });
+
+      const rule = registry.getRule('test/increment');
+      const state = server.engine.getState();
+      const events = [{ tag: 'unrelated', payload: {} }];
+      const stateWithEvents = { ...state, events };
+      const result = rule!.impl(stateWithEvents as Parameters<typeof rule!.impl>[0], events);
+
+      expect(result).toBeInstanceOf(RuleResult);
+      expect((result as RuleResult).kind).toBe('skip');
+    });
+  });
+
+  describe('registry introspection', () => {
+    it('should list all rules', () => {
+      const rules = registry.getAllRules();
+      expect(rules).toHaveLength(2);
+      expect(rules.map(r => r.id)).toContain('test/increment');
+      expect(rules.map(r => r.id)).toContain('test/greet');
+    });
+
+    it('should list all constraints', () => {
+      const constraints = registry.getAllConstraints();
+      expect(constraints).toHaveLength(1);
+      expect(constraints[0].id).toBe('test/positive-counter');
+    });
+
+    it('should provide contract details for rules', () => {
+      const rule = registry.getRule('test/increment');
+      expect(rule?.contract).toBeDefined();
+      expect(rule?.contract?.behavior).toContain('Increments counter');
+      expect(rule?.contract?.examples).toHaveLength(1);
+      expect(rule?.contract?.invariants).toContain('Counter must always increase by 1');
+    });
+  });
+
+  describe('completeness audit integration', () => {
+    it('should run audit via engine', async () => {
+      const { auditCompleteness, formatReport } = await import('../core/completeness.js');
+
+      const manifest = {
+        branches: [
+          {
+            location: 'test.ts:1',
+            condition: 'counter > 0',
+            kind: 'domain' as const,
+            coveredBy: 'test/increment',
+          },
+        ],
+        stateFields: [
+          { source: 'store', field: 'counter', inContext: true, usedByRule: true },
+        ],
+        transitions: [
+          { description: 'increment counter', eventTag: 'counter.increment', location: 'test.ts:5' },
+        ],
+        rulesNeedingContracts: ['test/increment', 'test/greet'],
+      };
+
+      const rulesWithContracts = registry.getAllRules()
+        .filter(r => r.contract)
+        .map(r => r.id);
+
+      const report = auditCompleteness(
+        manifest,
+        registry.getRuleIds(),
+        registry.getConstraintIds(),
+        rulesWithContracts,
+      );
+
+      expect(report.score).toBeGreaterThan(0);
+      expect(report.rating).toBeDefined();
+      expect(formatReport(report)).toContain('Praxis Completeness');
+    });
+  });
+
+  describe('suggestion engine', () => {
+    it('should generate rule suggestions for behavioral gaps', () => {
+      // Test the suggestId logic indirectly through server creation
+      const server = createPraxisMcpServer({
+        initialContext: { counter: 0, name: 'Test' },
+        registry,
+      });
+
+      expect(server).toBeDefined();
+    });
+  });
+
+  describe('step and state management', () => {
+    it('should step engine and accumulate facts', () => {
+      const server = createPraxisMcpServer({
+        initialContext: { counter: 5, name: 'Alice' },
+        registry,
+      });
+
+      // Step with increment event
+      const result1 = server.engine.step([{ tag: 'counter.increment', payload: {} }]);
+      expect(result1.state.facts.some(f => f.tag === 'counter.incremented')).toBe(true);
+
+      // Step with greet event
+      const result2 = server.engine.step([{ tag: 'greet', payload: {} }]);
+      expect(result2.state.facts.some(f => f.tag === 'greeting')).toBe(true);
+    });
+
+    it('should check constraints after step', () => {
+      const negativeRegistry = new PraxisRegistry<TestContext>({
+        compliance: { enabled: false },
+      });
+      negativeRegistry.registerModule(testModule);
+
+      const server = createPraxisMcpServer({
+        initialContext: { counter: -1, name: 'Test' },
+        registry: negativeRegistry,
+      });
+
+      const result = server.engine.step([{ tag: 'counter.increment', payload: {} }]);
+      // The constraint should report a violation for negative counter
+      const violation = result.diagnostics.find(
+        d => d.kind === 'constraint-violation' && d.message.includes('non-negative'),
+      );
+      expect(violation).toBeDefined();
+    });
+  });
+
+  describe('contract coverage', () => {
+    it('should track which rules have contracts', () => {
+      const rules = registry.getAllRules();
+      const withContracts = rules.filter(r => r.contract);
+      expect(withContracts).toHaveLength(2); // both test rules have contracts
+    });
+
+    it('should track which constraints have contracts', () => {
+      const constraints = registry.getAllConstraints();
+      const withContracts = constraints.filter(c => c.contract);
+      expect(withContracts).toHaveLength(1);
+    });
+  });
+});

package/src/__tests__/project.test.ts

@@ -0,0 +1,396 @@
+/**
+ * Tests for Project Logic
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  defineGate,
+  semverContract,
+  commitFromState,
+  branchRules,
+  lintGate,
+  formatGate,
+  expectationGate,
+} from '../project/project.js';
+import { PraxisRegistry } from '../core/rules.js';
+import { LogicEngine } from '../core/engine.js';
+import type { PraxisDiff } from '../project/types.js';
+
+// ─── Helper ─────────────────────────────────────────────────────────────────
+
+const emptyDiff: PraxisDiff = {
+  rulesAdded: [],
+  rulesRemoved: [],
+  rulesModified: [],
+  contractsAdded: [],
+  contractsRemoved: [],
+  expectationsAdded: [],
+  expectationsRemoved: [],
+  gateChanges: [],
+};
+
+// ─── defineGate ─────────────────────────────────────────────────────────────
+
+describe('Project Logic', () => {
+  describe('defineGate', () => {
+    it('should create a gate module with rule and constraint', () => {
+      const mod = defineGate('deploy', {
+        expects: ['tests-pass', 'lint-clean'],
+        onSatisfied: 'deploy-allowed',
+        onViolation: 'deploy-blocked',
+      });
+
+      expect(mod.rules).toHaveLength(1);
+      expect(mod.constraints).toHaveLength(1);
+      expect(mod.rules![0].id).toBe('gate/deploy');
+    });
+
+    it('should open gate when all expectations satisfied', () => {
+      const mod = defineGate('deploy', {
+        expects: ['tests-pass', 'lint-clean'],
+      });
+      const registry = new PraxisRegistry({ compliance: { enabled: false } });
+      registry.registerModule(mod);
+
+      const engine = new LogicEngine({
+        initialContext: {
+          expectations: { 'tests-pass': true, 'lint-clean': true },
+        },
+        registry,
+      });
+
+      const result = engine.step([{ tag: 'gate.check', payload: {} }]);
+      const status = result.state.facts.find(f => f.tag === 'gate.deploy.status');
+      expect(status).toBeDefined();
+      expect((status!.payload as { status: string }).status).toBe('open');
+    });
+
+    it('should block gate when expectations not met', () => {
+      const mod = defineGate('deploy', {
+        expects: ['tests-pass', 'lint-clean'],
+        onViolation: 'deploy-blocked',
+      });
+      const registry = new PraxisRegistry({ compliance: { enabled: false } });
+      registry.registerModule(mod);
+
+      const engine = new LogicEngine({
+        initialContext: {
+          expectations: { 'tests-pass': true, 'lint-clean': false },
+        },
+        registry,
+      });
+
+      const result = engine.step([{ tag: 'gate.check', payload: {} }]);
+      const status = result.state.facts.find(f => f.tag === 'gate.deploy.status');
+      expect((status!.payload as { status: string }).status).toBe('blocked');
+      expect((status!.payload as { unsatisfied: string[] }).unsatisfied).toContain('lint-clean');
+    });
+
+    it('should emit action fact on satisfied', () => {
+      const mod = defineGate('deploy', {
+        expects: ['ready'],
+        onSatisfied: 'go-deploy',
+      });
+      const registry = new PraxisRegistry({ compliance: { enabled: false } });
+      registry.registerModule(mod);
+
+      const engine = new LogicEngine({
+        initialContext: { expectations: { ready: true } },
+        registry,
+      });
+
+      const result = engine.step([{ tag: 'gate.deploy.check', payload: {} }]);
+      const action = result.state.facts.find(f => f.tag === 'gate.deploy.action');
+      expect(action).toBeDefined();
+      expect((action!.payload as { action: string }).action).toBe('go-deploy');
+    });
+
+    it('should emit action fact on violation', () => {
+      const mod = defineGate('deploy', {
+        expects: ['ready'],
+        onViolation: 'block-deploy',
+      });
+      const registry = new PraxisRegistry({ compliance: { enabled: false } });
+      registry.registerModule(mod);
+
+      const engine = new LogicEngine({
+        initialContext: { expectations: { ready: false } },
+        registry,
+      });
+
+      const result = engine.step([{ tag: 'gate.check', payload: {} }]);
+      const action = result.state.facts.find(f => f.tag === 'gate.deploy.action');
+      expect((action!.payload as { action: string }).action).toBe('block-deploy');
+    });
+
+    it('should include contract with invariants', () => {
+      const mod = defineGate('test', { expects: ['a', 'b'] });
+      expect(mod.rules![0].contract).toBeDefined();
+      expect(mod.rules![0].contract!.invariants.length).toBeGreaterThan(0);
+      expect(mod.constraints![0].contract).toBeDefined();
+    });
+  });
+
+  // ─── Predefined Gates ──────────────────────────────────────────────────
+
+  describe('predefined gates', () => {
+    it('lintGate creates a lint gate', () => {
+      const mod = lintGate();
+      expect(mod.rules![0].id).toBe('gate/lint');
+    });
+
+    it('formatGate creates a format gate', () => {
+      const mod = formatGate();
+      expect(mod.rules![0].id).toBe('gate/format');
+    });
+
+    it('expectationGate creates an expectations gate', () => {
+      const mod = expectationGate();
+      expect(mod.rules![0].id).toBe('gate/expectations');
+    });
+
+    it('predefined gates support additionalExpects', () => {
+      const mod = lintGate({ additionalExpects: ['custom-check'] });
+      expect(mod.rules![0].description).toContain('custom-check');
+    });
+  });
+
+  // ─── semverContract ─────────────────────────────────────────────────────
+
+  describe('semverContract', () => {
+    it('should create a semver check rule', () => {
+      const mod = semverContract({
+        sources: ['package.json', 'version.ts'],
+        invariants: ['All must match'],
+      });
+      expect(mod.rules![0].id).toBe('project/semver-check');
+    });
+
+    it('should emit consistent when versions match', () => {
+      const mod = semverContract({
+        sources: ['package.json', 'version.ts'],
+        invariants: [],
+      });
+      const registry = new PraxisRegistry({ compliance: { enabled: false } });
+      registry.registerModule(mod);
+
+      const engine = new LogicEngine({ initialContext: {}, registry });
+
+      const result = engine.step([{
+        tag: 'project.version-check',
+        payload: {
+          versions: { 'package.json': '1.2.3', 'version.ts': '1.2.3' },
+        },
+      }]);
+
+      const consistent = result.state.facts.find(f => f.tag === 'semver.consistent');
+      expect(consistent).toBeDefined();
+      expect((consistent!.payload as { version: string }).version).toBe('1.2.3');
+    });
+
+    it('should emit inconsistent when versions differ', () => {
+      const mod = semverContract({
+        sources: ['package.json', 'version.ts'],
+        invariants: [],
+      });
+      const registry = new PraxisRegistry({ compliance: { enabled: false } });
+      registry.registerModule(mod);
+
+      const engine = new LogicEngine({ initialContext: {}, registry });
+
+      const result = engine.step([{
+        tag: 'project.version-check',
+        payload: {
+          versions: { 'package.json': '1.2.3', 'version.ts': '1.2.0' },
+        },
+      }]);
+
+      const inconsistent = result.state.facts.find(f => f.tag === 'semver.inconsistent');
+      expect(inconsistent).toBeDefined();
+      expect((inconsistent!.payload as { consistent: boolean }).consistent).toBe(false);
+    });
+  });
+
+  // ─── commitFromState ──────────────────────────────────────────────────
+
+  describe('commitFromState', () => {
+    it('should generate feat message for added rules', () => {
+      const msg = commitFromState({
+        ...emptyDiff,
+        rulesAdded: ['auth/login', 'auth/logout'],
+      });
+
+      expect(msg).toContain('feat(auth)');
+      expect(msg).toContain('auth/login');
+      expect(msg).toContain('auth/logout');
+    });
+
+    it('should generate refactor message for removed rules', () => {
+      const msg = commitFromState({
+        ...emptyDiff,
+        rulesRemoved: ['old/deprecated-rule'],
+      });
+
+      expect(msg).toContain('refactor');
+      expect(msg).toContain('remove');
+    });
+
+    it('should generate refactor message for modified rules', () => {
+      const msg = commitFromState({
+        ...emptyDiff,
+        rulesModified: ['auth/login'],
+      });
+
+      expect(msg).toContain('refactor(auth)');
+      expect(msg).toContain('update');
+    });
+
+    it('should generate feat message for contract additions', () => {
+      const msg = commitFromState({
+        ...emptyDiff,
+        contractsAdded: ['auth/login'],
+      });
+
+      expect(msg).toContain('feat(contracts)');
+    });
+
+    it('should generate feat message for expectation additions', () => {
+      const msg = commitFromState({
+        ...emptyDiff,
+        expectationsAdded: ['toast-behavior'],
+      });
+
+      expect(msg).toContain('feat(expectations)');
+    });
+
+    it('should handle gate changes', () => {
+      const msg = commitFromState({
+        ...emptyDiff,
+        gateChanges: [{ gate: 'deploy', from: 'blocked', to: 'open' }],
+      });
+
+      expect(msg).toContain('gate');
+      expect(msg).toContain('deploy');
+    });
+
+    it('should include body with details', () => {
+      const msg = commitFromState({
+        ...emptyDiff,
+        rulesAdded: ['ui/toast'],
+        contractsAdded: ['ui/toast'],
+      });
+
+      expect(msg).toContain('\n\n');
+      expect(msg).toContain('Rules added: ui/toast');
+      expect(msg).toContain('Contracts added: ui/toast');
+    });
+
+    it('should truncate long rule lists', () => {
+      const msg = commitFromState({
+        ...emptyDiff,
+        rulesAdded: ['a/1', 'a/2', 'a/3', 'a/4', 'a/5'],
+      });
+
+      expect(msg).toContain('+3 more');
+    });
+
+    it('should handle empty diff', () => {
+      const msg = commitFromState(emptyDiff);
+      expect(msg).toContain('chore');
+    });
+
+    it('should infer scope from common prefix', () => {
+      const msg = commitFromState({
+        ...emptyDiff,
+        rulesAdded: ['ui/toast', 'ui/modal'],
+      });
+      expect(msg).toContain('feat(ui)');
+    });
+
+    it('should use "rules" scope for mixed prefixes', () => {
+      const msg = commitFromState({
+        ...emptyDiff,
+        rulesAdded: ['ui/toast', 'auth/login'],
+      });
+      expect(msg).toContain('feat(rules)');
+    });
+  });
+
+  // ─── branchRules ──────────────────────────────────────────────────────
+
+  describe('branchRules', () => {
+    it('should create a branch check rule', () => {
+      const mod = branchRules({
+        naming: 'feat/{name}',
+        mergeConditions: ['tests-pass'],
+      });
+      expect(mod.rules![0].id).toBe('project/branch-check');
+    });
+
+    it('should validate correct branch name', () => {
+      const mod = branchRules({
+        naming: 'feat/{name}',
+        mergeConditions: ['tests-pass'],
+      });
+      const registry = new PraxisRegistry({ compliance: { enabled: false } });
+      registry.registerModule(mod);
+      const engine = new LogicEngine({ initialContext: {}, registry });
+
+      const result = engine.step([{
+        tag: 'project.branch-check',
+        payload: {
+          branch: 'feat/my-feature',
+          conditions: { 'tests-pass': true },
+        },
+      }]);
+
+      const valid = result.state.facts.find(f => f.tag === 'branch.valid');
+      expect(valid).toBeDefined();
+      expect((valid!.payload as { mergeReady: boolean }).mergeReady).toBe(true);
+    });
+
+    it('should reject invalid branch name', () => {
+      const mod = branchRules({
+        naming: 'feat/{name}',
+        mergeConditions: ['tests-pass'],
+      });
+      const registry = new PraxisRegistry({ compliance: { enabled: false } });
+      registry.registerModule(mod);
+      const engine = new LogicEngine({ initialContext: {}, registry });
+
+      const result = engine.step([{
+        tag: 'project.branch-check',
+        payload: {
+          branch: 'random-branch',
+          conditions: { 'tests-pass': true },
+        },
+      }]);
+
+      const invalid = result.state.facts.find(f => f.tag === 'branch.invalid');
+      expect(invalid).toBeDefined();
+      expect((invalid!.payload as { reasons: string[] }).reasons[0]).toContain('pattern');
+    });
+
+    it('should reject when merge conditions not met', () => {
+      const mod = branchRules({
+        naming: 'feat/{name}',
+        mergeConditions: ['tests-pass', 'review-approved'],
+      });
+      const registry = new PraxisRegistry({ compliance: { enabled: false } });
+      registry.registerModule(mod);
+      const engine = new LogicEngine({ initialContext: {}, registry });
+
+      const result = engine.step([{
+        tag: 'project.branch-check',
+        payload: {
+          branch: 'feat/my-feature',
+          conditions: { 'tests-pass': true, 'review-approved': false },
+        },
+      }]);
+
+      const invalid = result.state.facts.find(f => f.tag === 'branch.invalid');
+      expect(invalid).toBeDefined();
+      expect((invalid!.payload as { reasons: string[] }).reasons[0]).toContain('review-approved');
+    });
+  });
+});