SUPEREC for Visual Studio Code

Sealed system maps, beautifully navigable: instant validation with stable codes, resource cards on hover, graph navigation, diagram preview, bounded context packs, and evidence-cited queries for .superec records.

Features

Model Explorer sidebar

A dedicated SUPEREC view in the Activity Bar: resources grouped by kind, relationships as readable "A → B" entries, and findings sorted by severity. Package rows expose version truth immediately: a resolved lock version, a requested constraint when no resolution is known, multiple-constraint status, or an explicit version unknown. Hover a package for a safe detail card with resolved version, every requested constraint, ecosystem, consumer count, and stable ID. Each click still jumps to the exact document fact.

One-click action hub

The status bar item shows live graph stats (resources·relationships, plus a findings badge). Click it - or press Ctrl+Alt+M - for every SUPEREC action in one quick-pick menu. Ctrl+Alt+D opens the diagram.

Instant validation

Open any .superec file - the status bar shows live validity, or SUPEREC: <error-code> when something is wrong. Problems are in the Problems panel with stable codes and precise locations. All validation is in-process (zero latency, fully offline, no CLI needed). Validate Workspace sweeps every .superec file in the project at once.

Architecture Insights

One click produces a Markdown report of coupling hotspots, potential single points of failure, orphan resources, dangling references, open findings by severity, and modelling gaps - clues for improving both the map and the architecture it describes. Fully offline.

AI-native (MCP)

Set Up AI Integration writes a .mcp.json entry so Claude Code and any MCP client get 9 tools over the map: validate, list resources, inspect a node, blast radius, insights, policy check, and sealed writes (add resource, connect, record finding). Every read verifies the integrity digest first and every write re-seals, so an agent can neither act on nor produce a tampered map. Plus one-click bounded context packs for LLM context windows.

Never stale, always enforced

Check Drift compares the sealed map against what workspace discovery currently finds and reports missing items, version mismatches, and possibly-removed resources, with one-click import of what's missing. Add a Policy embeds architecture rules in the document (forbidden relationships, required owners/versions, fan-in limits, SHA-pinned CI actions) - enforced live as diagnostics, in Insights, and by the CI gate.

Review-ready

What Changed? (Diff vs Git) renders the architecture delta against any revision: added, removed, and changed resources, relationships, and findings - perfect for PR review. Record a Finding… logs risks against resources through a guided flow. A CI gate (npx tsx scripts/validate-map.ts) fails the build on a broken or tampered map. Diagram nodes are clickable: jump straight to the resource's definition.

Import and synchronize your workspace

Import from Workspace proposes your git remote, submodules, npm dependencies, and GitHub Actions as map resources with edges, using local files only. Review, confirm, sealed. The extension never connects to repositories or the network and never dereferences URLs found inside documents.

For .NET workspaces, the bundled SUPEREC exporter is authoritative. It discovers every .csproj, .fsproj, and .vbproj, models projects as build units, preserves ProjectReference topology, resolves package declarations from project and central/build/version .props files, and reads lock evidence when available. Large solutions are not capped or flattened into one box.

After the initial map exists, run Sync System Map with Source. SUPEREC shows an add/update/remove preview before changing anything, refreshes source-owned resources, relationships, findings, and package versions, removes stale source-only facts, preserves authored resources, evidence, policies, and extensions, then re-seals the complete map. The editor change remains reviewable and undoable before save.

Made for humans - no JSON required

Create a New System Map (also on the folder right-click menu) scans the selected folder's local manifests and creates a schema-valid, sealed map with the repository, direct dependencies, container bases, and CI actions already connected. A project no longer starts as an unexplained single box. Add a Resource… and Connect Two Resources… are fully guided - pick a kind, type a name; IDs, required fields, and the digest are handled automatically. A Getting Started walkthrough opens on install.

Automatic integrity

The RFC 8785 / SHA-256 digest is re-sealed automatically on every save (formatting preserved; opt out with superec.resealOnSave). Graph-aware warnings flag unknown resource references inline, and the light-bulb quick fix repairs a stale digest in place.

Export professional reports (PDF)

Export Report produces a polished, self-contained HTML report - title block, stats, coupling hotspots, single points of failure, open findings, full inventory, and the architecture diagram embedded (when the CLI is available). It opens in your browser: Ctrl+P → Save as PDF.

Resource cards on hover

Hover any superec:-prefixed ID in the document - a card shows the resource kind, name, version, ecosystem, edge counts, and findings citing it.

Graph navigation (Go to Definition)

Ctrl+Click any resource ID (from, to, subjects, id) to jump to the resource's "id" definition in any workspace .superec document.

Document outline

Ctrl+Shift+O shows Resources, Relationships, and Findings with kind icons and short labels - navigate the graph structure in one keystroke.

CodeLens actions

Each resource gets ◉ Inspect Node and ◎ Blast Radius lenses; the top of the file gets ▶ Diagram Preview and ⧉ Context Pack.

Interactive diagram canvas

The theme-aware, offline canvas automatically fits every page to the available viewport. Disconnected inventory pages are packed into a responsive grid based on the viewport aspect ratio and actual box sizes, avoiding unreadable single lines. Zoom from a whole-system overview to individual boxes with the toolbar or Ctrl/Cmd + mouse wheel; select the percentage for 100%, or Fit at any time.

Select Arrange to pack any page efficiently into the current viewport. Boxes remain draggable and keyboard-movable; the first manual move stops responsive reflow, connected paths and labels follow live, and the arrangement is remembered per atlas page. Original restores Mermaid's generated layout. A click still jumps to the resource definition. SVG and PNG exports preserve the complete arrangement with safe large-canvas bounds.

Every native VSIX includes exactly one platform-matched SUPEREC CLI and verifies its packaged SHA-256 manifest before use. Native packages cover Windows, Linux, Alpine, and macOS on x64 and ARM64. An explicit superec.cliPath and PATH remain safe fallbacks; without a CLI, the extension generates the diagram in-process.

Large maps automatically open as a semantic-zoom Architecture Atlas: start at the bounded landscape, search thousands of pages or resource IDs, drill into typed relationship topology by clicking a node, and move with breadcrumbs plus Home/Previous/Next controls. Pages load lazily and are SHA-256 verified before rendering. A broken page cannot break navigation; oversized or future detail stays visible as an explicit black-box boundary.

Context pack + digest copy

One-click copy of a bounded, LLM-ready context pack (Markdown) or the SHA-256 digest to your clipboard.

Graph queries

Run node inspection or blast-radius from the editor or CodeLens - results appear in the SUPEREC Output channel with evidence citations.

Installation

From source (development)

cd vscode-superec
npm install
npm run sync-sdk    # vendors the TypeScript SDK from ../super/typescript
npm run compile      # esbuild extension + interactive viewer; copy Mermaid/assets
npm test             # unit tests (node:test, zero deps beyond installed)

Press F5 in VS Code to launch an Extension Development Host with the extension loaded. Open any .superec file to activate.

VS Code Marketplace and Auto Update

Install vic-e-com.superec-vscode from the VS Code Marketplace. With Extensions: Auto Update enabled, VS Code downloads each compatible newer release. Select Restart Extensions when offered to activate the downloaded version without closing the whole editor.

Every public update is produced from a signed vMAJOR.MINOR.PATCH tag. The release workflow rejects reused, older, or mismatched versions and publishes the same verified packages to GitHub Releases and Marketplace.

GitHub Release or local VSIX

GitHub Releases and Marketplace provide native packages for win32-x64, win32-arm64, linux-x64, linux-arm64, alpine-x64, alpine-arm64, darwin-x64, and darwin-arm64. VS Code selects the correct Marketplace package automatically.

Windows x64 releases also include a cache-safe installer. Download the versioned Windows x64 VSIX and install-local.ps1 or install-local.bat into the same folder. Close every VS Code window, then run the installer from an external terminal; it discovers the VSIX beside itself.

.\install-local.ps1

For a development build:

npx vsce package --target win32-x64
.\scripts\install-local.ps1 -OpenPath .

The installer refuses to run while Code.exe is active, verifies extension identity and the latest Activity Bar icon packaged from the tagged source, removes only the verified prior extension directory, installs the VSIX, validates the installed files, and starts a genuinely fresh VS Code process.

Configuration

Documentation

• User Guide - every feature, command, shortcut, and workflow, including what the Insights clues mean
• Architecture & Design - module map, layer model, build system, testing, security
• Comparison - how SUPEREC stacks up against Structurizr, LikeC4, IcePanel, D2, and PlantUML
• AGENTS.md - quality requirements for contributors
• Release Guide - signed tags, GitHub Releases, Marketplace publishing, Auto Update
• Changelog - user-visible changes by extension version
• scripts/README.md - CI build and publish scripts

Architecture

• In-process validation: vendored TypeScript SDK (zero runtime deps) parses, validates, and inspects - instant, offline, no subprocess
• jsonc-parser: Microsoft's own tolerant JSON parser for location mapping, hover, definitions, and symbols
• CLI subprocess: verified platform-matched bundle, explicit override, then PATH; powers diagrams, context packs, and graph queries with graceful degradation
• Disposable-safe: every provider, timer, and panel is disposed on deactivation - zero leaks, zero orphaned listeners
• Full error handling: every code path logs to the SUPEREC Output channel and never crashes the editor

License

Copyright 2026 VIC-E.com. The VIC-E.com source code is licensed under Apache-2.0, including its explicit patent grant.

The code license does not grant rights to VIC-E.com names, logos, or product branding. See NOTICE and the trademark policy. Licenses and required attribution for bundled dependencies are preserved in Third-Party Notices.