Add legacy TypeScript decorator metadata support

[TheHypnoo]

Summary

Adds the first usable legacy TypeScript decorator metadata path for Perry, focused on NestJS-style dependency injection canaries. The compiler keeps using SWC for parsing, but lowers decorators directly through HIR, codegen, and Perry runtime metadata rather than relying on emitted JavaScript helpers.

What changed

• Preserve class, method, property, and parameter decorators in HIR.
• Lower legacy decorator evaluation and invocation order.
• Emit decorator-related design metadata, including constructor design:paramtypes, property design:type, method design:paramtypes, and design:returntype.
• Add a minimal Reflect.*Metadata runtime subset and JS runtime bridge.
• Treat reflect-metadata imports as compatible with Perry-provided metadata hooks.
• Add Nest-like canaries covering injectable metadata, constructor injection metadata, metadata constants, scanner-style access, CommonJS decorator helpers, module imports, inheritance, and explicit unsupported class replacement behavior.

Compatibility notes

This targets legacy TypeScript decorators because NestJS, TypeORM, and similar frameworks rely on that ecosystem behavior. Full unmodified NestJS or TypeORM compatibility is still broader than this PR, but the main DI metadata path is now represented by focused parity canaries.

Class decorator replacement return values remain unsupported and are covered by an explicit negative canary.

Validation

• cargo build --release -p perry-jsruntime -p perry
• ./run_parity_tests.sh --filter decorators
• cargo fmt --check
• cargo test -p perry-hir -p perry-codegen -p perry-runtime --lib

[proggeramlug]

Thanks for putting this together — the implementation is cleaner than I'd expect for a feature this size (additive IR variants, gated runtime cost, no panics in the Reflect surface, real DI simulation in the integration canary). Before merging I want to nail down two questions about what this actually unlocks for users.

1. Does a real NestJS app boot on this?

The canaries pass, but they're hand-rolled — resolveProvider in test_decorators_nest_integration_canary.ts is bespoke test code, not @nestjs/core itself. To prove this PR delivers the win it's pitched on, can you add one end-to-end smoke test that:

• Starts from npx @nestjs/cli new (or the minimal equivalent — a package.json with @nestjs/common @nestjs/core reflect-metadata and a hand-written AppModule/AppController/AppService)
• Compiles with perry (using compilePackages if needed)
• Listens on a port and serves GET / returning a string

If you can get that working, the DX value is concrete. If you hit walls, the walls are what we need to see — they'll tell us how much further work is needed before this is usable end-to-end. Either way the smoke test belongs in tests/release/packages/ so it doesn't regress.

2. Two silent-failure cases I'd like to convert to compile errors before merge:

(a) import "reflect-metadata" is currently lowered to Ok(()) in crates/perry-hir/src/lower.rs:1213 — the import is silently dropped and Perry's built-in shim runs instead. The shim covers the methods this PR implements, but it's a subset of the npm package's surface (class-validator and TypeORM call into corners of reflect-metadata that aren't shimmed). Users importing the npm package will think they have the full thing. Suggested fix: keep the suppression but emit a one-time [perry] note: reflect-metadata import shimmed by built-in subset diagnostic at compile time, listing the methods Perry actually implements. That way the user knows what they're getting.

(b) Class decorators that return a replacement class currently run the decorator for side-effects and discard the return value — test_decorators_replacement_unsupported.ts documents this but doesn't enforce it. Real-world decorators like @Memoize, @Throttle, GraphQL resolver wrappers all return wrapped classes; they'd compile and run incorrectly. Suggested fix: detect at lowering time that a class decorator's resolved type is a ClassDecorator returning non-void/undefined and emit a compile error. If type-level detection is too fiddly, a runtime check at decorator-application time that throws on non-undefined return is acceptable as a fallback — anything beats silent failure.

Once those two are in and the NestJS smoke test compiles + serves a route, I'm comfortable merging. Appreciate the work — the metadata pipeline itself is well-scoped.

[TheHypnoo]

Thanks for the structured review. Pushed the work as four commits + a follow-up docs regen on top of the original PR.

2a (reflect-metadata shim diagnostic) — done. c04df7ad. import "reflect-metadata" now emits a one-shot [perry] note: … to stderr at compile time listing the implemented surface (defineMetadata, getMetadata, getOwnMetadata, hasMetadata, hasOwnMetadata, getMetadataKeys, getOwnMetadataKeys, deleteMetadata, @Reflect.metadata(...)) and pointing at docs/src/language/decorators.md. Guarded by an AtomicBool so repeated imports across the dep graph don't spam.

2b (class decorator replacement returns) — done as runtime throw, your suggested fallback. Same commit. append_class_decorator_invocations in crates/perry-hir/src/lower.rs captures the decorator return into a temp and, when typeof ret === "function", throws TypeError: Class decorator @<name> on <Class> returned a replacement class …. I used typeof === "function" rather than !== undefined to work around an unrelated Perry quirk (function-expression implicit returns leave a numeric sentinel in the return slot, which made !== undefined false-positive on bare side-effect decorators like @Injectable). Class refs are typeof "function" in JS, so this catches the @memoize / @Throttle / GraphQL-wrapper pattern precisely. The test_decorators_replacement_unsupported canary flipped from "replacement ignored" (silent) to the TypeError header.

1 (NestJS smoke test) — fixture wired, three walls broken, fourth documented. fc020ebb.

tests/release/packages/nestjs-hello/ follows the hono-basic layout: package.json with @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata rxjs + compilePackages, entry.ts with @Module / @Controller / @Injectable / @Get + NestFactory.create(AppModule) + app.listen(port), fixture.sh that does npm install → perry compile → run in background → curl / → diff. Listens for real on a port, no bespoke resolveProvider.

Walls fixed in this PR:

• util.types not in the API manifest — added property("util", "types") plus a real types surface in node:util (isPromise/isAsyncFunction/isMap/isUint8Array/isProxy/etc., unknown shapes default to false).
• super.<prop> value-form lowering hit a hard lower_bail! — lowered to this.<prop> / this[expr]. Correct when the subclass doesn't override the property (covers rxjs's OperatorSubscriber this._next = onNext ? wrapper : super._next pattern). Strict parent-vtable lookup is the proper fix; left as a TODO with an inline comment.
• async_hooks.AsyncResource missing — added AsyncResource + AsyncLocalStorage (+ executionAsyncId, createHook) to a real node:async_hooks stub. No real async-context tracking, but the runInAsyncScope shape is enough for the NestJS code path.

4ce4e693 regenerates docs/api/perry.d.ts + docs/src/api/reference.md for the new manifest entries (caught by the api-docs-drift gate).

Wall 4 — open: cross-module method symbol mangling for re-exported classes. Compile + codegen succeed; link fails on _perry_method_node_modules_rxjs_src_index_ts__Subscription__unsubscribe etc. The class is defined in rxjs/src/internal/Subscription.ts but callers reference it via the rxjs/src/index.ts barrel and Perry uses the barrel's prefix instead of the defining module's. The fixture file WALLS.md describes it and the probable next walls (the same bug from @nestjs/platform-express's ExpressAdapter, then likely Logger / setImmediate edges).

Structurally I think Wall 4 wants its own focused PR — it's surgery on crates/perry/src/commands/compile.rs and possibly crates/perry-codegen/src/codegen.rs, unrelated to decorator metadata. Same for whichever walls show up after that. The fixture is wired to SKIP-with-reason while WALLS.md is present and flips to hard FAIL the moment WALLS.md is removed, so each follow-up PR can chip away with a clear regression net.

Decorator parity still 12/12. CI is re-running on 4ce4e693.

[proggeramlug]

Audited the changes against the discussion above — both 2a (one-shot reflect-metadata note via AtomicBool::swap + correct surface listing) and 2b (Expr::TypeErrorNew with the typeof === "function" check) match the implementation claims, and the NestJS smoke fixture's SKIP-while-WALLS.md-exists / hard-FAIL-once-removed mechanism is well-designed. CI is green across all gates and decorator parity is 12/12.

Filed three follow-up issues for the deferred items so the trail isn't lost — none are merge blockers, and the first two are explicitly acknowledged as TODOs in the PR's own inline comments / WALLS.md:

• super.<prop> value-form lowering silently returns child override instead of parent #774 — super.<prop> value-form lowering returns the child override instead of the parent. The rxjs / NestJS pattern (no override) is correct; user code that overrides will silently get the wrong value. Includes a regression-test snippet.
• AsyncLocalStorage stub silently drops async context — emit shim diagnostic on async_hooks import #775 — AsyncLocalStorage is a structural stub with no real context tracking. Same silent-failure shape as the original 2a request — a [perry] note: on async_hooks import would close the loop for Sentry / OpenTelemetry / NestJS request-scoped users.
• Function-expression implicit return leaves numeric sentinel in return slot instead of undefined #776 — Function-expression implicit return leaves a numeric sentinel in the return slot instead of NaN-boxed undefined. This is the underlying bug that forced 2b to use typeof === "function" instead of !== undefined; once fixed, the decorator check can be tightened to also catch decorators returning non-function replacement values.

Approving.