Skip to content

Commit 227676f

Browse files
authored
Share the Chrome launcher and retarget CdpClient onto deno-cri (#14835)
A Chrome driver has three layers: launch the process, transport CDP commands over the socket, and the task logic on top. The launcher and transport were each duplicated between mermaid's cri.ts and the axe scanner; this unifies both, leaving only the task logic (cri.ts's facade vs. scanCell) separate since their commands differ. - New shared launchChrome() in src/core/cri/launch.ts replaces both ad hoc launchers, fixing three failure-path bugs along the way: an unread stdout pipe that could block Chrome, a cri.ts error path that could hang awaiting cmd.status, and onCleanup handlers that leaked one per mermaid render since they can't be unregistered - axe's CdpClient now runs its CDP transport on the vendored deno-cri, the same client cri.ts uses, removing the third hand-rolled WebSocket implementation in the tree - CdpClient adds its own in-flight-send tracking on top of deno-cri, since deno-cri leaves in-flight commands unsettled forever on a dropped socket rather than rejecting them - registerForExitCleanup() now installs its own exit handler, closing a gap where a command that spawns a browser without shelling out (quarto call axe) could orphan the process on Ctrl-C - New tests/smoke/axe/axe-transport-failclosed.test.ts exercises fail-closed behavior against a real browser instead of a manual check - llm-docs/axe-scan-architecture.md updated to describe the shared launcher and transport No user-visible change. Verified via full unit/smoke suites, a byte-identical mermaid PNG render before/after, and a full quarto-web scan producing an identical finding set before/after. Follow-up to a review thread on #14815.
1 parent 5f85ecc commit 227676f

9 files changed

Lines changed: 1012 additions & 398 deletions

File tree

‎llm-docs/axe-scan-architecture.md‎

Lines changed: 49 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
main_commit: abc6a78ed
3-
analyzed_date: 2026-08-27
3+
analyzed_date: 2026-08-31
44
key_files:
55
- src/command/call/axe/cmd.ts
66
- src/command/call/axe/config.ts
@@ -11,6 +11,7 @@ key_files:
1111
- src/command/call/axe/conformance.ts
1212
- src/command/call/axe/report.ts
1313
- src/command/call/axe/readme.ts
14+
- src/core/cri/launch.ts
1415
---
1516

1617
# Axe Scan Architecture (`quarto call axe`)
@@ -97,29 +98,49 @@ scan.
9798

9899
## The scan stage: raw CDP, fail-closed cells
99100

100-
The driver is a ~150-line generic CDP client (`CdpClient` in `scan.ts`)
101-
with three capabilities: send a command and await its result, wait
102-
(cancellably) for one event, close. It is transport, not scan logic — the
103-
scanning is six CDP *commands* that `scanCell` sends through it (navigate,
104-
viewport override, media emulation, evaluate-with-`awaitPromise`, an
105-
on-new-document script, the load event), and those stay the scanner's
106-
responsibility under any refactor. Because the command surface is that
107-
small, there is no wrapper library; puppeteer-core is the named fallback if
108-
raw CDP gets painful.
109-
110-
quarto-cli's existing wrapper (`src/core/cri/cri.ts`, which drives Chrome
111-
for mermaid) was read and declined — but be precise about which part: its
112-
*facade* exposes mermaid's commands only (navigate/query/screenshot — no
113-
emulation, no `awaitPromise`, no per-command timeout, so a hung `axe.run()`
114-
would hang forever). Underneath that facade sits the vendored `deno-cri`
115-
library, itself a generic send-any-command client; retargeting `CdpClient`'s
116-
internals onto it (keeping the interface the tests stub) is the plausible
117-
future unification of the *transport*. The more valuable near-term share is
118-
the *launcher*: two exist in the tree (`launchScanBrowser` here,
119-
`criClient`'s spawn half there), `cri.ts` cross-refers here, and extracting
120-
one shared launcher is tracked follow-up work. Browser discovery is already
121-
shared: `getBrowserExecutablePath()` (`src/core/puppeteer.ts`) encodes
122-
`QUARTO_CHROMIUM` → installed `chrome-headless-shell` → system Chrome/Edge.
101+
Think of a Chrome driver as three layers — launcher, transport, task logic —
102+
because the answer to "why not reuse quarto's existing one?" is different at
103+
each. The launcher and the transport are now shared with `src/core/cri/cri.ts`,
104+
which drives Chrome for mermaid. The task logic never will be: mermaid's
105+
commands and the scanner's commands are different jobs.
106+
107+
**Launcher.** `launchChrome()` (`src/core/cri/launch.ts`) is the one place
108+
quarto's CDP drivers start headless Chrome — this scanner and cri.ts.
109+
(`src/core/puppeteer.ts` keeps a separate `puppeteer.launch()` path —
110+
`withHeadlessBrowser`, reached through `withPuppeteerBrowserAndPage` and
111+
`inPuppeteer` — which nothing outside that file enters today.) It owns the
112+
flag set, the
113+
`QUARTO_CHROMIUM_HEADLESS_MODE` escape hatch, stderr draining, exit cleanup,
114+
and the wait for the CDP endpoint; callers pass in only what they genuinely
115+
disagree about — `--hide-scrollbars` and a throwaway profile dir here (so a
116+
scan cannot attach to, or be short-circuited by, a Chrome the user already has
117+
running), `--renderer-process-limit=1` for mermaid. Browser *discovery* is
118+
shared a level up again: `getBrowserExecutablePath()`
119+
(`src/core/puppeteer.ts`) encodes `QUARTO_CHROMIUM` → installed
120+
`chrome-headless-shell` → system Chrome/Edge.
121+
122+
**Transport.** `CdpClient` in `scan.ts` has three capabilities: send a command
123+
and await its result, wait (cancellably) for one event, close. The socket
124+
under it is the vendored `deno-cri` (`src/core/cri/deno-cri/`), the same
125+
generic send-any-command client cri.ts connects with. `CdpClient` is the typed
126+
layer over it, and what it adds is the behaviour fail-closed cells depend on
127+
and `deno-cri` does not have: a dropped connection rejects every command still
128+
in flight, so a crashed tab fails one cell inside `--timeout` rather than
129+
hanging the scan. Because the command surface is so small there is no wrapper
130+
library on top; puppeteer-core is the named fallback if raw CDP gets painful.
131+
132+
What is still *not* reused is cri.ts's **facade**, and it is worth being
133+
precise about why: it exposes mermaid's commands only
134+
(navigate/query/screenshot — no emulation, no `awaitPromise`, no per-command
135+
timeout, so a hung `axe.run()` would hang forever). The cleaner end state,
136+
where cri.ts *exports* a typed transport as a core surface and the scanner
137+
consumes it, waits on the scanner's own needs settling — concurrent tabs in
138+
particular.
139+
140+
**Task logic** is the six CDP *commands* `scanCell` sends through the
141+
transport: navigate, viewport override, media emulation,
142+
evaluate-with-`awaitPromise`, an on-new-document script, the load event.
143+
Those stay the scanner's responsibility under any refactor.
123144

124145
**Cells fail closed.** A timeout, an evaluation error, a payload that is not
125146
an axe result, or a page that moved is an infrastructure failure in the
@@ -302,6 +323,10 @@ change the render path every `axe:` user hits.
302323
page selection.
303324
- `tests/unit/axe-scan-cell.test.ts` — transport fail-closed with a stubbed
304325
CDP client; slugs; URL encoding.
326+
- `tests/smoke/axe/axe-transport-failclosed.test.ts` — the other half, against
327+
a real browser: that a real `CdpClient` rejects at all when the connection
328+
goes, on both the close and the dropped-socket paths. Every wait has a
329+
deadline, because a hang is the failure being guarded against.
305330
- `tests/unit/axe-config.test.ts` — flag parsing and its errors.
306331
- `tests/unit/axe-report-readme.test.ts`, `axe-conformance-parity.test.ts` —
307332
the views and the mirrored labellers.

0 commit comments

Comments
 (0)