@polagram/core 0.0.3 → 0.0.4

package/dist/src/api.js

@@ -1,4 +1,5 @@
 import { MermaidGeneratorVisitor } from './generator/generators/mermaid';
+import { PlantUMLGeneratorVisitor } from './generator/generators/plantuml';
 import { ParserFactory } from './parser';
 import { TransformationEngine } from './transformer/orchestration/engine';
 /**
@@ -17,19 +18,19 @@ export class Polagram {
     /**
      * Initialize a new Polagram transformation pipeline.
      * @param code Source diagram code
-     * @param format Input format (currently only 'mermaid' is supported)
+     * @param format Input format ('mermaid' or 'plantuml')
      */
     static init(code, format = 'mermaid') {
         const parser = ParserFactory.getParser(format);
         const ast = parser.parse(code);
-        return new PolagramBuilder(ast);
+        return new PolagramBuilder(ast, format);
     }
 }
 /**
  * Builder class for chaining transformations.
  */
 export class PolagramBuilder {
-    constructor(ast) {
+    constructor(ast, sourceFormat = 'mermaid') {
         Object.defineProperty(this, "ast", {
             enumerable: true,
             configurable: true,
@@ -42,7 +43,14 @@ export class PolagramBuilder {
             writable: true,
             value: []
         });
+        Object.defineProperty(this, "sourceFormat", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.ast = ast;
+        this.sourceFormat = sourceFormat;
     }
     // -- Entity Filtering --
     /**
@@ -122,6 +130,15 @@ export class PolagramBuilder {
         const generator = new MermaidGeneratorVisitor();
         return generator.generate(transformedAst);
     }
+    /**
+     * Generate PlantUML code from the transformed AST.
+     */
+    toPlantUML() {
+        const engine = new TransformationEngine();
+        const transformedAst = engine.transform(this.ast, this.layers);
+        const generator = new PlantUMLGeneratorVisitor();
+        return generator.generate(transformedAst);
+    }
     /**
      * Get the transformed AST (for advanced use cases).
      */
@@ -129,6 +146,12 @@ export class PolagramBuilder {
         const engine = new TransformationEngine();
         return engine.transform(this.ast, this.layers);
     }
+    /**
+     * Get the source format detected/specified during init.
+     */
+    getSourceFormat() {
+        return this.sourceFormat;
+    }
     // -- Helper Methods --
     normalizeParticipantSelector(selector) {
         if (this.isTextMatcher(selector)) {

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

@@ -109,6 +109,14 @@ declare const TargetConfigSchema: z.ZodObject<{
             }, z.core.$strip>], "kind">;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    format: z.ZodOptional<z.ZodEnum<{
+        mermaid: "mermaid";
+        plantuml: "plantuml";
+    }>>;
+    outputFormat: z.ZodOptional<z.ZodEnum<{
+        mermaid: "mermaid";
+        plantuml: "plantuml";
+    }>>;
 }, z.core.$strip>;
 export declare const PolagramConfigSchema: z.ZodObject<{
     version: z.ZodNumber;
@@ -169,6 +177,14 @@ export declare const PolagramConfigSchema: z.ZodObject<{
                 }, z.core.$strip>], "kind">;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        format: z.ZodOptional<z.ZodEnum<{
+            mermaid: "mermaid";
+            plantuml: "plantuml";
+        }>>;
+        outputFormat: z.ZodOptional<z.ZodEnum<{
+            mermaid: "mermaid";
+            plantuml: "plantuml";
+        }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PolagramConfig = z.infer<typeof PolagramConfigSchema>;

package/dist/src/config/schema.js

@@ -50,12 +50,16 @@ const LensSchema = z.object({
     suffix: z.string().optional(), // Defaults to .name in logic
     layers: z.array(LayerSchema)
 });
+// -- Format --
+const DiagramFormatSchema = z.enum(['mermaid', 'plantuml']);
 // -- Config --
 const TargetConfigSchema = z.object({
     input: z.array(z.string()),
     outputDir: z.string(),
     ignore: z.array(z.string()).optional(),
-    lenses: z.array(LensSchema)
+    lenses: z.array(LensSchema),
+    format: DiagramFormatSchema.optional(), // Input format (auto-detected if omitted)
+    outputFormat: DiagramFormatSchema.optional() // Output format (same as input if omitted)
 });
 export const PolagramConfigSchema = z.object({
     version: z.number(),

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

@@ -0,0 +1,17 @@
+import { ActivationNode, DividerNode, FragmentNode, MessageNode, NoteNode, Participant, ParticipantGroup, PolagramRoot, ReferenceNode, SpacerNode } from '../../ast';
+import { PolagramVisitor } from '../interface';
+export declare class PlantUMLGeneratorVisitor implements PolagramVisitor {
+    generate(root: PolagramRoot): string;
+    visitRoot(node: PolagramRoot): string;
+    visitParticipant(node: Participant): string;
+    visitGroup(node: ParticipantGroup, context?: Map<string, Participant>): string;
+    visitMessage(node: MessageNode): string;
+    visitFragment(node: FragmentNode): string;
+    private visitEvent;
+    visitNote(node: NoteNode): string;
+    visitActivation(node: ActivationNode): string;
+    visitParticipantGroup(_node: ParticipantGroup): string;
+    visitDivider(_node: DividerNode): string;
+    visitSpacer(_node: SpacerNode): string;
+    visitReference(_node: ReferenceNode): string;
+}

package/dist/src/generator/generators/plantuml.js

@@ -0,0 +1,131 @@
+export class PlantUMLGeneratorVisitor {
+    generate(root) {
+        return this.visitRoot(root);
+    }
+    visitRoot(node) {
+        const lines = ['@startuml'];
+        if (node.meta.title) {
+            lines.push(`title ${node.meta.title}`);
+        }
+        const participantsMap = new Map(node.participants.map(p => [p.id, p]));
+        const groupedParticipantIds = new Set();
+        // Groups
+        for (const group of node.groups) {
+            lines.push(this.visitGroup(group, participantsMap));
+            group.participantIds.forEach(id => groupedParticipantIds.add(id));
+        }
+        // Ungrouped Participants
+        for (const participant of node.participants) {
+            if (!groupedParticipantIds.has(participant.id)) {
+                lines.push(this.visitParticipant(participant));
+            }
+        }
+        // Events
+        for (const event of node.events) {
+            lines.push(this.visitEvent(event));
+        }
+        lines.push('@enduml');
+        return lines.join('\n');
+    }
+    visitParticipant(node) {
+        // If Name == ID, use concise format: "type ID"
+        // Otherwise use explicit format: "type "Name" as ID"
+        if (node.name === node.id) {
+            return `${node.type} ${node.id}`;
+        }
+        return `${node.type} "${node.name}" as ${node.id}`;
+    }
+    // Adjusted signature to pass context
+    visitGroup(node, context) {
+        const parts = [];
+        const color = node.style?.backgroundColor ? ` ${node.style.backgroundColor}` : '';
+        const title = node.name ? ` "${node.name}"` : '';
+        parts.push(`box${title}${color}`);
+        if (context) {
+            for (const pid of node.participantIds) {
+                const p = context.get(pid);
+                if (p) {
+                    parts.push(this.visitParticipant(p));
+                }
+            }
+        }
+        parts.push('end box');
+        return parts.join('\n');
+    }
+    visitMessage(node) {
+        const from = node.from || '[*]'; // Handle lost/found if needed
+        const to = node.to || '[*]';
+        let arrow = '->';
+        if (node.type === 'reply')
+            arrow = '-->';
+        else if (node.type === 'async')
+            arrow = '->>'; // PlantUML doesn't strictly distinguish async arrow head generally, but ->> is fine
+        // style override
+        if (node.style.line === 'dotted') {
+            // If reply, already --> (dotted). If sync but dotted: A -[dotted]-> B ?
+            // PlantUML: A ..> B
+            // But --> is usually standard reply.
+        }
+        return `${from} ${arrow} ${to}: ${node.text}`;
+    }
+    visitFragment(node) {
+        const lines = [];
+        const op = node.operator;
+        node.branches.forEach((branch, index) => {
+            if (index === 0) {
+                lines.push(`${op} ${branch.condition || ''}`.trim());
+            }
+            else {
+                lines.push(`else ${branch.condition || ''}`.trim());
+            }
+            for (const event of branch.events) {
+                // We need to recursively visit events (messages, nested fragments, etc.)
+                // But we can't easily call visitX because we don't know the type statically here or need a centralized dispatcher that returns string.
+                // But wait, visitRoot has a dispatcher. We should extract it to `visitEvent`.
+                // For now, let's duplicate the relevant dispatch logic or creating a helper.
+                lines.push(this.visitEvent(event));
+            }
+        });
+        lines.push('end');
+        return lines.join('\n');
+    }
+    visitEvent(event) {
+        switch (event.kind) {
+            case 'message': return this.visitMessage(event);
+            case 'fragment': return this.visitFragment(event);
+            case 'note': return this.visitNote(event);
+            case 'activation': return this.visitActivation(event);
+            case 'divider': return this.visitDivider(event);
+            case 'spacer': return this.visitSpacer(event);
+            case 'ref': return this.visitReference(event);
+            default: return '';
+        }
+    }
+    visitNote(node) {
+        const position = node.position || 'over';
+        const participants = node.participantIds.join(', ');
+        // note left of A: Text
+        // note over A, B: Text
+        // For 'over', we don't say 'of' in standard examples? "note over Alice", "note over Alice, Bob"
+        // But 'left of', 'right of' use 'of'.
+        const positionStr = (position === 'left' || position === 'right') ? `${position} of` : position;
+        return `note ${positionStr} ${participants}: ${node.text}`;
+    }
+    visitActivation(node) {
+        // activate A
+        // deactivate A
+        return `${node.action} ${node.participantId}`;
+    }
+    visitParticipantGroup(_node) {
+        return '';
+    }
+    visitDivider(_node) {
+        return '';
+    }
+    visitSpacer(_node) {
+        return '';
+    }
+    visitReference(_node) {
+        return '';
+    }
+}

package/dist/src/generator/generators/plantuml.test.d.ts

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

package/dist/src/generator/generators/plantuml.test.js

@@ -0,0 +1,143 @@
+import { describe, expect, it } from 'vitest';
+import { PlantUMLGeneratorVisitor } from './plantuml';
+describe('PlantUML Generator', () => {
+    const generator = new PlantUMLGeneratorVisitor();
+    it('should generate basic document structure', () => {
+        const ast = {
+            kind: 'root',
+            meta: { version: '1.0.0', source: 'plantuml', title: 'My Diagram' },
+            participants: [],
+            groups: [],
+            events: []
+        };
+        const code = generator.generate(ast);
+        expect(code).toContain('@startuml');
+        expect(code).toContain('title My Diagram');
+        expect(code).toContain('@enduml');
+    });
+    it('should generate participants', () => {
+        const ast = {
+            kind: 'root',
+            meta: { version: '1.0.0', source: 'plantuml' },
+            participants: [
+                { id: 'User', name: 'User', type: 'actor' },
+                { id: 'DB', name: 'DB', type: 'database' },
+                { id: 'Svc', name: 'Service', type: 'participant' }
+            ],
+            groups: [],
+            events: []
+        };
+        const code = generator.generate(ast);
+        expect(code).toContain('actor User');
+        expect(code).toContain('database DB');
+        expect(code).toContain('participant "Service" as Svc');
+    });
+    it('should generate messages', () => {
+        const ast = {
+            kind: 'root',
+            meta: { version: '1.0.0', source: 'plantuml' },
+            participants: [
+                { id: 'A', name: 'A', type: 'participant' },
+                { id: 'B', name: 'B', type: 'participant' }
+            ],
+            groups: [],
+            events: [
+                { kind: 'message', id: 'm1', from: 'A', to: 'B', text: 'Sync', type: 'sync', style: { line: 'solid', head: 'arrow' } },
+                { kind: 'message', id: 'm2', from: 'B', to: 'A', text: 'Reply', type: 'reply', style: { line: 'dotted', head: 'arrow' } },
+                { kind: 'message', id: 'm3', from: 'A', to: 'A', text: 'Self', type: 'sync', style: { line: 'solid', head: 'arrow' } }
+            ]
+        };
+        const code = generator.generate(ast);
+        expect(code).toContain('A -> B: Sync');
+        expect(code).toContain('B --> A: Reply');
+        expect(code).toContain('A -> A: Self');
+    });
+    it('should generate fragments', () => {
+        const ast = {
+            kind: 'root',
+            meta: { version: '1.0.0', source: 'plantuml' },
+            participants: [],
+            groups: [],
+            events: [
+                {
+                    kind: 'fragment',
+                    id: 'f1',
+                    operator: 'alt',
+                    branches: [
+                        { id: 'b1', condition: 'success', events: [
+                                { kind: 'message', id: 'm1', from: 'A', to: 'B', text: 'OK', type: 'sync', style: { line: 'solid', head: 'arrow' } }
+                            ] },
+                        { id: 'b2', condition: 'failure', events: [
+                                { kind: 'message', id: 'm2', from: 'A', to: 'B', text: 'Fail', type: 'sync', style: { line: 'solid', head: 'arrow' } }
+                            ] }
+                    ]
+                }
+            ]
+        };
+        const code = generator.generate(ast);
+        expect(code).toContain('alt success');
+        expect(code).toContain('A -> B: OK');
+        expect(code).toContain('else failure');
+        expect(code).toContain('A -> B: Fail');
+        expect(code).toContain('end');
+    });
+    it('should generate notes', () => {
+        const ast = {
+            kind: 'root',
+            meta: { version: '1.0.0', source: 'plantuml' },
+            participants: [
+                { id: 'A', name: 'A', type: 'participant' }
+            ],
+            groups: [],
+            events: [
+                { kind: 'note', id: 'n1', text: 'My Note', position: 'right', participantIds: ['A'] },
+                { kind: 'note', id: 'n2', text: 'Over Note', position: 'over', participantIds: ['A'] }
+            ]
+        };
+        const code = generator.generate(ast);
+        expect(code).toContain('note right of A: My Note');
+        expect(code).toContain('note over A: Over Note');
+    });
+    it('should generate lifecycle events', () => {
+        const ast = {
+            kind: 'root',
+            meta: { version: '1.0.0', source: 'plantuml' },
+            participants: [
+                { id: 'A', name: 'A', type: 'participant' }
+            ],
+            groups: [],
+            events: [
+                { kind: 'activation', participantId: 'A', action: 'activate' },
+                // Some message presumably
+                { kind: 'activation', participantId: 'A', action: 'deactivate' }
+            ]
+        };
+        const code = generator.generate(ast);
+        expect(code).toContain('activate A');
+        expect(code).toContain('deactivate A');
+    });
+    it('should generate groups', () => {
+        const ast = {
+            kind: 'root',
+            meta: { version: '1.0.0', source: 'plantuml' },
+            participants: [
+                { id: 'A', name: 'A', type: 'participant' },
+                { id: 'B', name: 'B', type: 'participant' },
+                { id: 'C', name: 'C', type: 'participant' }
+            ],
+            groups: [
+                { kind: 'group', id: 'g1', name: 'Box1', type: 'box', participantIds: ['A', 'B'], style: { backgroundColor: '#LightBlue' } }
+            ],
+            events: []
+        };
+        const code = generator.generate(ast);
+        // Expect Box1 to contain A and B
+        // C should be outside
+        // Exact order depends on implementation, but box should be there
+        expect(code).toContain('box "Box1" #LightBlue');
+        expect(code).toContain('participant A');
+        expect(code).toContain('participant B');
+        expect(code).toContain('end box');
+        expect(code).toContain('participant C');
+    });
+});

package/dist/src/index.d.ts

@@ -1,9 +1,13 @@
 export * from './ast';
 export { ParserFactory } from './parser';
+export { FormatDetector } from './parser/format-detector';
+export type { DiagramFormat } from './parser/format-detector';
 export type { DiagramParser } from './parser/interface';
 export { Traverser } from './generator/base/walker';
 export type { PolagramVisitor } from './generator/interface';
+export * from './config/schema';
 export { MermaidGeneratorVisitor } from './generator/generators/mermaid';
+export { PlantUMLGeneratorVisitor } from './generator/generators/plantuml';
 export * from './transformer';
 export { Polagram, PolagramBuilder } from './api';
 export * from './config';

package/dist/src/index.js

@@ -3,11 +3,15 @@
 export * from './ast';
 // Parsers (Factory & Strategy)
 export { ParserFactory } from './parser';
+export { FormatDetector } from './parser/format-detector';
 // Generators
 export { Traverser } from './generator/base/walker';
 // Default Implementations (Optional, or force users to use Factory)
 // We export Mermaid Generator specifically as it might be used directly or via a future Factory
+// Config & Validation
+export * from './config/schema';
 export { MermaidGeneratorVisitor } from './generator/generators/mermaid';
+export { PlantUMLGeneratorVisitor } from './generator/generators/plantuml';
 // Transformation Engine
 export * from './transformer';
 // Fluent API (Recommended for most users)

package/dist/src/parser/base/lexer.d.ts

@@ -1,5 +1,5 @@
-import { Token } from '../languages/mermaid/tokens';
-export declare abstract class BaseLexer {
+import { BaseToken } from './token';
+export declare abstract class BaseLexer<T extends BaseToken = BaseToken> {
     protected input: string;
     protected position: number;
     protected readPosition: number;
@@ -8,7 +8,7 @@ export declare abstract class BaseLexer {
     protected column: number;
     constructor(input: string);
     getInput(): string;
-    abstract nextToken(): Token;
+    abstract nextToken(): T;
     protected readChar(): void;
     protected peekChar(): string;
     protected skipWhitespace(): void;

package/dist/src/parser/base/parser.d.ts

@@ -1,14 +1,14 @@
 import { PolagramRoot } from '../../ast';
-import { Token, TokenType } from '../languages/mermaid/tokens';
 import { BaseLexer } from './lexer';
-export declare abstract class BaseParser {
-    protected lexer: BaseLexer;
-    protected currToken: Token;
-    protected peekToken: Token;
-    constructor(lexer: BaseLexer);
+import { BaseToken } from './token';
+export declare abstract class BaseParser<T extends BaseToken = BaseToken> {
+    protected lexer: BaseLexer<T>;
+    protected currToken: T;
+    protected peekToken: T;
+    constructor(lexer: BaseLexer<T>);
     protected advance(): void;
     abstract parse(): PolagramRoot;
-    protected curTokenIs(t: TokenType): boolean;
-    protected peekTokenIs(t: TokenType): boolean;
-    protected expectPeek(t: TokenType): boolean;
+    protected curTokenIs(t: string): boolean;
+    protected peekTokenIs(t: string): boolean;
+    protected expectPeek(t: string): boolean;
 }

package/dist/src/parser/base/token.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Base token interface that all token types should extend.
+ * Represents a lexical token with position information.
+ */
+export interface BaseToken {
+    /** Token type identifier */
+    type: string;
+    /** Literal string value of the token */
+    literal: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Column number (0-indexed) */
+    column: number;
+    /** Start position in source (0-indexed) */
+    start: number;
+    /** End position in source (0-indexed) */
+    end: number;
+}

package/dist/src/parser/base/token.js

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

package/dist/src/parser/base/tokens.d.ts

@@ -0,0 +1,8 @@
+export interface BaseToken {
+    type: string;
+    literal: string;
+    line: number;
+    column: number;
+    start: number;
+    end: number;
+}

package/dist/src/parser/base/tokens.js

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

package/dist/src/parser/format-detector.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Supported diagram formats
+ */
+export type DiagramFormat = 'mermaid' | 'plantuml';
+/**
+ * Format detection utilities for diagram source code.
+ * Detects diagram format based on file extension and content analysis.
+ */
+export declare class FormatDetector {
+    /**
+     * File extensions mapped to their diagram formats
+     */
+    private static readonly EXTENSION_MAP;
+    /**
+     * Content patterns for format detection
+     */
+    private static readonly CONTENT_PATTERNS;
+    /**
+     * Detect diagram format from file path and content.
+     *
+     * @param filePath - Path to the diagram file
+     * @param content - Content of the diagram file
+     * @returns Detected format, or null if format cannot be determined
+     *
+     * @example
+     * ```typescript
+     * const format = FormatDetector.detect('diagram.puml', content);
+     * if (format === 'plantuml') {
+     *   // Process as PlantUML
+     * }
+     * ```
+     */
+    static detect(filePath: string, content: string): DiagramFormat | null;
+    /**
+     * Detect format based on file extension.
+     *
+     * @param filePath - Path to the diagram file
+     * @returns Detected format, or null if extension is not recognized
+     */
+    static detectByExtension(filePath: string): DiagramFormat | null;
+    /**
+     * Detect format based on content patterns.
+     *
+     * @param content - Content of the diagram file
+     * @returns Detected format, or null if no pattern matches
+     */
+    static detectByContent(content: string): DiagramFormat | null;
+    /**
+     * Get file extension for a given format.
+     *
+     * @param format - Diagram format
+     * @returns Default file extension for the format
+     */
+    static getDefaultExtension(format: DiagramFormat): string;
+}