@markuplint/spec-generator 4.8.0 → 4.8.2

package/docs/maintenance.ja.md

@@ -0,0 +1,212 @@
+# メンテナンスガイド
+
+`@markuplint/spec-generator` の実践的な運用・メンテナンスガイド。
+
+## コマンド
+
+| コマンド                                              | 説明                                                       |
+| ----------------------------------------------------- | ---------------------------------------------------------- |
+| `yarn build --scope @markuplint/spec-generator`       | TypeScript を `lib/` にコンパイル                          |
+| `yarn workspace @markuplint/spec-generator run dev`   | ウォッチモードでコンパイル                                 |
+| `yarn workspace @markuplint/spec-generator run clean` | コンパイル出力をクリーン                                   |
+| `yarn up:gen`                                         | 仕様生成を実行（html-spec 経由でこのパッケージを呼び出し） |
+
+**注意:** このパッケージは直接実行されません。`@markuplint/html-spec/build.mjs` が消費し、`main()` を呼び出します。完全な生成をトリガーするには `yarn up:gen` を使用してください。
+
+## トラブルシューティング
+
+### スクレイピング失敗の検出
+
+`yarn up:gen` 実行後、必ず `index.json` の差分を確認:
+
+```bash
+git diff packages/@markuplint/html-spec/index.json
+```
+
+**スクレイピング失敗の兆候:**
+
+- 差分が極端に大量のデータ消失を示す（仕様データが一括で消失）
+- 複数の要素で突然 `description` フィールドが空になる
+- 以前存在していた属性が削除される
+- ARIA ロールやプロパティの定義が空、または大幅に減少
+
+**これはほぼ確実にスクレイピングの失敗であり**、実際の仕様変更ではありません。正当な仕様変更は漸進的で、少数の要素にのみ影響します。
+
+**根本原因:** 参照サイト（MDN または W3C）の HTML 構造、情報の記述方法、要素の ID/クラスが変更された。
+
+**対処法:**
+
+1. 影響を受けているデータを特定（要素メタデータ、ARIA ロール、SVG 要素など）
+2. 該当するモジュールを特定:
+   - 要素の説明、カテゴリ、属性 -- `scraping.ts`
+   - ARIA ロールとプロパティ -- `aria.ts`
+   - SVG 非推奨要素 -- `svg.ts`
+3. 影響を受けたウェブページをブラウザで開き、現在の HTML 構造を調査
+4. モジュールの CSS セレクタを新しい構造に合わせて更新
+5. ビルド: `yarn build --scope @markuplint/spec-generator`
+6. 再生成: `yarn up:gen`
+7. `index.json` の差分が正しくなったことを確認
+
+### ビルドコンパイルエラー
+
+`yarn build --scope @markuplint/spec-generator` が失敗する場合:
+
+1. `@markuplint/ml-spec` の型が変更されていないか確認（これが主要な型プロバイダ）
+2. 開発依存がインストールされていることを確認: `yarn install`
+3. クリーンビルドを試行: `yarn workspace @markuplint/spec-generator run clean && yarn build --scope @markuplint/spec-generator`
+
+### 生成時のネットワークエラー
+
+**症状:** `yarn up:gen` が失敗またはハングする。
+
+**原因:** MDN または W3C サーバーに到達できない。
+
+**対処法:**
+
+- ネットワーク接続を確認
+- 失敗したフェッチは空文字列としてキャッシュされ、ビルドは継続
+- プログレスバーが現在フェッチ中の URL を表示 -- どのドメインが失敗しているか特定
+- サービスが利用可能になったら再試行
+
+## レシピ
+
+### 1. MDN ページ構造変更への対応
+
+MDN が要素リファレンスページを再構築した場合、`scraping.ts` の CSS セレクタの更新が必要です。
+
+1. 実際のページ HTML と `scraping.ts` のセレクタを比較して影響を受けたセレクタを特定
+2. 確認すべき主要セレクタ:
+   - `MAIN_ARTICLE_SELECTOR`（`main#content`）-- メインコンテンツ領域
+   - `.reference-layout__header .content-section` -- 説明の抽出
+   - `.bc-table tbody tr:first-child th` -- 互換性テーブル
+   - `#technical_summary ~ figure.table-container > table` -- 技術サマリ
+   - `.content-section[aria-labelledby="attributes"]` -- 属性セクション
+   - アイコンクラス（`.ic-experimental`, `.ic-deprecated` など）-- ステータスフラグ
+3. セレクタを新しい構造に合わせて更新
+4. ビルド: `yarn build --scope @markuplint/spec-generator`
+5. 再生成: `yarn up:gen`
+6. 差分で正しいデータの復元を確認
+
+### 2. 新しい ARIA バージョンの追加
+
+新しい ARIA 仕様バージョンが公開された場合（例: 1.4）:
+
+1. `src/aria.ts` を開く
+2. `getARIASpecURLByVersion()` に新しいケースを追加:
+   ```typescript
+   case '1.4': {
+     if (!graphicsAria) {
+       return 'https://www.w3.org/TR/wai-aria-1.4/'; // またはエディターズドラフト URL
+     }
+     return 'https://w3c.github.io/graphics-aria/';
+   }
+   ```
+3. `getAria()` に新しいバージョンを追加:
+   ```typescript
+   const roles14 = await getRoles('1.4');
+   // ...
+   '1.4': {
+     roles: roles14,
+     props: await getProps('1.4', roles14),
+     graphicsRoles: await getRoles('1.4', true),
+   },
+   ```
+4. **パッケージ間連携:** `@markuplint/ml-spec` の `ARIAVersion` 型も `'1.4'` を含むよう更新が必要
+5. ビルドと再生成を実行
+
+### 3. 非推奨リストへの要素追加
+
+新しく非推奨になった HTML 要素を追加するには:
+
+1. `src/html-elements.ts` を開く
+2. `obsoleteList` 配列に要素名を追加
+3. 要素は自動的に `obsolete: true` の最小限の仕様スタブを取得
+4. ビルド: `yarn build --scope @markuplint/spec-generator`
+5. 再生成: `yarn up:gen`
+6. `index.json` で要素が `"obsolete": true` で表示されることを確認
+
+### 4. ExtendedSpec 型変更への追従
+
+`@markuplint/ml-spec` が `ExtendedSpec` や `ExtendedElementSpec` の型を変更した場合:
+
+1. どのフィールドが追加、削除、変更されたか確認
+2. `src/index.ts` のアセンブリロジック（`json` オブジェクト）を更新
+3. 新しいフィールドを外部データから取得する必要がある場合はスクレイピングモジュールを更新
+4. ビルドと再生成で確認
+
+### 5. cheerio メジャーバージョン更新時の対応
+
+`cheerio` パッケージはスクレイピングに使用される DOM API を提供します。更新時:
+
+1. cheerio の変更履歴で破壊的 API 変更を確認
+2. 使用されている主要 API: `.find()`, `.text()`, `.attr()`, `.toArray()`, `.each()`, `.next()`, `.prev()`, `.parent()`, `.children()`, `.before()`, `.remove()`, `.clone()`, `.append()`, `.filter()`, `.siblings()`, `.prop()`
+3. `cheerio.load()`（`fetch.ts` で使用）も確認
+4. HTML パース動作が変更された場合はセレクタを更新
+5. ビルドと再生成で確認
+
+## デバッグ
+
+### 個別要素のスクレイピング結果確認
+
+特定の要素についてスクレイピングされるデータをデバッグするには:
+
+1. `scraping.ts` の `fetchHTMLElement()` 呼び出し後に一時的なログを追加:
+   ```typescript
+   const mdnData = await fetchHTMLElement(cite);
+   if (localName === 'your-element') {
+     console.log(JSON.stringify(mdnData, null, 2));
+   }
+   ```
+2. ビルドして `yarn up:gen` を実行
+3. スクレイピングデータのコンソール出力を確認
+4. デバッグ後に一時的なログを削除
+
+### キャッシュされたフェッチ結果の調査
+
+`fetch.ts` の `cache` Map はすべての生の HTML レスポンスを保存しています。特定の URL のフェッチ内容を調査するには:
+
+1. `fetchText()` に一時的なログを追加:
+   ```typescript
+   if (url.includes('your-search-term')) {
+     console.log(`Fetched ${url}: ${text.length} chars`);
+   }
+   ```
+2. 長さが 0 の場合はフェッチ失敗を示す（空文字列がキャッシュされた）
+
+### ARIA ロールスクレイピングの確認
+
+特定の ARIA バージョンから抽出されたロールを確認するには:
+
+1. `getAria()` 内の `getRoles()` 後に一時的なログを追加:
+   ```typescript
+   const roles13 = await getRoles('1.3');
+   console.log(`ARIA 1.3 roles: ${roles13.map(r => r.name).join(', ')}`);
+   ```
+
+## 依存関係メモ
+
+### cheerio
+
+- バージョン: 1.1.2
+- パースされた HTML に対する jQuery 風 DOM API を提供
+- `scraping.ts`, `aria.ts`, `svg.ts`, `fetch.ts` 全体で使用
+- `CheerioAPI` 型は `cheerio` から、`Element` は `domhandler`（cheerio の基盤 DOM ライブラリ）からインポート
+
+### fast-xml-parser
+
+- バージョン: 5.3.4
+- 依存として記載されているが、現在どのソースモジュールからもインポートされていない
+- 将来の XML パースニーズのために予約されている可能性あり
+
+### strip-json-comments
+
+- バージョン: 5.0.3
+- `read-json.ts` で JSON 仕様ファイルの `//` および `/* */` コメントをサポートするために使用
+- `html-spec` パッケージは仕様ファイルの先頭に仕様 URL の参照としてコメントを使用
+
+### cli-progress
+
+- バージョン: 3.12.0
+- フェッチ操作中のターミナルプログレスバーを提供
+- `fetch.ts` でモジュール読み込み時に初期化
+- `shades_grey` プリセットを使用

package/docs/maintenance.md

@@ -0,0 +1,212 @@
+# Maintenance Guide
+
+Practical operations and maintenance guide for `@markuplint/spec-generator`.
+
+## Commands
+
+| Command                                               | Description                                              |
+| ----------------------------------------------------- | -------------------------------------------------------- |
+| `yarn build --scope @markuplint/spec-generator`       | Compile TypeScript to `lib/`                             |
+| `yarn workspace @markuplint/spec-generator run dev`   | Watch mode compilation                                   |
+| `yarn workspace @markuplint/spec-generator run clean` | Clean compiled output                                    |
+| `yarn up:gen`                                         | Run spec generation (invokes this package via html-spec) |
+
+**Note:** This package is not run directly. It is consumed by `@markuplint/html-spec/build.mjs`, which calls `main()`. Use `yarn up:gen` to trigger a full generation.
+
+## Troubleshooting
+
+### Scraping Failure Detection
+
+After running `yarn up:gen`, always check the `index.json` diff:
+
+```bash
+git diff packages/@markuplint/html-spec/index.json
+```
+
+**Signs of scraping failure:**
+
+- The diff shows an extremely large amount of data loss (specification data disappears in bulk)
+- Multiple elements suddenly have empty `description` fields
+- Attributes that were previously present are removed
+- ARIA role or property definitions are empty or significantly reduced
+
+**This is almost certainly a scraping failure**, not an actual specification change. Legitimate spec changes are incremental and affect small numbers of elements.
+
+**Root cause:** The referenced site (MDN or W3C) has changed its HTML structure, information layout, or element IDs/classes.
+
+**Resolution:**
+
+1. Identify which data is affected (element metadata, ARIA roles, SVG elements, etc.)
+2. Determine the responsible module:
+   - Element descriptions, categories, attributes -- `scraping.ts`
+   - ARIA roles and properties -- `aria.ts`
+   - SVG deprecated elements -- `svg.ts`
+3. Open the affected web page in a browser and inspect its current HTML structure
+4. Update the CSS selectors in the module to match the new structure
+5. Rebuild: `yarn build --scope @markuplint/spec-generator`
+6. Regenerate: `yarn up:gen`
+7. Verify the `index.json` diff is now correct
+
+### Build Compilation Errors
+
+If `yarn build --scope @markuplint/spec-generator` fails:
+
+1. Check if `@markuplint/ml-spec` types have changed (this is the primary type provider)
+2. Verify that dev dependencies are installed: `yarn install`
+3. Try a clean build: `yarn workspace @markuplint/spec-generator run clean && yarn build --scope @markuplint/spec-generator`
+
+### Network Errors During Generation
+
+**Symptom:** `yarn up:gen` fails or hangs.
+
+**Cause:** MDN or W3C servers are unreachable.
+
+**Resolution:**
+
+- Check network connectivity
+- Failed fetches are cached as empty strings and the build continues
+- The progress bar shows the current URL being fetched -- identify which domain is failing
+- Retry later when the service is available
+
+## Common Recipes
+
+### 1. Fixing MDN Page Structure Changes
+
+When MDN restructures their element reference pages, the CSS selectors in `scraping.ts` need updating.
+
+1. Identify affected selectors by comparing the actual page HTML with the selectors in `scraping.ts`
+2. Key selectors to check:
+   - `MAIN_ARTICLE_SELECTOR` (`main#content`) -- main content area
+   - `.reference-layout__header .content-section` -- description extraction
+   - `.bc-table tbody tr:first-child th` -- compatibility table
+   - `#technical_summary ~ figure.table-container > table` -- technical summary
+   - `.content-section[aria-labelledby="attributes"]` -- attribute sections
+   - Icon classes (`.ic-experimental`, `.ic-deprecated`, etc.) -- status flags
+3. Update the selectors to match the new structure
+4. Build: `yarn build --scope @markuplint/spec-generator`
+5. Regenerate: `yarn up:gen`
+6. Verify the diff shows correct data restoration
+
+### 2. Adding a New ARIA Version
+
+When a new ARIA specification version is published (e.g., 1.4):
+
+1. Open `src/aria.ts`
+2. Add a new case in `getARIASpecURLByVersion()`:
+   ```typescript
+   case '1.4': {
+     if (!graphicsAria) {
+       return 'https://www.w3.org/TR/wai-aria-1.4/'; // or editor's draft URL
+     }
+     return 'https://w3c.github.io/graphics-aria/';
+   }
+   ```
+3. Add the new version to `getAria()`:
+   ```typescript
+   const roles14 = await getRoles('1.4');
+   // ...
+   '1.4': {
+     roles: roles14,
+     props: await getProps('1.4', roles14),
+     graphicsRoles: await getRoles('1.4', true),
+   },
+   ```
+4. **Cross-package:** The `ARIAVersion` type in `@markuplint/ml-spec` must also be updated to include `'1.4'`
+5. Build and regenerate
+
+### 3. Adding Elements to the Obsolete List
+
+To add a newly obsoleted HTML element:
+
+1. Open `src/html-elements.ts`
+2. Add the element name to the `obsoleteList` array
+3. The element will automatically get a minimal spec stub with `obsolete: true`
+4. Build: `yarn build --scope @markuplint/spec-generator`
+5. Regenerate: `yarn up:gen`
+6. Verify the element appears in `index.json` with `"obsolete": true`
+
+### 4. Adapting to ExtendedSpec Type Changes
+
+When `@markuplint/ml-spec` changes the `ExtendedSpec` or `ExtendedElementSpec` types:
+
+1. Check which fields were added, removed, or modified
+2. Update the assembly logic in `src/index.ts` (the `json` object)
+3. Update scraping modules if new fields need to be populated from external data
+4. Build and regenerate to verify
+
+### 5. Updating cheerio Major Versions
+
+The `cheerio` package provides the DOM API used for scraping. When updating:
+
+1. Check the cheerio changelog for breaking API changes
+2. Key APIs used: `.find()`, `.text()`, `.attr()`, `.toArray()`, `.each()`, `.next()`, `.prev()`, `.parent()`, `.children()`, `.before()`, `.remove()`, `.clone()`, `.append()`, `.filter()`, `.siblings()`, `.prop()`
+3. Also check `cheerio.load()` (used in `fetch.ts`)
+4. Update selectors if the HTML parsing behavior changed
+5. Build and regenerate to verify
+
+## Debugging
+
+### Checking Individual Element Scraping Results
+
+To debug what data is being scraped for a specific element:
+
+1. Add temporary logging in `scraping.ts` after the `fetchHTMLElement()` call:
+   ```typescript
+   const mdnData = await fetchHTMLElement(cite);
+   if (localName === 'your-element') {
+     console.log(JSON.stringify(mdnData, null, 2));
+   }
+   ```
+2. Rebuild and run `yarn up:gen`
+3. Check the console output for the scraped data
+4. Remove the temporary logging after debugging
+
+### Inspecting Cached Fetch Results
+
+The `cache` Map in `fetch.ts` stores all raw HTML responses. To inspect what was fetched for a specific URL:
+
+1. Add temporary logging in `fetchText()`:
+   ```typescript
+   if (url.includes('your-search-term')) {
+     console.log(`Fetched ${url}: ${text.length} chars`);
+   }
+   ```
+2. A length of 0 indicates a fetch failure (empty string cached)
+
+### Verifying ARIA Role Scraping
+
+To check which roles were extracted from a specific ARIA version:
+
+1. Add temporary logging after `getRoles()` in `getAria()`:
+   ```typescript
+   const roles13 = await getRoles('1.3');
+   console.log(`ARIA 1.3 roles: ${roles13.map(r => r.name).join(', ')}`);
+   ```
+
+## Dependency Notes
+
+### cheerio
+
+- Version: 1.1.2
+- Provides jQuery-like DOM API for parsed HTML
+- Used throughout `scraping.ts`, `aria.ts`, `svg.ts`, and `fetch.ts`
+- The `CheerioAPI` type is imported from `cheerio`, and `Element` from `domhandler` (cheerio's underlying DOM library)
+
+### fast-xml-parser
+
+- Version: 5.3.4
+- Listed as a dependency but not currently imported by any source module
+- May be reserved for future XML parsing needs
+
+### strip-json-comments
+
+- Version: 5.0.3
+- Used in `read-json.ts` to support `//` and `/* */` comments in JSON spec files
+- The `html-spec` package uses comments at the top of spec files for spec URL references
+
+### cli-progress
+
+- Version: 3.12.0
+- Provides the terminal progress bar during fetch operations
+- Initialized at module load time in `fetch.ts`
+- Uses the `shades_grey` preset

package/docs/modules.ja.md

@@ -0,0 +1,252 @@
+# モジュールリファレンス
+
+`@markuplint/spec-generator` の各ソースモジュールの詳細ドキュメント。
+
+## index.ts
+
+メインオーケストレータ。`@markuplint/html-spec/build.mjs` が消費する公開 API をエクスポートします。
+
+### `main(options: Options): Promise<void>`
+
+3つの並列データ収集タスクを調整し、結果を `ExtendedSpec` オブジェクトに組み立て、JSON として書き込みます。
+
+**フロー:**
+
+1. `Promise.all` で3つのタスクを同時実行:
+   - `getElements(htmlFilePattern)` -- 要素仕様
+   - `getGlobalAttrs(commonAttrsFilePath)` -- グローバル属性定義
+   - `getAria()` -- ARIA 定義
+2. `getReferences()` でフェッチした全 URL を収集
+3. `readJson(commonContentsFilePath).models` でコンテンツモデルを読み込み
+4. `ExtendedSpec` オブジェクトを組み立て:
+   ```typescript
+   {
+     cites: string[],              // ソート済み URL リスト
+     def: {
+       "#globalAttrs": { ... },    // グローバル属性カテゴリ
+       "#aria": { ... },           // バージョンごとの ARIA データ
+       "#contentModels": { ... }   // コンテンツモデルカテゴリ
+     },
+     specs: ExtendedElementSpec[]  // 要素仕様
+   }
+   ```
+5. JSON を `outputFilePath` に書き込み
+
+### `Options` 型
+
+| フィールド               | 型       | 説明                                         |
+| ------------------------ | -------- | -------------------------------------------- |
+| `outputFilePath`         | `string` | 生成 JSON の書き込み先の絶対パス             |
+| `htmlFilePattern`        | `string` | 要素ごとの JSON ファイルの絶対 glob パターン |
+| `commonAttrsFilePath`    | `string` | グローバル属性 JSON の絶対パス               |
+| `commonContentsFilePath` | `string` | コンテンツモデル JSON の絶対パス             |
+
+---
+
+## html-elements.ts
+
+HTML および SVG 要素仕様の完全なリストを構築します。
+
+### `getElements(filePattern: string): Promise<ExtendedElementSpec[]>`
+
+**フロー:**
+
+1. `readJsons()` で glob パターンにマッチする全仕様ファイルを読み込み。要素名は正規表現 `spec.([\w-]+).json` でファイル名から抽出（例: `spec.a.json` → `a`）
+2. `getSVGElementList()` で非推奨 SVG 要素リストを取得
+3. `fetchObsoleteElements()` で既存の仕様にない非推奨要素のスタブを生成
+4. 各要素について MDN URL を構築し、`fetchHTMLElement()` でメタデータをスクレイピング:
+   - 見出し要素（`h1`-`h6`）は MDN パス `Heading_Elements` にマッピング
+   - SVG 要素は `/Web/SVG/Reference/Element/<name>` パスを使用
+   - HTML 要素は `/Web/HTML/Reference/Elements/<name>` パスを使用
+5. スクレイピングデータとローカル仕様データをマージ。**ローカル仕様データが優先**:
+   - `cite` -- ローカル値があればそちらを使用、なければ MDN URL
+   - `description`, `categories`, `omission` -- MDN から
+   - `contentModel`, `aria` -- ローカル仕様のみ（スクレイピングされない）
+   - `attributes` -- 属性名ごとにマージ; ローカルエントリが MDN エントリをオーバーライド
+6. アルファベット順にソートし、SVG 要素を HTML 要素の後に配置
+
+### `obsoleteList`
+
+31個の非適合 HTML 要素のハードコードリスト:
+
+`applet`, `acronym`, `bgsound`, `dir`, `frame`, `frameset`, `noframes`, `isindex`, `keygen`, `listing`, `menuitem`, `nextid`, `noembed`, `param`, `plaintext`, `rb`, `rtc`, `strike`, `xmp`, `basefont`, `big`, `blink`, `center`, `font`, `marquee`, `multicol`, `nobr`, `spacer`, `tt`
+
+MDN から取得した非推奨 SVG 要素と組み合わせて、完全な非推奨セットを構成します。
+
+---
+
+## scraping.ts
+
+MDN 要素リファレンスページからメタデータをスクレイピングします。CSS セレクタと脆弱ポイントの詳細は[スクレイピング詳細](scraping.ja.md)を参照。
+
+### `fetchHTMLElement(link: string): Promise<ExtendedElementSpec>`
+
+単一の MDN 要素ページをスクレイピングし、以下を含む要素仕様オブジェクトを返します:
+
+- `description` -- `.reference-layout__header .content-section` から
+- 互換性フラグ（`experimental`, `obsolete`, `deprecated`, `nonStandard`）-- ブラウザ互換性テーブルまたはフォールバックインジケータから
+- `categories` -- 技術サマリテーブルの「Content categories」行をパース
+- `attributes` -- `aria-labelledby` ID で識別されるセクションの定義リストから: `attributes`, `deprecated_attributes`, `individual_attributes`, `non-standard_attributes`, `obsolete_attributes`
+
+### `fetchObsoleteElements(obsoleteList, specs): ExtendedElementSpec[]`
+
+既存の仕様配列に存在しない非推奨要素の最小限のスタブを生成。各スタブは:
+
+- `cite` は HTML 仕様の非推奨機能セクションを指す
+- `obsolete: true`
+- `contents: true`（任意のコンテンツ許可）
+- `permittedRoles: true`, `implicitRole: false`
+
+### プライベートヘルパー
+
+- `getProperty($, prop)` -- MDN 技術サマリテーブル（`#technical_summary ~ figure.table-container > table`）から値を抽出
+- `getAttributes($, id)` -- `.content-section[aria-labelledby="<id>"]` セクションの `<dt>`/`<dd>` ペアをパース
+- `getItsHeading($start)` -- DOM を上方にたどって最も近い先行見出しを検索
+- `upToPrevOrParent($start)` -- 前の兄弟要素またはに移動
+- `isHeading($el)` -- 要素が `<h1>` から `<h6>` かどうかをテスト
+
+---
+
+## aria.ts
+
+W3C ARIA 仕様からロールとプロパティの定義をスクレイピングします。URL パターンとセレクタの詳細は[スクレイピング詳細](scraping.ja.md)を参照。
+
+### `getAria(): Promise<Record<ARIAVersion, { roles, props, graphicsRoles }>>`
+
+サポートされている3つのバージョンすべての ARIA データを返します。各バージョンについて:
+
+1. `getRoles(version)` でロールを取得
+2. `getProps(version, roles)` でプロパティ/ステートを取得
+3. `getRoles(version, true)` でグラフィックス ARIA ロールを取得
+
+**実行順序:** バージョンは順次処理されます（1.3 → 1.2 → 1.1）。各バージョン内では、プロパティの前にロールを取得する必要があります（プロパティはロールの `ownedProperties` から検出されるため）。
+
+### URL マッピング
+
+| バージョン | ARIA 仕様 URL                         | Graphics ARIA URL                          |
+| ---------- | ------------------------------------- | ------------------------------------------ |
+| 1.1        | `https://www.w3.org/TR/wai-aria-1.1/` | `https://www.w3.org/TR/graphics-aria-1.0/` |
+| 1.2        | `https://www.w3.org/TR/wai-aria-1.2/` | `https://w3c.github.io/graphics-aria/`     |
+| 1.3        | `https://w3c.github.io/aria/`         | `https://w3c.github.io/graphics-aria/`     |
+
+### プライベート関数
+
+- `getRoles(version, graphicsAria?)` -- `#role_definitions section.role` 要素をスクレイピング。抽出内容: name, description, generalization, owned properties（required/inherited/general）, required context roles, required owned elements, accessible name 設定, children presentational フラグ, prohibited properties。ロールの同義語を処理（`none`/`presentation`, `image`/`img`）
+- `getProps(version, roles)` -- 全ロールの `ownedProperties` からプロパティリストを構築し、各プロパティのセクションをスクレイピング: type（property/state）, value type, enum values, default value, global フラグ, 同等の HTML 属性。`aria-checked` と `aria-hidden` の条件付き値オーバーライドを適用
+- `getAriaInHtml()` -- `https://www.w3.org/TR/html-aria/` から HTML 属性と ARIA プロパティのマッピングテーブルをスクレイピング。`contenteditable` はスキップ（祖先の評価が必要なため）
+- `$$(el, selectors)` -- 複数の CSS セレクタを試し、最初の非空マッチを返す
+
+---
+
+## fetch.ts
+
+キャッシュとプログレス表示付きの HTTP フェッチレイヤー。
+
+### キャッシュ
+
+2つのインメモリ `Map` キャッシュ:
+
+| キャッシュ | キー | 値                        | 目的                        |
+| ---------- | ---- | ------------------------- | --------------------------- |
+| `cache`    | URL  | 生の HTML 文字列          | 同じ URL の再フェッチを回避 |
+| `domCache` | URL  | `CheerioAPI` インスタンス | 同じ HTML の再パースを回避  |
+
+キャッシュはプロセススコープです。ビルド間での永続化はありません。
+
+### `fetch(url: string): Promise<CheerioAPI>`
+
+パース済みの Cheerio DOM インスタンスを返します。まず `domCache` を確認し、なければ `fetchText()` に委譲して生の HTML を取得します。
+
+### `fetchText(url: string): Promise<string>`
+
+`globalThis.fetch()` を使用して URL の生テキストコンテンツを取得します。失敗時（例外発生時）は空文字列をキャッシュして返します。各呼び出しで CLI プログレスバーを更新します。
+
+### `getReferences(): string[]`
+
+プログレスバーを終了し、フェッチした全 URL のソート済みリストを返します。全スクレイピング完了後に一度だけ呼び出されます。
+
+### プログレスバー
+
+`cli-progress` の `shades_grey` プリセットを使用。モジュール読み込み時にバーが開始され、各フェッチ呼び出しで更新されます。フォーマット:
+
+```
+🔎 Fetch references... ████░░░░ 45% | ETA: 30s | 90/200 🔗 https://develo...ments/div
+```
+
+---
+
+## read-json.ts
+
+コメントサポート付き JSON ファイル読み込み。
+
+### `readJson<T>(filePath: string): T`
+
+単一の JSON ファイルを読み込みます。`strip-json-comments` を使用してパース前に `//` および `/* */` コメントを除去します。パスが絶対パスでない場合はエラーをスローします。
+
+### `readJsons<T>(pattern: string, hook?): Promise<T[]>`
+
+絶対 glob パターンにマッチする全 JSON ファイルを読み込みます。オプションで `hook` 関数により各結果を変換可能（ファイル名とパース済みボディを受け取る）。全ファイルを `Promise.all` で並列読み込みします。
+
+---
+
+## global-attrs.ts
+
+### `getGlobalAttrs(filePath: string): SpecDefs["#globalAttrs"]`
+
+`readJson()` の薄いラッパーで、指定された JSON ファイルからグローバル属性定義を読み込んで返します。
+
+---
+
+## svg.ts
+
+### `getSVGElementList(): Promise<string[]>`
+
+MDN SVG 要素インデックスページ（`https://developer.mozilla.org/en-US/docs/Web/SVG/Element`）をフェッチし、「Obsolete and deprecated elements」セクションから非推奨/廃止 SVG 要素名を抽出します。
+
+**処理:**
+
+1. すべての `<section>` ラッパーをアンラップ（子要素で置換）
+2. `#obsolete_and_deprecated_elements` 見出しを検索
+3. `getThisOutline()` で次の `<h2>` まで兄弟要素を収集
+4. `<a>` タグから要素名を抽出し、`svg_` プレフィックスを付加
+
+`["svg_altGlyph", "svg_altGlyphDef", ...]` のような名前を返します。
+
+---
+
+## utils.ts
+
+複数のモジュールで使用される共有ヘルパー関数。
+
+### `nameCompare(a, b): number`
+
+`name` プロパティ（または文字列値）による大文字小文字を区別しない比較。コードベース全体でソートのコンパレータとして使用。
+
+### `sortObjectByKey<T>(o: T): T`
+
+同じキーバリューペアを持つ新しいオブジェクトを、キーのアルファベット順（`nameCompare` 使用）でソートして返します。
+
+### `arrayUnique<T extends { name: string }>(array: T[]): T[]`
+
+`name` プロパティに基づいて重複項目を除去し、最初の出現のみを保持します。
+
+### `getThisOutline($, $start): Cheerio<Element>`
+
+`$start` の後の全兄弟要素を次の `<h2>` 見出しまで収集し、コンテナ `<div>` でラップします。`svg.ts` で見出しで定義されたセクションのコンテンツを抽出するために使用。
+
+### `mergeAttributes<T>(fromDocs: T, fromJSON: T): T`
+
+2つの属性オブジェクトを浅くマージし、`fromJSON` の値を優先します。
+
+### `keys<T, K>(object: T): K[]`
+
+カスタム型キャスト付きの `Object.keys()` を返します。
+
+### `getName(origin: string): { localName, namespace?, ml }`
+
+要素名文字列をパース:
+
+| 入力           | `localName` | `namespace`                    | `ml`     |
+| -------------- | ----------- | ------------------------------ | -------- |
+| `"div"`        | `"div"`     | `undefined`                    | `"HTML"` |
+| `"svg_circle"` | `"circle"`  | `"http://www.w3.org/2000/svg"` | `"SVG"`  |