Structure Fold

A VS Code extension that folds Python and C++ definitions, not arbitrary indentation levels.

Three levels

Minus moves 0 -> 1 -> 2. Plus moves 2 -> 1 -> 0. Repeated presses at an endpoint reapply that level; they do not cycle. Expanding a class at level 2 reveals its still-collapsed methods.

Only the active editor is affected. Each open file/editor group has an independent level, including split views. Levels survive tab switches, and active editors retain their level when moved. Levels are not persisted across closing the document or restarting VS Code.

Named nested definitions, decorated/async Python functions, Python property getters, and C++ constructors, destructors, and overloaded operators are included. One-line definitions and C++ declarations without bodies are left alone.

Loops, conditionals, fields, multiline values, comments, imports, namespaces, enums, and lambda expressions are not targeted. Existing manual folds of those regions are preserved. Level 0 expands definitions; it does not restore an earlier set of manual class/function folds. Source text is never edited.

Install

Install Structure Fold (akaminer.structure-fold) from VS Code's Extensions view, or run:

code --install-extension akaminer.structure-fold

For manual installation, choose Extensions -> ... -> Install from VSIX... and select structure-fold-0.1.4.vsix.

If you installed an earlier local build, uninstall local-structure-fold.structure-fold before installing the Marketplace version. The publisher changed, so VS Code treats them as different extensions. Reload the window after replacing the local build to avoid duplicate commands.

Enable Settings Sync: Extensions in VS Code to synchronize installation across your machines. Python/C++ language support is still required on each host.

The extension requires VS Code 1.96 or newer and language support that supplies document symbols and compatible folding ranges:

• Python: the Python and Pylance extensions.
• C++: the Microsoft C/C++ extension, clangd, or another compatible provider.

C++ headers are supported when their VS Code language mode is C++. Read-only editors are supported because folding does not change the document.

Shortcuts

On a US keyboard, the plus binding is Ctrl+Alt+Shift+= (Cmd+Option+Shift+= on macOS).

To change either shortcut, open Preferences: Open Keyboard Shortcuts, search for Structure Fold, and edit:

• Structure Fold: Collapse One Level (structureFold.collapse)
• Structure Fold: Expand One Level (structureFold.expand)

Both commands are also available in the Command Palette. The default shortcuts are active only while a Python/C++ text editor has focus, so ordinary typing of + and - is not intercepted.

Manual folding clicks do not change the remembered level. The next shortcut applies the requested level again.

Diagnostics and limitations

Provider failures and unavailable symbols/ranges are reported in a notification and the Structure Fold output channel. Wait for the language service to load and ensure Editor: Folding is enabled.

The commands serialize rapid key presses and cancel stale work when the active file/editor group, document, language mode, or folding settings change during a request. Recreating the editor for the same document in the same group does not cancel folding.

VS Code folding is line-based. Definitions must have distinct folding headers to represent level 1 independently. Ambiguous/shared headers or incomplete provider ranges produce an error instead of folding a class or an internal block by accident. For very large files, also check Editor: Folding Maximum Regions. Both clangd's region-labelled folds (which leave closing braces visible) and Microsoft C/C++ folding ranges are supported. Python folds may include trailing indented comments beyond the language provider's symbol range; these remain part of the whole-definition fold.

Development and verification

Node.js 22 or newer is required for the development/packaging tools. There are no runtime npm dependencies.

npm ci
npm run check
npm test
npm run test:integration
npm run test:providers
npm run package

The integration tests use a separate VS Code 1.96.4 Extension Development Host, original Python/C++ fixtures, and an isolated user profile. The provider smoke tests install Python/Pylance and C/C++ only into a test extension directory. Use npm run test:clangd to test Python/Pylance and clangd instead. It requires a local clangd executable on PATH, or an explicit CLANGD_PATH. The two C++ providers are tested separately to avoid registration conflicts. Your normal VS Code settings and installed extensions are not modified. Downloaded test tools are cached in .vscode-test/ and excluded from the VSIX. Set VSCODE_TEST_VERSION=stable to test the latest stable VS Code instead.

Headless Linux/WSL testing can use the supplied test/Dockerfile:

docker build -t structure-fold-tests -f test/Dockerfile test
docker run --rm --init --cpus=2 --memory=3g \
  --user "$(id -u):$(id -g)" \
  --mount "type=bind,source=$PWD,target=/workspace" \
  structure-fold-tests xvfb-run -a sh -c \
  'npm test && npm run test:integration && npm run test:providers'

Keep --init: Xvfb's readiness handshake requires a parent other than PID 1. The tests cover declaration targeting, hierarchy, unrelated/manual folds, all level transitions, rapid presses, tab/split/group behavior, stale work, provider errors, and actual Python/Pylance, C/C++, and clangd language support.