Add comprehensive error handling and test coverage for analyze

.env.example

@@ -0,0 +1,12 @@
+# Google Sheets Report - OAuth2 Credentials
+# ------------------------------------------
+# credentials.json: Google Cloud OAuth2 service account key file.
+# Download from Google Cloud Console > APIs & Services > Credentials.
+# See: https://developers.google.com/sheets/api/quickstart/nodejs
+#
+# Default path: ./credentials.json (override with --credentials flag)
+# IMPORTANT: Never commit credentials.json or token.json to version control.
+
+# For testing report-google-sheets package:
+# TEST_CREDENTIALS_PATH=./credentials.json
+# TEST_TOKEN_PATH=./token.json

.github/workflows/ci.yml

@@ -15,9 +15,12 @@ jobs:
           cache: yarn
       - run: yarn install --immutable
       - run: yarn build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: packages/**/lib/
+          retention-days: 1
 
-  # build ジョブはビルド成果物を共有しないが、
-  # ビルドが通らない場合にテストを実行しても意味がないためガードとして依存させている。
   test:
     needs: build
     runs-on: ubuntu-latest
@@ -29,7 +32,10 @@ jobs:
           node-version: 24
           cache: yarn
       - run: yarn install --immutable
-      - run: yarn build
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          path: packages/
       - run: yarn test
 
   lint:

ARCHITECTURE.md

@@ -117,7 +117,7 @@ crawler/src/
 │   ├── object/                 # cleanObject
 │   └── error/                  # DOMEvaluationError, ErrorEmitter
 ├── archive/                    # SQLite アーカイブストレージ
-│   ├── filesystem/             # 1関数1ファイル（14ファイル）+ tar, untar
+│   ├── filesystem/             # 1関数1ファイル（16ファイル）+ tar, untar
 │   └── ...                     # archive, archive-accessor, database, page, resource
 ├── crawler/                    # Crawler エンジン
 │   ├── crawler.ts              # Crawler クラス
@@ -608,3 +608,40 @@ interval: 0             # 待機なし
 parallels: 1            # 直列実行
 image: false            # 画像取得なし
 ```
+
+---
+
+## 13. 外部依存パッケージ（`@d-zero/*`）
+
+Nitpicker は D-ZERO が公開する以下の外部パッケージに依存している。
+仕様変更やバグ調査時はこれらのパッケージを参照すること。バージョンは各パッケージの `package.json` を参照。
+
+| パッケージ              | 用途                                                                          | 検索キーワード                        |
+| ----------------------- | ----------------------------------------------------------------------------- | ------------------------------------- |
+| `@d-zero/beholder`      | Puppeteer ベースのスクレイパーエンジン。`ScrapeResult` を返す                 | `"@d-zero/beholder" changelog`        |
+| `@d-zero/dealer`        | 並列処理・スケジューリング。`deal()` 関数を提供                               | `"@d-zero/dealer" deal concurrent`    |
+| `@d-zero/shared`        | 共有ユーティリティ（サブパスエクスポート形式: `@d-zero/shared/parse-url` 等） | `"@d-zero/shared" subpath exports`    |
+| `@d-zero/roar`          | CLI フレームワーク                                                            | `"@d-zero/roar" command`              |
+| `@d-zero/google-auth`   | OAuth2 認証（`credentials.json` → `token.json`）                              | `"@d-zero/google-auth" oauth2`        |
+| `@d-zero/google-sheets` | Google Sheets API クライアント                                                | `"@d-zero/google-sheets" spreadsheet` |
+| `@d-zero/fs`            | ファイルシステムユーティリティ                                                | `"@d-zero/fs"`                        |
+| `@d-zero/readtext`      | テキスト読み取りユーティリティ                                                | `"@d-zero/readtext"`                  |
+
+### 利用箇所マップ
+
+```
+@d-zero/beholder      → crawler（Scraper, ScrapeResult）
+@d-zero/dealer         → crawler, core, cli, report-google-sheets（deal() 並列制御）
+@d-zero/shared         → 全パッケージ（parseUrl, delay, isError, detectCompress, detectCDN）
+@d-zero/roar           → cli（CLI コマンド定義）
+@d-zero/google-auth    → report-google-sheets（OAuth2 認証）
+@d-zero/google-sheets  → report-google-sheets（Sheets API）
+@d-zero/fs             → crawler（ファイルシステムユーティリティ）
+@d-zero/readtext       → cli（リストファイル読み込み）
+```
+
+### バージョン更新時の注意
+
+- **`@d-zero/beholder`**: `ScrapeResult` の型が変わると crawler 全体に影響
+- **`@d-zero/dealer`**: `deal()` の API が変わると crawler と core の並列処理に影響
+- **`@d-zero/shared`**: サブパスエクスポートの追加・削除に注意。`@d-zero/shared/parse-url` 形式でインポートすること

CONTRIBUTING.md

@@ -0,0 +1,118 @@
+# Contributing to Nitpicker
+
+Nitpicker へのコントリビューションを歓迎します。
+
+## 開発環境セットアップ
+
+```sh
+# リポジトリをクローン
+git clone https://github.com/d-zero-dev/nitpicker.git
+cd nitpicker
+
+# 依存関係をインストール（Yarn のみ使用、npm 厳禁）
+corepack enable
+yarn install --immutable
+
+# 全パッケージをビルド
+yarn build
+
+# テスト実行
+yarn test
+```
+
+### 必要な環境
+
+- **Node.js** 24 以上（Volta でバージョン管理推奨）
+- **Yarn** 4.x（`corepack enable` で自動有効化）
+- **npm は使用しない**: すべてのコマンドは `yarn` 経由で実行
+
+## 開発ワークフロー
+
+### ブランチ戦略
+
+- `main` ブランチから feature ブランチを作成
+- ブランチ名: `feat/機能名`, `fix/バグ名`, `docs/ドキュメント名`
+
+### コマンド制約
+
+- **パッケージディレクトリに `cd` しない**: 常にリポジトリルートからコマンドを実行
+- **ビルドは `yarn build` のみ**: `npx tsc`, `yarn tsc` 等は禁止
+- **対象を限定した操作**: ビルド検証は `yarn build` で全パッケージ一括実行
+
+```sh
+# 全パッケージビルド
+yarn build
+
+# ユニットテスト
+yarn test
+
+# E2E テスト
+yarn vitest run --config vitest.e2e.config.ts
+
+# lint
+yarn lint:check
+```
+
+### コミットメッセージ
+
+[Conventional Commits](https://www.conventionalcommits.org/) に準拠:
+
+```
+feat(crawler): add retry logic for failed requests
+fix(core): prevent analyze results from being silently empty
+docs: update README with new CLI options
+```
+
+commitlint がプリコミットフックで検証します。
+
+## コーディング規約
+
+### ファイル構成
+
+- **1ファイル1エクスポート**: エクスポートする関数/クラスは1つのみ
+- **`index.ts` 禁止**: モジュールの公開は `package.json` の `exports` フィールドで行う
+- **型は `types.ts` に集約**: ドメインごとに専用 `types.ts` を作成
+
+### TypeScript
+
+- **JSDoc 必須**: すべての公開関数、クラス、interface、type に JSDoc を記述
+- **`interface` 優先**: `type` はユニオン型・交差型など `type` でしか定義できない場合のみ
+- **パラメータ3つ以上**: 名前付きオブジェクトにまとめる
+- **Vitest 4**: `import { describe, it, expect } from 'vitest'` を明示的に記述
+
+### テスト
+
+- **1関数1ファイルにはユニットテスト必須**
+- **テストファーストを推奨**: バグ修正や明確な仕様の機能追加では、実装より先にテスト
+
+### analyze プラグイン
+
+- `console.log` を使わない（`deal()` が進捗表示を担当）
+- `definePlugin()` でプラグインを定義
+- `eachPage` / `eachUrl` コールバックでページ単位の分析を実装
+
+## PR ガイドライン
+
+1. 変更の目的を明確に記述
+2. テストを追加・更新
+3. `yarn build && yarn test && yarn lint:check` がパスすることを確認
+4. 破壊的変更にはマイグレーションガイドを同梱
+
+## パッケージ構成
+
+詳細は [ARCHITECTURE.md](./ARCHITECTURE.md) を参照。
+
+## 外部依存パッケージ
+
+| パッケージ              | 用途                                           | 参照                         |
+| ----------------------- | ---------------------------------------------- | ---------------------------- |
+| `@d-zero/beholder`      | Puppeteer ベースのスクレイパー                 | npm: `@d-zero/beholder`      |
+| `@d-zero/dealer`        | 並列処理・スケジューリング                     | npm: `@d-zero/dealer`        |
+| `@d-zero/shared`        | 共有ユーティリティ（サブパスエクスポート形式） | npm: `@d-zero/shared`        |
+| `@d-zero/roar`          | CLI フレームワーク                             | npm: `@d-zero/roar`          |
+| `@d-zero/google-auth`   | OAuth2 認証                                    | npm: `@d-zero/google-auth`   |
+| `@d-zero/google-sheets` | Google Sheets API クライアント                 | npm: `@d-zero/google-sheets` |
+
+## ライセンス
+
+Apache 2.0 — 詳細は [LICENSE](./LICENSE) を参照。