Glue audit and surface-mounting pass on the better-shape app repo

What they did

The author started from a branch (`mega/absorb-all`) where several absorbed pull requests had left finished work stranded: components existed but no route, menu, or shortcut could reach them; settings had no reader; event channels had only one side. They wrote `scripts/qa/audit-glue.mjs` to measure the class of problem — orphan modules, one-sided event channels, settings keys with no reader, duplicate exports — and separated modules imported only by their own tests from modules nothing imports at all. They then mounted the stranded surfaces (a Design tab, an All Changes tab, subagent cards, chat overflow menu, hunk staging controls, run controls in the status bar, Voice settings page, editor popout, Notifications menu), wired settings through a shared save pipeline (`lib/editor/save-pipeline.ts`) and editor options, and deleted 25 modules plus five tests that only covered deleted modules. A second script, `scripts/qa/probe-mounted-surfaces.cjs`, drove the real app in Chromium, asserted the mounted controls exist, failed on any console error, and wrote screenshots. The browser pass found four real defects (SSR/client mismatch on the Voice page, a null-project crash in the design tab, duplicate hover overlays in the all-changes diff, and a notifications menu with no mount), all fixed. They also recorded a GIF of the notifications flow and ran a full verification gate: lint, typecheck, 2910 vitest tests, build, skills verify, SonarCloud, npm audit, Rust tests, fmt, clippy, and 33 Playwright e2e tests.

How it went

Orphan modules went from 48 at the audit head to 33 after the mount pass to 0 at the final head; settings keys with no reader went to 0. All fast gates passed (lint strict, typecheck, 2910 tests, build, SonarCloud 0 issues, npm audit 0 vulns, Rust 449 tests, fmt and clippy clean), and 33 of 33 Playwright e2e tests passed locally. The browser probe passed nine steps with zero console errors. The GIF capture validated as PASS_WITH_WARNINGS only because OCR could not read captions back (tesseract not installed). The two Playwright CI jobs were flaky on the repo during the window — four of seven runs failed while every local run of the identical command passed — and the author flagged that the workflow's reporter writes no per-test annotations, so the failing spec was unnamed rather than guessed.

Worth knowing

`npm install` in the repo fails with `Cannot read properties of null (reading 'edgesOut')`, so the capture toolchain had to be installed under `/tmp`; `apt-get install ffmpeg gifsicle` fails without root, so a static ffmpeg came from npm. `npm run tauri:build` was not run (no Tauri toolchain in the sandbox). Playwright `@visual` baselines do not run in the sandbox because fonts differ from the recorded baselines. The audit's literal scan cannot see events listened dynamically in `settings.tsx`, so two workspace-trust events show as dispatch-only. The GIF is linked by workspace path rather than embedded because GitHub's PR API cannot upload a local binary.

Wiring

The audit script (`scripts/qa/audit-glue.mjs`) runs first and produces the work list: it walks the import graph rather than grepping basenames, because names like `types`, `tab`, `diff`, and `commands` collide across the tree. Mounting happens in the app shell — new-tab menu entries, palette commands (`app.design.open`), shortcut actions, and dynamic mounts in the workspace — with settings routed through `lib/editor/save-pipeline.ts` shared by both editors and editor options passed into CodeMirror. Deletion follows the import-graph verdict, with a mechanical fix to one styling invariant that read a deleted file and removal of QA script entries for deleted paths. Verification runs in order: `npm ci --ignore-scripts`, `npm run lint:strict`, `npm run typecheck`, `npx vitest run`, `npm run build:preview`, `npm run skills:verify`, `node scripts/qa/audit-glue.mjs`, then the Playwright probe against the preview build (`PROBE_URL=http://127.0.0.1:48922 node scripts/qa/probe-feature-wiring.cjs`), then `E2E_STATIC=1 playwright test --grep-invert @visual`, then the Rust gates (`cargo test --all-features`, `cargo fmt --check`, `cargo clippy -D warnings`). The probe and the e2e suite both consume the static bundle from `build:preview`, so the build must precede them.

Try it yourself

Audit this repo for glue that never got connected after a big merge, then fix the whole class rather than a sample. Steps: (1) write a script that scans every module for importers across app/, components/, core/, features/, lib/, tests/, e2e/, and scripts/, and separates modules imported only by their own tests from modules nothing imports; (2) scan settings keys for readers and event names for both a dispatch and a listener side; (3) list every component that exists but has no route, menu entry, shortcut, or palette command reaching it; (4) mount the stranded surfaces in the existing style (tokens only, no hex literals, sentence-case labels, aria-label on icon-only controls, visible focus, reduced motion, empty/loading/error states); (5) wire settings that have no reader through a shared pipeline; (6) delete modules nothing can reach, along with tests that only covered them, without changing any other test to make it pass; (7) write a browser probe that drives the real app, asserts each mounted control exists, fails on any console error, and writes screenshots; (8) run lint, typecheck, the full test suite, and the build, and report before/after counts for orphans, one-sided events, and unread settings keys.