@polagram/core 0.0.3 → 0.1.0

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

@@ -1,82 +0,0 @@
-import { Matcher } from '../selector/matcher';
-import { Walker } from '../traverse/walker';
-export class RemoveFilter 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, "removedParticipantIds", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: new Set()
-        });
-    }
-    transform(root) {
-        const selector = this.layer.selector;
-        // 1. Pre-calculate removed participants
-        if (selector.kind === 'participant') {
-            root.participants.forEach(p => {
-                if (this.matcher.matchParticipant(p, selector)) {
-                    this.removedParticipantIds.add(p.id);
-                }
-            });
-            // Also remove the participants from definitions
-            root.participants = root.participants.filter(p => !this.removedParticipantIds.has(p.id));
-        }
-        // 2. Remove Groups
-        if (selector.kind === 'group') {
-            root.groups = root.groups.filter(g => !this.matcher.matchGroup(g, selector));
-        }
-        return super.transform(root);
-    }
-    visitEvent(node) {
-        const selector = this.layer.selector;
-        // A. Remove by Message Selector
-        if (selector.kind === 'message') {
-            if (node.kind === 'message') {
-                if (this.matcher.matchMessage(node, selector)) {
-                    return [];
-                }
-            }
-            // Note: Message selector doesn't apply to other event types
-        }
-        // B. Remove by Participant (Cascade to events)
-        if (selector.kind === 'participant') {
-            if (node.kind === 'message') {
-                const msg = node;
-                if (this.isRelatedToRemovedParticipant(msg))
-                    return [];
-            }
-            if (node.kind === 'note') {
-                const note = node;
-                const isRelated = note.participantIds.some(pid => this.removedParticipantIds.has(pid));
-                if (isRelated)
-                    return [];
-            }
-            if (node.kind === 'activation') {
-                const activation = node;
-                if (this.removedParticipantIds.has(activation.participantId))
-                    return [];
-            }
-        }
-        return super.visitEvent(node);
-    }
-    isRelatedToRemovedParticipant(msg) {
-        if (msg.from && this.removedParticipantIds.has(msg.from))
-            return true;
-        if (msg.to && this.removedParticipantIds.has(msg.to))
-            return true;
-        return false;
-    }
-}

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

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

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

@@ -1,38 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { RemoveFilter } from './remove';
-describe('RemoveFilter', () => {
-    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' }
-        ],
-        groups: [],
-        events
-    });
-    const msgA = { kind: 'message', id: 'm1', text: 'Hello', from: 'A', to: 'B', type: 'sync', style: { line: 'solid', head: 'arrow' } };
-    const msgB = { kind: 'message', id: 'm2', text: 'World', from: 'B', to: 'C', type: 'sync', style: { line: 'solid', head: 'arrow' } };
-    it('removes message by direct selector', () => {
-        const root = createAst([msgA, msgB]);
-        const layer = {
-            action: 'remove',
-            selector: { kind: 'message', text: 'Hello' }
-        };
-        const result = new RemoveFilter(layer).transform(root);
-        expect(result.events).toHaveLength(1);
-        expect(result.events[0].text).toBe('World');
-    });
-    it('removes messages related to removed participant', () => {
-        const root = createAst([msgA, msgB]);
-        // Remove 'C'. msgB involves C (to: C).
-        const layer = {
-            action: 'remove',
-            selector: { kind: 'participant', name: 'C' }
-        };
-        const result = new RemoveFilter(layer).transform(root);
-        expect(result.events).toHaveLength(1);
-        expect(result.events[0].id).toBe('m1');
-    });
-});

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

@@ -1,9 +0,0 @@
-import { EventNode, FragmentNode } from '../../ast';
-import { Walker } from '../traverse/walker';
-import { ResolveLayer } from '../types';
-export declare class ResolveFilter extends Walker {
-    private layer;
-    private matcher;
-    constructor(layer: ResolveLayer);
-    protected visitFragment(node: FragmentNode): EventNode[];
-}

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

@@ -1,32 +0,0 @@
-import { Matcher } from '../selector/matcher';
-import { Walker } from '../traverse/walker';
-export class ResolveFilter 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()
-        });
-    }
-    visitFragment(node) {
-        // 1. Check if ANY branch matches the selector
-        // The layer.selector is a FragmentSelector (which matches branch properties)
-        const matchedBranch = node.branches.find(branch => this.matcher.matchBranch(branch, this.layer.selector, node.operator));
-        if (matchedBranch) {
-            // RESOLVE ACTION:
-            // "Promote" the selected branch by returning its content.
-            // The FragmentNode itself is replaced by these events.
-            return this.mapEvents(matchedBranch.events);
-        }
-        // 2. If no match, behave like default (Keep fragment, recurse into children)
-        return super.visitFragment(node);
-    }
-}

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

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

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

@@ -1,48 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { ResolveFilter } from './resolve';
-describe('ResolveFilter', () => {
-    const createAst = (events) => ({
-        kind: 'root',
-        meta: { version: '1', source: 'unknown' },
-        participants: [],
-        groups: [],
-        events
-    });
-    const msg = { kind: 'message', id: 'm1', text: 'Inside', from: 'A', to: 'B', type: 'sync', style: { line: 'solid', head: 'arrow' } };
-    it('unwraps fragment branch matching selector', () => {
-        const fragment = {
-            kind: 'fragment', id: 'f1', operator: 'alt',
-            branches: [
-                { id: 'b1', condition: 'target', events: [msg] },
-                { id: 'b2', condition: 'other', events: [] }
-            ]
-        };
-        const root = createAst([fragment]);
-        // Unwrap branches with condition 'target'
-        const layer = {
-            action: 'resolve',
-            selector: { kind: 'fragment', condition: 'target' }
-        };
-        const result = new ResolveFilter(layer).transform(root);
-        // Should trigger unwrap: return content of b1
-        expect(result.events).toHaveLength(1);
-        expect(result.events[0].id).toBe('m1');
-    });
-    it('does nothing if no branch matches', () => {
-        const fragment = {
-            kind: 'fragment', id: 'f1', operator: 'alt',
-            branches: [
-                { id: 'b1', condition: 'other', events: [msg] }
-            ]
-        };
-        const root = createAst([fragment]);
-        const layer = {
-            action: 'resolve',
-            selector: { kind: 'fragment', condition: 'nomatch' }
-        };
-        const result = new ResolveFilter(layer).transform(root);
-        // Should keep fragment
-        expect(result.events).toHaveLength(1);
-        expect(result.events[0].kind).toBe('fragment');
-    });
-});

package/dist/src/transformer/index.d.ts

@@ -1,10 +0,0 @@
-export * from './cleaners/prune-empty';
-export * from './cleaners/prune-unused';
-export * from './filters/focus';
-export * from './filters/remove';
-export * from './filters/resolve';
-export * from './lens';
-export * from './orchestration/engine';
-export * from './orchestration/registry';
-export * from './selector/matcher';
-export * from './types';

package/dist/src/transformer/index.js

@@ -1,10 +0,0 @@
-export * from './cleaners/prune-empty';
-export * from './cleaners/prune-unused';
-export * from './filters/focus';
-export * from './filters/remove';
-export * from './filters/resolve';
-export * from './lens';
-export * from './orchestration/engine';
-export * from './orchestration/registry';
-export * from './selector/matcher';
-export * from './types';

package/dist/src/transformer/lens.d.ts

@@ -1,12 +0,0 @@
-import { PolagramRoot } from '../ast';
-import { Lens } from './types';
-/**
- * Type Guard to validate if an object is a valid Lens.
- * Acts as an Anti-Corruption Layer.
- */
-export declare function validateLens(lens: unknown): lens is Lens;
-/**
- * Apply a lens object to the AST.
- * Facade for the TransformationEngine.
- */
-export declare function applyLens(root: PolagramRoot, lens: Lens): PolagramRoot;

package/dist/src/transformer/lens.js

@@ -1,58 +0,0 @@
-import { TransformationEngine } from './orchestration/engine';
-/**
- * Type Guard to validate if an object is a valid Lens.
- * Acts as an Anti-Corruption Layer.
- */
-export function validateLens(lens) {
-    if (typeof lens !== 'object' || lens === null) {
-        return false;
-    }
-    const l = lens;
-    // Check name (optional string)
-    if (Reflect.has(l, 'name') && typeof l.name !== 'string') {
-        return false;
-    }
-    // Check layers (required array)
-    if (!Array.isArray(l.layers)) {
-        return false;
-    }
-    // Validate each layer
-    for (const layer of l.layers) {
-        if (!validateLayer(layer)) {
-            return false;
-        }
-    }
-    return true;
-}
-function validateLayer(layer) {
-    if (typeof layer !== 'object' || layer === null) {
-        return false;
-    }
-    const l = layer;
-    // Check action
-    if (typeof l.action !== 'string') {
-        return false;
-    }
-    const validActions = ['focus', 'remove', 'resolve'];
-    if (!validActions.includes(l.action)) {
-        return false;
-    }
-    // Check selector
-    if (typeof l.selector !== 'object' || l.selector === null) {
-        return false;
-    }
-    // Simple check for selector structure
-    const s = l.selector;
-    if (typeof s.kind !== 'string') {
-        return false;
-    }
-    return true;
-}
-/**
- * Apply a lens object to the AST.
- * Facade for the TransformationEngine.
- */
-export function applyLens(root, lens) {
-    const engine = new TransformationEngine();
-    return engine.transform(root, lens.layers);
-}

package/dist/src/transformer/lens.test.d.ts

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

package/dist/src/transformer/lens.test.js

@@ -1,60 +0,0 @@
-import yaml from 'js-yaml';
-import { describe, expect, it } from 'vitest';
-import { applyLens, validateLens } from './lens';
-describe('Lens API', () => {
-    describe('validateLens', () => {
-        it('should return true for valid lens object', () => {
-            const valid = {
-                name: 'Test Lens',
-                layers: [
-                    { action: 'focus', selector: { kind: 'participant', name: 'Bob' } }
-                ]
-            };
-            expect(validateLens(valid)).toBe(true);
-        });
-        it('should return false for invalid structure', () => {
-            expect(validateLens(null)).toBe(false);
-            expect(validateLens({ name: 123 })).toBe(false); // Invalid name
-            expect(validateLens({ layers: 'not-array' })).toBe(false);
-        });
-        it('should return false for invalid rule action', () => {
-            const invalid = {
-                layers: [{ action: 'destroyWorld', selector: { kind: 'participant' } }]
-            };
-            expect(validateLens(invalid)).toBe(false);
-        });
-    });
-    describe('Integration with js-yaml (Usage Layer)', () => {
-        it('should parse YAML and apply lens correctly', () => {
-            const yamlStr = `
-name: My Transformation
-layers:
-  - action: focus
-    selector:
-      kind: participant
-      name: Bob
-`;
-            // 1. Adapter Layer: Parse YAML
-            const parsed = yaml.load(yamlStr);
-            // 2. Anti-Corruption Layer: Validate
-            if (!validateLens(parsed)) {
-                throw new Error('Validation failed');
-            }
-            // 3. Facade: Apply
-            // Mocking a simple AST
-            const mockRoot = {
-                kind: 'root',
-                meta: { version: '1.0', source: 'mermaid', title: 'test' },
-                participants: [
-                    { id: 'Bob', name: 'Bob', type: 'participant' }
-                ],
-                groups: [],
-                events: [],
-            };
-            const result = applyLens(mockRoot, parsed);
-            // Just verifying it runs without error and returns an AST (Transformation logic is tested elsewhere)
-            expect(result).toBeDefined();
-            expect(result.kind).toBe('root');
-        });
-    });
-});

package/dist/src/transformer/orchestration/engine.d.ts

@@ -1,5 +0,0 @@
-import { PolagramRoot } from '../../ast';
-import { Layer } from '../types';
-export declare class TransformationEngine {
-    transform(root: PolagramRoot, layers: Layer[]): PolagramRoot;
-}

package/dist/src/transformer/orchestration/engine.js

@@ -1,24 +0,0 @@
-import { StructureCleaner } from '../cleaners/prune-empty';
-import { UnusedCleaner } from '../cleaners/prune-unused';
-import { transformerRegistry } from './registry';
-export class TransformationEngine {
-    transform(root, layers) {
-        let currentAst = root;
-        // Phase 1: Layers (User Intent)
-        for (const layer of layers) {
-            const transformer = transformerRegistry.get(layer);
-            if (transformer) {
-                currentAst = transformer.transform(currentAst);
-            }
-            else {
-                console.warn(`Unknown action: ${layer.action}`);
-            }
-        }
-        // Phase 2: Cleaners (Integrity Assurance)
-        // 2-1. Structure Cleaner (Prune empty branches)
-        currentAst = new StructureCleaner().transform(currentAst);
-        // 2-2. Unused Cleaner (Prune unused definitions)
-        currentAst = new UnusedCleaner().transform(currentAst);
-        return currentAst;
-    }
-}

package/dist/src/transformer/orchestration/engine.test.d.ts

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

package/dist/src/transformer/orchestration/engine.test.js

@@ -1,41 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { TransformationEngine } from './engine';
-describe('TransformationEngine (Pipeline Integration)', () => {
-    const createAst = (participants, events) => ({
-        kind: 'root',
-        meta: { version: '1', source: 'unknown' },
-        participants,
-        groups: [],
-        events
-    });
-    const msgAB = { kind: 'message', id: 'm1', text: 'A->B', from: 'A0', to: 'B0', type: 'sync', style: { line: 'solid', head: 'arrow' } };
-    const msgCD = { kind: 'message', id: 'm2', text: 'C->D', from: 'C0', to: 'D0', type: 'sync', style: { line: 'solid', head: 'arrow' } };
-    // Participants
-    const pA = { id: 'A0', name: 'A', type: 'participant' };
-    const pB = { id: 'B0', name: 'B', type: 'participant' };
-    const pC = { id: 'C0', name: 'C', type: 'participant' };
-    const pD = { id: 'D0', name: 'D', type: 'participant' };
-    it('runs FocusParticipant -> StructureCleaner pipeline correctly', () => {
-        const fragment = {
-            kind: 'fragment', id: 'f1', operator: 'alt',
-            branches: [
-                { id: 'b1', condition: 'keep', events: [msgAB] },
-                { id: 'b2', condition: 'drop', events: [msgCD] }
-            ]
-        };
-        const root = createAst([pA, pB, pC, pD], [fragment]);
-        // Rule: Focus A. (Should keep msgAB, remove msgCD)
-        const layer = {
-            action: 'focus',
-            selector: { kind: 'participant', name: 'A' }
-        };
-        const result = new TransformationEngine().transform(root, [layer]);
-        // 1. Filter (Focus) should have cleared events in b2 but left empty branch
-        // 2. Cleaner (Structure) should have removed b2
-        const resFrag = result.events[0];
-        expect(resFrag.branches).toHaveLength(1);
-        expect(resFrag.branches[0].id).toBe('b1'); // b2 is gone
-        // 3. Cleaner (Unused) should have removed C and D
-        expect(result.participants.map(p => p.id).sort()).toEqual(['A0', 'B0']);
-    });
-});

package/dist/src/transformer/orchestration/registry.d.ts

@@ -1,10 +0,0 @@
-import { Layer, Transformer } from '../types';
-type TransformerFactory = (layer: Layer) => Transformer;
-declare class TransformerRegistry {
-    private factories;
-    constructor();
-    register(action: string, factory: TransformerFactory): void;
-    get(layer: Layer): Transformer | null;
-}
-export declare const transformerRegistry: TransformerRegistry;
-export {};

package/dist/src/transformer/orchestration/registry.js

@@ -1,27 +0,0 @@
-import { FocusFilter } from '../filters/focus';
-import { RemoveFilter } from '../filters/remove';
-import { ResolveFilter } from '../filters/resolve';
-class TransformerRegistry {
-    constructor() {
-        Object.defineProperty(this, "factories", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: new Map()
-        });
-        // Register defaults
-        this.register('resolve', (layer) => new ResolveFilter(layer));
-        this.register('focus', (layer) => new FocusFilter(layer));
-        this.register('remove', (layer) => new RemoveFilter(layer));
-    }
-    register(action, factory) {
-        this.factories.set(action, factory);
-    }
-    get(layer) {
-        const factory = this.factories.get(layer.action);
-        if (!factory)
-            return null;
-        return factory(layer);
-    }
-}
-export const transformerRegistry = new TransformerRegistry();

package/dist/src/transformer/selector/matcher.d.ts

@@ -1,9 +0,0 @@
-import { FragmentBranch, FragmentOperator, MessageNode, Participant, ParticipantGroup } from '../../ast';
-import { FragmentSelector, GroupSelector, MessageSelector, ParticipantSelector } from '../types';
-export declare class Matcher {
-    matchBranch(branch: FragmentBranch, selector: FragmentSelector, parentOperator: FragmentOperator): boolean;
-    matchParticipant(node: Participant, selector: ParticipantSelector): boolean;
-    matchMessage(node: MessageNode, selector: MessageSelector): boolean;
-    matchGroup(node: ParticipantGroup, selector: GroupSelector): boolean;
-    private matchText;
-}

package/dist/src/transformer/selector/matcher.js

@@ -1,62 +0,0 @@
-export class Matcher {
-    // -- Branch / Fragment --
-    matchBranch(branch, selector, parentOperator) {
-        // 1. Match Operator (e.g., "loop", "alt")
-        if (selector.operator) {
-            const ops = Array.isArray(selector.operator) ? selector.operator : [selector.operator];
-            if (!ops.includes(parentOperator))
-                return false;
-        }
-        // 2. Match Condition Text (e.g., "Success")
-        if (selector.condition) {
-            if (!branch.condition)
-                return false;
-            if (!this.matchText(branch.condition, selector.condition))
-                return false;
-        }
-        return true;
-    }
-    // -- Participant --
-    matchParticipant(node, selector) {
-        if (selector.id && !this.matchText(node.id, selector.id))
-            return false;
-        if (selector.name && !this.matchText(node.name, selector.name))
-            return false;
-        if (selector.stereotype && node.stereotype && !this.matchText(node.stereotype, selector.stereotype))
-            return false;
-        return true;
-    }
-    // -- Message --
-    matchMessage(node, selector) {
-        if (selector.text && !this.matchText(node.text, selector.text))
-            return false;
-        // Note: from/to in selector are TextMatchers, so we match against node.from/to (IDs)
-        // Ideally this should resolve IDs from Names if possible, but for now we look at raw fields.
-        if (selector.from && node.from && !this.matchText(node.from, selector.from))
-            return false;
-        if (selector.to && node.to && !this.matchText(node.to, selector.to))
-            return false;
-        return true;
-    }
-    // -- Group --
-    matchGroup(node, selector) {
-        if (selector.name && node.name && !this.matchText(node.name, selector.name))
-            return false;
-        return true;
-    }
-    // -- Helpers --
-    matchText(actual, matcher) {
-        if (typeof matcher === 'string') {
-            return actual === matcher; // Default: Exact match
-        }
-        if (matcher instanceof RegExp) {
-            return matcher.test(actual);
-        }
-        if (typeof matcher === 'object' && matcher.pattern) {
-            const flags = matcher.flags || '';
-            const regex = new RegExp(matcher.pattern, flags);
-            return regex.test(actual);
-        }
-        return false;
-    }
-}

package/dist/src/transformer/selector/matcher.test.d.ts

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

package/dist/src/transformer/selector/matcher.test.js

@@ -1,53 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { Matcher } from './matcher';
-describe('Matcher', () => {
-    const matcher = new Matcher();
-    describe('Text Matching', () => {
-        // We test via matchParticipant since matchText is private
-        it('matches string as exact match', () => {
-            const p = { type: 'participant', name: 'UserLogService', id: 'p1' };
-            expect(matcher.matchParticipant(p, { kind: 'participant', name: 'UserLogService' })).toBe(true);
-            expect(matcher.matchParticipant(p, { kind: 'participant', name: 'Log' })).toBe(false);
-        });
-        it('matches RegExp', () => {
-            const p = { type: 'participant', name: 'UserLogService', id: 'p1' };
-            expect(matcher.matchParticipant(p, { kind: 'participant', name: /Log/ })).toBe(true);
-            expect(matcher.matchParticipant(p, { kind: 'participant', name: /^User/ })).toBe(true);
-            expect(matcher.matchParticipant(p, { kind: 'participant', name: /^Service/ })).toBe(false);
-        });
-        it('matches Serializable Object', () => {
-            const p = { type: 'participant', name: 'UserLogService', id: 'p1' };
-            expect(matcher.matchParticipant(p, { kind: 'participant', name: { pattern: 'Log' } })).toBe(true);
-            expect(matcher.matchParticipant(p, { kind: 'participant', name: { pattern: '^user', flags: 'i' } })).toBe(true);
-        });
-    });
-    describe('Participant Matching', () => {
-        it('matches by ID', () => {
-            const p = { type: 'participant', name: 'User', id: 'user_01' };
-            expect(matcher.matchParticipant(p, { kind: 'participant', id: 'user_01' })).toBe(true);
-            expect(matcher.matchParticipant(p, { kind: 'participant', id: 'other' })).toBe(false);
-        });
-    });
-    describe('Message Matching', () => {
-        const msg = {
-            kind: 'message',
-            text: 'Login Request',
-            from: 'user',
-            to: 'api',
-            id: 'm1',
-            type: 'sync',
-            style: {
-                line: 'solid',
-                head: 'arrow'
-            }
-        };
-        it('matches by text', () => {
-            expect(matcher.matchMessage(msg, { kind: 'message', text: 'Login Request' })).toBe(true);
-            expect(matcher.matchMessage(msg, { kind: 'message', text: 'Login' })).toBe(false);
-        });
-        it('matches by from/to', () => {
-            expect(matcher.matchMessage(msg, { kind: 'message', from: 'user' })).toBe(true);
-            expect(matcher.matchMessage(msg, { kind: 'message', to: 'db' })).toBe(false);
-        });
-    });
-});

package/dist/src/transformer/traverse/walker.d.ts

@@ -1,14 +0,0 @@
-import { EventNode, FragmentBranch, FragmentNode, PolagramRoot } from '../../ast';
-/**
- * Abstract base class for tree transformations.
- * Implements the "Updating Visitor" pattern with Copy-on-Write immutability.
- *
- * Subclasses should override `visitEvent` to apply specific logic.
- */
-export declare abstract class Walker {
-    transform(root: PolagramRoot): PolagramRoot;
-    protected mapEvents(events: EventNode[]): EventNode[];
-    protected visitEvent(node: EventNode): EventNode[];
-    protected visitFragment(node: FragmentNode): EventNode[];
-    protected visitBranch(branch: FragmentBranch): FragmentBranch;
-}