Skip to content

.metalib metadata sidecar for NuGet-shipped libraries #27

@danfma

Description

@danfma

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

Part of #14.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions