[apotema]

Summary

src/main_zig.zig is the 4,692-line code generator that every backend × platform combo flows through. A full split is high-risk: bit-identical generated output must be preserved for every example, and there are ~18 template slots wired through a single orchestrator.

This PR is an RFC for the cut plan plus one proof-of-concept extraction. The rest of the cuts are deferred until reviewers vet the approach. Refs #183.

What's in this PR

1. docs/REFACTOR-PLAN-main-zig.md — section-by-section map of main_zig.zig, proposed module layout (src/codegen/{scan, idents, validate, blocks/*, lifecycle/*, preview, main_template}.zig), dependency graph, per-section risk assessment, and ordering for future extraction PRs.
2. src/codegen/scan.zig (875 lines) — the PoC extraction. Holds the AST-walk discovery helpers (PluginEvent, PluginFlowDecls, PluginPinStyle, PluginCoercion, discoverPluginEvents, discoverPluginFlowDecls, dedupePinStyles, sanitizePluginIdent, pathToIdent) plus the existing pathToIdent tests. Chosen because it's pure data collection — no template state, no codegen-orchestrator coupling, well-defined public API already used externally.
3. src/main_zig.zig (4,692 → 3,880 lines, -812) — re-exports the moved symbols so root.zig and test/tests.zig keep their existing imports unchanged. Pure move + import; no call sites moved, no logic touched.
4. scripts/gen_all_examples.sh — regenerates every bundled example so before/after diffs can verify the bit-identical contract.

Verification

• zig build clean.
• zig build test exits 0 (same as origin/main; "failed command" log lines are pre-existing diagnostic-output tests, not test failures).
• Bit-identical generated output across all 9 bundled examples (raylib, sokol, sokol_imgui, null, plugin-controllers, flows-smoke, asset-streaming-smoke, bgfx, wgpu):

  find /tmp/asm-before -name "main.zig" -not -path "*/deps/*" | while read f; do
    after=${f/asm-before/asm-after}
    cmp -s "$f" "$after" || echo "DIFF: $f"
  done
  # → zero diffs
  

  The only diff -r drift across the entire generated tree is the generated_at ISO-8601 timestamp inside flow_catalog.json (expected and unrelated).

Constraints honored

• No logic rewritten — pure move + import.
• Public API unchanged: every @import("main_zig.zig").Plugin* / .discover* site keeps working via re-exports.
• No further extractions attempted.
• No backend templates touched.

Asks for review

1. Is the proposed module layout the right shape? Particularly: do you want src/codegen/blocks/*.zig per-slot or one blocks.zig? Per-backend lifecycle/* vs one file?
2. Is the ordering sensible? Plan lists 10 steps; PoC is step 1. Steps 2-9 each ship as their own PR with the same bit-identical guarantee.
3. Any preview/orchestrator state I'm under-estimating? The risk table flags preview.zig (~1200 lines of inline templates) and lifecycle/* as medium-to-high. The orchestrator itself stays last.

If the plan looks wrong, the PoC reverts cleanly (one re-export shim, one new file).

Test plan

• Reviewer skims docs/REFACTOR-PLAN-main-zig.md and reacts to the proposed module layout / ordering.
• Reviewer spot-checks src/codegen/scan.zig against the deleted regions of src/main_zig.zig to confirm pure move.
• CI runs zig build + zig build test.
• Reviewer optionally re-runs bash scripts/gen_all_examples.sh /tmp/x on this branch vs origin/main to reproduce the bit-identical check.

DRAFT — do not merge until plan is reviewed.

[gemini-code-assist]

Code Review

This pull request initiates a refactoring plan to split the large src/main_zig.zig file by extracting discovery and scanning helpers into a new submodule, src/codegen/scan.zig, while maintaining backward compatibility via re-exports. It also introduces a verification script to ensure bit-identical output generation across examples. The review feedback highlights critical memory leak risks in the newly extracted scanning code where partial allocations are not properly cleaned up with block-scoped errdefers on failure. Additionally, it recommends replacing std.debug.print with standard logging facilities (std.log.err) for user-facing errors in CLI contexts.

[gemini-code-assist]

If any of the subsequent allocator.dupe allocations or the entries.append call fail, the previously allocated strings in the current iteration will be leaked. Using block-scoped errdefers ensures that these temporary allocations are cleaned up if the iteration fails before ownership is transferred to entries.

            const duped_import_name = try allocator.dupe(u8, module_name);
            errdefer allocator.free(duped_import_name);
            const duped_sanitized = try allocator.dupe(u8, sanitized);
            errdefer allocator.free(duped_sanitized);
            const duped_event_name = try allocator.dupe(u8, event_name);
            errdefer allocator.free(duped_event_name);

            try entries.append(allocator, .{
                .plugin_import_name = duped_import_name,
                .plugin_sanitized = duped_sanitized,
                .event_name = duped_event_name,
            });

[gemini-code-assist]

If any of the allocator.dupe calls or the append call fail, constructs_value (which is allocated by extractConstructsString) and any previously allocated strings in the current iteration will be leaked. Block-scoped errdefers should be used to prevent these memory leaks on allocation failure.

                const init_src = ast.getNodeSource(member_init);
                const constructs_value = extractConstructsString(allocator, init_src);
                errdefer if (constructs_value) |c| allocator.free(c);

                const duped_path = try allocator.dupe(u8, module_import_path);
                errdefer allocator.free(duped_path);
                const duped_sanitized = try allocator.dupe(u8, module_sanitized);
                errdefer allocator.free(duped_sanitized);
                const duped_name = try allocator.dupe(u8, member_name);
                errdefer allocator.free(duped_name);

                try flow_nodes_out.append(allocator, .{
                    .module_import_path = duped_path,
                    .module_sanitized = duped_sanitized,
                    .node_name = duped_name,
                    .is_script = is_script,
                    .constructs = constructs_value,
                });

[gemini-code-assist]

According to the general rules, debug-specific print functions like std.debug.print should not be used for user-facing warnings or errors in CLI tools. Standard logging facilities (such as std.log.err) should be used instead.

                std.log.err("labelle: path too long for identifier (max {d} chars): too many escaped chars", .{b.len});

References

1. In CLI tools, use standard logging facilities (e.g. std.log.warn) or write to stderr for user-facing warnings, rather than using debug-specific print functions (e.g. std.debug.print).

[apotema]

Now under umbrella PR #202

The content from this PR is already on the umbrella integration branch feat/183-split-main-zig (which #202 targets to main). The umbrella aggregates the whole main_zig.zig split — every leaf in the stack and the eventual mixin conversion pass.

You can either:

• Review + merge this PR individually, then the umbrella's diff shrinks as the leaves below land
• Or skip individual review and review the whole split via Umbrella: split src/main_zig.zig (#183) #202 when it's ready — in which case this PR closes (content lands via the umbrella merge)

Either way the actual code on main ends up identical.

[apotema]

Closing — content is fully on the umbrella branch feat/183-split-main-zig (via the 12-PR stack that merged into it). Review the complete refactor on #202.

The branch refactor/183-main-zig-investigation (and refactor/183-extract-next for #195) is left in place — git history is preserved.