feat: Source mapping and DWARF debug info support for C-to-assembly attribution

[CTalkobt]

Implement source line attribution and debug information infrastructure to enable seamless debugging across C and assembly code.

Core Features

Source Mapping Infrastructure

• Track which assembly instructions correspond to C source lines
• Maintain mapping through compilation pipeline:
  • cc45: C AST → IR with source location
  • Code generation: IR → assembly with line attribution
  • ca45: Assembly → object with embedded source info
  • ln45: Link objects while preserving source references
• Support for inlined functions (show original source line)
• Handle macro expansion attribution (point to macro definition)

DWARF Debug Format

• Emit DWARF 3+ debug information in .o45 objects
• Include sections:
  • .debug_info — Type and variable information
  • .debug_line — Line number program
  • .debug_loc — Location lists for variables
  • .debug_str — String table
• Support variable scoping and lifetime information
• Proper prologue/epilogue attribution

Line Number Programs

• Maintain accurate mapping of:
  • Assembly addresses → source file + line number
  • Source line → assembly address range
• Handle:
  • Instructions from different source files (linking)
  • Inlined functions (multiple source locations per instruction)
  • Macro-generated code (original vs expanded location)

Variable Location Information

• Track where C variables live during execution:
  • Register (A, X, Y, Z)
  • ZP address
  • Stack relative address
  • Memory address (for globals)
• Support variables that change location (spilled/restored)
• Handle composite types (struct members with individual locations)
• Lifetime information (when variable is in scope)

Compiler Changes

cc45 Modifications

• Extend AST nodes to carry source location (file, line, column)
• Maintain location through optimization passes
• Emit IR with precise location information
• Code generator produces assembly with location comments
• Annotate inlined function expansions with original location

Generated Assembly

• Include .loc directives for each instruction sequence:

  .loc 1 42 5         ; file 1, line 42, column 5
  lda #$20          
  sta value

• Support for:
  • File registration (.file "path/to/file.c")
  • Basic block tracking
  • Inlining/call site information
  • Conditional branches (mark jump targets)

Assembler Changes

ca45 Modifications

• Parse .loc directives and metadata
• Preserve location information in .o45 objects
• Track address ranges for each source line
• Build line number index for efficient lookup
• Support:
  • Multiple files in single object
  • Line range compression
  • Address range merging

Linker Changes

ln45 Modifications

• Merge DWARF info from multiple objects
• Adjust relocatable addresses in debug sections
• Build complete symbol table with types
• Resolve cross-object references
• Output unified DWARF in final executable (if supported by target)
• Maintain line number mapping across linking

Output Formats

Debug Info Emission

• .o45 objects contain debug sections alongside code/data
• Optional: embedded DWARF in final PRG (if format supports)
• Alternative: separate .dbg file with line/variable info
• Serialized format for LSP/debugger consumption:
  • JSON mapping of addresses to (file, line, column)
  • Variable location database
  • Symbol type information

Integration Points

1. LSP Server (feat: Language Server Protocol (LSP) implementation + VS Code extension #198) — Consume source mapping for:

   • Go-to-definition navigation
   • Hover type information
   • Inline error attribution

2. Debugger (feat: Emulator integration for mmemu debugger and build-and-run workflow #200) — Use line info for:

   • Breakpoint setting
   • Stack trace with source lines
   • Source-level stepping
   • Variable inspection

3. Object Inspector (feat: Object file inspector UI for .o45 relocatable object analysis #201) — Display:

   • Disassembly with source line attribution
   • Variable locations in memory
   • Inline function origins

4. Linter (feat: Custom linter with MEGA65-specific diagnostics #199) — Report:

   • Warnings with source file and line
   • Cross-reference to generated assembly

Testing Strategy

• Unit tests for location tracking through optimization passes
• Integration tests: C → assembly with source mapping verification
• Debugger tests: set breakpoint on source line, verify machine address
• Variable location tests: inspect variable at different program points
• Multi-file tests: linking preserves source info across objects

Complexity & Phases

Phase 1 — Basic line number mapping

• Simple .loc directive support
• Single-file programs only
• No variable location tracking

Phase 2 — Multi-file and optimization

• Cross-file merging at link time
• Preserve locations through optimization passes
• Inlining support

Phase 3 — Full variable tracking

• Location lists for spilled variables
• Struct member locations
• Full DWARF emission (optional)

Phase 4 — Performance & compression

• Address range compression
• Line number table optimization
• Incremental debug info (faster relinking)

[CTalkobt]

Related to #198 (LSP/IDE implementation)

Source mapping and DWARF debug info are deferred to Phase 4+ of the LSP implementation. Phase 1-3 focus on real-time diagnostics, hover, completion, and symbol navigation for both C and assembly.

Current phase:

• Phase 1: Diagnostic infrastructure ✅ (in progress)
  • Normalized error format in cc45/ca45
  • LSP diagnostic parsing from subprocess output
  • VS Code extension scaffolding complete

Phase 2-3: Static data providers and symbol indexing

Phase 4+: Debug info and source mapping (this issue) + debugger integration (#200)

The lightweight ctags-style symbol indexing in Phase 3 will provide a foundation for source mapping later.