CALM VSCode Extension - AI Assistant Guide

This guide helps AI assistants work efficiently with the CALM VSCode extension codebase.

Tech Stack

Language: TypeScript 5.8+
Framework: VSCode Extension API 1.88+
State Management: Zustand (Redux-like store)
Build Tool: tsup (esbuild-based)
Test Framework: Vitest
Architecture Pattern: MVVM + Hexagonal + Mediator
UI Components: Native VSCode API (TreeView, Webview, Commands)

Key Commands

IMPORTANT: Always run npm commands from the repository root using workspaces, not from within this package directory.

# Development (from repository root)
npm run build --workspace calm-plugins/vscode          # Build extension
npm run watch --workspace calm-plugins/vscode          # Watch mode (no auto-reload in VSCode)
npm test --workspace calm-plugins/vscode               # Run Vitest tests
npm run lint --workspace calm-plugins/vscode           # ESLint check
npm run lint-fix --workspace calm-plugins/vscode       # Auto-fix linting issues
npm run package --workspace calm-plugins/vscode        # Create .vsix package for distribution

# Convenience scripts (run the build:shared prerequisite for you)
npm run test:vscode                                    # build:shared + test the extension
npm run package:vscode                                 # build:shared + package the extension

# Testing Extension in VSCode
# 1. Open the repository root in VSCode (File → Open Folder)
# 2. Use the "calm-plugin: watch" task or run: npm run watch --workspace calm-plugins/vscode
# 3. Press F5 (or Run → Start Debugging) to launch Extension Development Host
# 4. In the new Extension Development Host window, open a CALM JSON file to activate extension

Architecture Overview

🏗️ Three-Layer Architecture

MVVM (Model-View-ViewModel)

View (VSCode UI) <--> ViewModel (Framework-free) <--> Model (Zustand Store)

Hexagonal Architecture (Ports & Adapters)

src/core/
├── ports/           # Interfaces (dependency inversion)
├── services/        # Core business logic
└── mediators/       # Cross-cutting orchestration

Mediator Pattern

Coordinates between services without tight coupling
Examples: RefreshService, SelectionService, WatchService

Directory Structure

src/
├── extension.ts                    # VSCode entry point (activate/deactivate)
├── calm-extension-controller.ts    # Main orchestrator (wires dependencies)
├── application-store.ts            # Zustand global state
│
├── core/                           # Framework-free business logic
│   ├── ports/                      # Interfaces for dependency inversion
│   ├── services/                   # Core services (model, config, navigation, diagnostics, calm-schema-registry, logging)
│   ├── mediators/                  # Cross-cutting coordinators (refresh, selection, watch, store-reaction)
│   └── emitter.ts                 # Event system (framework-free)
│
├── features/                       # Feature modules
│   ├── tree-view/                 # Sidebar tree navigation
│   │   ├── tree-view-factory.ts  # Wires view + view-model
│   │   ├── view/                 # VSCode-specific view (tree-view.ts, tree-item.ts)
│   │   └── view-model/           # MVVM presentation logic (framework-free)
│   ├── editor/                    # Editor integration (hover, CodeLens)
│   └── preview/                   # Webview preview panel
│       ├── webview/              # Webview internals (mermaid-renderer, pan-zoom-manager,
│       │                         #   diagram-controls, panel.view)
│       ├── docify-tab/           # Documentation generation
│       ├── model-tab/            # Model data display
│       └── template-tab/         # Template processing & live mode
│
├── commands/                       # VSCode command handlers
├── models/                         # CALM model parsing & indexing
└── cli/                           # CLI integration (deprecated, being replaced)

Key Design Principles

Framework Isolation: ViewModels have NO vscode imports
Dependency Inversion: Core depends on ports, not VSCode
Single Store: All state in application-store.ts
Mediator Coordination: Services don't call each other directly

Key Concepts

State Management (Zustand)

Store Location: src/application-store.ts

The store is created via the createApplicationStore() factory (using Zustand's subscribeWithSelector middleware), not a module-level create() singleton. The extension controller owns the instance and injects it where needed.

interface ApplicationStore {
    calmModel: CalmModel | null;
    selectedNode: string | null;
    isLoading: boolean;
    // ... other state
    
    // Actions
    setCalmModel: (model: CalmModel) => void;
    setSelectedNode: (nodeId: string | null) => void;
    // ... other actions
}

Usage (illustrative — the real store is a per-instance object created by the factory):

import { createApplicationStore } from './application-store';

const store = createApplicationStore();

// Read with a selector
const model = store.getState().calmModel;

// React to changes (subscribeWithSelector)
store.subscribe(state => state.calmModel, model => { /* ... */ });

MVVM Pattern

ViewModel Example:

// src/features/tree-view/view-model/tree-view-model.ts
export class TreeViewModel {
    // NO vscode imports!
    constructor(
        private store: ApplicationStore,
        private emitter: Emitter
    ) {}
    
    getTreeData(): TreeNode[] {
        const model = this.store.getState().calmModel;
        return this.transformToTree(model);
    }
}

View (VSCode Specific):

// src/features/tree-view/tree-data-provider.ts
export class CalmTreeDataProvider implements vscode.TreeDataProvider {
    constructor(private viewModel: TreeViewModel) {}
    
    getChildren(element?: TreeItem): TreeItem[] {
        return this.viewModel.getTreeData().map(toTreeItem);
    }
}

Mediator Pattern

Mediators coordinate between services:

// src/core/mediators/store-reaction-mediator.ts
export class StoreReactionMediator {
    constructor(
        private store: ApplicationStore,
        private refreshService: RefreshService,
        private selectionService: SelectionService
    ) {
        // React to store changes
        this.store.subscribe(
            state => state.calmModel,
            model => this.refreshService.refreshAll()
        );
    }
}

Navigation Service

Purpose: Handles navigation between CALM documents via detailed-architecture references.
Key Logic: Uses DocumentLoader from @finos/calm-shared to resolve URLs/relative paths to local files based on calm.urlMapping.
Integration: Called by SelectionService when a node with details is clicked.

Features

Tree View

Purpose: Sidebar navigation of CALM model structure
Location: src/features/tree-view/
Key Files:
- view/tree-view.ts - VSCode TreeDataProvider implementation
- view/tree-item.ts - VSCode TreeItem wrapper
- tree-view-factory.ts - Wires the view and view-model together
- view-model/tree-view-model.ts - Business logic (framework-free)

Validation Service

Purpose: Real-time CALM document validation with Problems panel integration
Location: src/features/validation/
Key Files:
- validation-service.ts - Main service, handles document events and diagnostics
- validation-service.spec.ts - Unit tests
Behavior:
- Validates on document open, save, and editor activation
- Clears diagnostics when editor tab is closed
- Uses content-based detection (checks $schema field for known CALM schemas)
- Produces precise line numbers for error positioning using shared enrichment logic
Dependencies: Uses runValidation, enrichWithDocumentPositions from @finos/calm-shared

Webview Preview

Purpose: Multi-tab preview (Model, Docify, Template)
Location: src/features/preview/
Tabs:
- Model Tab: Display CALM JSON in formatted view
- Docify Tab: Generate documentation websites
- Template Tab: Live template processing with Handlebars

Editor Integration

Hover Providers: Show info on hover
CodeLens: Inline commands in editor
Location: src/features/editor/

Testing

Test Structure

*.spec.ts - Unit tests alongside source
test_fixtures/ - Sample CALM files for testing (architecture/, navigable-architecture/)

Running Tests

# From repository root (preferred)
npm test --workspace calm-plugins/vscode              # All tests
npm test --workspace calm-plugins/vscode -- --watch   # Watch mode
npm test --workspace calm-plugins/vscode -- <file>    # Specific test file

Testing ViewModels

ViewModels are framework-free, so they're easy to unit test:

import { TreeViewModel } from './tree-view-model';

describe('TreeViewModel', () => {
    it('transforms model to tree', () => {
        const store = createMockStore();
        const vm = new TreeViewModel(store, mockEmitter);
        
        const tree = vm.getTreeData();
        expect(tree).toHaveLength(3);
    });
});

Common Tasks

Adding a New Command

{
    "contributes": {
        "commands": [{
            "command": "calm.myCommand",
            "title": "CALM: My Command"
        }]
    }
}

Create handler in src/commands/:

export function registerMyCommand(context: vscode.ExtensionContext) {
    context.subscriptions.push(
        vscode.commands.registerCommand('calm.myCommand', () => {
            // Implementation
        })
    );
}

import { registerMyCommand } from './commands/my-command';

export function activate(context: vscode.ExtensionContext) {
    registerMyCommand(context);
}

Adding State to Store

Update src/application-store.ts (add to the interface and the createApplicationStore factory):

interface ApplicationStore {
    myNewState: string;
    setMyNewState: (value: string) => void;
}

export function createApplicationStore(): ApplicationStoreApi {
    return createStore<ApplicationStore>()(
        subscribeWithSelector((set) => ({
            myNewState: '',
            setMyNewState: (value) => set({ myNewState: value }),
        }))
    );
}

Creating a New ViewModel

Create in appropriate feature folder (framework-free!):

// src/features/my-feature/view-model/my-view-model.ts
export class MyViewModel {
    constructor(
        private store: ApplicationStore,
        private emitter: Emitter
    ) {}
    
    // Methods that work with store, NO vscode imports
}

Create VSCode View:

// src/features/my-feature/my-view.ts
import * as vscode from 'vscode';
import { MyViewModel } from './view-model/my-view-model';

export class MyView {
    constructor(private viewModel: MyViewModel) {}
    
    // VSCode-specific implementation
}

Adding a Webview Tab

Create tab component in src/features/preview/my-tab/
Update src/features/preview/preview-panel.ts to include new tab
Add HTML template if needed

Dependencies on Other Packages

vscode-plugin depends on:
  ├── calm-models (via ../../calm-models)
  ├── calm-widgets (via ../../calm-widgets)
  └── shared (via ../../shared)

Important: Build dependencies first:

# From repository root (always use workspaces)
npm run build:shared    # Builds models, widgets, shared
# Or build individual packages:
npm run build --workspace calm-models
npm run build --workspace calm-widgets
npm run build --workspace shared

Bundled Assets

The extension bundles CALM schemas, widgets, and template bundles into dist/ at build time so validation, rendering, and templating work without network access or reaching into sibling workspaces at runtime.

Build Process

The postbuild step does two things:

copyfiles copies CALM schemas from the repo root:
- calm/release/**/meta/* → dist/calm/release/...
- calm/draft/**/meta/* → dist/calm/draft/...
scripts/copy-calm-assets.js copies the remaining runtime assets:
- widgets from calm-widgets/dist/cli/widgets (falls back to calm-widgets/src/widgets) → dist/widgets/
- template bundles from shared/dist/template-bundles → dist/template-bundles/

Schemas are indexed by their $id field for lookup when validating documents.

Schema Registry

CalmSchemaRegistry (src/core/services/calm-schema-registry.ts) manages schema discovery:

Loads bundled schemas from dist/calm/
Loads additional schemas from folders configured in calm.schemas.additionalFolders
Provides isKnownCalmSchema(url) to check if a schema URL is available locally

Adding New Schema Versions

When new CALM schema versions are released:

Add the schema files to calm/{release|draft}/{version}/meta/
Rebuild the extension - schemas are automatically copied and indexed

Common Pitfalls

Importing vscode in ViewModels: ViewModels must be framework-free!
Direct Service Calls: Use mediators for cross-cutting concerns
Store Mutations: Always use store actions, never mutate directly
Extension Not Activating: Check activationEvents in package.json
Webview Not Updating: Remember to postMessage from webview to extension
toCanonicalSchema adds undefined values: When using toCanonicalSchema() from calm-models, ALL optional properties are added with undefined values. Code checking for property existence must check for truthy values, not just key existence. See calm-widgets/AGENTS.md for details.
URL Mapping: To test multi-document navigation, you likely need to configure calm.urlMapping in .vscode/settings.json to point to a mapping file (e.g. calm-mapping.json) in the workspace root.

Debugging

Debug Extension

Open this folder in VSCode
Set breakpoints in TypeScript source
Press F5 (or Run → Start Debugging)
Extension Development Host window opens
Open a CALM file to trigger activation

Debug Webview

In Extension Development Host: Ctrl+Shift+P
Run: "Developer: Open Webview Developer Tools"
Use browser devtools to debug webview

Configuration Files

package.json - Extension manifest, commands, views
tsconfig.json - TypeScript compiler options
tsup.config.ts - Build configuration
vitest.config.mts - Test configuration
eslint.config.mjs - Linting rules

Publishing

# From repository root
npm run package:vscode                                 # build:shared + creates .vsix file
# (or, if dependencies are already built: npm run package --workspace calm-plugins/vscode)
# Then publish to VS Code Marketplace via GitHub Actions

Useful Links

DEVELOPER.md - Detailed architecture guide with diagrams
README.md - User-facing documentation
VSCode Extension API - Official docs
Root README - Monorepo overview

FilesExpand file tree

AGENTS.md

Latest commit

History