@polagram/core 0.0.2

package/dist/src/parser/languages/mermaid/parser.test.js

@@ -0,0 +1,252 @@
+import { describe, expect, it } from 'vitest';
+import { Lexer } from './lexer';
+import { Parser } from './parser';
+describe('Mermaid Parser', () => {
+    const parse = (input) => {
+        const lexer = new Lexer(input);
+        const parser = new Parser(lexer);
+        return parser.parse();
+    };
+    describe('Basic Document Structure', () => {
+        it('should parse "sequenceDiagram" header', () => {
+            const input = `sequenceDiagram`;
+            const ast = parse(input);
+            expect(ast.kind).toBe('root');
+            expect(ast.meta.source).toBe('mermaid');
+            expect(ast.participants).toEqual([]);
+            expect(ast.events).toEqual([]);
+        });
+        it('should handle newlines around header', () => {
+            const input = `
+sequenceDiagram
+`;
+            const ast = parse(input);
+            expect(ast.meta.source).toBe('mermaid');
+        });
+    });
+    describe('Participant Definitions', () => {
+        it('should parse simple participant', () => {
+            const input = `
+sequenceDiagram
+participant Alice
+participant Bob
+`;
+            const ast = parse(input);
+            expect(ast.participants).toHaveLength(2);
+            expect(ast.participants[0]).toMatchObject({
+                id: 'Alice',
+                name: 'Alice',
+                type: 'participant'
+            });
+            expect(ast.participants[1]).toMatchObject({
+                id: 'Bob',
+                name: 'Bob',
+                type: 'participant'
+            });
+        });
+        it('should parse participant with multi-word alias', () => {
+            const input = `
+sequenceDiagram
+participant API as API Server
+participant DB as Database System
+API->>DB: Query
+`;
+            const ast = parse(input);
+            const api = ast.participants.find(p => p.id === 'API');
+            expect(api).toBeDefined();
+            expect(api?.name).toBe('API Server');
+        });
+    });
+    describe('Message Definitions', () => {
+        it('should parse sync message and implicit participants', () => {
+            const input = `
+sequenceDiagram
+A->B: Hello
+`;
+            const ast = parse(input);
+            expect(ast.participants).toHaveLength(2);
+            expect(ast.participants).toMatchObject([
+                { id: 'A', name: 'A' },
+                { id: 'B', name: 'B' }
+            ]);
+            expect(ast.events).toHaveLength(1);
+            expect(ast.events[0]).toMatchObject({
+                kind: 'message',
+                from: 'A',
+                to: 'B',
+                text: 'Hello',
+                type: 'sync',
+                style: { line: 'solid', head: 'open' }
+            });
+        });
+        it('should parse various arrow types', () => {
+            const input = `
+sequenceDiagram
+A->>B: Arrow
+A-->>B: Reply Arrow
+A-->B: Dotted Open
+A-xB: Cross
+`;
+            const ast = parse(input);
+            expect(ast.events).toHaveLength(4);
+            const m1 = ast.events[0];
+            const m2 = ast.events[1];
+            const m3 = ast.events[2];
+            const m4 = ast.events[3];
+            // ->> : sync, solid, arrow
+            expect(m1).toMatchObject({
+                kind: 'message',
+                type: 'sync',
+                style: { line: 'solid', head: 'arrow' }
+            });
+            // -->> : reply, dotted, arrow
+            expect(m2).toMatchObject({
+                kind: 'message',
+                type: 'reply',
+                style: { line: 'dotted', head: 'arrow' }
+            });
+            // --> : reply, dotted, open
+            expect(m3).toMatchObject({
+                kind: 'message',
+                type: 'reply',
+                style: { line: 'dotted', head: 'open' }
+            });
+            // -x : destroy, solid, cross
+            expect(m4).toMatchObject({
+                kind: 'message',
+                type: 'destroy',
+                style: { line: 'solid', head: 'cross' }
+            });
+        });
+        it('should parse lifecycle activations in messages', () => {
+            const input = `
+sequenceDiagram
+A->>+B: Activate Target
+B-->>-A: Deactivate Source
+`;
+            const ast = parse(input);
+            const m1 = ast.events[0];
+            const m2 = ast.events[1];
+            if (m1.kind !== 'message' || m2.kind !== 'message') {
+                throw new Error('Expected message events');
+            }
+            expect(m1.lifecycle).toMatchObject({ activateTarget: true, deactivateSource: false });
+            expect(m2.lifecycle).toMatchObject({ activateTarget: false, deactivateSource: true });
+        });
+    });
+    describe('Lifecycle Definitions', () => {
+        it('should parse standalone activate/deactivate', () => {
+            const input = `
+sequenceDiagram
+activate A
+deactivate A
+`;
+            const ast = parse(input);
+            expect(ast.events).toHaveLength(2);
+            expect(ast.events[0]).toMatchObject({ kind: 'activation', participantId: 'A', action: 'activate' });
+            expect(ast.events[1]).toMatchObject({ kind: 'activation', participantId: 'A', action: 'deactivate' });
+        });
+    });
+    describe('Note Definitions', () => {
+        it('should parse note positions', () => {
+            const input = `
+sequenceDiagram
+note left of A: Note Left
+note right of A: Note Right
+note over A: Note Over
+`;
+            const ast = parse(input);
+            expect(ast.events).toHaveLength(3);
+            expect(ast.events[0]).toMatchObject({ kind: 'note', position: 'left', participantIds: ['A'], text: 'Note Left' });
+            expect(ast.events[1]).toMatchObject({ kind: 'note', position: 'right', participantIds: ['A'], text: 'Note Right' });
+            expect(ast.events[2]).toMatchObject({ kind: 'note', position: 'over', participantIds: ['A'], text: 'Note Over' });
+        });
+        it('should parse note over multiple participants', () => {
+            const input = `sequenceDiagram\nnote over A,B: Shared Note`;
+            const ast = parse(input);
+            expect(ast.events[0]).toMatchObject({ kind: 'note', position: 'over', participantIds: ['A', 'B'], text: 'Shared Note' });
+        });
+    });
+    describe('Fragment Definitions', () => {
+        it('should parse loop fragment', () => {
+            const input = `
+sequenceDiagram
+loop Every minute
+  A->B: Check
+end
+`;
+            const ast = parse(input);
+            expect(ast.events).toHaveLength(1);
+            const fragment = ast.events[0];
+            expect(fragment.kind).toBe('fragment');
+            if (fragment.kind !== 'fragment')
+                return; // type guard
+            expect(fragment.operator).toBe('loop');
+            expect(fragment.branches).toHaveLength(1);
+            expect(fragment.branches[0].condition).toBe('Every minute');
+            expect(fragment.branches[0].events).toHaveLength(1);
+            expect(fragment.branches[0].events[0].kind).toBe('message');
+        });
+        it('should parse alt/else fragment', () => {
+            const input = `
+sequenceDiagram
+alt Success
+    A->B: OK
+else Failure
+    A->B: Error
+end
+`;
+            const ast = parse(input);
+            const fragment = ast.events[0];
+            expect(fragment.kind).toBe('fragment');
+            expect(fragment.operator).toBe('alt');
+            expect(fragment.branches).toHaveLength(2);
+            expect(fragment.branches[0].condition).toBe('Success');
+            expect(fragment.branches[0].events).toHaveLength(1);
+            expect(fragment.branches[1].condition).toBe('Failure');
+            expect(fragment.branches[1].events).toHaveLength(1);
+        });
+    });
+    describe('Box/Group Definitions', () => {
+        it('should parse box definition with color and name', () => {
+            const code = `
+  sequenceDiagram
+  box "Frontend" #eef
+      participant A
+      participant B
+  end
+  box Backend
+      participant C
+  end
+  A->>C: Request
+  C-->>A: Response
+      `;
+            const ast = parse(code);
+            // Verify participants
+            expect(ast.participants).toHaveLength(3);
+            expect(ast.participants.map(p => p.id)).toEqual(['A', 'B', 'C']);
+            // Verify groups
+            expect(ast.groups).toHaveLength(2);
+            const group1 = ast.groups[0];
+            expect(group1.name).toContain('Frontend');
+            expect(group1.participantIds).toEqual(['A', 'B']);
+            const group2 = ast.groups[1];
+            expect(group2.name).toBe('Backend');
+            expect(group2.participantIds).toEqual(['C']);
+        });
+        it('should handle messages inside box block', () => {
+            const code = `
+  sequenceDiagram
+  participant U
+  box App
+      participant A
+      U->>A: inside box
+  end
+      `;
+            const ast = parse(code);
+            expect(ast.events).toHaveLength(1);
+            expect(ast.events[0].kind).toBe('message');
+            expect(ast.groups[0].participantIds).toEqual(['A']);
+        });
+    });
+});

package/dist/src/parser/languages/mermaid/tokens.d.ts

@@ -0,0 +1,9 @@
+export type TokenType = 'SEQUENCE_DIAGRAM' | 'NEWLINE' | 'EOF' | 'PARTICIPANT' | 'COLON' | 'IDENTIFIER' | 'STRING' | 'ARROW' | 'LOOP' | 'ALT' | 'OPT' | 'END' | 'ELSE' | 'UNKNOWN' | 'AS' | 'ACTOR' | 'TITLE' | 'NOTE' | 'LEFT' | 'RIGHT' | 'OVER' | 'OF' | 'ACTIVATE' | 'DEACTIVATE' | 'PLUS' | 'MINUS' | 'COMMA' | 'BOX';
+export interface Token {
+    type: TokenType;
+    literal: string;
+    line: number;
+    column: number;
+    start: number;
+    end: number;
+}

package/dist/src/parser/languages/mermaid/tokens.js

@@ -0,0 +1 @@
+export {};

package/dist/src/transformer/cleaners/prune-empty.d.ts

@@ -0,0 +1,9 @@
+import { EventNode, FragmentNode } from '../../ast';
+import { Walker } from '../traverse/walker';
+/**
+ * Cleaner that removes empty fragments and branches from the AST.
+ * This runs after filters to ensure the AST structure remains valid/clean.
+ */
+export declare class StructureCleaner extends Walker {
+    protected visitFragment(node: FragmentNode): EventNode[];
+}

package/dist/src/transformer/cleaners/prune-empty.js

@@ -0,0 +1,27 @@
+import { Walker } from '../traverse/walker';
+/**
+ * Cleaner that removes empty fragments and branches from the AST.
+ * This runs after filters to ensure the AST structure remains valid/clean.
+ */
+export class StructureCleaner extends Walker {
+    visitFragment(node) {
+        // 1. Let super map the branches (recurse)
+        const result = super.visitFragment(node);
+        // Should contain exactly one node (the fragment with mapped branches)
+        if (result.length === 0)
+            return [];
+        const fragment = result[0];
+        // 2. Filter out empty branches
+        // A branch is "empty" if it has 0 events.
+        const validBranches = fragment.branches.filter(b => b.events.length > 0);
+        // 3. Evaluation
+        if (validBranches.length === 0) {
+            return []; // Remove fragment entirely
+        }
+        // Return updated fragment
+        return [{
+                ...fragment,
+                branches: validBranches
+            }];
+    }
+}

package/dist/src/transformer/cleaners/prune-empty.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/transformer/cleaners/prune-empty.test.js

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { StructureCleaner } from './prune-empty';
+describe('StructureCleaner', () => {
+    const createAst = (events) => ({
+        kind: 'root',
+        meta: { version: '1', source: 'unknown' },
+        participants: [],
+        groups: [],
+        events
+    });
+    const msg = {
+        kind: 'message',
+        id: 'm1',
+        text: 'M',
+        from: 'A',
+        to: 'B',
+        type: 'sync',
+        style: { line: 'solid', head: 'arrow' }
+    };
+    it('removes fragment if it has no branches', () => {
+        const fragment = {
+            kind: 'fragment', id: 'f1', operator: 'alt',
+            branches: [] // Empty
+        };
+        const root = createAst([fragment, msg]);
+        const result = new StructureCleaner().transform(root);
+        expect(result.events).toHaveLength(1);
+        expect(result.events[0].id).toBe('m1');
+    });
+    it('removes branch if it has no events', () => {
+        const fragment = {
+            kind: 'fragment', id: 'f1', operator: 'alt',
+            branches: [
+                { id: 'b1', condition: 'C1', events: [] }, // Empty
+                { id: 'b2', condition: 'C2', events: [msg] } // Should keep
+            ]
+        };
+        const root = createAst([fragment]);
+        const result = new StructureCleaner().transform(root);
+        const resFrag = result.events[0];
+        expect(resFrag.branches).toHaveLength(1);
+        expect(resFrag.branches[0].id).toBe('b2');
+    });
+    it('removes fragment if all branches are empty', () => {
+        const fragment = {
+            kind: 'fragment', id: 'f1', operator: 'alt',
+            branches: [
+                { id: 'b1', condition: 'C1', events: [] }
+            ]
+        };
+        const root = createAst([fragment]);
+        const result = new StructureCleaner().transform(root);
+        expect(result.events).toHaveLength(0);
+    });
+    it('recursively cleans nested fragments', () => {
+        const innerFrag = {
+            kind: 'fragment', id: 'inner', operator: 'loop',
+            branches: [{ id: 'ib', condition: 'loop', events: [] }]
+        };
+        const outerFrag = {
+            kind: 'fragment', id: 'outer', operator: 'opt',
+            branches: [{ id: 'ob', condition: 'opt', events: [innerFrag] }]
+        };
+        const root = createAst([outerFrag, msg]);
+        const result = new StructureCleaner().transform(root);
+        expect(result.events).toHaveLength(1);
+        expect(result.events[0].id).toBe('m1');
+    });
+});

package/dist/src/transformer/cleaners/prune-unused.d.ts

@@ -0,0 +1,5 @@
+import { PolagramRoot } from '../../ast';
+export declare class UnusedCleaner {
+    transform(root: PolagramRoot): PolagramRoot;
+    private collectUsedParticipants;
+}

package/dist/src/transformer/cleaners/prune-unused.js

@@ -0,0 +1,48 @@
+export class UnusedCleaner {
+    transform(root) {
+        const usedIds = this.collectUsedParticipants(root.events);
+        // Filter participants
+        const activeParticipants = root.participants.filter(p => usedIds.has(p.id));
+        // Filter groups (remove if empty, clean up member lists)
+        const activeGroups = root.groups.map(g => ({
+            ...g,
+            participantIds: g.participantIds.filter(pid => usedIds.has(pid))
+        })).filter(g => g.participantIds.length > 0);
+        return {
+            ...root,
+            participants: activeParticipants,
+            groups: activeGroups
+        };
+    }
+    collectUsedParticipants(events) {
+        const used = new Set();
+        function scan(nodes) {
+            for (const node of nodes) {
+                switch (node.kind) {
+                    case 'message':
+                        if (node.from)
+                            used.add(node.from);
+                        if (node.to)
+                            used.add(node.to);
+                        break;
+                    case 'fragment':
+                        for (const branch of node.branches) {
+                            scan(branch.events);
+                        }
+                        break;
+                    case 'activation':
+                        used.add(node.participantId);
+                        break;
+                    case 'note':
+                        node.participantIds.forEach(id => used.add(id));
+                        break;
+                    case 'ref':
+                        node.participantIds.forEach(id => used.add(id));
+                        break;
+                }
+            }
+        }
+        scan(events);
+        return used;
+    }
+}

package/dist/src/transformer/cleaners/prune-unused.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/transformer/cleaners/prune-unused.test.js

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { UnusedCleaner } from './prune-unused';
+describe('UnusedCleaner', () => {
+    const createAst = (participants, events) => ({
+        kind: 'root',
+        meta: { version: '1', source: 'unknown' },
+        participants,
+        groups: [],
+        events
+    });
+    it('removes participants that are not referenced in messages', () => {
+        const p1 = { id: 'A', name: 'Alice', type: 'participant' };
+        const p2 = { id: 'B', name: 'Bob', type: 'participant' };
+        const p3 = { id: 'C', name: 'Charlie', type: 'participant' }; // Unused
+        const msg = {
+            kind: 'message', id: 'm1', text: 'Hi', from: 'A', to: 'B',
+            type: 'sync', style: { line: 'solid', head: 'arrow' }
+        };
+        const root = createAst([p1, p2, p3], [msg]);
+        const result = new UnusedCleaner().transform(root);
+        expect(result.participants).toHaveLength(2);
+        expect(result.participants.map(p => p.id)).toEqual(['A', 'B']);
+    });
+    it('keeps participants referenced in activations', () => {
+        const p1 = { id: 'A', name: 'Alice', type: 'participant' };
+        const act = { kind: 'activation', participantId: 'A', action: 'activate' };
+        const root = createAst([p1], [act]);
+        const result = new UnusedCleaner().transform(root);
+        expect(result.participants).toHaveLength(1);
+    });
+    it('keeps participants referenced in notes', () => {
+        const p1 = { id: 'A', name: 'Alice', type: 'participant' };
+        const note = { kind: 'note', id: 'n1', text: 'Note', position: 'over', participantIds: ['A'] };
+        const root = createAst([p1], [note]);
+        const result = new UnusedCleaner().transform(root);
+        expect(result.participants).toHaveLength(1);
+    });
+    it('cleans up groups removing unused members', () => {
+        const p1 = { id: 'A', name: 'Alice', type: 'participant' };
+        const p2 = { id: 'B', name: 'Bob', type: 'participant' }; // Unused
+        const group = { kind: 'group', id: 'g1', name: 'G', participantIds: ['A', 'B'] };
+        const msg = {
+            kind: 'message', id: 'm1', text: 'Hi', from: 'A', to: 'A',
+            type: 'sync', style: { line: 'solid', head: 'arrow' }
+        };
+        const root = {
+            kind: 'root',
+            meta: { version: '1', source: 'unknown' },
+            participants: [p1, p2],
+            groups: [group],
+            events: [msg]
+        };
+        const result = new UnusedCleaner().transform(root);
+        expect(result.participants.map(p => p.id)).toEqual(['A']);
+        expect(result.groups).toHaveLength(1);
+        expect(result.groups[0].participantIds).toEqual(['A']);
+    });
+    it('removes group entirely if becomes empty', () => {
+        const p2 = { id: 'B', name: 'Bob', type: 'participant' }; // Unused
+        const group = { kind: 'group', id: 'g1', name: 'G', participantIds: ['B'] };
+        const root = {
+            kind: 'root',
+            meta: { version: '1', source: 'unknown' },
+            participants: [p2],
+            groups: [group],
+            events: []
+        };
+        const result = new UnusedCleaner().transform(root);
+        expect(result.groups).toHaveLength(0);
+    });
+});

package/dist/src/transformer/filters/focus.d.ts

@@ -0,0 +1,13 @@
+import { EventNode, PolagramRoot } from '../../ast';
+import { Walker } from '../traverse/walker';
+import { FocusLayer } from '../types';
+export declare class FocusFilter extends Walker {
+    private layer;
+    private matcher;
+    private targetParticipantIds;
+    constructor(layer: FocusLayer);
+    transform(root: PolagramRoot): PolagramRoot;
+    private resolveTargetParticipants;
+    protected visitEvent(node: EventNode): EventNode[];
+    private isRelatedToParticipant;
+}

package/dist/src/transformer/filters/focus.js

@@ -0,0 +1,71 @@
+import { Matcher } from '../selector/matcher';
+import { Walker } from '../traverse/walker';
+export class FocusFilter extends Walker {
+    constructor(layer) {
+        super();
+        Object.defineProperty(this, "layer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: layer
+        });
+        Object.defineProperty(this, "matcher", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Matcher()
+        });
+        Object.defineProperty(this, "targetParticipantIds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+    }
+    transform(root) {
+        this.resolveTargetParticipants(root);
+        return super.transform(root);
+    }
+    resolveTargetParticipants(root) {
+        this.targetParticipantIds.clear();
+        const selector = this.layer.selector;
+        root.participants.forEach(p => {
+            if (this.matcher.matchParticipant(p, selector)) {
+                this.targetParticipantIds.add(p.id);
+            }
+        });
+    }
+    visitEvent(node) {
+        // Only apply filtering if we have targets. 
+        // If targets is empty, strictly speaking we should hide everything? 
+        // Yes, "Focus on X" means "Show ONLY X". If X is not found, show nothing.
+        if (node.kind === 'message') {
+            const msg = node;
+            if (!this.isRelatedToParticipant(msg)) {
+                return []; // Drop irrelevant message
+            }
+        }
+        if (node.kind === 'note') {
+            const note = node;
+            const isRelated = note.participantIds.some(pid => this.targetParticipantIds.has(pid));
+            if (!isRelated)
+                return [];
+        }
+        if (node.kind === 'activation') {
+            const activation = node;
+            if (!this.targetParticipantIds.has(activation.participantId)) {
+                return [];
+            }
+        }
+        return super.visitEvent(node);
+    }
+    // Helper to check if message involves the participant from selector
+    isRelatedToParticipant(msg) {
+        // Check if from or to matches any targeted participant ID
+        if (msg.from && this.targetParticipantIds.has(msg.from))
+            return true;
+        if (msg.to && this.targetParticipantIds.has(msg.to))
+            return true;
+        return false;
+    }
+}

package/dist/src/transformer/filters/focus.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/transformer/filters/focus.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { FocusFilter } from './focus';
+describe('FocusFilter', () => {
+    const createAst = (events) => ({
+        kind: 'root',
+        meta: { version: '1', source: 'unknown' },
+        participants: [
+            { id: 'A', name: 'A', type: 'participant' },
+            { id: 'B', name: 'B', type: 'participant' },
+            { id: 'C', name: 'C', type: 'participant' },
+            { id: 'D', name: 'D', type: 'participant' }
+        ],
+        groups: [],
+        events
+    });
+    const msgAB = { kind: 'message', id: 'm1', text: 'A->B', from: 'A', to: 'B', type: 'sync', style: { line: 'solid', head: 'arrow' } };
+    const msgBC = { kind: 'message', id: 'm2', text: 'B->C', from: 'B', to: 'C', type: 'sync', style: { line: 'solid', head: 'arrow' } };
+    const msgCD = { kind: 'message', id: 'm3', text: 'C->D', from: 'C', to: 'D', type: 'sync', style: { line: 'solid', head: 'arrow' } };
+    it('removes messages not related to focused participant', () => {
+        const root = createAst([msgAB, msgBC, msgCD]);
+        const layer = {
+            action: 'focus',
+            selector: { kind: 'participant', name: 'A' }
+        };
+        // Expect: msgAB (involves A), others removed
+        const result = new FocusFilter(layer).transform(root);
+        expect(result.events).toHaveLength(1);
+        expect(result.events[0].id).toBe('m1');
+    });
+    it('removes messages even inside fragments, but keeps structure', () => {
+        const fragment = {
+            kind: 'fragment', id: 'f1', operator: 'alt',
+            branches: [
+                { id: 'b1', condition: 'related', events: [msgAB] },
+                { id: 'b2', condition: 'irrelevant', events: [msgCD] }
+            ]
+        };
+        const root = createAst([fragment]);
+        const layer = {
+            action: 'focus',
+            selector: { kind: 'participant', name: 'A' }
+        };
+        const result = new FocusFilter(layer).transform(root);
+        const resFrag = result.events[0];
+        // b1 should keep event
+        expect(resFrag.branches[0].events).toHaveLength(1);
+        // b2 should have event removed, BUT branch itself remains (empty)
+        expect(resFrag.branches[1].events).toHaveLength(0);
+    });
+});

package/dist/src/transformer/filters/remove.d.ts

@@ -0,0 +1,12 @@
+import { EventNode, PolagramRoot } from '../../ast';
+import { Walker } from '../traverse/walker';
+import { RemoveLayer } from '../types';
+export declare class RemoveFilter extends Walker {
+    private layer;
+    private matcher;
+    private removedParticipantIds;
+    constructor(layer: RemoveLayer);
+    transform(root: PolagramRoot): PolagramRoot;
+    protected visitEvent(node: EventNode): EventNode[];
+    private isRelatedToRemovedParticipant;
+}