Skip to content

README.md

Latest commit

 

History

History
163 lines (114 loc) · 6.11 KB

README.md

File metadata and controls

163 lines (114 loc) · 6.11 KB

Struct Scope

Struct Scope is a local-first Visual Studio Code extension and command-line tool for inspecting memory layout in C, C++, and Rust. It parses source files, extracts struct-like definitions, computes ABI-aware field placement, and reports byte offsets, field sizes, alignment, padding, cache-line split risks, platform differences, and rule-based improvement guidance without invoking a compiler.

The project is designed for systems programming, embedded development, performance engineering, protocol design, and low-level code review workflows where object layout affects memory footprint, binary compatibility, cache behavior, or wire-format design.

Capabilities

  • Static analysis for C structs, C++ structs/classes with data members, and Rust structs
  • ABI-aware layout computation for x86_64, arm64, arm32, avr, and riscv32
  • Host ABI auto-detection with manual target-platform override
  • Visual byte map with field regions, padding cells, and cache-line boundaries
  • Field table with offsets, sizes, padding-after values, and cache-line notes
  • Rule-based, local-only improvement guidance with severity, confidence, and safe recommendations
  • Layout score and grade for quick prioritization
  • Greedy field reorder suggestions with expected byte savings
  • Platform comparison reports for pointer-width and ABI-sensitive structures
  • VS Code diagnostics for padding hotspots, high-waste structs, and cache-line split fields
  • Analyze-on-save workflow with optional automatic dashboard opening
  • Activity Bar dashboard, status bar command, editor title action, context menu action, and Command Palette commands
  • Terminal CLI for scripting, CI checks, JSON output, Markdown reports, and platform comparison

Safety Model

Struct Scope provides rule-based suggestions only. It does not rewrite source code automatically, execute generated code, fetch remote rules, or call model APIs. Every recommendation is returned with safe: true and auto_apply: false; the user remains responsible for deciding whether a layout change is compatible with ABI, serialization, protocol, or public API requirements.

Requirements

  • Visual Studio Code 1.85 or newer
  • Python 3.8 or newer
  • pip
  • Node.js and npm for development, testing, or packaging

Install Python dependencies:

pip install -r python/requirements.txt

VS Code Usage

Open a supported C, C++, header, or Rust source file. Struct Scope can be invoked through:

  • File save when structscope.analyzeOnSave is enabled
  • StructScope: Analyze Struct from the Command Palette
  • Ctrl+Shift+M on Windows/Linux or Cmd+Shift+M on macOS
  • The Struct Scope status bar item
  • The editor title action or editor context menu
  • The Struct Scope Activity Bar dashboard

The dashboard renders the selected structure as a byte map, field table, metrics panel, rule insights panel, cache-line ruler, and reorder suggestion panel. The platform selector can be changed manually. The Detect control re-runs host ABI detection and refreshes the layout.

Terminal Usage

Analyze a source file:

python python/cli.py tests/fixtures/v2_local_demo.c --platform x86_64

Filter output to one struct:

python python/cli.py tests/fixtures/v2_local_demo.c --platform x86_64 --struct TelemetryPacket

Print rule guidance only:

python python/cli.py tests/fixtures/v2_local_demo.c --platform x86_64 --struct TelemetryPacket --rules-only

Compare target platforms:

python python/cli.py tests/fixtures/v2_local_demo.c --compare x86_64 arm32

Emit JSON or Markdown reports:

python python/cli.py tests/fixtures/v2_local_demo.c --platform auto --json
python python/cli.py tests/fixtures/v2_local_demo.c --platform x86_64 --markdown

Example local C output:

TelemetryPacket: total=40B padding=18B (45.0%) optimal=24B savings=16B
CacheSplitDemo: total=68B padding=0B (0.0%) optimal=68B savings=0B
warning: Field value straddles cache line boundary

Configuration

Setting Description
structscope.pythonPath Optional Python executable path for the analysis backend
structscope.defaultPlatform Default ABI platform: auto, x86_64, arm64, arm32, avr, or riscv32
structscope.cacheLine Cache-line size in bytes: 32, 64, or 128
structscope.analyzeOnSave Runs analysis when supported files are saved
structscope.autoOpenPanel Opens the dashboard automatically during save-triggered analysis
structscope.showStatusBar Shows or hides the Struct Scope status bar command

Supported Inputs

Languages:

  • C structs
  • C++ structs and classes with data members
  • Rust structs

ABI platforms:

  • x86_64
  • arm64
  • arm32
  • avr
  • riscv32

The auto platform option detects the host ABI. Cross-compilation targets cannot be inferred reliably from source text alone, so embedded and firmware projects should select the intended target ABI explicitly.

Architecture

Struct Scope is split into a TypeScript VS Code extension and a Python analysis backend.

  • src/extension.ts manages VS Code commands, diagnostics, status bar state, Activity Bar entries, the webview, and the Python child process.
  • python/server.py exposes newline-delimited JSON-RPC over stdio.
  • python/cli.py provides terminal access to the same analysis pipeline.
  • python/parser_c.py and python/parser_rust.py extract structure definitions with tree-sitter.
  • python/layout_engine.py computes ABI layout with deterministic alignment arithmetic.
  • python/analyser.py and python/rules_engine.py compute waste, cache-line risks, layout grade, and safe guidance.
  • python/platforms.py contains ABI tables and host platform detection.
  • webview/ contains the local dashboard UI assets.

No source code is sent to cloud services, telemetry endpoints, compiler services, third-party analysis systems, or model APIs.

Development

Run tests:

pytest tests/ -v
python tests/test_server_integration.py

Run TypeScript checks and build:

npx tsc --noEmit
npx esbuild src/extension.ts --bundle --platform=node --external:vscode --outfile=out/extension.js

Package the extension:

npx @vscode/vsce package

License

MIT