Integrate CALM CLI commands into VSCode extension

[rocketstack-matt]

Feature Proposal

Target Project:

calm-plugins/vscode (primary), cli and shared (refactoring support)

Description of Feature:

Integrate core CALM CLI capabilities (validate, generate, docify) directly into the VSCode extension by utilizing the shared code libraries, rather than executing the CLI as a subprocess. This ensures a smoother user experience, faster performance, and removes the requirement for users to have the calm CLI installed globally or locally in their project.

This integration will allow users to:

1. Validate architecture files against patterns with inline error reporting in the VSCode Problems panel.
2. Generate architecture files from patterns using a UI-driven wizard.
3. Docify their models into documentation sites directly from the command palette.

User Stories:

1. As a CALM architect, I want to see validation errors in my architecture.json file highlighted in the editor (squiggles) and listed in the Problems panel, so I can fix issues immediately without running a command.
2. As a developer, I want to right-click a CALM pattern file and select "Generate Architecture", so I can quickly scaffold a new architecture file.
3. As a documentation writer, I want to run "CALM: Docify" from the command palette to generate the static site, without needing to learn the CLI syntax or install Node.js dependencies manually.
4. As a new user, I want the extension to work "out of the box" without needing to configure a path to the CALM CLI binary.

Current Limitations:

• The current extension focuses primarily on visualization (Preview).
• Users must install the calm CLI separately to perform validation or generation.
• There is no feedback loop between the editor and the validation logic (no inline linting).
• Shelling out to a subprocess (if implemented) is slow, requires path configuration, and error handling is brittle.

Proposed Implementation:

Technical Design Considerations

The core logic for CALM commands already resides in the @finos/calm-shared package, which is a dependency of both the CLI and the VSCode extension. The proposed approach is to consume these shared libraries directly within the VSCode extension.

1. Refactoring (cli -> shared):

   • The validate command in the CLI currently contains logic for loading files and resolving references (loadArchitectureAndPattern, resolveSchemaRef) inside cli/src/command-helpers/validate.ts.
   • This logic should be moved to @finos/calm-shared (e.g., shared/src/document-loader/loading-helpers.ts) so it can be reused by the VSCode extension to load and parse documents exactly as the CLI does.

2. VSCode Integration (calm-plugins/vscode):

   • Validation:
     • Create a ValidationProvider that listens to vscode.workspace.onDidSaveTextDocument.
     • Use DocumentLoader (from shared) and the refactored loading helpers to parse the file.
     • Call validate() from @finos/calm-shared/commands/validate.
     • Map the resulting ValidationOutcome errors/warnings to a vscode.DiagnosticCollection to show squiggles and problem markers.
   • Generation:
     • Register command calm.generate.
     • Use VSCode QuickPick API to replicate the interactive prompts (currently using inquirer in CLI).
     • Call runGenerate() from @finos/calm-shared.
   • Docify:
     • Register command calm.docify.
     • Call Docifier class from @finos/calm-shared.

API Changes

• @finos/calm-shared: Export new helper functions for loading architecture/patterns and resolving references (extracted from CLI).

Dependencies on Other Components

• Depends on @finos/calm-shared.
• No external binary dependencies.

Alternatives Considered:

• Shelling out to CLI: Execute calm validate ... as a child process.
  • Rejected: Slower, requires user to manage CLI installation/version, difficult to map stdout/stderr to VSCode diagnostics precisely, poor UX for interactive commands.
• Language Server Protocol (LSP): Implement a full LSP server.
  • Rejected for now: Significantly higher complexity. Direct integration is a good first step; LSP can be a future evolution if we need to support other editors (Neovim, IntelliJ).

Testing Strategy:

• Unit Tests: Verify the refactored loading logic in shared has high coverage.
• Extension Tests: Use @vscode/test-electron to run integration tests:
  • Open a workspace with invalid architecture.
  • Assert that diagnostics are generated.
  • Run generation command and assert file creation.

Documentation Requirements:

• Update VSCode extension README.md to highlight new features.
• Update CONTRIBUTING.md or AGENTS.md in vscode package to explain how to debug the shared logic.

Implementation Checklist:

• Move loadArchitectureAndPattern and resolveSchemaRef from CLI to Shared.
• Update CLI to use new Shared helpers (ensure no regression).
• Implement ValidationProvider in VSCode extension.
• Implement calm.generate command in VSCode.
• Implement calm.docify command in VSCode.
• Add unit and integration tests.

[LeighFinegold]

Just to add some context on current state vs. what’s being proposed:

• The VSCode extension already depends directly on @finos/calm-shared (introduced as part of 1650, so the core architectural decision to run logic in-process rather than shelling out to the CLI is already in place.

From my perspective, this issue is therefore less about introducing a new integration model and more about:

• completing the refactor to move remaining CLI-specific helpers into shared, and
• wiring existing shared commands (validate, generate, docify) into VSCode UI surfaces (diagnostics, commands, quick picks).

I raised #2061 on back off last week's office hours. I think based on the above one change that can be made is actually keep the naming consistent with the cli commands. So Rather "Create Website", will change to just calm-docify

[rocketstack-matt]

Agreed, this is just about making sure we don't introduce that dependency.