FA Insight

Framealloc-aware IDE tooling for Rust game engines.

Overview

FA Insight is a VS Code extension that brings memory intent awareness to your Rust game development workflow. It integrates with framealloc and cargo-fa to provide:

• Inline diagnostics — See memory intent violations as you code
• Memory inspector panel — Real-time view of allocation patterns
• Budget tracking — Visual budget pressure indicators
• Tag hierarchy — Understand allocation distribution by tag

Philosophy: All features are opt-in, explicit, and zero-cost when disabled.

Features

Inline Diagnostics

FA Insight runs cargo-fa in the background and surfaces diagnostics directly in your editor:

⚠️ FA501: Frame allocation behaves like long-lived data
   avg lifetime: 96 frames → consider `pool_alloc`

Click any diagnostic code to see a detailed explanation with examples.

Memory Inspector Panel

A sidebar panel showing real-time memory state:

• Summary — Frame, pool, heap bytes with peak tracking
• Tag tree — Hierarchical view of tagged allocations
• Budget pressure — Visual bars showing per-thread usage
• Promotions — Track data moving between allocation tiers
• Diagnostics — Quick access to current issues

Snapshot Capture

Capture memory snapshots from your running application:

Status Bar

Quick health indicator showing total memory and warning count:

$(pulse) FA: 7.0 MB | ⚠ 3

CodeLens Integration (v0.2.0)

Memory usage displayed directly above functions:

// $(pulse) Frame: 4.2 KB | Pool: 1.1 KB
fn update_physics(&mut self) {
    let collision_data = frame_alloc::<CollisionData>();
    // ...
}

• Shows frame and pool allocation sizes from runtime snapshots
• Click to open Memory Inspector panel
• Only appears on functions using framealloc patterns

Trend Graphs (v0.2.0)

Sparkline visualization in the sidebar showing memory usage over time:

Memory Trend: ▁▂▃▄▅▆▇█ (rising)

• Configurable history size (default: 30 snapshots)
• Color-coded: blue (stable), orange (rising), green (falling)
• Helps spot memory leaks and growth patterns instantly

Budget Alerts (v0.2.0)

Toast notifications when memory budgets exceed thresholds:

🟡 main_thread: 82.5% (1.65 MB / 2.0 MB)

• Configurable threshold (default: 80%)
• Progressive alerts at 80%, 90%, 95%, 100%
• Click "Show Details" to jump to Memory Inspector

Requirements

• VS Code 1.85.0 or later
• cargo-fa installed and in PATH
• Rust project using framealloc

Installing cargo-fa

cargo install cargo-fa

Or from the framealloc repository:

cd cargo-fa && cargo install --path .

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "FA Insight"
4. Click Install

From VSIX

code --install-extension fa-insight-0.2.0.vsix

From Source (Development)

git clone https://github.com/YelenaTor/fa-insight.git
cd fa-insight
npm install
npm run compile

Then press F5 in VS Code to launch the Extension Development Host.

Manual Installation from Git

If you want to build and install the extension yourself:

# Clone the repository
git clone https://github.com/YelenaTor/fa-insight.git
cd fa-insight

# Install dependencies
npm install

# Build the extension
npm run compile

# Package as VSIX
npx vsce package --allow-missing-repository

# Install the VSIX
code --install-extension fa-insight-*.vsix

To update later:

cd fa-insight
git pull
npm install
npm run compile
npx vsce package --allow-missing-repository
code --install-extension fa-insight-*.vsix --force

Configuration

Commands

Diagnostic Codes

FA Insight surfaces diagnostics from cargo-fa:

Run FA Insight: Explain Code or click a diagnostic code to see detailed explanations.

Runtime Integration

To enable snapshot capture, add to your framealloc configuration:

# Cargo.toml
[dependencies]
framealloc = { version = "0.6", features = ["snapshots"] }

// In your app
let config = AllocConfig::default()
    .with_snapshots(true)
    .with_snapshot_dir("target/framealloc");

The extension watches the snapshot directory and updates automatically.

Snapshot Schema

Snapshots are JSON files with this structure:

{
  "version": 1,
  "frame": 18421,
  "summary": {
    "frame_bytes": 4194304,
    "pool_bytes": 2097152,
    "heap_bytes": 1048576,
    "total_bytes": 7340032,
    "peak_bytes": 8388608
  },
  "threads": [...],
  "tags": [...],
  "promotions": {...},
  "diagnostics": [...]
}

See DESIGN.md for the complete schema specification.

Troubleshooting

"cargo-fa is not installed"

Install cargo-fa:

cargo install cargo-fa

No diagnostics appearing

1. Ensure your project uses framealloc
2. Check that analysis checks are enabled in settings
3. Try running cargo fa --all manually

Snapshots not updating

1. Ensure your app has snapshots enabled
2. Check the snapshot directory path matches your config
3. Verify the directory exists and is writable

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT OR Apache-2.0, at your option.

Related

• framealloc — The memory allocation library
• cargo-fa — Static analysis CLI tool
• TECHNICAL.md — Architecture documentation