Support @custom:override-namespace-id annotation to override namespace ID

[ernestognw]

Summary

• Add support for a @custom:override-namespace-id <Name> NatSpec annotation on contracts to override the namespace ID used in the ERC-7201 storage struct generation.
• When present, the transpiler uses the annotation value instead of the contract name for the struct name, storage location ID, location constant, and getter function.

Motivation

When refactoring contracts (e.g. extracting a base contract from an existing one), the storage variables may move to a new contract with a different name. Without an override, the transpiled upgradeable version would produce a different ERC-7201 namespace (e.g. openzeppelin.storage.ERC20Vault instead of the existing openzeppelin.storage.ERC4626), breaking storage compatibility for deployed proxies.

This annotation allows the source contract to declare the intended namespace identity, preserving backward-compatible storage layouts across such refactors.

Changes

• src/utils/natspec.ts: Add extractTranspileNamespace() to extract the @custom:oz-transpile-namespace annotation from a contract's NatSpec documentation.
• src/transformations/add-namespace-struct.ts: Use the override (if present) instead of contract.name when deriving the namespace struct name and openzeppelin.storage.* ID.
• src/transformations/transform-constructor.ts: Use the override (if present) when emitting the namespace storage getter in the generated initializer.
• contracts/namespaces-override.sol: Test fixture with contracts annotated with @custom:oz-transpile-namespace.
• src/transform-namespaces.test.ts: Snapshot test for the namespace override behavior.