@markuplint/spec-generator 4.8.0 → 4.8.2

package/docs/modules.md

@@ -0,0 +1,252 @@
+# Module Reference
+
+Detailed documentation for each source module in `@markuplint/spec-generator`.
+
+## index.ts
+
+The main orchestrator. Exports the public API consumed by `@markuplint/html-spec/build.mjs`.
+
+### `main(options: Options): Promise<void>`
+
+Coordinates three parallel data-gathering tasks, assembles the results into an `ExtendedSpec` object, and writes it as JSON.
+
+**Flow:**
+
+1. Launch three tasks concurrently via `Promise.all`:
+   - `getElements(htmlFilePattern)` -- element specifications
+   - `getGlobalAttrs(commonAttrsFilePath)` -- global attribute definitions
+   - `getAria()` -- ARIA definitions
+2. Collect all fetched URLs via `getReferences()`
+3. Read content models via `readJson(commonContentsFilePath).models`
+4. Assemble the `ExtendedSpec` object:
+   ```typescript
+   {
+     cites: string[],              // Sorted URL list
+     def: {
+       "#globalAttrs": { ... },    // Global attribute categories
+       "#aria": { ... },           // ARIA data per version
+       "#contentModels": { ... }   // Content model categories
+     },
+     specs: ExtendedElementSpec[]  // Element specifications
+   }
+   ```
+5. Write the JSON to `outputFilePath`
+
+### `Options` type
+
+| Field                    | Type     | Description                                       |
+| ------------------------ | -------- | ------------------------------------------------- |
+| `outputFilePath`         | `string` | Absolute path where the generated JSON is written |
+| `htmlFilePattern`        | `string` | Absolute glob pattern for per-element JSON files  |
+| `commonAttrsFilePath`    | `string` | Absolute path to global attributes JSON           |
+| `commonContentsFilePath` | `string` | Absolute path to content models JSON              |
+
+---
+
+## html-elements.ts
+
+Builds the complete list of HTML and SVG element specifications.
+
+### `getElements(filePattern: string): Promise<ExtendedElementSpec[]>`
+
+**Flow:**
+
+1. Read all spec files matching the glob pattern via `readJsons()`. Element names are extracted from filenames using the regex `spec.([\w-]+).json` (e.g., `spec.a.json` becomes `a`)
+2. Fetch the deprecated SVG element list via `getSVGElementList()`
+3. Generate stubs for obsolete elements not already present via `fetchObsoleteElements()`
+4. For each element, construct the MDN URL and scrape metadata via `fetchHTMLElement()`:
+   - Heading elements (`h1`-`h6`) are mapped to MDN path `Heading_Elements`
+   - SVG elements use the path `/Web/SVG/Reference/Element/<name>`
+   - HTML elements use `/Web/HTML/Reference/Elements/<name>`
+5. Merge scraped data with local spec data. **Local spec data takes precedence**:
+   - `cite` -- local value wins if present, otherwise MDN URL
+   - `description`, `categories`, `omission` -- from MDN
+   - `contentModel`, `aria` -- from local spec only (never scraped)
+   - `attributes` -- merged per attribute name; local entries override MDN entries
+6. Sort alphabetically, with SVG elements placed after HTML elements
+
+### `obsoleteList`
+
+A hardcoded list of 31 non-conforming HTML elements:
+
+`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`
+
+These are combined with deprecated SVG elements fetched from MDN to form the complete obsolete set.
+
+---
+
+## scraping.ts
+
+Scrapes MDN element reference pages for metadata. See [Scraping Details](scraping.md) for CSS selectors and fragile points.
+
+### `fetchHTMLElement(link: string): Promise<ExtendedElementSpec>`
+
+Scrapes a single MDN element page and returns an element spec object containing:
+
+- `description` -- from `.reference-layout__header .content-section`
+- Compatibility flags (`experimental`, `obsolete`, `deprecated`, `nonStandard`) -- from the browser compatibility table or fallback indicators
+- `categories` -- parsed from the "Content categories" row in the technical summary table
+- `attributes` -- from definition lists in sections identified by `aria-labelledby` IDs: `attributes`, `deprecated_attributes`, `individual_attributes`, `non-standard_attributes`, `obsolete_attributes`
+
+### `fetchObsoleteElements(obsoleteList, specs): ExtendedElementSpec[]`
+
+Generates minimal spec stubs for obsolete elements not already present in the existing specs array. Each stub has:
+
+- `cite` pointing to the HTML spec obsolete features section
+- `obsolete: true`
+- `contents: true` (any content allowed)
+- `permittedRoles: true`, `implicitRole: false`
+
+### Private helpers
+
+- `getProperty($, prop)` -- Extracts a value from the MDN technical summary table (`#technical_summary ~ figure.table-container > table`)
+- `getAttributes($, id)` -- Parses `<dt>`/`<dd>` pairs from a `.content-section[aria-labelledby="<id>"]` section
+- `getItsHeading($start)` -- Traverses DOM upward to find the nearest preceding heading
+- `upToPrevOrParent($start)` -- Moves to previous sibling or parent
+- `isHeading($el)` -- Tests if an element is `<h1>` through `<h6>`
+
+---
+
+## aria.ts
+
+Scrapes W3C ARIA specifications for role and property definitions. See [Scraping Details](scraping.md) for URL patterns and selectors.
+
+### `getAria(): Promise<Record<ARIAVersion, { roles, props, graphicsRoles }>>`
+
+Returns ARIA data for all three supported versions. For each version:
+
+1. Fetch roles via `getRoles(version)`
+2. Fetch properties/states via `getProps(version, roles)`
+3. Fetch graphics ARIA roles via `getRoles(version, true)`
+
+**Execution order:** Versions are processed sequentially (1.3, then 1.2, then 1.1). Within each version, roles must be fetched before properties (properties are discovered from the roles' `ownedProperties`).
+
+### URL mapping
+
+| Version | ARIA Spec 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/`     |
+
+### Private functions
+
+- `getRoles(version, graphicsAria?)` -- Scrapes `#role_definitions section.role` elements. Extracts: name, description, generalization, owned properties (required/inherited/general), required context roles, required owned elements, accessible name settings, children presentational flag, prohibited properties. Handles role synonyms (`none`/`presentation`, `image`/`img`)
+- `getProps(version, roles)` -- Builds a property list from all role `ownedProperties`, then scrapes each property's section for: type (property/state), value type, enum values, default value, global flag, equivalent HTML attributes. Applies conditional value overrides for `aria-checked` and `aria-hidden`
+- `getAriaInHtml()` -- Scrapes `https://www.w3.org/TR/html-aria/` for the HTML attribute to ARIA property mapping table. Skips `contenteditable` (requires ancestor evaluation)
+- `$$(el, selectors)` -- Tries multiple CSS selectors and returns the first non-empty match
+
+---
+
+## fetch.ts
+
+HTTP fetching layer with caching and progress display.
+
+### Caching
+
+Two in-memory `Map` caches:
+
+| Cache      | Key | Value                 | Purpose                         |
+| ---------- | --- | --------------------- | ------------------------------- |
+| `cache`    | URL | Raw HTML string       | Avoids re-fetching the same URL |
+| `domCache` | URL | `CheerioAPI` instance | Avoids re-parsing the same HTML |
+
+Caches are process-scoped. There is no persistence between builds.
+
+### `fetch(url: string): Promise<CheerioAPI>`
+
+Returns a parsed Cheerio DOM instance. Checks `domCache` first, then delegates to `fetchText()` for the raw HTML.
+
+### `fetchText(url: string): Promise<string>`
+
+Fetches the raw text content of a URL using `globalThis.fetch()`. On failure (any exception), caches and returns an empty string. Updates the CLI progress bar on each call.
+
+### `getReferences(): string[]`
+
+Finalizes the progress bar and returns a sorted list of all fetched URLs. Called once after all scraping is complete.
+
+### Progress bar
+
+Uses `cli-progress` with the `shades_grey` preset. The bar starts at module load time and is updated with each fetch call. Format:
+
+```
+🔎 Fetch references... ████░░░░ 45% | ETA: 30s | 90/200 🔗 https://develo...ments/div
+```
+
+---
+
+## read-json.ts
+
+JSON file reading with comment support.
+
+### `readJson<T>(filePath: string): T`
+
+Reads a single JSON file. Uses `strip-json-comments` to remove `//` and `/* */` comments before parsing. Throws if the path is not absolute.
+
+### `readJsons<T>(pattern: string, hook?): Promise<T[]>`
+
+Reads all JSON files matching an absolute glob pattern. Optionally transforms each result via the `hook` function (receives filename and parsed body). All files are read in parallel via `Promise.all`.
+
+---
+
+## global-attrs.ts
+
+### `getGlobalAttrs(filePath: string): SpecDefs["#globalAttrs"]`
+
+A thin wrapper around `readJson()` that reads and returns the global attributes definition from the specified JSON file.
+
+---
+
+## svg.ts
+
+### `getSVGElementList(): Promise<string[]>`
+
+Fetches the MDN SVG element index page (`https://developer.mozilla.org/en-US/docs/Web/SVG/Element`) and extracts deprecated/obsolete SVG element names from the "Obsolete and deprecated elements" section.
+
+**Processing:**
+
+1. Unwrap all `<section>` wrappers (replace with their children)
+2. Find the `#obsolete_and_deprecated_elements` heading
+3. Collect siblings until the next `<h2>` via `getThisOutline()`
+4. Extract element names from `<a>` tags, prefixed with `svg_`
+
+Returns names like `["svg_altGlyph", "svg_altGlyphDef", ...]`.
+
+---
+
+## utils.ts
+
+Shared helper functions used across multiple modules.
+
+### `nameCompare(a, b): number`
+
+Case-insensitive comparison by `name` property (or string value). Used as a sort comparator throughout the codebase.
+
+### `sortObjectByKey<T>(o: T): T`
+
+Returns a new object with the same key-value pairs sorted alphabetically by key (using `nameCompare`).
+
+### `arrayUnique<T extends { name: string }>(array: T[]): T[]`
+
+Removes duplicate items based on their `name` property, keeping the first occurrence.
+
+### `getThisOutline($, $start): Cheerio<Element>`
+
+Collects all sibling elements after `$start` until the next `<h2>` heading, wrapping them in a container `<div>`. Used by `svg.ts` to extract a section of content defined by a heading.
+
+### `mergeAttributes<T>(fromDocs: T, fromJSON: T): T`
+
+Shallow-merges two attribute objects with `fromJSON` values taking precedence.
+
+### `keys<T, K>(object: T): K[]`
+
+Returns `Object.keys()` with a custom type cast.
+
+### `getName(origin: string): { localName, namespace?, ml }`
+
+Parses an element name string:
+
+| Input          | `localName` | `namespace`                    | `ml`     |
+| -------------- | ----------- | ------------------------------ | -------- |
+| `"div"`        | `"div"`     | `undefined`                    | `"HTML"` |
+| `"svg_circle"` | `"circle"`  | `"http://www.w3.org/2000/svg"` | `"SVG"`  |

package/docs/scraping.ja.md

@@ -0,0 +1,320 @@
+# スクレイピング詳細
+
+このドキュメントでは、`@markuplint/spec-generator` が使用するウェブスクレイピングの対象、CSS セレクタ、キャッシュ戦略、エラー処理について説明します。ビルドはネットワーク依存で、MDN および W3C 仕様に対して 200 以上の HTTP リクエストを発行します。
+
+## MDN 要素スクレイピング
+
+**モジュール:** `scraping.ts`
+
+### URL パターン
+
+HTML 要素:
+
+```
+https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/<name>
+```
+
+SVG 要素:
+
+```
+https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/<name>
+```
+
+**特殊ケース:** 見出し要素（`h1`-`h6`）は単一のページにマッピング:
+
+```
+https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements
+```
+
+### 抽出データ
+
+各要素について `fetchHTMLElement()` が抽出する項目:
+
+| データ   | セレクタ / メソッド                                                             | 備考                                                                        |
+| -------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| 説明     | `main#content .reference-layout__header .content-section`                       | テキストコンテンツ、空白正規化済み                                          |
+| 互換性   | `.bc-table tbody tr:first-child th`（アイコン）                                 | BC テーブルが利用不可の場合は notecard ベースのインジケータにフォールバック |
+| カテゴリ | `#technical_summary ~ figure.table-container > table`（「Content categories」） | 既知のカテゴリキーワードとマッチング                                        |
+| 属性     | `.content-section[aria-labelledby="<id>"] > dl > dt`                            | 複数セクションの定義リストからパース                                        |
+
+### 互換性フラグの検出
+
+ブラウザ互換性テーブルの有無に応じて2つの戦略を使用:
+
+**戦略 1: ブラウザ互換性テーブル**（最初の行の `<code>` が要素名と一致する場合）
+
+| フラグ         | `tbody tr:first-child th` 内のセレクタ |
+| -------------- | -------------------------------------- |
+| `experimental` | `.ic-experimental`                     |
+| `obsolete`     | `.ic-obsolete`                         |
+| `deprecated`   | `.ic-deprecated`                       |
+| `nonStandard`  | `.ic-non-standard`                     |
+
+**戦略 2: フォールバックインジケータ**（BC テーブルがない、またはマッチしない場合）
+
+| フラグ         | セレクタ                                                                                                 |
+| -------------- | -------------------------------------------------------------------------------------------------------- |
+| `experimental` | `.blockIndicator.experimental` または `> div .notecard.experimental`                                     |
+| `obsolete`     | `.obsoleteHeader` または `h1` テキストに "obsolete" を含む または `> div:first-child .notecard.obsolete` |
+| `deprecated`   | `.deprecatedHeader` または `> div:first-child .notecard.deprecated` または `h1 + * .notecard.deprecated` |
+| `nonStandard`  | `.nonStandardHeader` または `h4#Non-standard`                                                            |
+
+### コンテンツカテゴリのパース
+
+「Content categories」プロパティは技術サマリテーブルから抽出されます。テキストは以下のキーワードとマッチング（大文字小文字不区別）:
+
+| キーワード            | カテゴリ             |
+| --------------------- | -------------------- |
+| `metadata content`    | `#metadata`          |
+| `flow content`        | `#flow`              |
+| `sectioning content`  | `#sectioning`        |
+| `heading content`     | `#heading`           |
+| `phrasing content`    | `#phrasing`          |
+| `embedded content`    | `#embedded`          |
+| `interactive content` | `#interactive`       |
+| `palpable content`    | `#palpable`          |
+| `script-supporting`   | `#script-supporting` |
+
+### 属性の抽出
+
+属性は `aria-labelledby` ID で識別される最大5つのセクションから抽出:
+
+| セクション ID             | 適用されるステータスフラグ     |
+| ------------------------- | ------------------------------ |
+| `attributes`              | 属性ごとのアイコンからのフラグ |
+| `deprecated_attributes`   | 見出しから `deprecated: true`  |
+| `individual_attributes`   | 属性ごとのアイコンからのフラグ |
+| `non-standard_attributes` | 属性ごとのアイコンからのフラグ |
+| `obsolete_attributes`     | 見出しから `obsolete: true`    |
+
+各 `<dt>` エントリについて:
+
+1. `<code>` テキストから属性名を抽出
+2. 次の `<dd>` 兄弟要素から説明を抽出
+3. アイコンクラスからステータスフラグを検出:
+   - `.icon-beaker`, `.icon.experimental`, `.icon.icon-experimental` -- experimental
+   - `.icon-trash`, `.icon.obsolete`, `.icon.icon-obsolete`, `.obsolete` -- obsolete
+   - `.icon-thumbs-down-alt`, `.icon.deprecated`, `.icon.icon-deprecated` -- deprecated
+   - `.icon-warning-sign`, `.icon.non-standard`, `.icon.icon-nonstandard` -- non-standard
+4. 見出しコンテキスト（`getItsHeading()`）でセクションレベルのフラグを確認
+
+抽出した全属性はマージされ、キーでソートされます。
+
+---
+
+## MDN SVG インデックススクレイピング
+
+**モジュール:** `svg.ts`
+
+### 対象
+
+```
+https://developer.mozilla.org/en-US/docs/Web/SVG/Element
+```
+
+### 抽出プロセス
+
+1. すべての `<section>` 要素をアンラップ（子要素で置換）してドキュメント構造をフラット化
+2. `id="obsolete_and_deprecated_elements"` の見出しを検索
+3. `getThisOutline()` で次の `<h2>` まで全兄弟要素を収集
+4. `div > a` 要素から要素名を抽出し、山括弧を除去
+5. 各名前に `svg_` プレフィックスを付加（例: `altGlyph` → `svg_altGlyph`）
+
+---
+
+## WAI-ARIA スクレイピング
+
+**モジュール:** `aria.ts`
+
+### 仕様 URL
+
+| バージョン | URL                                   | ステータス             |
+| ---------- | ------------------------------------- | ---------------------- |
+| 1.1        | `https://www.w3.org/TR/wai-aria-1.1/` | 勧告（Recommendation） |
+| 1.2        | `https://www.w3.org/TR/wai-aria-1.2/` | 勧告（Recommendation） |
+| 1.3        | `https://w3c.github.io/aria/`         | 草案（Working Draft）  |
+
+### ロールの抽出
+
+**セレクタ:** `#role_definitions section.role`
+
+各ロールセクションについて:
+
+| データ                           | セレクタ                                             |
+| -------------------------------- | ---------------------------------------------------- |
+| 名前                             | `.role-name[title]`                                  |
+| 説明                             | `.role-description p`（`\n\n` で結合）               |
+| 抽象かどうか                     | `.role-abstract` テキストが "true"                   |
+| 汎化                             | `.role-parent a`                                     |
+| 必須プロパティ                   | `.role-required-properties li`（親にフォールバック） |
+| 継承プロパティ                   | `.role-inherited li`                                 |
+| 所有プロパティ                   | `.role-properties li` または `.role-properties > a`  |
+| 必須コンテキストロール           | `.role-scope li` または `.role-scope a`              |
+| 必須所有要素                     | `.role-mustcontain li` または `.role-mustcontain a`  |
+| アクセシブル名必須               | `.role-namerequired` に "true" を含む                |
+| アクセシブル名（著者から）       | `.role-namefrom` に "author" を含む                  |
+| アクセシブル名（コンテンツから） | `.role-namefrom` に "content" を含む                 |
+| アクセシブル名禁止               | `.role-namefrom` に "prohibited" を含む              |
+| 子の表示                         | `.role-childpresentational` "true"/"false"           |
+| 禁止プロパティ                   | `.role-disallowed li code`                           |
+
+**ロール同義語の処理:**
+
+- ARIA 1.1/1.2: `none` は `presentation` からプロパティを継承
+- ARIA 1.3: `presentation` は `none` から継承; `img` は `image` から継承
+
+### プロパティ/ステートの抽出
+
+プロパティは、スクレイピングした全ロールの `ownedProperties` から検出されます。各プロパティについて:
+
+**セレクタベース:** `#<property-name>`（例: `#aria-label`）
+
+| データ             | セレクタ                                                                                       |
+| ------------------ | ---------------------------------------------------------------------------------------------- |
+| 型                 | セクションクラス: `/property/i` にマッチ → `"property"`、それ以外 → `"state"`                  |
+| 非推奨             | セクションクラスに "deprecated" を含む                                                         |
+| 値の型             | `table .${type}-value` または `table .property-value` または `.state-features .property-value` |
+| 値の説明           | `table:is(.value-descriptions, .def:has(.value-description)) tbody tr`                         |
+| 列挙値             | `.value-name` 要素から（`token` または `token list` 値型の場合のみ）                           |
+| デフォルト値       | `.value-name .default` テキスト                                                                |
+| グローバルかどうか | `#global_states li a` にリストされているか                                                     |
+
+**条件付き値のオーバーライド:**
+
+- `aria-checked`: 値を `"true/false"` に設定し、`checkbox` と `menuitemcheckbox` ロールに対して条件付きで `"tristate"` を追加
+- `aria-hidden`: `hidden` HTML 属性の同等物を `isNotStrictEquivalent` としてマーク
+
+### グローバルステート/プロパティ
+
+グローバル ARIA 属性は `#global_states li` 下の全 `<a>` リンクを収集して識別します。各リンクのハッシュフラグメントがプロパティ名として使用されます。
+
+---
+
+## Graphics ARIA スクレイピング
+
+**モジュール:** `aria.ts`
+
+Graphics ARIA ロールは、同じ `getRoles()` 関数に `graphicsAria = true` を渡してフェッチします。
+
+| バージョン | URL                                        |
+| ---------- | ------------------------------------------ |
+| 1.1        | `https://www.w3.org/TR/graphics-aria-1.0/` |
+| 1.2        | `https://w3c.github.io/graphics-aria/`     |
+| 1.3        | `https://w3c.github.io/graphics-aria/`     |
+
+標準 ARIA ロールと同じ CSS セレクタが Graphics ARIA ロールにも適用されます。
+
+---
+
+## HTML-ARIA マッピング
+
+**モジュール:** `aria.ts`（`getAriaInHtml()`）
+
+### 対象
+
+```
+https://www.w3.org/TR/html-aria/
+```
+
+### セレクタ
+
+```
+#requirements-for-use-of-aria-attributes-in-place-of-equivalent-html-attributes table tbody tr
+```
+
+各行について:
+
+- HTML 属性名: `th:nth-of-type(1) a`（最初のリンクテキスト）
+- 暗黙の ARIA プロパティ: `td:nth-of-type(1) code`（最初のコード要素テキスト）
+- プロパティ文字列を `=` で分割して ARIA プロパティ名と値を取得
+
+**スキップ:** `contenteditable` 属性は祖先の評価が必要なため除外されます。
+
+---
+
+## キャッシュ
+
+### プロセス内キャッシュ
+
+`fetch.ts` に2つの `Map` キャッシュが存在:
+
+| キャッシュ | キー | 値               | スコープ                               |
+| ---------- | ---- | ---------------- | -------------------------------------- |
+| `cache`    | URL  | 生の HTML 文字列 | 単一ビルド実行（プロセスの存続期間中） |
+| `domCache` | URL  | `CheerioAPI`     | 単一ビルド実行（プロセスの存続期間中） |
+
+- 同じ URL は単一ビルド内で二度フェッチされない
+- 失敗したフェッチは空文字列としてキャッシュされ、リトライを防止
+- **ビルド間の永続化はなし** -- `yarn up:gen` を実行するたびに全 URL を新たにフェッチ
+
+### 失敗時のキャッシュ動作
+
+`globalThis.fetch()` が例外をスローした場合:
+
+1. その URL に対して空文字列がキャッシュされる
+2. ビルドは継続（中断しない）
+3. ページのフェッチに失敗した要素は空/欠落したメタデータを持つ
+
+---
+
+## エラー処理
+
+| シナリオ               | 動作                                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------ |
+| HTTP フェッチ失敗      | 空文字列をキャッシュ、ビルド継続、メタデータは空                                     |
+| DOM 要素が見つからない | Cheerio は空の選択を返し、フィールドはデフォルトで空になる                           |
+| MDN ページ構造変更     | CSS セレクタがサイレントに失敗、影響を受けた要素のデータが失われる                   |
+| W3C 仕様 URL 変更      | フェッチがエラーページの HTML を返し、スクレイピングがゴミを抽出するか何も取得しない |
+
+ジェネレータはスクレイピングしたデータを期待される構造に対してバリデーションしません。不正確または欠落したデータはサイレントに `index.json` に伝播します。
+
+---
+
+## 既知の脆弱ポイント
+
+以下の CSS セレクタは上流のページ構造変更に敏感です:
+
+### MDN ページ
+
+| セレクタ                                                        | 用途                | リスクレベル |
+| --------------------------------------------------------------- | ------------------- | ------------ |
+| `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"]`                | 属性セクション      | 中           |
+| `.icon-beaker`, `.icon.experimental`, `.icon.icon-experimental` | experimental フラグ | 高           |
+| `.icon-trash`, `.icon.obsolete`, `.icon.icon-obsolete`          | obsolete フラグ     | 高           |
+
+### W3C ARIA 仕様ページ
+
+| セレクタ                         | 用途                 | リスクレベル |
+| -------------------------------- | -------------------- | ------------ |
+| `#role_definitions section.role` | ロールセクション     | 低           |
+| `.role-name[title]`              | ロール名             | 低           |
+| `.role-required-properties li`   | 必須プロパティ       | 低           |
+| `.role-properties li`            | 所有プロパティ       | 低           |
+| `#global_states li a`            | グローバルプロパティ | 低           |
+
+W3C 仕様はより構造化されたクラス名を使用しており、MDN セレクタよりも変更される可能性は低いです。
+
+---
+
+## スクレイピング失敗の診断
+
+`yarn up:gen` 実行後、`index.json` の差分を確認:
+
+```bash
+git diff packages/@markuplint/html-spec/index.json
+```
+
+**スクレイピング失敗の兆候:**
+
+- **大量のデータ消失** -- `index.json` から仕様データの大きな部分が消失。これはほぼ確実にスクレイピングの失敗を示しており、実際の仕様変更ではない
+- **空の説明** -- 複数の要素で突然 `description` フィールドが空になる
+- **属性の欠落** -- 以前存在していた属性が消失
+- **空の ARIA データ** -- ロールやプロパティの定義が空、または大幅に減少
+
+**根本原因:** 参照サイト（MDN、W3C）の HTML 構造、情報の記述方法、要素の ID/クラスが変更された。
+
+**対処法:** 実際のページ構造を調べてどのモジュールの CSS セレクタが壊れているかを特定し、`scraping.ts` または `aria.ts` のセレクタを新しい構造に合わせて更新する。`yarn up:gen` を再実行して確認。