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

Open
  • Is something wrong?
#469 6 comments 3 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Quiet
Tech stack
typescript, vscode
Domain
developer-experience, tooling

Research direction

Start by reviewing the VS Code extension’s built-in DSL catalog and its parity with runtime and documentation; the issue does not name specific files or tests. First decide the coverage bar, plugin scope, metadata strategy, and diagnostics goals, then map the agreed work into implementation tasks. Done means built-in features are discoverable and accurately represented, with guardrails against future drift.

Written by the indexing model from the issue text.

Description

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
Dominant language
TypeScript
Stars
4.9k
Forks
140
Avg merge
2d 3h
Merged PRs (30d)
35

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from dmno-dev/varlock

All issues in dmno-dev/varlock

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.