deprecation (module)

Answers whether an asset is deprecated, why, and what replaces it. An asset states it in its own .metadata:

{ "deprecated": { "reason": "one line why", "replacedBy": "@builtin::assetTypes.effect" } }

The marker works for any asset, builtin or published. It is passed down:

• an asset is deprecated when a folder holding it at any depth (a package, a toolbox, any folder asset) carries the marker, so marking a package covers everything inside it;
• an asset is deprecated when its asset type carries the marker, so marking a type covers every instance of it.

Assets stay resolvable and loadable by identity and guid. Search surfaces do not index or offer them.

Reading it

local deprecation = require("modules.deprecation")
local d = deprecation.of("@builtin::deprecated.deprecatedParticles.DeprecatedParticleEmitter")
if d then
    print(d.via, d.reason, d.replacedBy) -- "container", "...", "@builtin::assetTypes.effect"
end

deprecation.of(ref, memo?) is the one function that answers. via says where the marker is held: "asset", "container" or "type"; source is the folder holding it. Pass one memo table across the calls of a pass so each folder's .metadata is read once.

deprecation.indexed(ref, memo?) is true unless the asset is deprecated; every search surface asks it before it reads an asset.

deprecation.warnOnce(handle) logs one warning per asset per session naming the asset, the reason and the replacement; asset.resolve, asset.tryResolve and asset.ref call it. deprecation.describe(subject, found) renders the sentence and deprecation.forget() resets what has warned.

asset.deprecation(ref) answers the same as of from the asset namespace.