@viewscript/renderer 0.1.0-202605140639

package/dist/semantic/__tests__/semantic-translator.test.js

@@ -0,0 +1,203 @@
+/**
+ * Tests for SemanticTranslator (Phase 7: Task 20)
+ */
+import { describe, it, expect } from 'vitest';
+import { SemanticTranslator, createEntityRegistry, createEmptyRegistry, } from '../semantic-translator';
+describe('SemanticTranslator', () => {
+    describe('parseVarId', () => {
+        it('should parse valid VarId keys', () => {
+            const translator = new SemanticTranslator(createEmptyRegistry());
+            expect(translator.parseVarId('1:x')).toEqual({ entityId: 1, component: 'x' });
+            expect(translator.parseVarId('42:y')).toEqual({ entityId: 42, component: 'y' });
+            expect(translator.parseVarId('100:value')).toEqual({ entityId: 100, component: 'value' });
+            expect(translator.parseVarId('5:r')).toEqual({ entityId: 5, component: 'r' });
+            expect(translator.parseVarId('5:alpha')).toEqual({ entityId: 5, component: 'alpha' });
+        });
+        it('should return null for invalid keys', () => {
+            const translator = new SemanticTranslator(createEmptyRegistry());
+            expect(translator.parseVarId('')).toBeNull();
+            expect(translator.parseVarId('invalid')).toBeNull();
+            expect(translator.parseVarId(':x')).toBeNull();
+            expect(translator.parseVarId('1:')).toBeNull();
+            expect(translator.parseVarId('1:unknown_component')).toBeNull();
+            expect(translator.parseVarId('abc:x')).toBeNull();
+        });
+    });
+    describe('parseRationalToFloat', () => {
+        it('should parse rational strings', () => {
+            const translator = new SemanticTranslator(createEmptyRegistry());
+            expect(translator.parseRationalToFloat('100/1')).toBe(100);
+            expect(translator.parseRationalToFloat('1/2')).toBe(0.5);
+            expect(translator.parseRationalToFloat('100')).toBe(100);
+            expect(translator.parseRationalToFloat('-50/1')).toBe(-50);
+            expect(translator.parseRationalToFloat('1/3')).toBeCloseTo(0.333, 2);
+        });
+        it('should handle zero denominator', () => {
+            const translator = new SemanticTranslator(createEmptyRegistry());
+            expect(translator.parseRationalToFloat('1/0')).toBeNaN();
+        });
+    });
+    describe('translateSolution', () => {
+        it('should translate a simple point solution', () => {
+            const registry = createEntityRegistry([
+                { entityId: 1, type: 'point', name: 'P1' },
+            ]);
+            const translator = new SemanticTranslator(registry);
+            const rawSolution = new Map([
+                ['1:x', '100/1'],
+                ['1:y', '200/1'],
+            ]);
+            const result = translator.translateSolution(rawSolution, 0);
+            expect(result.solutionIndex).toBe(0);
+            expect(result.entities).toHaveLength(1);
+            expect(result.entities[0].entityId).toBe(1);
+            expect(result.entities[0].type).toBe('point');
+            expect(result.entities[0].coordinates?.x).toBe(100);
+            expect(result.entities[0].coordinates?.y).toBe(200);
+            expect(result.entities[0].description).toContain('P1');
+            expect(result.entities[0].description).toContain('100');
+            expect(result.entities[0].description).toContain('200');
+        });
+        it('should translate multiple entities', () => {
+            const registry = createEntityRegistry([
+                { entityId: 1, type: 'point', name: 'Start' },
+                { entityId: 2, type: 'point', name: 'End' },
+                { entityId: 3, type: 'control_point', name: 'CP1' },
+            ]);
+            const translator = new SemanticTranslator(registry);
+            const rawSolution = new Map([
+                ['1:x', '0/1'],
+                ['1:y', '0/1'],
+                ['2:x', '100/1'],
+                ['2:y', '0/1'],
+                ['3:x', '50/1'],
+                ['3:y', '50/1'],
+            ]);
+            const result = translator.translateSolution(rawSolution, 0);
+            expect(result.entities).toHaveLength(3);
+            expect(result.summary).toContain('3 entities');
+        });
+        it('should translate color stop entities', () => {
+            const registry = createEntityRegistry([
+                { entityId: 10, type: 'color_stop', name: 'Stop1' },
+            ]);
+            const translator = new SemanticTranslator(registry);
+            const rawSolution = new Map([
+                ['10:r', '255/1'],
+                ['10:g', '128/1'],
+                ['10:b', '0/1'],
+                ['10:alpha', '1/1'],
+                ['10:position', '1/2'],
+            ]);
+            const result = translator.translateSolution(rawSolution, 0);
+            expect(result.entities).toHaveLength(1);
+            expect(result.entities[0].type).toBe('color_stop');
+            expect(result.entities[0].color?.r).toBe(255);
+            expect(result.entities[0].color?.g).toBe(128);
+            expect(result.entities[0].color?.b).toBe(0);
+            expect(result.entities[0].color?.position).toBe(0.5);
+            expect(result.entities[0].description).toContain('50%');
+            expect(result.entities[0].description).toContain('rgb(255, 128, 0)');
+        });
+        it('should handle unknown entity types', () => {
+            const translator = new SemanticTranslator(createEmptyRegistry());
+            const rawSolution = new Map([
+                ['99:x', '50/1'],
+                ['99:y', '75/1'],
+            ]);
+            const result = translator.translateSolution(rawSolution, 0);
+            expect(result.entities).toHaveLength(1);
+            expect(result.entities[0].type).toBe('unknown');
+            expect(result.entities[0].coordinates?.x).toBe(50);
+        });
+        it('should detect horizontal alignment relationships', () => {
+            const registry = createEntityRegistry([
+                { entityId: 1, type: 'point' },
+                { entityId: 2, type: 'point' },
+                { entityId: 3, type: 'point' },
+            ]);
+            const translator = new SemanticTranslator(registry);
+            // Three points on the same horizontal line (y=100)
+            const rawSolution = new Map([
+                ['1:x', '0/1'],
+                ['1:y', '100/1'],
+                ['2:x', '50/1'],
+                ['2:y', '100/1'],
+                ['3:x', '100/1'],
+                ['3:y', '100/1'],
+            ]);
+            const result = translator.translateSolution(rawSolution, 0);
+            expect(result.relationships.length).toBeGreaterThan(0);
+            const alignment = result.relationships.find(r => r.type === 'alignment');
+            expect(alignment).toBeDefined();
+            expect(alignment?.description).toContain('horizontally aligned');
+        });
+    });
+    describe('compareSolutions', () => {
+        it('should detect identical solutions', () => {
+            const registry = createEntityRegistry([
+                { entityId: 1, type: 'point', name: 'P1' },
+            ]);
+            const translator = new SemanticTranslator(registry);
+            const rawSolution = new Map([
+                ['1:x', '100/1'],
+                ['1:y', '200/1'],
+            ]);
+            const solution1 = translator.translateSolution(rawSolution, 0);
+            const solution2 = translator.translateSolution(rawSolution, 1);
+            const diff = translator.compareSolutions(solution1, solution2);
+            expect(diff.differingEntities).toHaveLength(0);
+            expect(diff.summary).toContain('identical');
+        });
+        it('should detect differing solutions', () => {
+            const registry = createEntityRegistry([
+                { entityId: 1, type: 'point', name: 'P1' },
+            ]);
+            const translator = new SemanticTranslator(registry);
+            const solution1 = translator.translateSolution(new Map([['1:x', '100/1'], ['1:y', '200/1']]), 0);
+            const solution2 = translator.translateSolution(new Map([['1:x', '150/1'], ['1:y', '250/1']]), 1);
+            const diff = translator.compareSolutions(solution1, solution2);
+            expect(diff.differingEntities).toHaveLength(1);
+            expect(diff.differingEntities[0].entityId).toBe(1);
+            expect(diff.summary).toContain('1 entities differ');
+        });
+    });
+    describe('translateMultipleSolutions', () => {
+        it('should translate and compare multiple solutions', () => {
+            const registry = createEntityRegistry([
+                { entityId: 1, type: 'point', name: 'P1' },
+            ]);
+            const translator = new SemanticTranslator(registry);
+            const rawSolutions = [
+                new Map([['1:x', '100/1'], ['1:y', '0/1']]),
+                new Map([['1:x', '-100/1'], ['1:y', '0/1']]),
+            ];
+            const result = translator.translateMultipleSolutions(rawSolutions);
+            expect(result.solutions).toHaveLength(2);
+            expect(result.comparison).toContain('2 solutions found');
+            expect(result.comparison).toContain('differ');
+        });
+        it('should handle single solution', () => {
+            const translator = new SemanticTranslator(createEmptyRegistry());
+            const rawSolutions = [
+                new Map([['1:x', '100/1']]),
+            ];
+            const result = translator.translateMultipleSolutions(rawSolutions);
+            expect(result.solutions).toHaveLength(1);
+            expect(result.comparison).toContain('Only one solution');
+        });
+    });
+});
+describe('createEntityRegistry', () => {
+    it('should create a working registry', () => {
+        const entities = [
+            { entityId: 1, type: 'point', name: 'P1' },
+            { entityId: 2, type: 'rect', name: 'R1' },
+        ];
+        const registry = createEntityRegistry(entities);
+        expect(registry.get(1)?.type).toBe('point');
+        expect(registry.get(2)?.name).toBe('R1');
+        expect(registry.get(999)).toBeUndefined();
+        expect(registry.getAll()).toHaveLength(2);
+    });
+});

package/dist/semantic/semantic-translator.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Semantic Translator for P/Q Dimension Bridge (Phase 7: Task 20)
+ *
+ * This module converts raw solver output (VarId -> Rational maps) into
+ * entity-level coordinate descriptions suitable for LLM comprehension.
+ *
+ * ## Purpose
+ *
+ * The P-dimension solver produces solutions in the form:
+ *   { "1:x": "100/1", "1:y": "200/1", "2:x": "300/1", ... }
+ *
+ * This is not LLM-friendly. The SemanticTranslator converts this to:
+ *   {
+ *     entities: [
+ *       { entityId: 1, coordinates: { x: 100, y: 200 }, description: "Point at (100, 200)" },
+ *       { entityId: 2, coordinates: { x: 300, y: 150 }, description: "Point at (300, 150)" }
+ *     ],
+ *     relationships: [
+ *       { type: "distance", from: 1, to: 2, value: "~212 units" }
+ *     ]
+ *   }
+ *
+ * ## Axiom 2: Ouroboros Binding
+ *
+ * This module sits at the P/Q dimension boundary. It translates deterministic
+ * solver output (P) into natural language suitable for non-deterministic
+ * oracles (Q/LLM).
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const translator = new SemanticTranslator(entityRegistry);
+ * const semanticSolution = translator.translateSolution(rawSolution);
+ * const diff = translator.compareSolutions(solution1, solution2);
+ * ```
+ */
+import type { EntityId } from '../ast/types';
+/**
+ * Raw solution from solver: "entity_id:component" -> "numerator/denominator"
+ */
+export type RawSolution = Map<string, string>;
+/**
+ * Parsed VarId key.
+ */
+export interface ParsedVarId {
+    entityId: EntityId;
+    component: VectorComponent;
+}
+/**
+ * Vector components matching Rust VectorComponent enum.
+ */
+export type VectorComponent = 'x' | 'y' | 'z' | 't' | 'value' | 'r' | 'g' | 'b' | 'alpha' | 'position';
+/**
+ * Entity type classification for semantic descriptions.
+ */
+export type EntityType = 'point' | 'control_point' | 'rect' | 'circle' | 'text' | 'color_stop' | 'scalar' | 'unknown';
+/**
+ * Metadata about an entity (provided by the constraint graph).
+ */
+export interface EntityMetadata {
+    entityId: EntityId;
+    type: EntityType;
+    name?: string;
+    parentId?: EntityId;
+}
+/**
+ * Registry of entity metadata for semantic translation.
+ */
+export interface EntityRegistry {
+    get(entityId: EntityId): EntityMetadata | undefined;
+    getAll(): EntityMetadata[];
+}
+/**
+ * Coordinates for a spatial entity.
+ */
+export interface EntityCoordinates {
+    x?: number;
+    y?: number;
+    z?: number;
+    t?: number;
+}
+/**
+ * Color values for a color stop entity.
+ */
+export interface EntityColor {
+    r?: number;
+    g?: number;
+    b?: number;
+    alpha?: number;
+    position?: number;
+}
+/**
+ * Scalar value for value-only entities.
+ */
+export interface EntityScalar {
+    value?: number;
+}
+/**
+ * A semantic entity description.
+ */
+export interface SemanticEntity {
+    entityId: EntityId;
+    type: EntityType;
+    name?: string;
+    /** Spatial coordinates (for points, rects, etc.) */
+    coordinates?: EntityCoordinates;
+    /** Color values (for color stops) */
+    color?: EntityColor;
+    /** Scalar value (for radius, angle, etc.) */
+    scalar?: EntityScalar;
+    /** Human-readable description for LLM */
+    description: string;
+}
+/**
+ * Relationship between entities derived from geometry.
+ */
+export interface SemanticRelationship {
+    type: 'distance' | 'alignment' | 'containment' | 'collinear';
+    fromEntityId: EntityId;
+    toEntityId: EntityId;
+    description: string;
+    value?: string;
+}
+/**
+ * Complete semantic solution.
+ */
+export interface SemanticSolution {
+    /** Unique identifier for this solution (index in MultipleSolutions) */
+    solutionIndex: number;
+    /** All entities with resolved coordinates */
+    entities: SemanticEntity[];
+    /** Derived relationships between entities */
+    relationships: SemanticRelationship[];
+    /** High-level summary for LLM consumption */
+    summary: string;
+}
+/**
+ * Difference between two solutions.
+ */
+export interface SolutionDiff {
+    /** Entities that differ between solutions */
+    differingEntities: EntityDiff[];
+    /** Human-readable diff summary */
+    summary: string;
+}
+export interface EntityDiff {
+    entityId: EntityId;
+    name?: string;
+    solution1: SemanticEntity;
+    solution2: SemanticEntity;
+    description: string;
+}
+/**
+ * Translates raw solver output to LLM-friendly semantic descriptions.
+ */
+export declare class SemanticTranslator {
+    private readonly registry;
+    constructor(registry: EntityRegistry);
+    /**
+     * Parse a raw VarId key (e.g., "5:x") into its components.
+     */
+    parseVarId(key: string): ParsedVarId | null;
+    /**
+     * Parse a rational string (e.g., "100/1" or "100") to a number.
+     *
+     * WARNING: This converts P-dimension exact rationals to Q-dimension floats.
+     * Only use for display/LLM consumption, NEVER for constraint solving.
+     */
+    parseRationalToFloat(value: string): number;
+    /**
+     * Translate a raw solution to a semantic solution.
+     */
+    translateSolution(rawSolution: RawSolution, solutionIndex?: number): SemanticSolution;
+    /**
+     * Build a semantic entity from raw components.
+     */
+    private buildSemanticEntity;
+    /**
+     * Generate description for a spatial entity.
+     */
+    private describeSpatialEntity;
+    /**
+     * Generate description for a color stop.
+     */
+    private describeColorStop;
+    /**
+     * Generate description for a scalar entity.
+     */
+    private describeScalar;
+    /**
+     * Format a coordinate value for display.
+     */
+    private formatCoord;
+    /**
+     * Derive geometric relationships between entities.
+     */
+    private deriveRelationships;
+    /**
+     * Generate a high-level summary of the solution.
+     */
+    private generateSummary;
+    /**
+     * Compare two solutions and generate a diff.
+     */
+    compareSolutions(solution1: SemanticSolution, solution2: SemanticSolution): SolutionDiff;
+    /**
+     * Check if two semantic entities are equal.
+     */
+    private entitiesEqual;
+    /**
+     * Describe the difference between two entities.
+     */
+    private describeDiff;
+    /**
+     * Translate multiple solutions and generate comparative descriptions.
+     */
+    translateMultipleSolutions(rawSolutions: RawSolution[]): {
+        solutions: SemanticSolution[];
+        comparison: string;
+    };
+}
+/**
+ * Create an EntityRegistry from an array of metadata.
+ */
+export declare function createEntityRegistry(entities: EntityMetadata[]): EntityRegistry;
+/**
+ * Create an empty EntityRegistry (all entities will be "unknown" type).
+ */
+export declare function createEmptyRegistry(): EntityRegistry;