struct-align

Find and fix wasted space in your C/C++ structs — without leaving the editor.

struct-align is a real-time layout analyzer for C and C++ structs. As you type, it highlights padding bytes the compiler silently inserted between your fields and offers a one-click reorder that recovers them — typically 10–40% of the struct's size, with zero functional change.

Why struct padding matters

C and C++ lay out struct fields in declaration order. Each field must sit at an offset that is a multiple of its alignment. When the next field needs more alignment than the running offset provides, the compiler inserts padding bytes — silent, invisible, and free in CPU terms but costly in memory and cache.

Consider this struct:

struct Order {
    char     order_type;   // 1 byte
    double   price;        // 8 bytes
    uint32_t quantity;     // 4 bytes
    uint64_t order_id;     // 8 bytes
};

It looks like 21 bytes of data. The compiler actually allocates 32 bytes — eleven bytes are padding the developer never wrote. Reorder by alignment (largest first) and the same data fits in 24 bytes:

struct Order {
    double   price;
    uint64_t order_id;
    uint32_t quantity;
    char     order_type;
};

That's 25% less memory, with identical semantics. For systems processing millions of records — fintech order books, ECS components, network packet buffers, blockchain account state — this compounds into measurable gains in cache pressure, bandwidth, and dollar cost per request.

struct-align finds these wasted bytes automatically, every time you save.

Features

• Real-time padding diagnostics on every keystroke, powered by an in-process WebAssembly analyzer. No subprocess, no filesystem access — the analyzer is sandboxed inside the extension host.
• Quick Fix code action — apply the suggested reorder with a single click. Preserves comments, attributes, bitfield widths, and inline initializers.
• Hover popup showing the full byte map per struct (offset, size, field name, type) plus a per-field summary (offset, alignment, padding before, parent struct).
• Deep analysis (libclang) — opt-in for projects where the lightweight analyzer can't resolve a custom type. Resolves templates, inheritance, and stdlib types exactly, using your existing compile_commands.json.
• Multi-platform layout: target x86_64-linux, x86_64-windows, or x86_32. Stdlib-aware heuristics (libstdcxx, libcxx, msvc-stl) for std::string, std::vector<T>, and the other usual suspects.
• Honest about limits — flags bitfields, packed structs, virtual methods, and unknown types instead of silently producing wrong numbers.
• Configurable via 5-level cascade: CLI flags > env vars > project config > user-global config > defaults. Register custom types (opaque handles, third-party objects) with explicit size and alignment.

Quick start

1. Install the extension from the Marketplace (or code --install-extension vesangelov.struct-align).
2. Open any .c, .cpp, .hpp, .cc, or .h file containing a struct declaration.
3. Padding above the structAlign.paddingThreshold (default 5%) gets a warning squiggle on the struct name, with the savings shown inline.
4. Click the lightbulb 💡 → "Reorder fields to save N bytes" to apply.
5. Hover any struct or field for the full byte-map / per-field view.

For optional deep (libclang) analysis on save:

1. Install libclang-dev (Linux), Xcode Command Line Tools (macOS), or the LLVM Windows installer.
2. Build and install struct-align-cli from the project repo with -DBUILD_LIBCLANG_PARSER=ON.
3. Set structAlign.deepAnalysis to on-save.

Settings

Commands

How it works

The struct-align core is a C++20 layout calculator + optimizer, compiled to WebAssembly via Emscripten. The extension's TypeScript layer loads the WASM module lazily on first analysis, then calls it in-process — no spawn, no file I/O, no temp files.

Deep analysis (Variant B) routes through a native struct-align-cli subprocess that uses libclang for full type resolution. Results are merged with Variant A diagnostics under a distinct source label so you can tell which layer produced which warning.

Architectural decisions are recorded as ADRs in the project repository.

Modelled constructs (v1.0)

Known limitations

• Multiple / virtual inheritance — detected and flagged with INHERITANCE_UNSUPPORTED; layout not modelled (ADR-0012 defers this to v2.0 because it needs non-linear field placement).
• Polymorphism + inheritance combo — same reason; vtable+base ABI interaction is its own sub-algorithm.
• Uninstantiated templates — no concrete size, skipped with an UNSUPPORTED_FEATURE info diagnostic. Instantiate via a using declaration to make them visible.
• Bitfield / packed / union optimization — layout is reported correctly but no reorder is suggested. Reordering these changes wire format / ABI and is deliberately never proposed.

The forward roadmap lives in ADR-0012.

Feedback & support

When reporting a bug or an incorrect layout, please include:

1. The smallest struct that reproduces the issue — one file, one struct, no external types if possible.
2. Output of struct-align: Show output channel — timestamps + the diagnostic codes emitted make triage minutes instead of hours.
3. Your structAlign.* settings — paste the relevant block from settings.json (particularly platform, stdlibImpl, variant, deepAnalysis).
4. Expected vs actual layout — what sizeof/alignof your compiler reports and what the extension reports.

Feature ideas are welcome even when incomplete. If you have a real-world struct that hits a limitation above, an issue with the offending code + "here's what I wish the tool said" is exactly the input v1.x releases are prioritised from.

License

MIT © vesangelov.