domainforge 0.13.0

package/typescript-tests/expression.test.ts

@@ -0,0 +1,228 @@
+import { describe, it, expect } from 'vitest';
+import {
+  Expression,
+  NormalizedExpression,
+  BinaryOp,
+  UnaryOp,
+  Quantifier,
+  AggregateFunction,
+  WindowSpec,
+} from '..';
+
+describe('Expression Factory Methods', () => {
+  it('creates boolean literal expressions', () => {
+    const exprTrue = Expression.literalBool(true);
+    expect(exprTrue.toStringRepr()).toBe('true');
+
+    const exprFalse = Expression.literalBool(false);
+    expect(exprFalse.toStringRepr()).toBe('false');
+  });
+
+  it('creates number literal expressions', () => {
+    const expr = Expression.literalNumber(42);
+    expect(expr.toStringRepr()).toContain('42');
+  });
+
+  it('creates string literal expressions', () => {
+    const expr = Expression.literalString('hello');
+    expect(expr.toStringRepr()).toContain('hello');
+  });
+
+  it('creates variable expressions', () => {
+    const expr = Expression.variable('x');
+    expect(expr.toStringRepr()).toBe('x');
+  });
+
+  it('creates quantity expressions', () => {
+    const expr = Expression.quantity('100', 'USD');
+    const str = expr.toStringRepr();
+    expect(str).toContain('100');
+    expect(str).toContain('USD');
+  });
+
+  it('creates time expressions', () => {
+    const expr = Expression.time('2025-01-01T00:00:00Z');
+    expect(expr.toStringRepr()).toContain('2025-01-01');
+  });
+
+  it('creates interval expressions', () => {
+    const expr = Expression.interval('2025-01-01T09:00:00Z', '2025-01-01T17:00:00Z');
+    const str = expr.toStringRepr();
+    expect(str).toContain('09:00:00');
+    expect(str).toContain('17:00:00');
+  });
+
+  it('creates binary expressions', () => {
+    const left = Expression.variable('a');
+    const right = Expression.variable('b');
+    const expr = Expression.binary(BinaryOp.And, left, right);
+    const str = expr.toStringRepr();
+    expect(str).toContain('AND');
+    expect(str).toContain('a');
+    expect(str).toContain('b');
+  });
+
+  it('creates unary NOT expressions', () => {
+    const operand = Expression.variable('x');
+    const expr = Expression.unary(UnaryOp.Not, operand);
+    const str = expr.toStringRepr();
+    expect(str).toContain('NOT');
+    expect(str).toContain('x');
+  });
+
+  it('creates member access expressions', () => {
+    const expr = Expression.memberAccess('user', 'name');
+    const str = expr.toStringRepr();
+    expect(str).toContain('user');
+    expect(str).toContain('name');
+  });
+
+  it('creates cast expressions', () => {
+    const operand = Expression.variable('x');
+    const expr = Expression.cast(operand, 'Money');
+    const str = expr.toStringRepr();
+    expect(str).toContain('x');
+    expect(str).toContain('Money');
+  });
+
+  it('creates quantifier expressions', () => {
+    const collection = Expression.variable('items');
+    const condition = Expression.variable('valid');
+    const expr = Expression.quantifier(Quantifier.ForAll, 'x', collection, condition);
+    const str = expr.toStringRepr().toLowerCase();
+    expect(str).toContain('forall');
+  });
+
+  it('creates aggregation expressions', () => {
+    const collection = Expression.variable('items');
+    const expr = Expression.aggregation(AggregateFunction.Count, collection, null, null);
+    const str = expr.toStringRepr().toLowerCase();
+    expect(str).toContain('count');
+  });
+});
+
+describe('Normalization', () => {
+  it('returns a NormalizedExpression', () => {
+    const expr = Expression.variable('x');
+    const normalized = expr.normalize();
+    expect(normalized).toBeDefined();
+    expect(typeof normalized.stableHash).toBe('function');
+  });
+
+  it('eliminates identity (true AND x → x)', () => {
+    const trueExpr = Expression.literalBool(true);
+    const xExpr = Expression.variable('x');
+    const expr = Expression.binary(BinaryOp.And, trueExpr, xExpr);
+    const normalized = expr.normalize();
+    expect(normalized.toStringRepr()).toBe('x');
+  });
+
+  it('eliminates identity (false OR x → x)', () => {
+    const falseExpr = Expression.literalBool(false);
+    const xExpr = Expression.variable('x');
+    const expr = Expression.binary(BinaryOp.Or, falseExpr, xExpr);
+    const normalized = expr.normalize();
+    expect(normalized.toStringRepr()).toBe('x');
+  });
+
+  it('sorts commutative operands', () => {
+    const b = Expression.variable('b');
+    const a = Expression.variable('a');
+    const expr = Expression.binary(BinaryOp.And, b, a);
+    const normalized = expr.normalize();
+    expect(normalized.toStringRepr()).toBe('(a AND b)');
+  });
+
+  it('applies idempotence (a AND a → a)', () => {
+    const a = Expression.variable('a');
+    const expr = Expression.binary(BinaryOp.And, a, a);
+    const normalized = expr.normalize();
+    expect(normalized.toStringRepr()).toBe('a');
+  });
+
+  it('eliminates double negation (NOT NOT x → x)', () => {
+    const x = Expression.variable('x');
+    const notX = Expression.unary(UnaryOp.Not, x);
+    const notNotX = Expression.unary(UnaryOp.Not, notX);
+    const normalized = notNotX.normalize();
+    expect(normalized.toStringRepr()).toBe('x');
+  });
+});
+
+describe('Equivalence', () => {
+  it('recognizes equivalent expressions', () => {
+    const a1 = Expression.variable('a');
+    const b1 = Expression.variable('b');
+    const expr1 = Expression.binary(BinaryOp.And, a1, b1);
+
+    const a2 = Expression.variable('a');
+    const b2 = Expression.variable('b');
+    const expr2 = Expression.binary(BinaryOp.And, b2, a2);
+
+    expect(expr1.isEquivalent(expr2)).toBe(true);
+  });
+
+  it('recognizes non-equivalent expressions', () => {
+    const a = Expression.variable('a');
+    const b = Expression.variable('b');
+    const c = Expression.variable('c');
+
+    const expr1 = Expression.binary(BinaryOp.And, a, b);
+    const expr2 = Expression.binary(BinaryOp.And, a, c);
+
+    expect(expr1.isEquivalent(expr2)).toBe(false);
+  });
+});
+
+describe('Stable Hash', () => {
+  it('is deterministic', () => {
+    const expr = Expression.variable('x');
+    const hash1 = expr.normalize().stableHash();
+    const hash2 = expr.normalize().stableHash();
+    expect(hash1).toBe(hash2);
+  });
+
+  it('is the same for equivalent expressions', () => {
+    const a1 = Expression.variable('a');
+    const b1 = Expression.variable('b');
+    const expr1 = Expression.binary(BinaryOp.And, a1, b1);
+
+    const a2 = Expression.variable('a');
+    const b2 = Expression.variable('b');
+    const expr2 = Expression.binary(BinaryOp.And, b2, a2);
+
+    expect(expr1.normalize().stableHash()).toBe(expr2.normalize().stableHash());
+  });
+
+  it('has hex representation', () => {
+    const expr = Expression.variable('x');
+    const hashHex = expr.normalize().stableHashHex();
+    expect(hashHex).toMatch(/^0x[0-9a-f]+$/);
+  });
+});
+
+describe('NormalizedExpression Methods', () => {
+  it('returns inner expression', () => {
+    const expr = Expression.variable('x');
+    const normalized = expr.normalize();
+    const inner = normalized.innerExpression();
+    expect(inner.toStringRepr()).toBe('x');
+  });
+
+  it('has string representation', () => {
+    const expr = Expression.variable('x');
+    const normalized = expr.normalize();
+    expect(normalized.toStringRepr()).toBe('x');
+  });
+
+  it('supports equality check', () => {
+    const a = Expression.variable('a');
+    const b = Expression.variable('b');
+    const expr1 = Expression.binary(BinaryOp.And, a, b);
+    const expr2 = Expression.binary(BinaryOp.And, b, a);
+
+    const norm1 = expr1.normalize();
+    const norm2 = expr2.normalize();
+    expect(norm1.equals(norm2)).toBe(true);
+  });
+});

package/typescript-tests/golden-payment-flow.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { Graph } from '../index';
+
+const PAYMENT_DSL = `
+Role "Payer"
+Role "Payee"
+
+Resource "Money" units
+
+Entity "Alice"
+Entity "Bob"
+
+Flow "Money" from "Alice" to "Bob" quantity 10
+
+Relation "Payment"
+  subject: "Payer"
+  predicate: "pays"
+  object: "Payee"
+  via: flow "Money"
+`;
+
+describe('Payment role flow golden path', () => {
+    it('parses roles, relations, and flows consistently', () => {
+        const graph = Graph.parse(PAYMENT_DSL);
+
+        expect(graph.entityCount()).toBe(2);
+        expect(graph.resourceCount()).toBe(1);
+        expect(graph.flowCount()).toBe(1);
+        expect(graph.roleCount()).toBe(2);
+        expect(graph.relationCount()).toBe(1);
+
+        const roles = Object.fromEntries(
+            graph.allRoles().map((role) => [role.name, role.id])
+        );
+        expect(roles).toHaveProperty('Payer');
+        expect(roles).toHaveProperty('Payee');
+
+        const relations = graph.allRelations();
+        expect(relations).toHaveLength(1);
+        expect(relations[0].name).toBe('Payment');
+        expect(relations[0].predicate).toBe('pays');
+        expect(relations[0].subjectRoleId).toBe(roles.Payer);
+        expect(relations[0].objectRoleId).toBe(roles.Payee);
+        const flows = graph.allFlows();
+        expect(flows).toHaveLength(1);
+        const flowResource = flows[0].resourceId ? graph.getResource(flows[0].resourceId) : null;
+        expect(flowResource).not.toBeNull();
+        expect(flowResource?.name).toBe('Money');
+        expect(flows[0].quantity).toBe(10);
+    });
+});

package/typescript-tests/graph.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest';
+import { Graph, Entity, Resource, Flow } from '../index';
+
+describe('Graph', () => {
+  it('creates empty graph', () => {
+    const graph = new Graph();
+    expect(graph.entityCount()).toBe(0);
+    expect(graph.resourceCount()).toBe(0);
+    expect(graph.flowCount()).toBe(0);
+  });
+
+  it('adds entities', () => {
+    const graph = new Graph();
+    const entity = new Entity('Warehouse');
+    
+    graph.addEntity(entity);
+    expect(graph.entityCount()).toBe(1);
+    expect(graph.hasEntity(entity.id)).toBe(true);
+  });
+
+  it('adds resources', () => {
+    const graph = new Graph();
+    const resource = new Resource('Cameras', 'units');
+    
+    graph.addResource(resource);
+    expect(graph.resourceCount()).toBe(1);
+    expect(graph.hasResource(resource.id)).toBe(true);
+  });
+
+  it('adds flows', () => {
+    const graph = new Graph();
+    const entity1 = new Entity('Warehouse');
+    const entity2 = new Entity('Factory');
+    const resource = new Resource('Cameras', 'units');
+    
+    graph.addEntity(entity1);
+    graph.addEntity(entity2);
+    graph.addResource(resource);
+    
+    const flow = new Flow(resource.id, entity1.id, entity2.id, 100);
+    graph.addFlow(flow);
+    
+    expect(graph.flowCount()).toBe(1);
+  });
+
+  it('retrieves entities by ID', () => {
+    const graph = new Graph();
+    const entity = new Entity('Warehouse');
+    
+    graph.addEntity(entity);
+    const retrieved = graph.getEntity(entity.id);
+    
+    expect(retrieved).not.toBeNull();
+    expect(retrieved!.name).toBe('Warehouse');
+  });
+
+  it('finds entities by name', () => {
+    const graph = new Graph();
+    const entity = new Entity('Warehouse');
+    
+    graph.addEntity(entity);
+    const foundId = graph.findEntityByName('Warehouse');
+    
+    expect(foundId).toBe(entity.id);
+  });
+
+  it('queries flows from entity', () => {
+    const graph = new Graph();
+    const entity1 = new Entity('Warehouse');
+    const entity2 = new Entity('Factory');
+    const resource = new Resource('Cameras', 'units');
+    
+    graph.addEntity(entity1);
+    graph.addEntity(entity2);
+    graph.addResource(resource);
+    
+    const flow = new Flow(resource.id, entity1.id, entity2.id, 100);
+    graph.addFlow(flow);
+    
+    const flows = graph.flowsFrom(entity1.id);
+    expect(flows.length).toBe(1);
+    expect(flows[0].quantity).toBe(100);
+  });
+
+  it('queries flows to entity', () => {
+    const graph = new Graph();
+    const entity1 = new Entity('Warehouse');
+    const entity2 = new Entity('Factory');
+    const resource = new Resource('Cameras', 'units');
+    
+    graph.addEntity(entity1);
+    graph.addEntity(entity2);
+    graph.addResource(resource);
+    
+    const flow = new Flow(resource.id, entity1.id, entity2.id, 100);
+    graph.addFlow(flow);
+    
+    const flows = graph.flowsTo(entity2.id);
+    expect(flows.length).toBe(1);
+    expect(flows[0].quantity).toBe(100);
+  });
+
+  it('lists all entities', () => {
+    const graph = new Graph();
+    graph.addEntity(new Entity('Warehouse'));
+    graph.addEntity(new Entity('Factory'));
+    
+    const entities = graph.allEntities();
+    expect(entities.length).toBe(2);
+  });
+
+  it('parses SEA DSL', () => {
+    const source = `
+      Entity "Warehouse" in logistics
+      Entity "Factory" in manufacturing
+      Resource "Cameras" units
+      Flow "Cameras" from "Warehouse" to "Factory" quantity 100
+    `;
+    
+    const graph = Graph.parse(source);
+    expect(graph.entityCount()).toBe(2);
+    expect(graph.resourceCount()).toBe(1);
+    expect(graph.flowCount()).toBe(1);
+  });
+
+  it('parses complex DSL with namespaces', () => {
+    const source = `
+      Entity "Main Warehouse" in logistics
+      Entity "Assembly Line" in manufacturing
+      Resource "Electronic Components" units in electronics
+      Flow "Electronic Components" from "Main Warehouse" to "Assembly Line" quantity 500
+    `;
+    
+    const graph = Graph.parse(source);
+    const entities = graph.allEntities();
+    const resources = graph.allResources();
+    
+    expect(entities.some(e => e.namespace === 'logistics')).toBe(true);
+    expect(entities.some(e => e.namespace === 'manufacturing')).toBe(true);
+    expect(resources.some(r => r.namespace === 'electronics')).toBe(true);
+  });
+});

package/typescript-tests/native-binding.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { validateNativeExports } from '../lib/validate_native_exports';
+
+describe('validateNativeExports helper', () => {
+    it('throws a helpful error when required exports are missing', () => {
+        const fakeBinding = { Graph: {} }; // minimal missing many required symbols
+        const required = ['Graph', 'Entity', 'Resource'];
+        expect(() => validateNativeExports(fakeBinding, required)).toThrowError(/Missing required export\(s\): Entity, Resource|missing required export/i);
+    });
+
+    it('does not throw when required exports are present', () => {
+        const fakeBinding = {
+            Graph: {},
+            Entity: {},
+            Resource: {},
+        };
+        const required = ['Graph', 'Entity', 'Resource'];
+        expect(() => validateNativeExports(fakeBinding, required)).not.toThrow();
+    });
+});

package/typescript-tests/primitives.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import { Entity, Resource, Flow, ResourceInstance } from '../index';
+
+describe('Entity', () => {
+  it('creates entity with name', () => {
+    const entity = new Entity('Warehouse A');
+    expect(entity.name).toBe('Warehouse A');
+    expect(entity.id).toHaveLength(36);
+  });
+
+  it('supports namespaces', () => {
+    const entity = new Entity('Factory', 'manufacturing');
+    expect(entity.namespace).toBe('manufacturing');
+  });
+
+  it('manages attributes', () => {
+    const entity = new Entity('Warehouse');
+    entity.setAttribute('capacity', JSON.stringify(10000));
+    expect(JSON.parse(entity.getAttribute('capacity')!)).toBe(10000);
+  });
+
+  it('handles complex attributes', () => {
+    const entity = new Entity('Warehouse');
+    entity.setAttribute('location', JSON.stringify({ lat: 40.7128, lng: -74.0060 }));
+    const location = JSON.parse(entity.getAttribute('location')!);
+    expect(location.lat).toBe(40.7128);
+    expect(location.lng).toBe(-74.0060);
+  });
+});
+
+describe('Resource', () => {
+  it('creates resource with unit', () => {
+    const resource = new Resource('Cameras', 'units');
+    expect(resource.name).toBe('Cameras');
+    expect(resource.unit).toBe('units');
+    expect(resource.id).toHaveLength(36);
+  });
+
+  it('supports namespaces', () => {
+    const resource = new Resource('Steel', 'kg', 'materials');
+    expect(resource.namespace).toBe('materials');
+  });
+
+  it('manages attributes', () => {
+    const resource = new Resource('Cameras', 'units');
+    resource.setAttribute('model', JSON.stringify('HD-2000'));
+    expect(JSON.parse(resource.getAttribute('model')!)).toBe('HD-2000');
+  });
+});
+
+describe('Flow', () => {
+  it('creates flow between entities', () => {
+    const entity1 = new Entity('Warehouse');
+    const entity2 = new Entity('Factory');
+    const resource = new Resource('Cameras', 'units');
+    
+    const flow = new Flow(resource.id, entity1.id, entity2.id, 100);
+    expect(flow.resourceId).toBe(resource.id);
+    expect(flow.fromId).toBe(entity1.id);
+    expect(flow.toId).toBe(entity2.id);
+    expect(flow.quantity).toBe(100);
+  });
+
+  it('throws on invalid UUID', () => {
+    expect(() => {
+      new Flow('invalid-uuid', 'also-invalid', 'still-invalid', 100);
+    }).toThrow();
+  });
+});
+
+describe('ResourceInstance', () => {
+  it('creates instance', () => {
+    const entity = new Entity('Warehouse');
+    const resource = new Resource('Cameras', 'units');
+    
+    const instance = new ResourceInstance(resource.id, entity.id);
+    expect(instance.resourceId).toBe(resource.id);
+    expect(instance.entityId).toBe(entity.id);
+  });
+
+  it('supports namespaces', () => {
+    const entity = new Entity('Warehouse');
+    const resource = new Resource('Cameras', 'units');
+    
+    const instance = new ResourceInstance(resource.id, entity.id, 'inventory');
+    expect(instance.namespace).toBe('inventory');
+  });
+});

package/typescript-tests/registry.test.ts

@@ -0,0 +1,122 @@
+import * as fs from 'fs';
+import { tmpdir } from 'os';
+import * as path from 'path';
+import { describe, expect, it } from 'vitest';
+import { NamespaceRegistry } from '../index';
+
+describe('NamespaceRegistry (TS)', () => {
+    it('discovers and resolves files', () => {
+        // Skip test if addon does not expose namespace registry (prebuilt binaries)
+        if ((global as any).NamespaceRegistry === undefined) {
+            // Access via require('./index') module import
+            const index = require('../index');
+            if (!index.NamespaceRegistry) {
+                // Skip runtime assertion rather than failing the build
+                return;
+            }
+        }
+        const base = fs.mkdtempSync(path.join(tmpdir(), 'sea-test-'));
+        const dir = path.join(base, 'domains', 'logistics');
+        fs.mkdirSync(dir, { recursive: true });
+        const filePath = path.join(dir, 'warehouse.sea');
+        fs.writeFileSync(filePath, 'Entity "Warehouse"');
+
+        const registryPath = path.join(base, '.sea-registry.toml');
+        const content = `version = 1\ndefault_namespace = "default"\n\n[[namespaces]]\nnamespace = "logistics"\npatterns = ["domains/logistics/**/*.sea"]\n`;
+        fs.writeFileSync(registryPath, content);
+
+        const reg = NamespaceRegistry.fromFile(registryPath);
+        expect(reg).toBeDefined();
+        const files = reg.resolveFiles();
+        expect(files.length).toBe(1);
+        expect(files[0].path).toBe(filePath);
+        expect(files[0].namespace).toBe('logistics');
+
+        const ns = reg.namespaceFor(filePath);
+        expect(ns).toBe('logistics');
+    });
+
+    it('enforces precedence longest prefix', () => {
+        if ((global as any).NamespaceRegistry === undefined) {
+            const index = require('../index');
+            if (!index.NamespaceRegistry) {
+                return;
+            }
+        }
+        const base = fs.mkdtempSync(path.join(tmpdir(), 'sea-test-'));
+        const dir = path.join(base, 'domains', 'logistics');
+        fs.mkdirSync(dir, { recursive: true });
+        const filePath = path.join(dir, 'warehouse.sea');
+        fs.writeFileSync(filePath, 'Entity "Warehouse"');
+
+        const registryPath = path.join(base, '.sea-registry.toml');
+        const content = `version = 1\ndefault_namespace = "default"\n\n[[namespaces]]\nnamespace = "short"\npatterns = ["domains/**/*.sea"]\n\n[[namespaces]]\nnamespace = "long"\npatterns = ["domains/logistics/**/*.sea"]\n`;
+        fs.writeFileSync(registryPath, content);
+
+        const reg = NamespaceRegistry.fromFile(registryPath);
+        expect(reg).toBeDefined();
+        const ns = reg.namespaceFor(filePath);
+        expect(ns).toBe('long');
+    });
+
+    it('enforces alphabetical tie-breaker', () => {
+        if ((global as any).NamespaceRegistry === undefined) {
+            const index = require('../index');
+            if (!index.NamespaceRegistry) {
+                return;
+            }
+        }
+        const base = fs.mkdtempSync(path.join(tmpdir(), 'sea-test-'));
+        const dir = path.join(base, 'domains', 'logistics');
+        fs.mkdirSync(dir, { recursive: true });
+        const filePath = path.join(dir, 'warehouse.sea');
+        fs.writeFileSync(filePath, 'Entity "Warehouse"');
+
+        const registryPath = path.join(base, '.sea-registry.toml');
+        const content = `version = 1\ndefault_namespace = "default"\n\n[[namespaces]]\nnamespace = "logistics"\npatterns = ["domains/*/warehouse.sea"]\n\n[[namespaces]]\nnamespace = "finance"\npatterns = ["domains/*/warehouse.sea"]\n`;
+        fs.writeFileSync(registryPath, content);
+
+        const reg = NamespaceRegistry.fromFile(registryPath);
+        expect(reg).toBeDefined();
+        const ns = reg.namespaceFor(filePath);
+        expect(ns).toBe('finance');
+    });
+
+    it('errors on ambiguous match when fail flag set', () => {
+        if ((global as any).NamespaceRegistry === undefined) {
+            const index = require('../index');
+            if (!index.NamespaceRegistry) {
+                return;
+            }
+        }
+        const base = fs.mkdtempSync(path.join(tmpdir(), 'sea-test-'));
+        const dir = path.join(base, 'domains', 'logistics');
+        fs.mkdirSync(dir, { recursive: true });
+        const filePath = path.join(dir, 'warehouse.sea');
+        fs.writeFileSync(filePath, 'Entity "Warehouse"');
+
+        const registryPath = path.join(base, '.sea-registry.toml');
+        const content = `version = 1\ndefault_namespace = "default"\n\n[[namespaces]]\nnamespace = "logistics"\npatterns = ["domains/*/warehouse.sea"]\n\n[[namespaces]]\nnamespace = "finance"\npatterns = ["domains/*/warehouse.sea"]\n`;
+        fs.writeFileSync(registryPath, content);
+
+        const reg = NamespaceRegistry.fromFile(registryPath);
+        expect(reg).toBeDefined();
+        let threw = false;
+        try {
+            // pass true to indicate failing on ambiguity
+            reg.namespaceFor(filePath, true);
+        } catch (err) {
+            threw = true;
+        }
+        expect(threw).toBe(true);
+
+        // resolveFiles should error as well
+        threw = false;
+        try {
+            reg.resolveFiles(true);
+        } catch (err) {
+            threw = true;
+        }
+        expect(threw).toBe(true);
+    });
+});