Experimental Live Docify Plugin with VSCode Marketplace Publishing

[LeighFinegold]

Description

This PR introduces a more evolved experimental CALM VS Code extension that demonstrates live docify capabilities with marketplace publishing setup. Building on the original POC, it showcases how CALM architecture visualization and documentation can be integrated directly into the VS Code development workflow.

What end users get:

• 📋 Live documentation: Real-time doc generation similar to calm docify --website mode
• 🔍 Smart navigation: Click elements in tree/preview to jump to source code
• 🚀 Zero setup: Self-contained - no need to install CALM CLI separately

Technical foundation:

• 🏗️ Structural Foundation: Redux Pattern + MVVM + Hexagonal.
• 📦 Marketplace ready: GitHub Actions publishing workflow (manual but will move to automated upon successful test)

⚠️ Disclaimer
This is still a bit away from production quality (more tests needed + further refactoring) but raising PR to allow for vscode extension setup to be tested.

Type of Change

• ✨ New feature (non-breaking change which adds functionality)
• ✅ Test additions or updates
• ♻️ Refactoring (no functional changes)
• 📚 Documentation update (atleast in the vscode project itself)

Affected Components

• VS Code Extension (calm-plugins/vscode/)
• CI/CD (GitHub Actions workflow)

Improvements Over Original POC

🎯 Bug Fixes

• Extension Creation Works: Fixed critical VSIX bundling - original POC wouldn't install/run properly
• Zero Dependencies: Users don't need CALM CLI installed - everything is self-contained
• Memory: Extension remembers your node positions and zoom level per document
• Real-time Templates: Edit models, see documentation update instantly
• Template Simulation: Mimics calm docify --scaffold default menu generation (some of the logic will move out into docify module as part of Introduce a two-stage website generation flow for CALM Docify that integrates with Docusaurus #1563)

🏗️ Production-Ready Architecture

Built with Redux/State Store + MVVM + Hexagonal Architecture for maintainability and testing:

graph TB
    UI[VS Code UI<br/>TreeView, Webview, Commands]
    VM[View Models<br/>Presentation Logic]
    M[Mediators<br/>Cross-cutting Concerns]
    Store[Application Store<br/>Global State]
    
    UI <--> VM
    VM --> Store
    M --> Store
    M --> VM
    
    subgraph "VSCode Framework-Free Zone"
        VM
        Store
    end
    
    subgraph "VS Code Integration"
        UI
        M
    end
    
    style Store fill:#e1f5fe
    style VM fill:#f3e5f5
    style M fill:#fff3e0
    style UI fill:#e8f5e8

Loading

Testing

• I have tested my changes locally
• I have added/updated unit tests (109 view-model tests - More to come)
• All existing tests pass
• Manual testing across light/dark themes
• VSIX installation and functionality verified
• GitHub Actions workflow tested

Checklist

• My commits follow the conventional commit format
• I have updated documentation if necessary
• I have added tests for my changes (109 comprehensive tests)
• My changes follow the project's coding standards
• Extension packages successfully (calm-vscode-plugin-0.0.1.vsix)
• GitHub Actions workflow configured
• All lint errors resolved
• Dark mode Mermaid rendering tested and working
• Ready for production (still experimental - requires further testing and refinement)

📋 In Progress/Planned

• Hexagonal Architecture Refinement: Completing ports/adapters pattern
• Mediator Coordination: Fine-tuning cross-cutting concerns
• CLI Integration Replacement: --scaffold mode from docify CLI will replace most of the code in src/cli/ + templates folder (See Introduce a two-stage website generation flow for CALM Docify that integrates with Docusaurus #1563)
• Model Updates: Original POC models in src/models/ and settings need updating to potentially use models from @finos/calm-models and reduce use of any
• Enhanced Validation: Richer diagnostics and error reporting
• More Tests!

[LeighFinegold]

I can back this out for the main build, but originally defined an automated task to publish to VSCode marketplace if a release tag with "vscode-" was created. That clashes with this existing rule that only looks for v....

[Thels]

Couldn't we just use semantic-release for this?

[LeighFinegold]

I think we can look to set that up in subsequent PR once confirm publishing to the market place works. Set the version as 0.0.1 for now.

[rocketstack-matt]

To test I built the vxix locally and installed, open an architecture, looks good, e.g.

I then open the CALM Model Elements view and navigate to a node, I see

"Error: [WidgetEngine] ❌ Conflict: Handlebars already has a helper registered as 'table'."

[LeighFinegold]

I then open the CALM Model Elements view and navigate to a node, I see

"Error: [WidgetEngine] ❌ Conflict: Handlebars already has a helper registered as 'table'."

As discussed with @rocketstack-matt that was fixed already on the PR - https://github.com/finos/architecture-as-code/pull/1650/files#diff-e440dbaf04525b6f2a9a3a32351b1791…. The issue is upon testing this, one needs to run a new build of calm-widgets which doesn't happen at the individual project level.

I will raise an update for the README.md for now to run from root package:vscode and mention this on next office hours as we have a similar setup for other modules e.g. npm run build on the shared project won't recompile the calm-models project.

[finos-admin]

🎉 This PR is included in version 1.7.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀