VS Code extension for CodeCharter's rule authoring DSL

The VS Code Extension brings full editor support for the CodeCharter DSL. When you write custom .ccr rules, you get syntax highlighting, snippets, and auto-completion for schema properties.

Installation

The extension requires VS Code 1.85 or later. Downloading from the portal requires a signed-in account with an active subscription.

1. Get codecharter-X.Y.Z.vsix from the portal downloads.
2. In VS Code: Command Palette → "Extensions: Install from VSIX..." → select the downloaded file.

Note: VS Code will show a security prompt about an unverified publisher when installing a VSIX file that is not from the Marketplace. This is expected. Confirm to proceed with the installation.

Alternatively via CLI:

code --install-extension codecharter-X.Y.Z.vsix

The Windows installer offers this as a pre-selected setup option when it detects a VS Code installation.

The extension requires the CodeCharter CLI for all language features: the language server is provided by the CLI itself. If no CLI is found, the extension shows an error on activation and completion and validation do not work. The CLI is auto-detected on the PATH (executable names codecharter, CodeCharter.Cli, or CodeCharter.Cli.exe) or configured via codecharter.serverPath.

Features

• Syntax highlighting for .ccr files with a dedicated tokenizer.
• Snippets for common rule skeletons.
• Auto-completion for schema properties (TypeModel, MethodModel, and others) via a language server provided by the CodeCharter CLI.
• Inline validation of rule syntax. Typos in property names are flagged immediately in the editor.
• Spec testing with CodeLens actions: "Run spec" and "Scaffold spec" appear on .ccr and .spec.md files; failing cases show up in the Problems panel.

When your codecharter.yml declares portal profiles, the extension runs codecharter restore on activation, shows the active rule set in the status bar, and warns when codecharter.lock.json is newer than the rule cache.

The extension also receives rule drafts from the portal: Open in VSCode in the portal rule editor pulls the current draft into VS Code, and CodeCharter: Push to portal sends it back as a draft. The full round trip is described under Editing rules in VS Code.

Commands in the Command Palette

• CodeCharter: Validate current rule file
• CodeCharter: Analyze workspace (.sln/.csproj)
• CodeCharter: Test rule spec
• CodeCharter: Test all specs
• CodeCharter: Scaffold spec for current rule
• CodeCharter: Restart language server
• CodeCharter: Show language server output

Analyze workspace runs the CodeCharter CLI on the solution or project in the VS Code terminal. Findings appear there as console output.

Configuration

Settings under codecharter.* in VS Code settings:

Setting	Default	Description
codecharter.serverPath	empty	Path to the CodeCharter CLI. Empty = auto-detect from PATH. Supports ${workspaceFolder} and ${userHome}.
codecharter.analyze.rulesDirectory	empty	Rules directory for Analyze workspace. Empty = the CLI's default resolution: ./rules in the workspace, otherwise the rule set shipped with the CLI.
codecharter.trace.server	off	Trace LSP communication (off, messages, verbose).
codecharter.portalBaseUrl	https://codecharter.tools	Portal address for the rule-draft handoff, see Editing rules in VS Code.

Other editors

The language server is not tied to VS Code. The CLI command

codecharter lsp

starts the CodeCharter DSL language server speaking the Language Server Protocol over stdio (stdin/stdout). Any LSP-capable editor can attach it to .ccr files: configure your editor to launch codecharter lsp as a stdio language server for the .ccr file extension; how to wire up a stdio server is described in your editor's LSP documentation.

The server provides:

• Diagnostics, published when a file is opened or changed.
• Completion for schema properties, triggered by @, ., and space.
• Hover information.
• Semantic tokens (full document) for syntax highlighting.
• Code actions for reported diagnostics.

Document sync is full-document. Like every CLI command, codecharter lsp runs the license check on startup and accepts --license to point at a specific codecharter.license file.

Note that VS-Code-specific features described above (snippets, CodeLens spec actions, codecharter restore on activation, status bar) come from the extension, not from the language server. In other editors you get the language server capabilities listed above.

Editing .codecharter/config.yml

.codecharter/config.yml is the file where you configure profiles, rule parameters, overrides, ignore entries, and analysis scopes — the file every CodeCharter user edits, and one where a mistyped rule slug or parameter name otherwise fails silently instead of erroring. Two ways to get editor support for it, independent of the DSL support above:

A language server, started with:

codecharter config-lsp

Like codecharter lsp, this speaks the Language Server Protocol over stdio; attach it in any LSP-capable editor as the server for config.yml files under .codecharter/. It provides:

• Diagnostics on every change, from the same parser the CLI uses to load the file — structural errors are flagged as you type, not only when you next run codecharter analyze.
• Completion for top-level and scope keys, ignore/include entry keys, coverage keys, and severity values.
• Rule slug completion after rule: and under overrides:, drawn from a rules/ directory next to .codecharter/ when your repository has one. In a workspace that relies only on portal profiles, slug completion is omitted rather than guessed.
• Hover text describing each key.

A JSON Schema, for editors that prefer schema-driven YAML support (for example VS Code's YAML extension via its yaml.schemas setting) over running a second language server. Generate it with:

codecharter config schema --out codecharter.schema.json

See Configuration file for what codecharter config schema covers and for the other codecharter config subcommands. Pick whichever fits your editor: config-lsp gives live diagnostics and rule-slug completion as you type; the JSON Schema route needs no running process but does not know your repository's rule slugs.

Troubleshooting

If the language server does not start:

1. Open the Output panel (View → Output) and select CodeCharter in the dropdown.
2. Check the CLI path. If the CLI is not on the PATH, set codecharter.serverPath explicitly to the full path.
3. Check permissions on Linux and macOS. The binary must be executable (chmod +x codecharter).
4. Enable LSP tracing for detailed diagnostics: set codecharter.trace.server to messages or verbose in VS Code settings. Reset to off when done.

More under VS Code Extension hangs.