Sonic Code Sentinel (sonic-boom)

Sonic Code Sentinel encodes an entire TypeScript / JavaScript codebase into a single PNG heatmap that vision-capable AI models can read in one glance — bypassing token limits for codebase-scale audits.

The image is a deterministic function of the AST: same code → byte-identical pixels. Each pixel encodes a category (via color) and severity (via brightness), so the picture itself is the audit summary — no separate lookup required.

---

🎵 The Spectrogram

The codebase is laid out as a 2D heatmap.

graph LR
    Code[Source Code] --> Scanner[AST Scanner]
    Scanner --> Map[Deterministic Color Map]
    Map --> PNG[Spectrogram PNG]
    PNG --> AI[Vision AI Model]
    AI --> Fix[Surgical Code Fix]

🗺️ Coordinate Mapping

• X-Axis: Each file occupies a contiguous horizontal slot. Within a slot, X is proportional to the line number of the node.
• Y-Axis: Partitioned into four bands (see below). Within the top ANOMALY band, each Y-row is reserved for one concern — turning the band into a row-per-category heatmap.
• Color: Encodes the anomaly category (see catalog below).
• Brightness (Amplitude): Encodes severity — high is brightest (1.0), med is mid (0.75), low is dim (0.5). Structural (non-anomaly) pixels fade with nesting depth.

🌈 Frequency Bands

Hz Range	Layer	Content
20 – 8 k	LOGIC	Source files (.ts, .tsx, .js, .jsx)
8 k – 12 k	STYLES	Stylesheets (.css, .scss, .less)
12 k – 16 k	MARKUP	Markup assets (.svg, .html, .md)
16 k – 20 k	ANOMALY	Per-category rows for detected concerns

---

🔬 Detected Anomalies

13 categories. Each has a stable Hz row, a stable color, and a fixed severity — so the heatmap is readable without consulting the mapping table.

Category	Severity	Detection
Empty catch block	high	catch (e) {} with empty body
Layer Violation	high	File under /components/ importing from /pages/
Massive Component	high	.tsx / .jsx with > 250 lines
Prop Overload	high	Interface ending in Props with > 7 members (count surfaced in label)
Explicit : any type	med	Parameter, variable, or property typed any
Heavy Library Import	med	Imports moment, lodash, or jquery (name surfaced in label)
High Complexity	med (high if cc ≥ 20)	Function / method / arrow / class with cyclomatic > 5 or depth > 5 — label includes cc=N, depth=N
Heavy Barrel Export	med	index.ts / index.js with > 10 exports
Commented-out Code Block	med	Long comment block containing code-like characters
Z-Index Escalation	med	z-[N] or z-N where N > 1000
Unresolved TODO/FIXME	med	Leading comment matching `/TODO
Tailwind Magic Value	low	Arbitrary -[value] Tailwind class outside var(...)
Missing Test File	low	Source file with no sibling *.test.* or *.spec.*

🎨 Color Legend

Color	Category
White	Layer Violation
Bright Red	Empty catch block
Light Red	Explicit : any type
Purple	Heavy Library Import
Orange	Prop Overload
Amber	High Complexity (with 5-px horizontal spread for emphasis)
Gold	Massive Component
Dim Yellow	Heavy Barrel Export
Sky Blue	Z-Index Escalation
Cyan	Tailwind Magic Value
Bright Yellow	Unresolved TODO/FIXME
Grey	Commented-out Code Block
Dim Blue-Grey	Missing Test File

Below the ANOMALY band, structural pixels render green / blue / orange for the LOGIC / STYLES / MARKUP layers respectively.

---

🛠️ MCP Tools

Three tools, used as a pipeline.

Tool	Purpose
get_project_spectrogram	Generates the PNG + mapping table. Returns the PNG (base64), a severity-sorted top-10 anomaly summary, and the color legend.
resolve_sonic_coordinates	Translates (x, y) pixel coordinates into { file, line, type, category?, severity?, proximityMatch?, pixelDistance?, context }.
get_code_snippet	Fetches a 20-line context window for a given file + line.

Resolution behavior

• Strict snap: clicks within 12 px of an anomaly pixel resolve to that anomaly, including its canonical category and severity.
• Proximity fallback: a click that lands far from every anomaly in a non-empty file slot still resolves — to the closest in-slot anomaly, flagged with proximityMatch: true and a pixelDistance in pixels. Replaces the old "Could not resolve coordinates" dead end.

Workflow

1. Visualize: agent calls get_project_spectrogram over the repo root.
2. Read the heatmap: the vision model identifies a bright pixel cluster by color (e.g. amber row = High Complexity, white row = Layer Violation).
3. Resolve: resolve_sonic_coordinates(x, y) returns file, line, category, severity.
4. Snippet: get_code_snippet for the 20-line window.
5. Fix: apply patch.

---

🚀 Getting Started

Prerequisites

• Bun v1.1+

Install

bun install

CLI

Generate a spectrogram for any local directory:

# Scan a project
bun run src/index.ts ../path/to/project

# Exclude additional patterns
bun run src/index.ts ../path/to/project --exclude "**/tests/**"

# Resolve coordinates from a previously generated mapping
bun run src/index.ts fix --coords 150,400 --issue "describe the issue"

Outputs land in ./output/:

• spectrogram.png — the heatmap.
• mapping_table.json — per-pixel metadata used by the resolver (file, line, anomaly category, severity).

MCP server

Add to your MCP client config (e.g. Claude Desktop):

{
  "mcpServers": {
    "sonic-boom": {
      "command": "npx",
      "args": ["-y", "sonic-boom-mcp@latest"]
    }
  }
}

The MCP server stores its artifacts under <tmp>/sonic-boom-mcp/; tool calls pass directoryPath to identify the project root.

Inspect MCP locally

bun x npx @modelcontextprotocol/inspector bun run src/mcp-server.ts

Run tests

bun test

The suite covers ignore-file handling, every anomaly detection rule, scan determinism, and resolver round-trip behavior.

---

🧱 Design Properties

• Deterministic: same source → byte-identical PNG and mapping JSON across runs. No RNG anywhere in the scan or render pipeline.
• Heatmap by construction: color = category, brightness = severity, Y-row = concern. The image is the audit, not a decoration.
• Ignore-file aware: respects .gitignore, .npmignore, .dockerignore, .sonicignore, .eslintignore, .prettierignore, and .gcloudignore — both at the repo root and in any subdirectory. Built-in skip list: node_modules, .git, dist, .next, out, build, .vscode, .idea, output.

Sonic Code Sentinel — Hear the code. See the bugs.

---

📄 License

This project is licensed under the PolyForm Noncommercial License 1.0.0.

• Free for personal / non-commercial use: research, learning, hobby projects.
• Commercial use requires a separate commercial license — please contact the author for details.