Scalus Profile — VS Code extension

Annotate your Scala source with Scalus CEK-machine profiling cost, right in the editor, and open the full interactive profile report in a panel.

When you profile a Scalus smart contract, the evaluator emits a machine-readable profile.json (per-source-location and per-builtin cost, the control-flow edges, and the total budget). This extension reads that file and shows the cost inline on the source lines that produced it.

Per-line CEK cost annotations and heat backgrounds on a Scalus auction validator

Features

Inline cost annotations — each profiled line gets ⏱ <cpu> · <mem> · <count>× · <fee> lov at the end of the line.
Heat background — lines are tinted by their share of the selected metric (cpu or fee), so hot spots jump out.
Hover breakdown — hover a profiled line for its totals, the builtins invoked there, and the hottest control-flow edges leaving it.
Status bar — total CEK budget and on-chain fee; click to open the full report.
Open Report — loads the self-contained interactive HTML report (sortable tables, hot paths, annotated source) into a webview.
Auto-refresh — re-reads the profile when your tests regenerate it.

Producing a profile

From a Scalus project, run an evaluation with profiling enabled. The simplest way is the environment switch:

SCALUS_PROFILE=full <your test/run command>

For every profiled script run this writes, into the report output directory (SCALUS_DUMP_DIR, default: target/scalus):

<scriptHash>-<tag>-<index>.profile.html – the interactive report
<scriptHash>-<tag>-<index>.profile.json – machine-readable data ("schemaVersion": 1)
<scriptHash>-<tag>-<index>.profile.csv – flat table
profile-manifest.json – the discovery entry point listing every run

The extension reads profile-manifest.json first (schema version 1, checked): each run appears in the profile picker labelled by script hash, redeemer and Plutus version, and "Open Report" opens the HTML report belonging to the selected run. Without a manifest (older Scalus), the extension falls back to scanning for *profile*.json files, newest first – e.g. ones written directly with:

ProfileFormatter.writeJson(profile, "target/my-profile.json")
ProfileFormatter.writeHtml(profile, "target/my-profile.html") // optional, for the report panel

The JSON file paths are absolute source paths captured at compile time; the extension matches them to your open files by trailing path segments, so a profile generated on CI still lines up.

Usage

Open your Scalus project folder in VS Code.
Generate a profile (above). The extension auto-discovers it via profile-manifest.json (or the newest *profile*.json when there is no manifest).
Open a profiled .scala file — annotations appear on the costed lines.
Run Scalus Profile: Open Report from the Command Palette for the rich view.

Commands

Command	Description
`Scalus Profile: Open Report`	Open the HTML report in a webview
`Scalus Profile: Reload Profile Data`	Re-read the profile JSON
`Scalus Profile: Toggle Inline Annotations`	Show/hide inline cost text
`Scalus Profile: Select Profile File`	Pick among the manifest's profile runs (or loose `profile.json` files)

Settings

Setting	Default	Description
`scalusProfile.manifestGlob`	`**/profile-manifest.json`	Where to find the profile manifest (source of truth when present)
`scalusProfile.jsonGlob`	`*/profile*.json`	Fallback: where to find the profile JSON (newest wins)
`scalusProfile.htmlGlob`	`*/profile*.html`	Where to find the HTML report
`scalusProfile.metric`	`cpu`	Primary metric: `cpu` or `fee` (fee falls back to cpu when unpriced)
`scalusProfile.showInline`	`true`	Inline per-line annotations
`scalusProfile.showHeat`	`true`	Line heat backgrounds
`scalusProfile.minPercent`	`0`	Only annotate lines ≥ this % of the file's hottest line
`scalusProfile.heatColor`	`220,40,40`	Base RGB for the heat tint

Development

npm install
npm run compile      # bundle to dist/extension.js (esbuild)
npm run typecheck    # tsc --noEmit
npm run vsce:package # build a .vsix

Press F5 in VS Code to launch the Extension Development Host. Open the fixtures/ folder (or any Scalus project) — fixtures/sample-profile.json and sample-profile.html are real output from the Scalus auction example, so you can see the annotations and report immediately.

License

Apache-2.0

Scalus Profile

Lantr