fYmious/infocom-systems-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add hw2

Browse Source
This commit is contained in:
nik
2025-10-03 22:27:28 +03:00
parent 829fad0e17
commit 871cf7e792
16520 changed files with 2967597 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
node_modules/@zenuml/core/docs/CONTEXT-tier2-component.md generated vendored Normal file
View File

@@ -0,0 +1,96 @@
# [COMPONENT NAME] - Component Context (Tier 2)
> **Note**: This is component-specific context. See root **CLAUDE.md** for master project context and coding standards.
## Purpose
[Brief description of this component's role in the system. What problem does it solve and how does it fit into the overall architecture?]
## Current Status: [Status Description] ✅/🚧/📋
[Current implementation state, what's working, what's in progress, and key milestones achieved]
## Component-Specific Development Guidelines
- **[Technology/Framework]**: [Specific technology requirements for this component]
- **[Architecture Pattern]**: [Component-specific architectural approach]
- **[Code Organization]**: [How code should be structured within this component]
- **[Integration Patterns]**: [How this component integrates with others]
- **[Quality Standards]**: [Component-specific quality requirements]
## Key Component Structure
### Core Modules (`[path]/`)
- **[module1]/** - [Purpose and key functionality]
- **[file1].[ext]** - [Specific file purpose and key features]
- **[file2].[ext]** - [Specific file purpose and key features]
- **[module2]/** - [Purpose and key functionality]
- **[module3]/** - [Purpose and key functionality]
### [Secondary Structure] (`[path]/`)
- **[component].[ext]** - [Component purpose and architecture pattern]
- **[utilities].[ext]** - [Utility functions and helpers]
- **[config].[ext]** - [Configuration and settings management]
### [Integration Layer] (`[path]/`)
- **[integration1].[ext]** - [External service integration patterns]
- **[integration2].[ext]** - [Inter-component communication]
## Implementation Highlights
### [Key Feature 1]
- **[Technical Implementation]**: [How this feature is implemented]
- **[Architecture Decision]**: [Why this approach was chosen]
- **[Performance Considerations]**: [Optimization details]
- **[Integration Points]**: [How it connects to other components]
### [Key Feature 2]
- **[Implementation Pattern]**: [Technical implementation approach]
- **[Quality Measures]**: [Testing, monitoring, error handling]
- **[Scalability Considerations]**: [How it handles growth/load]
### [Key Feature 3]
- **[Technical Details]**: [Implementation specifics]
- **[Dependencies]**: [External dependencies and integration points]
- **[Configuration]**: [How it's configured and customized]
## Critical Implementation Details
### [Technical Pattern 1]
**[Pattern Description]**: [What problem this pattern solves]
```[language]
// Example implementation showing the pattern
[code example demonstrating the critical implementation]
```
### [Technical Pattern 2]
**[Architecture Decision]**: [Why this approach was chosen]
```[language]
// Code example showing architecture implementation
[code example demonstrating the architecture]
```
### [Integration Pattern]
**[Integration Description]**: [How this component integrates with others]
```[language]
// Integration implementation example
[code example showing integration patterns]
```
## Development Notes
### [Current Challenges]
- **[Challenge 1]**: [Description and current approach]
- **[Challenge 2]**: [Description and mitigation strategy]
### [Future Considerations]
- **[Enhancement 1]**: [Planned improvement and rationale]
- **[Enhancement 2]**: [Future architectural evolution]
### [Performance Metrics]
- **[Key Metric 1]**: [Current performance and targets]
- **[Key Metric 2]**: [Monitoring and optimization approach]
---
*This component documentation provides context for AI-assisted development within [COMPONENT NAME]. For system-wide patterns and standards, reference the master CLAUDE.md file.*

162
node_modules/@zenuml/core/docs/CONTEXT-tier3-feature.md generated vendored Normal file
View File

@@ -0,0 +1,162 @@
# [FEATURE NAME] Documentation (Tier 3)
*This file documents [feature/module] patterns, architectural decisions, and implementations within [component name].*
## [Feature] Architecture Overview
### [Architecture Decision Title]
**Context**: [Situation that led to this architectural decision]
**Decision**: [What was decided and implemented]
**Reasoning**:
- **[Benefit 1]**: [Why this approach provides this benefit]
- **[Benefit 2]**: [Technical or business advantage]
- **[Benefit 3]**: [Performance or maintainability benefit]
- **[Benefit 4]**: [Developer experience or operational benefit]
**Consequences**:
- [Positive outcome from this decision]
- [Technical improvement achieved]
- [Operational or maintenance benefit]
- [User experience enhancement]
## [Feature] Implementation Patterns
### [Implementation Pattern 1]
**File Organization**:
```
[feature-directory]/
├── [file1].[ext] # [Purpose and responsibility]
├── [file2].[ext] # [Purpose and responsibility]
├── [file3].[ext] # [Purpose and responsibility]
└── [file4].[ext] # [Purpose and responsibility]
```
**Architecture Benefits**:
- **[Benefit 1]**: [How this organization provides this benefit]
- **[Benefit 2]**: [Technical advantage of this structure]
- **[Benefit 3]**: [Maintainability or scalability benefit]
- **[Benefit 4]**: [Developer experience improvement]
### [Implementation Pattern 2]
**Architecture Decision**: [Technical approach taken]
**Context**: [Background and requirements that led to this approach]
**Decision**: [Specific implementation choice made]
**Reasoning**:
- **[Technical Reason]**: [Why this was the best technical choice]
- **[Performance Reason]**: [Performance benefits]
- **[Maintainability Reason]**: [Long-term maintenance benefits]
- **[Integration Reason]**: [How it integrates with other components]
**Implementation Details**:
```[language]
// [Description of what this code demonstrates]
[detailed code example showing the implementation pattern]
```
### [Implementation Pattern 3]
**[Pattern Name]**: [Description of the pattern]
```[language]
// [Code example title]
[comprehensive code example showing the pattern in action]
```
**Implementation Benefits**:
- **[Benefit 1]**: [Specific advantage this implementation provides]
- **[Benefit 2]**: [Performance or reliability improvement]
- **[Benefit 3]**: [Developer experience enhancement]
## [Technical Domain] Implementation
### [Technical Feature 1]
**[Feature Description]**: [What this feature does and why it's important]
**Architecture Pattern**:
```[language]
// [Description of the architectural approach]
[code example demonstrating the architecture]
```
**Key Implementation Details**:
- **[Detail 1]**: [Important implementation consideration]
- **[Detail 2]**: [Technical constraint or optimization]
- **[Detail 3]**: [Integration or performance consideration]
### [Technical Feature 2]
**Implementation Approach**: [How this feature is implemented]
```[language]
// [Code example description]
[detailed implementation example]
```
**Technical Considerations**:
- **[Consideration 1]**: [Important technical factor]
- **[Consideration 2]**: [Performance or scalability factor]
- **[Consideration 3]**: [Maintenance or testing consideration]
## [Integration/Communication] Patterns
### [Integration Pattern 1]
**Context**: [When and why this integration pattern is used]
**Implementation**:
```[language]
// [Integration example description]
[code showing integration implementation]
```
**Benefits**:
- **[Integration Benefit 1]**: [How this improves system integration]
- **[Integration Benefit 2]**: [Performance or reliability improvement]
### [Integration Pattern 2]
**Pattern Description**: [What problem this integration pattern solves]
```[language]
// [Integration code example]
[implementation showing integration pattern]
```
## Performance & Optimization Details
### [Performance Optimization 1]
**Optimization**: [What was optimized and how]
- **Before**: [Previous performance characteristics]
- **After**: [Improved performance metrics]
- **Implementation**: [How the optimization was achieved]
### [Performance Optimization 2]
**Technical Improvement**: [Specific performance enhancement]
- **Impact**: [Measurable improvement achieved]
- **Method**: [Technical approach used]
- **Trade-offs**: [Any compromises made for the optimization]
## Error Handling & Edge Cases
### [Error Scenario 1]
**Scenario**: [What error condition this handles]
**Handling**: [How the error is detected and managed]
**Recovery**: [How the system recovers from this error]
### [Error Scenario 2]
**Edge Case**: [Unusual condition that needs handling]
**Solution**: [How the implementation handles this case]
**Validation**: [How this handling is tested or verified]
---
*This feature documentation provides detailed implementation context for AI-assisted development. For broader component context, see the component-level CONTEXT.md file.*

207
node_modules/@zenuml/core/docs/README.md generated vendored Normal file
View File

@@ -0,0 +1,207 @@
# Documentation System Guide
This guide explains how the 3-tier documentation architecture powers the Claude Code Development Kit and why it provides superior results compared to traditional documentation approaches.
## Critical Foundation Files
Two files form the cornerstone of the entire documentation system:
1. **docs-overview.md** - The central routing guide that directs AI agents to appropriate documentation based on task complexity. This file maps your entire documentation structure and enables intelligent context loading.
2. **project-structure.md** - The comprehensive overview of your project's complete file structure and technology stack. This file is required reading for all AI agents and must be attached to Gemini consultations.
These foundation files ensure AI agents always have the essential context needed to understand your project and navigate to relevant documentation.
## Why the 3-Tier System
### Traditional Documentation Problems
Standard documentation approaches create friction for AI-assisted development:
- **Context Overload** - AI agents must process entire documentation sets for simple tasks
- **Maintenance Burden** - Every code change cascades to multiple documentation locations
- **Stale Content** - Documentation diverges from implementation reality
- **No AI Optimization** - Human-readable formats lack structure for machine processing
### The 3-Tier Solution
The kit solves these problems through hierarchical organization:
**Tier 1: Foundation (Rarely Changes)**
- Project-wide standards, architecture decisions, technology stack
- Auto-loads for every AI session
- Provides consistent baseline without redundancy
- Uses CLAUDE.md as the master context file
**Tier 2: Component (Occasionally Changes)**
- Component boundaries, architectural patterns, integration points
- Loads only when working within specific components
- Isolates architectural decisions from implementation details
- Uses CONTEXT.md files at component roots
**Tier 3: Feature (Frequently Changes)**
- Implementation specifics, technical details, local patterns
- Co-located with code for immediate updates
- Minimizes documentation cascade when code changes
- Uses CONTEXT.md files within feature directories
## Benefits vs Traditional Systems
### 1. Intelligent Context Loading
**Traditional**: AI loads entire documentation corpus regardless of task
**3-Tier**: Commands load only relevant tiers based on complexity
Example:
- Simple query → Tier 1 only (minimal tokens)
- Component work → Tier 1 + relevant Tier 2
- Deep implementation → All relevant tiers
### 2. Maintenance Efficiency
**Traditional**: Update multiple documents for each change
**3-Tier**: Updates isolated to appropriate tier
Example:
- API endpoint change → Update only Tier 3 API documentation
- New component → Add Tier 2 documentation, Tier 1 unchanged
- Coding standard → Update only Tier 1, applies everywhere
### 3. AI Performance Optimization
**Traditional**: AI struggles to find relevant information
**3-Tier**: Structured hierarchy guides AI to precise context
The system provides:
- Clear routing logic for agent navigation
- Predictable documentation locations
- Efficient token usage through targeted loading
## Integration with Kit Components
### Command Integration
Commands leverage the 3-tier structure for intelligent operation:
```
Command Execution → Analyze Task Complexity → Load Appropriate Tiers
↓
Simple: Tier 1 only
Component: Tiers 1-2
Complex: All relevant tiers
```
### MCP Server Integration
External AI services receive proper context through the tier system:
- **Gemini Consultations** - Auto-attach `project-structure.md` (Tier 1)
- **Context7 Lookups** - Happen within established project context
- **Recommendations** - Align with documented architecture
### Multi-Agent Routing
The documentation structure determines agent behavior:
- Number of agents spawned based on tiers involved
- Each agent receives targeted documentation subset
- Parallel analysis without context overlap
## Key Files and Their Roles
### Foundation Files (ai-context/)
**docs-overview.md**
- Template for implementing 3-tier documentation
- Maps documentation structure for AI navigation
- [View Template](ai-context/docs-overview.md)
**project-structure.md**
- Complete technology stack and file organization
- Required reading for all AI agents
- Auto-attaches to Gemini consultations
- [View Template](ai-context/project-structure.md)
**system-integration.md**
- Cross-component communication patterns
- Integration architectures for multi-agent analysis
- [View Template](ai-context/system-integration.md)
**deployment-infrastructure.md**
- Infrastructure patterns and constraints
- Deployment context for AI recommendations
- [View Template](ai-context/deployment-infrastructure.md)
**handoff.md**
- Session continuity between AI interactions
- Task state preservation
- [View Template](ai-context/handoff.md)
### Context Templates
**CLAUDE.md** (Tier 1)
- Master AI context with coding standards
- Project-wide instructions and patterns
- [View Template](CLAUDE.md)
**CONTEXT-tier2-component.md**
- Component-level architectural context
- [View Template](CONTEXT-tier2-component.md)
**CONTEXT-tier3-feature.md**
- Feature-specific implementation details
- [View Template](CONTEXT-tier3-feature.md)
## Implementation Strategy
### 1. Start with Templates
Use provided templates as foundation:
- Copy and customize for your project
- Maintain consistent structure
- Focus on AI-consumable formatting
### 2. Follow Natural Boundaries
Let your architecture guide tier placement:
- Stable decisions → Tier 1
- Component design → Tier 2
- Implementation details → Tier 3
### 3. Co-locate Documentation
Place CONTEXT.md files with related code:
```
backend/
├── CONTEXT.md # Backend architecture (Tier 2)
└── src/
└── api/
└── CONTEXT.md # API implementation (Tier 3)
```
### 4. Maintain Hierarchy
Ensure clear relationships:
- Tier 3 references Tier 2 patterns
- Tier 2 follows Tier 1 standards
- No circular dependencies
### 5. Use Documentation Commands
The kit provides commands to manage documentation:
- **`/create-docs`** - Generate initial documentation structure for projects without existing docs
- **`/update-docs`** - Regenerate and update documentation after code changes to keep everything current
## Measuring Success
The 3-tier system succeeds when:
1. **AI agents find context quickly** - No searching through irrelevant documentation
2. **Updates stay localized** - Changes don't cascade unnecessarily
3. **Documentation stays current** - Co-location ensures updates happen
4. **Commands work efficiently** - Appropriate context loads automatically
5. **MCP servers provide relevant advice** - External AI understands your project
---
*Part of the Claude Code Development Kit - see [main documentation](../README.md) for complete system overview.*

179
node_modules/@zenuml/core/docs/UNICODE_SUPPORT.md generated vendored Normal file
View File

@@ -0,0 +1,179 @@
# Unicode 字符支持
ZenUML 现在完全支持 Unicode 字符，包括中文、日文、韩文、阿拉伯文、俄文等多种语言的标识符。
## 功能特性
### 1. 直接使用 Unicode 字符作为标识符
您可以直接使用任何 Unicode 字母字符作为：
- 参与者名称
- 方法名称
- 变量名称
- 参数名称
**示例：**
```zenuml
// 中文标识符
用户 订单服务 数据库
用户.登录()
订单服务.创建订单()
数据库.保存数据()
return 成功
```
### 2. 包含空格的文本使用引号
如果标识符中需要包含空格或特殊字符，请使用双引号：
```zenuml
// 使用引号处理包含空格的名称
"用户 服务" "订单 管理系统"
"用户 服务"."获取 用户信息"()
"订单 管理系统"."创建 新订单"()
return "操作 成功"
```
### 3. 中英文混合支持
您可以自由混合使用中文和英文：
```zenuml
UserService 数据库 CacheManager
UserService.获取用户()
数据库.query("SELECT * FROM users")
CacheManager.缓存结果()
```
## 支持的 Unicode 范围
当前实现支持所有 Unicode 字母字符，包括但不限于：
- **中文**：汉字字符
- **日文**：平假名、片假名、汉字
- **韩文**：韩文字母
- **阿拉伯文**：阿拉伯字母
- **俄文**：西里尔字母
- **其他**：所有 Unicode 定义的字母字符
## 使用规则
1. **标识符规则**：
- 必须以 Unicode 字母或下划线 `_` 开头
- 可以包含 Unicode 字母、数字和下划线
- 不能包含空格（需要空格请使用引号）
2. **引号字符串**：
- 可以包含任何字符（除了换行符）
- 适用于包含空格或特殊字符的文本
3. **保留关键字**：
- 英文关键字（如 `if`, `while`, `return` 等）保持不变
- 不能使用保留关键字作为标识符
## 实际应用示例
### 示例 1：订单处理流程
```zenuml
title "订单处理流程"
@Actor 用户
@Service 订单服务
@Database 数据库
用户->订单服务: 创建订单
订单服务.验证订单() {
if (库存充足) {
数据库.保存订单()
return "订单创建成功"
} else {
return "库存不足"
}
}
```
### 示例 2：用户认证流程
```zenuml
用户 认证服务 令牌管理器
用户.登录(用户名, 密码)
认证服务.验证凭据(用户名, 密码) {
if (验证成功) {
令牌 = 令牌管理器.生成令牌()
return 令牌
} else {
return "认证失败"
}
}
```
### 示例 3：多语言混合
```zenuml
// 混合多种语言的示例
ユーザー // 日文
사용자 // 韩文
用户 // 中文
User // 英文
ユーザー.ログイン()
사용자.로그인()
用户.登录()
User.login()
```
## 技术实现
### 词法分析器更改
在 `SequenceLexer.g4` 中，ID token 定义已更新为：
```antlr
ID
: [\p{L}_] [\p{L}\p{Nd}_]*
;
```
- `\p{L}` 匹配任何 Unicode 字母
- `\p{Nd}` 匹配任何 Unicode 十进制数字
- 保持了对下划线 `_` 的支持
### 向后兼容性
所有现有的 ASCII 标识符仍然完全支持：
- 英文字母 (a-z, A-Z)
- 数字 (0-9)
- 下划线 (_)
现有的 ZenUML 代码无需任何修改即可继续工作。
## 测试
您可以通过以下方式测试 Unicode 支持：
1. **开发服务器测试**：
```bash
pnpm dev
```
然后访问 http://localhost:8080/test-chinese.html
2. **单元测试**：
```bash
pnpm test src/parser/ChineseSupport.spec.ts
```
## 注意事项
1. **编码**：确保您的文件使用 UTF-8 编码保存
2. **字体支持**：渲染时需要系统或浏览器支持相应的字体
3. **方向性**：某些语言（如阿拉伯文）是从右到左书写，但在 ZenUML 中仍按从左到右的顺序处理
## 贡献
如果您发现任何 Unicode 相关的问题或有改进建议，欢迎提交 issue 或 pull request。

21
node_modules/@zenuml/core/docs/ai-context/deployment-infrastructure.md generated vendored Normal file
View File

@@ -0,0 +1,21 @@
# Deployment & Infrastructure Documentation
This document contains deployment and infrastructure-related documentation for the project.
## Purpose
This template serves as a placeholder for documenting:
- Deployment strategies and procedures
- Infrastructure architecture and configuration
- CI/CD pipelines and automation
- Environment management
- Monitoring and observability setup
- Scaling strategies and considerations
## Implementation Note
Replace this template with your actual deployment and infrastructure documentation as your project develops. Focus on patterns and decisions that AI agents need to understand when working with infrastructure-related code or making architectural recommendations.
---
*Customize this template based on your specific deployment and infrastructure requirements.*

89
node_modules/@zenuml/core/docs/ai-context/docs-overview.md generated vendored Normal file
View File

@@ -0,0 +1,89 @@
# Documentation Architecture
This project uses a **3-tier documentation system** that organizes knowledge by stability and scope, enabling efficient AI context loading and scalable development.
## How the 3-Tier System Works
**Tier 1 (Foundation)**: Stable, system-wide documentation that rarely changes - architectural principles, technology decisions, cross-component patterns, and core development protocols.
**Tier 2 (Component)**: Architectural charters for major components - high-level design principles, integration patterns, and component-wide conventions without feature-specific details.
**Tier 3 (Feature-Specific)**: Granular documentation co-located with code - specific implementation patterns, technical details, and local architectural decisions that evolve with features.
This hierarchy allows AI agents to load targeted context efficiently while maintaining a stable foundation of core knowledge.
## Documentation Principles
- **Co-location**: Documentation lives near relevant code
- **Smart Extension**: New documentation files created automatically when warranted
- **AI-First**: Optimized for efficient AI context loading and machine-readable patterns
## Tier 1: Foundational Documentation (System-Wide)
- **[Master Context](/CLAUDE.md)** - *Essential for every session.* Coding standards, security requirements, MCP server integration patterns, and development protocols
- **[Project Structure](/docs/ai-context/project-structure.md)** - *REQUIRED reading.* Complete technology stack, file tree, and system architecture. Must be attached to Gemini consultations
- **[System Integration](/docs/ai-context/system-integration.md)** - *For cross-component work.* Communication patterns, data flow, testing strategies, and performance optimization
- **[Deployment Infrastructure](/docs/ai-context/deployment-infrastructure.md)** - *Infrastructure patterns.* Containerization, monitoring, CI/CD workflows, and scaling strategies
- **[Task Management](/docs/ai-context/handoff.md)** - *Session continuity.* Current tasks, documentation system progress, and next session goals
## Tier 2: Component-Level Documentation
### Backend Components
- **[Backend Context](/backend/CONTEXT.md)** - *Server implementation.* API patterns, database integration, service architecture, and performance considerations
- **[Worker Services](/workers/CONTEXT.md)** - *Background processing.* Job queue patterns, scheduling, and async task management
- **[Shared Libraries](/shared/CONTEXT.md)** - *Reusable code.* Common utilities, shared types, and cross-component functionality
### Frontend Components
- **[Web Application](/frontend/CONTEXT.md)** - *Client implementation.* UI patterns, state management, routing, and user interaction patterns
- **[Mobile Application](/mobile/CONTEXT.md)** - *Mobile implementation.* Platform-specific patterns, native integrations, and mobile optimizations
- **[Admin Dashboard](/admin/CONTEXT.md)** - *Administrative interface.* Permission patterns, admin workflows, and management tools
### Infrastructure Components
- **[Infrastructure Code](/infrastructure/CONTEXT.md)** - *IaC patterns.* Terraform/CloudFormation templates, resource definitions, and deployment automation
- **[Monitoring Setup](/monitoring/CONTEXT.md)** - *Observability patterns.* Metrics collection, alerting rules, and dashboard configurations
## Tier 3: Feature-Specific Documentation
Granular CONTEXT.md files co-located with code for minimal cascade effects:
### Backend Feature Documentation
- **[Core Services](/backend/src/core/services/CONTEXT.md)** - *Business logic patterns.* Service architecture, data processing, integration patterns, and error handling
- **[API Layer](/backend/src/api/CONTEXT.md)** - *API patterns.* Endpoint design, validation, middleware, and request/response handling
- **[Data Layer](/backend/src/data/CONTEXT.md)** - *Data patterns.* Database models, queries, migrations, and data access patterns
- **[Authentication](/backend/src/auth/CONTEXT.md)** - *Auth patterns.* Authentication flows, authorization rules, session management, and security
- **[Integrations](/backend/src/integrations/CONTEXT.md)** - *External services.* Third-party API clients, webhook handlers, and service adapters
### Frontend Feature Documentation
- **[UI Components](/frontend/src/components/CONTEXT.md)** - *Component patterns.* Reusable components, styling patterns, accessibility, and composition strategies
- **[State Management](/frontend/src/store/CONTEXT.md)** - *State patterns.* Global state, local state, data flow, and persistence strategies
- **[API Client](/frontend/src/api/CONTEXT.md)** - *Client patterns.* HTTP clients, error handling, caching, and data synchronization
- **[Routing](/frontend/src/routes/CONTEXT.md)** - *Navigation patterns.* Route definitions, guards, lazy loading, and deep linking
- **[Utilities](/frontend/src/utils/CONTEXT.md)** - *Helper functions.* Formatters, validators, transformers, and common utilities
### Shared Feature Documentation
- **[Common Types](/shared/src/types/CONTEXT.md)** - *Type definitions.* Shared interfaces, enums, and type utilities
- **[Validation Rules](/shared/src/validation/CONTEXT.md)** - *Validation patterns.* Schema definitions, custom validators, and error messages
- **[Constants](/shared/src/constants/CONTEXT.md)** - *Shared constants.* Configuration values, enums, and magic numbers
- **[Utilities](/shared/src/utils/CONTEXT.md)** - *Shared utilities.* Cross-platform helpers, formatters, and common functions
## Adding New Documentation
### New Component
1. Create `/new-component/CONTEXT.md` (Tier 2)
2. Add entry to this file under appropriate section
3. Create feature-specific Tier 3 docs as features develop
### New Feature
1. Create `/component/src/feature/CONTEXT.md` (Tier 3)
2. Reference parent component patterns
3. Add entry to this file under component's features
### Deprecating Documentation
1. Remove obsolete CONTEXT.md files
2. Update this mapping document
3. Check for broken references in other docs
---
*This documentation architecture template should be customized to match your project's actual structure and components. Add or remove sections based on your architecture.*

174
node_modules/@zenuml/core/docs/ai-context/handoff.md generated vendored Normal file
View File

@@ -0,0 +1,174 @@
# Task Management & Handoff Template
This file manages task continuity, session transitions, and knowledge transfer for AI-assisted development sessions.
## Purpose
This template helps maintain:
- **Session continuity** between AI development sessions
- **Task status tracking** for complex, multi-session work
- **Context preservation** when switching between team members
- **Knowledge transfer** for project handoffs
- **Progress documentation** for ongoing development efforts
## Current Session Status
### Active Tasks
Document currently in-progress work:
```markdown
## In Progress
- [ ] Task 1: [Brief description]
- Status: [Started/Blocked/Awaiting review]
- Context: [Relevant files, decisions made]
- Next steps: [What needs to be done next]
- Dependencies: [What this task depends on]
- [ ] Task 2: [Brief description]
- Status: [Current status]
- Files modified: [List of files changed]
- Challenges: [Any issues encountered]
- Notes: [Important context for continuation]
```
### Pending Tasks
Document queued work:
```markdown
## Pending
- [ ] Task A: [Description]
- Priority: [High/Medium/Low]
- Dependencies: [What must be completed first]
- Estimated effort: [Time estimate]
- Context: [Background information]
- [ ] Task B: [Description]
- Priority: [Priority level]
- Requirements: [Specific requirements or constraints]
- Resources needed: [Tools, access, information needed]
```
### Completed Tasks
Track completed work for context:
```markdown
## Completed This Session
- [x] Task X: [Description]
- Completed: [Date]
- Outcome: [What was accomplished]
- Files changed: [Modified files]
- Notes: [Important decisions or lessons learned]
- [x] Task Y: [Description]
- Completed: [Date]
- Impact: [How this affects other tasks]
- Follow-up needed: [Any follow-up actions required]
```
## Architecture & Design Decisions
### Recent Decisions
Document architectural decisions made during development:
```markdown
## Design Decisions Made
- **Decision**: [What was decided]
- Date: [When decision was made]
- Rationale: [Why this approach was chosen]
- Alternatives considered: [Other options evaluated]
- Impact: [How this affects the system]
- Validation: [How to verify this was the right choice]
- **Decision**: [Another decision]
- Context: [Situation that led to this decision]
- Trade-offs: [What was gained/lost with this choice]
- Dependencies: [What this decision depends on]
```
### Technical Debt & Issues
Track technical debt and known issues:
```markdown
## Technical Debt Identified
- **Issue**: [Description of technical debt]
- Location: [Where in codebase]
- Impact: [How it affects development/performance]
- Proposed solution: [How to address it]
- Priority: [When should this be addressed]
- **Issue**: [Another issue]
- Root cause: [Why this debt exists]
- Workaround: [Current mitigation strategy]
- Long-term fix: [Proper solution approach]
```
## Next Session Goals
### Immediate Priorities
Define what should be tackled next:
```markdown
## Next Session Priorities
1. **Primary Goal**: [Main objective for next session]
- Success criteria: [How to know this is complete]
- Prerequisites: [What must be ready beforehand]
- Estimated effort: [Time estimate]
2. **Secondary Goal**: [Secondary objective]
- Dependencies: [What this depends on]
- Resources needed: [Tools, information, access required]
3. **If Time Permits**: [Optional tasks]
- Context: [Background on why these are valuable]
- Preparation: [What needs to be done to start these]
```
### Knowledge Gaps
Document areas needing research or clarification:
```markdown
## Knowledge Gaps to Address
- **Question**: [What needs to be clarified]
- Impact: [How this affects current work]
- Research needed: [What investigation is required]
- Decision maker: [Who can answer this]
- **Unknown**: [Technical uncertainty]
- Options: [Possible approaches to explore]
- Experiments: [What should be tested]
- Timeline: [When this needs to be resolved]
```
## Context for Continuation
### Key Files & Components
Document important files for session continuity:
```markdown
## Files Currently Being Modified
- `[file-path]`: [Purpose and current changes]
- `[file-path]`: [What's being implemented here]
- `[file-path]`: [Status and next steps]
## Important Context Files
- `[context-file]`: [Why this is relevant]
- `[documentation]`: [What information this contains]
- `[reference]`: [How this relates to current work]
```
### Development Environment
Document environment and setup considerations:
```markdown
## Environment Status
- **Development setup**: [Current state of dev environment]
- **Database**: [Schema changes, migrations, data state]
- **External services**: [API keys, service configurations]
- **Testing**: [Test suite status, coverage, failing tests]
- **Build/Deploy**: [Build status, deployment considerations]
```
---
*This template provides a comprehensive framework for managing task continuity and knowledge transfer. Customize it based on your team's workflow, project complexity, and communication needs.*

160
node_modules/@zenuml/core/docs/ai-context/project-structure.md generated vendored Normal file
View File

@@ -0,0 +1,160 @@
# Project Structure Template
This document provides a template for documenting the complete technology stack and file tree structure for your project. **AI agents MUST read this file to understand the project organization before making any changes.**
## Technology Stack Template
### Backend Technologies
Document your backend technology choices:
- **[Language] [Version]** with **[Package Manager]** - Dependency management and packaging
- **[Web Framework] [Version]** - Web framework with specific features (async, type hints, etc.)
- **[Server] [Version]** - Application server configuration
- **[Configuration] [Version]** - Configuration management approach
Example:
```
- Python 3.11+ with Poetry - Dependency management and packaging
- FastAPI 0.115.0+ - Web framework with type hints and async support
- Uvicorn 0.32.0+ - ASGI server with standard extras
- Pydantic Settings 2.5.2+ - Configuration management with type validation
```
### Integration Services & APIs
Document external services and integrations:
- **[Service Name] [API/SDK Version]** - Purpose and usage pattern
- **[AI Service] [Version]** - AI/ML service integration details
- **[Database] [Version]** - Data storage and management
- **[Monitoring] [Version]** - Observability and logging
### Real-time Communication
Document real-time features:
- **[WebSocket Library]** - Real-time communication patterns
- **[HTTP Client]** - Async HTTP communication
- **[Message Queue]** - Event processing (if applicable)
### Development & Quality Tools
Document development toolchain:
- **[Formatter] [Version]** - Code formatting
- **[Linter] [Version]** - Code quality and linting
- **[Type Checker] [Version]** - Static type checking
- **[Testing Framework] [Version]** - Testing approach
- **[Task Runner]** - Build automation and task orchestration
### Frontend Technologies (if applicable)
Document frontend technology stack:
- **[Language] [Version]** - Frontend development language
- **[Framework] [Version]** - UI framework
- **[Build Tool] [Version]** - Development and build tooling
- **[Deployment] [Version]** - Deployment and hosting approach
### Future Technologies
Document planned technology additions:
- **[Planned Technology]** - Future integration plans
- **[Platform]** - Target platform expansion
- **[Service]** - Planned service integrations
## Complete Project Structure Template
```
[PROJECT-NAME]/
├── README.md # Project overview and setup
├── CLAUDE.md # Master AI context file
├── [BUILD-FILE] # Build configuration (Makefile, package.json, etc.)
├── .gitignore # Git ignore patterns
├── .[IDE-CONFIG]/ # IDE workspace configuration
│ ├── settings.[ext] # IDE settings
│ ├── extensions.[ext] # Recommended extensions
│ └── launch.[ext] # Debug configurations
├── [BACKEND-DIR]/ # Backend application
│ ├── CONTEXT.md # Backend-specific AI context
│ ├── src/ # Source code
│ │ ├── config/ # Configuration management
│ │ │ └── settings.[ext] # Application settings
│ │ ├── core/ # Core business logic
│ │ │ ├── CONTEXT.md # Core logic patterns
│ │ │ ├── services/ # Business services
│ │ │ │ ├── [service1].[ext] # Service implementations
│ │ │ │ └── [service2].[ext]
│ │ │ ├── models/ # Data models
│ │ │ │ ├── [model1].[ext] # Model definitions
│ │ │ │ └── [model2].[ext]
│ │ │ └── utils/ # Utility functions
│ │ │ ├── logging.[ext] # Structured logging
│ │ │ ├── validation.[ext] # Input validation
│ │ │ └── helpers.[ext] # Helper functions
│ │ ├── api/ # API layer
│ │ │ ├── CONTEXT.md # API patterns and conventions
│ │ │ ├── routes/ # API route definitions
│ │ │ │ ├── [resource1].[ext] # Resource-specific routes
│ │ │ │ └── [resource2].[ext]
│ │ │ ├── middleware/ # API middleware
│ │ │ │ ├── auth.[ext] # Authentication middleware
│ │ │ │ ├── logging.[ext] # Request logging
│ │ │ │ └── validation.[ext] # Request validation
│ │ │ └── schemas/ # Request/response schemas
│ │ │ ├── [schema1].[ext] # Data schemas
│ │ │ └── [schema2].[ext]
│ │ └── integrations/ # External service integrations
│ │ ├── CONTEXT.md # Integration patterns
│ │ ├── [service1]/ # Service-specific integration
│ │ │ ├── client.[ext] # API client
│ │ │ ├── models.[ext] # Integration models
│ │ │ └── handlers.[ext] # Response handlers
│ │ └── [service2]/
│ ├── tests/ # Test suite
│ │ ├── unit/ # Unit tests
│ │ ├── integration/ # Integration tests
│ │ └── fixtures/ # Test fixtures and data
│ ├── [PACKAGE-FILE] # Package configuration
│ └── [ENV-FILE] # Environment configuration
├── [FRONTEND-DIR]/ # Frontend application (if applicable)
│ ├── CONTEXT.md # Frontend-specific AI context
│ ├── src/ # Source code
│ │ ├── components/ # UI components
│ │ │ ├── CONTEXT.md # Component patterns
│ │ │ ├── common/ # Shared components
│ │ │ └── [feature]/ # Feature-specific components
│ │ ├── pages/ # Page components/routes
│ │ │ ├── [page1].[ext] # Page implementations
│ │ │ └── [page2].[ext]
│ │ ├── stores/ # State management
│ │ │ ├── CONTEXT.md # State management patterns
│ │ │ ├── [store1].[ext] # Store implementations
│ │ │ └── [store2].[ext]
│ │ ├── api/ # API client layer
│ │ │ ├── CONTEXT.md # Client patterns
│ │ │ ├── client.[ext] # HTTP client setup
│ │ │ └── endpoints/ # API endpoint definitions
│ │ ├── utils/ # Utility functions
│ │ │ ├── logging.[ext] # Client-side logging
│ │ │ ├── validation.[ext] # Form validation
│ │ │ └── helpers.[ext] # Helper functions
│ │ └── assets/ # Static assets
│ ├── tests/ # Frontend tests
│ ├── [BUILD-CONFIG] # Build configuration
│ └── [PACKAGE-FILE] # Package configuration
├── docs/ # Documentation
│ ├── ai-context/ # AI-specific documentation
│ │ ├── project-structure.md # This file
│ │ ├── docs-overview.md # Documentation architecture
│ │ ├── system-integration.md # Integration patterns
│ │ ├── deployment-infrastructure.md # Infrastructure docs
│ │ └── handoff.md # Task management
│ ├── api/ # API documentation
│ ├── deployment/ # Deployment guides
│ └── development/ # Development guides
├── scripts/ # Automation scripts
│ ├── setup.[ext] # Environment setup
│ ├── deploy.[ext] # Deployment scripts
│ └── maintenance/ # Maintenance scripts
├── [INFRASTRUCTURE-DIR]/ # Infrastructure as code (if applicable)
│ ├── [PROVIDER]/ # Cloud provider configurations
│ ├── docker/ # Container configurations
│ └── monitoring/ # Monitoring and alerting
└── [CONFIG-FILES] # Root-level configuration files
```
---
*This template provides a comprehensive foundation for documenting project structure. Adapt it based on your specific technology stack, architecture decisions, and organizational requirements.*

21
node_modules/@zenuml/core/docs/ai-context/system-integration.md generated vendored Normal file
View File

@@ -0,0 +1,21 @@
# System Integration Documentation
This document contains cross-component integration patterns and system-wide architectural decisions.
## Purpose
This template serves as a placeholder for documenting:
- Cross-component communication patterns
- Data flow architectures between services
- Integration strategies with external systems
- Performance optimization patterns
- Testing strategies for integrated systems
- Error handling across service boundaries
## Implementation Note
Replace this template with your actual system integration documentation as your project develops. Focus on patterns that AI agents need to understand when working across component boundaries or implementing features that span multiple services.
---
*Customize this template based on your specific integration patterns and architectural requirements.*

54
node_modules/@zenuml/core/docs/asciidoc/contributor.adoc generated vendored Normal file
View File

@@ -0,0 +1,54 @@
== Audience
:icons: font
This document is written for the contributors. If you want to integrate ZenUML in your application,
you should read index.adoc; if you want to create themes, you should read create-my-own-theme.adoc.
== Build
This project is built with vue cli. It has two types of target: the web application and the library.
....
# to build the library
yarn build
# to build the web application
yarn build:site
....
== Demo pages
In the public folder, there are some demo pages for testing the library.
=== How do they work?
The demo pages^1^ are built with vue cli service. On the page, there needs to be a `pre`
element with class `zenuml` and the content being the ZenUML DSL code.
For example:
[source, html]
....
<pre class="zenuml">
A.method
</pre>
....
The entry point of the demo pages is `src/main.ts`. It will find all the `pre` elements with
class `zenuml` and render the ZenUML DSL code in it.
== Parser
We use antlr4 to parse the ZenUML DSL code. The grammar files are:
1. Parser: `./src/g4/sequenceParser.g4`
2. Lexer: `./src/g4/sequenceLexer.g4`
=== How to generate the parser and lexer
Run `yarn antlr4` to generate the parser and lexer.
=== Setup local development environment
Run `yarn antlr:setup` (`python3 -m pip install antlr4-tools`) to install the antlr4 command and the runtime.
To test the setup, go to `src/g4-unit/hello-world` folder, and run:
1.

149
node_modules/@zenuml/core/docs/asciidoc/create-my-own-theme.adoc generated vendored Normal file
View File

@@ -0,0 +1,149 @@
= Creat my own theme
Since the elements on the rendered diagram is based on HTML Dom (and svg), it is simple
to create your own theme. There is a repository on GitHub that have some themes collected
by third party. You may be able to get some inspiration from there. https://github.com/abruzzi/zenuml-css-overrides
== The Information Architecture
image::./images/three-layer-info-arch.png[width=600]
The diagram is rendered in two layers. The back layer is the lifeline layer. The front layer
is the message layer.
Key information on the diagram can be grouped in the following structure:
Text messages are internally styled at four levels:
1. text-skin-base: used for all messages
2. text-skin-muted: used for comments
3. text-skin-link: used for links
4. text-skin-secondary: used for everything else, such as title, participant, divider notes, etc.
When it comes to branding, the following elements are the most important:
1. Canvas background, however, it can easily be overwhelming if you use high contrast color to the
overall page background.
2. Title background, participant background and fragment header background are the most attractive
elements to brand. These are where your brand color should be used.
3. The background of the occurrence (message bar) is also a good place to use your brand color, but
less attractive than the above three.
4. The borders of the frame, participant, fragment, occurrence and lifeline can add a bit
of color to the diagram.
5. The color of the message and the arrow are the most important information on
the diagram. Choose a striking and comfortable color for them. You can use the brand color here, but
they should not be the only elements that reflect your brand color. Same principles apply to the
background and text color for hover state.
6. Then is the color of link and control. They should avoid attracting too much attention
[%autowidth]
|===
|Category | Diagram Frame |Lifeline Layer | Message Layer
h|Text Info
a|* Title
* Brand
a|* Participant name
* Stereotype
* Comment
a|* Message name
* Fragment type
* Fragment condition
* Comment
* Divider name
h|Shapes
a|* Security (icon)
* Tips (icon)
a|* Participant box (rectangle)
* Lifeline (vertical line)
a|* Message arrow (line and head)
* Fragment (rectangle)
* Divider line (left and right)
|===
Each of the elements has a semantic selector that can be used to customize the appearance.
The component has basic styling in itself mostly to support layout and positioning. Then
the core renderer comes with a default theme that defines the appearance of the elements.
[source,css]
----
----
A typical custom theme will be like below:
[source,css]
----
----
== What can a theme change?
A theme can change two aspects of the diagram:
1. colors
2. slightly change the layout (e.g. padding, margin, etc.). For example, you can make the
diagram more compact by reducing the padding.
== where can I apply themes
You can apply themes on the follow products:
. JetBrains plugins (Intellij IDEA, WebStore, PhpStore, etc.)
. https://app.zenuml.com
With https://chrome.google.com/webstore/detail/user-css/okpjlejfhacmgjkmknjhadmkdbcldfcb[User CSS]
browser extension, you can apply themes anywhere (e.g. https://zenuml.cn).
== Principles of creating themes
=== 1. Do not override tailwind classes
The tailwind classes directly applied on the elements are important for layout so
they are NOT meant be overridden.
For example,
[html]
....
// Participant.vue
<div class="participant relative flex flex-col justify-center z-10 h-10"
....
=== 2. Use provided class selectors
Important elements are provided with a semantic class selector. You can use them
to override the style.
For the above example, the class selector is `participant`. You can override the
style by using this selector.
[css]
....
// use `.zenuml .sequence-diagram` to increase specificity
.zenuml .sequence-diagram .participant {
background-color: #f00;
}
....
=== 3. Debug your theme
You can use the browser extension https://chrome.google.com/webstore/detail/user-css/okpjlejfhacmgjkmknjhadmkdbcldfcb[User CSS]
to debug your theme.
image::user-css.png[User CSS]
Alternatively, you can use our web app https://app.zenuml.com[app.zenuml.com]. Go to the CSS tab
and paste your theme there. You can see the result immediately.
image::theme-debug-web-app.png[]
=== JetBrains
=== app.zenuml.com
== Tips
=== Give occurrence a boarder

BIN
node_modules/@zenuml/core/docs/asciidoc/images/creation-component.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
node_modules/@zenuml/core/docs/asciidoc/images/creation-rtl.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
node_modules/@zenuml/core/docs/asciidoc/images/message-arrow-rtl.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
node_modules/@zenuml/core/docs/asciidoc/images/occurrence.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 86 KiB

BIN
node_modules/@zenuml/core/docs/asciidoc/images/return-message-conflict.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
node_modules/@zenuml/core/docs/asciidoc/images/shift-up-half-the-height.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.3 KiB

BIN
node_modules/@zenuml/core/docs/asciidoc/images/three-layer-info-arch.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 510 KiB

1
node_modules/@zenuml/core/docs/asciidoc/images/vertical-alignment.svg generated vendored Normal file
View File

@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 202.624 202.624" style="enable-background:new 0 0 202.624 202.624" xml:space="preserve"><path d="M202.621 97.416h-38.966V58.45a3.896 3.896 0 0 0-3.897-3.897h-38.966a3.896 3.896 0 0 0-3.897 3.897v38.966H85.724V35.07a3.896 3.896 0 0 0-3.897-3.897H42.862a3.896 3.896 0 0 0-3.897 3.897v62.345H0v7.793h38.966v62.345a3.896 3.896 0 0 0 3.897 3.897h38.966a3.896 3.896 0 0 0 3.897-3.897v-62.345h31.172v38.966a3.896 3.896 0 0 0 3.897 3.897h38.966a3.896 3.896 0 0 0 3.897-3.897v-38.966h38.966v-7.793h-.003zm-124.69 0v66.241H46.759V38.968h31.172v58.448zm77.931 0v42.862H124.69V62.346h31.172v35.07z"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 647 B

BIN
node_modules/@zenuml/core/docs/asciidoc/images/vertically-aligning.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.6 KiB

277
node_modules/@zenuml/core/docs/asciidoc/index.adoc generated vendored Normal file
View File

@@ -0,0 +1,277 @@
:icons: font
== Font
Font [.underline]#must# be *preloaded*. Font mainly have impact to Creation
rendering. The font will impact the width of the participant box which then
impacts the with of message container for creation.
The following code should help with preloading google fonts. But it is not super
reliable. Specifically, when you disable cache in Chrome. It is not preloaded
where you can see the impact.
....
<link rel='preconnect' href='https://fonts.gstatic.com' crossorigin>
<link rel='preload stylesheet' as='style' href='https://fonts.googleapis.com/css2?family=Roboto+Slab:wght@300;400;500;700&display=swap'>
....
We have to use `setTimeout` to delay the calculation of the width of the
message container.
== The two layer structure
At the highest level, the diagram is rendered in two layers:
the lifeline layer and the message layer.
....
<div class="sequence-diagram">
<div class="life-line-layer absolute h-full">
</div>
<div class="message-layer">
</div>
</div>
....
=== Key classes
==== .absolute
The `absolute` class is used to remove the lifeline layer from the normal
flow of the document.
==== .h-full
The `h-full` class is used to make the lifeline layer as tall as the parent
element. The parent element get the height from the `message-layer`.
== The message layer
=== Occurrence
_TODO_: explain misalignment of the occurrence concept and the spec.
image::images/occurrence.png[width=304,alt="occurrence"]
The occurrence is the bar (or invisible bar for async messages) that
represents the execution of a message.
It has a width of 15px and border of 2px. These two values #must not#
be overridden in themes.
It has a padding-left of 5px which pushes the children `interaction` to
the middle of the occurrence.
....
(occurrenceWidth - occurrenceBorderWidth x 2 - lifelineWidth) / 2
= (15 - 2 x 2 - 1) / 2
= 5
....
Because the lifeline has width of 1px, for normal (left to right) `interaction` s
we give it a margin left of 1px to avoid the overlap of the lifeline and the
interaction border. See `interaction` for more details.
=== Interaction
The `interaction` is one of the key conceptual elements. It works with
the `occurrence` to influence high-level layout. The `interaction` is the container
of the message, children interactions and the response.
The `interaction` has a border of 5px. This value #must not# be overridden in themes.
....
(occurrenceWidth - occurrenceBorderWidth x 2 - lifelineWidth) / 2
= (15 - 2 x 2 - 1) / 2
= 5
....
Within Interaction, the DOM structure is like below:
....
<div class="interaction">
<div class="occurrence source"></div>
<comment/>
<invocation/> <1>
<occurrence/>
<message type="return">
</div>
....
<1> SelfInvocation or Message
==== Do not add margin to interaction
It is on purpose that interaction box overlaps source lifeline but not the target
lifeline. Do not add #margin# to interaction components. This margin will cause
interaction's right board overlaps target lifeline and that is accumulative.
==== Debugging
Disable transparency of the interaction borders.
=== Common features among Interaction, Interaction and Creation
All the three work as a container for the message, children interactions and the
response. In the normal direction (left to right), they start with the middle
of the source lifeline and end with the middle of the target lifeline.
=== Return message
The return message is the message that is sent back to the sender of the original
message. It is rendered as a dashed line.
A return message is rendered from three syntax:
* `return x` which matches `RETURN expr? SCOL?`
* `@return A->B: ret` which matches `ANNOTATION_RET asyncMessage EVENT_END?`
* `x=A.m` or `x=new A()` which matches `assignment? ((from ARROW)? to DOT)? func` or `assignment? NEW construct(OPAR parameters? CPAR)?`
==== Statement `return x` or `@return A->B: ret`
`return x` or `@return A->B: ret` is implemented via the `Return` component.
In such cases, it has its own context and can have a comment. Then it
delegates to `SelfInvocation` or `Message`.
===== When do we need `@return A->B: ret`?
....
Browser->BookController.onPost() {
BookLibService.Borrow(id) {
receipt = process(id)
if (receipt != null) {
return receipt
@return BookController->Browser: receipt
} else {
return null
@return BookController->Browser: 404
}
}
}
....
If the statement is the last statement we set the height of the message to 0px,
so that it does not push the message down further. This is because a return message
does not have children and does not need an occurrence.
....
.statement-container:last-child>.return {
height: 0;
}
....
==== Return message from `x=A.m` or `x=new A`
This is implemented in Interaction and Creation components.
....
<message class="return transform -translate-y-full"/>
....
==== Conflicting return messages
We provide two ways in DSL to represent `return` messages:
....
// option 1
x = A.method
// option 2
A.method() {
return y
}
....
If you use both, we will render both with overlapping. This is on purpose to expose
the conflict to the user.
.Return message conflict
image::images/return-message-conflict.png[width=200,alt="return message conflict"]
=== Message arrow
.Message arrow (the dashed line and arrow head)
image::images/creation-component.png[width=224]
This time we focus on how to align the arrow line and the arrow head.
We use a similar approach as pattern #vertically aligning# with pattern
#shift half the height#. Instead of `items-center` we use `items-end`.
Then we use `translate-y-1/2` to shift the arrow head down half the
height of the arrow head. (See Message.vue)
....
<div class="message flex items-end"
<div class="name flex-grow" style="padding-left: 10px">{{content}}</div>
<point class="flex-shrink-0 transform translate-y-1/2 -my-px" :fill="fill" :rtl="rtl"/>
</div>
....
==== Key classes
===== .flex .items-end
The `flex` and `items-end` classes are used to align the arrow line
and the arrow head at the bottom of the message.
===== .flex-grow
The `flex-grow` class is used to make the message name grow to fill
the available space.
===== .flex-shrink-0
The `flex-shrink-0` class is used to make the arrow head not shrink
when the message name is too long.
===== .transform .translate-y-1/2
The `transform` and `translate-y-1/2` classes are used to shift the
arrow head down half the height of the arrow head.
=== Message arrow right to left
image::images/message-arrow-rtl.png[width=200,alt="message arrow right to left"]
....
<div class="message flex items-end" :class="{'flex-row-reverse': rtl}">
<div class="name flex-grow"
>{{content}}</div>
<point class="flex-shrink-0 transform translate-y-1/2 -my-px"/>
</div>
....
==== Key classes
===== .flex-row-reverse
The `flex-row-reverse` class is used to reverse the order of the name and
the arrow head.
=== Creation
image::images/creation-component.png[width=240]
==== Pattern 1: Vertically aligning
image::images/vertical-alignment.svg[width=40]
....
<div class="flex items-center">
<div class="w-10 h-8 bg-blue-200"></div>
<div class="w-10 h-20 bg-green-200"></div>
</div>
....
==== Pattern 2: Shift half the height
image::images/shift-up-half-the-height.png[width=50]
The message arrow is supposed to point to the middle of the participant
box. It is not he whole message that is aligned with the participant
box. So we have to shift the message up half the height of the message.
....
<div class="flex items-center m-10">
<div class="w-10 h-8 bg-blue-200 transform -translate-y-1/2"></div>
<div class="w-10 h-20 bg-green-200"></div>
</div>
....
This pattern is also used at the arrows. See the image for creation.
=== Creation participant top
While all normal participants have their name boxes at the top of the
diagram, creation participant boxes need to be pushed down to align
with the message arrow.
To implement this, we add a `padding-top` to the containing lifeline
of the corresponding participant.
The padding top is calculated by subtracting the top of message from
the top of participant's original value.
==== Challenge
When the message container is mounted, it does not have the correct
participant box offsetWidth.
=== Creation right to left
image::images/creation-rtl.png[width=240,alt="creation right to left"]
On top of normal Creation, we need to flip the participant placeholder
and the message container. We use the `flex-row-reverse` class to flip.
See "Message right to left" for example using `flex-row-reverse`.

BIN
node_modules/@zenuml/core/docs/asciidoc/theme-debug-web-app.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

22
node_modules/@zenuml/core/docs/asciidoc/tutorial.adoc generated vendored Normal file
View File

@@ -0,0 +1,22 @@
= User's guide
== Audience
This document is written for end users of the software. If you want to integrate
ZenUML into your own application, please refer to the integration guide. If you
want to contribute to the development of ZenUML, please refer to the contributor's
guide.
== Introduction
> A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order.
ZenUML is a tool for creating sequence diagrams from text. It runs completely
in the browser, so you don't need to worry about data privacy or security. See
https://link[data privacy and security] for more information.
++++
<iframe src="https://embed.zenuml.com/smoke-creation.html"></iframe>
++++
== Syntax
=== Participants

BIN
node_modules/@zenuml/core/docs/asciidoc/user-css.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

81
node_modules/@zenuml/core/docs/async-vs-sync-parser-rules.md generated vendored Normal file
View File

@@ -0,0 +1,81 @@
Async:
```
asyncMessage
: source ARROW target COL content
| source (MINUS | ARROW) target?
;
content
: EVENT_PAYLOAD_LXR
;
source
: ID | STRING
;
target
: ID | STRING
;
```
Sync:
```
message
: messageBody (SCOL | braceBlock)?
;
// Order of 'func | (to DOT)' is important. Otherwise A.m will be parsed as to messages
messageBody
: assignment? ((from ARROW)? to DOT)? func
| assignment
| to DOT
;
// func is also used in exp as parameter with expr: (to DOT)? func;
func
: signature (DOT signature)*
;
from
: ID | STRING
;
signature
: methodName invocation?
;
// We have removed the alternative rule with single OPAR as we are improving the editor to always close the brackets.
invocation
: OPAR parameters? CPAR
;
assignment
: (type? assignee ASSIGN)
;
```
First of all, `from->to` and `source->target` are very similar. Let's first merge them.
if(!this.rightToLeft) {
if(this.outOfBand) {
// A B C
// inh pro to
const dist = this.distance2(this.origin, this.providedFrom)
return dist - indent + fragmentOff
} else {
// A B
// inh to
// No self call indent here. It is used only for width.
return fragmentOff
}
} else {
// A B C
// to pro origin
// OR
// A B
// to origin
const dist = this.distance2(this.to, this.origin)
return (dist - indent - fragmentOff) * (-1)
}

38
node_modules/@zenuml/core/docs/divider-parser-allow-spaces.md generated vendored Normal file
View File

@@ -0,0 +1,38 @@
This document describe the design of parsing rules for the `divider` statement.
## Typical use case
The `divider` statement is used to separate the sequence of statements into logical
groups.
For example, a HTTPS sequence can be separated into three logical groups:
1. Connect establishment
2. TLS handshake
3. HTTP request/response
```
Client->Server: TCP SYNC
Server->Client: TCP SYN+ACK
Client->Server: TCP ACK
== Connection Established ==
Client->Server: TLS Client Hello
Server->Client: TLS Server Hello
Server->Client: TLS Certificate
Server->Client: TLS Server Hello Done
== Certificate Check ==
Client->Server: TLS Client Key Exchange
Client->Server: TLS Change Cipher Spec
Client->Server: TLS Finished
Server->Client: TLS Change Cipher Spec
Server->Client: TLS Finished
== Key Exchange, Handshake Completed ==
Client->Server: HTTP Request
Server->Client: HTTP Response
```
## The Lexer
## `divider` is a statement
`divider` is treated as a statement as any other messages.

BIN
node_modules/@zenuml/core/docs/handling-starter.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 174 KiB

52
node_modules/@zenuml/core/docs/highlighting-messages.md generated vendored Normal file
View File

@@ -0,0 +1,52 @@
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.

BIN
node_modules/@zenuml/core/docs/images/editor-sample.png generated vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 401 KiB

64
node_modules/@zenuml/core/docs/inherited-vs-provided-from.md generated vendored Normal file
View File

@@ -0,0 +1,64 @@
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.

17
node_modules/@zenuml/core/docs/module-vs-main-in-package-json.md generated vendored Normal file
View File

@@ -0,0 +1,17 @@
The `module` field is not officially defined by Node.js and support is not planned.
Instead, the Node.js community settled on package `exports` which they believe is
more versatile.
For practical reasons JavaScript bundlers will continue support the `module` field.
The esbuild docs [explain](https://esbuild.github.io/api/#main-fields)
when to use `module` as well as related fields like `main` and `browser`.
* `main` is the standard field for all packages that are mean to be used with node.
It is reasonable to expect that the file path in this field is a valid CommonJS module.
* `module` is a non-standard field that is used to integrate ECMAScript modules into
node. It is reasonable to expect that the file path in this field is an ECMAScript module (esm).
For @zenuml/core, the `main` field is set to `dist/zenuml.js` and the `module` field
is set to `dist/zenuml.esm.js`.

79
node_modules/@zenuml/core/docs/open-issues/example-api-performance-issue.md generated vendored Normal file
View File

@@ -0,0 +1,79 @@
# API Performance Issue - Example Template
## Issue Description
Describe the specific performance issue or bug that needs to be addressed. Include symptoms, affected features, and user impact.
Example: "API endpoint `/api/data/process` has intermittent high latency (>5 seconds) under normal load conditions, causing user timeout errors."
## Root Cause
Detailed analysis of what's causing the issue. Include:
- Technical root cause
- Contributing factors
- System conditions that trigger the issue
Example: "Database query optimization needed for complex joins. Current query scans entire table without proper indexing."
## Impact Assessment
- **Severity**: Critical/High/Medium/Low
- **Affected Users**: Percentage or number of users impacted
- **Business Impact**: Revenue, user experience, or operational impact
- **Workarounds**: Any temporary solutions currently in place
## Proposed Solution
### Technical Approach
Detailed technical solution including:
- Code changes required
- Architecture modifications
- Database schema updates
- Performance improvements expected
### Implementation Plan
1. **Phase 1**: Initial fixes (timeline)
2. **Phase 2**: Optimization improvements (timeline)
3. **Phase 3**: Monitoring and validation (timeline)
## Testing Strategy
- **Unit Tests**: Specific test cases to validate the fix
- **Integration Tests**: End-to-end testing scenarios
- **Performance Tests**: Load testing and benchmarking
- **Regression Tests**: Ensure no existing functionality breaks
## Related Files
List all files that need to be modified:
- `src/api/routes/data.py` - Main endpoint logic
- `src/database/models.py` - Database model updates
- `src/utils/query_optimizer.py` - Query optimization utilities
- `tests/test_api_performance.py` - Performance test suite
## References
- [External documentation or APIs]
- [Related GitHub issues or PRs]
- [Performance benchmarking results]
- [Stack Overflow discussions or solutions]
## Status
- [ ] **Open** - Issue identified and documented
- [ ] **In Progress** - Solution being implemented
- [ ] **Testing** - Fix implemented, undergoing testing
- [ ] **Fixed** - Issue resolved and deployed
- [ ] **Closed** - Issue confirmed resolved in production
## Implementation Notes
Track progress and implementation details:
- Date started: [DATE]
- Key decisions made: [DECISIONS]
- Challenges encountered: [CHALLENGES]
- Performance improvements achieved: [METRICS]
---
*This template provides a structured approach to documenting and tracking technical issues. Customize sections based on your project's specific needs and workflow.*

13
node_modules/@zenuml/core/docs/osx-unsupported-arm64-node12.md generated vendored Normal file
View File

@@ -0,0 +1,13 @@
Error when running 'yarn build'
```shell
ERROR Failed to compile with 1 error 10:15:37 AM
error in ./src/components/theme-blue-river.scss
Syntax Error: ModuleError: Module Error (from ./node_modules/sass-loader/dist/cjs.js):
Missing binding /Users/pengxiao/workspaces/zenuml/vue-sequence/node_modules/node-sass/vendor/darwin-x64-83/binding.node
Node Sass could not find a binding for your current environment: OS X 64-bit with Node.js 14.x
```
Remove 'node_modules' and re-run 'yarn build' under node 14.

425
node_modules/@zenuml/core/docs/parser/PARSER_IMPROVEMENTS_CC.md generated vendored Normal file
View File

@@ -0,0 +1,425 @@
# 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.

116
node_modules/@zenuml/core/docs/parser/grammar_review_gemini.md generated vendored Normal file
View File

@@ -0,0 +1,116 @@
# 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.

25
node_modules/@zenuml/core/docs/participants-function.md generated vendored Normal file
View File

@@ -0,0 +1,25 @@
# 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.

52
node_modules/@zenuml/core/docs/responsive-participant-margin.md generated vendored Normal file
View File

@@ -0,0 +1,52 @@
This is to adjust the margin of the lifelines based on the message length.
For example, if the message is long, the margin of the lifelines will be increased.
A.method() {
B.aLongMethodName_and_we_want_to_adjust_the_margin_of_the_lifelines_based_on_the_message_length();
}
# Strategy A
Step 1. We need to know the width of the method box is shorter than the
width of the message label. We only need to compare the scrollWidth and the width.
# Strategy B
Instead of rendering message layer based on lifeline's position, we render
the lifelines based on message occurrence's positions.
There is a problem of this strategy. If we pre-declare the order of the participants,
for example, `B A A.method()`, we have to render B on the left of A.
So maybe, we could implement it in two rounds. First, we define the order of participants.
Then we calculate the position of the lifelines based on the order.
Note that `mounted` is only called when we "mount" the element,
not when we "move" or "relayout" the element.
When we change the code, it may NOT trigger mounted. It may not even
trigger the update of Occurrence.
We cannot just clear the stored positions, because we will have no other chance
to refresh the positions again. So another option is to refresh the positions
when we after mounted and/or updated MessageLayer.
It looks promising now. The current challenge is to render lifelines
according to the positions of participants. A particularly interesting part
is participant group. We may need to render it on a different layer.
Strategy B relies on the browser's behavior on 'width: auto'. So we need
to know when we should set it as auto. Pre-assign positions is in conflict
of this approach, unless we could tell whether it is pre-assigned or not.
What if we always set interaction width to auto first and then update according
to calculated positions?
One of the most tricky part is when a message is removed. To make sure we know
the gap between two participants, we need to know the width of message. However,
if the message is removed, we need to clear the gap we saved because of this message.
This is particularly trick because we may not receive a message for it. Vue may not
destroy the message but just trigger an update and render a different message on it.
In the new try, we will try to generate the positions based on antlr root context
and two width providers - message width provider and participant width provider.

76
node_modules/@zenuml/core/docs/running-cypress-tests-locally.md generated vendored Normal file
View File

@@ -0,0 +1,76 @@
# Running Cypress Tests Locally
This document explains how to run Cypress tests locally on your machine, with a focus on ensuring color profiles match those used in GitHub Actions for consistent visual testing results.
## Running Tests
You can run Cypress tests using the following commands:
- Run all tests headlessly:
```bash
pnpm cy
```
- Run a specific test file:
```bash
pnpm cypress run --spec "cypress/e2e/smoke.spec.js"
```
## Color Profile Configuration
### Why Color Profiles Matter
Visual regression tests in Cypress compare screenshots pixel-by-pixel. Different color profiles can cause the same UI to render with slightly different colors, leading to false test failures. To match the GitHub Actions environment, we use the sRGB color profile.
### Automatic Configuration
Our Cypress configuration automatically forces the sRGB color profile when running tests. This is configured in `cypress/plugins/index.js` with the following code:
```javascript
on("before:browser:launch", (browser = {}, launchOptions) => {
if (browser.family === "chromium" && browser.name !== "electron") {
launchOptions.args.push("--force-color-profile=srgb");
}
});
```
### Configuring macOS Color Profile
For the most consistent results, you should also configure your macOS system to use the sRGB color profile:
1. Open System Preferences (or System Settings on newer macOS versions)
2. Go to "Displays"
3. Select the "Color" tab
4. Click "Calibrate" to open the Display Calibrator Assistant
5. Follow the wizard and when prompted for a color profile, select "sRGB"
6. Complete the calibration and save the profile
Alternatively, you can directly select an existing sRGB profile:
1. Open System Preferences > Displays > Color
2. From the list of color profiles, select "sRGB IEC61966-2.1" or a similar sRGB profile
3. Click "Apply"
## Troubleshooting Visual Test Failures
If you encounter visual test failures despite using the sRGB profile:
1. Check that your display brightness is set to a consistent level
2. Ensure you're using the same browser version as GitHub Actions (Chrome)
3. Verify that your OS theme/appearance settings match the CI environment (light mode is recommended)
4. If necessary, adjust the threshold in the image snapshot configuration:
```javascript
cy.document().toMatchImageSnapshot({
imageConfig: { threshold: 0.012 }, // Increase this value if needed
capture: "viewport",
});
```
## Additional Resources
- [Cypress Image Snapshot Documentation](https://github.com/jaredpalmer/cypress-image-snapshot)
- [Chrome Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches/)
- [macOS Color Management Guide](https://support.apple.com/guide/mac-help/calibrate-your-display-mchlp2920/mac)

9
node_modules/@zenuml/core/docs/starter.md generated vendored Normal file
View File

@@ -0,0 +1,9 @@
There are two ways for the context to get declared Starter:
1. @Starter(X)
2. X->A:m or X->A.m
As long as the starter's name is not \_STARTER\_, it is treated as declared.
Then we check whether the Starter is a declared participant by its `explicit`
field.

27
node_modules/@zenuml/core/docs/testing-minified-lib.md generated vendored Normal file
View File

@@ -0,0 +1,27 @@
```html
<meta charset="utf-8" />
<title>vue-sequence demo</title>
<script src="https://unpkg.com/vue@2.6.12/dist/vue.js"></script>
<script src="https://unpkg.com/vuex@3.6.2/dist/vuex.js"></script>
<script src="./vue-sequence.umd.min.js"></script>
<link rel="stylesheet" href="./vue-sequence.css" />
<div id="mounting-point"></div>
<script>
window.addEventListener('load', function (event) {
console.log('window loaded');
Vue.use(Vuex);
let { SeqDiagram, Store } = window['vue-sequence'];
let storeConfig = Store();
storeConfig.state.code = 'A.method';
Vue.component('seq-diagram', SeqDiagram);
window.app = new Vue({
el: document.getElementById('mounting-point'),
store: new Vuex.Store(storeConfig),
render: (h) => h('seq-diagram'),
});
});
</script>
```

1
node_modules/@zenuml/core/docs/watch.md generated vendored Normal file
View File

@@ -0,0 +1 @@
watch 'yarn antlr' src/g4

16
node_modules/@zenuml/core/docs/why-we-publish-embed-view-to-github-pages.md generated vendored Normal file
View File

@@ -0,0 +1,16 @@
We have got two options to host the embed view: on GitHub pages or
Cloudflare pages (or other third party).
The benefit of Cloudflare pages is:
1. It offers multiple versions. Basically every publish will generate
a standalone url with current commit hash.
2. It does not require commit the `dist` folder to the repository.
The benefit of using GitHub Pages:
1. It will definitely be easier to set up for collaborators on GitHub,
because they do not need a Cloudflare account.
Easy collaboration is more important to us, so we will host this on
GitHub Pages.

62
node_modules/@zenuml/core/docs/width-translate-and-offsets.md generated vendored Normal file
View File

@@ -0,0 +1,62 @@
# Interaction width
Interaction width, in the most simple scenario, is defined by the distance of two participants -
`from` and `to`.
## Simple case
### Width
In the following
Each '◻' is a pixel
```
| A | | B |
1 2 3 4 5 6 7 8 9 a b c d e f g h
◻ ◻ ◻ ◻ ◻ ◻ ◻ ◻ ◻ ◻ ◻ ◻ ◻ ◻ ◻ ◻ ◻
```
#### 1. Interaction width
Interaction will overlap the left lifeline but not the right.
A has left as 2, center as 4 and right as 6; B has a/c/e. For Interaction `m2` in (A.m1{B.m2}),
the width should be 4 to c (inclusive) that is 9 (`c - 4 + 1`). This is `distance(from, to)`.
#### 2. Message width
Message width should be 100% content + interactionBorderWidthx2 - ((OccurrenceWidth - 1)/2)x2 - interactionBorderWidth.
### Left
#### 1. Message left
```
100% // content width of interaction
+ InteractionBorderWidth x 2
- ((OccurrenceWidth-1)/2) x 2
```
#### 2. Self Occurrence Left
```
left: width of InteractionBorderWidth
```
### Offset
There are a few ways to implement offset, we have to combine them.
#### 1. Padding of occurance
> Suppose the width of an occurance is 5 (border width 1x2, content 3)
To aligh Occurance's center, we need to set its left. An occurance
at `left: 100%` will be from c to g. Note that the 100% only consider
the content width.
To align its center to c, we
have to move back by 3 (`(occuranceWidth-1)/2 - interactionBorderWidth - LifelineWidth`).
occurance must have a padding of 1 that is (width - boarder x 2 - 1) / 2.
## Self call indent

59
node_modules/@zenuml/core/docs/xss.md generated vendored Normal file
View File

@@ -0,0 +1,59 @@
In this document we are disclosing a cross-site scripting vulnerability in the
[@zenuml/core](https://www.npmjs.com/package/@zenuml/core) package.
XSS is a type of security vulnerability that allows an attacker to inject
malicious code into a web page viewed by other users.
# How to reproduce
ZenUML generates sequence diagrams from text. If the text contains a
malicious script, it will be executed when the diagram is rendered.
The following content is known to pop an alert box:
```
"><img src=x onerror=alert(1)>ent #FFEBE6
```
# Known affected products
| Product | Severity | Comment |
|-------------------|----------|---------------------------------------------------------------------|
| Confluence plugin | P3 | Content must be create by registered users; scripts run in sandbox. |
| Web App | P3 | Only the current user can view content created by themselves. |
| Chrome Extension | P3 | Only the current user can view content created by themselves. |
| Desktop (Win/Mac) | P3 | Only the current user can view content created by themselves. |
| JetBrains plugin | P3 | Scripts run inside sandbox. |
# What is the cause of the vulnerability?
The cause of the XSS vulnerability in @zenuml/core is due to accepting an arbitrary text as `innerHTML` in the
WidthProviderFunc.ts file. Specifically, the vulnerability is located in the code that measures the width
of the message or participant element in the library. The issue is present in line 29 of the file, which
can be found at [this URL](https://github.com/ZenUml/core/blob/577f2a550a0b82a392215875298bc358a8feff0d/src/positioning/WidthProviderFunc.ts#L29).
In this line, the code uses unsanitized user input which is passed as an argument in the function, this
allows an attacker to inject malicious JavaScript code into the web page viewed potentially by other users.
```
let hiddenDiv = document.querySelector('.textarea-hidden-div') as HTMLDivElement;
if (!hiddenDiv) {
const newDiv = document.createElement('div');
...
document.body.appendChild(newDiv);
hiddenDiv = newDiv;
}
hiddenDiv.innerHTML = text;
const scrollWidth = hiddenDiv.scrollWidth;
return scrollWidth;
```
# Fix of the vulnerability
The fix is to replace the `innerHTML` with `textContent` in the code. This will prevent the browser from
interpreting the text as HTML and will treat it as plain text.
```
...
hiddenDiv.textContent = text;
const scrollWidth = hiddenDiv.scrollWidth;
return scrollWidth;
```