@synergenius/flow-weaver 0.2.0

package/dist/chevrotain-parser/grammar-diagrams.js

@@ -0,0 +1,264 @@
+/**
+ * @module chevrotain-parser/grammar-diagrams
+ *
+ * Generates railroad diagrams for all JSDoc grammars using Chevrotain.
+ */
+import { createSyntaxDiagramsCode } from 'chevrotain';
+import { getPortGrammar } from './port-parser.js';
+import { getNodeGrammar } from './node-parser.js';
+import { getConnectGrammar } from './connect-parser.js';
+import { getPositionGrammar } from './position-parser.js';
+import { getScopeGrammar } from './scope-parser.js';
+import { getPathGrammar } from './path-parser.js';
+export function serializedToEBNF(productions) {
+    const lines = [];
+    for (const prod of productions) {
+        if (prod.type === 'Rule') {
+            // Access rule properties with type assertion
+            const rule = prod;
+            if (rule.definition && rule.name) {
+                const body = definitionToEBNF(rule.definition);
+                lines.push(`${rule.name} ::= ${body}`);
+            }
+        }
+    }
+    return lines.join('\n\n');
+}
+function definitionToEBNF(definition) {
+    return definition.map((item) => itemToEBNF(item)).join(' ');
+}
+function itemToEBNF(item) {
+    switch (item.type) {
+        case 'Terminal':
+            const pattern = item.pattern || '';
+            // Show readable patterns for known tokens
+            if (pattern.startsWith('@')) {
+                return `"${pattern.replace('\\b', '')}"`;
+            }
+            // Punctuation
+            const punctuation = {
+                '->': '"->"',
+                ':': '":"',
+                ',': '","',
+                '=': '"="',
+                '-': '"-"',
+                '\\.': '"."',
+                '\\[': '"["',
+                '\\]': '"]"',
+                '\\(': '"("',
+                '\\)': '")"',
+            };
+            if (punctuation[pattern])
+                return punctuation[pattern];
+            // Keywords
+            if (pattern === 'scope:')
+                return '"scope:"';
+            if (pattern === 'order:')
+                return '"order:"';
+            if (pattern === 'placement:')
+                return '"placement:"';
+            if (pattern === 'label:')
+                return '"label:"';
+            if (pattern === 'expr:')
+                return '"expr:"';
+            if (pattern === 'portOrder:')
+                return '"portOrder:"';
+            if (pattern === 'pullExecution:')
+                return '"pullExecution:"';
+            if (pattern === 'minimized\\b')
+                return '"minimized"';
+            if (pattern === 'TOP\\b')
+                return '"TOP"';
+            if (pattern === 'BOTTOM\\b')
+                return '"BOTTOM"';
+            // Identifier pattern - use semantic name if available
+            if (pattern === '[a-zA-Z_$][a-zA-Z0-9_$]*') {
+                const semanticName = item.terminalLabel || 'IDENTIFIER';
+                return semanticName;
+            }
+            // Integer pattern
+            if (pattern === '-?\\d+') {
+                return item.terminalLabel || 'INTEGER';
+            }
+            // String literal
+            if (pattern.includes('(?:[^"\\\\]|\\\\.)*')) {
+                return item.terminalLabel || 'STRING';
+            }
+            // Fallback
+            return item.terminalLabel || item.name || 'unknown';
+        case 'NonTerminal':
+            return `<${item.name || 'unknown'}>`;
+        case 'Alternation':
+            const alts = (item.definition || []).map((alt) => {
+                if (alt.type === 'Alternative' && alt.definition) {
+                    return definitionToEBNF(alt.definition);
+                }
+                return itemToEBNF(alt);
+            });
+            return `( ${alts.join(' | ')} )`;
+        case 'Option':
+            return `[ ${definitionToEBNF(item.definition || [])} ]`;
+        case 'Repetition':
+            return `{ ${definitionToEBNF(item.definition || [])} }`;
+        case 'RepetitionMandatory':
+            return `${definitionToEBNF(item.definition || [])}+`;
+        case 'RepetitionMandatoryWithSeparator':
+            const sepName = item.separator?.name || ',';
+            return `${definitionToEBNF(item.definition || [])} { "${sepName === 'Comma' ? ',' : sepName}" ${definitionToEBNF(item.definition || [])} }`;
+        case 'RepetitionWithSeparator':
+            const sep = item.separator?.name || ',';
+            return `[ ${definitionToEBNF(item.definition || [])} { "${sep === 'Comma' ? ',' : sep}" ${definitionToEBNF(item.definition || [])} } ]`;
+        default:
+            return `/* ${item.type} */`;
+    }
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Get all grammar productions as serialized GAST (Grammar AST).
+ */
+export function getAllGrammars() {
+    return {
+        port: getPortGrammar(),
+        node: getNodeGrammar(),
+        connect: getConnectGrammar(),
+        position: getPositionGrammar(),
+        scope: getScopeGrammar(),
+        path: getPathGrammar(),
+    };
+}
+/**
+ * Generate standalone HTML with railroad diagrams for all grammars.
+ * Uses Chevrotain's createSyntaxDiagramsCode which returns a complete HTML page.
+ */
+export function generateGrammarDiagrams() {
+    const grammars = getAllGrammars();
+    // Combine all grammars for unified diagram
+    const allProductions = [
+        ...grammars.port,
+        ...grammars.node,
+        ...grammars.connect,
+        ...grammars.position,
+        ...grammars.scope,
+        ...grammars.path,
+    ];
+    // createSyntaxDiagramsCode returns a complete HTML document
+    const html = createSyntaxDiagramsCode(allProductions);
+    // Generate EBNF text
+    const ebnf = serializedToEBNF(allProductions);
+    // Inject custom styling and header into the generated HTML
+    const customStyles = `
+<style>
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif !important;
+    max-width: 1400px;
+    margin: 0 auto;
+    padding: 2rem;
+    background-color: #f8f9fa !important;
+  }
+  h1.grammar-title {
+    text-align: center;
+    color: #333;
+    margin-bottom: 0.5rem;
+    font-size: 2rem;
+  }
+  .back-link {
+    display: block;
+    text-align: center;
+    margin-bottom: 2rem;
+    color: #4a90d9;
+    text-decoration: none;
+  }
+  .back-link:hover { text-decoration: underline; }
+  .tabs {
+    display: flex;
+    gap: 0;
+    margin-bottom: 0;
+    border-bottom: 2px solid #ddd;
+  }
+  .tab {
+    padding: 0.75rem 1.5rem;
+    cursor: pointer;
+    background: #e9ecef;
+    border: none;
+    border-bottom: 2px solid transparent;
+    margin-bottom: -2px;
+    font-size: 1rem;
+    color: #666;
+  }
+  .tab:hover { background: #dee2e6; }
+  .tab.active {
+    background: #fff;
+    border-bottom-color: #4a90d9;
+    color: #333;
+    font-weight: 500;
+  }
+  .tab-content { display: none; padding: 1rem 0; }
+  .tab-content.active { display: block; }
+  .ebnf-container {
+    background: #1e1e1e;
+    color: #d4d4d4;
+    padding: 1.5rem;
+    border-radius: 8px;
+    overflow-x: auto;
+    font-family: 'Fira Code', 'Consolas', monospace;
+    font-size: 0.9rem;
+    line-height: 1.6;
+    white-space: pre-wrap;
+  }
+  .ebnf-container .rule-name { color: #569cd6; }
+  .ebnf-container .terminal { color: #ce9178; }
+  .ebnf-container .nonterminal { color: #4ec9b0; }
+  .ebnf-container .operator { color: #d4d4d4; }
+</style>
+`;
+    // Escape HTML first, then apply syntax highlighting
+    const escaped = ebnf.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    // Use placeholders to avoid regex conflicts
+    const ebnfHtml = escaped
+        .replace(/"([^"]+)"/g, '___TERM_START___$1___TERM_END___')
+        .replace(/&lt;(\w+)&gt;/g, '___NT_START___$1___NT_END___')
+        .replace(/^(\w+)\s*::=/gm, '___RULE_START___$1___RULE_END___ ::=')
+        .replace(/___TERM_START___/g, '<span class="terminal">"')
+        .replace(/___TERM_END___/g, '"</span>')
+        .replace(/___NT_START___/g, '<span class="nonterminal">&lt;')
+        .replace(/___NT_END___/g, '&gt;</span>')
+        .replace(/___RULE_START___/g, '<span class="rule-name">')
+        .replace(/___RULE_END___/g, '</span>');
+    const header = `
+<h1 class="grammar-title">Flow Weaver JSDoc Grammar</h1>
+<a href="index.html" class="back-link">← Back to API Documentation</a>
+<div class="tabs">
+  <button class="tab active" onclick="showTab('diagrams')">Railroad Diagrams</button>
+  <button class="tab" onclick="showTab('ebnf')">EBNF Text</button>
+</div>
+<div id="ebnf" class="tab-content">
+  <div class="ebnf-container">${ebnfHtml}</div>
+</div>
+<script>
+function showTab(id) {
+  document.querySelectorAll('.tab-content').forEach(el => el.classList.remove('active'));
+  document.querySelectorAll('.tab').forEach(el => el.classList.remove('active'));
+  document.getElementById(id).classList.add('active');
+  event.target.classList.add('active');
+}
+</script>
+`;
+    // Insert styles after existing style block, header before diagrams
+    return html
+        .replace('</style>', `</style>${customStyles}`)
+        .replace('<div id="diagrams"', `${header}<div id="diagrams" class="tab-content active"`);
+}
+/**
+ * Generate diagram HTML for a specific grammar.
+ */
+export function generateGrammarDiagramFor(grammarName) {
+    const grammars = getAllGrammars();
+    const grammar = grammars[grammarName];
+    const html = createSyntaxDiagramsCode(grammar);
+    const title = grammarName.charAt(0).toUpperCase() + grammarName.slice(1);
+    const header = `<h1 style="text-align:center;color:#333">${title} Grammar</h1>`;
+    return html.replace('<div id="diagrams"', `${header}<div id="diagrams"`);
+}
+//# sourceMappingURL=grammar-diagrams.js.map

package/dist/chevrotain-parser/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module chevrotain-parser
+ *
+ * Chevrotain-based parsers for JSDoc annotations.
+ * Provides structured parsing for @input, @output, @node, @connect, and @position.
+ */
+export { JSDocLexer, allTokens, InputTag, OutputTag, NodeTag, ConnectTag, PositionTag, ScopeTag, MapTag, PathTag, TriggerTag, CancelOnTag, RetriesTag, TimeoutTag, ThrottleTag, } from './tokens.js';
+export { parsePortLine, getPortGrammar } from './port-parser.js';
+export type { PortParseResult } from './port-parser.js';
+export { parseNodeLine, getNodeGrammar } from './node-parser.js';
+export type { NodeParseResult } from './node-parser.js';
+export { parseConnectLine, getConnectGrammar } from './connect-parser.js';
+export type { ConnectParseResult, PortReference } from './connect-parser.js';
+export { parsePositionLine, getPositionGrammar } from './position-parser.js';
+export type { PositionParseResult } from './position-parser.js';
+export { parseScopeLine, getScopeGrammar } from './scope-parser.js';
+export type { ScopeParseResult } from './scope-parser.js';
+export { parseMapLine, getMapGrammar } from './map-parser.js';
+export type { MapParseResult } from './map-parser.js';
+export { parsePathLine, getPathGrammar } from './path-parser.js';
+export type { PathParseResult, PathStep } from './path-parser.js';
+export { parseTriggerLine, parseCancelOnLine, parseRetriesLine, parseTimeoutLine, parseThrottleLine } from './trigger-cancel-parser.js';
+export type { TriggerParseResult, CancelOnParseResult, ThrottleParseResult } from './trigger-cancel-parser.js';
+export { generateGrammarDiagrams, getAllGrammars, serializedToEBNF } from './grammar-diagrams.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/chevrotain-parser/index.js

@@ -0,0 +1,27 @@
+/**
+ * @module chevrotain-parser
+ *
+ * Chevrotain-based parsers for JSDoc annotations.
+ * Provides structured parsing for @input, @output, @node, @connect, and @position.
+ */
+// Token exports (for advanced use cases)
+export { JSDocLexer, allTokens, InputTag, OutputTag, NodeTag, ConnectTag, PositionTag, ScopeTag, MapTag, PathTag, TriggerTag, CancelOnTag, RetriesTag, TimeoutTag, ThrottleTag, } from './tokens.js';
+// Port parser
+export { parsePortLine, getPortGrammar } from './port-parser.js';
+// Node parser
+export { parseNodeLine, getNodeGrammar } from './node-parser.js';
+// Connect parser
+export { parseConnectLine, getConnectGrammar } from './connect-parser.js';
+// Position parser
+export { parsePositionLine, getPositionGrammar } from './position-parser.js';
+// Scope parser
+export { parseScopeLine, getScopeGrammar } from './scope-parser.js';
+// Map parser
+export { parseMapLine, getMapGrammar } from './map-parser.js';
+// Path parser
+export { parsePathLine, getPathGrammar } from './path-parser.js';
+// Trigger/cancel/retries/timeout/throttle parser
+export { parseTriggerLine, parseCancelOnLine, parseRetriesLine, parseTimeoutLine, parseThrottleLine } from './trigger-cancel-parser.js';
+// Grammar diagram generation
+export { generateGrammarDiagrams, getAllGrammars, serializedToEBNF } from './grammar-diagrams.js';
+//# sourceMappingURL=index.js.map

package/dist/chevrotain-parser/map-parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module chevrotain-parser/map-parser
+ *
+ * Parser for @map sugar annotations using Chevrotain.
+ *
+ * Syntax:
+ *   @map <instanceId> <childNode> over <sourceNode>.<sourcePort>
+ *   @map <instanceId> <childNode>(inputPort -> outputPort) over <sourceNode>.<sourcePort>
+ */
+export interface MapParseResult {
+    /** Instance ID for the synthetic iterator node (e.g., "loop") */
+    instanceId: string;
+    /** Child node ID to apply to each item (e.g., "proc") */
+    childId: string;
+    /** Source node for the array (e.g., "scan") */
+    sourceNode: string;
+    /** Source port for the array (e.g., "files") */
+    sourcePort: string;
+    /** Explicit input port on child (auto-inferred if omitted) */
+    inputPort?: string;
+    /** Explicit output port on child (auto-inferred if omitted) */
+    outputPort?: string;
+}
+/**
+ * Parse a @map line and return structured result.
+ * Returns null if the line is not a valid @map declaration.
+ */
+export declare function parseMapLine(input: string, warnings: string[]): MapParseResult | null;
+/**
+ * Get serialized grammar for documentation/diagram generation.
+ */
+export declare function getMapGrammar(): import("chevrotain").ISerializedGast[];
+//# sourceMappingURL=map-parser.d.ts.map

package/dist/chevrotain-parser/map-parser.js

@@ -0,0 +1,130 @@
+/**
+ * @module chevrotain-parser/map-parser
+ *
+ * Parser for @map sugar annotations using Chevrotain.
+ *
+ * Syntax:
+ *   @map <instanceId> <childNode> over <sourceNode>.<sourcePort>
+ *   @map <instanceId> <childNode>(inputPort -> outputPort) over <sourceNode>.<sourcePort>
+ */
+import { CstParser } from 'chevrotain';
+import { JSDocLexer, MapTag, OverKeyword, Identifier, Dot, LParen, RParen, Arrow, allTokens, } from './tokens.js';
+// =============================================================================
+// Parser Definition
+// =============================================================================
+class MapParser extends CstParser {
+    constructor() {
+        super(allTokens);
+        this.performSelfAnalysis();
+    }
+    // Entry rule: @map instanceId childNode[(inputPort -> outputPort)] over source.port
+    mapLine = this.RULE('mapLine', () => {
+        this.CONSUME(MapTag);
+        this.CONSUME(Identifier, { LABEL: 'instanceId' });
+        this.CONSUME2(Identifier, { LABEL: 'childId' });
+        this.OPTION(() => {
+            this.SUBRULE(this.portMapping);
+        });
+        this.CONSUME(OverKeyword);
+        this.SUBRULE(this.portRef);
+    });
+    // (inputPort -> outputPort)
+    portMapping = this.RULE('portMapping', () => {
+        this.CONSUME(LParen);
+        this.CONSUME(Identifier, { LABEL: 'inputPort' });
+        this.CONSUME(Arrow);
+        this.CONSUME2(Identifier, { LABEL: 'outputPort' });
+        this.CONSUME(RParen);
+    });
+    // node.port
+    portRef = this.RULE('portRef', () => {
+        this.CONSUME(Identifier, { LABEL: 'sourceNode' });
+        this.CONSUME(Dot);
+        this.CONSUME2(Identifier, { LABEL: 'sourcePort' });
+    });
+}
+// =============================================================================
+// Parser Instance (singleton)
+// =============================================================================
+const parserInstance = new MapParser();
+// =============================================================================
+// CST Visitor
+// =============================================================================
+const BaseVisitor = parserInstance.getBaseCstVisitorConstructor();
+class MapVisitor extends BaseVisitor {
+    constructor() {
+        super();
+        this.validateVisitor();
+    }
+    mapLine(ctx) {
+        const instanceId = ctx.instanceId[0].image;
+        const childId = ctx.childId[0].image;
+        const portRef = this.visit(ctx.portRef[0]);
+        let inputPort;
+        let outputPort;
+        if (ctx.portMapping) {
+            const mapping = this.visit(ctx.portMapping[0]);
+            inputPort = mapping.inputPort;
+            outputPort = mapping.outputPort;
+        }
+        return {
+            instanceId,
+            childId,
+            sourceNode: portRef.sourceNode,
+            sourcePort: portRef.sourcePort,
+            ...(inputPort && { inputPort }),
+            ...(outputPort && { outputPort }),
+        };
+    }
+    portMapping(ctx) {
+        return {
+            inputPort: ctx.inputPort[0].image,
+            outputPort: ctx.outputPort[0].image,
+        };
+    }
+    portRef(ctx) {
+        return {
+            sourceNode: ctx.sourceNode[0].image,
+            sourcePort: ctx.sourcePort[0].image,
+        };
+    }
+}
+const visitorInstance = new MapVisitor();
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Parse a @map line and return structured result.
+ * Returns null if the line is not a valid @map declaration.
+ */
+export function parseMapLine(input, warnings) {
+    const lexResult = JSDocLexer.tokenize(input);
+    if (lexResult.errors.length > 0) {
+        return null;
+    }
+    if (lexResult.tokens.length === 0) {
+        return null;
+    }
+    const firstToken = lexResult.tokens[0];
+    if (firstToken.tokenType !== MapTag) {
+        return null;
+    }
+    parserInstance.input = lexResult.tokens;
+    const cst = parserInstance.mapLine();
+    if (parserInstance.errors.length > 0) {
+        const firstError = parserInstance.errors[0];
+        const truncatedInput = input.length > 60 ? input.substring(0, 60) + '...' : input;
+        warnings.push(`Failed to parse @map line: "${truncatedInput}"\n` +
+            `  Error: ${firstError.message}\n` +
+            `  Expected format: @map instanceId childNode over source.port`);
+        return null;
+    }
+    return visitorInstance.visit(cst);
+}
+/**
+ * Get serialized grammar for documentation/diagram generation.
+ */
+export function getMapGrammar() {
+    return parserInstance.getSerializedGastProductions();
+}
+//# sourceMappingURL=map-parser.js.map

package/dist/chevrotain-parser/node-parser.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module chevrotain-parser/node-parser
+ *
+ * Parser for @node declarations using Chevrotain.
+ */
+export interface NodeParseResult {
+    instanceId: string;
+    nodeType: string;
+    parentScope?: string;
+    label?: string;
+    expressions?: Record<string, string>;
+    portOrder?: Record<string, number>;
+    portLabel?: Record<string, string>;
+    minimized?: boolean;
+    pullExecution?: string;
+    size?: {
+        width: number;
+        height: number;
+    };
+    color?: string;
+    icon?: string;
+    tags?: Array<{
+        label: string;
+        tooltip?: string;
+    }>;
+}
+/**
+ * Parse a @node line and return structured result.
+ * Returns null if the line is not a node declaration.
+ */
+export declare function parseNodeLine(input: string, warnings: string[]): NodeParseResult | null;
+/**
+ * Get serialized grammar for documentation/diagram generation.
+ */
+export declare function getNodeGrammar(): import("chevrotain").ISerializedGast[];
+//# sourceMappingURL=node-parser.d.ts.map