feat: complete usecase diagram integration & validation#7530
feat: complete usecase diagram integration & validation#7530Sudhanshu-Ambastha wants to merge 50 commits intomermaid-js:developfrom
Conversation
✅ Deploy Preview for mermaid-js ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
🦋 Changeset detectedLatest commit: a378d72 The changes in this PR will be included in the next version bump. This PR includes changesets to release 2 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
@mermaid-js/examples
mermaid
@mermaid-js/layout-elk
@mermaid-js/layout-tidy-tree
@mermaid-js/mermaid-zenuml
@mermaid-js/parser
@mermaid-js/tiny
commit: |
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## develop #7530 +/- ##
==========================================
- Coverage 3.33% 3.30% -0.04%
==========================================
Files 537 547 +10
Lines 56310 57318 +1008
Branches 821 835 +14
==========================================
+ Hits 1877 1893 +16
- Misses 54433 55425 +992
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
|
Hi, I looked through your PR and it already seems very well advanced. The main adjustment I can see is the parser side: since Mermaid is adopting Langium for new diagrams, it may make sense to migrate this from Jison to Langium to match the current repository standard. Would you be open to a PR against your branch to help with that migration? |
- Create usecase.langium with complete grammar - 8 statement types: Actor, External, System, Usecase, Collaboration, Note, Association, Relationship - Support for 8 relationship types: include, extend, generalization, dependency, realization, anchor, constraint, containment - Implement tokenBuilder.ts with keywords for diagram detection - Implement module.ts following Radar/Packet dependency injection pattern - Register grammar in langium-config.json - Import usecase module in parser language index Follows the Langium 4.0.0 pattern used by Radar and Packet diagram types.
- Add lazy initializer for usecase parser via createUsecaseServices()
- Add promise-based parse('usecase', text) overload
- Update DiagramAST union type to include Usecase
- Connects Langium grammar generator to central parser dispatcher
Parser now auto-loads usecase module on first diagram parse, following singleton pattern used by other diagram types.
- Implement parser.ts bridge between Langium AST and usecaseDb - populate(ast) function iterates AST statements and dispatches by \ - Type-safe casts handle optional fields (label, alias, notes) - Supports all 8 relationship types with proper type validation - Replaces regex-based parsing in usecaseDb.ts Bridge pattern separates concerns: grammar/generation → parser bridge → state management.
- Lines: 481 → 250 (48% reduction, focusing on state management) - Remove parseDiagram() and all regex-based parsing logic - Remove parseString() utility function - Keep all entity types, state structures, validation rules - Keep inferUseCases() type inference for edge cases - DB now acts as pure state container, parsing delegated to parser.ts bridge Benefits: - Separation of concerns (parsing vs state management) - Type safety via Langium AST instead of regex captures - Easier to test and maintain
- Rewrite 22 tests to match new db interface (no parsing in db) - Tests focus on: entity creation, state management, relationship validation - Test system boundaries with nested usecases - Validate all 8 relationship types (include, extend, etc.) - Test inference logic and edge cases - All tests passing (22/22 in 44ms) Tests now validate db contract independently of parser, enabling future parser refactors.
- Change regex from: /^\\s*usecase/i (too broad, false positives) - To: /^\\s*(usecaseDiagram|useCase)\\b/i (specific keywords) - Prevents misdetection of comments or other diagrams starting with 'use' This fixes the core issue where usecase diagrams were undetectable or causing false positives in diagram auto-detection. Aligns with Langium keywords: 'usecaseDiagram' (document start) and 'useCase' (entity definition).
- Remove ucDb.clear() call (now in parser bridge initialization) - Remove ucDb.parseDiagram(text) call (parsing delegated to parser.ts) - Renderer now directly calls getModel() assuming db is populated - Simplifies render lifecycle: parse → populate → render (3 clear phases) Benefits: - Renderer focuses solely on SVG rendering - Parser logic isolated in parser.ts bridge - Enables easier testing of render logic independently
Update usecaseDiagram.ts to use new parser registration pattern with Langium-generated detector.
- Delete usecase.jison (dead code) - Jison implementation never invoked after migration to Langium - All parsing now handled by Langium grammar + parser bridge Langium provides superior benefits: - Strict grammar validation at parse time - Type-safe AST generation - Better error reporting - Consistent with new diagram types (Radar, Packet)
- Change comment syntax from # to %% (Mermaid standard) - Fix diagrams 1, 3, 4 which had parsing errors - Langium is stricter about syntax than old Jison parser - All 4 demo diagrams now parse and render correctly Demo updated to serve as reference for correct usecase syntax: 1. Basic actors, systems, and usecases 2. Generalization relationships and system boundary 3. System with nested usecases 4. Complex multi-system diagram with all relationship types
Hi, thanks for taking the time out of your busy schedule to respond! While testing my implementation, I noticed a behavior that matches the issue I recently raised in #7569. The diagram renders correctly when the code is explicitly typed in the editor, but it doesn't show up in the selection menu or samples list. Since I faced this while implementing the Use Case diagram, I’d like to know if the migration to Langium will automatically resolve this registration in the Live Editor's UI, or if there is a separate configuration I should be updating alongside the parser to ensure full discovery by the UI components. I'll reach out if I hit any roadblocks during the transition. Looking forward to your guidance! |
|
To answer your question about the Live Editor: no, the Langium migration alone won't automatically fix the Live Editor's sample menu discovery. Those are two separate things:
Diagram parsing and rendering ✅ The samples list lives in a different repository: mermaid-live-editor I already have the branch ready at gabriel/migrate-jison-langium on my fork and a open PR at your codebase. |
Ok I checked the pr I though so that was the reason even I asked from diff AIs they also said that we need to edit from editor side but I don't remember who said that it should auto show up on the editor side if done perfectly in backend ok I fix the backend + the editor code too |
Ok then i will merge them 1 by 1 as for now like for usecase is in my fork's main branch & cpm/pert in seprate + for the refactor part of repo i haven't started anything yet related to it + I need someone to help/guide me with it refactor thing as i don't want to end up breaking that so i haven't touched/started it yet |
feat: migrate usecase diagram from Jison to Langium
|
Hey @Restodecoca! I've pushed the latest updates, but 2 tests are still failing in the E2E suite. It seems the parser is still struggling with quoted strings in certain contexts, which is causing the Argos visual tests to fail as well. Also, the |
2 participants
📑 Summary
Implements a dedicated Use Case Diagram renderer for Mermaid (
usecaseDiagram), resolving the approved diagram request and addressing the curved path routing issue for include/extend relationships within system boundaries.The implementation follows UML 2.x standards for correct element shapes, relationship types, and layout conventions.
Resolves #7414
Also closes #4628
📏 Design Decisions
usecaseDb.ts) — A text-based parser readsusecaseDiagramsyntax directly.actor,usecase,system {}boundary,external,collaboration,note, and 9 relationship types.log.warnhint instead of causing runtime failures.usecaseRenderer.ts) — D3-based SVG renderer aligned with Mermaid’s rendering architecture.config.yaml) — IntroducesUsecaseDiagramConfiginto the global Mermaid configuration schema.usecaseStyles.ts) — Uses standard Mermaid theme variables (primaryColor,lineColor, etc.).styles.spec.ts) — Adds automated tests (Vitest) to ensure consistent rendering across default themes.usecaseDetector.ts) — Activates onusecaseDiagramoruseCasekeywords at the start of input.Example Syntax
usecaseDiagram actor "Customer" as C actor "Technician" as T external "Bank Server" as S system "ATM System" { usecase "Withdraw Cash" as UC1 usecase "Check Balance" as UC2 usecase "Login" as UC3 } note "Requires PIN" as N1 C --> UC1; UC2 T --> UC3 include: UC1 --> UC3 dependency: UC1 --> S generalization: T --> C anchor: N1 --> UC3📝 Notes for Reviewers
Relationship Rules
usecaseDb.ts(ALLOWEDtable)Invalid Relationships
log.warnhint for easier debuggingRendering
Known Issue
📋 Tasks
pnpm changeset