Merge pull request #950 from d-zero-dev/worktree-proud-tickling-rose

Adopt Explicit Resource Management for using/dispose lifecycle

Author: YusukeHirao

packages/@d-zero/a11y-check-axe-scenario/package.json

@@ -7,6 +7,9 @@
 	"publishConfig": {
 		"access": "public"
 	},
+	"engines": {
+		"node": ">=24.11.0"
+	},
 	"type": "module",
 	"exports": {
 		".": {
@@ -30,11 +33,11 @@
 	},
 	"devDependencies": {
 		"axe-core": "4.12.1",
-		"puppeteer": "25.3.0"
+		"puppeteer": "25.5.0"
 	},
 	"peerDependencies": {
 		"axe-core": "4.12.1",
-		"puppeteer": "25.2.1"
+		"puppeteer": "25.5.0"
 	},
 	"repository": {
 		"type": "git",

packages/@d-zero/a11y-check-core/package.json

@@ -7,6 +7,9 @@
 	"publishConfig": {
 		"access": "public"
 	},
+	"engines": {
+		"node": ">=24.11.0"
+	},
 	"type": "module",
 	"exports": {
 		".": {
@@ -27,7 +30,7 @@
 		"@d-zero/shared": "0.22.5",
 		"ansi-colors": "4.1.3",
 		"color-contrast-checker": "2.1.0",
-		"puppeteer": "25.3.0"
+		"puppeteer": "25.5.0"
 	},
 	"devDependencies": {
 		"@d-zero/dealer": "1.10.4",

packages/@d-zero/a11y-check-scenarios/package.json

@@ -7,6 +7,9 @@
 	"publishConfig": {
 		"access": "public"
 	},
+	"engines": {
+		"node": ">=24.11.0"
+	},
 	"type": "module",
 	"exports": {
 		".": {
@@ -28,10 +31,10 @@
 		"ansi-colors": "4.1.3"
 	},
 	"devDependencies": {
-		"puppeteer": "25.3.0"
+		"puppeteer": "25.5.0"
 	},
 	"peerDependencies": {
-		"puppeteer": "25.2.1"
+		"puppeteer": "25.5.0"
 	},
 	"repository": {
 		"type": "git",

packages/@d-zero/a11y-check-scenarios/src/scenario2.ts

@@ -1,8 +1,10 @@
 import type { ScenarioOptions } from './types.js';
 import type { NeedAnalysis } from '@d-zero/a11y-check-core';
+import type { ConsoleMessage } from 'puppeteer';
 
 import { createScenario } from '@d-zero/a11y-check-core';
 import { Cache } from '@d-zero/shared/cache';
+import { disposableListener } from '@d-zero/shared/disposable-listener';
 import c from 'ansi-colors';
 
 const scenarioId = 'a11y-check/scenario02';
@@ -41,19 +43,27 @@ export default createScenario((options?: ScenarioOptions) => {
 			for (const selector of navigations) {
 				const logBase = `Finding "${selector}"`;
 				logger(`Finding "${selector}"`);
-				page.on('console', (msg) => {
-					const msgType = msg.type();
-					switch (msgType) {
-						case 'error': {
-							logger(`${logBase}: ${c.red(msg.text())}`);
-							break;
+				// `using` により、各ループ反復の終わりで確実にリスナーが解除される。
+				// ループ内で page.on('console', ...) するため、解除しないと
+				// selector の数だけリスナーが累積する。
+				using _consoleListener = disposableListener(
+					page,
+					'console',
+					(msg: ConsoleMessage) => {
+						const msgType = msg.type();
+						switch (msgType) {
+							case 'error': {
+								logger(`${logBase}: ${c.red(msg.text())}`);
+								break;
+							}
+							default: {
+								logger(`${logBase}: ${c.gray(msg.text())}`);
+								break;
+							}
 						}
-						default: {
-							logger(`${logBase}: ${c.gray(msg.text())}`);
-							break;
-						}
-					}
-				});
+					},
+				);
+				void _consoleListener;
 				const outerHTML = await page.evaluate((selector) => {
 					return [...document.querySelectorAll(selector)].map((el) => el.outerHTML);
 				}, selector);

packages/@d-zero/a11y-check/package.json

@@ -7,6 +7,9 @@
 	"publishConfig": {
 		"access": "public"
 	},
+	"engines": {
+		"node": ">=24.11.0"
+	},
 	"type": "module",
 	"exports": {
 		".": {

packages/@d-zero/a11y-check/src/spreadsheet.ts

@@ -16,6 +16,23 @@ export class SpreadsheetReporter {
 	// eslint-disable-next-line no-restricted-syntax
 	private constructor() {}
 
+	/**
+	 * `await using` 宣言のスコープ脱出時に呼ばれ、内部の {@link SheetTable} を
+	 * フラッシュする。バッファに未送信行が残ったままスコープを抜けてデータが
+	 * 欠損するのを防ぐ。
+	 * @example
+	 * ```ts
+	 * {
+	 *   await using reporter = await SpreadsheetReporter.setup(sheetUrl, sheetName);
+	 *   await reporter.report(violations);
+	 * } // スコープ脱出時に自動で内部 SheetTable の未送信バッファが flush される
+	 * ```
+	 */
+	async [Symbol.asyncDispose]() {
+		if (this.#table) {
+			await this.#table[Symbol.asyncDispose]();
+		}
+	}
 	async report(results: readonly Violation[]) {
 		if (!this.#table) {
 			throw new Error('Table is not created');

packages/@d-zero/anatomist/package.json

@@ -7,6 +7,9 @@
 	"publishConfig": {
 		"access": "public"
 	},
+	"engines": {
+		"node": ">=24.11.0"
+	},
 	"type": "module",
 	"exports": {
 		".": {
@@ -36,10 +39,11 @@
 	},
 	"dependencies": {
 		"@d-zero/beholder": "4.2.2",
+		"@d-zero/cli-core": "1.3.16",
 		"@d-zero/dealer": "1.10.4",
 		"@d-zero/puppeteer-page-scan": "4.6.8",
 		"@d-zero/shared": "0.22.5",
-		"puppeteer": "25.3.0"
+		"puppeteer": "25.5.0"
 	},
 	"repository": {
 		"type": "git",

packages/@d-zero/anatomist/src/cli.spec.ts

@@ -215,6 +215,8 @@ describe('runCli', () => {
 				return true;
 			}),
 			end: mockEnd,
+			// cli.ts の `await using outFile` が要求する Symbol.asyncDispose のスタブ
+			[Symbol.asyncDispose]: vi.fn(async () => {}),
 		} as never);
 		vi.mocked(runBatch).mockImplementation((_urls, options?: RunBatchOptions) => {
 			options?.onResult?.({
@@ -249,6 +251,7 @@ describe('runCli', () => {
 			end: vi.fn((callback: (error: Error) => void) => {
 				callback(new Error('disk full'));
 			}),
+			[Symbol.asyncDispose]: vi.fn(async () => {}),
 		} as never);
 
 		const stderr = new PassThrough();

packages/@d-zero/anatomist/src/cli.ts

@@ -8,6 +8,8 @@ import { createWriteStream } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import process from 'node:process';
 
+import { unwrapSuppressedError } from '@d-zero/cli-core';
+
 import { formatResultLine } from './format-output.js';
 import { parseArgs } from './parse-args.js';
 import { parseUrlList } from './parse-url-list.js';
@@ -134,9 +136,12 @@ export async function runCli(options: {
 		return 1;
 	}
 
-	const outStream: NodeJS.WritableStream = args.out
-		? createWriteStream(args.out)
-		: options.stdout;
+	// `await using` により、runBatch() が想定外の例外を投げてスコープを抜けても
+	// --out で開いたファイル記述子が確実に閉じられる（stdout の場合は outFile が
+	// undefined のままなので dispose は no-op — process.stdout を誤って
+	// close してしまうことはない）。
+	await using outFile = args.out ? createWriteStream(args.out) : undefined;
+	const outStream: NodeJS.WritableStream = outFile ?? options.stdout;
 
 	let hadError = false;
 	await runBatch(urls, {
@@ -158,24 +163,26 @@ export async function runCli(options: {
 		},
 		onError: (url, error) => {
 			hadError = true;
-			options.stderr.write(
-				`anatomist: failed to analyze ${url}: ${(error as Error).message}\n`,
-			);
+			// SuppressedError（using スコープ内で本体と dispose の両方が例外を投げた
+			// 場合）を分解し、定型メッセージの裏に隠れる根本原因を両方とも出力する
+			for (const cause of unwrapSuppressedError(error)) {
+				options.stderr.write(
+					`anatomist: failed to analyze ${url}: ${cause instanceof Error ? cause.message : String(cause)}\n`,
+				);
+			}
 		},
 	});
 
-	if (args.out) {
+	if (outFile) {
 		try {
 			await new Promise<void>((resolve, reject) => {
-				(outStream as ReturnType<typeof createWriteStream>).end(
-					(error?: Error | null) => {
-						if (error) {
-							reject(error);
-						} else {
-							resolve();
-						}
-					},
-				);
+				outFile.end((error?: Error | null) => {
+					if (error) {
+						reject(error);
+					} else {
+						resolve();
+					}
+				});
 			});
 		} catch (error) {
 			// Consistent with every other failure path here: report to stderr

packages/@d-zero/anatomist/src/run-batch.spec.ts

@@ -45,15 +45,37 @@ function makeSequentialDealMock() {
 }
 
 describe('runBatch', () => {
-	let mockPage: { close: ReturnType<typeof vi.fn> };
-	let mockBrowser: { newPage: ReturnType<typeof vi.fn>; close: ReturnType<typeof vi.fn> };
+	let mockPage: {
+		close: ReturnType<typeof vi.fn>;
+		[Symbol.asyncDispose]: ReturnType<typeof vi.fn>;
+	};
+	let mockBrowser: {
+		newPage: ReturnType<typeof vi.fn>;
+		close: ReturnType<typeof vi.fn>;
+		[Symbol.asyncDispose]: ReturnType<typeof vi.fn>;
+	};
 
 	beforeEach(() => {
-		mockPage = { close: vi.fn().mockResolvedValue() };
+		// `run-batch.ts` now uses `await using`, which requires a real
+		// `Symbol.asyncDispose` implementation — delegate to the existing
+		// `close` mock so assertions on `close` call counts stay meaningful.
+		mockPage = {
+			close: vi.fn().mockResolvedValue(),
+			[Symbol.asyncDispose]: vi.fn(),
+		};
+		mockPage[Symbol.asyncDispose].mockImplementation(async () => {
+			await mockPage.close();
+		});
+
 		mockBrowser = {
 			newPage: vi.fn().mockResolvedValue(mockPage),
 			close: vi.fn().mockResolvedValue(),
+			[Symbol.asyncDispose]: vi.fn(),
 		};
+		mockBrowser[Symbol.asyncDispose].mockImplementation(async () => {
+			await mockBrowser.close();
+		});
+
 		vi.mocked(launch).mockResolvedValue(mockBrowser as never);
 		vi.mocked(deal).mockImplementation(makeSequentialDealMock() as never);
 		vi.mocked(analyzePageLayout).mockReset().mockResolvedValue([]);