refactor(codegen): extract idents helpers from main_zig.zig (#183, step 2)

[apotema]

Summary

Second extraction from src/main_zig.zig per the cut plan in #193 (docs/REFACTOR-PLAN-main-zig.md). Moves four identifier / string-emit leaf helpers to src/codegen/idents.zig:

• extWithoutDot
• isValidZigIdentifier
• writeZigString
• pathToPascal

Private re-aliases stay in main_zig.zig so every existing call site (extWithoutDot(res.sound), pathToPascal(name, &buf), …) compiles unchanged. When each consuming block writer / validator moves out in a later cut, the alias for that helper goes with it.

pathToIdent and sanitizePluginIdent already live in codegen/scan.zig from the PoC — they were moved alongside the discovery passes that consume them. Re-moving them here would be churn-only with no semantic value, so the plan's idents-module split lands across two files.

Diff sizes

• src/main_zig.zig: 3880 → 3817 lines (-63)
• src/codegen/idents.zig: 93 lines (new)
• Pure move + import. No logic changes.

Bit-identical verification

scripts/gen_all_examples.sh (added in #193) regenerates every bundled example. Compared /tmp/asm-before (this branch's parent tip, refactor/183-main-zig-investigation) vs /tmp/asm-after (this branch):

• All 9 examples that ran (sokol_imgui soft-fails on the missing labelle-imgui sibling in both runs — same as PoC baseline) produced byte-identical generated main.zig, build.zig, build.zig.zon, and the entire generated tests/ tree (46 files).
• Only flow_catalog.json's generated_at ISO-8601 timestamp differs — exactly the documented drift in docs/REFACTOR-PLAN-main-zig.md.

Test plan

• zig build succeeds
• zig build test: 506/510 passed (4 skipped) — identical count to the parent branch baseline
• bash scripts/gen_all_examples.sh produces byte-identical output (except flow_catalog.json timestamp) for every working example

Base branch dependency

This PR is draft and based on refactor/183-main-zig-investigation (PR #193), not main. Once #193 lands, I will rebase this onto main and mark it ready.

Refs: #183
Builds on: #193

[gemini-code-assist]

Code Review

This pull request extracts several allocation-free string and identifier helpers from src/main_zig.zig into a dedicated module src/codegen/idents.zig to facilitate reuse. Private aliases are maintained in src/main_zig.zig to avoid breaking existing call sites. The review feedback highlights two important improvements: first, pathToPascal should prepend an underscore if the input starts with a digit to ensure the generated Zig identifier is valid; second, writeZigString should escape common control characters (like \n, \r, and \t) to prevent compilation errors in the generated source code.

[gemini-code-assist]

According to the general rules, Zig identifiers must not start with a digit. When converting strings (such as file paths) to Zig identifiers, we must prefix the result with an underscore if the input starts with a digit to ensure the generated code is valid.

Currently, pathToPascal does not handle this case, which can lead to invalid Zig identifiers (e.g., 1Enemy instead of _1Enemy) if a script or component path starts with a digit.

pub fn pathToPascal(name: []const u8, pascal_buf: *[128]u8) []const u8 {
    const end = if (std.mem.endsWith(u8, name, ".zig")) name.len - 4 else name.len;
    var i: usize = 0;
    if (end > 0 and name[0] >= '0' and name[0] <= '9') {
        pascal_buf[i] = '_';
        i += 1;
    }
    var capitalize_next = true;
    for (name[0..end]) |c| {
        switch (c) {
            'A'...'Z', 'a'...'z', '0'...'9' => {
                if (i >= pascal_buf.len) break;
                pascal_buf[i] = if (capitalize_next) std.ascii.toUpper(c) else c;
                i += 1;
                capitalize_next = false;
            },
            else => capitalize_next = true,
        }
    }
    return pascal_buf[0..i];
}

References

1. Zig identifiers must not start with a digit. When converting strings (such as file paths) to Zig identifiers, prefix the result with an underscore if the input starts with a digit to ensure the generated code is valid.

[gemini-code-assist]

Currently, writeZigString only escapes " and \. If an asset or scene name contains other control characters like newlines (\n), carriage returns (\r), or tabs (\t), they will be written raw into the double-quoted string literal, which will cause compile errors in the generated Zig code.

We should also escape these common control characters to ensure the generated code is always valid.

pub fn writeZigString(w: anytype, s: []const u8) !void {
    try w.writeByte('"');
    for (s) |c| {
        switch (c) {
            '"' => try w.writeAll("\\\""),
            '\\' => try w.writeAll("\\\\"),
            '\n' => try w.writeAll("\\n"),
            '\r' => try w.writeAll("\\r"),
            '\t' => try w.writeAll("\\t"),
            else => try w.writeByte(c),
        }
    }
    try w.writeByte('"');
}

[Copilot]

Pull request overview

This PR continues the planned refactor of the main Zig code generator by extracting a small set of identifier/string helper utilities out of src/main_zig.zig into a dedicated src/codegen/idents.zig module, while keeping local aliases in main_zig.zig so existing call sites remain unchanged.

Changes:

• Added new src/codegen/idents.zig module containing extWithoutDot, isValidZigIdentifier, writeZigString, and pathToPascal.
• Updated src/main_zig.zig to import codegen/idents.zig and keep private aliases to avoid touching call sites.
• Removed the original helper function definitions from src/main_zig.zig (pure move).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/main_zig.zig	Imports the new idents helper module and keeps private aliases; removes in-file helper implementations.
src/codegen/idents.zig	New leaf-utilities module for identifier derivation and Zig-string emission escaping.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[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.