@d-zero/archaeologist 3.5.9 → 3.6.0

package/README.md

@@ -8,6 +8,7 @@
 - 複数のデバイスサイズでスクリーンショットを撮影可能（7種類のプリセット + カスタム設定）
 - スクリーンショットは画像差分（ビジュアルリグレッション）を検出・出力します
 - HTMLの差分も検出します
+- 生HTMLソースの差分も検出します（ブラウザ不要）
 - レスポンシブデザインの差分検証に最適
 
 ## CLI
@@ -22,7 +23,7 @@ URLリストを持つファイルを指定して実行します。
 
 - `-v, --version`: バージョンを表示
 - `-f, --listfile <filepath>`: URLリストを持つファイルのパス（必須）
-- `-t, --type <types>`: 比較タイプの指定（`image,dom,text`、カンマ区切り）
+- `-t, --type <types>`: 比較タイプの指定（`image,dom,text,code`、カンマ区切り）
 - `-s, --selector <selector>`: 比較対象を限定するCSSセレクター
 - `-i, --ignore <selector>`: 無視するCSSセレクター
 - `-d, --devices <devices>`: デバイスプリセット（カンマ区切り、デフォルト: desktop-compact,mobile）
@@ -44,6 +45,19 @@ URLリストを持つファイルを指定して実行します。
 - `mobile-large`: 414px幅（3倍解像度）
 - `mobile-small`: 320px幅（2倍解像度）
 
+### 比較タイプ
+
+`-t` オプションで指定する比較タイプの詳細:
+
+| タイプ  | 説明                                                                                   | ブラウザ |
+| ------- | -------------------------------------------------------------------------------------- | -------- |
+| `image` | スクリーンショットのピクセル単位のビジュアル差分                                       | 必要     |
+| `dom`   | ブラウザでレンダリングされた後のDOMツリーの差分（JavaScript実行後の状態）              | 必要     |
+| `text`  | ページのテキストコンテンツの差分（形態素解析による比較）                               | 必要     |
+| `code`  | HTTPで取得した生HTMLソースの差分（JavaScript実行前の状態、デバイスサイズに依存しない） | 不要     |
+
+デフォルトではすべてのタイプが有効です。`code` のみを指定した場合はブラウザを起動せずに実行されます。
+
 ### 使用例
 
 ```sh
@@ -56,6 +70,12 @@ npx @d-zero/archaeologist -f urls.txt --devices desktop,tablet,mobile
 # 合成画像を出力（2つの環境のスクリーンショットを左右に並べて表示）
 npx @d-zero/archaeologist -f urls.txt --combined
 
+# 生HTMLソースの差分のみ比較（ブラウザ不要）
+npx @d-zero/archaeologist -f urls.txt -t code
+
+# 画像差分と生HTMLソース差分を併用
+npx @d-zero/archaeologist -f urls.txt -t image,code
+
 # フリーズモード（参照用スクリーンショット作成）
 npx @d-zero/archaeologist --freeze urls.txt
 ```
@@ -138,3 +158,5 @@ export default async function (page, { name, width, resolution, log }) {
 Basic認証が必要なページの場合はURLにユーザー名とパスワードを含めます。
 
 例: `https://user:pass@example.com`
+
+`image`/`dom`/`text` タイプではPuppeteerが認証を処理します。`code` タイプではHTTPリクエストに`Authorization`ヘッダーとして認証情報を付与します。サーバーがリダイレクトを返す場合でも認証ヘッダーは維持されます。

package/dist/analyze-child-process.js

@@ -7,118 +7,144 @@ import { combineImages } from './modules/combine-images.js';
 import { diffImages } from './modules/diff-images.js';
 import { diffText } from './modules/diff-text.js';
 import { diffTree } from './modules/diff-tree.js';
+import { fetchHtml } from './modules/fetch-html.js';
 import { getData } from './modules/get-data.js';
 import { normalizeTextDocument } from './modules/normalize-text-document.js';
 import { score } from './utils.js';
 createChildProcess((param) => {
-    const { list, dir, types = ['image', 'dom', 'text'], selector, ignore, devices, combined = false, } = param;
+    const { list, dir, types = ['image', 'dom', 'text', 'code'], selector, ignore, devices, combined = false, } = param;
     return {
         async eachPage({ page, url: urlA, index }, logger) {
             const urlPair = list.find(([url]) => url === urlA);
             if (!urlPair) {
                 throw new Error(`Failed to find urlPair: ${urlA}`);
             }
-            const dataPair = [];
-            for (const url of urlPair) {
-                const data = await getData(page, url, {
-                    htmlDiffOnly: !types.includes('image'),
-                    selector,
-                    ignore,
-                    devices,
-                }, logger);
-                dataPair.push(data);
-                await delay(600);
-            }
-            const [a, b] = dataPair;
-            if (!a || !b) {
-                throw new Error('Failed to get screenshots');
-            }
+            const needsBrowser = types.some((t) => ['image', 'dom', 'text'].includes(t));
             const screenshotResult = {};
-            const outputUrl = 'vs ' + c.gray(urlPair[1]);
-            for (const [name, screenshotA] of Object.entries(a.screenshots)) {
-                const screenshotB = b.screenshots[name];
-                const sizeName = c.bgMagenta(` ${name} `);
-                const id = `${index}_${name}`;
-                if (!screenshotB) {
-                    throw new Error(`Failed to get screenshotB: ${id}`);
+            if (needsBrowser) {
+                const dataPair = [];
+                for (const url of urlPair) {
+                    const data = await getData(page, url, {
+                        htmlDiffOnly: !types.includes('image'),
+                        selector,
+                        ignore,
+                        devices,
+                    }, logger);
+                    dataPair.push(data);
+                    await delay(600);
                 }
-                let image = null;
-                if (types.includes('image')) {
-                    const imageDiff = await diffImages(screenshotA, screenshotB, (phase, data) => {
-                        switch (phase) {
-                            case 'create': {
-                                logger(`${sizeName} ${outputUrl} 🖼️ Create images`);
-                                break;
-                            }
-                            case 'resize': {
-                                const { width, height } = data;
-                                logger(`${sizeName} ${outputUrl} ↔️ Resize images to ${width}x${height}`);
-                                break;
+                const [a, b] = dataPair;
+                if (!a || !b) {
+                    throw new Error('Failed to get screenshots');
+                }
+                const outputUrl = 'vs ' + c.gray(urlPair[1]);
+                for (const [name, screenshotA] of Object.entries(a.screenshots)) {
+                    const screenshotB = b.screenshots[name];
+                    const sizeName = c.bgMagenta(` ${name} `);
+                    const id = `${index}_${name}`;
+                    if (!screenshotB) {
+                        throw new Error(`Failed to get screenshotB: ${id}`);
+                    }
+                    let image = null;
+                    if (types.includes('image')) {
+                        const imageDiff = await diffImages(screenshotA, screenshotB, (phase, data) => {
+                            switch (phase) {
+                                case 'create': {
+                                    logger(`${sizeName} ${outputUrl} 🖼️ Create images`);
+                                    break;
+                                }
+                                case 'resize': {
+                                    const { width, height } = data;
+                                    logger(`${sizeName} ${outputUrl} ↔️ Resize images to ${width}x${height}`);
+                                    break;
+                                }
+                                case 'diff': {
+                                    logger(`${sizeName} ${outputUrl} 📊 Compare images`);
+                                    break;
+                                }
                             }
-                            case 'diff': {
-                                logger(`${sizeName} ${outputUrl} 📊 Compare images`);
-                                break;
+                        });
+                        if (imageDiff) {
+                            logger(`${sizeName} ${outputUrl} 🧩 Matches ${score(imageDiff.matches, 0.9)}`);
+                            await delay(1500);
+                            await writeFile(path.resolve(dir, `${id}_a.png`), imageDiff.images.a);
+                            await writeFile(path.resolve(dir, `${id}_b.png`), imageDiff.images.b);
+                            const outFilePath = path.resolve(dir, `${id}_diff.png`);
+                            logger(`${sizeName} ${outputUrl} 📊 Save diff image to ${path.relative(dir, outFilePath)}`);
+                            await writeFile(outFilePath, imageDiff.images.diff);
+                            // 合成画像を出力
+                            if (combined) {
+                                const combinedImage = await combineImages(imageDiff.images.a, imageDiff.images.b);
+                                const combinedFilePath = path.resolve(dir, `${id}_combined.png`);
+                                logger(`${sizeName} ${outputUrl} 🖼️ Save combined image to ${path.relative(dir, combinedFilePath)}`);
+                                await writeFile(combinedFilePath, combinedImage);
                             }
+                            image = {
+                                matches: imageDiff.matches,
+                                file: outFilePath,
+                            };
                         }
-                    });
-                    if (imageDiff) {
-                        logger(`${sizeName} ${outputUrl} 🧩 Matches ${score(imageDiff.matches, 0.9)}`);
-                        await delay(1500);
-                        await writeFile(path.resolve(dir, `${id}_a.png`), imageDiff.images.a);
-                        await writeFile(path.resolve(dir, `${id}_b.png`), imageDiff.images.b);
-                        const outFilePath = path.resolve(dir, `${id}_diff.png`);
-                        logger(`${sizeName} ${outputUrl} 📊 Save diff image to ${path.relative(dir, outFilePath)}`);
-                        await writeFile(outFilePath, imageDiff.images.diff);
-                        // 合成画像を出力
-                        if (combined) {
-                            const combinedImage = await combineImages(imageDiff.images.a, imageDiff.images.b);
-                            const combinedFilePath = path.resolve(dir, `${id}_combined.png`);
-                            logger(`${sizeName} ${outputUrl} 🖼️ Save combined image to ${path.relative(dir, combinedFilePath)}`);
-                            await writeFile(combinedFilePath, combinedImage);
-                        }
-                        image = {
-                            matches: imageDiff.matches,
+                    }
+                    let dom = null;
+                    if (types.includes('dom')) {
+                        const htmlDiff = diffTree(a.url, b.url, screenshotA.domTree, screenshotB.domTree);
+                        const outFilePath = path.resolve(dir, `${id}_html.diff`);
+                        await writeFile(outFilePath, htmlDiff.result, { encoding: 'utf8' });
+                        dom = {
+                            matches: htmlDiff.matches,
+                            diff: htmlDiff.changed ? htmlDiff.result : null,
                             file: outFilePath,
                         };
                     }
-                }
-                let dom = null;
-                if (types.includes('dom')) {
-                    const htmlDiff = diffTree(a.url, b.url, screenshotA.domTree, screenshotB.domTree);
-                    const outFilePath = path.resolve(dir, `${id}_html.diff`);
-                    await writeFile(outFilePath, htmlDiff.result, { encoding: 'utf8' });
-                    dom = {
-                        matches: htmlDiff.matches,
-                        diff: htmlDiff.changed ? htmlDiff.result : null,
-                        file: outFilePath,
+                    let text = null;
+                    if (types.includes('text')) {
+                        const contentA = normalizeTextDocument(screenshotA.text.textContent);
+                        const contentB = normalizeTextDocument(screenshotB.text.textContent);
+                        const altTextListA = screenshotA.text.altTextList.join('\n');
+                        const altTextListB = screenshotB.text.altTextList.join('\n');
+                        const textA = `${contentA}\n\n${altTextListA}`;
+                        const textB = `${contentB}\n\n${altTextListB}`;
+                        const textDiff = diffText(a.url, b.url, textA, textB);
+                        const outFilePath = path.resolve(dir, `${id}_text.diff`);
+                        await writeFile(outFilePath, `${textDiff.phrases.result}\n\n${textDiff.tokens.result}`, { encoding: 'utf8' });
+                        text = {
+                            matches: textDiff.tokens.matches,
+                            diff: textDiff.tokens.changed ? textDiff.tokens.result : null,
+                            file: outFilePath,
+                        };
+                    }
+                    screenshotResult[name] = {
+                        image,
+                        dom,
+                        text,
                     };
                 }
-                let text = null;
-                if (types.includes('text')) {
-                    const contentA = normalizeTextDocument(screenshotA.text.textContent);
-                    const contentB = normalizeTextDocument(screenshotB.text.textContent);
-                    const altTextListA = screenshotA.text.altTextList.join('\n');
-                    const altTextListB = screenshotB.text.altTextList.join('\n');
-                    const textA = `${contentA}\n\n${altTextListA}`;
-                    const textB = `${contentB}\n\n${altTextListB}`;
-                    const textDiff = diffText(a.url, b.url, textA, textB);
-                    const outFilePath = path.resolve(dir, `${id}_text.diff`);
-                    await writeFile(outFilePath, `${textDiff.phrases.result}\n\n${textDiff.tokens.result}`, { encoding: 'utf8' });
-                    text = {
-                        matches: textDiff.tokens.matches,
-                        diff: textDiff.tokens.changed ? textDiff.tokens.result : null,
+            }
+            let code = null;
+            if (types.includes('code')) {
+                const fetched = await Promise.all([
+                    fetchHtml(urlPair[0]),
+                    fetchHtml(urlPair[1]),
+                ]).catch((error) => {
+                    logger(`⚠️ CODE fetch failed: ${error instanceof Error ? error.message : error}`);
+                    return null;
+                });
+                if (fetched) {
+                    const [htmlA, htmlB] = fetched;
+                    const codeDiff = diffTree(urlPair[0], urlPair[1], htmlA, htmlB);
+                    const outFilePath = path.resolve(dir, `${index}_code.diff`);
+                    await writeFile(outFilePath, codeDiff.result, { encoding: 'utf8' });
+                    code = {
+                        matches: codeDiff.matches,
+                        diff: codeDiff.changed ? codeDiff.result : null,
                         file: outFilePath,
                     };
                 }
-                screenshotResult[name] = {
-                    image,
-                    dom,
-                    text,
-                };
             }
             const result = {
-                target: [a.url, b.url],
+                target: [...urlPair],
                 screenshots: screenshotResult,
+                code,
             };
             return result;
         },

package/dist/analyze-main-process.d.ts

@@ -1,8 +1,8 @@
 import type { AnalyzeOptions, URLPair } from './types.js';
 import type { DealOptions } from '@d-zero/dealer';
 /**
- *
- * @param list
- * @param options
+ * URLペアのリストを比較分析し、結果を`.archaeologist`ディレクトリに出力する
+ * @param list - 比較対象のURLペアのリスト
+ * @param options - 分析オプション（比較タイプ、デバイス、並列実行数など）
  */
 export declare function analyze(list: readonly URLPair[], options?: AnalyzeOptions & DealOptions): Promise<void>;

package/dist/analyze-main-process.js

@@ -6,9 +6,9 @@ import stripAnsi from 'strip-ansi';
 import { analyzeUrlList } from './modules/analize-url.js';
 import { score } from './utils.js';
 /**
- *
- * @param list
- * @param options
+ * URLペアのリストを比較分析し、結果を`.archaeologist`ディレクトリに出力する
+ * @param list - 比較対象のURLペアのリスト
+ * @param options - 分析オプション（比較タイプ、デバイス、並列実行数など）
  */
 export async function analyze(list, options) {
     const results = [];
@@ -54,6 +54,9 @@ export async function analyze(list, options) {
                 output.push(`  ${c.bgGreenBright(' TEXT ')}: ${score(text.matches, 0.995)} ${text.file}`);
             }
         }
+        if (result.code) {
+            output.push(`  ${c.bgCyan(' CODE ')}: ${score(result.code.matches, 0.995)} ${result.code.file}`);
+        }
     }
     await writeFile(path.resolve(dir, 'RESULT.txt'), stripAnsi(output.join('\n').replaceAll(dir, '.')), 'utf8');
     process.stdout.write(output.join('\n') + '\n');

package/dist/cli.js

@@ -21,7 +21,9 @@ const { options, hasConfigFile } = createCLI({
         '',
         'Options:',
         '\t-f, --listfile <file>     File containing URL pairs to analyze',
-        '\t-t, --type <types>        Analysis types (comma-separated): image,dom,text',
+        '\t-t, --type <types>        Analysis types (comma-separated): image,dom,text,code',
+        '\t                          image: visual diff, dom: rendered DOM diff,',
+        '\t                          text: text content diff, code: raw HTML source diff',
         '\t-d, --devices <devices>   Device presets (comma-separated, default: desktop-compact,mobile)',
         '\t-s, --selector <selector> CSS selector for specific elements',
         '\t-i, --ignore <ignore>     CSS selector for elements to ignore',

package/dist/freeze-main-process.d.ts

@@ -1,8 +1,9 @@
 import type { FreezeOptions } from './types.js';
 import type { DealOptions } from '@d-zero/dealer';
 /**
- *
- * @param list
- * @param options
+ * URLリストのスクリーンショットとDOMを参照用として保存し、ZIPアーカイブを生成する
+ * @param list - フリーズ対象のURLリスト
+ * @param options - フリーズオプション（並列実行数など）
+ * @returns 生成されたZIPファイルの絶対パス
  */
 export declare function freeze(list: readonly string[], options?: FreezeOptions & DealOptions): Promise<string>;

package/dist/freeze-main-process.js

@@ -6,9 +6,10 @@ import { timestamp } from '@d-zero/shared/timestamp';
 import c from 'ansi-colors';
 import { analyzeUrlList } from './modules/analize-url.js';
 /**
- *
- * @param list
- * @param options
+ * URLリストのスクリーンショットとDOMを参照用として保存し、ZIPアーカイブを生成する
+ * @param list - フリーズ対象のURLリスト
+ * @param options - フリーズオプション（並列実行数など）
+ * @returns 生成されたZIPファイルの絶対パス
  */
 export async function freeze(list, options) {
     const name = `${timestamp('YYYYMMDD')}.archae`;

package/dist/modules/analize-url.d.ts

@@ -4,8 +4,9 @@ type AnalyzedUrlList = {
     hasNoSSL: boolean;
 };
 /**
- *
- * @param list
+ * URLリストを解析し、Basic認証やHTTP（非SSL）の使用有無を判定する
+ * @param list - 解析対象のURLペアまたはURL文字列のリスト
+ * @returns 認証情報の有無とSSL未使用の有無
  */
 export declare function analyzeUrlList(list: readonly (URLPair | string)[]): AnalyzedUrlList;
 export {};

package/dist/modules/analize-url.js

@@ -1,6 +1,7 @@
 /**
- *
- * @param list
+ * URLリストを解析し、Basic認証やHTTP（非SSL）の使用有無を判定する
+ * @param list - 解析対象のURLペアまたはURL文字列のリスト
+ * @returns 認証情報の有無とSSL未使用の有無
  */
 export function analyzeUrlList(list) {
     const result = {

package/dist/modules/diff-images.d.ts

@@ -17,10 +17,11 @@ export type DiffImagesPhase = {
 };
 type DiffImagesListener = (phase: keyof DiffImagesPhase, data: DiffImagesPhase[keyof DiffImagesPhase]) => void;
 /**
- *
- * @param dataA
- * @param dataB
- * @param listener
+ * 2つのスクリーンショットのピクセル単位の差分を生成する
+ * @param dataA - 比較元のスクリーンショットデータ
+ * @param dataB - 比較先のスクリーンショットデータ
+ * @param listener - 処理フェーズの進捗を受け取るリスナー
+ * @returns 一致率と差分画像バッファ。バイナリが存在しない場合はnull
  */
 export declare function diffImages(dataA: Screenshot, dataB: Screenshot, listener: DiffImagesListener): Promise<{
     matches: number;

package/dist/modules/diff-images.js

@@ -2,10 +2,11 @@ import { Jimp, HorizontalAlign, VerticalAlign, JimpMime } from 'jimp';
 import pixelmatch from 'pixelmatch';
 import { PNG } from 'pngjs';
 /**
- *
- * @param dataA
- * @param dataB
- * @param listener
+ * 2つのスクリーンショットのピクセル単位の差分を生成する
+ * @param dataA - 比較元のスクリーンショットデータ
+ * @param dataB - 比較先のスクリーンショットデータ
+ * @param listener - 処理フェーズの進捗を受け取るリスナー
+ * @returns 一致率と差分画像バッファ。バイナリが存在しない場合はnull
  */
 export async function diffImages(dataA, dataB, listener) {
     if (!dataA.binary || !dataB.binary) {

package/dist/modules/diff-text.d.ts

@@ -1,9 +1,10 @@
 /**
- *
- * @param urlA
- * @param urlB
- * @param phraseA
- * @param phraseB
+ * 2つのテキストを形態素解析し、フレーズ単位とトークン頻度の両方で差分を比較する
+ * @param urlA - 比較元のURL（diffヘッダーに使用）
+ * @param urlB - 比較先のURL（diffヘッダーに使用）
+ * @param phraseA - 比較元のテキスト
+ * @param phraseB - 比較先のテキスト
+ * @returns フレーズ差分とトークン頻度差分の両方を含むオブジェクト
  */
 export declare function diffText(urlA: string, urlB: string, phraseA: string, phraseB: string): {
     phrases: {

package/dist/modules/diff-text.js

@@ -27,11 +27,12 @@ function frequencyMap(tokens) {
         .toSorted((a, b) => a.localeCompare(b));
 }
 /**
- *
- * @param urlA
- * @param urlB
- * @param phraseA
- * @param phraseB
+ * 2つのテキストを形態素解析し、フレーズ単位とトークン頻度の両方で差分を比較する
+ * @param urlA - 比較元のURL（diffヘッダーに使用）
+ * @param urlB - 比較先のURL（diffヘッダーに使用）
+ * @param phraseA - 比較元のテキスト
+ * @param phraseB - 比較先のテキスト
+ * @returns フレーズ差分とトークン頻度差分の両方を含むオブジェクト
  */
 export function diffText(urlA, urlB, phraseA, phraseB) {
     const tokensA = tokenList(phraseA);

package/dist/modules/diff-tree.d.ts

@@ -1,9 +1,10 @@
 /**
- *
- * @param urlA
- * @param urlB
- * @param dataA
- * @param dataB
+ * 2つのテキストデータの行差分を生成し、一致率を算出する
+ * @param urlA - 比較元のURL（diffヘッダーに使用）
+ * @param urlB - 比較先のURL（diffヘッダーに使用）
+ * @param dataA - 比較元のテキストデータ
+ * @param dataB - 比較先のテキストデータ
+ * @returns 差分結果（変更有無、最大行数、一致率、unified diff文字列）
  */
 export declare function diffTree(urlA: string, urlB: string, dataA: string, dataB: string): {
     changed: boolean;

package/dist/modules/diff-tree.js

@@ -1,11 +1,12 @@
 import { createTwoFilesPatch } from 'diff';
 import parse from 'parse-diff';
 /**
- *
- * @param urlA
- * @param urlB
- * @param dataA
- * @param dataB
+ * 2つのテキストデータの行差分を生成し、一致率を算出する
+ * @param urlA - 比較元のURL（diffヘッダーに使用）
+ * @param urlB - 比較先のURL（diffヘッダーに使用）
+ * @param dataA - 比較元のテキストデータ
+ * @param dataB - 比較先のテキストデータ
+ * @returns 差分結果（変更有無、最大行数、一致率、unified diff文字列）
  */
 export function diffTree(urlA, urlB, dataA, dataB) {
     const result = createTwoFilesPatch(urlA, urlB, dataA, dataB);

package/dist/modules/fetch-html.d.ts

@@ -0,0 +1,10 @@
+/**
+ * HTTPで生のHTMLソースを取得する
+ *
+ * URLにBasic認証情報（user:pass）が含まれている場合、
+ * Authorizationヘッダーに変換して送信する。
+ * リダイレクト先でも認証ヘッダーを維持するため、リダイレクトを手動で追跡する。
+ * @param url - 取得対象のURL
+ * @returns HTMLソース文字列
+ */
+export declare function fetchHtml(url: string): Promise<string>;

package/dist/modules/fetch-html.js

@@ -0,0 +1,37 @@
+/**
+ * HTTPで生のHTMLソースを取得する
+ *
+ * URLにBasic認証情報（user:pass）が含まれている場合、
+ * Authorizationヘッダーに変換して送信する。
+ * リダイレクト先でも認証ヘッダーを維持するため、リダイレクトを手動で追跡する。
+ * @param url - 取得対象のURL
+ * @returns HTMLソース文字列
+ */
+export async function fetchHtml(url) {
+    const urlObj = new URL(url);
+    const headers = {};
+    if (urlObj.username || urlObj.password) {
+        const credentials = btoa(`${urlObj.username}:${urlObj.password}`);
+        headers['Authorization'] = `Basic ${credentials}`;
+        urlObj.username = '';
+        urlObj.password = '';
+    }
+    const maxRedirects = 10;
+    let target = urlObj.toString();
+    for (let i = 0; i <= maxRedirects; i++) {
+        const res = await fetch(target, { headers, redirect: 'manual' });
+        if (res.status >= 300 && res.status < 400) {
+            const location = res.headers.get('location');
+            if (!location) {
+                throw new Error(`Redirect without Location header from ${target}`);
+            }
+            target = new URL(location, target).toString();
+            continue;
+        }
+        if (!res.ok) {
+            throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
+        }
+        return res.text();
+    }
+    throw new Error(`Too many redirects fetching ${url}`);
+}

package/dist/modules/get-data.d.ts

@@ -9,10 +9,11 @@ export interface GetDataOptions {
     readonly devices?: readonly string[];
 }
 /**
- *
- * @param page
- * @param url
- * @param options
- * @param update
+ * Puppeteerでページを開き、各デバイスサイズのスクリーンショットとDOMツリーを取得する
+ * @param page - PuppeteerのPageインスタンス
+ * @param url - 取得対象のURL
+ * @param options - スクリーンショット取得のオプション
+ * @param update - 進捗ログを受け取るコールバック
+ * @returns 各デバイスサイズのスクリーンショットとDOMツリーを含むページデータ
  */
 export declare function getData(page: Page, url: string, options: GetDataOptions, update: (log: string) => void): Promise<PageData>;

package/dist/modules/get-data.js

@@ -2,11 +2,12 @@ import { distill } from '@d-zero/html-distiller';
 import { createSizesFromDevices } from '@d-zero/puppeteer-page-scan';
 import { screenshotListener, screenshot } from '@d-zero/puppeteer-screenshot';
 /**
- *
- * @param page
- * @param url
- * @param options
- * @param update
+ * Puppeteerでページを開き、各デバイスサイズのスクリーンショットとDOMツリーを取得する
+ * @param page - PuppeteerのPageインスタンス
+ * @param url - 取得対象のURL
+ * @param options - スクリーンショット取得のオプション
+ * @param update - 進捗ログを受け取るコールバック
+ * @returns 各デバイスサイズのスクリーンショットとDOMツリーを含むページデータ
  */
 export async function getData(page, url, options, update) {
     const htmlDiffOnly = options.htmlDiffOnly ?? false;

package/dist/modules/normalize-text-document.d.ts

@@ -1,5 +1,6 @@
 /**
- *
- * @param text
+ * テキストを正規化する（連続空白を改行に変換、句点で改行、連続改行を単一改行に統合）
+ * @param text - 正規化対象のテキスト
+ * @returns 正規化されたテキスト
  */
 export declare function normalizeTextDocument(text: string): string;

package/dist/modules/normalize-text-document.js

@@ -1,6 +1,7 @@
 /**
- *
- * @param text
+ * テキストを正規化する（連続空白を改行に変換、句点で改行、連続改行を単一改行に統合）
+ * @param text - 正規化対象のテキスト
+ * @returns 正規化されたテキスト
  */
 export function normalizeTextDocument(text) {
     return (text

package/dist/read-config.d.ts

@@ -1,6 +1,7 @@
 /**
- *
- * @param filePath
+ * Frontmatter形式の設定ファイルを読み込み、URLペアリストとページフックを返す
+ * @param filePath - 設定ファイルのパス
+ * @returns URLペアのリストとページフック関数の配列
  */
 export declare function readConfig(filePath: string): Promise<{
     pairList: [string, string][];

package/dist/read-config.js

@@ -2,8 +2,9 @@ import { readPageHooks } from '@d-zero/puppeteer-page-scan';
 import { toList } from '@d-zero/readtext/list';
 import { readConfigFile } from '@d-zero/shared/config-reader';
 /**
- *
- * @param filePath
+ * Frontmatter形式の設定ファイルを読み込み、URLペアリストとページフックを返す
+ * @param filePath - 設定ファイルのパス
+ * @returns URLペアのリストとページフック関数の配列
  */
 export async function readConfig(filePath) {
     const { content, baseDir } = await readConfigFile(filePath);

package/dist/types.d.ts

@@ -10,6 +10,7 @@ export type URLPair = readonly [urlA: string, urlB: string];
 export type Result = {
     target: [urlA: string, urlB: string];
     screenshots: Record<string, MediaResult>;
+    code: CodeResult | null;
 };
 export type MediaResult = {
     image: ImageResult | null;
@@ -30,6 +31,11 @@ export type TextResult = {
     diff: string | null;
     file: string;
 };
+export type CodeResult = {
+    matches: number;
+    diff: string | null;
+    file: string;
+};
 export interface ArchaeologistOptions extends AnalyzeOptions {
 }
 export interface AnalyzeOptions extends GeneralOptions {

package/dist/utils.d.ts

@@ -1,6 +1,7 @@
 /**
- *
- * @param matches
- * @param threshold
+ * 一致率をパーセント表示し、閾値に基づいて色付けする
+ * @param matches - 一致率（0〜1の範囲）
+ * @param threshold - 合格とみなす閾値（超えると緑、以下は赤）
+ * @returns ANSI色付きのパーセント文字列
  */
 export declare function score(matches: number, threshold: number): string;

package/dist/utils.js

@@ -1,8 +1,9 @@
 import c from 'ansi-colors';
 /**
- *
- * @param matches
- * @param threshold
+ * 一致率をパーセント表示し、閾値に基づいて色付けする
+ * @param matches - 一致率（0〜1の範囲）
+ * @param threshold - 合格とみなす閾値（超えると緑、以下は赤）
+ * @returns ANSI色付きのパーセント文字列
  */
 export function score(matches, threshold) {
     const color = matches > threshold ? c.green : c.red;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@d-zero/archaeologist",
-	"version": "3.5.9",
+	"version": "3.6.0",
 	"description": "Uncover visual and HTML differences in web pages with precision",
 	"author": "D-ZERO",
 	"license": "MIT",
@@ -24,14 +24,14 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
-		"@d-zero/cli-core": "1.3.4",
+		"@d-zero/cli-core": "1.3.6",
 		"@d-zero/fs": "0.2.2",
 		"@d-zero/html-distiller": "2.0.4",
-		"@d-zero/puppeteer-dealer": "0.7.6",
-		"@d-zero/puppeteer-page-scan": "4.4.5",
-		"@d-zero/puppeteer-screenshot": "3.3.5",
+		"@d-zero/puppeteer-dealer": "0.7.8",
+		"@d-zero/puppeteer-page-scan": "4.4.7",
+		"@d-zero/puppeteer-screenshot": "3.3.7",
 		"@d-zero/readtext": "1.1.20",
-		"@d-zero/shared": "0.20.1",
+		"@d-zero/shared": "0.21.1",
 		"ansi-colors": "4.1.3",
 		"diff": "8.0.3",
 		"front-matter": "4.0.2",
@@ -49,5 +49,5 @@
 		"@types/pixelmatch": "5.2.6",
 		"@types/pngjs": "6.0.5"
 	},
-	"gitHead": "866364294ddacc3095f65a9f8b488d40c4ccb904"
+	"gitHead": "6f13c72151f3d6fe5ddf72d0cde61b31a7fc96ac"
 }