Artificonfig for VS Code

Intelligent authoring support for Artificonfig YAML and JSON configuration files: validation, navigation, auto-completion, hover documentation, syntax highlighting and quick fixes — powered by a Python language server that talks directly to the artificonfig library installed in your environment.

Links

Report bugs in the extension (highlighting, completions, diagnostics, commands) to the extension repository. Report bugs in the config format or runtime behaviour to the library repository.

The Artificonfig: Report Issue... command opens a pre-filled issue template containing your environment details and can take you straight to the extension's issue tracker.

Requirements

• VS Code 1.80.0 or newer
• Python 3.10 or newer, with the artificonfig library installed (1.0.0 or newer)

The extension picks up the interpreter selected by the Python extension. To pin a specific one, set artificonfig.python.interpreterPath.

If the library is missing or too old, the extension tells you and offers to run the install/upgrade command for you (uv pip install --upgrade artificonfig). The notification is non-blocking — VS Code keeps working while it is on screen.

Getting started

1. Install the extension and make sure artificonfig is importable from your selected Python interpreter.
2. Open a workspace containing config files. Files are treated as Artificonfig configs when they contain a <BASIC:...>, <OBJECT:...>, <COMMAND:...> or <LINK:...> node.
3. Check the Artificonfig item in the status bar — a check mark means the language server is running. Click it for a quick info menu.

By default the extension scans the workspace at startup and reports problems for every config file it finds. Use artificonfig.workspace.configRootPath and artificonfig.workspace.additionalConfigPaths to control what gets scanned.

Features

Validation

Diagnostics are produced at four increasing levels of depth. The level used while you type is artificonfig.validation.level; the (cheaper) level used for the startup scan is artificonfig.workspace.startupScanLevel.

Additional checks:

• Link resolution — <LINK:...> targets are resolved and reported when missing. Links resolve against the closest ancestor folder named configs; if there is none, you get a warning explaining that resolution fell back to the configured root.
• Legacy syntax — files using the old @OBJECT_CONFIG / @SIMPLE_CONFIG / @COMMAND_CONFIG / @CONFIG_LINK markers are flagged with a single clear error plus a quick fix to convert them.
• Environment variables — ${VAR}, ${VAR:-default} and ${VAR-default} are understood; unresolved variables without a default are reported.
• Live updates — the model cache is invalidated when you edit the Python classes your configs point at, so diagnostics follow your code without a restart.

Navigation (Go to Definition)

F12 / Cmd+click on:

• a config node class path (<BASIC:my.module.MyConfig>) → opens the Python class
• a <TARGET> value → opens the target Python class
• a <LINK:shared.database> path → opens the linked config file

Auto-completion

Triggered by <, :, ., / or Ctrl+Space:

• Config node types — typing < at the start of a line suggests BASIC, OBJECT and COMMAND with full snippets (the OBJECT snippet includes its <TARGET> line).
• Value-position nodes — typing < after field: suggests LINK and ENV.
• Class paths — after <BASIC: etc., suggests config classes discovered in the workspace.
• Target classes — after <TARGET>:, suggests concrete implementation classes.
• Link paths — after <LINK:, suggests other config files, resolved relative to the config root.
• ENV placeholder types — after <ENV:, suggests the supported placeholder types (currently None).
• Environment variables — after $ or ${, suggests names from your environment together with their current values.
• Field names — inside a config node, suggests the remaining Pydantic fields of the parent model, with type hints and snippets, and hides fields you already used.

Hover

Hovering shows:

• config and target classes — docstring, module path and field summary
• field names — declared type, default value, and whether the field is required
• <LINK:...> paths — the resolved file path and its root config node
• ${VAR} references — the current value from the environment, or the default that will be used

Syntax highlighting

A TextMate injection grammar highlights Artificonfig markers inside otherwise ordinary YAML and JSON:

• config nodes <BASIC:...>, <OBJECT:...>, <COMMAND:...>
• the <TARGET> key
• config links <LINK:...>, including env-var substitutions inside the path
• typed placeholders <ENV:None>
• env-var substitutions ${VAR}, ${VAR:-default}, ${VAR-default}

Escaping is honoured: anything escaped with a backslash — \<BASIC:key>, \<TARGET>, \<LINK:path>, \${VAR} — is rendered as ordinary text using your theme's normal string/key colour, exactly as the library treats it.

<ENV:...> is only highlighted when it is the entire value, or the entire default of a substitution as in ${VAR:-<ENV:None>}. This matches the library, which leaves as<ENV:None> as a plain string.

Colours are contributed as defaults and can be overridden per theme via editor.tokenColorCustomizations.

Quick fixes and code actions

Available from the lightbulb or Cmd+.:

• Convert this file to new artificonfig syntax — offered anywhere inside a legacy file
• Convert all files in a directory to new artificonfig syntax...
• Add <TARGET> field — for OBJECT nodes that are missing it
• Change to '<type>' — corrects an invalid or misspelled config type
• Fix path to '<path>' — corrects a mistyped module path when a close match exists
• Generate stub for <Class> (required fields) — fills in the required fields of the referenced Pydantic model

Config preview

The Preview Config Output command — also available as the preview icon in the editor title bar for recognised config files — runs the config through artificonfig and shows the fully resolved result, with links expanded and environment variables substituted. The preview refreshes automatically when you save the file.

Format conversion

Convert File Format... converts the open config between YAML and JSON, preserving escaping, and asks where to write the result.

Diagnostics for your setup

• The status bar item reports whether the language server is running, and opens a quick menu with the detected library version, interpreter, config root and file counts.
• Show Info (Detailed Panel) writes the same report to the output channel.
• Set artificonfig.trace.server to messages or verbose to log the LSP traffic.

Commands

All commands are available from the Command Palette (Cmd+Shift+P) under the Artificonfig prefix.

Settings

Troubleshooting

No highlighting or diagnostics in a config file. The extension only treats files containing an Artificonfig node as configs. Confirm the file has a root <BASIC:...> / <OBJECT:...> / <COMMAND:...> node, and that the status bar shows the server as active.

"artificonfig library not found". The selected interpreter cannot import the library. Select the right interpreter, or set artificonfig.python.interpreterPath, then run Restart Language Server.

Unexpected schema errors on <BASIC:...> keys. Another YAML schema is being applied. Make sure artificonfig.yaml.overrideSchema is enabled and reload the window.

<LINK:...> resolves to the wrong file. Links resolve against the closest ancestor directory named configs. Set artificonfig.workspace.configRootPath if your layout differs.

Files outside the config root are ignored by the startup scan. Use Add Current File / Directory to Config Paths.

For anything else, run Artificonfig: Report Issue... — it collects the environment details needed to diagnose the problem.

Contributing

Development setup, architecture notes and the release process live in CONTRIBUTING.md and the docs/ folder:

• docs/planning.md — architecture and strategy
• docs/implementation.md — feature implementation details
• docs/artificonfig-syntax.md — syntax reference
• docs/testing-and-release.md — testing and packaging
• docs/quick-reference.md — summary and future work
• docs/todo.md — progress tracker

git submodule update --init --recursive   # the artificonfig library is a submodule
make install-dev                          # Node.js + Python dependencies
make compile                              # build the TypeScript client
make test                                 # run the test suites
make help                                 # all available targets

License

See LICENSE.