@polagram/core 0.0.2

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

@@ -0,0 +1,140 @@
+import { getArrowString } from '../../parser/languages/mermaid/constants';
+import { Traverser } from '../base/walker';
+/**
+ * Visitor implementation that generates Mermaid code.
+ */
+export class MermaidGeneratorVisitor {
+    constructor() {
+        Object.defineProperty(this, "lines", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "indentLevel", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "traverser", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.traverser = new Traverser(this);
+    }
+    generate(ast) {
+        this.lines = [];
+        this.indentLevel = 0;
+        this.traverser.traverse(ast);
+        return this.lines.join('\n');
+    }
+    visitRoot(node) {
+        this.lines.push('sequenceDiagram');
+        this.indentLevel++;
+        if (node.meta?.title) {
+            this.add(`title ${node.meta.title}`);
+        }
+        // Participants
+        // Note: We iterate participants in defined order. 
+        // Currently, AST does not preserve the interleaving of Box definitions and Participants,
+        // so we cannot reliably reconstruct Box blocks wrapping specific ordered participants
+        // without potentially reordering them. 
+        // For now, we revert to simple iteration (ignoring boxes) to preserve order and existing behavior.
+        for (const p of node.participants) {
+            this.visitParticipant(p);
+        }
+        // Events
+        this.traverser.dispatchEvents(node.events);
+    }
+    visitParticipant(node) {
+        const typeKeyword = node.type === 'actor' ? 'actor' : 'participant';
+        const safeName = node.name;
+        if (node.id === node.name) {
+            this.add(`${typeKeyword} ${node.id}`);
+        }
+        else {
+            this.add(`${typeKeyword} ${node.id} as ${safeName}`);
+        }
+    }
+    visitParticipantGroup(node) {
+        let line = `box`;
+        if (node.style?.backgroundColor) {
+            line += ` ${node.style.backgroundColor}`;
+        }
+        if (node.name) {
+            line += ` ${node.name}`;
+        }
+        this.add(line);
+    }
+    visitMessage(node) {
+        const from = node.from ?? '[*]';
+        const to = node.to ?? '[*]';
+        const arrow = getArrowString(node.type, node.style);
+        let suffix = '';
+        if (node.lifecycle?.activateTarget) {
+            suffix += '+';
+        }
+        if (node.lifecycle?.deactivateSource) {
+            suffix += '-';
+        }
+        this.add(`${from}${arrow}${suffix}${to}: ${node.text}`);
+    }
+    visitFragment(node) {
+        if (node.branches.length === 0)
+            return;
+        const first = node.branches[0];
+        const firstCondition = first.condition ? ` ${first.condition}` : '';
+        this.add(`${node.operator}${firstCondition}`);
+        this.indent(() => {
+            this.traverser.dispatchEvents(first.events);
+        });
+        for (let i = 1; i < node.branches.length; i++) {
+            const b = node.branches[i];
+            const cond = b.condition ? ` ${b.condition}` : '';
+            this.add(`else${cond}`);
+            this.indent(() => {
+                this.traverser.dispatchEvents(b.events);
+            });
+        }
+        this.add('end');
+    }
+    visitNote(node) {
+        const pos = node.position;
+        let target = '';
+        if (node.participantIds.length > 0) {
+            target = node.participantIds.join(',');
+            if (pos !== 'over') {
+                target = ` of ${target}`;
+            }
+            else {
+                target = ` ${target}`;
+            }
+        }
+        this.add(`note ${pos}${target}: ${node.text}`);
+    }
+    visitActivation(node) {
+        this.add(`${node.action} ${node.participantId}`);
+    }
+    visitDivider(node) {
+        this.add(`%% == ${node.text || ''} ==`);
+    }
+    visitSpacer(node) {
+        this.add(`...${node.text || ''}...`);
+    }
+    visitReference(node) {
+        this.add(`%% ref: ${node.text}`);
+    }
+    // --- Helpers ---
+    add(line) {
+        const spaces = '    '.repeat(this.indentLevel);
+        this.lines.push(`${spaces}${line}`);
+    }
+    indent(fn) {
+        this.indentLevel++;
+        fn();
+        this.indentLevel--;
+    }
+}

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

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

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

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { MermaidGeneratorVisitor } from './mermaid';
+describe('MermaidGeneratorVisitor', () => {
+    it('should generate sequence diagram header', () => {
+        const root = { kind: 'root', meta: { version: '1.0.0', source: 'mermaid' }, participants: [], groups: [], events: [] };
+        const visitor = new MermaidGeneratorVisitor();
+        const output = visitor.generate(root);
+        expect(output).toContain('sequenceDiagram');
+    });
+    it('should generate title if present', () => {
+        const root = { kind: 'root', meta: { version: '1.0.0', source: 'mermaid', title: 'My Diagram' }, participants: [], groups: [], events: [] };
+        const visitor = new MermaidGeneratorVisitor();
+        const output = visitor.generate(root);
+        expect(output).toContain('title My Diagram');
+    });
+    it('should generate participants', () => {
+        const root = {
+            kind: 'root',
+            meta: { version: '1.0.0', source: 'mermaid' },
+            participants: [
+                { id: 'A', name: 'Alice', type: 'participant' },
+                { id: 'B', name: 'Bob', type: 'actor' }
+            ],
+            groups: [],
+            events: []
+        };
+        const visitor = new MermaidGeneratorVisitor();
+        const output = visitor.generate(root);
+        expect(output).toContain('participant A as Alice');
+        expect(output).toContain('actor B as Bob');
+    });
+    it('should generate participant with multi-word name without extra quotes', () => {
+        const root = {
+            kind: 'root',
+            meta: { version: '1.0.0', source: 'mermaid' },
+            participants: [
+                { id: 'API', name: 'API Server', type: 'participant' }
+            ],
+            groups: [],
+            events: []
+        };
+        const visitor = new MermaidGeneratorVisitor();
+        const output = visitor.generate(root);
+        // We expect it NOT to be quoted if the user wants clean text
+        // But currently it IS quoted. checking what it does now vs what we want.
+        // If we want to fix it, we should expect "API Server" plain.
+        expect(output).toContain('participant API as API Server');
+    });
+    it('should generate messages', () => {
+        const msg = {
+            kind: 'message',
+            id: '1',
+            from: 'A',
+            to: 'B',
+            text: 'hello',
+            type: 'sync',
+            style: { line: 'solid', head: 'arrow' }
+        };
+        const root = {
+            kind: 'root',
+            meta: { version: '1.0.0', source: 'mermaid' },
+            participants: [],
+            groups: [],
+            events: [msg]
+        };
+        const visitor = new MermaidGeneratorVisitor();
+        const output = visitor.generate(root);
+        expect(output).toContain('A->>B: hello');
+    });
+});

package/dist/src/generator/interface.d.ts

@@ -0,0 +1,17 @@
+import { ActivationNode, DividerNode, FragmentNode, MessageNode, NoteNode, Participant, ParticipantGroup, PolagramRoot, ReferenceNode, SpacerNode } from '../ast';
+/**
+ * Visitor interface for traversing the Polagram AST.
+ * Implement this interface to create code generators, validators, etc.
+ */
+export interface PolagramVisitor {
+    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;
+}

package/dist/src/generator/interface.js

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

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+export * from './ast';
+export { ParserFactory } from './parser';
+export type { DiagramParser } from './parser/interface';
+export { Traverser } from './generator/base/walker';
+export type { PolagramVisitor } from './generator/interface';
+export { MermaidGeneratorVisitor } from './generator/generators/mermaid';
+export * from './transformer';
+export { Polagram, PolagramBuilder } from './api';
+export * from './config';

package/dist/src/index.js

@@ -0,0 +1,17 @@
+// Public API Exports
+// AST
+export * from './ast';
+// Parsers (Factory & Strategy)
+export { ParserFactory } from './parser';
+// 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
+export { MermaidGeneratorVisitor } from './generator/generators/mermaid';
+// Transformation Engine
+export * from './transformer';
+// Fluent API (Recommended for most users)
+export { Polagram, PolagramBuilder } from './api';
+// Legacy compatibility or convenience helpers could go here if needed.
+// Configuration & Schema
+export * from './config';

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

@@ -0,0 +1,18 @@
+import { Token } from '../languages/mermaid/tokens';
+export declare abstract class BaseLexer {
+    protected input: string;
+    protected position: number;
+    protected readPosition: number;
+    protected ch: string;
+    protected line: number;
+    protected column: number;
+    constructor(input: string);
+    getInput(): string;
+    abstract nextToken(): Token;
+    protected readChar(): void;
+    protected peekChar(): string;
+    protected skipWhitespace(): void;
+    protected readWhile(predicate: (ch: string) => boolean): string;
+    protected isLetter(ch: string): boolean;
+    protected isDigit(ch: string): boolean;
+}

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

@@ -0,0 +1,95 @@
+export class BaseLexer {
+    constructor(input) {
+        Object.defineProperty(this, "input", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: input
+        });
+        Object.defineProperty(this, "position", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "readPosition", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "ch", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ''
+        });
+        Object.defineProperty(this, "line", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 1
+        });
+        Object.defineProperty(this, "column", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        this.readChar();
+    }
+    getInput() {
+        return this.input;
+    }
+    readChar() {
+        if (this.readPosition >= this.input.length) {
+            this.ch = '';
+        }
+        else {
+            this.ch = this.input[this.readPosition];
+        }
+        this.position = this.readPosition;
+        this.readPosition += 1;
+        this.column += 1;
+        if (this.ch === '\n') {
+            this.line += 1;
+            this.column = 0;
+        }
+    }
+    peekChar() {
+        if (this.readPosition >= this.input.length) {
+            return '';
+        }
+        return this.input[this.readPosition];
+    }
+    skipWhitespace() {
+        while (this.ch === ' ' || this.ch === '\t' || this.ch === '\r') {
+            this.readChar();
+        }
+    }
+    readWhile(predicate) {
+        const position = this.position;
+        while (predicate(this.ch)) {
+            this.readChar();
+        }
+        return this.input.slice(position, this.position);
+    }
+    isLetter(ch) {
+        // Support ASCII letters and underscore
+        if (('a' <= ch && ch <= 'z') || ('A' <= ch && ch <= 'Z') || ch === '_') {
+            return true;
+        }
+        // Support Unicode letters (including Japanese, Chinese, Korean, etc.)
+        // This uses a simple check: if the character code is > 127 (non-ASCII)
+        // and it's not a digit or whitespace, treat it as a letter
+        const code = ch.charCodeAt(0);
+        if (code > 127) {
+            // Exclude Unicode digits and whitespace
+            return !/[\s\d]/.test(ch);
+        }
+        return false;
+    }
+    isDigit(ch) {
+        return '0' <= ch && ch <= '9';
+    }
+}

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

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

package/dist/src/parser/base/lexer.test.js

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { BaseLexer } from './lexer';
+// Concrete implementation for testing abstract class
+class TestLexer extends BaseLexer {
+    nextToken() {
+        this.skipWhitespace();
+        if (this.readPosition > this.input.length) { // fixed EOF logic for test, check base-lexer readChar behavior
+            // BaseLexer: readPosition moves past End.
+            return { type: 'EOF', literal: '', line: this.line, column: this.column, start: this.position, end: this.position };
+        }
+        const char = this.ch;
+        const start = this.position;
+        this.readChar();
+        return {
+            type: 'UNKNOWN', // Dummy type
+            literal: char,
+            line: this.line,
+            column: this.column,
+            start,
+            end: this.position
+        };
+    }
+    // Expose protected methods for testing
+    testReadIdentifier() { return this.readWhile(c => this.isLetter(c)); }
+    testIsDigit(c) { return this.isDigit(c); }
+    testIsLetter(c) { return this.isLetter(c); }
+    getChar() { return this.ch; }
+}
+describe('BaseLexer', () => {
+    it('should initialize correctly', () => {
+        const input = "abc";
+        const lexer = new TestLexer(input);
+        expect(lexer.getInput()).toBe(input);
+        expect(lexer.getChar()).toBe('a');
+    });
+    it('should identify digits', () => {
+        const lexer = new TestLexer("");
+        expect(lexer.testIsDigit('1')).toBe(true);
+        expect(lexer.testIsDigit('a')).toBe(false);
+    });
+    it('should identify letters', () => {
+        const lexer = new TestLexer("");
+        expect(lexer.testIsLetter('a')).toBe(true);
+        expect(lexer.testIsLetter('_')).toBe(true);
+        expect(lexer.testIsLetter('1')).toBe(false);
+    });
+    it('should read characters while predicate matches', () => {
+        const lexer = new TestLexer("abc 123");
+        const ident = lexer.testReadIdentifier();
+        expect(ident).toBe("abc");
+        expect(lexer.getChar()).toBe(" "); // Stops at space
+    });
+});

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

@@ -0,0 +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);
+    protected advance(): void;
+    abstract parse(): PolagramRoot;
+    protected curTokenIs(t: TokenType): boolean;
+    protected peekTokenIs(t: TokenType): boolean;
+    protected expectPeek(t: TokenType): boolean;
+}

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

@@ -0,0 +1,43 @@
+export class BaseParser {
+    constructor(lexer) {
+        Object.defineProperty(this, "lexer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: lexer
+        });
+        Object.defineProperty(this, "currToken", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "peekToken", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.advance();
+        this.advance();
+    }
+    advance() {
+        this.currToken = this.peekToken;
+        this.peekToken = this.lexer.nextToken();
+    }
+    curTokenIs(t) {
+        return this.currToken.type === t;
+    }
+    peekTokenIs(t) {
+        return this.peekToken.type === t;
+    }
+    expectPeek(t) {
+        if (this.peekTokenIs(t)) {
+            this.advance();
+            return true;
+        }
+        else {
+            return false;
+        }
+    }
+}

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

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

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

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import { BaseLexer } from './lexer';
+import { BaseParser } from './parser';
+// Mocks
+class MockLexer extends BaseLexer {
+    constructor(tokens) {
+        super("");
+        Object.defineProperty(this, "tokens", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "index", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        this.tokens = tokens;
+    }
+    nextToken() {
+        if (this.index >= this.tokens.length) {
+            return { type: 'EOF', literal: '', line: 0, column: 0, start: 0, end: 0 };
+        }
+        return this.tokens[this.index++];
+    }
+}
+class TestParser extends BaseParser {
+    parse() {
+        return { kind: 'root', meta: { version: '1.0.0', source: 'unknown' }, participants: [], groups: [], events: [] };
+    }
+    // Expose protected methods
+    getCurr() { return this.currToken; }
+    getPeek() { return this.peekToken; }
+    testAdvance() { this.advance(); }
+    testCurTokenIs(t) { return this.curTokenIs(t); }
+    testPeakTokenIs(t) { return this.peekTokenIs(t); }
+    testExpectPeek(t) { return this.expectPeek(t); }
+}
+describe('BaseParser', () => {
+    const tokens = [
+        { type: 'IDENTIFIER', literal: 'A', line: 1, column: 0, start: 0, end: 1 },
+        { type: 'ARROW', literal: '->', line: 1, column: 1, start: 1, end: 3 },
+        { type: 'IDENTIFIER', literal: 'B', line: 1, column: 3, start: 3, end: 4 },
+    ];
+    it('should initialize curr and peek tokens', () => {
+        const lexer = new MockLexer(tokens);
+        const parser = new TestParser(lexer);
+        // Constructor called advance twice.
+        // 1st advance: curr=undefined, peek=Tokens[0]
+        // 2nd advance: curr=Tokens[0], peek=Tokens[1]
+        expect(parser.getCurr().type).toBe('IDENTIFIER');
+        expect(parser.getCurr().literal).toBe('A');
+        expect(parser.getPeek().type).toBe('ARROW');
+    });
+    it('should advance tokens', () => {
+        const lexer = new MockLexer(tokens);
+        const parser = new TestParser(lexer);
+        parser.testAdvance();
+        // curr=Tokens[1] (ARROW), peek=Tokens[2] (IDENTIFIER B)
+        expect(parser.getCurr().type).toBe('ARROW');
+        expect(parser.getPeek().type).toBe('IDENTIFIER');
+    });
+    it('should check current and peek token types', () => {
+        const lexer = new MockLexer(tokens);
+        const parser = new TestParser(lexer);
+        expect(parser.testCurTokenIs('IDENTIFIER')).toBe(true);
+        expect(parser.testPeakTokenIs('ARROW')).toBe(true);
+        expect(parser.testPeakTokenIs('EOF')).toBe(false);
+    });
+    it('should expect peek token and advance if match', () => {
+        const lexer = new MockLexer(tokens);
+        const parser = new TestParser(lexer);
+        // Peek is ARROW. Expect ARROW should likely succeed?
+        // Method signature: expectPeek(t). If peek matches, advance and return true.
+        const result = parser.testExpectPeek('ARROW');
+        expect(result).toBe(true);
+        // After advance, curr is ARROW.
+        expect(parser.getCurr().type).toBe('ARROW');
+    });
+    it('should expect peek token and return false if mismatch', () => {
+        const lexer = new MockLexer(tokens);
+        const parser = new TestParser(lexer);
+        const result = parser.testExpectPeek('EOF'); // Peek is ARROW
+        expect(result).toBe(false);
+        // Should not have advanced
+        expect(parser.getCurr().type).toBe('IDENTIFIER');
+    });
+});

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

@@ -0,0 +1,10 @@
+import { DiagramParser } from './interface';
+/**
+ * Parser Factory
+ * Centralizes retrieval of parser strategies.
+ */
+export declare class ParserFactory {
+    private static parsers;
+    static register(language: string, parser: DiagramParser): void;
+    static getParser(language: string): DiagramParser;
+}

package/dist/src/parser/index.js

@@ -0,0 +1,29 @@
+var _a;
+import { mermaidParser } from './languages/mermaid';
+/**
+ * Parser Factory
+ * Centralizes retrieval of parser strategies.
+ */
+export class ParserFactory {
+    static register(language, parser) {
+        this.parsers.set(language, parser);
+    }
+    static getParser(language) {
+        const parser = this.parsers.get(language);
+        if (!parser) {
+            throw new Error(`Parser for language '${language}' not found.`);
+        }
+        return parser;
+    }
+}
+_a = ParserFactory;
+Object.defineProperty(ParserFactory, "parsers", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Map()
+});
+(() => {
+    // Register built-in parsers
+    _a.register('mermaid', mermaidParser);
+})();

package/dist/src/parser/index.test.d.ts

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

package/dist/src/parser/index.test.js

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { ParserFactory } from './index';
+describe('ParserFactory', () => {
+    it('should retrieve registered parser', () => {
+        const parser = ParserFactory.getParser('mermaid');
+        expect(parser).toBeDefined();
+        // Since we import implemented parser, we expect checking it conforms to interface
+        expect(typeof parser.parse).toBe('function');
+    });
+    it('should throw error for unknown language', () => {
+        expect(() => {
+            ParserFactory.getParser('unknown-lang');
+        }).toThrow("Parser for language 'unknown-lang' not found.");
+    });
+    it('should allow registering new parser', () => {
+        const mockParser = {
+            parse: (_code) => ({ kind: 'root', meta: { version: '1.0.0', source: 'unknown' }, participants: [], groups: [], events: [] })
+        };
+        ParserFactory.register('test-lang', mockParser);
+        const retrieved = ParserFactory.getParser('test-lang');
+        expect(retrieved).toBe(mockParser);
+    });
+});

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

@@ -0,0 +1,8 @@
+import { PolagramRoot } from '../ast';
+/**
+ * Strategy Interface for Diagram Parsing.
+ * Implements the Strategy Pattern: different formats implement this interface.
+ */
+export interface DiagramParser {
+    parse(code: string): PolagramRoot;
+}

package/dist/src/parser/interface.js

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