richlander/source-annotations

SourceAnnotations

Embed curated file annotations in PDB files so tools and AI agents can discover what matters in a library's source repository.

What This Library Does

SourceAnnotations is a companion to SourceLink. Where SourceLink maps binary symbols to source URLs, SourceAnnotations lets library authors tag specific files — docs, migration guides, key source files — with human-readable descriptions and freeform role tags. These annotations are embedded in the PDB and travel with the binary.

Key Concepts

• Annotations are (path, role, description) tuples stored as a JSON blob in the PDB's CustomDebugInformation table.
• Paths are repo-relative. Combined with SourceLink, they resolve to exact-commit URLs.
• Roles are freeform strings like llm-context, breaking-change, migration-guide, api-surface. Consumers filter on roles they understand.
• GUID: The well-known identifier for the annotation blob is a7e2f251-4cd1-4bfc-a2f0-e3e8e8d1f74b.

Architecture

src/
  SourceAnnotations/              Core model + reader library
    SourceAnnotation.cs           Record: (Path, Role?, Description?)
    SourceAnnotationsDocument.cs  Record: (Version, Annotations)
    SourceAnnotationsGuids.cs     Well-known GUID constant
    SourceAnnotationsReader.cs    Read annotations from PDB files

  SourceAnnotations.Tasks/        MSBuild integration
    GenerateSourceAnnotationsTask.cs   ITaskItem[] → JSON file
    EmbedSourceAnnotationsTask.cs      JSON + PDB → modified PDB
    build/
      SourceAnnotations.Tasks.props    Convention auto-discovery
      SourceAnnotations.Tasks.targets  Build target wiring

Public API

// Core types
record SourceAnnotation(string Path, string? Role, string? Description);
record SourceAnnotationsDocument(int Version, IReadOnlyList<SourceAnnotation> Annotations);

// Reader
static class SourceAnnotationsReader
{
    static SourceAnnotationsDocument? Read(string pdbPath);
    static SourceAnnotationsDocument? Read(MetadataReader reader);
}

// GUID
static readonly Guid SourceAnnotationsGuids.SourceAnnotationsId;

MSBuild Integration

Authors add <SourceAnnotation> items to their project file:

<ItemGroup>
  <SourceAnnotation Include="SKILL.md" Role="llm-context"
    Description="LLM-optimized library guide." />
</ItemGroup>

The GenerateSourceAnnotations target runs after CoreCompile:

1. GenerateSourceAnnotationsTask — deduplicates items (last-writer-wins), validates paths are relative with no .. traversal, writes JSON.
2. EmbedSourceAnnotationsTask — reads the standalone PDB, copies all debug tables, adds/replaces the CustomDebugInformation row, writes back using PortablePdbBuilder.

Convention auto-discovery: llms.txt and docs/llms.txt are automatically included with the llm-context role if present.

PDB Embedding Details

The embed task uses System.Reflection.Metadata and System.Reflection.Metadata.Ecma335 to:

• Read all 8 portable PDB debug tables (Document, MethodDebugInformation, LocalScope, LocalVariable, LocalConstant, ImportScope, StateMachineMethod, CustomDebugInformation)
• Copy them into a new MetadataBuilder
• Add/replace the SourceAnnotations CustomDebugInformation row
• Serialize with PortablePdbBuilder, preserving the original PDB ID and type system row counts

JSON Schema (v1)

{
  "version": 1,
  "annotations": [
    { "path": "SKILL.md", "role": "llm-context", "description": "..." },
    { "path": "src/Foo.cs" }
  ]
}

Fields role and description are omitted from JSON when empty.

Common Tasks

| Task | Command | |------|---------| | Build | dotnet build | | Test | dotnet test | | Pack | dotnet pack src/SourceAnnotations.Tasks |