Architectural Quality

The quality engine reduces a workspace to one continuous quality_signal in the 0–10000 band, computed as the geometric mean of six graph- and function-level metrics. Scans run on demand from the desktop panel, the loop quality scan CLI, the quality_scan MCP tool, or — when enabled — automatically after each agent file edit.

Design is inspired by sentrux (Rust, MIT). Algorithms are clean-room Go re-implementations under internal/quality/.

Related docs: Configuration | HTTP API | Events System | MCP Server | Commands

What the signal measures

Each metric returns a Score in [0, 1]; quality_signal is round(10000 * geo_mean(scores)). See internal/quality/metrics/signal.go. The standalone clones sub-metric (clusters, duplicated/total LOC) is exposed separately via quality_clones and GET /quality/clones; it is folded into Redundancy at the headline level so the geomean factor count stays at six.

Languages

The active grammar set is pinned in internal/quality/grammars.go:

• Go — internal/quality/parser/queries/go.scm
• TypeScript — internal/quality/parser/queries/typescript.scm
• JavaScript — internal/quality/parser/queries/javascript.scm

Files in other languages are enumerated and counted toward quality.max_files but are skipped at parse time and reported via the parse_failed counter. To add a language: append to ActiveLanguages in grammars.go, vendor the upstream tree-sitter tags.scm plus any quality-specific captures into internal/quality/parser/queries/<lang>.scm, and add fixtures under internal/quality/parser/testdata/.

For each parsed function, the parser also runs a tree-sitter body walk (internal/quality/parser/bodywalk.go) that produces a FunctionBody fact — decision points, cognitive load, max nesting, parameter count, LOC, and a normalised shingle list. The Complexity and Clones metrics consume these directly; languages without a body-walk pass simply skip those metrics.

The parser is github.com/odvcencio/gotreesitter — a pure-Go tree-sitter runtime, MIT-licensed. No CGO; cross-compiles to every Go target supported by Loop.

Configuration

Quality is driven by quality.* keys in ~/.loop/config.json and per-project .loop/config.json. See Configuration: Quality .

"quality": {
  "max_files": 25000,                  // hard cap; over this returns RepoTooLarge
  "exclude_paths": ["docs/**"],        // appended to .gitignore + built-in defaults
  "complexity": {                      // per-dimension soft thresholds; 0/omit = use default
    "cyclomatic_t": 10,
    "cognitive_t":  15,
    "nesting_t":    4,
    "params_t":     5,
    "loc_t":        60
  },
  "clones": {                          // SimHash clone detector
    "min_loc":      5,                 // skip functions smaller than this
    "max_distance": 3                  // 0 = exact, up to 64
  },
  "rules": {
    "signal_floor":            { "enabled": true, "threshold": 5000 },
    "parse_fail":              { "enabled": true, "threshold": 0.01 },
    "no_import_cycles":        { "enabled": true },
    "complexity_ceiling":      { "enabled": true, "threshold": 10 },
    "complexity_score_floor":  { "enabled": true, "threshold": 0.5 },
    "duplication_ceiling":     { "enabled": true, "threshold": 0.10 }
  }
}

Built-in path exclusions (always applied): .git/, node_modules/, dist/, build/, target/, vendor/, *.min.js, *.generated.go (see internal/quality/graph/enumerate.go). The repo’s .gitignore is layered on top, then quality.exclude_paths is appended.

Config changes drop the engine’s parser/graph cache for the affected channel but do not auto-trigger a rescan — the panel keeps rendering the previous snapshot until the next manual scan rebuilds with the new config.

Snapshots

One row per (channel_id, branch) is persisted in the quality_snapshots table:

Manual “Scan now” and live-rescan both upsert for the current branch. Other branches’ snapshots are preserved (switching branches doesn’t lose data). Rows older than 7 days are pruned on engine start. See internal/quality/snapshot/snapshot.go.

When the panel asks for a snapshot whose branch differs from the current branch, the API returns the most recent row with branch_mismatch: true so the UI can render a banner.

Rules

Six built-in rules ship enabled by default. Each emits structured citations consumable by the panel and any future rules MCP tool.

Per-rule overrides go under quality.rules.<name>.{enabled,threshold} (project config and global config both honored). Rule pass/fail is data, not behavior: the CLI exits 0 regardless. CI gates on the JSON output:

loop quality scan --json | jq -e '.rules.failed | length == 0'

Surfaces

Desktop panel

QualityPanel.tsx (app/src/components/panels/QualityPanel.tsx). Available as a per-channel split-pane panel; opens via the + panel switcher or the chat-bar quality indicator.

Layout, top to bottom:

1. Headline — the absolute signal is the primary number (48px, band-coloured: red < 5000, amber 5000–7000, green > 7000). Once at least two scans exist for the current (channel, branch) the change since the last scan rides alongside as a secondary chip prefixed with Δ (green for improvement, red for regression). On the first scan there is no chip — the absolute number stands alone. The underlying previous_signal field is also exposed on the quality.scanned event payload so consumers can render the delta without re-fetching the snapshot.
2. Tabs — Overview (metric cards + treemap), Diagnostics (per-tile breakdown), Hotspots (function-level complexity + clone clusters), Cycles (Tarjan SCC list), Evolution (git-history coupling, churn, bus-factor), What-if (mutation simulator), C4 (Mermaid).
3. Metric cards — one per metric (Modularity, Cycles, Depth, Equality, Redundancy, Complexity) with current value.
4. Treemap — @visx/hierarchy binary treemap. Tile size = file LOC, tile color = per-file deficit (red = drag on signal, green = healthy). Clicking a tile selects it for the popover.
5. Diagnostic popover — opens when a tile is selected; shows path, LOC, top-reason metric, and per-metric deficit breakdown for that file (including complexity drag).
6. Hotspots tab — worst-first complex functions with score, band-coloured severity, and per-dim breakdown (cyc / cog / nest / params / LOC); plus collapsible clone-cluster cards listing each member function, total LOC, and worst pairwise Hamming distance. Both lists page via ?limit= / ?offset=.
7. Failed rules — citation cards for any failing rule.

Empty state (no snapshot ever scanned for this channel) renders a centered “Scan now” button plus a one-line explainer. Loading state during a scan dims the previous snapshot and shows Scanning… <done>/<total> driven by quality.scan_progress events (throttled to ~250 ms, with a guaranteed first and terminal tick).

The chat-bar quality indicator (app/src/components/chat/QualityIndicator.tsx) renders as a round dot in the input toolbar. Outline before the first scan; filled with the band color after. Clicking it adds a quality leaf to the channel’s split-pane tree (lands on the empty-state if no snapshot exists).

CLI

loop quality scan      [path]                    [--max-files <n>] [--json]
loop quality cycles    [path]                    [--max-files <n>] [--json]
loop quality whatif    [path] --file <muts.json> [--max-files <n>] [--json]
loop quality evolution [path] [--since-months N] [--max-commits N] [--json]
loop quality c4        [path]                    [--max-files <n>] [--json]

All subcommands run a one-shot scan of [path] (defaults to CWD). --json emits the same payload as the matching MCP tool / HTTP endpoint. Exit code 0 unless the engine itself crashes — rule pass/fail (for scan) is data in the output.

• scan — full scan; prints the signal + metric breakdown.
• cycles — lists Tarjan SCCs > 1 file.
• whatif — reads a JSON mutation list ({op, path, new_module?, parts?} or array) from --file <path> (use - for stdin) and prints the predicted Δ signal.
• evolution — git log over the configured window (default 12 months / 1000 commits) for coupling, churn, and bus-factor signals. Requires git on PATH.
• c4 — emits a Mermaid flowchart clustered by Go package (file directory), with top-level segments wrapped in subgraph blocks.

Useful for CI gates and ad-hoc inspection without running the daemon.

MCP tools

All tools read channelID from the per-channel MCP server struct; they take no WorkDir argument.

HTTP

There is no auth — endpoints are intended for local Electron only, like every other /api/* route.

Events

All quality events use the standard 2-segment noun.verb format and are scoped to a channel_id.

See Events System for subscription details.

Triggering scans

There is no live-rescan loop. Scans run on demand:

• Panel — the per-channel Quality panel exposes a “Scan now” button.
• CLI — loop quality scan [--json] from the workdir.
• MCP — the agent calls the quality_scan tool (per-channel).

Repo-too-large guard

If, after applying built-in defaults + .gitignore + quality.exclude_paths, the remaining file count exceeds quality.max_files (default 25000), the engine refuses the scan and returns a structured RepoTooLargeError. The MCP tool, HTTP endpoint, and CLI surface this verbatim.

The cap is checked once at the start of file enumeration — no partial scan is produced. The panel’s empty-state banner asks the user to add patterns to quality.exclude_paths or raise quality.max_files.

Coalescing concurrent scans

The engine holds one in-flight cancel function per channel_id. A second quality_scan arriving while a scan is running returns {status: "in_progress"} immediately — no queue, no cancel-and-replace. The panel disables its “Scan now” button on quality.session_started and re-enables on quality.scanned / quality.session_ended / quality.scan_cancelled.

DELETE /api/channels/{id}/quality/scan invokes the cached cancel function — the engine returns context.Canceled, the daemon emits quality.scan_cancelled, and the partial state is discarded. Returns 404 if no scan is running.

Package layout

internal/quality/
├── doc.go                  # package overview
├── grammars.go             # active gotreesitter grammar pin
├── engine/                 # entry point: Scan() orchestrates parser→graph→metrics→snapshot
├── parser/                 # tree-sitter wrapper + .scm queries (go/ts/js)
│   └── queries/
├── graph/                  # file enumeration, .gitignore, dependency graph + cache
├── metrics/                # 5 metrics + signal aggregation + tile attribution
├── rules/                  # 3 built-in rules + per-rule config
├── snapshot/               # SQL-backed persistence (sql_store.go)
├── whatif/                 # shadow-graph mutation simulator + predicted Δ signal
├── evolution/              # git-log coupling / churn / bus-factor analysis
└── c4/                     # Mermaid flowchart emitter (Component layer)

Development

# Unit tests for the engine packages
go test ./internal/quality/...

# Local one-shot scan against the current repo
go run ./cmd/loop quality scan --root .

Coverage gate (make coverage-check) runs over the entire tree, including all of internal/quality/.... The parser package exposes a parser.Parser interface so unit tests run without invoking gotreesitter on every iteration.