You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Background:ADR-0004 explains that the current cross-project flow reuses Roslyn compilation references, which works for `ProjectReference` inside a solution / Bun monorepo. Libraries distributed as NuGet packages with no source can't be consumed that way — Roslyn sees the assembly metadata but has no knowledge of which types Metano has transpiled, which package they map to, or what guard info exists.
This issue tracks the follow-up: a binary metadata sidecar file (`.metalib`) that captures the cross-assembly info a NuGet-shipped library needs to expose.
Goal
Design and implement a `.metalib` format that a Metano-annotated library embeds in its NuGet package, and that a consumer's transpiler reads during cross-assembly resolution. The consumer should be able to import from a NuGet-packaged Metano library identically to how it imports from a `ProjectReference` today.
Scope
Schema design — what exactly goes in the file?
Type signatures (namespace, name, kind, modifiers, generics, inheritance)
Target-specific metadata (TypeScript sub-path, branded type info, JSX element info when applicable)
Dependency declarations (referenced packages from `[Import]`, `[ExportFromBcl]`, sibling `[EmitPackage]`)
Runtime guard info when `[GenerateGuard]` was used
Format: JSON (debuggable, git-diffable) vs MessagePack / MemoryPack (compact, fast). Start with JSON for the MVP.
Generation — emit `.metalib` during transpilation alongside the `.ts` files
Embedding — `.csproj` targets that copy `.metalib` into the NuGet package's `content` or `build` folder
Consumption — on the consumer side, when walking `compilation.References`, detect NuGet-sourced assemblies that ship a `.metalib` and feed its contents into `_crossAssemblyTypeMap` alongside the Roslyn-derived entries
Disambiguation — when both a `.metalib` and Roslyn metadata describe the same type, the `.metalib` wins (it's the target-aware source)
Tests covering the round-trip: produce `.metalib` from a library, consume it from a different compilation as if it were a NuGet package
A sample that exercises the flow end-to-end
Constraints
Must coexist with the existing `ProjectReference` flow — don't regress the monorepo use case
Format must be forward-compatible (add fields without breaking older consumers) and backward-compatible (older libraries without `.metalib` still work via Roslyn references)
No hard dependency on Newtonsoft / System.Text.Json at read time — the transpiler already uses `System.Text.Json` for `package.json` writing, reuse that
Background: ADR-0004 explains that the current cross-project flow reuses Roslyn compilation references, which works for `ProjectReference` inside a solution / Bun monorepo. Libraries distributed as NuGet packages with no source can't be consumed that way — Roslyn sees the assembly metadata but has no knowledge of which types Metano has transpiled, which package they map to, or what guard info exists.
This issue tracks the follow-up: a binary metadata sidecar file (`.metalib`) that captures the cross-assembly info a NuGet-shipped library needs to expose.
Goal
Design and implement a `.metalib` format that a Metano-annotated library embeds in its NuGet package, and that a consumer's transpiler reads during cross-assembly resolution. The consumer should be able to import from a NuGet-packaged Metano library identically to how it imports from a `ProjectReference` today.
Scope
Constraints
Part of #14.