@polagram/core 0.0.2

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

@@ -0,0 +1,119 @@
+/**
+ * Polagram Abstract Syntax Tree (AST) Definitions
+ *
+ * Designed to be a lossless representation of Sequence Diagrams from:
+ * - Mermaid
+ * - PlantUML
+ *
+ * It captures structure, semantics (lifecycle, grouping), and necessary visual hints.
+ */
+export interface PolagramRoot {
+    kind: 'root';
+    meta: MetaData;
+    participants: Participant[];
+    groups: ParticipantGroup[];
+    events: EventNode[];
+}
+export interface MetaData {
+    version: string;
+    source: 'mermaid' | 'plantuml' | 'unknown';
+    title?: string;
+    theme?: Record<string, string>;
+}
+export interface Participant {
+    id: string;
+    name: string;
+    alias?: string;
+    type: ParticipantType;
+    stereotype?: string;
+    style?: StyleProps;
+}
+export type ParticipantType = 'participant' | 'actor' | 'boundary' | 'control' | 'entity' | 'database' | 'collections' | 'queue';
+export interface ParticipantGroup {
+    kind: 'group';
+    id: string;
+    name?: string;
+    type?: string;
+    participantIds: string[];
+    style?: StyleProps;
+}
+export type EventNode = MessageNode | FragmentNode | NoteNode | DividerNode | ActivationNode | ReferenceNode | SpacerNode;
+export type MessageEndpoint = string | null;
+/**
+ * Represents a directional interaction.
+ * Includes standard sync/async calls, returns, and object creation/deletion.
+ */
+export interface MessageNode {
+    kind: 'message';
+    id: string;
+    from: MessageEndpoint;
+    to: MessageEndpoint;
+    text: string;
+    type: 'sync' | 'async' | 'reply' | 'create' | 'destroy';
+    style: {
+        line: 'solid' | 'dotted';
+        head: 'arrow' | 'async' | 'open' | 'cross';
+        color?: string;
+    };
+    lifecycle?: {
+        activateTarget?: boolean;
+        deactivateSource?: boolean;
+    };
+}
+export interface FragmentNode {
+    kind: 'fragment';
+    id: string;
+    operator: FragmentOperator;
+    branches: FragmentBranch[];
+}
+export type FragmentOperator = 'alt' | 'opt' | 'loop' | 'par' | 'break' | 'critical' | 'rect' | 'group';
+export interface FragmentBranch {
+    id: string;
+    condition?: string;
+    events: EventNode[];
+}
+export interface NoteNode {
+    kind: 'note';
+    id: string;
+    text: string;
+    position: 'left' | 'right' | 'over';
+    participantIds: string[];
+    style?: StyleProps;
+}
+/**
+ * Independent activation/deactivation not tied to a specific message line.
+ * e.g., Mermaid "activate A", PlantUML "activate A"
+ */
+export interface ActivationNode {
+    kind: 'activation';
+    participantId: string;
+    action: 'activate' | 'deactivate';
+    style?: StyleProps;
+}
+/**
+ * Refers to another sequence diagram or a frame covering participants.
+ * e.g., PlantUML "ref over A, B : Init"
+ */
+export interface ReferenceNode {
+    kind: 'ref';
+    id: string;
+    text: string;
+    participantIds: string[];
+    link?: string;
+}
+export interface DividerNode {
+    kind: 'divider';
+    id: string;
+    text?: string;
+}
+export interface SpacerNode {
+    kind: 'spacer';
+    id: string;
+    height?: number;
+    text?: string;
+}
+export interface StyleProps {
+    color?: string;
+    backgroundColor?: string;
+    shape?: string;
+}

package/dist/src/ast/index.js

@@ -0,0 +1,2 @@
+// packages/core/src/ast.ts
+export {};

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

@@ -0,0 +1 @@
+export * from './schema';

package/dist/src/config/index.js

@@ -0,0 +1 @@
+export * from './schema';

package/dist/src/config/schema.d.ts

@@ -0,0 +1,182 @@
+import { z } from 'zod';
+declare const LensSchema: z.ZodObject<{
+    name: z.ZodString;
+    suffix: z.ZodOptional<z.ZodString>;
+    layers: z.ZodArray<z.ZodObject<{
+        action: z.ZodEnum<{
+            resolve: "resolve";
+            focus: "focus";
+            remove: "remove";
+        }>;
+        selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"fragment">;
+            condition: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+            operator: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"participant">;
+            name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+            id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+            stereotype: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"message">;
+            text: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+            from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+            to: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"group">;
+            name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const TargetConfigSchema: z.ZodObject<{
+    input: z.ZodArray<z.ZodString>;
+    outputDir: z.ZodString;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    lenses: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        suffix: z.ZodOptional<z.ZodString>;
+        layers: z.ZodArray<z.ZodObject<{
+            action: z.ZodEnum<{
+                resolve: "resolve";
+                focus: "focus";
+                remove: "remove";
+            }>;
+            selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"fragment">;
+                condition: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+                operator: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"participant">;
+                name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+                id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+                stereotype: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"message">;
+                text: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+                from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+                to: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"group">;
+                name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>], "kind">;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const PolagramConfigSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    targets: z.ZodArray<z.ZodObject<{
+        input: z.ZodArray<z.ZodString>;
+        outputDir: z.ZodString;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        lenses: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            suffix: z.ZodOptional<z.ZodString>;
+            layers: z.ZodArray<z.ZodObject<{
+                action: z.ZodEnum<{
+                    resolve: "resolve";
+                    focus: "focus";
+                    remove: "remove";
+                }>;
+                selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"fragment">;
+                    condition: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                    operator: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"participant">;
+                    name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                    id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                    stereotype: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"message">;
+                    text: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                    from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                    to: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"group">;
+                    name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>], "kind">;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PolagramConfig = z.infer<typeof PolagramConfigSchema>;
+export type TargetConfig = z.infer<typeof TargetConfigSchema>;
+export type LensConfig = z.infer<typeof LensSchema>;
+/**
+ * Validates the input object against the Polagram Config Schema.
+ * Throws a formatted error message if validation fails.
+ */
+export declare function validateConfig(input: unknown): PolagramConfig;
+export {};

package/dist/src/config/schema.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+// -- Text Matcher --
+const TextMatcherSchema = z.union([
+    z.string(),
+    z.object({
+        pattern: z.string(),
+        flags: z.string().optional()
+    })
+]);
+// -- Selectors --
+// Explicitly requiring 'kind' for all selectors
+const FragmentSelectorSchema = z.object({
+    kind: z.literal('fragment'),
+    condition: TextMatcherSchema.optional(),
+    operator: z.union([z.string(), z.array(z.string())]).optional()
+    // Note: Operator types might need to be refined if we want strict enum validation, 
+    // but string is flexible for now.
+});
+const ParticipantSelectorSchema = z.object({
+    kind: z.literal('participant'),
+    name: TextMatcherSchema.optional(),
+    id: TextMatcherSchema.optional(),
+    stereotype: TextMatcherSchema.optional()
+});
+const MessageSelectorSchema = z.object({
+    kind: z.literal('message'),
+    text: TextMatcherSchema.optional(),
+    from: TextMatcherSchema.optional(),
+    to: TextMatcherSchema.optional()
+});
+const GroupSelectorSchema = z.object({
+    kind: z.literal('group'),
+    name: TextMatcherSchema.optional()
+});
+const SelectorSchema = z.discriminatedUnion('kind', [
+    FragmentSelectorSchema,
+    ParticipantSelectorSchema,
+    MessageSelectorSchema,
+    GroupSelectorSchema
+]);
+// -- Layers --
+const ActionSchema = z.enum(['focus', 'remove', 'resolve']);
+const LayerSchema = z.object({
+    action: ActionSchema,
+    selector: SelectorSchema
+});
+// -- Lens --
+const LensSchema = z.object({
+    name: z.string(),
+    suffix: z.string().optional(), // Defaults to .name in logic
+    layers: z.array(LayerSchema)
+});
+// -- Config --
+const TargetConfigSchema = z.object({
+    input: z.array(z.string()),
+    outputDir: z.string(),
+    ignore: z.array(z.string()).optional(),
+    lenses: z.array(LensSchema)
+});
+export const PolagramConfigSchema = z.object({
+    version: z.number(),
+    targets: z.array(TargetConfigSchema)
+});
+/**
+ * Validates the input object against the Polagram Config Schema.
+ * Throws a formatted error message if validation fails.
+ */
+export function validateConfig(input) {
+    const result = PolagramConfigSchema.safeParse(input);
+    if (!result.success) {
+        const errorMessages = result.error.issues.map(issue => {
+            const path = issue.path.join('.');
+            return `[${path}]: ${issue.message}`;
+        }).join('\n');
+        throw new Error(`Invalid Polagram Configuration:\n${errorMessages}`);
+    }
+    return result.data;
+}

package/dist/src/config/schema.test.d.ts

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

package/dist/src/config/schema.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import { validateConfig } from './schema';
+describe('Config Schema Validation', () => {
+    it('should validate a correct configuration', () => {
+        const input = {
+            version: 1,
+            targets: [
+                {
+                    input: ['src/*.mmd'],
+                    outputDir: 'dist',
+                    lenses: [
+                        {
+                            name: 'Success',
+                            layers: [
+                                {
+                                    action: 'resolve',
+                                    selector: { kind: 'fragment', condition: 'Success' }
+                                }
+                            ]
+                        }
+                    ]
+                }
+            ]
+        };
+        const config = validateConfig(input);
+        expect(config.version).toBe(1);
+        expect(config.targets[0].lenses[0].name).toBe('Success');
+    });
+    it('should throw error for missing required fields', () => {
+        const input = {
+            // missing version
+            targets: []
+        };
+        expect(() => validateConfig(input)).toThrow('Invalid Polagram Configuration');
+        // Zod message might vary, just checking it fails is often enough, 
+        // but let's check for the path at least.
+        expect(() => validateConfig(input)).toThrow('[version]:');
+    });
+    it('should validate fragment selector correctly', () => {
+        const input = {
+            version: 1,
+            targets: [{
+                    input: ['src/*.mmd'],
+                    outputDir: 'dist',
+                    lenses: [{
+                            name: 'Test',
+                            layers: [{
+                                    action: 'focus',
+                                    selector: { kind: 'fragment', condition: 'Success' }
+                                }]
+                        }]
+                }]
+        };
+        expect(() => validateConfig(input)).not.toThrow();
+    });
+    it('should fail if selector kind is missing', () => {
+        const input = {
+            version: 1,
+            targets: [{
+                    input: ['src/*.mmd'],
+                    outputDir: 'dist',
+                    lenses: [{
+                            name: 'Test',
+                            layers: [{
+                                    action: 'focus',
+                                    selector: { condition: 'Success' } // Missing kind: 'fragment'
+                                }]
+                        }]
+                }]
+        };
+        // Expect failure because checking against union requires discrimination
+        expect(() => validateConfig(input)).toThrow();
+    });
+    it('should validate participant selector with complex matcher', () => {
+        const input = {
+            version: 1,
+            targets: [{
+                    input: ['src/*.mmd'],
+                    outputDir: 'dist',
+                    lenses: [{
+                            name: 'Test',
+                            layers: [{
+                                    action: 'focus',
+                                    selector: {
+                                        kind: 'participant',
+                                        name: { pattern: 'User.*', flags: 'i' }
+                                    }
+                                }]
+                        }]
+                }]
+        };
+        expect(() => validateConfig(input)).not.toThrow();
+    });
+});

package/dist/src/generator/base/walker.d.ts

@@ -0,0 +1,19 @@
+import { EventNode, PolagramRoot } from '../../ast';
+import { PolagramVisitor } from '../interface';
+/**
+ * Helper class to traverse AST nodes and dispatch to the visitor.
+ */
+export declare class Traverser {
+    private visitor;
+    constructor(visitor: PolagramVisitor);
+    traverse(root: PolagramRoot): void;
+    /**
+     * Dispatches a single event node to the appropriate visitor method.
+     * This is public so Visitors can call it recursively (e.g. inside Fragments/Groups).
+     */
+    dispatchEvent(node: EventNode): void;
+    /**
+     * Helper to iterate over a list of events.
+     */
+    dispatchEvents(events: EventNode[]): void;
+}

package/dist/src/generator/base/walker.js

@@ -0,0 +1,56 @@
+/**
+ * Helper class to traverse AST nodes and dispatch to the visitor.
+ */
+export class Traverser {
+    constructor(visitor) {
+        Object.defineProperty(this, "visitor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: visitor
+        });
+    }
+    traverse(root) {
+        this.visitor.visitRoot(root);
+    }
+    /**
+     * Dispatches a single event node to the appropriate visitor method.
+     * This is public so Visitors can call it recursively (e.g. inside Fragments/Groups).
+     */
+    dispatchEvent(node) {
+        switch (node.kind) {
+            case 'message':
+                this.visitor.visitMessage(node);
+                break;
+            case 'fragment':
+                this.visitor.visitFragment(node);
+                break;
+            case 'note':
+                this.visitor.visitNote(node);
+                break;
+            case 'activation':
+                this.visitor.visitActivation(node);
+                break;
+            case 'divider':
+                this.visitor.visitDivider(node);
+                break;
+            case 'spacer':
+                this.visitor.visitSpacer(node);
+                break;
+            case 'ref':
+                this.visitor.visitReference(node);
+                break;
+            default:
+                // Unknown node type
+                break;
+        }
+    }
+    /**
+     * Helper to iterate over a list of events.
+     */
+    dispatchEvents(events) {
+        for (const event of events) {
+            this.dispatchEvent(event);
+        }
+    }
+}

package/dist/src/generator/base/walker.test.d.ts

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

package/dist/src/generator/base/walker.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Traverser } from './walker';
+describe('Traverser', () => {
+    it('should dispatch visitRoot', () => {
+        const mockVisitor = {
+            visitRoot: vi.fn(),
+            visitParticipant: vi.fn(),
+            visitParticipantGroup: vi.fn(),
+            visitMessage: vi.fn(),
+            visitFragment: vi.fn(),
+            visitNote: vi.fn(),
+            visitActivation: vi.fn(),
+            visitDivider: vi.fn(),
+            visitSpacer: vi.fn(),
+            visitReference: vi.fn()
+        };
+        const traverser = new Traverser(mockVisitor);
+        const root = { kind: 'root', meta: { version: '1.0.0', source: 'unknown' }, participants: [], groups: [], events: [] };
+        traverser.traverse(root);
+        expect(mockVisitor.visitRoot).toHaveBeenCalledWith(root);
+    });
+    it('should dispatch events based on kind', () => {
+        const mockVisitor = {
+            visitRoot: vi.fn(), // Root visitor might internally call dispatchEvents
+            visitParticipant: vi.fn(),
+            visitParticipantGroup: vi.fn(),
+            visitMessage: vi.fn(),
+            visitFragment: vi.fn(),
+            visitNote: vi.fn(),
+            visitActivation: vi.fn(),
+            visitDivider: vi.fn(),
+            visitSpacer: vi.fn(),
+            visitReference: vi.fn()
+        };
+        const traverser = new Traverser(mockVisitor);
+        const msg = {
+            kind: 'message',
+            id: '1',
+            from: 'A',
+            to: 'B',
+            text: 'hi',
+            type: 'sync',
+            style: { line: 'solid', head: 'arrow' }
+        };
+        // Directly call dispatchEvents (as if called from visitRoot implementation)
+        traverser.dispatchEvents([msg]);
+        expect(mockVisitor.visitMessage).toHaveBeenCalledWith(msg);
+    });
+});

package/dist/src/generator/generators/mermaid.d.ts

@@ -0,0 +1,24 @@
+import { ActivationNode, DividerNode, FragmentNode, MessageNode, NoteNode, Participant, ParticipantGroup, PolagramRoot, ReferenceNode, SpacerNode } from '../../ast';
+import { PolagramVisitor } from '../interface';
+/**
+ * Visitor implementation that generates Mermaid code.
+ */
+export declare class MermaidGeneratorVisitor implements PolagramVisitor {
+    private lines;
+    private indentLevel;
+    private traverser;
+    constructor();
+    generate(ast: PolagramRoot): string;
+    visitRoot(node: PolagramRoot): void;
+    visitParticipant(node: Participant): void;
+    visitParticipantGroup(node: ParticipantGroup): void;
+    visitMessage(node: MessageNode): void;
+    visitFragment(node: FragmentNode): void;
+    visitNote(node: NoteNode): void;
+    visitActivation(node: ActivationNode): void;
+    visitDivider(node: DividerNode): void;
+    visitSpacer(node: SpacerNode): void;
+    visitReference(node: ReferenceNode): void;
+    private add;
+    private indent;
+}