wip: lua metaprogram rework

scripts/passes/annotation.lua

@@ -0,0 +1,29 @@
+-- passes/annotation.lua
+--
+-- Validate atom annotation DSL usage in source files. Reads:
+--   - atom_annot / atom_init / atom_setup / atom_commit / atom_bind
+--     / atom_terminate / atom_label / atom_offset / TAPE_WORDS
+--   - atom_resource / atom_region / atom_group / atom_cadence / atom_async
+--   - Binds_* struct declarations
+-- Writes:
+--   - build/gen/<basename>.errors.h         (with #error directives on findings)
+--   - build/gen/<basename>.annotations.txt  (human-readable summary)
+-- Ported from scripts/tape_atom_annotation_pass.lua:78-545 + 1081-1407
+-- (validation only — NOT rendering, which goes to passes/report.lua).
+--
+-- Coding standard: tabs (1/level), EmmyLua annotations, no regex.
+
+--- @class M
+
+local M = {}
+
+--- @param ctx PassCtx
+--- @return PassResult
+function M.run(ctx)
+	error("passes.annotation.run: implement by porting " ..
+		"find_atom_names, find_atom_annotations, find_macro_word_annotations, " ..
+		"find_atom_pragmas, find_binds_structs, validate from " ..
+		"tape_atom_annotation_pass.lua:78-1407")
+end
+
+return M

scripts/passes/components.lua

@@ -0,0 +1,39 @@
+-- passes/components.lua
+--
+-- Generate <module>/gen/<basename>.macs.h from MipsAtomComp_ declarations
+-- in source files. Ported from tape_atom_annotation_pass.lua:773-1079
+-- (find_component_atoms, preceding_comment_block, extract_arg_names,
+-- convert_line_comments_to_block, compute_component_word_count,
+-- emit_component_macros_h).
+--
+-- Coding standard: tabs (1/level), EmmyLua annotations, no regex.
+
+--- @class M
+
+local M = {}
+
+--- @param ctx PassCtx
+--- @return PassResult
+function M.run(ctx)
+	-- PORT NOTE: copy find_component_atoms, find_function_args_for,
+	-- preceding_comment_block, extract_arg_names, find_component_atoms
+	-- (body parser), convert_line_comments_to_block, emit_component_macros_h
+	-- from tape_atom_annotation_pass.lua lines 604-1079.
+	-- Adaptations:
+	--   - Replace word_counts usage with word_count_eval.count_body_words
+	--   - Pass ctx.out_root / ctx.dry_run / ctx.verbose through
+	--   - Return { outputs, errors, warnings } shape
+	--
+	-- For each src in ctx.sources:
+	--   1. find_component_atoms(src.text) -> [{name, body, args, line, comment}]
+	--   2. for each component, compute its word count (recursively via
+	--      word_count_eval.count_body_words)
+	--   3. emit "#define mac_X(args) body" + "WORD_COUNT(mac_X, N)" to
+	--      <src.dir>/gen/<src.basename>.macs.h
+	--   4. Extend ctx.shared.word_counts with the computed counts
+	--   5. Add {macs_h = path} to result.outputs
+	error("passes.components.run: implement by porting from " ..
+		"tape_atom_annotation_pass.lua:773-1079")
+end
+
+return M

scripts/passes/offsets.lua

@@ -0,0 +1,43 @@
+-- passes/offsets.lua
+--
+-- Generate <module>/gen/<basename>.offsets.h with branch offset
+-- immediates for every atom_offset(F, T) reference in atom bodies.
+-- Ported from scripts/tape_atom.offset_gen.meta.lua:148-389.
+--
+-- The branch offset regression we just fixed in commit 98e27c2 must
+-- NOT return. The fix was in duffle.lua's split_top_level_commas +
+-- tape_atom_annotation_pass.lua's compute_component_word_count.
+-- word_count_eval.count_token_words (Task 1) preserves the fix.
+--
+-- Coding standard: tabs (1/level), EmmyLua annotations, no regex.
+
+--- @class M
+
+local M = {}
+
+--- @param ctx PassCtx
+--- @return PassResult
+function M.run(ctx)
+	-- PORT NOTE: copy find_atoms, scan_atom_body, compute_offsets,
+	-- generate_header, process_source from tape_atom.offset_gen.meta.lua
+	-- lines 245-389.
+	-- Adaptations:
+	--   - Replace local word_count_of_token with word_count_eval.count_token_words
+	--   - Take (ctx, src) instead of (source_path, word_counts) — read
+	--     word counts from ctx.shared.word_counts
+	--   - Return { outputs, errors, warnings } shape
+	--   - Convert indentation from 8-space to tabs
+	--
+	-- For each src in ctx.sources:
+	--   1. Find MipsAtom_ declarations in src.text (find_atoms)
+	--   2. For each atom body, scan_atom_body to count words + find
+	--      atom_label/atom_offset markers
+	--   3. compute_offsets (target_word - branch_word - 1 per pair)
+	--   4. generate_header emits "#define atom_offset__F__T  (N)" +
+	--      "enum { atom_offset__F__T = N, ... }" to <src.dir>/gen/<src.basename>.offsets.h
+	--   5. Add {offsets_h = path} to result.outputs
+	error("passes.offsets.run: implement by porting from " ..
+		"tape_atom.offset_gen.meta.lua:245-389")
+end
+
+return M

scripts/passes/report.lua

@@ -0,0 +1,31 @@
+-- passes/report.lua
+--
+-- Render the per-project summary (build/gen/annotation_validation.txt).
+-- Aggregates errors + warnings from upstream passes.
+--
+-- Coding standard: tabs (1/level), EmmyLua annotations, no regex.
+
+--- @class M
+
+local M = {}
+
+--- @param ctx PassCtx
+--- @return PassResult
+function M.run(ctx)
+	-- PORT NOTE: copy render_source_report + render_project_report
+	-- from tape_atom_annotation_pass.lua lines 1411-1528.
+	-- Adaptations:
+	--   - Read errors/warnings from ctx.upstream[pass_name].outputs/errors
+	--     (orchestrator-collected)
+	--   - Write to <ctx.out_root>/annotation_validation.txt (was
+	--     build/gen/annotation_validation.txt — same path)
+	--   - Return { outputs = {{summary_txt = path}}, errors = {}, warnings = {} }
+	--
+	-- The summary renders a per-atom table + error count + warning count,
+	-- matching the pre-rework format. See the spec's "Report" pass
+	-- description for the expected output.
+	error("passes.report.run: implement by porting render_source_report + " ..
+		"render_project_report from tape_atom_annotation_pass.lua:1411-1528")
+end
+
+return M

scripts/passes/static_analysis.lua

@@ -0,0 +1,16 @@
+-- passes/static_analysis.lua
+--
+-- [FUTURE] Per-atom static-analysis checks. Stub for now; the upcoming
+-- static_analysis_atoms_20260708 track will deliver the 5 (+1) checks.
+
+--- @class M
+
+local M = {}
+
+--- @param ctx PassCtx
+--- @return PassResult
+function M.run(ctx)
+	return { outputs = {}, errors = {}, warnings = {} }
+end
+
+return M