Add @deprecated item decorator

[Copilot]

Adds a @deprecated decorator for env-spec config items that surfaces a deprecation warning (never a hard error) and annotates generated TypeScript types with @deprecated JSDoc so IDEs show strikethrough on access.

Decorator behavior

# @deprecated                          # warns: "This config item is deprecated"
# @deprecated="Use NEW_API_KEY instead" # warns with message
# @deprecated=false                    # explicit opt-out (no warning)
OLD_API_KEY=

• Item still resolves normally — deprecation produces a warn validation state, not error
• @deprecated=false allows opt-out (useful for override scenarios)

Changes

• decorators.ts — registers deprecated in builtInItemDecorators; process() throws a warning SchemaError with the optional message appended after :
• config-item.ts — adds isDeprecated and deprecationMessage getters using simplifiedValue from the parsed decorator (no async resolution needed); extends TypeGenItemInfo with both fields
• type-generation.ts — emits @deprecated [message] JSDoc tag when info.isDeprecated is true, enabling IDE strikethrough on deprecated env accesses
• deprecated-decorator.test.ts — tests for warning-only behavior, message formatting, @deprecated=false opt-out, validationState === 'warn', getter values, and type gen info

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• api.iconify.design
  • Triggering command: /usr/local/bin/node /usr/local/bin/node --experimental-import-meta-resolve --require /home/REDACTED/work/varlock/varlock/node_modules/vitest/suppress-warnings.cjs --conditions node --conditions development /home/REDACTED/work/varlock/varlock/node_modules/vitest/dist/workers/forks.js /home/REDACTED/.nvm/package.json /home/REDACTED/.nvm/rename_test.sh /home/REDACTED/.nvm/test k/no�� m (dns block)
  • Triggering command: /usr/local/bin/node /usr/local/bin/node --experimental-import-meta-resolve --require /home/REDACTED/work/varlock/varlock/node_modules/vitest/suppress-warnings.cjs --conditions node --conditions development /home/REDACTED/work/varlock/varlock/node_modules/vitest/dist/workers/forks.js journal-or-kmsg ndor/bin/git tail bin/�� (dns block)
  • Triggering command: /usr/local/bin/node /usr/local/bin/node --experimental-import-meta-resolve --require /home/REDACTED/work/varlock/varlock/node_modules/vitest/suppress-warnings.cjs --conditions node --conditions development /home/REDACTED/work/varlock/varlock/node_modules/vitest/dist/workers/forks.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[bumpy-bot]

The changes in this PR will be included in the next version bump.

Patch releases

• varlock 0.9.1 → 0.9.2

Bump files in this PR

• add-deprecated-decorator.md (view diff) (edit)

Click here if you want to add another bump file to this PR

---

This comment is maintained by bumpy.

[theoephraim]

Im not sure about having a warning here. I thought it would just add it to the generated ts types?
The user knows it's likely still set, or else they would remove it from the schema altogether.

We could potentially still mark it somehow in the varlock load output, but the warning may be a bit too agressive?

[philmillman]

Yeah I'm on the fence there too. I could see a case for warning, especially in CI, but maybe we put it behind a flag?

[theoephraim]

prob want one too checking the type output with just the @deprecated and no custom message

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/varlock@644

commit: 744aa2b