ed/pikuma_ps1
1
0
Fork 0
mirror of https://github.com/Ed94/pikuma_ps1.git synced 2026-08-25 02:20:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

auto-column alignment formatting pass on trailing type annotations.

Browse Source
This commit is contained in:
ed
2026-08-19 23:48:46 -04:00
parent 2a087f735e
commit de13bc3ce9
16 changed files with 1035 additions and 1181 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/passes/annotation.lua
+16 -16
View File
@@ -11,7 +11,7 @@
-- Bootstrap follows the entry scripts; `scripts/duffle_paths.lua` sets package.path and package.cpath. See `ps1_meta.lua` for the rationale.
-- `debug.getinfo(1, "S").source` locates this file for standalone and orchestrated runs, then `duffle_paths.lua` returns the loaded `duffle` module.
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
-- The annotation pass reads the source-derived registries from scan_source:
-- * pipe_ctx.register_alias_registry — for atom_dbg_reg_default(R_X, ...) and atom_reg_types(R_X, ...) member-identity checks
@@ -140,7 +140,7 @@ end
--- @return nil
local function check_macro_word_drift(m, pipe_ctx, findings)
local wc = (pipe_ctx and pipe_ctx.word_counts) or {} ---@type WordCounts
local declared = wc[m.name] ---@type integer|nil
local declared = wc[m.name] ---@type integer|nil
if not declared then
findings.errors[#findings.errors + 1] = {
line = m.line,
@@ -169,7 +169,7 @@ end
--- @return nil
local function check_semantic_reg_defaults(_src, pipe_ctx, findings)
-- Detect duplicate defaults using the ordered occurrence list (the out.types hash only retains the last declaration).
local seen_first_line = {} ---@type table<string, integer> -- bag: register ident -> first source line
local seen_first_line = {} ---@type table<string, integer> -- bag: register ident -> first source line
for _, occ in ipairs(pipe_ctx.type_occurrences or {}) do ---@type integer, RegTypeOccurrence
if seen_first_line[occ.reg] == nil then
seen_first_line[occ.reg] = occ.source_line
@@ -184,7 +184,7 @@ local function check_semantic_reg_defaults(_src, pipe_ctx, findings)
end
local reg_registry = pipe_ctx.register_alias_registry or {} ---@type table<string, AliasEntry>
local type_registry = pipe_ctx.type_name_registry or {} ---@type table<string, TypeNameEntry>
for reg, def in pairs(pipe_ctx.types or {}) do ---@type string, RegTypeDefault
for reg, def in pairs(pipe_ctx.types or {}) do ---@type string, RegTypeDefault
if not reg_registry[reg] then
findings.errors[#findings.errors + 1] = {
line = def.source_line,
@@ -221,7 +221,7 @@ end
local function check_atom_reg_types(_src, pipe_ctx, findings)
local reg_registry = pipe_ctx.register_alias_registry or {} ---@type table<string, AliasEntry>
local type_registry = pipe_ctx.type_name_registry or {} ---@type table<string, TypeNameEntry>
for _, ai in ipairs(pipe_ctx.atom_infos_list or {}) do ---@type integer, AtomInfoEntry
for _, ai in ipairs(pipe_ctx.atom_infos_list or {}) do ---@type integer, AtomInfoEntry
if ai.reg_type_overrides then
for reg, ov in pairs(ai.reg_type_overrides) do ---@type string, RegTypeOverride
if not reg_registry[reg] then
@@ -282,7 +282,7 @@ end
--- @return nil
local function check_binds_no_duplicate_fields(_src, pipe_ctx, findings)
for _, bs in ipairs(pipe_ctx.binds_list or {}) do ---@type integer, BindsEntry
local seen = {} ---@type table<string, integer> -- bag: field name -> occurrence count
local seen = {} ---@type table<string, integer> -- bag: field name -> occurrence count
for _, f in ipairs(bs.fields or {}) do ---@type integer, TypeField
seen[f.name] = (seen[f.name] or 0) + 1
end
@@ -375,7 +375,7 @@ local function check_wave_context_migration(_src, pipe_ctx, findings)
if not (pipe_ctx.types and next(pipe_ctx.types)) then return end
if not (pipe_ctx.atom_infos_list) then return end
local reg_registry = pipe_ctx.register_alias_registry or {} ---@type table<string, AliasEntry>
for _, ai in ipairs(pipe_ctx.atom_infos_list) do ---@type integer, AtomInfoEntry
for _, ai in ipairs(pipe_ctx.atom_infos_list) do ---@type integer, AtomInfoEntry
if ai.reg_type_overrides then
for reg, _ in pairs(ai.reg_type_overrides) do ---@type string, RegTypeOverride
if not reg_registry[reg] then
@@ -428,8 +428,8 @@ local CHECK_RULES = { ---@type CheckRule[]
--- @return PipeCtx
local function build_corpus_pipe_ctx(ctx)
local view = duffle.corpus_view(ctx) ---@type PipeCtx
local annot_counts = {} ---@type table<string, integer> -- bag: atom name -> annotation count
for _, info in ipairs(view.atom_infos) do ---@type integer, AtomInfoEntry
local annot_counts = {} ---@type table<string, integer> -- bag: atom name -> annotation count
for _, info in ipairs(view.atom_infos) do ---@type integer, AtomInfoEntry
if info and info.atom_name then
annot_counts[info.atom_name] = (annot_counts[info.atom_name] or 0) + 1
end
@@ -467,7 +467,7 @@ local function validate(ctx, src, corpus_pipe_ctx)
register_alias_registry = corpus_pipe_ctx.register_alias_registry,
type_name_registry = corpus_pipe_ctx.type_name_registry,
}
local atoms = {} ---@type AtomEntry[]
local atoms = {} ---@type AtomEntry[]
for _, a in ipairs(scan.atoms) do ---@type integer, AtomEntry
if a.kind == "atom" or a.kind == "atom_proc" then
atoms[#atoms + 1] = a
@@ -503,7 +503,7 @@ local function validate(ctx, src, corpus_pipe_ctx)
-- scan_source records each marker in scan.debug_skip_markers; this loop validates each record independently and emits at most one error per marker.
-- Valid markers stamp `debug_skip = true` on the following atom or component declaration, which downstream consumers read directly.
local skip_markers = scan.debug_skip_markers or {} ---@type DebugSkipMarker[]
for _, marker in ipairs(skip_markers) do ---@type integer, DebugSkipMarker
for _, marker in ipairs(skip_markers) do ---@type integer, DebugSkipMarker
duffle.run_check_rules(CHECK_RULES, "per_skip_marker", marker, pipe_ctx, findings)
end
@@ -554,17 +554,17 @@ function M.run(ctx)
-- Build the shared pipe_ctx once for this run; every validate() call sees the same cross-source registries.
-- The corpus owns the canonical cross-source registries; per-source scans retain body / declaration ownership.
local corpus_pipe_ctx = build_corpus_pipe_ctx(ctx) ---@type PipeCtx
local corpus = ctx.shared.corpus ---@type Corpus
local corpus = ctx.shared.corpus ---@type Corpus
-- Group `corpus.sources_by_dir` by module, validate every source in each bucket, and emit one errors.h per directory.
local by_dir = (corpus and corpus.sources_by_dir) or {} ---@type table<string, SourceFile[]>
for dir, dir_sources in pairs(by_dir) do ---@type string, SourceFile[]
local dir_basename = dir:match("([^/\\]+)$") or dir ---@type string
local dir_atoms = 0 ---@type integer
local dir_errors = {} ---@type PassFinding[]
local dir_warnings = {} ---@type PassFinding[]
for _, src in ipairs(dir_sources) do ---@type integer, SourceFile
local dir_atoms = 0 ---@type integer
local dir_errors = {} ---@type PassFinding[]
local dir_warnings = {} ---@type PassFinding[]
for _, src in ipairs(dir_sources) do ---@type integer, SourceFile
local result = validate(ctx, src, corpus_pipe_ctx) ---@type AnnotatedResult
result.source = src.path -- tag for downstream rendering
dir_atoms = dir_atoms + #result.atoms
scripts/passes/atoms_source_map.lua
+21 -21
View File
@@ -38,8 +38,8 @@
-- (works both standalone + when require'd). `duffle_paths.lua` sets package.path then returns `require("duffle")`
-- at the bottom, so the dofile value IS the duffle module.
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local elf_dwarf = require("elf_dwarf") ---@type ElfDwarfMod
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local elf_dwarf = require("elf_dwarf") ---@type ElfDwarfMod
-- ════════════════════════════════════════════════════════════════════════════
-- Constants
@@ -103,14 +103,14 @@ local FORMAT_VERSION = 1 ---@type integer
--- @return WordMapEntry[]
--- @return integer
local function canonical_word_entries(atom)
local paths = atom.paths or {} ---@type AtomPaths
local events = paths.word_events or {} ---@type WordEvent[]
local word_items = {} ---@type EmissionItem[]
local paths = atom.paths or {} ---@type AtomPaths
local events = paths.word_events or {} ---@type WordEvent[]
local word_items = {} ---@type EmissionItem[]
for _, item in ipairs(paths.items or {}) do ---@type integer, EmissionItem
if item.kind == "word" then word_items[#word_items + 1] = item end
end
local entries = {} ---@type WordMapEntry[]
local entries = {} ---@type WordMapEntry[]
for index, event in ipairs(events) do ---@type integer, WordEvent
local item = word_items[index] or {} ---@type EmissionItem
entries[#entries + 1] = {
@@ -138,13 +138,13 @@ end
--- @return string[]
--- @return integer
local function emit_provenance_stanza(src, atom, wc)
local lines = {} ---@type string[]
local rel_path = src.path:gsub("\\\\", "/") ---@type string
local lines = {} ---@type string[]
local rel_path = src.path:gsub("\\\\", "/") ---@type string
local entries, total = canonical_word_entries(atom) ---@type WordMapEntry[], integer
lines[#lines + 1] = string.format('ATOM %s "%s" 0', atom.raw_name or atom.name, rel_path)
for _, entry in ipairs(entries) do ---@type integer, WordMapEntry
local inv = entry.invocation ---@type InvocationRecord|nil
local inv = entry.invocation ---@type InvocationRecord|nil
local macro_count = inv and wc["mac_" .. inv.component_name] ---@type integer|nil
if inv and macro_count ~= nil then
lines[#lines + 1] = string.format('WORD %d CALL %s:%d MACRO %s "%s:%d" BODY %d'
@@ -177,7 +177,7 @@ local function render_provenance(src, wc)
--- @param atom AtomEntry
--- @return nil
local function append(atom)
local stanza = emit_provenance_stanza(src, atom, wc) ---@type string[]
local stanza = emit_provenance_stanza(src, atom, wc) ---@type string[]
for _, line in ipairs(stanza) do lines[#lines + 1] = line end ---@type integer, string
end
for _, atom in ipairs(src.scan.atoms or {}) do ---@type integer, AtomEntry
@@ -197,8 +197,8 @@ end
--- @return string[]
--- @return integer
local function emit_atom_stanza(src, atom)
local lines = {} ---@type string[]
local rel_path = src.path:gsub("\\\\", "/") ---@type string
local lines = {} ---@type string[]
local rel_path = src.path:gsub("\\\\", "/") ---@type string
local entries, total = canonical_word_entries(atom) ---@type WordMapEntry[], integer
lines[#lines + 1] = string.format('ATOM %s "%s" 0', atom.raw_name or atom.name, rel_path)
@@ -223,7 +223,7 @@ local function render_source_map(src)
--- @param atom AtomEntry
--- @return nil
local function append(atom)
local stanza = emit_atom_stanza(src, atom) ---@type string[]
local stanza = emit_atom_stanza(src, atom) ---@type string[]
for _, line in ipairs(stanza) do lines[#lines + 1] = line end ---@type integer, string
end
for _, atom in ipairs(src.scan.atoms or {}) do ---@type integer, AtomEntry
@@ -253,8 +253,8 @@ end
--- @return GdbAtomRecord[]
local function build_atom_table(ctx)
local addrs = elf_dwarf.read_nm(ctx.flags.elf_path) ---@type table<string, NmAddr>
local corpus = ctx.shared and ctx.shared.corpus ---@type Corpus|nil
local matched = {} ---@type GdbAtomRecord[]
local corpus = ctx.shared and ctx.shared.corpus ---@type Corpus|nil
local matched = {} ---@type GdbAtomRecord[]
for _, src in ipairs(corpus.source_order or {}) do ---@type integer, SourceFile
local file_base = src.path:match("([^/\\\\]+)$") or src.path ---@type string
@@ -263,7 +263,7 @@ local function build_atom_table(ctx)
local function append(atom)
if not atom.paths then return end
local name = atom.raw_name or atom.name ---@type string
local info = addrs[name] ---@type NmAddr|nil
local info = addrs[name] ---@type NmAddr|nil
if not info then return end
local entries, total = canonical_word_entries(atom) ---@type WordMapEntry[], integer
matched[#matched + 1] = {
@@ -276,7 +276,7 @@ local function build_atom_table(ctx)
entries = entries,
}
end
for _, atom in ipairs((src.scan or {}).atoms or {}) do append(atom) end ---@type integer, AtomEntry
for _, atom in ipairs((src.scan or {}).atoms or {}) do append(atom) end ---@type integer, AtomEntry
for _, atom in ipairs((src.scan or {}).raw_atoms or {}) do append(atom) end ---@type integer, AtomEntry
end
@@ -537,12 +537,12 @@ function M.render_atom_source_map(atom)
assert(type(atom) == "table", "render_atom_source_map: atom must be a table")
assert(type(atom.paths) == "table", "render_atom_source_map: atom.paths must be a table")
local entries, total = canonical_word_entries(atom) ---@type WordMapEntry[], integer
local lines = {} ---@type string[]
local lines = {} ---@type string[]
lines[#lines + 1] = string.format("ATOM %s %d", (atom.raw_name or atom.name), total)
for _, entry in ipairs(entries) do ---@type integer, WordMapEntry
local word_line = string.format("WORD %d LINE %d TEXT %s", ---@type string
entry.pos, entry.line, entry.text)
local keys = {} ---@type string[]
local keys = {} ---@type string[]
for pos = 1, 16 do ---@type integer
local k = entry.gpr_keys and entry.gpr_keys[pos] ---@type string|nil
if type(k) == "string" and k:sub(1, 7) == "reguse:" then
@@ -571,10 +571,10 @@ function M.render_atom_provenance(atom, wc, rel_path)
assert(type(atom.paths) == "table", "render_atom_provenance: atom.paths must be a table")
assert(type(rel_path) == "string", "render_atom_provenance: rel_path must be a string")
local entries, total = canonical_word_entries(atom) ---@type WordMapEntry[], integer
local lines = {} ---@type string[]
local lines = {} ---@type string[]
lines[#lines + 1] = string.format("ATOM %s %d", (atom.raw_name or atom.name), total)
for _, entry in ipairs(entries) do ---@type integer, WordMapEntry
local inv = entry.invocation ---@type InvocationRecord|nil
local inv = entry.invocation ---@type InvocationRecord|nil
local macro_count = inv and wc and wc["mac_" .. inv.component_name] ---@type integer|nil
if inv and macro_count ~= nil then
lines[#lines + 1] = string.format('WORD %d CALL %s:%d MACRO %s "%s:%d" BODY %d'
scripts/passes/auto_reg.lua
+21 -21
View File
@@ -36,7 +36,7 @@
--- @field POOL GprIdent[]
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
--- ════════════════════════════════════════════════════════════════════════════
--- THE GPR ALLOCATION POOL — what's allocatable, and (more importantly) WHY
@@ -83,7 +83,7 @@ local INT_CODE_TO_POOL_GPR = { ---@type table<integer, GprIdent> -- bag: MIPS G
--- @param tbl table<string, string> -- bag: key set only; values unused
--- @return string[]
local function stable_sort_keys(tbl)
local keys = {} ---@type string[]
local keys = {} ---@type string[]
for k in pairs(tbl) do keys[#keys + 1] = k end ---@type string
table.sort(keys)
return keys
@@ -99,10 +99,10 @@ local function allocate_phase(phase_label, decls)
-- Deep-copy POOL into a fresh sequence table. The original `table.unpack and table.unpack(POOL) or { unpack(POOL) }`
-- idiom wraps the unpacked values in a single inner table under LuaJIT 5.1 (`table.unpack` is nil; the `or` returns one value),
-- which corrupts the pool into `{ {R_T0, R_T1, ...} }` — making `table.remove(pool, 1)` return the inner table on iteration.
local pool = {} ---@type GprIdent[]
for i = 1, #POOL do pool[i] = POOL[i] end ---@type integer
local result = {} ---@type GprAllocMap
local errors = {} ---@type PassFinding[]
local pool = {} ---@type GprIdent[]
for i = 1, #POOL do pool[i] = POOL[i] end ---@type integer
local result = {} ---@type GprAllocMap
local errors = {} ---@type PassFinding[]
for _, sym in ipairs(stable_sort_keys(decls)) do ---@type integer, string
local next_gpr = table.remove(pool, 1) ---@type GprIdent|nil
if not next_gpr then
@@ -166,13 +166,13 @@ local function find_used_gprs(body_text, alias_to_gpr)
-- (b) Alias references (R_<Alias>) resolved to physical GPRs via the registry.
-- Sorted by name so the regex is byte-stable across runs.
if alias_to_gpr and next(alias_to_gpr) then
local aliases = {} ---@type string[]
local aliases = {} ---@type string[]
for alias_name in pairs(alias_to_gpr) do ---@type string
aliases[#aliases + 1] = alias_name
end
table.sort(aliases)
local pattern = "(" .. table.concat(aliases, "|") .. ")" ---@type string
for alias_name in body_text:gmatch(pattern) do ---@type string
for alias_name in body_text:gmatch(pattern) do ---@type string
local gpr = alias_to_gpr[alias_name] ---@type GprIdent|nil
if gpr and not found[gpr] then
found[gpr] = 1
@@ -206,7 +206,7 @@ local function emit_auto_reg_h(out_dir, dir, sources, mappings)
lines[#lines + 1] = "// R_<Sym>_Code = <chosen GPR's _Code constant> for every marker in this directory."
lines[#lines + 1] = ""
for _, sym in ipairs(stable_sort_keys(mappings)) do ---@type integer, string
local gpr = mappings[sym] ---@type GprIdent
local gpr = mappings[sym] ---@type GprIdent
local gpr_code = gpr .. "_Code" ---@type string
lines[#lines + 1] = "#define " .. sym .. "_Code " .. gpr_code
end
@@ -242,10 +242,10 @@ function M.run(ctx)
local user_pinned, alias_to_gpr = build_user_pins(corpus) ---@type table<GprIdent, boolean>, table<string, GprIdent>
-- 1. Allocate phase pools first (phase declarations take precedence over per-atom declarations).
local phase_allocations = {} ---@type table<string, GprAllocMap> -- bag: phase_label -> alloc map
local phase_allocations = {} ---@type table<string, GprAllocMap> -- bag: phase_label -> alloc map
for phase_label, decls in pairs(corpus.phase_auto_regs or {}) do ---@type string, table<string, string>
local mapping, errs = allocate_phase(phase_label, decls) ---@type GprAllocMap, PassFinding[]
for sym, gpr in pairs(mapping) do ---@type string, GprIdent
for sym, gpr in pairs(mapping) do ---@type string, GprIdent
phase_allocations[phase_label] = phase_allocations[phase_label] or {}
phase_allocations[phase_label][sym] = gpr
end
@@ -258,14 +258,14 @@ function M.run(ctx)
-- Otherwise, allocate a private pool for the atom.
-- The phase membership is in `corpus.atom_phases[phase_label].atoms` (an array of atom names declared via `atom_phase(<phase>)`
-- in the atom's `atom_info` line). Build a reverse map `atom_name -> phase_label` so the lookup is O(1) per atom scope.
local atom_name_to_phase = {} ---@type table<AtomName, string> -- bag: atom name -> phase label
local atom_name_to_phase = {} ---@type table<AtomName, string> -- bag: atom name -> phase label
for phase_label, entry in pairs(corpus.atom_phases or {}) do ---@type string, AtomPhaseGroup
for _, atom_name in ipairs(entry.atoms or {}) do ---@type integer, AtomName
atom_name_to_phase[atom_name] = phase_label
end
end
local atom_allocations = {} ---@type table<AtomName, GprAllocMap> -- bag: atom scope -> alloc map
local atom_allocations = {} ---@type table<AtomName, GprAllocMap> -- bag: atom scope -> alloc map
for atom_scope, decls in pairs(corpus.atom_auto_regs or {}) do ---@type AtomName, table<string, string>
local phase_label = atom_name_to_phase[atom_scope] ---@type string|nil
-- Build the atom's source pool: start with the full POOL, subtract:
@@ -277,7 +277,7 @@ function M.run(ctx)
-- the original `source_pool = phase_allocations[phase_label]` form used the phase
-- allocation MAP as a pool, but that map has no array part, so `table.remove(source_pool, 1)`
-- returned nil and every atom-with-phase marker errored with `phase_register_pool_exhausted`.
local used = {} ---@type table<GprIdent, boolean> -- bag: committed or body-referenced GPR -> true
local used = {} ---@type table<GprIdent, boolean> -- bag: committed or body-referenced GPR -> true
for _, m in pairs(phase_allocations) do for _, gpr in pairs(m) do used[gpr] = true end end ---@type integer, GprAllocMap
for _, m in pairs(atom_allocations) do for _, gpr in pairs(m) do used[gpr] = true end end ---@type integer, GprAllocMap
-- (c) Body references — scan the atom body for hardcoded + alias-resolved GPRs.
@@ -285,16 +285,16 @@ function M.run(ctx)
local atom = corpus.atoms_by_name and corpus.atoms_by_name[atom_scope] ---@type AtomEntry|nil
if atom and atom.body then
local body_used = find_used_gprs(atom.body, alias_to_gpr) ---@type table<GprIdent, integer>
for gpr in pairs(body_used) do used[gpr] = true end ---@type GprIdent
for gpr in pairs(body_used) do used[gpr] = true end ---@type GprIdent
end
local source_pool = {} ---@type GprIdent[]
local source_pool = {} ---@type GprIdent[]
for _, gpr in ipairs(POOL) do ---@type integer, GprIdent
-- Exclude (a) prior commitments, (b) USER-PINNED GPRs (wave-context carriers declared via atom_reg + _Code defs, preserved across atoms globally).
if not used[gpr] and not user_pinned[gpr] then
source_pool[#source_pool + 1] = gpr
end
end
local result = {} ---@type GprAllocMap
local result = {} ---@type GprAllocMap
for _, sym in ipairs(stable_sort_keys(decls)) do ---@type integer, string
local next_gpr = table.remove(source_pool, 1) ---@type GprIdent|nil
if not next_gpr then
@@ -322,7 +322,7 @@ function M.run(ctx)
local atom = corpus.atoms_by_name and corpus.atoms_by_name[atom_scope] ---@type AtomEntry|nil
if atom and atom.body then
local used_in_body = find_used_gprs(atom.body, alias_to_gpr) ---@type table<GprIdent, integer>
for sym, allocated_gpr in pairs(decls) do ---@type string, GprIdent
for sym, allocated_gpr in pairs(decls) do ---@type string, GprIdent
if used_in_body[allocated_gpr] and used_in_body[allocated_gpr] > 0 then
warnings[#warnings + 1] = {
line = atom.line or 0,
@@ -338,8 +338,8 @@ function M.run(ctx)
-- 4. Emit per-directory gen/auto_reg.h.
-- For each source directory that has atom_auto_regs or phase_auto_regs entries, emit one header.
local sources_by_dir = corpus.sources_by_dir or {} ---@type table<string, SourceFile[]>
for dir, sources in pairs(sources_by_dir) do ---@type string, SourceFile[]
local per_dir_mappings = {} ---@type GprAllocMap
for dir, sources in pairs(sources_by_dir) do ---@type string, SourceFile[]
local per_dir_mappings = {} ---@type GprAllocMap
for _, src in ipairs(sources) do ---@type integer, SourceFile
-- Collect every (sym -> gpr) entry that originated from a source in this directory.
-- `src.scan.atom_auto_regs` is keyed by ATOM SCOPE NAME; `pairs(t)` iterates KEYS so `scope_name` here is the scope ident (e.g. "cube_g4_face").
@@ -356,7 +356,7 @@ function M.run(ctx)
end
end
end
local out_dir = dir .. "/gen" ---@type string
local out_dir = dir .. "/gen" ---@type string
local out_path = emit_auto_reg_h(out_dir, dir, sources, per_dir_mappings) ---@type string|nil
if out_path then outputs[#outputs + 1] = { auto_reg_h = out_path } end
end
scripts/passes/components.lua
+41 -41
View File
@@ -23,7 +23,7 @@
-- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when require'd).
-- duffle_paths.lua sets package.path then returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
-- ════════════════════════════════════════════════════════════════════════════
-- Constants
@@ -31,20 +31,20 @@ local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type
-- Atom component declaration identifiers.
local ATOM_COMP_PROC = "MipsAtomComp_Proc_" ---@type string
local MIPS_ATOM = "Slice_MipsCode" ---@type string -- prefix on the function declaration that wraps an AtomComp_Proc_
local MIPS_ATOM = "Slice_MipsCode" ---@type string -- prefix on the function declaration that wraps an AtomComp_Proc_
-- Component-name prefixes.
local AC_PREFIX = "ac_" ---@type string -- arg to MipsAtomComp_(ac_X); the X is the atom name
local AC_PREFIX_LEN = 3 ---@type integer
local AC_PREFIX_LEN = 3 ---@type integer
local MAC_PREFIX = "mac_" ---@type string -- prefix on generated macros; the rest is the atom name
local MAC_PREFIX_LEN = 4 ---@type integer
local MAC_PREFIX_LEN = 4 ---@type integer
-- ASCII byte values used in tokenization.
local BYTE_NEWLINE = 10 ---@type integer
local BYTE_SLASH = 47 ---@type integer
-- Output gen subdirectory + filename (per-directory aggregation; the directory name is the namespace).
local GEN_SUBDIR = "gen" ---@type string
local GEN_SUBDIR = "gen" ---@type string
local MACS_FILENAME = "macs.h" ---@type string
-- ════════════════════════════════════════════════════════════════════════════
@@ -126,9 +126,9 @@ end
--- @return string[]|nil
local function extract_arg_names(args_str)
if not args_str or args_str == "" then return nil end
local names = {} ---@type string[]
local names = {} ---@type string[]
local tokens = duffle.split_top_level_commas(args_str) ---@type string[]
for _, tok in ipairs(tokens) do ---@type integer, string
for _, tok in ipairs(tokens) do ---@type integer, string
local trimmed = duffle.trim(tok) ---@type string
if trimmed ~= "" then
-- Strip trailing block comment (/* ... */) from the token, if present.
@@ -151,7 +151,7 @@ local function extract_arg_names(args_str)
end
end
-- Now scan back from close_pos for the `/*` opener (slashes are at close_pos-1 and close_pos-2).
local opener_pos = nil ---@type integer|nil
local opener_pos = nil ---@type integer|nil
local scan = close_pos - 3 ---@type integer
while scan >= 1 do
if trimmed:sub(scan, scan + 1) == "/*" then
@@ -240,7 +240,7 @@ end
--- @param scan SourceScan
--- @return Component[]
local function project_components(source, scan)
local out = {} ---@type Component[]
local out = {} ---@type Component[]
for _, a in ipairs(scan.atoms) do ---@type integer, AtomEntry
-- Only `MipsAtomComp_(ac_X)` (kind="comp_bare") and `MipsAtomComp_Proc_(ac_X, ...)` (kind="comp_proc")
-- are COMPONENTS — they get inlined via `mac_<name>` aliases inside atom bodies.
@@ -286,8 +286,8 @@ end
--- @param s string
--- @return string
local function convert_line_comments_to_block(s)
local result = s ---@type string
local pos = 1 ---@type integer
local result = s ---@type string
local pos = 1 ---@type integer
local len = #result ---@type integer
while pos <= len do
local is_double_slash = result:byte(pos) == BYTE_SLASH ---@type boolean
@@ -300,9 +300,9 @@ local function convert_line_comments_to_block(s)
while eol <= len and result:byte(eol) ~= BYTE_NEWLINE do
eol = eol + 1
end
local before = result:sub(1, pos - 1) ---@type string
local comment = result:sub(pos + 2, eol - 1) ---@type string -- skip the `//`
local after ---@type string
local before = result:sub(1, pos - 1) ---@type string
local comment = result:sub(pos + 2, eol - 1) ---@type string -- skip the `//`
local after ---@type string
if eol <= len and result:byte(eol) == BYTE_NEWLINE then
after = " */" .. result:sub(eol) -- keep the newline
else
@@ -361,7 +361,7 @@ local function word_count_rec(name, comp_by_name, wc, cache)
if cache[name] ~= nil then return cache[name] end
cache[name] = -1 -- mark in-progress (cycle detection)
local cc = comp_by_name[name] ---@type Component|nil
local n ---@type integer
local n ---@type integer
if cc then
n = 0
local tokens = cc.body_tokens ---@type BodyToken[]
@@ -412,11 +412,11 @@ end
--- @param wc WordCounts
--- @return table<string, integer> -- bag: bare component name -> word count
local function count_all_components(components, wc)
local comp_by_name = {} ---@type table<string, Component>
local comp_by_name = {} ---@type table<string, Component>
for _, cc in ipairs(components) do comp_by_name[cc.name] = cc end ---@type integer, Component
local cache = {} ---@type table<string, integer> -- bag: memo; -1 in-progress sentinel
local counts = {} ---@type table<string, integer> -- bag: bare name -> word count
for _, c in ipairs(components) do ---@type integer, Component
local cache = {} ---@type table<string, integer> -- bag: memo; -1 in-progress sentinel
local counts = {} ---@type table<string, integer> -- bag: bare name -> word count
for _, c in ipairs(components) do ---@type integer, Component
counts[c.name] = word_count_rec(c.name, comp_by_name, wc, cache)
end
return counts
@@ -446,10 +446,10 @@ local function component_meta_rec(name, comp_by_name, latency, cache)
if cache[name] ~= nil then return cache[name] end
cache[name] = { cycle_cost = -1, gp0_contrib = -1 }
local cc = comp_by_name[name] ---@type Component|nil
local cycle_cost ---@type integer
local gp0_contrib ---@type integer
local cycle_cost ---@type integer
local gp0_contrib ---@type integer
if cc then
local skip_cycle = (name == "yield") ---@type boolean
local skip_cycle = (name == "yield") ---@type boolean
local skip_gp0 = name:match("^insert_ot_tag") ~= nil ---@type boolean
cycle_cost = 0
gp0_contrib = 0
@@ -460,7 +460,7 @@ local function component_meta_rec(name, comp_by_name, latency, cache)
if trimmed ~= "" then
local ident = duffle.read_ident(trimmed, 1) ---@type string|nil
if ident and ident:sub(1, MAC_PREFIX_LEN) == MAC_PREFIX then
local nested = ident:sub(MAC_PREFIX_LEN + 1) ---@type string
local nested = ident:sub(MAC_PREFIX_LEN + 1) ---@type string
local nested_meta = component_meta_rec(nested, comp_by_name, latency, cache) ---@type ComponentMeta
if not skip_cycle then
cycle_cost = cycle_cost + nested_meta.cycle_cost
@@ -471,7 +471,7 @@ local function component_meta_rec(name, comp_by_name, latency, cache)
else
if not skip_cycle then
local isa = duffle.instr(ident) ---@type InstructionRow|nil
local gte = duffle.gte(ident) ---@type GteCommandRow|nil
local gte = duffle.gte(ident) ---@type GteCommandRow|nil
cycle_cost = cycle_cost + ((isa and isa.cycles) or (gte and gte.cycles) or latency[ident] or 1)
end
if not skip_gp0 then
@@ -506,11 +506,11 @@ end
--- @param latency table<string, integer> -- bag: ident -> cycle cost
--- @return ComponentMetaMap
local function compute_components_metadata(components, latency)
local comp_by_name = {} ---@type table<string, Component>
local comp_by_name = {} ---@type table<string, Component>
for _, cc in ipairs(components) do comp_by_name[cc.name] = cc end ---@type integer, Component
local cache = {} ---@type ComponentMetaMap
local out = {} ---@type ComponentMetaMap
for _, c in ipairs(components) do ---@type integer, Component
local cache = {} ---@type ComponentMetaMap
local out = {} ---@type ComponentMetaMap
for _, c in ipairs(components) do ---@type integer, Component
out[c.name] = component_meta_rec(c.name, comp_by_name, latency, cache)
end
return out
@@ -526,7 +526,7 @@ end
--- @return string[]
local function split_comment_lines(s)
local out = {} ---@type string[]
local pos = 1 ---@type integer
local pos = 1 ---@type integer
local s_len = #s ---@type integer
while pos <= s_len do
local nl = s:find("\n", pos, true) ---@type integer|nil
@@ -690,9 +690,9 @@ local function build_component_lines(c, counts)
end
end
local tokens = duffle.split_top_level_commas(c.body) ---@type string[]
local tokens = duffle.split_top_level_commas(c.body) ---@type string[]
for i = 1, #tokens do tokens[i] = duffle.trim(tokens[i]) end ---@type integer
local sig = signature_from_args(c.args) ---@type string
local sig = signature_from_args(c.args) ---@type string
-- Direct lookup against the per-source precomputed `counts` table (built once by count_all_components).
local n = counts[c.name] ---@type integer
@@ -718,7 +718,7 @@ end
--- @return string[]
local function header_boilerplate(dir, sources)
local source_lines = { "// Directory: " .. duffle.to_absolute_path(dir) .. "/" } ---@type string[]
for _, src in ipairs(sources) do ---@type integer, SourceFile
for _, src in ipairs(sources) do ---@type integer, SourceFile
source_lines[#source_lines + 1] = "// source: " .. duffle.to_absolute_path(src.path)
end
local source_blob = table.concat(source_lines, "\n") ---@type string
@@ -749,7 +749,7 @@ end
--- @return string -- Output directory
--- @return string -- Full output path
local function compute_macs_h_path(dir)
local out_dir = dir .. "/" .. GEN_SUBDIR ---@type string
local out_dir = dir .. "/" .. GEN_SUBDIR ---@type string
local out_path = out_dir .. "/" .. MACS_FILENAME ---@type string
return out_dir, out_path
end
@@ -764,7 +764,7 @@ end
--- @return string|nil -- Path to the written file (nil if no components)
local function emit_component_macros_h(ctx, dir, sources, components, counts)
if #components == 0 then return nil end
local out_dir, out_path = compute_macs_h_path(dir) ---@type string, string
local out_dir, out_path = compute_macs_h_path(dir) ---@type string, string
local lines = header_boilerplate(dir, sources) ---@type string[]
for _, c in ipairs(components) do ---@type integer, Component
@@ -791,7 +791,7 @@ end
--- @param counts table<string, integer> -- bag: bare component name -> word count
--- @return nil
local function update_canonical_word_counts(corpus, components, counts)
local wc = corpus.word_counts ---@type WordCounts
local wc = corpus.word_counts ---@type WordCounts
for _, c in ipairs(components) do ---@type integer, Component
local key = "mac_" .. c.name ---@type string
if wc[key] == nil then
@@ -821,7 +821,7 @@ end
--- @return nil
local function update_canonical_components(corpus, src, components, metadata)
local rel_path = src.path:gsub("\\", "/") ---@type string
for _, c in ipairs(components) do ---@type integer, Component
for _, c in ipairs(components) do ---@type integer, Component
-- Keyed by bare name (e.g. `yield`, `load_tri_indices`).
-- The atoms_source_map pass looks up components by bare name from the corpus;
-- `mac_` prefix lives at the call-site identifier and is stripped before lookup.
@@ -841,7 +841,7 @@ local function update_canonical_components(corpus, src, components, metadata)
-- Identical-shape declarations (same path + line) reuse the first-wins entry without a collision record.
local existing = corpus.components[c.name] ---@type ComponentDef
if existing.path ~= rel_path or existing.line ~= c.line then
local kind = c.kind or "comp_bare" ---@type string
local kind = c.kind or "comp_bare" ---@type string
local first_kind = existing.kind or "comp_bare" ---@type string
corpus.collisions[#corpus.collisions + 1] = {
kind = "component",
@@ -866,7 +866,7 @@ end
--- @return nil
local function update_canonical_component_body_index(corpus, src, components, scan)
local line_of = scan and scan.line_of ---@type (fun(pos: integer): integer)|nil
for _, c in ipairs(components) do ---@type integer, Component
for _, c in ipairs(components) do ---@type integer, Component
if corpus.component_body_index[c.name] == nil then
corpus.component_body_index[c.name] = {
body_tokens = c.body_tokens,
@@ -911,14 +911,14 @@ function M.run(ctx)
-- Per-directory aggregation: every source in the same directory contributes to one `gen/macs.h`.
-- The directory itself is the namespace. `corpus.sources_by_dir` preserves source-order within each bucket (matches `corpus.source_order`).
local sources_by_dir = corpus.sources_by_dir or duffle.group_sources_by_dir(corpus.source_order) ---@type table<string, SourceFile[]>
for dir, sources in pairs(sources_by_dir) do ---@type string, SourceFile[]
for dir, sources in pairs(sources_by_dir) do ---@type string, SourceFile[]
-- Aggregate components from every source in this directory.
-- `project_components` returns nil for sources with no `MipsAtomComp_` declarations; we skip those.
local aggregated_components = {} ---@type Component[]
local metadata_per_source = {} ---@type table<SourceFile, ComponentMetaMap>
for _, src in ipairs(sources) do ---@type integer, SourceFile
local per_source = project_components(src.text, src.scan) or {} ---@type Component[]
for _, c in ipairs(per_source) do ---@type integer, Component
for _, c in ipairs(per_source) do ---@type integer, Component
aggregated_components[#aggregated_components + 1] = c
end
if #per_source > 0 then
@@ -928,7 +928,7 @@ function M.run(ctx)
if #aggregated_components > 0 then
-- Compute word counts across the aggregated set. `corpus.word_counts` carries the
-- same-source + prior-directory entries so the recursive lookup sees both.
local counts = count_all_components(aggregated_components, corpus.word_counts) ---@type table<string, integer> -- bag: bare name -> word count
local counts = count_all_components(aggregated_components, corpus.word_counts) ---@type table<string, integer> -- bag: bare name -> word count
local macs_path = emit_component_macros_h(ctx, dir, sources, aggregated_components, counts) ---@type string|nil
if macs_path then
outputs[#outputs + 1] = { macs_h = macs_path }
scripts/passes/dwarf_injection.lua
+167 -167
View File
@@ -34,7 +34,7 @@
-- Load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when require'd).
-- Sets package.path + package.cpath then returns duffle.
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
-- ELF32 / DWARF / atoms-source-map utilities (post-link debug-info injection).
-- Sister module to duffle.lua — contains the format-constant tables (ELF32 byte offsets, DWARF opcodes, etc.) and the I/O helpers
@@ -55,27 +55,27 @@ local sleb128 = elf_dwarf.sleb128 ---@type fun(n: integer): string
-- All values lifted from `elf_dwarf.DWARF_LINE_OPS` + `elf_dwarf.DWARF5_RNGLISTS`.
-- Local aliases preserve the code's readability
-- (e.g. `DW_LNS_copy` reads better than `elf_dwarf.DWARF_LINE_OPS.DW_LNS_copy` in an emitter body).
local DWARF_LINE_OPS = elf_dwarf.DWARF_LINE_OPS ---@type DwarfLineOps
local DWARF5_RNGLISTS = elf_dwarf.DWARF5_RNGLISTS ---@type Dwarf5Rnglists
local DWARF_LINE_OPS = elf_dwarf.DWARF_LINE_OPS ---@type DwarfLineOps
local DWARF5_RNGLISTS = elf_dwarf.DWARF5_RNGLISTS ---@type Dwarf5Rnglists
local MIPS_BYTES_PER_WORD = elf_dwarf.MIPS_BYTES_PER_WORD ---@type integer
local DW_LNS_copy = DWARF_LINE_OPS.DW_LNS_copy ---@type integer
local DW_LNS_advance_pc = DWARF_LINE_OPS.DW_LNS_advance_pc ---@type integer
local DW_LNS_copy = DWARF_LINE_OPS.DW_LNS_copy ---@type integer
local DW_LNS_advance_pc = DWARF_LINE_OPS.DW_LNS_advance_pc ---@type integer
local DW_LNS_advance_line = DWARF_LINE_OPS.DW_LNS_advance_line ---@type integer
local DW_LNS_set_file = DWARF_LINE_OPS.DW_LNS_set_file ---@type integer
local DW_LNS_negate_stmt = DWARF_LINE_OPS.DW_LNS_negate_stmt ---@type integer
local DW_LNS_extended = DWARF_LINE_OPS.DW_LNS_extended ---@type integer
local DW_LNS_set_file = DWARF_LINE_OPS.DW_LNS_set_file ---@type integer
local DW_LNS_negate_stmt = DWARF_LINE_OPS.DW_LNS_negate_stmt ---@type integer
local DW_LNS_extended = DWARF_LINE_OPS.DW_LNS_extended ---@type integer
local DW_LNE_end_sequence = DWARF_LINE_OPS.DW_LNE_end_sequence ---@type integer
local DW_LNE_set_address = DWARF_LINE_OPS.DW_LNE_set_address ---@type integer
local DW_LNE_set_address = DWARF_LINE_OPS.DW_LNE_set_address ---@type integer
local DW_RLE_end_of_list = DWARF5_RNGLISTS.end_of_list ---@type integer
local DW_RLE_end_of_list = DWARF5_RNGLISTS.end_of_list ---@type integer
local DW_RLE_start_length = DWARF5_RNGLISTS.start_length ---@type integer
-- File-index lookup for the existing main line unit (Unit 2).
-- Populated at pass start by `init_file_index_lookup(elf_path)` from the runtime ELF (see `elf_dwarf.read_line_unit_file_table`).
local _file_index_by_basename = nil ---@type table<string, integer>|nil -- bag -- [basename] = 1-based line-table file index
local _file_path_by_index = nil ---@type table<integer, string>|nil -- bag -- [1-based index] = full source path (diagnostics / future consumers)
local _default_atom_source_index = nil ---@type integer -- any valid index used in opaque-row fallbacks
local _file_index_by_basename = nil ---@type table<string, integer>|nil -- bag -- [basename] = 1-based line-table file index
local _file_path_by_index = nil ---@type table<integer, string>|nil -- bag -- [1-based index] = full source path (diagnostics / future consumers)
local _default_atom_source_index = nil ---@type integer -- any valid index used in opaque-row fallbacks
-- RR_<R_Name> debug-visible variables come from the merged register_alias_registry filtered to aliases whose code is a valid MIPS GPR 0..31
-- (see collect_per_source_registries + by_alias in build_inserted_children).
@@ -86,16 +86,16 @@ local _default_atom_source_index = nil ---@type integer -- any valid index used
-- DW_OP_bregN would describe a memory location addressed from a register; the breg form would make gdb dereference the atom register value rather than display it.
-- New abbreviation codes (100+ to avoid collision with gcc's existing 1-60+ codes).
local ABBREV_CU = 0x64 ---@type integer -- 100: DW_TAG_compile_unit
local ABBREV_SUBPROGRAM = 0x65 ---@type integer -- 101: DW_TAG_subprogram
local ABBREV_VARIABLE = 0x66 ---@type integer -- 102: DW_TAG_variable with DW_AT_type = ref4 to U4
local ABBREV_STRUCT_TYPE = 0x67 ---@type integer -- 103: DW_TAG_structure_type with children (Binds_X mirror)
local ABBREV_MEMBER = 0x68 ---@type integer -- 104: DW_TAG_member no children (DW_AT_type = ref4 to U4 base)
local ABBREV_BIND_VAR = 0x69 ---@type integer -- 105: DW_TAG_variable no children + DW_AT_type = ref4 (the bind_args variable)
local ABBREV_BASE_TYPE = 0x6A ---@type integer -- 106: DW_TAG_base_type no children (U4)
local ABBREV_CU = 0x64 ---@type integer -- 100: DW_TAG_compile_unit
local ABBREV_SUBPROGRAM = 0x65 ---@type integer -- 101: DW_TAG_subprogram
local ABBREV_VARIABLE = 0x66 ---@type integer -- 102: DW_TAG_variable with DW_AT_type = ref4 to U4
local ABBREV_STRUCT_TYPE = 0x67 ---@type integer -- 103: DW_TAG_structure_type with children (Binds_X mirror)
local ABBREV_MEMBER = 0x68 ---@type integer -- 104: DW_TAG_member no children (DW_AT_type = ref4 to U4 base)
local ABBREV_BIND_VAR = 0x69 ---@type integer -- 105: DW_TAG_variable no children + DW_AT_type = ref4 (the bind_args variable)
local ABBREV_BASE_TYPE = 0x6A ---@type integer -- 106: DW_TAG_base_type no children (U4)
-- Component step-into (DW_TAG_inlined_subroutine + abstract DW_TAG_subprogram).
local ABBREV_ABSTRACT_SUBPROGRAM = 0x6B ---@type integer -- 107: DW_TAG_subprogram (abstract — no low_pc/high_pc); for each unique mac_X component
local ABBREV_INLINED_SUBROUTINE = 0x6C ---@type integer -- 108: DW_TAG_inlined_subroutine with children (per-component invocation range)
local ABBREV_ABSTRACT_SUBPROGRAM = 0x6B ---@type integer -- 107: DW_TAG_subprogram (abstract — no low_pc/high_pc); for each unique mac_X component
local ABBREV_INLINED_SUBROUTINE = 0x6C ---@type integer -- 108: DW_TAG_inlined_subroutine with children (per-component invocation range)
-- Bind_args uses DW_FORM_sec_offset → .debug_loclists for PC-ranged liveness
-- (each field transitions from tape memory to GPR at load_pc + 8 = MIPS I load-delay slot boundary).
local ABBREV_BIND_VAR_LOCLIST = 0x6D ---@type integer -- 109: DW_TAG_variable no children + DW_AT_type = ref4 + DW_AT_location = sec_offset
@@ -213,26 +213,26 @@ local DW_TAG_pointer_type = 0x0F ---@type integer
-- Component step-into.
local DW_TAG_inlined_subroutine = 0x1D ---@type integer
local DW_AT_name = 0x03 ---@type integer
local DW_AT_low_pc = 0x11 ---@type integer
local DW_AT_high_pc = 0x12 ---@type integer
local DW_AT_language = 0x13 ---@type integer
local DW_AT_location = 0x02 ---@type integer
local DW_AT_comp_dir = 0x1B ---@type integer
local DW_AT_byte_size = 0x0B ---@type integer
local DW_AT_encoding = 0x3E ---@type integer -- DWARF5 §7.7.1: DW_AT_encoding for the DW_ATE_unsigned base type
local DW_AT_name = 0x03 ---@type integer
local DW_AT_low_pc = 0x11 ---@type integer
local DW_AT_high_pc = 0x12 ---@type integer
local DW_AT_language = 0x13 ---@type integer
local DW_AT_location = 0x02 ---@type integer
local DW_AT_comp_dir = 0x1B ---@type integer
local DW_AT_byte_size = 0x0B ---@type integer
local DW_AT_encoding = 0x3E ---@type integer -- DWARF5 §7.7.1: DW_AT_encoding for the DW_ATE_unsigned base type
local DW_AT_data_member_location = 0x38 ---@type integer
local DW_AT_type = 0x49 ---@type integer
local DW_AT_linkage_name = 0x6E ---@type integer -- DWARF5 §7.7.1: DW_AT_linkage_name with DW_FORM_string
local DW_AT_external = 0x3F ---@type integer -- marks a variable/function as externally visible
local DW_AT_type = 0x49 ---@type integer
local DW_AT_linkage_name = 0x6E ---@type integer -- DWARF5 §7.7.1: DW_AT_linkage_name with DW_FORM_string
local DW_AT_external = 0x3F ---@type integer -- marks a variable/function as externally visible
-- Inlined_subroutine + abstract_origin attributes.
local DW_AT_abstract_origin = 0x31 ---@type integer
local DW_AT_call_file = 0x58 ---@type integer
local DW_AT_call_line = 0x59 ---@type integer
local DW_AT_inline = 0x20 ---@type integer -- DWARF5 §7.7.1: DW_AT_inline (used by abstract subprogram for the mac_X() components)
local DW_AT_inline = 0x20 ---@type integer -- DWARF5 §7.7.1: DW_AT_inline (used by abstract subprogram for the mac_X() components)
-- decl_file + decl_line on the abstract subprogram so consumers can resolve an abstract origin back to its definition site even when no inlined_subroutine instance currently maps to it.
local DW_AT_decl_file = 0x3A ---@type integer -- DWARF5 §7.7.1: DW_AT_decl_file (1-based file index into the CU's file table)
local DW_AT_decl_line = 0x3B ---@type integer -- DWARF5 §7.7.1: DW_AT_decl_line
local DW_AT_decl_file = 0x3A ---@type integer -- DWARF5 §7.7.1: DW_AT_decl_file (1-based file index into the CU's file table)
local DW_AT_decl_line = 0x3B ---@type integer -- DWARF5 §7.7.1: DW_AT_decl_line
-- Replaced the hardcoded `ATOM_SOURCE_FILE_INDEX = 11` and the `PROVENANCE_BASENAME_TO_FILE_INDEX` table below with a runtime lookup
-- (`init_file_index_lookup` + `resolve_provenance_file_index`) that reads the actual `.debug_line` file table from the post-link ELF.
@@ -284,7 +284,7 @@ local function resolve_provenance_file_index(path)
local normalized = path:gsub("\\", "/") ---@type string
-- Take the last path component (the basename).
local basename = normalized:match("([^/]+)$") or normalized ---@type string
local idx = _file_index_by_basename[basename] ---@type integer|nil
local idx = _file_index_by_basename[basename] ---@type integer|nil
if idx ~= nil then return idx end
-- Last-resort exact-path match (handles paths that don't reduce to a known basename).
for i, p in pairs(_file_path_by_index) do ---@type integer, string
@@ -299,13 +299,13 @@ end
local DW_FORM_addr = 0x01 ---@type integer
local DW_FORM_data1 = 0x0B ---@type integer
local DW_FORM_string = 0x08 ---@type integer -- inline null-terminated
local DW_FORM_strp = 0x0E ---@type integer -- 4-byte offset into .debug_str
local DW_FORM_exprloc = 0x18 ---@type integer -- length-prefixed (ULEB128) DW_OP bytes
local DW_FORM_ref4 = 0x13 ---@type integer -- 4-byte offset within the same .debug_info CU
local DW_FORM_udata = 0x0F ---@type integer -- ULEB128 (DW_AT_byte_size for struct_type, DW_AT_data_member_location for member)
local DW_FORM_implicit_const = 0x21 ---@type integer -- DWARF5 §7.5.6: abbrev declaration carries a SLEB constant (used by the abbrev-table walker)
local DW_FORM_sec_offset = 0x17 ---@type integer -- 4-byte section-relative offset (into .debug_loclists / .debug_rnglists)
local DW_FORM_string = 0x08 ---@type integer -- inline null-terminated
local DW_FORM_strp = 0x0E ---@type integer -- 4-byte offset into .debug_str
local DW_FORM_exprloc = 0x18 ---@type integer -- length-prefixed (ULEB128) DW_OP bytes
local DW_FORM_ref4 = 0x13 ---@type integer -- 4-byte offset within the same .debug_info CU
local DW_FORM_udata = 0x0F ---@type integer -- ULEB128 (DW_AT_byte_size for struct_type, DW_AT_data_member_location for member)
local DW_FORM_implicit_const = 0x21 ---@type integer -- DWARF5 §7.5.6: abbrev declaration carries a SLEB constant (used by the abbrev-table walker)
local DW_FORM_sec_offset = 0x17 ---@type integer -- 4-byte section-relative offset (into .debug_loclists / .debug_rnglists)
-- DW_OP_reg0 + DW_OP_piece are declared above (lines 114-116) alongside the other DWARF5 §7.7.3 loclist opcodes.
@@ -337,26 +337,26 @@ local function build_debug_loclists_section(atom_table, registries)
-- When absent we emit just the section terminator (a single DW_LLE_end_of_list byte); the .debug_loclists section stays non-empty so the linker accepts it,
-- and `bind_args` will be emitted with no loclist PC range (readelf will display it as having no .debug_loclists entries).
local tape_alias_entry = registries.register_alias_registry and registries.register_alias_registry["R_TapePtr"] ---@type AliasEntry|nil
local tape_reg = tape_alias_entry and tape_alias_entry.code ---@type integer
local parts = {} ---@type string[]
for _, atom in ipairs(atom_table) do ---@type integer, DwarfAtom
local tape_reg = tape_alias_entry and tape_alias_entry.code ---@type integer
local parts = {} ---@type string[]
for _, atom in ipairs(atom_table) do ---@type integer, DwarfAtom
if atom.rbind and tape_reg then
local fields = atom.rbind.fields or {} ---@type TypeField[]
local regs = atom.rbind.regs or {} ---@type DwarfLoadPair[]
local n_fields = #fields ---@type integer
local fields = atom.rbind.fields or {} ---@type TypeField[]
local regs = atom.rbind.regs or {} ---@type DwarfLoadPair[]
local n_fields = #fields ---@type integer
local last_load_pc = atom.addr + (n_fields - 1) * MIPS_BYTES_PER_WORD ---@type integer
local transition_pc = last_load_pc + MIPS_LOAD_DELAY_BYTES ---@type integer
local tape_pieces = {} ---@type string[]
for _, f in ipairs(fields) do ---@type integer, TypeField
local offset = f.offset or 0 ---@type integer
local transition_pc = last_load_pc + MIPS_LOAD_DELAY_BYTES ---@type integer
local tape_pieces = {} ---@type string[]
for _, f in ipairs(fields) do ---@type integer, TypeField
local offset = f.offset or 0 ---@type integer
local offset_sleb = elf_dwarf.sleb128(offset) ---@type string
-- (DW_OP_bregN, SLEB128(offset), DW_OP_piece, ULEB128(U4_BYTE_SIZE))
-- 4 = U4_BYTE_SIZE: each piece is sizeof(uint32_t) on MIPS32.
table.insert(tape_pieces, string.char(DW_OP_breg0 + tape_reg) .. offset_sleb .. string.char(DW_OP_piece) .. uleb128(U4_BYTE_SIZE))
end
local tape_expr = table.concat(tape_pieces) ---@type string
local gpr_pieces = {} ---@type string[]
for _, pair in ipairs(regs) do ---@type integer, DwarfLoadPair
local gpr_pieces = {} ---@type string[]
for _, pair in ipairs(regs) do ---@type integer, DwarfLoadPair
-- (DW_OP_regN, DW_OP_piece, ULEB128(4)) — one piece per GPR-resident field.
-- The 4 = U4_BYTE_SIZE: each piece is sizeof(uint32_t) on MIPS32.
table.insert(gpr_pieces, string.char(DW_OP_reg0 + pair.reg) .. string.char(DW_OP_piece) .. uleb128(U4_BYTE_SIZE))
@@ -376,9 +376,9 @@ local function build_debug_loclists_section(atom_table, registries)
-- Loclist unit header (DWARF5 §7.7.2):
-- unit_length(4) + version(2) + address_size(1) + segment_size(1) + offset_entry_count(4) = 12 bytes header.
-- version = 5 (DWARF5); address_size = 4 (MIPS32); segment_size = 0; offset_entry_count = 0 (we use DW_LLE_start_length, not offsets).
local LOCLIST_HEADER_SIZE = 12 ---@type integer
local body = table.concat(parts) ---@type string
local unit_length = LOCLIST_HEADER_SIZE - 4 + #body ---@type integer -- -4 because unit_length excludes itself
local LOCLIST_HEADER_SIZE = 12 ---@type integer
local body = table.concat(parts) ---@type string
local unit_length = LOCLIST_HEADER_SIZE - 4 + #body ---@type integer -- -4 because unit_length excludes itself
local header = elf_dwarf.write_u32_le(unit_length) ---@type string
.. elf_dwarf.write_u16_le(5) -- DWARF5
.. string.char(U4_BYTE_SIZE) -- address_size
@@ -401,11 +401,11 @@ end
-- @param atom_table DwarfAtom[] -- list of atoms with .rbind set
-- @return table<string, integer> -- bag: atom name -> offset_in_section
local function compute_loclists_offsets(atom_table)
local LOCLIST_ENTRY_HEADER_SIZE = 1 + 4 + 1 ---@type integer -- DW_LLE_start_length(1) + addr(4) + uleb_length(1)
local offsets = {} ---@type table<string, integer> -- bag
local LOCLIST_ENTRY_HEADER_SIZE = 1 + 4 + 1 ---@type integer -- DW_LLE_start_length(1) + addr(4) + uleb_length(1)
local offsets = {} ---@type table<string, integer> -- bag
-- Loclist unit header (DWARF5 §7.7.2): unit_length(4) + version(2) + address_size(1) + segment_size(1) + offset_entry_count(4) = 12 bytes.
-- The unit_length itself is not counted in the unit_length value, so the body starts at byte 12.
local cursor = 4 + 2 + 1 + 1 + 4 ---@type integer -- = 12
local cursor = 4 + 2 + 1 + 1 + 4 ---@type integer -- = 12
for _, atom in ipairs(atom_table) do ---@type integer, DwarfAtom
if atom.rbind then
offsets[atom.name] = cursor
@@ -414,14 +414,14 @@ local function compute_loclists_offsets(atom_table)
-- 1 (DW_LLE_start_length) + 4 (PC) + 1 (uleb length prefix) + sum(tape_piece_size(field.offset))
-- + 1 (DW_LLE_start_length) + 4 (transition_pc) + 1 (uleb length prefix) + n_fields * 3 (gpr pieces)
-- + 1 (DW_LLE_end_of_list)
local tape_pieces_size = 0 ---@type integer
local tape_pieces_size = 0 ---@type integer
for _, f in ipairs(atom.rbind.fields or {}) do ---@type integer, TypeField
tape_pieces_size = tape_pieces_size + tape_piece_size(f.offset or 0)
end
local gpr_pieces_size = n_fields * 3 ---@type integer -- each gpr piece: DW_OP_regN(1) + DW_OP_piece(1) + uleb(4)(1) = 3 bytes
local gpr_pieces_size = n_fields * 3 ---@type integer -- each gpr piece: DW_OP_regN(1) + DW_OP_piece(1) + uleb(4)(1) = 3 bytes
local tape_entry = LOCLIST_ENTRY_HEADER_SIZE + tape_pieces_size ---@type integer
local gpr_entry = LOCLIST_ENTRY_HEADER_SIZE + gpr_pieces_size ---@type integer
local body_len = tape_entry + gpr_entry + 1 ---@type integer -- +1 for DW_LLE_end_of_list
local gpr_entry = LOCLIST_ENTRY_HEADER_SIZE + gpr_pieces_size ---@type integer
local body_len = tape_entry + gpr_entry + 1 ---@type integer -- +1 for DW_LLE_end_of_list
cursor = cursor + body_len
end
end
@@ -430,7 +430,7 @@ end
-- Default name for the synthetic CU (so VSCode lists it as a known source).
local DEFAULT_CU_NAME = "tape_atom_locals" ---@type string
local DEFAULT_CU_COMP_DIR = "." ---@type string
local DEFAULT_CU_COMP_DIR = "." ---@type string
-- SECTION_WRITERS owns the .bin output path templates.
@@ -558,11 +558,11 @@ local DEFAULT_BASENAME = "hello_gte" ---@type string
--- @field data string
--- @class DwarfInjectionPass
--- @field run fun(ctx: PassCtx): PassResult
--- @field compute_loclists_offsets_for_test fun(atom_table: DwarfAtom[]): table<string, integer>
--- @field run fun(ctx: PassCtx): PassResult
--- @field compute_loclists_offsets_for_test fun(atom_table: DwarfAtom[]): table<string, integer>
--- @field build_debug_loclists_section_for_test fun(atom_table: DwarfAtom[], registries: DwarfRegistries): string
--- @field tape_piece_size_for_test fun(offset: integer): integer
--- @field build_atom_table_for_test fun(corpus: Corpus, addrs: table<string, NmAddr>): DwarfAtom[]
--- @field tape_piece_size_for_test fun(offset: integer): integer
--- @field build_atom_table_for_test fun(corpus: Corpus, addrs: table<string, NmAddr>): DwarfAtom[]
--- Project the corpus registries into the shape the section builders expect.
@@ -585,7 +585,7 @@ local function collect_per_source_registries(corpus)
-- `passes.scan_source.lua` has already folded every per-source scan into the corpus tables, so no per-source iteration is needed here.
-- `atom_infos` is preserved byte-for-byte with no filtering; consumers consult `corpus.atoms_by_name`
-- themselves when they need to know whether a particular atom_info corresponds to an actual atom record.
local atom_infos_list = {} ---@type AtomInfoEntry[]
local atom_infos_list = {} ---@type AtomInfoEntry[]
for _, ai in ipairs((corpus and corpus.atom_infos) or {}) do ---@type integer, AtomInfoEntry
atom_infos_list[#atom_infos_list + 1] = ai
end
@@ -660,7 +660,7 @@ local function build_atom_sequence(atom)
local function set_address(addr)
-- Per DWARF5 §6.2.5.3: marker(0) + size(ULEB128, includes sub_opcode byte) + sub_opcode + payload
-- For set_address: size = 1 (sub_opcode) + 4 (addr) = 5
local addr_bytes = elf_dwarf.write_u32_le(addr) ---@type string
local addr_bytes = elf_dwarf.write_u32_le(addr) ---@type string
local sub_size = string.char(DW_LNE_set_address) .. addr_bytes ---@type string
return string.char(DW_LNS_extended) .. uleb128(#sub_size) .. sub_size
end
@@ -714,12 +714,12 @@ local function build_atom_sequence(atom)
-- `start_pos` / `end_pos` are 0-based emitted-word positions stamped at construction/close time by `duffle.emit_invoke_begin` / `duffle.emit_invoke_end`;
-- Missing values are a corpus-plumbing bug, so we let the index expression fail loud with arithmetic-on-nil rather than silently producing `0+1=1` for a missing start_pos.
local invs = atom.invocations or {} ---@type InvocationRecord[]
local innermost_idx = {} ---@type table<integer, InvocationRecord|nil> -- bag
local ancestry_idx = {} ---@type table<integer, InvocationRecord[]> -- bag
for idx = 1, #atom.entries do ---@type integer
local innermost_idx = {} ---@type table<integer, InvocationRecord|nil> -- bag
local ancestry_idx = {} ---@type table<integer, InvocationRecord[]> -- bag
for idx = 1, #atom.entries do ---@type integer
innermost_idx[idx] = nil
ancestry_idx[idx] = {}
local active = {} ---@type InvocationRecord[]
local active = {} ---@type InvocationRecord[]
for _, inv in ipairs(invs) do ---@type integer, InvocationRecord
if idx >= inv.start_pos + 1 and idx <= inv.end_pos + 1 then
active[#active + 1] = inv
@@ -746,11 +746,11 @@ local function build_atom_sequence(atom)
-- This is the value the multi-row PC's body_lines[1] row must reference for source-order display: `anc.body_lines[1]` is the line of the FIRST WORD
-- (which for an outer whose body starts with a nested expansion is inside the inner's expansion = wrong for display purposes);
-- `anc.body_first_line` is the body's first content line in the parent's source (= correct for display).
local body_first_line_of = {} ---@type table<integer, integer> -- bag
local body_first_line_of = {} ---@type table<integer, integer> -- bag
for _, top_inv in ipairs(invs) do ---@type integer, InvocationRecord
local earliest_nested_call_line = nil ---@type integer
local earliest_nested_start_pos = nil ---@type integer
for _, cand in ipairs(invs) do ---@type integer, InvocationRecord
for _, cand in ipairs(invs) do ---@type integer, InvocationRecord
if cand.parent_id == top_inv.id and cand.call_line ~= nil then
if earliest_nested_start_pos == nil or cand.start_pos < earliest_nested_start_pos then
earliest_nested_start_pos = cand.start_pos
@@ -808,7 +808,7 @@ local function build_atom_sequence(atom)
local call_file_idx = resolve_provenance_file_index(atom.src_path) ---@type integer
-- --- Atom entry (idx 1) -------------------------------------------------
local entry_1 = atom.entries[1] ---@type DwarfAtomWord
local entry_1 = atom.entries[1] ---@type DwarfAtomWord
local entry_1_ancestry = ancestry_idx[1] ---@type InvocationRecord[]
-- If atom entry 1 starts inside an invocation, walk the ancestry and emit a call-site row + (when applicable)
@@ -842,7 +842,7 @@ local function build_atom_sequence(atom)
-- --- Subsequent entries (idx 2..N) --------------------------------------
for idx = 2, #atom.entries do ---@type integer|nil
local entry = atom.entries[idx] ---@type DwarfAtomWord
local entry = atom.entries[idx] ---@type DwarfAtomWord
local inv = innermost_idx[idx] ---@type InvocationRecord
-- Advance PC by 1 .word (4 bytes on MIPS).
@@ -946,7 +946,7 @@ local function build_atom_table(corpus, addrs)
-- Build the dense entries list from `word_events`.
-- `word_events[i].i` = the 0-based `.word` position
-- `call_line` = the root atom's physical source line for that word (stamped by emission_model)
local entries = {} ---@type DwarfAtomWord[]
local entries = {} ---@type DwarfAtomWord[]
for idx, ev in ipairs(word_events) do ---@type integer, WordEvent
entries[#entries + 1] = {
pos = ev.i or (idx - 1),
@@ -990,7 +990,7 @@ local function build_atom_table(corpus, addrs)
-- Cross-ref with the nm symbol table; atoms absent from `addrs` are skipped
-- (an atom declared in source but not emitted as a symbol is a metaprogram or atom-info bug, not a source-correlation bug — emit_no_emit would catch it upstream).
for _, src in ipairs((corpus and corpus.source_order) or {}) do ---@type integer, SourceFile
local src_path = src.path or "" ---@type string
local src_path = src.path or "" ---@type string
for _, atom_rec in ipairs(((src.scan or {}).atoms) or {}) do ---@type integer, AtomEntry
local info = addrs[atom_rec.name or atom_rec.raw_name] ---@type NmAddr|nil
if info then
@@ -1018,7 +1018,7 @@ end
--- @param atom_table DwarfAtom[]
--- @return table<string, DwarfComponentSite>
local function collect_component_defs(atom_table)
local out = {} ---@type table<string, DwarfComponentSite> -- bag
local out = {} ---@type table<string, DwarfComponentSite> -- bag
for _, atom in ipairs(atom_table) do ---@type integer, DwarfAtom
for _, inv in ipairs(atom.invocations or {}) do ---@type integer, InvocationRecord
if not out[inv.component_name] then
@@ -1065,14 +1065,14 @@ end
--- @param registries DwarfRegistries -- Merged registries from collect_per_source_registries
--- @return DwarfLoadPair[] -- List of {reg = <MIPS index>, field = <field name>}
local function parse_body_load_pairs(body_tokens, binds_name, registries)
local pairs = {} ---@type DwarfLoadPair[]
local pairs = {} ---@type DwarfLoadPair[]
local reg_index_by_name = (registries and registries.register_alias_registry) or {} ---@type table<string, AliasEntry> -- bag
-- One regex that matches any of: load_word, load_half, load_half_u, load_byte, load_byte_u, gte_lw, gte_lwc2.
-- The captured ident is `kind`; `inner` holds the parens body for arg parsing.
local load_pattern = "^(load_word|load_half|load_half_u|load_byte|load_byte_u|gte_lw|gte_lwc2)%s*%((.*)%)$" ---@type string
for _, t in ipairs(body_tokens or {}) do ---@type integer, BodyToken
for _, t in ipairs(body_tokens or {}) do ---@type integer, BodyToken
local tok = duffle.trim(t.tok or "") ---@type string
local kind, inner = tok:match(load_pattern) ---@type string|nil, string|nil
local kind, inner = tok:match(load_pattern) ---@type string|nil, string|nil
if kind then
local args = duffle.split_top_level_commas(inner) ---@type string[]
-- Expected shape for an rbind piece-chain load: (R_<reg>, R_TapePtr, O_(Binds_<X>, FieldName))
@@ -1083,7 +1083,7 @@ local function parse_body_load_pairs(body_tokens, binds_name, registries)
local third_arg = duffle.trim(args[3]) ---@type string
-- Match O_(Binds_<X>, FieldName)
local b, f = third_arg:match("^O_%((Binds_[%w_]+)%s*,%s*(.-)%s*%)$") ---@type string|nil, string|nil
local alias_entry = reg_index_by_name[reg_name] ---@type AliasEntry|nil
local alias_entry = reg_index_by_name[reg_name] ---@type AliasEntry|nil
if b and b == binds_name and alias_entry and alias_entry.code then
pairs[#pairs + 1] = {
reg = alias_entry.code,
@@ -1118,7 +1118,7 @@ local function parse_rbind_atoms(corpus, atom_table, registries)
-- Index binds by struct name; consume `scan.binds[i].fields` directly.
-- The scan-source pass emits each Binds_X's fields as {[type_name, pointer_depth, offset, byte_size, ...]},
-- so this pass builds the rbind_structs entry without re-parsing.
local binds_by_name = {} ---@type table<string, BindsEntry> -- bag
local binds_by_name = {} ---@type table<string, BindsEntry> -- bag
for _, src in ipairs((corpus and corpus.source_order) or {}) do ---@type integer, SourceFile
local scan = src.scan ---@type SourceScan|nil
if scan then
@@ -1139,7 +1139,7 @@ local function parse_rbind_atoms(corpus, atom_table, registries)
end
-- Walk every atom_info; if `binds` is set, find the atom body_tokens + parse load_word pairs.
local body_tokens_by_atom = {} ---@type table<string, BodyToken[]> -- bag
local body_tokens_by_atom = {} ---@type table<string, BodyToken[]> -- bag
for _, src in ipairs((corpus and corpus.source_order) or {}) do ---@type integer, SourceFile
local scan = src.scan ---@type SourceScan|nil
if scan then
@@ -1149,7 +1149,7 @@ local function parse_rbind_atoms(corpus, atom_table, registries)
end
end
local ai_by_atom = {} ---@type table<string, AtomInfoEntry> -- bag
local ai_by_atom = {} ---@type table<string, AtomInfoEntry> -- bag
for _, src in ipairs((corpus and corpus.source_order) or {}) do ---@type integer, SourceFile
local scan = src.scan ---@type SourceScan|nil
if scan then
@@ -1161,7 +1161,7 @@ local function parse_rbind_atoms(corpus, atom_table, registries)
for atom_name, ai in pairs(ai_by_atom) do ---@type string, AtomInfoEntry
if ai.binds then
local struct = rbind_structs[ai.binds] ---@type DwarfRbindStruct|nil
local struct = rbind_structs[ai.binds] ---@type DwarfRbindStruct|nil
local body_toks = body_tokens_by_atom[atom_name] ---@type BodyToken[]|nil
if struct and body_toks then
local pairs = parse_body_load_pairs(body_toks, ai.binds, registries) ---@type DwarfLoadPair[]
@@ -1208,9 +1208,9 @@ local function build_dwarf_line_section(existing, atom_table)
if #atom_table == 0 then return existing end
-- Build the sequences.
local sequences = {} ---@type string[]
local sequences = {} ---@type string[]
for _, atom in ipairs(atom_table) do sequences[#sequences + 1] = build_atom_sequence(atom) end ---@type integer, DwarfAtom
local appended = table.concat(sequences) ---@type string
local appended = table.concat(sequences) ---@type string
-- Walk DWARF32 line units and retain the final unit's bounds.
-- The main C CU points at this final unit (DW_AT_stmt_list = 0x5b in today's ELF).
@@ -1226,7 +1226,7 @@ local function build_dwarf_line_section(existing, atom_table)
end
if unit_pos ~= #existing or not last_pos then return existing end
local new_length = last_length + #appended ---@type integer
local new_length = last_length + #appended ---@type integer
local new_length_bytes = elf_dwarf.write_u32_le(new_length) ---@type string
return existing:sub(1, last_pos)
@@ -1272,8 +1272,8 @@ local function build_dwarf_aranges_section(existing, atom_table)
-- Walk all units and emit each one (preserving existing structure).
-- For the LAST unit, replace the terminator with my entries + new term.
local result = {} ---@type string[]
local i = 0 ---@type integer -- zero-based wire offset
local result = {} ---@type string[]
local i = 0 ---@type integer -- zero-based wire offset
local is_last_unit = false ---@type boolean
while i < #existing do
@@ -1285,21 +1285,21 @@ local function build_dwarf_aranges_section(existing, atom_table)
return existing
end
local unit_start = i ---@type integer
local unit_start = i ---@type integer
local unit_end_excl = i + 4 + ul ---@type integer
is_last_unit = (unit_end_excl == #existing)
if is_last_unit then
-- The old terminator is replaced by entries + a new terminator, so net section growth (and unit_length growth) is entries only.
local added_bytes = #atom_table * elf_dwarf.DWARF4_ARANGES.entry_size ---@type integer
local new_ul = ul + added_bytes ---@type integer
local new_ul_bytes = elf_dwarf.write_u32_le(new_ul) ---@type string
local new_ul = ul + added_bytes ---@type integer
local new_ul_bytes = elf_dwarf.write_u32_le(new_ul) ---@type string
-- Emit everything EXCEPT the last 8 bytes (terminator).
result[#result + 1] = new_ul_bytes
.. existing:sub(i + 5, unit_end_excl - elf_dwarf.DWARF4_ARANGES.terminator_size)
-- Append my atom entries.
for _, atom in ipairs(atom_table) do ---@type integer, DwarfAtom
local a = atom.addr ---@type integer
local a = atom.addr ---@type integer
local size = atom.size_bytes ---@type integer
result[#result + 1] = elf_dwarf.write_u32_le(a) .. elf_dwarf.write_u32_le(size)
end
@@ -1337,10 +1337,10 @@ end
local function build_dwarf_rnglists_section(existing, atom_table)
if #existing <= elf_dwarf.DWARF5_RNGLISTS.first_entry_offset or #atom_table == 0 then return existing end
local unit_length = elf_dwarf.read_u32_le(existing, elf_dwarf.DWARF5_RNGLISTS.unit_length_offset) ---@type integer
local version = elf_dwarf.read_u16_le(existing, elf_dwarf.DWARF5_RNGLISTS.version_offset) ---@type integer
local address_size = existing:byte(elf_dwarf.DWARF5_RNGLISTS.addr_size_offset + 1) ---@type integer
local segment_size = existing:byte(elf_dwarf.DWARF5_RNGLISTS.seg_size_offset + 1) ---@type integer
local unit_length = elf_dwarf.read_u32_le(existing, elf_dwarf.DWARF5_RNGLISTS.unit_length_offset) ---@type integer
local version = elf_dwarf.read_u16_le(existing, elf_dwarf.DWARF5_RNGLISTS.version_offset) ---@type integer
local address_size = existing:byte(elf_dwarf.DWARF5_RNGLISTS.addr_size_offset + 1) ---@type integer
local segment_size = existing:byte(elf_dwarf.DWARF5_RNGLISTS.seg_size_offset + 1) ---@type integer
local offset_entry_count = elf_dwarf.read_u32_le(existing, elf_dwarf.DWARF5_RNGLISTS.offset_count_offset) ---@type integer
if unit_length + 4 ~= #existing
@@ -1352,14 +1352,14 @@ local function build_dwarf_rnglists_section(existing, atom_table)
return existing
end
local entries = {} ---@type string[]
local entries = {} ---@type string[]
for _, atom in ipairs(atom_table) do ---@type integer, DwarfAtom
entries[#entries + 1] = string.char(DW_RLE_start_length)
.. elf_dwarf.write_u32_le(atom.addr)
.. uleb128(atom.size_bytes)
end
local appended = table.concat(entries) ---@type string
local new_length = unit_length + #appended ---@type integer
local appended = table.concat(entries) ---@type string
local new_length = unit_length + #appended ---@type integer
local new_length_bytes = elf_dwarf.write_u32_le(new_length) ---@type string
return new_length_bytes
@@ -1390,16 +1390,16 @@ end
--- @param rbind DwarfRbind -- {regs = {{reg, field}, ...}, fields = {{name, offset}, ...}, bytes = N}
--- @return string -- the exprloc byte sequence (length-prefixed)
local function piece_chain_exprloc(rbind)
local op_bytes = {} ---@type string[]
local field_offset_by_name = {} ---@type table<string, integer> -- bag
local op_bytes = {} ---@type string[]
local field_offset_by_name = {} ---@type table<string, integer> -- bag
for _, f in ipairs(rbind.fields) do ---@type integer, TypeField
field_offset_by_name[f.name] = f.offset
end
local next_offset = rbind.bytes ---@type integer
for i = #rbind.regs, 1, -1 do ---@type integer -- walk backwards to know each piece's size
local pair = rbind.regs[i] ---@type DwarfLoadPair
for i = #rbind.regs, 1, -1 do ---@type integer -- walk backwards to know each piece's size
local pair = rbind.regs[i] ---@type DwarfLoadPair
local off = field_offset_by_name[pair.field] or 0 ---@type integer
local size ---@type integer
local size ---@type integer
if i == #rbind.regs then
size = next_offset - off
else
@@ -1416,9 +1416,9 @@ local function piece_chain_exprloc(rbind)
next_offset = off
end
-- We built it back-to-front; reverse it.
local rev = {} ---@type string[]
local rev = {} ---@type string[]
for i = #op_bytes, 1, -1 do rev[#rev + 1] = op_bytes[i] end ---@type integer
local op = table.concat(rev) ---@type string
local op = table.concat(rev) ---@type string
return uleb128(#op) .. op
end
@@ -1440,10 +1440,10 @@ end
-- "math.floor(/16) instead of bit.rshift for LuaJIT 2.1 compat" comment at line 352).
-- DWARF5 compile-unit header constants.
local DW_VERSION_5 = 5 ---@type integer
local DW_UT_compile = 0x01 ---@type integer
local DWARF32_TERMINATOR = 0xFFFFFFFF ---@type integer -- sentinel for DWARF64 marker
local CU_HEADER_SIZE = 12 ---@type integer -- 4 + 2 + 1 + 1 + 4
local DW_VERSION_5 = 5 ---@type integer
local DW_UT_compile = 0x01 ---@type integer
local DWARF32_TERMINATOR = 0xFFFFFFFF ---@type integer -- sentinel for DWARF64 marker
local CU_HEADER_SIZE = 12 ---@type integer -- 4 + 2 + 1 + 1 + 4
--- Walk .debug_info to find the FINAL compilation unit, validate it as a DWARF5 32-bit compile-unit, and extract its bounds + abbrev-table offset.
--- Returns nil on any layout mismatch. Callers fall back to existing sections.
@@ -1467,7 +1467,7 @@ local function find_main_cu_layout(existing)
local buf_len = #existing ---@type integer
if buf_len < CU_HEADER_SIZE then return nil end
local pos = 0 ---@type integer
local pos = 0 ---@type integer
local main_cu_start = nil ---@type integer
local main_cu_end_excl = nil ---@type integer
while pos + 4 <= buf_len do
@@ -1489,10 +1489,10 @@ local function find_main_cu_layout(existing)
-- [6] unit_type
-- [7] address_size
-- [8..11] debug_abbrev_offset
local hdr = main_cu_start + 4 ---@type integer
local version = elf_dwarf.read_u16_le(existing, hdr) ---@type integer
local unit_type = existing:byte(hdr + 2 + 1) ---@type integer
local address_size = existing:byte(hdr + 3 + 1) ---@type integer
local hdr = main_cu_start + 4 ---@type integer
local version = elf_dwarf.read_u16_le(existing, hdr) ---@type integer
local unit_type = existing:byte(hdr + 2 + 1) ---@type integer
local address_size = existing:byte(hdr + 3 + 1) ---@type integer
local abbrev_off = elf_dwarf.read_u32_le(existing, hdr + 4) ---@type integer
if version ~= DW_VERSION_5 or unit_type ~= DW_UT_compile or address_size ~= 4 then
return nil
@@ -1673,7 +1673,7 @@ local function build_new_strings(atom_table, registries)
-- The CU name + comp_dir are the first two strings (offsets 0 and N1).
-- Then each unique atom name + each register name follows.
local strings = {} ---@type string[]
local map = {} ---@type table<string, integer> -- bag
local map = {} ---@type table<string, integer> -- bag
-- CU name at offset 0 in the new blob
strings[#strings + 1] = DEFAULT_CU_NAME .. "\0"
@@ -1698,7 +1698,7 @@ local function build_new_strings(atom_table, registries)
-- filtered to MIPS GPR 0..31 — the same filter that build_inserted_children applies
-- for the RR_<name> locals, so .debug_str entries stay in sync with .debug_info).
-- Lua's pairs() is non-deterministic; sort the alias names first so the emitted .debug_str bytes are byte-identical across runs.
local sorted_alias_names = {} ---@type string[]
local sorted_alias_names = {} ---@type string[]
for r_name, alias in pairs(registries.register_alias_registry or {}) do ---@type string, AliasEntry|nil
if alias.code and alias.code >= 0 and alias.code <= 31 then
sorted_alias_names[#sorted_alias_names + 1] = r_name
@@ -1775,13 +1775,13 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
-- by_alias_order: sorted list of by_alias keys, for deterministic iteration order.
-- Lua's pairs() order is implementation-defined and varies between runs; without sorting, the per-atom variable emission order
-- would be non-deterministic and the .debug_info bytes would differ across builds.
local by_alias = {} ---@type table<string, AliasEntry> -- bag
local by_alias = {} ---@type table<string, AliasEntry> -- bag
for r_name, alias in pairs(registries.register_alias_registry or {}) do ---@type string, AliasEntry|nil
if alias.code and alias.code >= 0 and alias.code <= 31 then
by_alias[r_name] = alias
end
end
local by_alias_order = {} ---@type string[]
local by_alias_order = {} ---@type string[]
for r_name in pairs(by_alias) do by_alias_order[#by_alias_order + 1] = r_name end ---@type string
table.sort(by_alias_order)
@@ -1790,7 +1790,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
--- @param atoms DwarfAtom[]
--- @return table<string, DwarfAtom>
local function build_atom_name_index(atoms)
local m = {} ---@type table<string, DwarfAtom> -- bag
local m = {} ---@type table<string, DwarfAtom> -- bag
for _, a in ipairs(atoms or {}) do ---@type integer, AliasEntry|nil
if a and a.name then m[a.name] = a end
end
@@ -1861,7 +1861,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
local row = DIE_SCHEMA[schema_name] ---@type DieSchema
emit(uleb128(row.abbrev))
for _, attr in ipairs(row.attrs) do ---@type integer, DieSchemaAttr
local v = values[attr.key] ---@type string|integer
local v = values[attr.key] ---@type string|integer
local w = FORM_WRITERS[attr.form] ---@type DieFormWriter
if not w then error("emit_die: unknown form " .. tostring(attr.form)) end
w(emit, v)
@@ -1898,7 +1898,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
-- Always include the base_type "unsigned int" as the U4 target.
type_offsets["U4"] = base_type_section_offset
-- Collect every unique (type_name, max_pointer_depth) used by any rbind field.
local used_typed_views = {} ---@type table<string, integer> -- bag -- { [type_name] = max_depth }
local used_typed_views = {} ---@type table<string, integer> -- bag -- { [type_name] = max_depth }
for _, atom in ipairs(atom_table) do ---@type integer, DwarfAtom
if atom.rbind and atom.rbind.fields then
for _, f in ipairs(atom.rbind.fields) do ---@type integer, TypeField
@@ -1912,7 +1912,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
end
end
-- Sort for deterministic emission.
local sorted_typed_types = {} ---@type string[]
local sorted_typed_types = {} ---@type string[]
for tn in pairs(used_typed_views) do sorted_typed_types[#sorted_typed_types + 1] = tn end ---@type string
table.sort(sorted_typed_types)
-- For each non-U4 type, emit a typedef (DW_TAG_typedef) named after the type and referencing the base_type "unsigned int" (4 bytes).
@@ -1938,7 +1938,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
return nil
end
if entry.byte_size == nil then return nil end
local members = {} ---@type DwarfTypeLayoutMember[]
local members = {} ---@type DwarfTypeLayoutMember[]
for _, f in ipairs(entry.fields) do ---@type integer, TypeField
if f.offset == nil or f.byte_size == nil then return nil end
members[#members + 1] = {
@@ -2028,7 +2028,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
end
for _, tn in ipairs(sorted_typed_types) do ---@type integer, string
if tn ~= "U4" then
local depth = used_typed_views[tn] ---@type integer
local depth = used_typed_views[tn] ---@type integer
local struct_offset = emit_struct_layout(tn) ---@type integer
if not struct_offset then
local innermost_offset = next_offset() ---@type integer
@@ -2084,8 +2084,8 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
type_chain_offsets["U4|1"] = u4_chain_offset
-- 2) Emit one DW_TAG_structure_type per unique Binds_X.
local struct_section_offsets = {} ---@type table<string, integer> -- bag
local sorted_struct_names = {} ---@type string[]
local struct_section_offsets = {} ---@type table<string, integer> -- bag
local sorted_struct_names = {} ---@type string[]
for k in pairs(rbind_structs) do sorted_struct_names[#sorted_struct_names + 1] = k end ---@type string
table.sort(sorted_struct_names)
for _, binds_name in ipairs(sorted_struct_names) do ---@type integer, string
@@ -2119,13 +2119,13 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
-- Each abstract DIE is a CU-level child (sibling of the per-atom subprograms below).
-- The abstract DIE's section offset is later used by inlined_subroutine DIEs (which embed `DW_AT_abstract_origin = ref4 → abstract DIE`).
-- Each abstract DIE also carries DW_AT_decl_file + DW_AT_decl_line pointing at the component's definition site (file path + body line).
local component_defs = collect_component_defs(atom_table) ---@type table<string, DwarfComponentSite> -- bag
local abstract_offsets = {} ---@type table<string, integer> -- bag -- name -> section offset
local sorted_comp_names = {} ---@type string[]
local component_defs = collect_component_defs(atom_table) ---@type table<string, DwarfComponentSite> -- bag
local abstract_offsets = {} ---@type table<string, integer> -- bag -- name -> section offset
local sorted_comp_names = {} ---@type string[]
for name in pairs(component_defs) do sorted_comp_names[#sorted_comp_names + 1] = name end ---@type string
table.sort(sorted_comp_names)
-- DW_INL_inlined (1) = "this subroutine was inlined" — accurate for the mac_* components.
local DW_INL_inlined = 0x01 ---@type integer
local DW_INL_inlined = 0x01 ---@type integer
for _, comp_name in ipairs(sorted_comp_names) do ---@type integer, string
local def = component_defs[comp_name] ---@type DwarfComponentSite
abstract_offsets[comp_name] = next_offset()
@@ -2159,10 +2159,10 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
-- (e) enum-site atom_type(<T>) default: register_alias_registry[R_Name].default_type (per-alias fallback declared in lottes_tape.h)
-- (f) void* fallback: the void_chain_offset built in section 1b; gdb renders `(void *) 0x...` (hex)
-- An R_Name absent from the registry AND missed by all of (a..e) skips emission for that alias entirely.
local atom_view_ctx_fields = nil ---@type table<string, TypeField>|nil -- bag -- populated by step (b); map field_name -> field entry
local reg_to_field_ctx = nil ---@type table<integer, string>|nil -- bag -- populated by step (b); map GPR index -> field name
local atom_view_phase_fields = nil ---@type table<string, TypeField>|nil -- bag -- populated by step (d); map field_name -> field entry
local reg_to_field_phase = nil ---@type table<integer, string>|nil -- bag -- populated by step (d); map GPR index -> field name
local atom_view_ctx_fields = nil ---@type table<string, TypeField>|nil -- bag -- populated by step (b); map field_name -> field entry
local reg_to_field_ctx = nil ---@type table<integer, string>|nil -- bag -- populated by step (b); map GPR index -> field name
local atom_view_phase_fields = nil ---@type table<string, TypeField>|nil -- bag -- populated by step (d); map field_name -> field entry
local reg_to_field_phase = nil ---@type table<integer, string>|nil -- bag -- populated by step (d); map GPR index -> field name
-- atom-name -> atom lookup is precomputed once as atom_by_name_global.
local field_type_by_name = {} ---@type table<string, TypeField> -- bag
if atom.rbind and atom.rbind.fields then
@@ -2194,7 +2194,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
end
-- step (d) inputs: this atom's `atom_phase(<label>)`. Find the FIRST atom in the same phase group that has its own rbind
-- and is in source-order (declared before this atom in any source file); locate it via the per-atom_info entry whose phase == this atom's name.
local my_phase_label = nil ---@type string|nil
local my_phase_label = nil ---@type string|nil
for _, ai in ipairs(registries.atom_infos or {}) do ---@type integer, AtomInfoEntry
if ai.atom_name == atom.name and ai.phase then
my_phase_label = ai.phase
@@ -2240,7 +2240,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
--- @param alias_code integer
--- @return integer|nil
function(r_name, alias_code)
local ctx_field_name = reg_to_field_ctx and reg_to_field_ctx[alias_code] ---@type string|nil
local ctx_field_name = reg_to_field_ctx and reg_to_field_ctx[alias_code] ---@type string|nil
local ctx_f = ctx_field_name and atom_view_ctx_fields and atom_view_ctx_fields[ctx_field_name] ---@type TypeField|nil
if ctx_f and ctx_f.pointer_depth and ctx_f.pointer_depth > 0 then
return type_chain_offsets[ctx_f.type_name .. "|" .. ctx_f.pointer_depth]
@@ -2251,7 +2251,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
--- @param alias_code integer
--- @return integer|nil
function(r_name, alias_code)
local field_name = reg_to_field[alias_code] ---@type string|nil
local field_name = reg_to_field[alias_code] ---@type string|nil
local f = field_name and field_type_by_name[field_name] ---@type TypeField|nil
if f and f.pointer_depth and f.pointer_depth > 0 then
return type_chain_offsets[f.type_name .. "|" .. f.pointer_depth]
@@ -2262,7 +2262,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
--- @param alias_code integer
--- @return integer|nil
function(r_name, alias_code)
local phase_field_name = reg_to_field_phase and reg_to_field_phase[alias_code] ---@type string|nil
local phase_field_name = reg_to_field_phase and reg_to_field_phase[alias_code] ---@type string|nil
local phase_f = phase_field_name and atom_view_phase_fields and atom_view_phase_fields[phase_field_name] ---@type TypeField|nil
if phase_f and phase_f.pointer_depth and phase_f.pointer_depth > 0 then
return type_chain_offsets[phase_f.type_name .. "|" .. phase_f.pointer_depth]
@@ -2282,11 +2282,11 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
-- Iterate `by_alias` in sorted order; Lua's pairs() is non-deterministic, so sorting ensures byte-identical DWARF output across builds.
for _, r_name in ipairs(by_alias_order) do ---@type integer, string
local alias = by_alias[r_name] ---@type AliasEntry|nil
local alias = by_alias[r_name] ---@type AliasEntry|nil
local rr_name = "RR_" .. strip_r_prefix(r_name) ---@type string
local alias_code = alias.code ---@type integer
local type_offset = type_chain_offsets["void|1"] ---@type integer
for _, step in ipairs(PRECEDENCE_STEPS) do ---@type integer, DwarfPrecedenceStep
local alias_code = alias.code ---@type integer
local type_offset = type_chain_offsets["void|1"] ---@type integer
for _, step in ipairs(PRECEDENCE_STEPS) do ---@type integer, DwarfPrecedenceStep
local candidate = step(r_name, alias_code) ---@type integer
if candidate then type_offset = candidate; break end
end
@@ -2303,7 +2303,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
-- Two PC ranges cover every field: [atom.addr, last_load+8) describes each field as tape memory (DW_OP_bregN + offset) piece,
-- and [last_load+8, atom.end) describes each field as a GPR (DW_OP_regN) piece.
if atom.rbind then
local binds_name = atom.rbind.binds ---@type string
local binds_name = atom.rbind.binds ---@type string
local loclists_offset = loclists_offsets[atom.name] or 0 ---@type integer
emit_die("bind_var_loclist", {
name = "bind_args",
@@ -2322,7 +2322,7 @@ local function build_inserted_children(main_cu_offset, main_cu_end_excl, atom_ta
-- This invocation emits no inlined_subroutine DIE; the whole-PC-range non-statement rows in .debug_line provide full skip semantics.
-- Stepping from the preceding atom statement lands at the first unskipped row after this invocation's range.
else
local inv_low = atom.addr + inv.start_pos * MIPS_BYTES_PER_WORD ---@type integer
local inv_low = atom.addr + inv.start_pos * MIPS_BYTES_PER_WORD ---@type integer
local inv_high = atom.addr + (inv.end_pos + 1) * MIPS_BYTES_PER_WORD ---@type integer
emit_die("inlined_subroutine", {
abstract_origin = ref4_of(abstract_offsets[inv.component_name]),
@@ -2368,7 +2368,7 @@ local function build_debug_abbrev_section(existing, main_abbrev_offset)
-- Duplicate the main table declarations, excluding its terminating 0 byte.
-- (1-indexed sub: existing:sub(main_abbrev_offset + 1, table_end) reads bytes from 0-based [main_abbrev_offset .. table_end - 1].)
local main_table_dup = existing:sub(main_abbrev_offset + 1, table_end) ---@type string
local new_abbrevs = build_new_abbrev() ---@type string -- includes its own terminating 0
local new_abbrevs = build_new_abbrev() ---@type string -- includes its own terminating 0
-- The MAIN CU's debug_abbrev_offset points to the duplicate's start (= #existing).
-- Codes 100..106 follow the duplicate's declarations inside that same table.
@@ -2407,12 +2407,12 @@ end
local function build_debug_info_section(existing, main_cu_start, main_cu_end_excl, new_abbrev_offset, atom_table, rbind_structs, loclists_offsets, registries)
-- 1) Build the inserted children bytes (just before the main CU's root terminator).
local inserted = build_inserted_children(main_cu_start, main_cu_end_excl, atom_table, rbind_structs, loclists_offsets, registries) ---@type string
local inserted_len = #inserted ---@type integer
local inserted_len = #inserted ---@type integer
-- 2) Patch main CU's unit_length += inserted_len.
local old_unit_length = elf_dwarf.read_u32_le(existing, main_cu_start) ---@type integer
local new_unit_length = old_unit_length + inserted_len ---@type integer
local new_unit_length_bytes = elf_dwarf.write_u32_le(new_unit_length) ---@type string
local new_unit_length = old_unit_length + inserted_len ---@type integer
local new_unit_length_bytes = elf_dwarf.write_u32_le(new_unit_length) ---@type string
-- 3) Patch main CU's debug_abbrev_offset (bytes [main_cu_start + 8 .. + 11]).
local new_abbrev_offset_bytes = elf_dwarf.write_u32_le(new_abbrev_offset) ---@type string
@@ -2425,8 +2425,8 @@ local function build_debug_info_section(existing, main_cu_start, main_cu_end_exc
-- [main_cu_start + 8 .. + 11] debug_abbrev_offset (PATCHED)
-- [main_cu_start + 12 .. main_cu_end_excl - 2] existing DIE bytes, unchanged
-- [main_cu_end_excl - 1] root children-terminator, unchanged 0
local pre_end = main_cu_end_excl - 2 ---@type integer -- 0-based end of existing DIE bytes (inclusive)
local root_terminator = main_cu_end_excl - 1 ---@type integer -- 0-based position of the final 0 byte
local pre_end = main_cu_end_excl - 2 ---@type integer -- 0-based end of existing DIE bytes (inclusive)
local root_terminator = main_cu_end_excl - 1 ---@type integer -- 0-based position of the final 0 byte
return existing:sub(1, main_cu_start) -- crt CU
.. new_unit_length_bytes -- patched unit_length (4 bytes)
@@ -2487,10 +2487,10 @@ local SECTION_WRITERS = { ---@type table<string, DwarfSectionPathWriter>
--- @param basename string -- output file basename (e.g. "hello_gte")
--- @return table<string, string>[] -- bag: one <section>_bin -> path per row
local function write_sections(results, ctx, basename)
local outputs = {} ---@type table<string, string>[] -- bag: one <section>_bin -> path per row
local outputs = {} ---@type table<string, string>[] -- bag: one <section>_bin -> path per row
for _, r in ipairs(results) do ---@type integer, DwarfSectionBlob
local path = SECTION_WRITERS[r.name](ctx.out_root, basename) ---@type string
local f = io.open(path, "wb") ---@type file*|nil
local f = io.open(path, "wb") ---@type file*|nil
if not f then
io.stderr:write(string.format("[dwarf_injection] failed to open %s for write\n", path))
else
@@ -2545,11 +2545,11 @@ function M.run(ctx)
-- Skip state lives in `corpus.atoms_by_name[*].debug_skip` (whole-atom) and `atom.paths.invocations[*].debug_skip` (per-invocation).
-- `corpus` is the sole canonical source projection.
local corpus = (ctx.shared and ctx.shared.corpus) or {} ---@type Corpus
local registries = collect_per_source_registries(corpus) ---@type DwarfRegistries
local registries = collect_per_source_registries(corpus) ---@type DwarfRegistries
-- Read nm symbols (the ONLY disk-side input to the atom table) and join them against `corpus.atoms_by_name` + `atom.paths` for word rows + invocation ancestry.
-- Disk source-map/provenance text is not consulted (those are diagnostic artifacts; semantic inputs are in memory).
local addrs = elf_dwarf.read_nm(ctx.flags.elf_path) ---@type table<string, NmAddr> -- bag
local atom_table = build_atom_table(corpus, addrs) ---@type DwarfAtom[]
local atom_table = build_atom_table(corpus, addrs) ---@type DwarfAtom[]
-- Detect rbind atoms + index Binds_* struct fields from the corpus.
-- The merged registries are threaded through so parse_body_load_pairs resolves R_<reg> via register_alias_registry.
@@ -2573,13 +2573,13 @@ function M.run(ctx)
-- Step 0: layout validation. Bail out safely if the .debug_info layout doesn't match what we expect (crt CU + DWARF5 main CU + final 0 byte).
-- A layout mismatch means the gcc emission changed; the safest response is to leave existing sections unchanged and emit no synthetic data, so the build's debug-info step never silently produces broken DWARF.
local existing_info = existing_sections[".debug_info"] or "" ---@type string
local existing_abbrev = existing_sections[".debug_abbrev"] or "" ---@type string
local existing_info = existing_sections[".debug_info"] or "" ---@type string
local existing_abbrev = existing_sections[".debug_abbrev"] or "" ---@type string
local main_cu_start, main_cu_end_excl, main_abbrev_offset = find_main_cu_layout(existing_info) ---@type integer|nil, integer|nil, integer|nil
if not main_cu_start then
io.stderr:write("[dwarf_injection] layout validation failed; writing existing sections unchanged\n")
local existing_str = existing_sections[".debug_str"] or "" ---@type string
local results_safe = { ---@type DwarfSectionBlob[]
local results_safe = { ---@type DwarfSectionBlob[]
{ name = "debug_info", data = existing_info },
{ name = "debug_abbrev", data = existing_abbrev },
{ name = "debug_str", data = existing_str },
scripts/passes/emission_model.lua
+15 -15
View File
@@ -123,7 +123,7 @@ local M = {} ---@type EmissionModelPass
-- Bootstrap: load `duffle_paths.lua` via debug.getinfo so the module works standalone (run as `luajit passes/emission_model.lua`) and when require'd from the orchestrator.
-- ─────────────────────────────────────────────────────────────────────────
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
-- ─────────────────────────────────────────────────────────────────────────
-- Helpers
@@ -155,8 +155,8 @@ local function stamp_root_provenance(projection, atom_record, src, corpus)
-- The walker assigns line 2 to the body's first content line because line 1 is the trailing `\n` after `{`. Body-text line k therefore maps to `root_body_line + (k - 1)`.
-- `body_off - 1` points at the opening `{`, whose line index identifies the header line. `body_off` points after `{` and would shift every word row forward by one line.
local root_body_line = root_line_of(atom_record.body_off - 1) or atom_record.line or 0 ---@type integer
local component_index = corpus.component_body_index or {} ---@type table<string, ComponentBodyEntry>
local word_items = {} ---@type EmissionItem[]
local component_index = corpus.component_body_index or {} ---@type table<string, ComponentBodyEntry>
local word_items = {} ---@type EmissionItem[]
for _, item in ipairs(projection.items) do ---@type integer, EmissionItem
if item.kind == "word" then word_items[#word_items + 1] = item end
@@ -173,7 +173,7 @@ local function stamp_root_provenance(projection, atom_record, src, corpus)
-- The innermost open invocation identifies which line index the walker used.
-- A component `line_of` makes `item.line` physical; the atom's `body_text` line index makes it body-relative.
if ids and #ids > 0 then
local inner_id = ids[#ids] ---@type integer
local inner_id = ids[#ids] ---@type integer
local inner_inv = inner_id and projection.invocations[inner_id] ---@type InvocationRecord|nil
if inner_inv then
local component = component_index[inner_inv.component_name] ---@type ComponentBodyEntry|nil
@@ -191,7 +191,7 @@ local function stamp_root_provenance(projection, atom_record, src, corpus)
-- Stamp the root source path onto invocation records whose `call_path` the walker left empty.
-- The walker passes `body_entry.source` to `emit_invoke_begin`; `M.project_emission` creates the root `body_entry` with source `""`, leaving its `call_path` empty.
-- This stamp gives every invocation a physical `call_path` matching `passes/atoms_source_map.lua`'s in-memory provenance projection.
local root_path = src.path or "" ---@type string
local root_path = src.path or "" ---@type string
for _, inv in ipairs(projection.invocations) do ---@type integer, InvocationRecord
if inv.call_path == nil or inv.call_path == "" then
inv.call_path = root_path
@@ -212,9 +212,9 @@ local function stamp_root_provenance(projection, atom_record, src, corpus)
-- Component words already carry physical `item.line` values from the walker's COMPONENT line index, so `body_line_for` returns them unchanged.
for _, inv in ipairs(projection.invocations) do ---@type integer, InvocationRecord
local sw = inv.start_word ---@type integer
local ew = inv.end_word ---@type integer
local bls = {} ---@type integer[]
for i = sw, ew do ---@type integer
local ew = inv.end_word ---@type integer
local bls = {} ---@type integer[]
for i = sw, ew do ---@type integer
local it = projection.items and projection.items[i] ---@type EmissionItem|nil
if it and it.kind == "word" then
local fake_event = { invocation_ids = { inv.id } } ---@type WordEvent
@@ -233,8 +233,8 @@ local function stamp_root_provenance(projection, atom_record, src, corpus)
item.line = body_line
we.body_line = body_line
local call_line = body_line ---@type integer
local outer_id = we.outermost_invocation_id or 0 ---@type integer
local call_line = body_line ---@type integer
local outer_id = we.outermost_invocation_id or 0 ---@type integer
local outer_inv = projection.invocations[outer_id] ---@type InvocationRecord|nil
if outer_inv then
-- `outer_inv.call_line` is physical after the conversion loop above, so use it directly.
@@ -255,10 +255,10 @@ end
--- @param corpus Corpus
--- @return EmissionProjection
local function project_atom(atom_record, src, corpus)
local body = atom_record.body or "" ---@type string
local wc = corpus.word_counts or {} ---@type WordCounts
local body = atom_record.body or "" ---@type string
local wc = corpus.word_counts or {} ---@type WordCounts
local cbi = corpus.component_body_index or {} ---@type table<string, ComponentBodyEntry>
local schema = nil ---@type RegUseSchema|nil
local schema = nil ---@type RegUseSchema|nil
if atom_record.reg_use_schema_name then
schema = corpus.reg_use_schemas and corpus.reg_use_schemas[atom_record.reg_use_schema_name]
end
@@ -322,7 +322,7 @@ function M.run(ctx)
return
end
local proj = project_atom(atom, src, corpus) ---@type EmissionProjection
for _, e in ipairs(proj.errors) do ---@type integer, EmitError
for _, e in ipairs(proj.errors) do ---@type integer, EmitError
-- Preserve `kind` (cycle / count_mismatch / unbalanced) so readers dispatch on the diagnostic class and leave the message string as display text.
errors[#errors + 1] = {
kind = e.kind,
@@ -344,7 +344,7 @@ function M.run(ctx)
-- Recognized kinds (atom | atom_proc | raw_atom | comp_bare | comp_proc) each receive the atom.paths projection via duffle.project_emission.
-- Components are macros inlined into atom bodies; focused tests and isolated component analyses consume atom.paths directly.
for _, src in ipairs(corpus.source_order) do ---@type integer, SourceFile
local scan = src.scan or {} ---@type SourceScan
local scan = src.scan or {} ---@type SourceScan
for _, atom in ipairs(scan.atoms or {}) do ---@type integer, AtomEntry
process_atom(atom, src)
end
scripts/passes/offsets.lua
+8 -8
View File
@@ -21,7 +21,7 @@
-- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when require'd).
-- duffle_paths.lua sets package.path then returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
-- ════════════════════════════════════════════════════════════════════════════
-- Constants
@@ -29,7 +29,7 @@ local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type
-- Offset macro/enum naming prefixes (the emitted header uses these).
local OFFSET_MACRO_PREFIX = "_atom_offset_" ---@type string
local OFFSET_ENUM_PREFIX = "atom_offset_" ---@type string
local OFFSET_ENUM_PREFIX = "atom_offset_" ---@type string
-- Column width for the `#define _atom_offset_F_T = N` alignment.
local OFFSET_MACRO_COL = 44 ---@type integer
@@ -114,7 +114,7 @@ local MARKER_PROJECTORS = { ---@type table<string, fun(state: MarkerProjectState
--- @return OffsetBranch[]
local function project_markers(markers)
local state = { labels = {}, branches = {} } ---@type MarkerProjectState
for _, marker in ipairs(markers or {}) do ---@type integer, EmissionMarker
for _, marker in ipairs(markers or {}) do ---@type integer, EmissionMarker
local project = MARKER_PROJECTORS[marker.kind] ---@type (fun(state: MarkerProjectState, marker: EmissionMarker): nil)|nil
if project then project(state, marker) end
end
@@ -140,7 +140,7 @@ end
--- @param errors PassFinding[]
--- @return BranchOffset[]
local function compute_offsets(labels, branches, errors)
local results = {} ---@type BranchOffset[]
local results = {} ---@type BranchOffset[]
for _, br in ipairs(branches) do ---@type integer, OffsetBranch
local target = labels[br.target] ---@type integer|nil
if not target then
@@ -205,7 +205,7 @@ local function emit_atom_offsets(add, atom)
if #atom.offsets == 0 then return end
add("// --- atom: " .. atom.name .. " (" .. atom.total_words .. " words) ---")
add("")
local consts = {} ---@type OffsetConst[]
local consts = {} ---@type OffsetConst[]
for _, r in ipairs(atom.offsets) do ---@type integer, BranchOffset
consts[#consts + 1] = make_offset_const(r)
end
@@ -278,8 +278,8 @@ local function process_directory(ctx, dir, sources, errors)
end
for _, src in ipairs(sources) do ---@type integer, SourceFile
local scan = src.scan or {} ---@type SourceScan
for _, atom in ipairs(scan.atoms or {}) do append_atom(atom) end ---@type integer, AtomEntry
local scan = src.scan or {} ---@type SourceScan
for _, atom in ipairs(scan.atoms or {}) do append_atom(atom) end ---@type integer, AtomEntry
for _, atom in ipairs(scan.raw_atoms or {}) do append_atom(atom) end ---@type integer, AtomEntry
end
if #atoms_data == 0 then return nil end
@@ -310,7 +310,7 @@ function M.run(ctx)
-- Per-directory aggregation: every source in the same directory contributes to one `gen/offsets.h`.
local sources_by_dir = corpus.sources_by_dir or duffle.group_sources_by_dir(corpus.source_order) ---@type table<string, SourceFile[]>
for dir, sources in pairs(sources_by_dir) do ---@type string, SourceFile[]
for dir, sources in pairs(sources_by_dir) do ---@type string, SourceFile[]
local out_path = process_directory(ctx, dir, sources, errors) ---@type string|nil
if out_path then
outputs[#outputs + 1] = { offsets_h = out_path }
scripts/passes/report.lua
+69 -69
View File
@@ -19,7 +19,7 @@
-- Bootstrap: Load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when require'd).
-- duffle_paths.lua sets package.path then returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
-- Load atoms_source_map for the `render_source_map` / `render_provenance` module functions (used by `render_module_atoms_md` to produce `<module>.atoms.md` without re-walking source tokens).
-- The pass itself emits no per-source files anymore; we only consume the two pure renderers here.
@@ -32,13 +32,13 @@ local atoms_source_map = dofile(_bootstrap_dir .. "atoms_source_map.lua") ---@ty
-- Section separators used in the rendered text reports.
-- The thin rules are hand-tuned to align with the per-section content width; do not change without also checking the section renderers below.
local RULE_THICK = "========================================================" ---@type string
local RULE_THICK = "========================================================" ---@type string
local SECTION_HEADER_ATOMS = "── Atoms ────────────────────────────────────────────────" ---@type string
local SECTION_HEADER_ANNOTS = "── Annotations ──────────────────────────────────────────" ---@type string
local SECTION_HEADER_BINDS = "── Binds_* structs ──────────────────────────────────────" ---@type string
local SECTION_HEADER_MACROS = "── Macro word-count declarations ─────────────────────────" ---@type string
local SECTION_HEADER_ERRORS = "── Errors ──────────────────────────────────────────────" ---@type string
local SECTION_HEADER_WARNINGS = "── Warnings ────────────────────────────────────────────" ---@type string
local SECTION_HEADER_ANNOTS = "── Annotations ──────────────────────────────────────────" ---@type string
local SECTION_HEADER_BINDS = "── Binds_* structs ──────────────────────────────────────" ---@type string
local SECTION_HEADER_MACROS = "── Macro word-count declarations ─────────────────────────" ---@type string
local SECTION_HEADER_ERRORS = "── Errors ──────────────────────────────────────────────" ---@type string
local SECTION_HEADER_WARNINGS = "── Warnings ────────────────────────────────────────────" ---@type string
-- Lua pattern that captures the basename (last path segment) of a forward- or back-slash separated path.
local BASENAME_PATTERN = "([^/\\]+)$" ---@type string
@@ -240,7 +240,7 @@ local function render_project_summary(all_results)
"|--------|-------|--------|-------|--------|----------|--------|----------|------|",
}
local totals = { atoms = 0, annots = 0, binds = 0, macros = 0, findings = 0, errors = 0, warnings = 0, info = 0 } ---@type ProjectSummaryTotals
for _, e in ipairs(all_results) do ---@type integer, ProjectSummaryRow
for _, e in ipairs(all_results) do ---@type integer, ProjectSummaryRow
lines[#lines + 1] = string.format("| %s | %d | %d | %d | %d | %d | %d | %d | %d |"
, e.module, e.atoms, e.annots, e.binds, e.macros, e.findings, e.errors, e.warnings, e.info)
totals.atoms = totals.atoms + e.atoms
@@ -266,7 +266,7 @@ end
--- @return string
local function render_module_atoms_md(dir, dir_sources, wc)
local dir_basename = source_basename(dir) ---@type string
local lines = { ---@type string[]
local lines = { ---@type string[]
"# " .. dir_basename .. " — atoms (verbose source map)",
"> Per-word call-site + provenance. Auto-generated.",
"",
@@ -276,7 +276,7 @@ local function render_module_atoms_md(dir, dir_sources, wc)
lines[#lines + 1] = "## " .. src_name
lines[#lines + 1] = ""
-- For each atom with a projection, render its sourcemap + provenance.
local atoms_list = {} ---@type AtomEntry[]
local atoms_list = {} ---@type AtomEntry[]
for _, atom in ipairs((src.scan or {}).atoms or {}) do ---@type integer, AtomEntry
if atom.paths then atoms_list[#atoms_list + 1] = atom end
end
@@ -290,7 +290,7 @@ local function render_module_atoms_md(dir, dir_sources, wc)
-- Per-source forward-slash path (same one `emit_atom_stanza` / `emit_provenance_stanza` would derive;
-- computed once per `## <source>` heading and reused by each atom's `WORD N CALL ...` field).
local rel_path = src.path:gsub("\\\\", "/") ---@type string
for _, atom in ipairs(atoms_list) do ---@type integer, AtomEntry
for _, atom in ipairs(atoms_list) do ---@type integer, AtomEntry
lines[#lines + 1] = string.format(
"### atom: %s (line %d, %d words)",
atom.name, atom.line or 0, #((atom.paths or {}).word_events or {}))
@@ -325,7 +325,7 @@ end
--- @return KindCounts
local function count_kinds(decls)
local n = { atom = 0, atom_proc = 0, comp_bare = 0, comp_proc = 0 } ---@type KindCounts
for _, a in ipairs(decls or {}) do ---@type integer, AtomEntry
for _, a in ipairs(decls or {}) do ---@type integer, AtomEntry
if n[a.kind] ~= nil then n[a.kind] = n[a.kind] + 1 end
end
return n
@@ -341,7 +341,7 @@ end
--- @param view ModuleView
--- @return table<string, boolean>
local function decl_names(view)
local names = {} ---@type table<string, boolean> -- bag: atom name -> true
local names = {} ---@type table<string, boolean> -- bag: atom name -> true
for _, a in ipairs(view.decls or {}) do ---@type integer, AtomEntry
if a.name then names[a.name] = true end
end
@@ -353,7 +353,7 @@ end
--- @return boolean
local function path_in_module(path, view)
if type(path) ~= "string" or path == "" then return false end
local norm = path:gsub("\\", "/") ---@type string
local norm = path:gsub("\\", "/") ---@type string
local dir = (view.dir or ""):gsub("\\", "/") ---@type string
if dir ~= "" and (norm == dir or norm:sub(1, #dir + 1) == dir .. "/") then
return true
@@ -369,17 +369,17 @@ end
--- @param corpus Corpus
--- @return ModuleView
local function build_module_view(dir, dir_sources, corpus)
local decls = {} ---@type AtomEntry[]
local decls = {} ---@type AtomEntry[]
for _, src in ipairs(dir_sources or {}) do ---@type integer, SourceFile
for _, a in ipairs((src.scan and src.scan.atoms) or {}) do ---@type integer, AtomEntry
if not a.source_path then a.source_path = src.path end
decls[#decls + 1] = a
end
end
local dir_basename = source_basename(dir) ---@type string
local dir_basename = source_basename(dir) ---@type string
local sa = (corpus.static_analysis_results or {})[dir_basename] or {} ---@type AtomAnalysis
local schemas = {} ---@type RegUseSchema[]
for name, schema in pairs(corpus.reg_use_schemas or {}) do ---@type string, RegUseSchema
local schemas = {} ---@type RegUseSchema[]
for name, schema in pairs(corpus.reg_use_schemas or {}) do ---@type string, RegUseSchema
for _, a in ipairs(decls) do ---@type integer, AtomEntry
if a.reg_use_schema_name == name then
schemas[#schemas + 1] = schema
@@ -424,11 +424,11 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_components(add, view)
local rows = {} ---@type ComponentReportRow[]
local rows = {} ---@type ComponentReportRow[]
local index = (view.corpus and view.corpus.component_body_index) or {} ---@type table<string, ComponentBodyEntry>
for _, a in ipairs(view.decls) do ---@type integer, AtomEntry
for _, a in ipairs(view.decls) do ---@type integer, AtomEntry
if a.kind == "comp_bare" or a.kind == "comp_proc" then
local idx = index[a.name] or {} ---@type ComponentBodyEntry
local idx = index[a.name] or {} ---@type ComponentBodyEntry
local args = idx.arg_names or {} ---@type string[]
rows[#rows + 1] = {
name = a.name,
@@ -453,13 +453,13 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_reguse(add, view)
local wrote = false ---@type boolean
local wrote = false ---@type boolean
for _, schema in ipairs(view.schemas or {}) do ---@type integer, RegUseSchema
wrote = true
add(string.format("### %s", schema.name or "?"))
for _, slot in ipairs(schema.slots or {}) do ---@type integer, RegUseSlot
local aliases = table.concat(slot.aliases or { slot.name }, ", ") ---@type string
local ro = slot.readonly and " readonly" or "" ---@type string
local ro = slot.readonly and " readonly" or "" ---@type string
add(string.format("- slot `%s` aliases %s%s", slot.name, aliases, ro))
end
for _, a in ipairs(view.decls) do ---@type integer, AtomEntry
@@ -469,11 +469,11 @@ local function render_section_reguse(add, view)
end
add("")
end
local bound = {} ---@type table<string, boolean> -- bag: schema name -> true
local bound = {} ---@type table<string, boolean> -- bag: schema name -> true
for _, schema in ipairs(view.schemas or {}) do ---@type integer, RegUseSchema
if schema.name then bound[schema.name] = true end
end
local errors = {} ---@type RegUseError[]
local errors = {} ---@type RegUseError[]
for _, err in ipairs((view.corpus and view.corpus.reg_use_errors) or {}) do ---@type integer, RegUseError
if bound[err.schema_name] or path_in_module(err.source_file, view) then
errors[#errors + 1] = err
@@ -494,7 +494,7 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_annotations(add, view)
local rows = {} ---@type AnnotReportRow[]
local rows = {} ---@type AnnotReportRow[]
for _, src in ipairs(view.sources) do ---@type integer, SourceFile
for _, info in ipairs((src.scan and src.scan.atom_infos) or {}) do ---@type integer, AtomInfoEntry
rows[#rows + 1] = {
@@ -522,7 +522,7 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_component_annotations(add, view)
local rows = {} ---@type CompAnnotReportRow[]
local rows = {} ---@type CompAnnotReportRow[]
for _, src in ipairs(view.sources) do ---@type integer, SourceFile
for _, info in ipairs((src.scan and src.scan.component_atom_infos) or {}) do ---@type integer, AtomInfoEntry
rows[#rows + 1] = {
@@ -548,7 +548,7 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_binds(add, view)
local wrote = false ---@type boolean
local wrote = false ---@type boolean
for _, src in ipairs(view.sources) do ---@type integer, SourceFile
for _, b in ipairs((src.scan and src.scan.binds) or {}) do ---@type integer, BindsEntry
wrote = true
@@ -567,11 +567,11 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_phases(add, view)
local corpus = view.corpus or {} ---@type Corpus
local names = decl_names(view) ---@type table<string, boolean>
local wrote = false ---@type boolean
local corpus = view.corpus or {} ---@type Corpus
local names = decl_names(view) ---@type table<string, boolean>
local wrote = false ---@type boolean
for phase, entry in pairs(corpus.atom_phases or {}) do ---@type string, AtomPhaseGroup
local here = {} ---@type string[]
local here = {} ---@type string[]
for _, atom_name in ipairs(entry.atoms or {}) do ---@type integer, string
if names[atom_name] then here[#here + 1] = atom_name end
end
@@ -600,8 +600,8 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_aliases(add, view)
local names = {} ---@type string[]
local seen = {} ---@type table<string, AliasEntry>
local names = {} ---@type string[]
local seen = {} ---@type table<string, AliasEntry>
for _, src in ipairs(view.sources or {}) do ---@type integer, SourceFile
for name, entry in pairs((src.scan and src.scan.register_alias_registry) or {}) do ---@type string, AliasEntry
if not seen[name] then
@@ -625,19 +625,19 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_autoreg(add, view)
local allowed = decl_names(view) ---@type table<string, boolean>
local allowed = decl_names(view) ---@type table<string, boolean>
for phase, entry in pairs((view.corpus and view.corpus.atom_phases) or {}) do ---@type string, AtomPhaseGroup
for _, atom_name in ipairs(entry.atoms or {}) do ---@type integer, string
if allowed[atom_name] then allowed[phase] = true end
end
end
local wrote = false ---@type boolean
local seen = {} ---@type table<string, boolean> -- bag: label\\0scope -> already dumped
local seen = {} ---@type table<string, boolean> -- bag: label\\0scope -> already dumped
--- @param label string
--- @param table_map table<string, GprAllocMap>|nil
--- @return nil
local function dump(label, table_map)
local scopes = {} ---@type string[]
local scopes = {} ---@type string[]
for scope in pairs(table_map or {}) do ---@type string
if allowed[scope] and not seen[label .. "\0" .. scope] then
scopes[#scopes + 1] = scope
@@ -647,7 +647,7 @@ local function render_section_autoreg(add, view)
for _, scope in ipairs(scopes) do ---@type integer, string
seen[label .. "\0" .. scope] = true
wrote = true
local syms = {} ---@type string[]
local syms = {} ---@type string[]
for sym, gpr in pairs(table_map[scope] or {}) do ---@type string, string
if type(gpr) == "string" and gpr ~= sym then
syms[#syms + 1] = string.format("%s → %s", sym, gpr)
@@ -674,9 +674,9 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_collisions(add, view)
local rows = {} ---@type CorpusCollision[]
local rows = {} ---@type CorpusCollision[]
for _, c in ipairs((view.corpus and view.corpus.collisions) or {}) do ---@type integer, CorpusCollision
local first = c.first_site or {} ---@type CollisionSite
local first = c.first_site or {} ---@type CollisionSite
local other = c.conflicting_site or {} ---@type CollisionSite
if path_in_module(first.path, view) or path_in_module(other.path, view) then
rows[#rows + 1] = c
@@ -684,7 +684,7 @@ local function render_section_collisions(add, view)
end
if #rows == 0 then add("_(none)_"); add(""); return end
for _, c in ipairs(rows) do ---@type integer, CorpusCollision
local first = c.first_site or {} ---@type CollisionSite
local first = c.first_site or {} ---@type CollisionSite
local other = c.conflicting_site or {} ---@type CollisionSite
add(string.format("- `%s` `%s` first %s:%s conflict %s:%s",
c.kind or "?", c.name or "?",
@@ -698,7 +698,7 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_findings(add, view)
local by_atom = {} ---@type table<string, CheckFinding[]>
local by_atom = {} ---@type table<string, CheckFinding[]>
for _, f in ipairs(view.findings or {}) do ---@type integer, CheckFinding
local key = f.atom or "?" ---@type string
by_atom[key] = by_atom[key] or {}
@@ -712,7 +712,7 @@ local function render_section_findings(add, view)
local function emit(name, fs)
add("### " .. name)
for _, f in ipairs(fs) do ---@type integer, CheckFinding
local msg = f.msg or "" ---@type string
local msg = f.msg or "" ---@type string
local slot = slot_suffix(f.gpr_key or f.producer_destination) ---@type string|nil
if slot and not msg:find("(slot ", 1, true) then
msg = msg .. " (slot " .. slot .. ")"
@@ -727,7 +727,7 @@ local function render_section_findings(add, view)
emit(a.name, by_atom[a.name])
end
end
local leftovers = {} ---@type string[]
local leftovers = {} ---@type string[]
for name in pairs(by_atom) do ---@type string
if not seen[name] then leftovers[#leftovers + 1] = name end
end
@@ -739,7 +739,7 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_relations(add, view)
local wrote = false ---@type boolean
local wrote = false ---@type boolean
for _, a in ipairs(view.decls) do ---@type integer, AtomEntry
local rels = (a.paths and a.paths.relations) or {} ---@type AtomRelation[]
if #rels > 0 then
@@ -747,8 +747,8 @@ local function render_section_relations(add, view)
add("### " .. a.name)
for _, rel in ipairs(rels) do ---@type integer, AtomRelation
local dest = rel.destination or rel.producer_destination or "—" ---@type string
local slot = slot_suffix(dest) ---@type string|nil
local dest_s = tostring(dest) ---@type string
local slot = slot_suffix(dest) ---@type string|nil
local dest_s = tostring(dest) ---@type string
if slot then dest_s = dest_s .. " (slot " .. slot .. ")" end
add(string.format("- `%s` words %s → %s dest %s",
rel.semantic or "?",
@@ -804,12 +804,12 @@ end
local function aliases_for_key(key, atom, view)
local slot = key:match("^reguse:.+:(.+)$") ---@type string|nil
if not slot then return "—" end
local schema_name = atom.reg_use_schema_name ---@type string|nil
local schema_name = atom.reg_use_schema_name ---@type string|nil
local schema = view.corpus and view.corpus.reg_use_schemas and view.corpus.reg_use_schemas[schema_name] ---@type RegUseSchema|nil
if not schema then return "—" end
for _, s in ipairs(schema.slots or {}) do ---@type integer, RegUseSlot
if s.name == slot then
local names = {} ---@type string[]
local names = {} ---@type string[]
for _, alias in ipairs(s.aliases or {}) do ---@type integer, string
if alias ~= slot then names[#names + 1] = alias end
end
@@ -829,7 +829,7 @@ end
--- @return string
local function physical_for_key(key, atom, view)
if PHYSICAL_GPR[key] then return key end
local corpus = view.corpus or {} ---@type Corpus
local corpus = view.corpus or {} ---@type Corpus
local alias = (corpus.register_alias_registry or {})[key] ---@type AliasEntry|string|nil
if type(alias) == "table" then
local phys = alias.physical or alias.gpr or alias.code_name ---@type string|nil
@@ -840,7 +840,7 @@ local function physical_for_key(key, atom, view)
end
local atom_map = (corpus.atom_auto_regs or {})[atom.name] ---@type GprAllocMap|nil
if type(atom_map) == "table" then
local slot = key:match("^reguse:.+:(.+)$") or key ---@type string
local slot = key:match("^reguse:.+:(.+)$") or key ---@type string
local bound = atom_map[slot] or atom_map["R_" .. slot] ---@type string|nil
if type(bound) == "string" and PHYSICAL_GPR[bound] then return bound end
end
@@ -851,15 +851,15 @@ end
--- @param atom AtomEntry
--- @return string
local function last_relation_for(key, atom)
local last = nil ---@type AtomRelation|nil
local last = nil ---@type AtomRelation|nil
for _, rel in ipairs((atom.paths and atom.paths.relations) or {}) do ---@type integer, AtomRelation
local dest = rel.destination or rel.producer_destination ---@type string|nil
if dest == key then last = rel end
end
if not last then return "—" end
local sem = last.semantic or "?" ---@type string
local a = last.producer_word ---@type integer|nil
local b = last.consumer_word ---@type integer|nil
local a = last.producer_word ---@type integer|nil
local b = last.consumer_word ---@type integer|nil
if a and b then return string.format("%s w%s→%s", sem, tostring(a), tostring(b)) end
return sem
end
@@ -868,11 +868,11 @@ end
--- @param view ModuleView
--- @return nil
local function render_section_forward(add, view)
local wrote = false ---@type boolean
local wrote = false ---@type boolean
for _, a in ipairs(view.decls) do ---@type integer, AtomEntry
local gpr = a.paths and a.paths.forward_state and a.paths.forward_state.gpr_values ---@type table<string, GprLatticeSlot>|nil
local keys = {} ---@type string[]
for k in pairs(gpr or {}) do ---@type string
local keys = {} ---@type string[]
for k in pairs(gpr or {}) do ---@type string
if k == "R_0" then
-- hidden
elseif HIDDEN_UNLESS_WRITTEN[k] and not encoder_wrote_key(a, k) then
@@ -888,7 +888,7 @@ local function render_section_forward(add, view)
add("|---|---|---|---|---|")
table.sort(keys)
for _, k in ipairs(keys) do ---@type integer, string
local slot = gpr[k] ---@type GprLatticeSlot|nil
local slot = gpr[k] ---@type GprLatticeSlot|nil
local lattice = "—" ---@type string
if slot and slot.kind == "constant" then
lattice = tostring(slot.value)
@@ -928,7 +928,7 @@ local SECTION_RENDERERS = { ---@type SectionRenderer[]
--- @return string
local function render_module_meta_report(view)
local dir_basename = source_basename(view.dir) ---@type string
local lines = { ---@type string[]
local lines = { ---@type string[]
"# " .. dir_basename .. " — atom meta report",
"> Auto-generated by ps1_meta.lua (passes/report.lua). Do not edit.",
"",
@@ -937,14 +937,14 @@ local function render_module_meta_report(view)
--- @return nil
local function add(s) lines[#lines + 1] = s end
local kinds = count_kinds(view.decls) ---@type KindCounts
local kinds = count_kinds(view.decls) ---@type KindCounts
local n_annot, n_binds, n_macros = 0, 0, 0 ---@type integer, integer, integer
for _, src in ipairs(view.sources) do ---@type integer, SourceFile
for _, src in ipairs(view.sources) do ---@type integer, SourceFile
n_annot = n_annot + #((src.scan and src.scan.atom_infos) or {})
n_binds = n_binds + #((src.scan and src.scan.binds) or {})
n_macros = n_macros + #((src.scan and src.scan.macros) or {})
end
local n_err, n_warn, n_info = 0, 0, 0 ---@type integer, integer, integer
local n_err, n_warn, n_info = 0, 0, 0 ---@type integer, integer, integer
for _, f in ipairs(view.findings or {}) do ---@type integer, CheckFinding
if f.kind == "error" then n_err = n_err + 1
elseif f.kind == "warning" then n_warn = n_warn + 1
@@ -1044,8 +1044,8 @@ local M = {} ---@type ReportPass
--- @param ctx PassCtx
--- @return PassResult
function M.run(ctx)
local outputs = {} ---@type PassOutputEntry[]
local corpus = ctx.shared and ctx.shared.corpus ---@type Corpus|nil
local outputs = {} ---@type PassOutputEntry[]
local corpus = ctx.shared and ctx.shared.corpus ---@type Corpus|nil
local by_dir = (corpus and corpus.sources_by_dir) or {} ---@type table<string, SourceFile[]>
-- `out_path_root`: when the conventional `out_root` is `build/gen` (any spelling — relative, absolute, separator variants).
@@ -1072,7 +1072,7 @@ function M.run(ctx)
-- Per-renderer dispatch for the per-module renderers (once = false).
for _, renderer in ipairs(REPORT_RENDERERS) do ---@type integer, ReportRenderer
if not renderer.once then
local body = renderer.gather(ctx, dir, dir_sources) ---@type string
local body = renderer.gather(ctx, dir, dir_sources) ---@type string
local out_path = out_root_effective .. "/" .. renderer.basename(dir_basename) .. "." .. renderer.ext ---@type string
duffle.write_file(out_path, body)
outputs[#outputs + 1] = { kind = renderer.name, path = out_path }
@@ -1080,13 +1080,13 @@ function M.run(ctx)
end
local view = build_module_view(dir, dir_sources, corpus) ---@type ModuleView
local n_annot, n_binds, n_macros = 0, 0, 0 ---@type integer, integer, integer
for _, src in ipairs(dir_sources) do ---@type integer, SourceFile
local n_annot, n_binds, n_macros = 0, 0, 0 ---@type integer, integer, integer
for _, src in ipairs(dir_sources) do ---@type integer, SourceFile
n_annot = n_annot + #((src.scan and src.scan.atom_infos) or {})
n_binds = n_binds + #((src.scan and src.scan.binds) or {})
n_macros = n_macros + #((src.scan and src.scan.macros) or {})
end
local n_err, n_warn, n_info = 0, 0, 0 ---@type integer, integer, integer
local n_err, n_warn, n_info = 0, 0, 0 ---@type integer, integer, integer
for _, f in ipairs(view.findings or {}) do ---@type integer, CheckFinding
if f.kind == "error" then n_err = n_err + 1
elseif f.kind == "warning" then n_warn = n_warn + 1
@@ -1109,7 +1109,7 @@ function M.run(ctx)
-- Project-wide renderer (once = true): write the summary file.
for _, renderer in ipairs(REPORT_RENDERERS) do ---@type integer, ReportRenderer
if renderer.once then
local body = renderer.gather(ctx, nil, nil, all_modules) ---@type string
local body = renderer.gather(ctx, nil, nil, all_modules) ---@type string
local out_path = out_root_effective .. "/" .. renderer.basename("") .. "." .. renderer.ext ---@type string
duffle.write_file(out_path, body)
outputs[#outputs + 1] = { kind = renderer.name, path = out_path }
scripts/passes/scan_source.lua
+150 -150
View File
@@ -22,7 +22,7 @@
-- Bootstrap: load `duffle_paths.lua` via `debug.getinfo(1, "S").source` (works both standalone + when required).
-- duffle_paths.lua sets package.path then returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
-- Forward declarations for helpers used by earlier parsers (parse_enum_body_fields needs parse_enum_int_literal;
-- parse_typedef_binds needs duffle.find_byte).
@@ -271,16 +271,16 @@ local QUALIFIER_KEYWORDS = { ---@type table<string, boolean> -- bag: C qualifie
-- "ac_" prefix length on component names (e.g., `MipsAtomComp_(ac_X, ...)`).
-- The components pass strips this prefix to derive the macro name (e.g., `mac_X`).
local AC_PREFIX = "ac_" ---@type string
local AC_PREFIX_LEN = 3 ---@type integer
local AC_PREFIX_LEN = 3 ---@type integer
-- The function-decl keyword that precedes a MipsAtomComp_Proc_ call.
-- Used by the backward walk in duffle.find_function_decl_for.
local SLICE_MIPS_CODE = "Slice_MipsCode" ---@type string
local SLICE_MIPS_CODE = "Slice_MipsCode" ---@type string
local SLICE_MIPS_CODE_LEN = #SLICE_MIPS_CODE ---@type integer
-- The return type that precedes a MipsAtom_Proc_ function declaration.
-- Used by the backward walk in duffle.find_atom_proc_decl_for.
local MIPS_ATOM_PTR = "MipsAtom*" ---@type string
local MIPS_ATOM_PTR = "MipsAtom*" ---@type string
local MIPS_ATOM_PTR_LEN = #MIPS_ATOM_PTR ---@type integer
--- Strip the "ac_" prefix from a component name.
@@ -302,7 +302,7 @@ end
--- @return nil
local function push_debug_skip_marker(out, marker)
local markers = out.debug_skip_markers ---@type DebugSkipMarker[]
local prior = markers[#markers] ---@type DebugSkipMarker
local prior = markers[#markers] ---@type DebugSkipMarker
if prior and prior.pending then
prior.pending = false
prior.superseded_by_marker_line = marker.marker_line
@@ -353,7 +353,7 @@ end
--- @param start_pos integer -- exclusive upper bound for the captured block
--- @return string
local function preceding_comment_walk_backward(source, start_pos)
local pieces = {} ---@type string[]
local pieces = {} ---@type string[]
local scan_pos = start_pos ---@type integer
while scan_pos > 0 do
local non_ws = scan_pos - 1 ---@type integer
@@ -370,8 +370,8 @@ local function preceding_comment_walk_backward(source, start_pos)
if non_ws >= 2 and source:sub(non_ws - 1, non_ws) == "*/" then
-- Block comment close: walk back over `/*` candidates.
local prefix = source:sub(1, non_ws - 1) ---@type string
local open_at = nil ---@type integer
for scan = #prefix - 1, 1, -1 do ---@type integer
local open_at = nil ---@type integer
for scan = #prefix - 1, 1, -1 do ---@type integer
if prefix:sub(scan, scan + 1) == "/*" then
open_at = scan
break
@@ -430,7 +430,7 @@ end
--- @return boolean|nil -- true iff the marker is the positive bare form
local function attach_debug_skip_marker(out, target_kind)
local markers = out.debug_skip_markers ---@type DebugSkipMarker[]
local marker = markers[#markers] ---@type DebugSkipMarker
local marker = markers[#markers] ---@type DebugSkipMarker
if not (marker and marker.pending) then return nil end
marker.pending = false
@@ -459,13 +459,13 @@ end
local function register_atom(out, kind, declaration_line, name, body, body_off, raw_name, pos, after_paren, source)
-- Capture the pending marker BEFORE attaching so the walker can anchor the backward comment walk on the marker's marker_pos
-- (which is the correct anchor even when an `FI_ MipsAtom ac_X(args)` proc-prelude separates the marker from the declaration).
local pending_marker = nil ---@type DebugSkipMarker|nil
local pending_marker = nil ---@type DebugSkipMarker|nil
local markers = out.debug_skip_markers ---@type DebugSkipMarker[]
local m = markers[#markers] ---@type DebugSkipMarker
local m = markers[#markers] ---@type DebugSkipMarker
if m and m.pending then pending_marker = m end
local positive = attach_debug_skip_marker(out, kind) ---@type boolean|nil
local comment = "" ---@type string
local comment = "" ---@type string
if kind == "comp_bare" or kind == "comp_proc" then
-- Scanner-owned declaration-comment attachment.
-- The walker does not need to detect marker shape.
@@ -513,9 +513,9 @@ local function parse_type_chain(text, pos)
if pos > #text then return nil end
-- Skip leading whitespace before the type ident.
local start = duffle.skip_ws_and_cmt(text, pos) ---@type integer
local ident, after = duffle.read_ident(text, start) ---@type string|nil, integer
local ident, after = duffle.read_ident(text, start) ---@type string|nil, integer
if not ident then return nil end
local depth = 0 ---@type integer
local depth = 0 ---@type integer
local cursor = duffle.skip_ws_and_cmt(text, after) ---@type integer
while cursor <= #text and text:sub(cursor, cursor) == "*" do
depth = depth + 1
@@ -564,8 +564,8 @@ local TYPE_CHAIN_MAX_DEPTH = 8 ---@type integer
--- @param build_field fun(first: string, first_end: integer, after_first: integer): (TypeField|nil, integer)
--- @return TypeField[]
local function walk_body_fields(body, build_field)
local fields = {} ---@type TypeField[]
local body_pos = 1 ---@type integer
local fields = {} ---@type TypeField[]
local body_pos = 1 ---@type integer
local body_len = #body ---@type integer
while body_pos <= body_len do
body_pos = duffle.skip_ws_and_cmt(body, body_pos)
@@ -574,7 +574,7 @@ local function walk_body_fields(body, build_field)
if not first then
body_pos = body_pos + 1
else
local after_first = duffle.skip_ws_and_cmt(body, first_end) ---@type integer
local after_first = duffle.skip_ws_and_cmt(body, first_end) ---@type integer
local result, new_pos = build_field(first, first_end, after_first) ---@type TypeField|nil, integer
if result then fields[#fields + 1] = result end
body_pos = new_pos or first_end
@@ -595,8 +595,8 @@ end
--- @param body string
--- @return TypeField[]
local function parse_struct_body_fields(body)
local fields = {} ---@type TypeField[]
local body_pos = 1 ---@type integer
local fields = {} ---@type TypeField[]
local body_pos = 1 ---@type integer
local body_len = #body ---@type integer
while body_pos <= body_len do
body_pos = duffle.skip_ws_and_cmt(body, body_pos)
@@ -647,11 +647,11 @@ local function parse_enum_body_fields(body)
--- @param after_name integer
--- @return TypeField, integer
return walk_body_fields(body, function(entry_name, name_end, after_name)
local value ---@type integer|nil
local value ---@type integer|nil
local new_pos ---@type integer
if body:sub(after_name, after_name) == "=" then
local val_pos = duffle.skip_ws_and_cmt(body, after_name + 1) ---@type integer
local v, end_pos = parse_enum_int_literal(body, val_pos) ---@type integer|nil, integer
local v, end_pos = parse_enum_int_literal(body, val_pos) ---@type integer|nil, integer
if v ~= nil then
value = v
new_pos = end_pos
@@ -696,8 +696,8 @@ local function resolve_typedef_byte_size(type_name, type_name_registry, visited,
-- Struct_ entries with unresolved byte_size can still resolve when their fields are all resolved.
if entry.kind == "struct" and entry.fields then
local sum = 0 ---@type integer
local all_have = true ---@type boolean
local sum = 0 ---@type integer
local all_have = true ---@type boolean
for _, f in ipairs(entry.fields) do ---@type integer, TypeField
if f.byte_size == nil then all_have = false; break end
sum = sum + f.byte_size
@@ -730,7 +730,7 @@ local function propagate_type_sizes(out)
-- The visited map is empty when handed to the resolver.
-- The resolver marks visited as it enters each node, so the cycle guard fires only on RECURSIVE re-entry (not on the initial call).
for _ = 1, TYPE_CHAIN_MAX_DEPTH do ---@type integer
local any_change = false ---@type boolean
local any_change = false ---@type boolean
for name, entry in pairs(reg) do ---@type string, TypeNameEntry
if entry.byte_size == nil then
local resolved = resolve_typedef_byte_size(name, reg, {}, 1) ---@type integer
@@ -747,23 +747,23 @@ local function propagate_type_sizes(out)
-- Iterate to a fixed point: struct A may reference struct B which hasn't been resolved yet on the first pass.
-- Each pass updates as many fields + aggregates as possible; the loop terminates when no struct's byte_size changes between passes.
for _ = 1, TYPE_CHAIN_MAX_DEPTH do ---@type integer
local any_change = false ---@type boolean
local any_change = false ---@type boolean
for _, entry in pairs(reg) do ---@type string, TypeNameEntry
if entry.kind == "array" and entry.byte_size == nil and entry.counts then
local elem_size = BUILTIN_BYTE_SIZES[entry.elem] ---@type integer
or (reg[entry.elem] and reg[entry.elem].byte_size)
if elem_size then
local n = 1 ---@type integer
local n = 1 ---@type integer
for _, c in ipairs(entry.counts) do n = n * c end ---@type integer, string
entry.byte_size = elem_size * n
any_change = true
end
end
if entry.kind == "struct" and entry.fields then
local byte_off = 0 ---@type integer
local gap_seen = false ---@type boolean
local sum = 0 ---@type integer
local all_have = true ---@type boolean
local byte_off = 0 ---@type integer
local gap_seen = false ---@type boolean
local sum = 0 ---@type integer
local all_have = true ---@type boolean
for _, f in ipairs(entry.fields) do ---@type integer, TypeField
-- Resolve field byte_size (pointer / builtin / typedef chain).
if f.byte_size == nil then
@@ -817,7 +817,7 @@ end
--- @param sub_inner string
--- @return string[]
local function scan_reg_list(sub_inner)
local regs = {} ---@type string[]
local regs = {} ---@type string[]
local sub_inner_pos = 1 ---@type integer
while sub_inner_pos <= #sub_inner do
sub_inner_pos = duffle.skip_ws_and_cmt(sub_inner, sub_inner_pos)
@@ -904,8 +904,8 @@ end
--- @return string|nil, string[]|nil, string[]|nil, string|nil, table<string, RegTypeOverride>|nil, string|nil, string|nil
local function scan_atom_info_subcalls(info_inner, info_line)
local binds, reads, writes = nil, nil, nil ---@type string|nil, string[]|nil, string[]|nil
local view_binds, reg_overrides = nil, nil ---@type string|nil, table<string, RegTypeOverride>|nil
local ctx_atom_name, phase_label = nil, nil ---@type string|nil, string|nil
local view_binds, reg_overrides = nil, nil ---@type string|nil, table<string, RegTypeOverride>|nil
local ctx_atom_name, phase_label = nil, nil ---@type string|nil, string|nil
-- Per-subcall handler table. Each handler takes (sub_inner, info_line) and mutates the outer locals above.
-- atom_reads/atom_writes share a handler (same shape; just different output target).
@@ -917,8 +917,8 @@ local function scan_atom_info_subcalls(info_inner, info_line)
-- reads/writes arrays contain ONLY register idents;
-- `atom_type(...)` sub-entry (when present and well-formed) is recorded as a per-atom reg_type_override.
local entries = duffle.split_top_level_commas(sub_inner) ---@type string[]
local regs = {} ---@type string[]
for _, entry in ipairs(entries) do ---@type integer, string
local regs = {} ---@type string[]
for _, entry in ipairs(entries) do ---@type integer, string
local reg_name, override, malformed = parse_atom_info_reg_entry(entry) ---@type string|nil, AtomInfoOverride|nil, boolean
if reg_name then
regs[#regs + 1] = reg_name
@@ -960,7 +960,7 @@ local function scan_atom_info_subcalls(info_inner, info_line)
if not args[1] then return end
reg_overrides = reg_overrides or {}
local reg_name = duffle.trim(args[1]) ---@type string
local type_name, depth = nil, 0 ---@type string|nil, integer
local type_name, depth = nil, 0 ---@type string|nil, integer
if args[2] then
local parsed_name, parsed_depth = parse_type_chain(args[2], 1) ---@type string|nil, integer
if parsed_name then
@@ -1013,7 +1013,7 @@ local function scan_atom_info_subcalls(info_inner, info_line)
local sub_open = duffle.skip_ws_and_cmt(info_inner, sub_end) ---@type integer
if info_inner:sub(sub_open, sub_open) == "(" then
local sub_inner, sub_after2 = duffle.read_parens(info_inner, sub_open) ---@type string|nil, integer
local handler = SUBCALL_HANDLERS[sub_ident] ---@type fun(sub_inner: string, info_line: integer|nil): nil|nil
local handler = SUBCALL_HANDLERS[sub_ident] ---@type fun(sub_inner: string, info_line: integer|nil): nil|nil
if handler then handler(sub_inner, info_line) end
sub_pos = sub_after2
else
@@ -1046,29 +1046,29 @@ end
-- symbol references resolve via the cross-source `_code_macros` registry built in two passes by `M.run`.
-- Byte constants (local to this file).
local BYTE_HASH = 0x23 ---@type integer -- '#'
local BYTE_NEWLINE = 0x0A ---@type integer -- '\n'
local BYTE_DASH = 0x2D ---@type integer -- '-'
local BYTE_COMMA = 0x2C ---@type integer -- ','
local BYTE_SEMI = 0x3B ---@type integer -- ';'
local BYTE_EQUAL = 0x3D ---@type integer -- '='
local BYTE_R = 0x52 ---@type integer -- 'R'
local BYTE_UNDERSCORE = 0x5F ---@type integer -- '_'
local BYTE_0 = 0x30 ---@type integer -- '0'
local BYTE_9 = 0x39 ---@type integer -- '9'
local BYTE_a = 0x61 ---@type integer -- 'a'
local BYTE_f = 0x66 ---@type integer -- 'f'
local BYTE_A = 0x41 ---@type integer -- 'A'
local BYTE_F = 0x46 ---@type integer -- 'F'
local BYTE_x = 0x78 ---@type integer -- 'x'
local BYTE_X = 0x58 ---@type integer -- 'X'
local BYTE_OPEN_BRACE = 0x7B ---@type integer -- '{'
local BYTE_CLOSE_BRACE= 0x7D ---@type integer -- '}'
local BYTE_SLASH = 0x2F ---@type integer -- '/'
local BYTE_STAR = 0x2A ---@type integer -- '*'
local BYTE_SPACE = 0x20 ---@type integer -- ' '
local BYTE_TAB = 0x09 ---@type integer -- '\t'
local BYTE_CR = 0x0D ---@type integer -- '\r'
local BYTE_HASH = 0x23 ---@type integer -- '#'
local BYTE_NEWLINE = 0x0A ---@type integer -- '\n'
local BYTE_DASH = 0x2D ---@type integer -- '-'
local BYTE_COMMA = 0x2C ---@type integer -- ','
local BYTE_SEMI = 0x3B ---@type integer -- ';'
local BYTE_EQUAL = 0x3D ---@type integer -- '='
local BYTE_R = 0x52 ---@type integer -- 'R'
local BYTE_UNDERSCORE = 0x5F ---@type integer -- '_'
local BYTE_0 = 0x30 ---@type integer -- '0'
local BYTE_9 = 0x39 ---@type integer -- '9'
local BYTE_a = 0x61 ---@type integer -- 'a'
local BYTE_f = 0x66 ---@type integer -- 'f'
local BYTE_A = 0x41 ---@type integer -- 'A'
local BYTE_F = 0x46 ---@type integer -- 'F'
local BYTE_x = 0x78 ---@type integer -- 'x'
local BYTE_X = 0x58 ---@type integer -- 'X'
local BYTE_OPEN_BRACE = 0x7B ---@type integer -- '{'
local BYTE_CLOSE_BRACE= 0x7D ---@type integer -- '}'
local BYTE_SLASH = 0x2F ---@type integer -- '/'
local BYTE_STAR = 0x2A ---@type integer -- '*'
local BYTE_SPACE = 0x20 ---@type integer -- ' '
local BYTE_TAB = 0x09 ---@type integer -- '\t'
local BYTE_CR = 0x0D ---@type integer -- '\r'
-- Maximum chain depth when resolving `R_*_Code` symbol RHS references.
-- Eight hops is enough for any production chain (R_TapePtr_Code -> R_T8_Code -> ...).
@@ -1164,7 +1164,7 @@ parse_enum_int_literal = function(text, start)
local peek = text:byte(pos + 1) ---@type integer
if peek == BYTE_x or peek == BYTE_X then
pos = pos + 2
local value = 0 ---@type integer|nil
local value = 0 ---@type integer|nil
local has_digit = false ---@type boolean
while pos <= len do
local d = hex_digit_value(text:byte(pos)) ---@type integer|nil
@@ -1286,25 +1286,25 @@ end
--- @return nil
local function try_extract_code_macro(source, directive_start, code_macros, code_macro_bodies)
local rest = duffle.skip_ws_and_cmt(source, directive_start + 1) ---@type integer
local kw, kw_end = duffle.read_ident(source, rest) ---@type string|nil, integer
local kw, kw_end = duffle.read_ident(source, rest) ---@type string|nil, integer
if kw ~= "define" then return end
local after_kw = duffle.skip_ws_and_cmt(source, kw_end) ---@type integer
local macro_name, macro_end = duffle.read_ident(source, after_kw) ---@type string|nil, integer
local macro_name, macro_end = duffle.read_ident(source, after_kw) ---@type string|nil, integer
if not macro_name then return end
if not is_r_code_macro(macro_name) then return end
-- Save the raw RHS (post-`=` text up to the line end) into the cross-source body table
-- FIRST so the chain walker can fall back to it when the defining `#define` lives in a different source.
local rhs_pos = duffle.skip_ws_and_cmt(source, macro_end) ---@type integer
local rhs_pos = duffle.skip_ws_and_cmt(source, macro_end) ---@type integer
local rhs_end = duffle.find_byte(source, BYTE_NEWLINE, rhs_pos) or (#source + 1) ---@type integer|nil
local rhs_text = duffle.trim(source:sub(rhs_pos, rhs_end - 1)) ---@type string
local rhs_text = duffle.trim(source:sub(rhs_pos, rhs_end - 1)) ---@type string
if rhs_text ~= "" then
code_macro_bodies[macro_name] = rhs_text
end
-- Resolve RHS via per-chain visited + depth-bounded recursion.
local visited = { [macro_name] = true } ---@type table<string, boolean> -- bag: already-walked ident -> true
local visited = { [macro_name] = true } ---@type table<string, boolean> -- bag: already-walked ident -> true
local value = resolve_code_macro_value(source, rhs_pos, code_macros, code_macro_bodies, visited, 1) ---@type integer|nil
if value ~= nil then code_macros[macro_name] = value end
end
@@ -1318,7 +1318,7 @@ end
--- @param code_macro_bodies table<string, string> -- bag: R_*_Code -> raw RHS text
--- @return nil
local function scan_source_pre_pass(source, code_macros, code_macro_bodies)
local pos = 1 ---@type integer
local pos = 1 ---@type integer
local src_len = #source ---@type integer
while pos <= src_len do
pos = duffle.skip_ws_and_cmt(source, pos)
@@ -1443,10 +1443,10 @@ local function parse_dbg_skip_marker(source, pos, ident_end, line_of, out)
-- Diagnostic-only detection of an invalid following `(...)`.
-- The cursor is advanced past the `()` either way to keep token order coherent for the next scan iteration.
local marker_end = ident_end ---@type integer
local marker_end = ident_end ---@type integer
local open_paren = duffle.skip_ws_and_cmt(source, ident_end) ---@type integer
local has_parens = false ---@type boolean
local args = nil ---@type string[]
local has_parens = false ---@type boolean
local args = nil ---@type string[]
if source:sub(open_paren, open_paren) == "(" then
local inner, after_paren = duffle.read_parens(source, open_paren) ---@type string|nil, integer
marker_end = after_paren
@@ -1479,13 +1479,13 @@ end
--- @param out SourceScan
--- @return integer
local function parse_auto_reg_marker(source, pos, ident_end, line_of, out)
local marker_kind = source:sub(pos, ident_end - 1) ---@type string -- "atom_auto_reg" or "phase_auto_reg"
local marker_kind = source:sub(pos, ident_end - 1) ---@type string -- "atom_auto_reg" or "phase_auto_reg"
local scope_kind = marker_kind == "atom_auto_reg" and "atom" or "phase" ---@type string
local inner, after_paren = read_parens_after(source, ident_end) ---@type string|nil, integer
if not inner then return after_paren end
local args = duffle.split_top_level_commas(inner) ---@type string[]
local args = duffle.split_top_level_commas(inner) ---@type string[]
local scope_name = args[1] and duffle.trim(args[1]) or nil ---@type string
local sym = args[2] and duffle.trim(args[2]) or nil ---@type string
@@ -1521,8 +1521,8 @@ local function parse_atom_dbg_reg_default(source, pos, ident_end, line_of, out)
-- Annotation pass surfaces this; we still consume the marker.
return after_paren
end
local reg_name = duffle.trim(args[1]) ---@type string
local type_part = args[2] or "void" ---@type string
local reg_name = duffle.trim(args[1]) ---@type string
local type_part = args[2] or "void" ---@type string
local type_name, depth = parse_type_chain(type_part, 1) ---@type string|nil, integer
if not type_name then type_name, depth = duffle.trim(type_part), 0 end
out.types[reg_name] = {
@@ -1551,13 +1551,13 @@ end
--- @return integer
local function parse_atom_info_after_decl(source, after_paren, raw_name, line_of, out, dest)
local lookahead = duffle.skip_ws_and_cmt(source, after_paren) ---@type integer
local look_ident, look_end = duffle.read_ident(source, lookahead) ---@type string|nil, integer
local look_ident, look_end = duffle.read_ident(source, lookahead) ---@type string|nil, integer
if look_ident ~= "atom_info" then return after_paren end
local info_open = duffle.skip_ws_and_cmt(source, look_end) ---@type integer
if source:sub(info_open, info_open) ~= "(" then return after_paren end
local info_inner, info_after = duffle.read_parens(source, info_open) ---@type string|nil, integer
if not info_inner then return after_paren end
local info_line = line_of(info_open) ---@type integer
local info_line = line_of(info_open) ---@type integer
local ai_binds, ai_reads, ai_writes, ai_view, ai_overrides, ai_ctx, ai_phase = scan_atom_info_subcalls(info_inner, info_line) ---@type string|nil, string[]|nil, string[]|nil, string|nil, table<string, RegTypeOverride>|nil, string|nil, string|nil
dest = dest or out.atom_infos
dest[#dest + 1] = {
@@ -1638,7 +1638,7 @@ local DECL_FORMS = { ---@type table<string, DeclForm>
--- @param open_paren integer
--- @return string|nil, integer|nil
local function last_brace_body(inner, open_paren)
local last_brace_pos = nil ---@type integer
local last_brace_pos = nil ---@type integer
for search_pos = #inner, 1, -1 do ---@type integer
if inner:sub(search_pos, search_pos) == "{" then
last_brace_pos = search_pos
@@ -1663,8 +1663,8 @@ local function reguse_hook(source, pos, line_of, out, extras)
local reg_use_schema_name, reg_use_param_name ---@type string|nil, string|nil
if extras.args_inner then
local arg_tokens = duffle.split_top_level_commas(extras.args_inner) ---@type string[]
for _, tok in ipairs(arg_tokens) do ---@type integer, string
local trimmed = duffle.trim(tok) ---@type string
for _, tok in ipairs(arg_tokens) do ---@type integer, string
local trimmed = duffle.trim(tok) ---@type string
local schema_suffix, param = trimmed:match("RegUse_([%w_]+)%s+([%w_]+)$") ---@type string, string
if schema_suffix then
if reg_use_schema_name then
@@ -1703,14 +1703,14 @@ end
--- @return integer
local function parse_decl_form(source, pos, ident_end, line_of, out)
local ident = duffle.read_ident(source, pos) ---@type string|nil
local form = ident and DECL_FORMS[ident] ---@type DeclForm|nil
local form = ident and DECL_FORMS[ident] ---@type DeclForm|nil
if not form then return ident_end end
local inner, after_paren, open_paren = read_parens_after(source, ident_end) ---@type string|nil, integer, integer
if not inner then return after_paren end
local extras = {} ---@type DeclExtras
local raw_name ---@type string
local raw_name ---@type string
if form.name == "paren_ident" then
raw_name = duffle.read_ident(inner, 1)
if form.strip and not raw_name then return open_paren + 1 end
@@ -1787,12 +1787,12 @@ end
--- @return integer
local function parse_mips_code(source, pos, ident_end, line_of, out)
local next_pos = duffle.skip_ws_and_cmt(source, ident_end) ---@type integer
local next_ident, next_after = duffle.read_ident(source, next_pos) ---@type string|nil, integer
local next_ident, next_after = duffle.read_ident(source, next_pos) ---@type string|nil, integer
if not next_ident or #next_ident <= 5 or next_ident:sub(1, 5) ~= "code_" then
return ident_end
end
local atom_name = next_ident:sub(6) ---@type string
local atom_name = next_ident:sub(6) ---@type string
local body, after_brace, body_off = find_body_braces(source, next_after, ident_end) ---@type string|nil, integer, integer
if not body then return after_brace end
register_raw_atom(out, line_of(pos), atom_name, body, body_off, atom_name, pos)
@@ -1820,7 +1820,7 @@ end
--- @return nil
local function register_struct_type(body, name, pos, line_of, out)
local fields = parse_struct_body_fields(body) ---@type TypeField[]
local source_pos = line_of(pos) ---@type integer
local source_pos = line_of(pos) ---@type integer
out.type_name_registry[name] = {
name = name,
kind = "struct",
@@ -1911,10 +1911,10 @@ local parse_reg_use_schema_body ---@type fun(body: string, type_registry: table<
--- @param type_registry table<string, TypeNameEntry>|nil
--- @return string[]|nil
local function fields_for_reg_type(type_name, type_registry)
local reg_name = "Reg_" .. type_name ---@type string
local reg_name = "Reg_" .. type_name ---@type string
local entry = type_registry and type_registry[reg_name] ---@type TypeNameEntry|nil
if entry and entry.fields and #entry.fields > 0 then
local names = {} ---@type string[]
local names = {} ---@type string[]
for _, field in ipairs(entry.fields) do ---@type integer, TypeField
if field.name then names[#names + 1] = field.name end
end
@@ -1923,7 +1923,7 @@ local function fields_for_reg_type(type_name, type_registry)
if entry and entry.body and parse_reg_use_schema_body then
local schema = parse_reg_use_schema_body(entry.body, type_registry) ---@type RegUseSchema|nil
if schema and schema.slots then
local names = {} ---@type string[]
local names = {} ---@type string[]
for _, slot in ipairs(schema.slots) do ---@type integer, RegUseSlot
if slot.name then names[#names + 1] = slot.name end
end
@@ -1940,11 +1940,11 @@ end
parse_reg_use_schema_body = function(body, type_registry, opts)
opts = opts or {}
local require_types = opts.require_types == true ---@type boolean
local pending = false ---@type boolean
local slots = {} ---@type RegUseSlot[]
local alias_to_slot = {} ---@type table<string, string> -- bag: alias path -> slot name
local slot_names = {} ---@type table<string, boolean> -- bag: slot name -> true
local errors = {} ---@type RegUseError[]
local pending = false ---@type boolean
local slots = {} ---@type RegUseSlot[]
local alias_to_slot = {} ---@type table<string, string> -- bag: alias path -> slot name
local slot_names = {} ---@type table<string, boolean> -- bag: slot name -> true
local errors = {} ---@type RegUseError[]
--- @param path string
--- @param slot string
@@ -2017,9 +2017,9 @@ parse_reg_use_schema_body = function(body, type_registry, opts)
errors[#errors + 1] = { kind = "reguse_malformed" }
return nil, errors
end
local views = {} ---@type RegUseView[]
local views = {} ---@type RegUseView[]
local union_readonly = nil ---@type boolean
local inner_pos = 1 ---@type integer
local inner_pos = 1 ---@type integer
--- @param flag boolean
--- @return boolean
@@ -2073,7 +2073,7 @@ parse_reg_use_schema_body = function(body, type_registry, opts)
pending = true
else
for _, inst in ipairs(inst_names) do ---@type integer, string
local names = {} ---@type string[]
local names = {} ---@type string[]
for _, field in ipairs(typed_fields) do ---@type integer, string
names[#names + 1] = inst .. "." .. field
end
@@ -2102,7 +2102,7 @@ parse_reg_use_schema_body = function(body, type_registry, opts)
return nil, errors
end
local lane_names = {} ---@type string[]
local s_pos = 1 ---@type integer
local s_pos = 1 ---@type integer
while s_pos <= #struct_inner do
s_pos = duffle.skip_ws_and_cmt(struct_inner, s_pos)
if s_pos > #struct_inner then break end
@@ -2145,8 +2145,8 @@ parse_reg_use_schema_body = function(body, type_registry, opts)
end
s_pos = new_s
elseif s_ty == "Reg" then
local s_after = duffle.skip_ws_and_cmt(struct_inner, s_ty_end) ---@type integer
local s_readonly = false ---@type boolean
local s_after = duffle.skip_ws_and_cmt(struct_inner, s_ty_end) ---@type integer
local s_readonly = false ---@type boolean
local maybe_const, maybe_end = duffle.read_ident(struct_inner, s_after) ---@type string|nil, integer
if maybe_const == "const" then
s_readonly = true
@@ -2177,8 +2177,8 @@ parse_reg_use_schema_body = function(body, type_registry, opts)
if inner:sub(inner_pos, inner_pos) == ";" then inner_pos = inner_pos + 1 end
elseif m_type == "Reg" then
local m_after = duffle.skip_ws_and_cmt(inner, m_type_end) ---@type integer
local m_readonly = false ---@type boolean
local m_after = duffle.skip_ws_and_cmt(inner, m_type_end) ---@type integer
local m_readonly = false ---@type boolean
local maybe_const, maybe_end = duffle.read_ident(inner, m_after) ---@type string|nil, integer
if maybe_const == "const" then
m_readonly = true
@@ -2200,7 +2200,7 @@ parse_reg_use_schema_body = function(body, type_registry, opts)
end
local after_close = duffle.skip_ws_and_cmt(body, after_braces) ---@type integer
local inst_name, inst_end = duffle.read_ident(body, after_close) ---@type string|nil, integer
local inst_name, inst_end = duffle.read_ident(body, after_close) ---@type string|nil, integer
if #views == 0 then
if not pending then
@@ -2208,13 +2208,13 @@ parse_reg_use_schema_body = function(body, type_registry, opts)
return nil, errors
end
else
local has_lanes = false ---@type boolean
local has_lanes = false ---@type boolean
for _, v in ipairs(views) do ---@type integer, RegUseView
if v.lanes then has_lanes = true end
end
if has_lanes then
local width = nil ---@type integer
local width = nil ---@type integer
for _, v in ipairs(views) do ---@type integer, RegUseView
if not v.lanes then
errors[#errors + 1] = { kind = "reguse_malformed" }
@@ -2231,7 +2231,7 @@ parse_reg_use_schema_body = function(body, type_registry, opts)
for i = 1, width do ---@type integer
local slot_name = views[1].names[i] ---@type string
if inst_name then slot_name = inst_name .. "." .. slot_name end
local aliases = {} ---@type string[]
local aliases = {} ---@type string[]
for _, v in ipairs(views) do ---@type integer, RegUseView
local n = v.names[i] ---@type integer
if inst_name then n = inst_name .. "." .. n end
@@ -2242,12 +2242,12 @@ parse_reg_use_schema_body = function(body, type_registry, opts)
end
end
else
local members = {} ---@type string[]
local members = {} ---@type string[]
for _, v in ipairs(views) do ---@type integer, RegUseView
for _, n in ipairs(v.names) do members[#members + 1] = n end ---@type integer, integer
end
local aliases = {} ---@type string[]
local slot_name ---@type string
local slot_name ---@type string
if inst_name then
slot_name = inst_name
for _, m in ipairs(members) do ---@type integer, string
@@ -2293,7 +2293,7 @@ parse_reg_use_schema_body = function(body, type_registry, opts)
end
after = duffle.skip_ws_and_cmt(body, after_paren)
end
local readonly = false ---@type boolean
local readonly = false ---@type boolean
local maybe_const, maybe_end = duffle.read_ident(body, after) ---@type string|nil, integer
if maybe_const == "const" then
readonly = true
@@ -2426,7 +2426,7 @@ local function parse_typedef_array(source, pos, id2_end, line_of, out, after_typ
if not inner then return id2_end end
local args = duffle.split_top_level_commas(inner) ---@type string[]
if #args < 2 then return after_paren end
local elem = duffle.trim(args[1]) ---@type string
local elem = duffle.trim(args[1]) ---@type string
local len = tonumber(duffle.trim(args[2]), 10) ---@type string
if type(elem) ~= "string" or elem == "" or not len or len < 1 or len ~= math.floor(len) then
return after_paren
@@ -2466,7 +2466,7 @@ local TYPE_FORMS = { ---@type table<string, fun(source: string, pos: integer, id
--- @return integer
local function parse_typedef_binds(source, pos, ident_end, line_of, out)
local after_typedef = duffle.skip_ws_and_cmt(source, ident_end) ---@type integer
local id2, id2_end = duffle.read_ident(source, after_typedef) ---@type string|nil, integer
local id2, id2_end = duffle.read_ident(source, after_typedef) ---@type string|nil, integer
if not id2 then return ident_end end
local form = TYPE_FORMS[id2] ---@type DeclForm|nil
if form then
@@ -2534,7 +2534,7 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
-- C-array suffix: `typedef S2 A3x3_S2[3][3];` → kind=array, not a typedef alias.
-- Malformed `[` / non-decimal dims fall through to the typedef-alias path.
if last_ident and not tset_arg then
local dims = {} ---@type integer[]
local dims = {} ---@type integer[]
local dim_scan = duffle.skip_ws_and_cmt(source, last_ident_end) ---@type integer
while dim_scan < semi_pos and source:sub(dim_scan, dim_scan) == "[" do
local close = source:find("]", dim_scan + 1, true) ---@type boolean
@@ -2561,7 +2561,7 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
if tset_arg then
-- Shape 4: alias is the TSet_ argument; the underlying span is the trimmed text from the start of id2 up to (but not including) the TSet_ ident.
local underlying_span = source:sub(after_typedef, tset_pos - 1) ---@type string
local underlying = duffle.trim(underlying_span) ---@type string
local underlying = duffle.trim(underlying_span) ---@type string
register_typedef_alias(underlying, tset_arg, pos, line_of, out)
attach_debug_skip_marker(out, "unrelated")
return tset_arg_end or (semi_pos + 1)
@@ -2570,7 +2570,7 @@ local function parse_typedef_binds(source, pos, ident_end, line_of, out)
if last_ident then
-- Shape 3: alias is the last ident before `;`; the underlying span is the trimmed text from the start of id2 up to (but not including) the alias ident.
local underlying_span = source:sub(after_typedef, last_ident_pos - 1) ---@type string
local underlying = duffle.trim(underlying_span) ---@type string
local underlying = duffle.trim(underlying_span) ---@type string
register_typedef_alias(underlying, last_ident, pos, line_of, out)
attach_debug_skip_marker(out, "unrelated")
return last_ident_end
@@ -2593,17 +2593,17 @@ local function parse_pragma_macro(source, pos, ident_end, line_of, out)
str = duffle.trim(str)
if str:sub(1, 1) ~= '"' or str:sub(-1) ~= '"' then return str_end end
local inner = str:sub(2, -2) ---@type string
local inner = str:sub(2, -2) ---@type string
local space = duffle.find_byte(inner, 32, 1) ---@type integer|nil
if not space then return str_end end
local name = inner:sub(1, space - 1) ---@type string
local rest = inner:sub(space + 1) ---@type integer
local name = inner:sub(1, space - 1) ---@type string
local rest = inner:sub(space + 1) ---@type integer
local eq = duffle.find_byte(rest, 61, 1) ---@type integer|nil
if not eq then return str_end end
local key = duffle.trim(rest:sub(1, eq - 1)) ---@type string
local val = duffle.trim(rest:sub(eq + 1)) ---@type string
local val = duffle.trim(rest:sub(eq + 1)) ---@type string
if key == "tape_atom words" or key == "words" then
out.macros[#out.macros + 1] = { line = line_of(pos), name = name, words = tonumber(val) or 0 }
end
@@ -2661,7 +2661,7 @@ end
--- @return integer
local function parse_enum_entry(source, body, body_offset, line_of, out, entry_name, name_body_pos, value_start)
-- value_start is within `body`, just past the `=`.
local after_ws = duffle.skip_ws_and_cmt(body, value_start) ---@type integer
local after_ws = duffle.skip_ws_and_cmt(body, value_start) ---@type integer
local value, value_end = parse_enum_value(body, after_ws, out) ---@type integer|nil, integer
if value == nil then return value_start end
@@ -2675,13 +2675,13 @@ local function parse_enum_entry(source, body, body_offset, line_of, out, entry_n
out.atom_entry_comments[entry_name] = trailing_cmt
end
local after_value = duffle.skip_ws_and_cmt(body, value_end) ---@type integer
local after_value = duffle.skip_ws_and_cmt(body, value_end) ---@type integer
local has_atom_reg, end_after_atom_reg = check_bare_atom_reg(body, after_value) ---@type boolean, integer
-- Only register R_* entries whose value is followed by bare `atom_reg`.
if has_atom_reg and entry_name:byte(1) == BYTE_R and entry_name:byte(2) == BYTE_UNDERSCORE then
local entry_source_pos = body_offset + name_body_pos - 1 ---@type integer
local entry = { ---@type SiteCarrier
local entry = { ---@type SiteCarrier
name = entry_name,
code = value,
source_line = line_of(entry_source_pos),
@@ -2690,7 +2690,7 @@ local function parse_enum_entry(source, body, body_offset, line_of, out, entry_n
has_atom_reg = true,
}
-- Adjacent enum-site default view, if any. Tolerant of malformed `atom_type(...)`.
local after_atom_reg = duffle.skip_ws_and_cmt(body, end_after_atom_reg) ---@type integer
local after_atom_reg = duffle.skip_ws_and_cmt(body, end_after_atom_reg) ---@type integer
local dflt_type_name, dflt_depth, end_after_atom_type = parse_enum_atom_type_default(body, after_atom_reg) ---@type string|nil, integer, integer
if dflt_type_name then
entry.default_type = dflt_type_name
@@ -2716,7 +2716,7 @@ end
--- @param out SourceScan
--- @return nil
local function parse_enum_body(source, body, body_offset, line_of, out)
local pos = 1 ---@type integer
local pos = 1 ---@type integer
local body_len = #body ---@type integer
while pos <= body_len do
pos = duffle.skip_ws_and_cmt(body, pos)
@@ -2773,7 +2773,7 @@ local function parse_enum(source, pos, ident_end, line_of, out)
-- pos points at the `e` of `enum`; ident_end points past `enum`.
-- Optional enum tag (e.g. `enum Foo { ... }`): a single ident between `enum` and `{` that is not followed by `(`.
local after_ident = duffle.skip_ws_and_cmt(source, ident_end) ---@type integer
local tag_ident, tag_end = duffle.read_ident(source, after_ident) ---@type string|nil, integer
local tag_ident, tag_end = duffle.read_ident(source, after_ident) ---@type string|nil, integer
if tag_ident and source:byte(tag_end) ~= 0x28 then -- not '('
after_ident = tag_end
end
@@ -2814,14 +2814,14 @@ end
local function parse_addrs_assign(source, pos, ident_end, line_of, out)
local after = duffle.skip_ws_and_cmt(source, ident_end) ---@type integer
if source:sub(after, after) ~= "[" then return ident_end end
local inner, after_br = duffle.read_brackets(source, after) ---@type string|nil, integer
local inner, after_br = duffle.read_brackets(source, after) ---@type string|nil, integer
local idx = inner and tonumber(duffle.trim(inner)) ---@type string
after_br = duffle.skip_ws_and_cmt(source, after_br or after)
if not (idx and source:sub(after_br, after_br) == "=") then
return after_br or (after + 1)
end
local rhs = duffle.skip_ws_and_cmt(source, after_br + 1) ---@type integer
local rhs_ident = duffle.read_ident(source, rhs) ---@type string|nil
local rhs_ident = duffle.read_ident(source, rhs) ---@type string|nil
if rhs_ident then out._addrs[idx] = rhs_ident end
return rhs
end
@@ -2835,7 +2835,7 @@ end
local function parse_tb_emit_(source, pos, ident_end, line_of, out)
local after = duffle.skip_ws_and_cmt(source, ident_end) ---@type integer
if source:sub(after, after) ~= "(" then return ident_end end
local inner, after_p = duffle.read_parens(source, after) ---@type string|nil, integer
local inner, after_p = duffle.read_parens(source, after) ---@type string|nil, integer
local name = duffle.trim(inner or ""):match("^([%w_]+)") ---@type string
if name then
out._chain = out._chain or {}
@@ -2853,11 +2853,11 @@ end
local function parse_tb_emit(source, pos, ident_end, line_of, out)
local after = duffle.skip_ws_and_cmt(source, ident_end) ---@type integer
if source:sub(after, after) ~= "(" then return ident_end end
local inner, after_p = duffle.read_parens(source, after) ---@type string|nil, integer
local inner, after_p = duffle.read_parens(source, after) ---@type string|nil, integer
local args = duffle.split_top_level_commas(inner or "") ---@type string[]
local last = duffle.trim(args[#args] or "") ---@type string
local idx = last:match("^addrs%s*%[%s*(%d+)%s*%]$") ---@type integer
local name ---@type string
local last = duffle.trim(args[#args] or "") ---@type string
local idx = last:match("^addrs%s*%[%s*(%d+)%s*%]$") ---@type integer
local name ---@type string
if idx then name = out._addrs[tonumber(idx)]
else name = last:match("([%w_]+)$")
end
@@ -2919,7 +2919,7 @@ local DECL_PARSERS = { ---@type table<string, fun(source: string, pos: integer,
--- @return SourceScan
local function scan_source(source, source_file, code_macros, code_macro_bodies)
local line_of = duffle.LineIndex(source) ---@type fun(pos: integer): integer
local out = { ---@type SourceScan
local out = { ---@type SourceScan
atoms = {},
raw_atoms = {},
binds = {},
@@ -2963,7 +2963,7 @@ local function scan_source(source, source_file, code_macros, code_macro_bodies)
_code_macro_bodies = code_macro_bodies or {},
_source_file = source_file,
}
local pos = 1 ---@type integer
local pos = 1 ---@type integer
local src_len = #source ---@type integer
while pos <= src_len do
@@ -2991,7 +2991,7 @@ local function scan_source(source, source_file, code_macros, code_macro_bodies)
-- If a pending marker is still open, consume it so it cannot drift to a later declaration.
-- Unsupported identifiers never create marker records.
local markers = out.debug_skip_markers ---@type DebugSkipMarker[]
local marker = markers[#markers] ---@type DebugSkipMarker
local marker = markers[#markers] ---@type DebugSkipMarker
if marker and marker.pending then
if ident == "FI_" then
marker.proc_prelude = true
@@ -3003,8 +3003,8 @@ local function scan_source(source, source_file, code_macros, code_macro_bodies)
end
else
local markers = out.debug_skip_markers ---@type DebugSkipMarker[]
local marker = markers[#markers] ---@type DebugSkipMarker
local c = source:sub(pos, pos) ---@type string
local marker = markers[#markers] ---@type DebugSkipMarker
local c = source:sub(pos, pos) ---@type string
if marker and marker.pending and marker.proc_prelude then
if c == "{" or c == ";" then
attach_debug_skip_marker(out, "unrelated")
@@ -3081,16 +3081,16 @@ local function type_shape(entry)
if type(entry) ~= "table" then return "" end
if entry.kind == "struct" then
local fields = entry.fields or {} ---@type TypeField[]
local parts = {} ---@type string[]
for _, f in ipairs(fields) do ---@type integer, TypeField
local parts = {} ---@type string[]
for _, f in ipairs(fields) do ---@type integer, TypeField
parts[#parts + 1] = string.format("%s:%s*%s",
tostring(f.name), tostring(f.type_name), tostring(f.pointer_depth or 0))
end
return "struct[" .. table.concat(parts, ",") .. "]"
elseif entry.kind == "enum" then
local fields = entry.fields or {} ---@type TypeField[]
local parts = {} ---@type string[]
for _, f in ipairs(fields) do ---@type integer, TypeField
local parts = {} ---@type string[]
for _, f in ipairs(fields) do ---@type integer, TypeField
parts[#parts + 1] = string.format("%s=%s", tostring(f.name), tostring(f.value))
end
return "enum[" .. table.concat(parts, ",") .. "]"
@@ -3109,8 +3109,8 @@ end
local function bind_shape(entry)
if type(entry) ~= "table" then return "" end
local fields = entry.fields or {} ---@type TypeField[]
local parts = {} ---@type string[]
for _, f in ipairs(fields) do ---@type integer, TypeField
local parts = {} ---@type string[]
for _, f in ipairs(fields) do ---@type integer, TypeField
parts[#parts + 1] = string.format("%s:%s*%s",
tostring(f.name), tostring(f.type_name), tostring(f.pointer_depth or 0))
end
@@ -3134,14 +3134,14 @@ end
--- @return string
local function view_shape(entry)
if type(entry) ~= "table" then return "" end
local overrides = entry.reg_type_overrides or {} ---@type table<string, RegTypeOverride>
local keys = {} ---@type string[]
local overrides = entry.reg_type_overrides or {} ---@type table<string, RegTypeOverride>
local keys = {} ---@type string[]
for k in pairs(overrides) do keys[#keys + 1] = k end ---@type string
--- @param a string
--- @param b string
--- @return boolean
table.sort(keys, function(a, b) return tostring(a) < tostring(b) end)
local parts = {} ---@type string[]
local parts = {} ---@type string[]
for _, k in ipairs(keys) do ---@type integer, string
local ov = overrides[k] ---@type RegTypeOverride
parts[#parts + 1] = string.format("%s=%s*%s", tostring(k),
@@ -3166,8 +3166,8 @@ end
--- @return string
local function phase_shape(entry)
if type(entry) ~= "table" then return "" end
local atoms = entry.atoms or {} ---@type string[]
local sorted = {} ---@type string[]
local atoms = entry.atoms or {} ---@type string[]
local sorted = {} ---@type string[]
for _, a in ipairs(atoms) do sorted[#sorted + 1] = a end ---@type integer, string
--- @param a string
--- @param b string
@@ -3194,9 +3194,9 @@ local function merge_named_with_sites(registry, name, new_entry, site, collision
registry[name].sites = { site }
return
end
local existing = registry[name] ---@type SiteCarrier
local existing = registry[name] ---@type SiteCarrier
local new_shape = shape_fn(new_entry) ---@type string
local old_shape = shape_fn(existing) ---@type string
local old_shape = shape_fn(existing) ---@type string
if new_shape == old_shape and new_shape ~= "" then
-- Identical shape: coalesce by appending the site.
existing.sites = existing.sites or { build_site(existing.source_file, existing.source_line) }
@@ -3381,7 +3381,7 @@ local SCHEMA_BODY_ERROR = { ---@type table<string, boolean> -- bag: reguse erro
--- @param corpus Corpus
--- @return nil
local function resolve_reg_use_schemas(corpus)
local kept = {} ---@type RegUseError[]
local kept = {} ---@type RegUseError[]
for _, err in ipairs(corpus.reg_use_errors or {}) do ---@type integer, RegUseError
if not SCHEMA_BODY_ERROR[err.kind] then
kept[#kept + 1] = err
@@ -3466,8 +3466,8 @@ function M.run(ctx)
-- Same `code_macros` table is shared with pass 2 below.
for macro_name, _ in pairs(code_macro_bodies) do ---@type string, string
if code_macros[macro_name] == nil then
local body = code_macro_bodies[macro_name] ---@type string
local visited = { [macro_name] = true } ---@type table<string, boolean> -- bag: already-walked ident -> true
local body = code_macro_bodies[macro_name] ---@type string
local visited = { [macro_name] = true } ---@type table<string, boolean> -- bag: already-walked ident -> true
local value = resolve_code_macro_value(body, 1, code_macros, code_macro_bodies, visited, 1) ---@type integer|nil
if value ~= nil then code_macros[macro_name] = value end
end
scripts/passes/static_analysis.lua
+264 -264
View File
File diff suppressed because it is too large Load Diff
scripts/passes/word_count_eval.lua
+1 -1
View File
@@ -24,7 +24,7 @@
-- Uses `debug.getinfo` to find this file's own directory, so it works both standalone and when require'd from the orchestrator.
-- duffle_paths.lua sets package.path then returns `require("duffle")` at the bottom, so the dofile value IS the duffle module.
local _bootstrap_dir = debug.getinfo(1, "S").source:match("^@?(.*[/\\])") or "./" ---@type string
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
local duffle = dofile(_bootstrap_dir .. "../duffle_paths.lua") ---@type DuffleExport
-- ════════════════════════════════════════════════════════════════════════════
-- Type declarations