AGENTS.md

Align Whitespace Agent Notes

Purpose

This repository is a small VS Code extension for aligning whitespace in C/C++ code around the active cursor line.

The extension entrypoint is JavaScript, but the alignment logic lives in Python. Most real work happens in python/align_cpp_block.py.

File Map

• extension.js: VS Code command registration and Python subprocess shim.
• python/align_cpp_block.py: Formatter core.
• tests/test_align_cpp_block.py: Pytest coverage for formatter behavior.
• README.md: User-facing examples and usage notes.

Current Formatter Scope

The formatter started as a simple declaration/assignment aligner and has been expanded to handle:

• declaration blocks like int a; / float bb;
• assignment blocks like int a = 1;
• compound assignment rows like value += 1; / mask |= flag;
• function parameter rows like int a, / float bb,
• call-like rows with inner argument-column alignment
• macro continuation blocks for #define ... \

Examples of current supported behavior:

int lerp(
    int a,
    int b,
    float r,
);

becomes:

int lerp(
    int   a,
    int   b,
    float r,
);

int x = lerp(1, 2, 0.5f);
float xx = lerp(11, 22, 1);

becomes:

int   x  = lerp(1,  2,  0.5f);
float xx = lerp(11, 22, 1   );

value += 1;
longestName = 22;
third -= 333;

becomes:

value       += 1;
longestName  = 22;
third       -= 333;

#define FOO(X) \
    X(a, 1, 2) \
    X(aa, 11, 22) \
    X(aaa, 111, 222)

becomes:

#define FOO(X)      \
    X(a,   1,   2)  \
    X(aa,  11,  22) \
    X(aaa, 111, 222)

Important Behavior Details

• Blocks are still collected by contiguous same-indent lines, except macro blocks, which are collected by #define plus \ continuations.
• Normal blocks are trimmed to the contiguous active run containing the cursor before alignment is applied.
• Inactive rows are hard boundaries for normal blocks. If the cursor is on an inactive row, nothing should happen.
• Assignment-only rows align together and are separate from declaration-style rows. Declaration rows and declaration-with-assignment rows are still active together.
• Compound assignment operators align on the = character, so +=, -=, |=, etc. share the same operator column as =.
• Mixed arity in delimited expressions is aligned only through shared prefix columns.
• Delimited-expression columns are left-aligned, not numeric-right-aligned.
• Nested commas inside strings, templates, nested calls, and braced initializers should not split outer columns.
• Partial changes are expected: only the active run containing the cursor may be reformatted, while inactive neighbors remain unchanged.
• Blank lines and comment-only lines break normal blocks.
• Control-flow lines like return, if (...), for (...), etc. should not be treated as declaration rows.

Tests

Run:

pytest -q

Current tests cover:

• simple declarations
• function parameters
• defaulted parameters
• assignments plus inner call argument alignment
• compound assignment operator alignment
• assignment-only rows staying separate from declaration-style rows
• partial alignment inside scopes
• cursor on different lines within the same block
• active-run boundaries around inactive rows
• scoped/template-qualified assignment targets
• macro continuation alignment
• mixed arity call/macro rows
• nested template/initializer commas
• inline comments
• blank-line and comment-line block boundaries
• blocked control-flow rows

Notes For Future Work

• If you give the user code pointers, also inline the relevant code snippet in the response, not just the file link.
• Use apply_patch for manual file edits.
• The repo currently has generated python/__pycache__/ artifacts after running tests unless they are cleaned up separately.