[Feature Request] Full built-in `.env.schema` parity in the VS Code extension

[voiys]

Description

I'd like to discuss the forward path for getting the VS Code extension to full built-in DSL coverage in .env.schema files, and how to keep it aligned with runtime/docs over time.

A few current bugs/docs drifts are obvious, narrow, and should just be fixed in small separate PRs. I don't want those to muddy this discussion.

This issue is about the product/engineering path going forward:

• what the coverage bar should be for built-in DSL features
• what is in scope vs out of scope
• how we prevent future drift between runtime, docs, and IntelliSense

Current examples of built-in gaps:

• missing or stale resolver coverage such as ifs() and the old default remap() snippet shape
• incomplete built-in decorator arg coverage like @generateTypes(auto, executeWhenImported), @setValuesBulk(createMissing, enabled), and @import(allowMissing, enabled)
• incomplete builtin VARLOCK_* discovery/help
• limited resolver hover/help compared to decorator hover
• parser/runtime/editor drift around header scope and diagnostics behavior

Motivation

Right now the extension covers a useful subset of the DSL, but it still feels like users need to already know parts of the built-in syntax from memory.

For .env.schema editing, I think the bar should be:

• built-in features are discoverable in-editor
• built-in features are represented accurately
• obvious runtime/parser semantics are reflected in completion/help/diagnostics
• new built-in features do not quietly ship without editor/docs support

In short, I don't think a "75% coverage" experience is the right long-term product shape for built-in DSL features.

Proposed Solution

1. Align on the product bar: full built-in .env.schema parity for the VS Code extension.
2. Keep plugin-defined DSL support as a separate follow-up problem.
3. Treat current built-in gaps as implementation work under that agreed bar.
4. Add guardrails so built-in code/editor/docs parity is checked instead of maintained manually by memory.

The implementation direction that seems most promising:

• built-in-only parity first
• parity tests for built-in names/high-risk metadata
• shared built-in metadata where practical, so runtime/editor/docs are not separate handwritten inventories

Questions worth deciding up front:

• Is full built-in parity the intended product bar?
• Is plugin-defined DSL explicitly out of scope for the first pass?
• Should the extension keep a handwritten static catalog, or should built-in metadata be shared/generated?
• What level of built-in diagnostics parity is worth aiming for in-editor?

Alternatives

Keep the current best-effort/manual approach

This keeps implementation simpler, but it also makes drift likely every time new built-in features land.

Try to solve plugin-defined DSL support first

This feels like it would complicate the discussion too early. Built-in parity seems like the clearer first target.

Explicitly declare limited built-in support

This is an option, but I think it would be a step down from the experience people expect when the built-in DSL is part of the core product.

Additional Information

I’m intentionally keeping obvious current fixes out of this issue and handling them as small separate PRs, since they seem low-risk and don’t really need architectural debate:

• #464 - docs reference drift
• #465 - VS Code header context parsing
• #466 - VS Code duplicate decorator rules
• #467 - VS Code diagnostics comment awareness

Future consideration to keep in mind:

• custom validation already seems to fit reasonably well via plugin-defined data types, including async validation (I saw it mentioned on Discord)
• if we later want more expensive active checks like "test this DB connection now", that may deserve a separate concept from normal @type validation
• that future consideration does not need to block the built-in parity discussion

[voiys]

Wanted to float a broader architecture question that I've been thinking about.

I’m still pretty new here, so this is me thinking out loud rather than trying to prescribe the direction. But since I worked on the VS Code extension, one thing I’m starting to worry about is the long-term maintenance cost of implementing the same behavior separately per editor.

Right now we have the VS Code extension in TS, #473 is adding IntelliJ support, and #478 is already asking for a Zed extension with VS Code feature parity.

My concern is that if parsing, validation, completions, masking, variable resolution, etc. keep getting implemented natively per editor, we could end up with duplicated logic and eventual drift whenever env-spec behavior changes.

Because of that, I wonder if it’s worth thinking about a shared “core + shim” model longer-term:

• shared core for parsing / validation / editor intelligence
• thinner editor-specific integrations on top
• native editor code only where it really pays off

Maybe that shared core ends up looking like a language-server-style layer, maybe not, but the general idea would be to centralize the logic we want to behave the same everywhere while still letting each editor handle its own UX/integration details.

Not suggesting we stop #473 or rewrite anything right now — it just feels like this might be the right time to talk about whether we want to keep scaling editor-by-editor implementations, or define a shared core that future editor support can build on.

For context, here’s a rough compatibility snapshot for an LSP-style approach across relevant editors:

Editor / IDE	LSP support	Notes
VS Code	Yes	First-class fit
Visual Studio	Yes	Official path
IntelliJ IDEA	Yes, with caveats	Possible, but native integrations go deeper
PyCharm	Yes	Same JetBrains story
Android Studio	No / limited	Main JetBrains-family exception
Zed	Yes	Strong fit
Neovim	Yes	Built-in client
Vim	Yes, via plugin	Plugin-based
Emacs	Yes, via Eglot / lsp-mode	Plugin-based
Cursor	Mostly yes	VS Code-compatible extension model
Notepad++	Partial	Plugin-based
JupyterLab	Partial	Extension-based

Not saying that means zero editor-specific work — just that LSP seems like a pretty normal foundation if the goal is to avoid reimplementing the full smart layer over and over.

[theoephraim]

Thanks for bringing this all up. Some kind of shared core definitely makes sense, and now would probably be the time to do it! I don't quite know what it would look like, but worth digging in. I also wonder how much logic can be offloaded to the parser itself rather than having to recreate a lot of it. Obviously the parser currently explodes when things go wrong, whereas in a language server setting, it needs to be a bit more forgiving. If I remember correctly, the zed extension will need a tree-sitter implementation, which is built exactly for this purpose. Perhaps it could even replace the peggy powered parser we currently have, but can make that call later. (Although the peggy one generates pure JS with no deps!)

I also agree that the more we can DRY things up the better - so for example pulling/generating intellisense content about a decorator from the same place the decorator is defined.

On that note, while supporting plugin decorators/types/etc now may seem like an unnecessary side-quest, I feel that it may point us architecturally in a certain direction that we would not necessarily go in otherwise, but would be forced to change to later. I think you either end up with some kind of language server evaluating the files and loading the plugins, or you have the the loading process spit out some generated JSON that the plugins interact with. The first one introduces some security issues since it would potentially be executing plugin code. A middle ground could be that a plugin need to expose a json manifest of what it adds. Since we control the whole plugin pipeline and all the plugins (for now), we can build tooling that generates it at build time to maintain a single source of truth.

As for the bar we set - I agree we should strive for full coverage. I think the only exception would be that we may occasionally want to introduce some beta features to play around with, but that should likely be rare, and temporary. While this high bar makes things a bit more daunting, considering AI is authoring a lot of code anyway, it shouldn't be too bad once we have a solid foundation.

Know of any similar projects we can look at for some inspiration here on the LSP side of things?

[theoephraim]

@voiys - im gonna get all your PRs merged. THANK YOU. But we should definitely start thinking through this shared core approach because it will quickly get out of hand with multiple plugins to support.

[voiys]

@voiys - im gonna get all your PRs merged. THANK YOU. But we should definitely start thinking through this shared core approach because it will quickly get out of hand with multiple plugins to support.

Awesome, thanks a lot. Yeah agreed — I spent a bit of time looking into how other projects handle this, and there seems to be a pretty consistent pattern: shared language/core logic or an LSP-style server, with thin editor-specific adapters on top. Vue/Volar, YAML LS, GraphQL tooling, Prisma, Svelte, etc. all seem to lean that way to varying degrees.

I didn’t find a perfect 1:1 match for varlock specifically, but the overall direction looks pretty standard: keep parsing/semantics centralized, let editors handle UX/integration, and for extensibility prefer declarative metadata/manifests where possible instead of duplicating smart behavior per editor. Cooking up a v1 of it pretty soon and posting a PR so y'all can have a look!

[philmillman]

awesome @voiys, since the intellij one is still in limbo I think it might make sense to just port it to this new arch if we all agree it's going to be the best way forward