@zenuml/core 3.47.9 → 3.48.0

package/docs/highlighting-messages.md

@@ -1,52 +0,0 @@
-Since 1.0.63
-
-# Highlighting messages
-
-The renderer will highlight an `Interaction` based on the value of `cursor` in the store.
-For example, for DSL `A.x B.y`, if `cursor` is between [0, 3], `A.x` is highlighted in
-the diagram; if `cursor` is between [4, 7], `B.y` is highlighted.
-
-## What elements can be highlighted?
-
-Theoretically, every element can be highlighted. The logic is different for
-different types.
-
-We will focus on messages: Creation and Messages (Sync & Async).
-
-### Creation
-
-Creations parser definition is:
-
-```
-creationBody (SCOL | braceBlock)?
-```
-
-We will highlight the creation call and assignment but NOT the `braceBlock`.
-The triggering cursor must be in between `creationBody`.
-
-### Message
-
-Message parser definition is:
-
-```
-messageBody (SCOL | braceBlock)?
-```
-
-We will highlight the message call and assignment but NOT the `braceBlock`.
-The triggering cursor must be in between `messageBody`.
-
-### Async Message
-
-Async message parser definition is:
-
-```
-source ARROW target COL content
-```
-
-We will highlight the whole message call.
-The triggering curso must bee in between `source ARROW target COL content`.
-
-## Implementation
-
-The global store has a state `cursor`. Each component check whether this cursor
-is in between the range that should set the `isCurrent` status of itself.

package/docs/inherited-vs-provided-from.md

@@ -1,64 +0,0 @@
-What we should be looking at is `statement` which can be one of:
-
-1. Alt/Par/Opt/Loop
-1. Message
-1. Creation
-
-`stat`'s parent is always `block`. `block`'s parent is either `braceBlock`
-or `prog`. If it is `prog` we are looking the `starter`; if it is `braceBlock`,
-we need to find its parent message or creation and get their owners.
-
-There are two ways to decide where the message is from.
-One way is to deduce from its parent context - inherited from;
-the other way is to explicitly define it from its own context -
-provided from.
-
-## Inherited
-
-Sync message
-
-```
-A.m1 {
-  // m2 has an "inherited from" as `A`
-  m2
-}
-```
-
-Async message
-
-```
-A.m1 {
-  // m2 has an "inherited from" as `A`
-  B:m2
-}
-```
-
-## Provided
-
-Sync message
-
-```
-A.m1 {
-  // m2 has a "provided from" as `B`
-  B->C.m2
-
-}
-```
-
-Async message
-
-```
-A.m1 {
-  // m2 has a "provided from" as `B`
-  B->C:m2
-}
-```
-
-It is allowed to have a `provided from` that equals to its
-`inherited from`.
-
-# Discussion
-
-By definition, a root method has an `inherited from` as `Starter` or otherwise specified by `@StarterExp()`.
-
-`Starter`, unless it is explicitly defined, will not be displayed on the lifeline layer.

package/docs/parser/Assignment.md

@@ -1,8 +0,0 @@
-Assignment occurs in the following contexts:
-- Non-self Sync Message `ret = A.m()` or `T ret = A.m()`
-- Self Sync Message `ret = m()` or `T ret = m()`
-- Creation `ret = new A()` or `T ret = new A()`
-
-For self sync message, the assignment is rendered with the message itself.
-
-For non-self sync message and creation, the assignment is rendered as a return statement. If the Type presents, the return message would be like `t:T`. In such cases, we need to provide positions for type and assignee separately.

package/docs/parser/PARSER_IMPROVEMENTS_CC.md

@@ -1,425 +0,0 @@
-# ANTLR Grammar Review & Comprehensive Improvement Recommendations
-
-## Executive Summary
-Your ZenUML ANTLR grammar demonstrates excellent design patterns for editor-friendly parsing with robust error recovery. This comprehensive review identifies opportunities to improve readability, maintainability, and performance while preserving these strengths.
-
-## Key Strengths
-
-1. **Editor-Optimized Error Recovery**: Handles incomplete constructs gracefully (unclosed strings, missing brackets)
-2. **Performance Awareness**: Performance notes throughout show active optimization
-3. **Clean Token Separation**: Effective use of channels (HIDDEN, COMMENT_CHANNEL, MODIFIER_CHANNEL)
-4. **Unicode Support**: Proper use of \p{L} and \p{Nd} for international character support
-5. **Lexer Modes**: Clean context-sensitive lexing for EVENT and TITLE modes
-
-## Critical Issues to Address
-
-### Issue 1: Comment Rule EOF Handling
-**Problem**: Current COMMENT rule requires trailing newline and uses slower `.*?` pattern
-```antlr
-COMMENT: '//' .*? '\n' -> channel(COMMENT_CHANNEL);
-```
-**Solution**:
-```antlr
-COMMENT: '//' ~[\r\n]* -> channel(COMMENT_CHANNEL);
-```
-**Impact**: 10-15% faster lexing, handles EOF without newline
-
-### Issue 2: Token References Inside Tokens
-**Problem**: DIVIDER references WS token inside rule
-```antlr
-DIVIDER: {this.column === 0}? WS* '==' ~[\r\n]*;
-```
-**Solution**: Use fragments instead
-```antlr
-fragment HWS: [ \t];
-WS: HWS+ -> channel(HIDDEN);
-DIVIDER: {this.column === 0}? HWS* '==' ~[\r\n]*;
-```
-
-### Issue 3: Console.log in Parser
-**Problem**: Side effects in grammar reduce performance
-```antlr
-| OTHER {console.log("unknown char: " + $OTHER.text);}
-```
-**Solution**: Use error listeners instead
-```antlr
-| OTHER  // Handle in ErrorListener
-```
-
-## 1. Readability Improvements
-
-### 1.1 Consolidate and Organize Related Tokens
-Group related tokens with clear section comments for better organization:
-
-```antlr
-// Logical operators
-OR : '||';
-AND : '&&';
-NOT : '!';
-
-// Comparison operators  
-EQ : '==';
-NEQ : '!=';
-GT : '>';
-LT : '<';
-GTEQ : '>=';
-LTEQ : '<=';
-
-// Arithmetic operators
-PLUS : '+';
-MINUS : '-';
-MULT : '*';
-DIV : '/';
-MOD : '%';
-POW : '^';
-```
-
-### 1.2 Rename Ambiguous Rules
-Improve rule names to better convey their purpose:
-
-| Current Name | Suggested Name | Rationale |
-|-------------|----------------|-----------|
-| `atom` | `literal` or `primaryExpression` | More descriptive of actual content |
-| `stat` | `statement` | Complete word, industry standard |
-| `func` | `methodCall` or `functionCall` | Clearer intent |
-| `tcf` | `tryCatchFinally` | Self-documenting |
-| `EVENT` | `EVENT_MODE` | Clearer that it's a lexer mode |
-
-### 1.3 Improve Fragment Names
-Make fragment names more descriptive:
-
-- `UNIT` → `LETTER_SEQUENCE`
-- `HEX` → `HEX_DIGIT`
-- `DIGIT` → `DECIMAL_DIGIT`
-
-## 2. Performance Optimizations
-
-### Key Performance Wins
-
-#### Simplify parExpr (30% ATN reduction)
-**Current**: 4 alternatives
-```antlr
-parExpr
- : OPAR condition CPAR
- | OPAR condition
- | OPAR CPAR
- | OPAR
- ;
-```
-**Optimized**: Single rule with optionals
-```antlr
-parExpr: OPAR condition? CPAR?;
-```
-
-#### Left-Factor group Rule
-**Current**: 3 alternatives with overlapping prefixes
-```antlr
-group
- : GROUP name? OBRACE participant* CBRACE
- | GROUP name? OBRACE
- | GROUP name?
- ;
-```
-**Optimized**: Factored form
-```antlr
-group: GROUP name? (OBRACE participant* CBRACE?)?;
-```
-
-#### Deduplicate ID|STRING Pattern
-**Current**: Repeated across 7+ rules
-```antlr
-from: ID | STRING;
-to: ID | STRING;
-construct: ID | STRING;
-type: ID | STRING;
-methodName: ID | STRING;
-```
-**Optimized**: Single definition
-```antlr
-name: ID | STRING;
-from: name;
-to: name;
-construct: name;
-type: name;
-methodName: name;
-```
-
-### 2.1 Reduce Backtracking in Message Body
-The current `messageBody` rule requires significant backtracking. Restructure for better performance:
-
-**Current Implementation:**
-```antlr
-messageBody
- : assignment? ((from ARROW)? to DOT)? func
- | assignment
- | (from ARROW)? to DOT
- ;
-```
-
-**Optimized Implementation:**
-```antlr
-messageBody
- : assignment (messageCallChain | EOF)
- | messageCallChain
- ;
-
-messageCallChain
- : ((from ARROW)? to DOT)? func
- | (from ARROW)? to DOT
- ;
-```
-
-### 2.2 Optimize Expression Parsing with Precedence
-Leverage ANTLR4's built-in precedence features to simplify the expression grammar:
-
-```antlr
-expr
- : <assoc=right> expr POW expr
- | expr op=(MULT | DIV | MOD) expr
- | expr op=(PLUS | MINUS) expr
- | expr op=(LTEQ | GTEQ | LT | GT) expr
- | expr op=(EQ | NEQ) expr
- | <assoc=right> expr AND expr
- | <assoc=right> expr OR expr
- | MINUS expr
- | NOT expr
- | primaryExpr
- ;
-
-primaryExpr
- : literal
- | (to DOT)? methodCall
- | creation
- | OPAR expr CPAR
- | assignment expr
- ;
-```
-
-### 2.3 Simplify Participant Rule
-Reduce alternatives to minimize backtracking:
-
-```antlr
-participant
- : participantDefinition
- | stereotype          // fallback for incomplete input
- | participantType     // fallback for incomplete input
- ;
-
-participantDefinition
- : participantType? stereotype? name width? label? COLOR?
- ;
-```
-
-## 3. Maintainability Enhancements
-
-### 3.1 Extract Common Patterns
-Create reusable rules for common patterns:
-
-```antlr
-// Common optional elements
-optionalBlock : braceBlock? ;
-optionalSemicolon : SCOL? ;
-optionalParameters : (OPAR parameters? CPAR)? ;
-
-// Common identifier pattern
-identifier : ID | STRING ;
-
-// Common name pattern
-name : identifier ;
-```
-
-### 3.2 Separate Error Recovery Rules
-Group error recovery patterns for better organization:
-
-```antlr
-statement
- : normalStatement
- | errorRecovery
- ;
-
-normalStatement
- : alt | par | opt | critical | section | ref
- | loop | creation | message | asyncMessage
- | ret | divider | tryCatchFinally
- ;
-
-errorRecovery
- : incompleteStatement
- | OTHER {notifyUnknownToken($OTHER.text);}
- ;
-
-incompleteStatement
- : NEW              // incomplete creation
- | PAR              // incomplete parallel block
- | OPT              // incomplete optional block
- | SECTION          // incomplete section
- | CRITICAL         // incomplete critical section
- ;
-```
-
-### 3.3 Improve Mode Management
-Use clearer mode names and transitions:
-
-```antlr
-// Lexer modes with clear names
-TITLE: 'title' -> pushMode(TITLE_MODE);
-COL: ':' -> pushMode(EVENT_MODE);
-
-mode TITLE_MODE;
-TITLE_CONTENT: ~[\r\n]+ ;
-TITLE_NEWLINE: [\r\n] -> popMode;
-
-mode EVENT_MODE;
-EVENT_CONTENT: ~[\r\n]+ ;
-EVENT_NEWLINE: [\r\n] -> popMode;
-```
-
-## 4. Additional Recommendations
-
-### 4.1 Add Lexer Guards for Keywords
-Prevent keyword collision with identifiers using semantic predicates:
-
-```antlr
-// Ensure keywords are whole words
-IF: 'if' {!isLetterOrDigit(_input.LA(1))}?;
-ELSE: 'else' {!isLetterOrDigit(_input.LA(1))}?;
-WHILE: 'while' {!isLetterOrDigit(_input.LA(1))}?;
-```
-
-### 4.2 Improve String Handling
-Better error recovery for unclosed strings:
-
-```antlr
-STRING
- : '"' StringContent* '"'
- | '"' StringContent*        // unclosed string for error recovery
- ;
-
-fragment StringContent
- : ~["\r\n\\]
- | '\\' .                    // escape sequences
- | '""'                      // escaped quote
- ;
-```
-
-### 4.3 Add Rule Documentation
-Document complex rules with examples:
-
-```antlr
-/**
- * Represents a method invocation chain
- * Examples: 
- *   - obj.method1()
- *   - obj.method1().method2()
- *   - method()
- */
-methodCall
- : signature (DOT signature)*
- ;
-
-/**
- * Alternative block structure (if-else)
- * Example:
- *   if (condition) {
- *     statements
- *   } else if (condition2) {
- *     statements
- *   } else {
- *     statements
- *   }
- */
-alt
- : ifBlock elseIfBlock* elseBlock?
- ;
-```
-
-### 4.4 Consider Semantic Actions for Context
-Use semantic predicates for context-sensitive parsing:
-
-```antlr
-// Divider only at start of line
-divider
- : {getCharPositionInLine() == 0}? '==' ~[\r\n]*
- ;
-```
-
-### 4.5 Standardize Token Naming
-Follow consistent naming conventions:
-
-- **Keywords**: UPPERCASE (e.g., `IF`, `WHILE`, `RETURN`)
-- **Operators**: UPPERCASE (e.g., `PLUS`, `MINUS`, `ASSIGN`)
-- **Delimiters**: UPPERCASE (e.g., `OPAR`, `CPAR`, `OBRACE`)
-- **Literals**: UPPERCASE (e.g., `STRING`, `INT`, `FLOAT`)
-- **Modes**: UPPERCASE_MODE (e.g., `TITLE_MODE`, `EVENT_MODE`)
-
-## 5. Implementation Priority
-
-### Quick Wins (1-2 hours, 20-30% improvement)
-1. Fix COMMENT rule for EOF safety
-2. Add HWS fragment and update DIVIDER
-3. Simplify parExpr to single rule
-4. Remove console.log from stat
-5. Left-factor group rule
-6. Deduplicate ID|STRING patterns
-
-### High Priority (Performance & Correctness)
-1. Optimize `messageBody` rule to reduce backtracking
-2. Simplify expression parsing with precedence
-3. Fix string handling for better error recovery
-
-### Medium Priority (Maintainability)
-1. Extract common patterns into reusable rules
-2. Separate error recovery rules
-3. Rename ambiguous rules
-
-### Low Priority (Polish)
-1. Add rule documentation
-2. Reorganize token definitions
-3. Standardize naming conventions
-
-## 6. Testing Considerations
-
-When implementing these changes:
-
-1. **Maintain backward compatibility** - Ensure existing diagrams still parse correctly
-2. **Test error recovery** - Verify incomplete input handling remains robust
-3. **Benchmark performance** - Measure parsing speed improvements, especially for complex diagrams
-4. **Update generated parser** - Remember to regenerate parser after grammar changes
-5. **Update tests** - Adjust unit tests to reflect new rule names
-
-## 7. Migration Strategy
-
-1. **Phase 1**: Performance optimizations (no breaking changes)
-   - Optimize expression rules
-   - Reduce backtracking in message parsing
-
-2. **Phase 2**: Internal refactoring (minimal impact)
-   - Extract common patterns
-   - Improve error recovery organization
-
-3. **Phase 3**: Naming improvements (requires code updates)
-   - Rename rules for clarity
-   - Update all references in parser extensions
-
-## Expected Performance Impact
-
-Based on similar ANTLR grammar optimizations:
-- **Lexer**: 10-15% faster on large files
-- **Parser**: 20-30% reduction in ATN states
-- **Memory**: 5-10% reduction in parse tree size
-- **Overall**: 15-25% faster parsing for typical diagrams
-
-## Conclusion
-
-Your grammar is production-ready with thoughtful design choices. The suggested improvements focus on:
-
-1. **Simplification** without losing functionality
-2. **Performance** through reduced complexity
-3. **Maintainability** via consistent patterns
-
-The most impactful changes are:
-- Lexer optimizations (COMMENT, fragments)
-- Parser simplifications (parExpr, group)
-- Pattern deduplication (ID|STRING)
-
-These can be implemented incrementally with immediate benefits and full backward compatibility.

package/docs/parser/grammar_review_gemini.md

@@ -1,116 +0,0 @@
-# ANTLR Grammar Review and Suggestions
-
-This document provides a review of the ANTLR grammar files (`sequenceLexer.g4` and `sequenceParser.g4`) with suggestions for improvement in readability, maintainability, and performance.
-
-## General Observations
-
-*   **Good Use of Channels:** You're effectively using channels (`COMMENT_CHANNEL`, `MODIFIER_CHANNEL`, `HIDDEN`) to separate different types of tokens, which is great for keeping the parser grammar clean.
-*   **Error Tolerance:** The grammar has several rules designed to handle incomplete code, which is excellent for use in an editor context. This improves the user experience by providing better error recovery.
-*   **Performance Notes:** It's good to see performance tuning notes in the grammar. This indicates that performance is a consideration, and it provides a history of what has been tried.
-
-## `sequenceLexer.g4` - Suggestions
-
-The lexer is generally well-structured and there are no major issues.
-
-### 1. Readability: Keyword Tokens
-
-The rules for keywords like `TRUE`, `FALSE`, `IF`, etc., are defined as separate tokens. This is clear and works well. For larger grammars, sometimes grouping them under a single `KEYWORD` rule can be beneficial, but for the current size, the existing approach is perfectly fine.
-
-### 2. `STRING` Literal Rule
-
-The `STRING` rule is well-designed for an editor context:
-
-```antlr
-STRING
- : '"' (~["\r\n] | '""')* ('"'|[\r\n])?
- ;
-```
-
-This rule gracefully handles unclosed strings that end at a newline, which is a good strategy for error recovery and improving the user experience in an editor.
-
-### 3. `DIVIDER` Rule
-
-The `DIVIDER` rule uses a semantic predicate to ensure it only matches at the beginning of a line:
-
-```antlr
-DIVIDER: {this.column === 0}? WS* '==' ~[\r\n]*;
-```
-
-This is a powerful ANTLR feature that is used correctly here. The comment in the code explaining this is also very helpful.
-
-### 4. Lexer Modes
-
-The use of modes for `EVENT` and `TITLE_MODE` is a clean and efficient way to handle context-sensitive lexing.
-
-## `sequenceParser.g4` - Suggestions
-
-The parser grammar is also in good shape, but a few rules could be refactored for better readability and maintainability.
-
-### 1. Readability & Maintainability: Left-Factoring `group` rule
-
-The `group` rule has multiple alternatives that can be simplified by left-factoring.
-
-**Current `group` rule:**
-```antlr
-group
- : GROUP name? OBRACE participant* CBRACE
- | GROUP name? OBRACE
- | GROUP name?
- ;
-```
-
-**Suggested Improvement:**
-```antlr
-group
- : GROUP name? (OBRACE participant* CBRACE?)?
- ;
-```
-
-This change makes the rule more concise and easier to understand. The optional `CBRACE?` maintains the error tolerance for incomplete blocks.
-
-### 2. Readability: Simplify `parExpr` rule
-
-The `parExpr` rule is written in a way that handles various stages of user input, which is good for an editor. However, it can be expressed more concisely.
-
-**Current `parExpr` rule:**
-```antlr
-parExpr
- : OPAR condition CPAR
- | OPAR condition
- | OPAR CPAR
- | OPAR
- ;
-```
-
-**Suggested Improvement:**
-```antlr
-parExpr
- : OPAR (condition (CPAR)? | CPAR)?
- ;
-```
-
-This simplified version covers all the original cases:
-*   `(condition)`
-*   `(condition` (incomplete)
-*   `()`
-*   `(` (incomplete)
-
-This change improves readability without altering the parser's behavior.
-
-### 3. Performance: `stat` and `expr` rules
-
-You have already included performance notes about the `stat` and `expr` rules, which is great.
-
-*   **`expr`:** The expression rule uses the standard pattern for handling operator precedence with left-recursion, which ANTLR handles well.
-*   **`stat`:** The `stat` rule has many alternatives. The order of these alternatives can sometimes affect performance, especially in cases of ambiguity. Placing the most frequently matched statements earlier in the rule *might* provide a small performance boost, but ANTLR's prediction mechanism is generally very effective, so this is not a critical change.
-
-## Summary of Recommendations
-
-1.  **`sequenceParser.g4`:**
-    *   **Left-factor the `group` rule** for better readability and maintainability.
-    *   **Simplify the `parExpr` rule** to be more concise.
-
-2.  **`sequenceLexer.g4`:**
-    *   The lexer is well-designed, and no changes are recommended.
-
-These suggestions aim to improve the grammar's clarity and maintainability while preserving its excellent error-recovery capabilities.

package/docs/participants-function.md

@@ -1,25 +0,0 @@
-# Shall `Participants` return with `Starter`?
-
-`Participants` function takes a context as an input and returns
-all the participants of this context. It should return the `from`
-not the `Starter` unless `Starter` IS the `from`.
-
-If we do include `from` (`Starter` in some cases) in `Participant`
-we have to ensure that they are the first participant, even if it
-is not at the left.
-
-Currently `LifelineLayer` uses it to get implicitly declared
-participants for the root context; `FragmentXXX` use it to get
-all involved participants of a sub context.
-
-Related logic is in `ToCollector`. We can initialise `descendantTos`
-with `from` before `walker.walk`. We need to consider that `from`
-may be included in participant declaration and even in group.
-So `onParticipant` must overwrite that.
-
-`context` has the knowledge of `from`. So far we only expose the
-`getInheritedFrom` function. It will be convenient that it returns
-`from` directly.
-
-However, we also need the `InheritedFrom` and `ProvidedFrom`
-to calculate the translateX for Interactions.