Transpiler: support structs with fixed-size array fields (Option A and B)

[Copilot]

Adds transpiler support for value-type struct fields that hold a fixed-size byte array, via either C# fixed byte buf[N] (Option A, unsafe) or [InlineArray(N)] (Option B). Enables porting C code like From Below's struct cluster { ... unsigned char layout[4]; ... } without resorting to structure-of-arrays.

Changes

• Struct layout detection (Transpiler.StructAnalysis.cs): new TryGetBufferFieldSize reads the [FixedBuffer] attribute, the field's value-type [InlineArray(N)] attribute, or the explicit ClassLayout of Roslyn's <name>e__FixedBuffer helper. Buffer fields contribute their full byte count to the struct layout so following fields land at the correct offset.
• Ldflda lowering (IL2NESWriter.StructFields.cs): pattern-matches the full buffer-access sub-sequence (fixed buffer: outer + inner ldflda; inline array: InlineArrayElementRef/InlineArrayFirstElementRef; inline array runtime index: InlineArrayAsSpan + Span<>.get_Item) through the matching stind.i1/ldind.u1 and emits one LDA/STA at base + fieldOffset + index — Absolute for constant indices, AbsoluteX (with LDX) for runtime indices.
• Skip mechanism (Transpiler.cs, IL2NESWriter.cs): new SkipUntilIndex lets a single handler consume a multi-instruction IL pattern; both main and user-method dispatch loops honor it.
• Initobj dispatched as a no-op so T cur = default; lowers correctly (consistent with existing semantics that treat struct locals as uninitialized zero-page bytes the user code fills in).
• Parser fixes (Transpiler.ILParsing.cs): skip synthesized declaring types like <PrivateImplementationDetails> so Roslyn's emitted InlineArrayElementRef/InlineArrayAsSpan helpers aren't treated as user methods; resolve MethodSpecification whose .Method is a MethodDefinition (those helpers).
• Tests: 4 new RoslynTests in StructsTests covering both options × {constant, runtime} indices.
• Docs (docs/8bitworkshop-samples.md): drop "no struct support" notes; mention the new buffer-field capabilities.

Example

Both lower identically to direct zero-page LDA/STA (Absolute for [0], AbsoluteX for [i]):

// Option A
unsafe struct Cluster {
    public byte sprite;
    public byte id;
    public fixed byte layout[4];
}

// Option B
[System.Runtime.CompilerServices.InlineArray(4)]
struct Bytes4 { private byte _element0; }
struct Cluster2 { public byte sprite; public byte id; public Bytes4 layout; }

Cluster cur;
cur.layout[0] = 5;     // STA $base+2
cur.layout[i] = 99;    // LDX i; STA $base+2,X

Deferred (stretch items called out in the issue)

• Passing a struct ref to a user method without copying (call-convention work).
• End-to-end Mesen2 sample under samples/.
• const 2D inline-array initializer inside a struct.

[Copilot]

Pull request overview

This PR extends dotnes’s IL→6502 pipeline to support struct fields that represent fixed-size byte buffers, enabling C# ports of C-style structs with inline byte arrays via either fixed byte buf[N] or [InlineArray(N)].

Changes:

• Adds struct-layout analysis for fixed buffers / inline arrays and exposes buffer-field byte sizes to the IL writer.
• Implements ldflda lowering that pattern-matches buffer element reads/writes through stind.i1 / ldind.u1, emitting a single LDA/STA using Absolute or AbsoluteX.
• Adds a skip mechanism (SkipUntilIndex) to let a handler consume multi-instruction IL patterns, plus new Roslyn tests and updated docs.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/dotnes.tests/StructsTests.cs	Adds Roslyn tests for fixed-buffer and inline-array constant/runtime indexing.
src/dotnes.tasks/Utilities/Transpiler.StructAnalysis.cs	Detects buffer-field byte sizes from metadata (FixedBuffer, InlineArray, layout size) and incorporates them into struct sizing.
src/dotnes.tasks/Utilities/Transpiler.ILParsing.cs	Skips synthesized helper methods (e.g., inline-array helpers) and improves parsing of some MethodSpecification cases.
src/dotnes.tasks/Utilities/Transpiler.cs	Plumbs BufferFieldSizes into writers and adds SkipUntilIndex handling to the main/user-method IL dispatch loops.
src/dotnes.tasks/Utilities/IL2NESWriter.StructFields.cs	Implements HandleLdflda buffer access lowering + helpers to extract index/value and emit Absolute/AbsoluteX.
src/dotnes.tasks/Utilities/IL2NESWriter.ILDispatch.cs	Dispatches Ldflda and treats Initobj as a no-op for struct locals.
src/dotnes.tasks/Utilities/IL2NESWriter.cs	Adds BufferFieldSizes and SkipUntilIndex to support multi-instruction lowering.
docs/8bitworkshop-samples.md	Updates docs to reflect the new struct buffer-field capabilities and current limitations.

Comments suppressed due to low confidence (1)

src/dotnes.tasks/Utilities/Transpiler.cs:411

• There are two statements on one line here (var labelName = ...; if (...)), which hurts readability and makes future diffs noisier. Please split this into separate lines.

                var labelName = $"{methodName}_instruction_{instruction.Offset:X2}";                if (methodWriter.CurrentBlock != null)
                    methodWriter.CurrentBlock.SetNextLabel(labelName);

[jonathanpeppers]

/review

[github-actions]

✅ dotnes PR Reviewer completed successfully!

[github-actions]

Review Summary

Verdict: ⚠️ Needs Changes (1 error, 1 warning, 2 suggestions)

CI: ✅ All checks passing (build, smoke-test macOS, smoke-test Windows).

What this PR does

Adds transpiler support for struct buffer fields via C# fixed byte buf[N] (Option A) and [InlineArray(N)] (Option B). The implementation pattern-matches multi-instruction IL sequences (ldflda through stind.i1/ldind.u1) and emits direct LDA/STA at computed absolute addresses. Good defensive error handling with explicit TranspileException for unsupported patterns.

Issues

Sev	Category	Summary
❌	Transpiler correctness	Buffer field stores only work with constant values — cur.layout[0] = someVariable will fail at transpile time
⚠️	Error handling	Bare catch {} in GetInlineArrayLength swallows all exceptions silently
💡	Testing	Single-byte hex assertions ("8D", "AE") are too broad to catch offset bugs
💡	Code organization	Skip-loop logic duplicated between main and user-method dispatch

Positives

• Thorough defensive coding — explicit TranspileException for every unsupported pattern rather than silent miscompilation
• Clean separation into StructAnalysis (metadata) and StructFields (emission)
• Good test coverage of both Option A and B × constant/runtime index combinations
• Well-documented IL pattern shapes in comments
• Parser fixes for <PrivateImplementationDetails> and MethodSpecification resolution are correct and targeted

Generated by dotnes PR Reviewer for issue #544 · ● 17.2M