Detector architecture v2: static engine, benchmarks, lab, and visual contrast

[pbakaus]

Summary

This PR turns the detector work into a much more explicit architecture, with the speed and inspection tooling needed to keep improving it safely.

Detector architecture

• Refactors the old detector monolith into focused modules for the registry, shared utilities, pure rule checks, profiling, CLI wiring, source/regex scans, static HTML/CSS scans, browser URL scans, injected browser runtime, and screenshot-based visual contrast.
• Keeps the public API facade intact through cli/engine/detect-antipatterns.mjs while moving implementation into cli/engine/engines/*, cli/engine/rules/*, cli/engine/shared/*, and cli/engine/browser/injected/*.
• Updates browser and extension builds to generate from the browser injected entry instead of stripping Node sections out of the old universal file.
• Moves build-time rule metadata reads to the detector registry instead of scraping the monolithic source file.

Static HTML/CSS engine

• Replaces the local HTML detection path with a fast static HTML/CSS parser stack: htmlparser2, css-select, css-tree, and domutils.
• Removes the jsdom-based path and keeps static analysis intentionally layout-free.
• Preserves detector-needed cascade behavior: linked local stylesheets, @layer flattening, selector matching, specificity/source order, !important, inline styles, variables/fallbacks, inherited typography properties, and needed shorthand expansion.

Browser, visual contrast, and extension behavior

• Adds createBrowserDetector() for warm browser reuse while keeping one-shot detectUrl() compatibility.
• Splits pure detection from overlay rendering with window.impeccableDetect() / window.impeccableDetectAsync() and window.impeccableScan() / window.impeccableScanAsync().
• Adds browser-first visual contrast analysis and pixel-diff screenshot fallback for hard cases like image backgrounds.
• Adds lazy in-browser visual contrast resolution for offscreen candidates and keeps extension-mode async visual contrast errors visible to the panel.

Benchmarks and detector lab

• Adds scripts/benchmark-detector.mjs plus bench:detector and bench:detector:browser scripts.
• Reports per-engine, per-phase, per-rule, per-target timing through the new profiling API.
• Adds the internal /detector workbench for navigating antipattern fixtures, running scans in an iframe, viewing findings, and seeing timing at a glance.
• Keeps benchmark output observational only; no hard budgets yet.

Validation

• bun run test
• bun run build:browser
• bun run build:extension
• bun run build:skills
• bun run build:site
• bun run bench:detector -- --quick
• bun run bench:detector:browser -- --quick
• git diff --check

Notes

• Local validation was run outside the sandbox where needed for Puppeteer/headless Chromium and repo build workflows.
• Rust/Go remains deferred; this branch focuses first on architecture, browser lifecycle, static parser reliability, visual contrast correctness, and measurable performance.

---

Note

Medium Risk
Medium risk because it introduces a new CLI entry path and substantially expands the in-browser detector runtime (overlay lifecycle + optional visual contrast sampling), which can affect scan accuracy/performance and extension messaging behavior.

Overview
Refactors the detector’s entrypoints and browser runtime toward a modular architecture. Adds a new CLI implementation (cli/engine/cli/main.mjs) that supports scanning stdin/files/dirs/URLs, optional --fast regex-only mode, JSON output, dev-server detection hints, large-scan confirmation, and import-graph annotations in output.

Overhauls the browser/extension injected detector runtime. Introduces cli/engine/browser/injected/index.mjs and updates the generated detect-antipatterns-browser.js to build from it, adding async scan/detect APIs (impeccableDetect*, impeccableScan*), overlay lifecycle cleanup, extension-safe error posting, configurable auto-scan, and an optional visual contrast pass that samples rendered backgrounds (incl. images/gradients) with lazy offscreen resolution.

Dependency changes: removes jsdom and adds a static parsing stack (htmlparser2, css-select, css-tree, domutils) reflected in bun.lock, alongside minor version shifts (e.g., entities, parse5, undici).

^{Reviewed by Cursor Bugbot for commit 72d7e57. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cloudflare-workers-and-pages]

Deploying impeccable with    Cloudflare Pages

Latest commit:	72d7e57
Status:	✅  Deploy successful!
Preview URL:	https://0a7319f9.impeccable-2rv.pages.dev
Branch Preview URL:	https://codex-detector-v2-speed-visu.impeccable-2rv.pages.dev

View logs

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d9b7070. Configure here.}

[cursor]

Remove handler misses lazy visual contrast observer cleanup

Medium Severity

The 'remove' action handler manually cleans up overlays but doesn't call disconnectLazyVisualContrastObserver() or increment scanGeneration. The clearOverlays() function does both, but the remove handler reimplements cleanup without these. If the lazy visual contrast IntersectionObserver is active, its pending resolutions can still fire, pass the staleness check (generation !== scanGeneration remains equal), call highlight() to append new overlays, and send stale findings to the extension panel — all after the user has explicitly removed everything.

Additional Locations (1)

• cli/engine/detect-antipatterns-browser.js#L3952-L3963

 

^{Reviewed by Cursor Bugbot for commit d9b7070. Configure here.}