Central deprecation-warning pass for v1 removals [v1 0.x]

[ricardo-devis-agullo]

Part of the OpenComponents v1 roadmap (see V1.md), Track 1 (non-breaking 0.x work). This is the keystone that lets v1 be "mostly removals": it warns users now about config/APIs that v1 will remove, without breaking anything.

Problem Statement

As a registry operator (and as a component developer using oc.json), several configuration options and conveniences are already slated for removal in v1 — the legacy s3 shortcut, the redundant refreshInterval, the boolean form of discovery, and the deprecated mocks block in oc.json — but nothing tells me they are going away. When v1 lands and removes them, my registry or local setup will break with no prior warning and no migration guidance. There is also no consistent, single mechanism for OC to signal deprecations, so the few warnings that exist today are ad hoc.

Solution

As a registry operator or component developer, I want OC on 0.x to emit a clear, consistent, one-time deprecation notice whenever I use an option that v1 will remove, telling me exactly what to switch to, so that I can migrate calmly before upgrading to v1 and experience v1 as a no-surprise release. Everything keeps working on 0.x; the notices are informational only.

User Stories

1. As a registry operator, I want a single, consistent deprecation-notice format across OC, so that deprecation messages are recognizable and greppable in my logs.
2. As a registry operator using the s3 config shortcut, I want a deprecation notice telling me to move to an explicit storage.adapter/storage.options, so that I can migrate before v1 removes the shortcut.
3. As a registry operator using refreshInterval, I want a deprecation notice telling me to use pollingInterval instead, so that I can consolidate onto the supported option.
4. As a registry operator passing discovery: true / discovery: false (boolean), I want a deprecation notice telling me to use the object form (discovery: { ui, api, ... }), so that I can adopt the shape v1 requires.
5. As a component developer with a mocks block in oc.json, I want a deprecation notice telling me to move plugin mocks to development.plugins, so that my local dev config keeps working in v1.
6. As a registry operator, I want each distinct deprecation to warn only once per process (not on every request or every poll), so that my logs are not flooded.
7. As a registry operator, I want every notice to name the offending option, the replacement, and that it will be removed in v1, so that I have everything I need to fix it.
8. As a registry operator, I want deprecated options to continue functioning exactly as before on 0.x, so that emitting a notice never changes runtime behavior.
9. As a maintainer, I want a single deprecation utility that all these call sites use, so that future v1 deprecations (e.g. callback APIs) can reuse it.
10. As a maintainer, I want the deprecation utility to support suppression/opt-out via a standard mechanism, so that noisy environments (e.g. CI) can silence notices if needed.
11. As a maintainer, I want each deprecation keyed by a stable identifier, so that "warn once" is reliable and testable.

Implementation Decisions

• Introduce one shared deprecation-notice utility in the oc package (a small internal module) that: formats a consistent message, deduplicates by a stable key so each deprecation fires at most once per process, and routes through a standard warning channel (Node's process.emitWarning with a DeprecationWarning type is the preferred channel; align with any existing warning emission already used by the storage-adapter legacy path).
• Wire the utility into the registry config entry seam (the options-sanitiser) for: s3 shortcut, refreshInterval, and boolean discovery.
• Wire the utility into the CLI/local config entry seam (the oc.json parser) for: the mocks block.
• Each notice includes: the deprecated option name, the concrete replacement, and a note that it is removed in v1.
• No behavioral change to any deprecated option — they keep resolving/merging exactly as today; the notice is purely additive.
• Support an opt-out consistent with Node conventions (e.g. honoring --no-deprecation/NODE_OPTIONS behavior that process.emitWarning already respects), so no bespoke env var is strictly required.
• Consolidate the pre-existing ad hoc deprecation messages (legacy storage adapter, legacy template on oc init) to route through the same utility where practical, so messaging is uniform. If that consolidation is risky, it may be deferred, but new deprecations must use the shared utility.

Testing Decisions

• Good tests assert external behavior at the config-entry seams: given a config that uses a deprecated option, a deprecation notice is emitted (once) and the resolved/sanitised config is otherwise unchanged. Do not test the internal shape of the utility beyond its public contract.
• Test at two existing high seams: the registry options-sanitiser (for s3, refreshInterval, boolean discovery) and the oc.json config parser (for mocks). No new seams are introduced.
• For each deprecated option: assert a notice is produced, assert it is produced only once for repeated use, and assert the sanitised/parsed result still behaves as before (e.g. s3 still yields a working storage config, boolean discovery still expands to the correct object, mocks.plugins still merges into development plugins).
• Prior art: existing options-sanitiser unit tests and ocConfig/config-parsing tests in the oc package — extend these; capture warnings via the standard warning mechanism in tests.

Out of Scope

• Removing any of these options — that is the v1 change.
• Deprecating the callback registry/plugin/adapter APIs (the promise-first work introduces its own soft notice; it may reuse this utility once available, but wiring all callback sites is separate).
• The legacy jade/handlebars template deprecation on oc init beyond optionally re-routing the existing message through the shared utility.
• tarExtractMode correction and adapter-neutral error codes (v1/registry items).

Further Notes

• Landing this first makes the promise-first API's soft deprecation notice trivial to add, and makes v1 a low-surprise upgrade.
• Keep messages actionable and short; prefer "X is deprecated and will be removed in OpenComponents v1 — use Y instead."