@markuplint/spec-generator 4.8.1 → 5.0.0-alpha.0

package/ARCHITECTURE.ja.md

@@ -0,0 +1,178 @@
+# @markuplint/spec-generator
+
+## 概要
+
+`@markuplint/spec-generator` は、markuplint の拡張仕様 JSON を生成するビルドツールです。W3C および MDN のウェブ標準ドキュメントをスクレイピングし、HTML/SVG 要素仕様、グローバル属性、ARIA ロール・プロパティ、コンテンツモデル定義を集約して、`@markuplint/html-spec` が消費する単一の `index.json` ファイルに出力します。
+
+このパッケージは直接利用するために公開されるものではありません。`@markuplint/html-spec/build.mjs` からのみ呼び出されます。
+
+## ディレクトリ構成
+
+```
+src/
+├── index.ts          — main() オーケストレータおよび公開 API
+├── html-elements.ts  — 要素仕様のアセンブリ、非推奨要素リスト
+├── scraping.ts       — MDN 要素ページのスクレイピング（説明、カテゴリ、属性）
+├── aria.ts           — W3C ARIA 仕様のスクレイピング（ロール、プロパティ、ステート）
+├── global-attrs.ts   — グローバル属性定義の読み込み
+├── svg.ts            — MDN から SVG 非推奨要素名を取得
+├── fetch.ts          — HTTP フェッチ（プロセス内キャッシュ＋プログレスバー付き）
+├── read-json.ts      — コメント除去付き JSON ファイル読み込み＋ glob 対応
+└── utils.ts          — 共有ヘルパー関数（ソート、重複排除、名前解析）
+
+lib/                  — コンパイル出力（`yarn build` で生成）
+```
+
+## アーキテクチャ図
+
+```mermaid
+flowchart TD
+    subgraph entry ["エントリーポイント"]
+        main["main(options)"]
+    end
+
+    subgraph parallel ["並列データ収集"]
+        getElements["getElements()\n(html-elements.ts)"]
+        getGlobalAttrs["getGlobalAttrs()\n(global-attrs.ts)"]
+        getAria["getAria()\n(aria.ts)"]
+    end
+
+    subgraph scraping ["ウェブスクレイピング"]
+        mdnHTML["MDN HTML 要素ページ\n(scraping.ts)"]
+        mdnSVG["MDN SVG 要素インデックス\n(svg.ts)"]
+        ariaSpecs["W3C ARIA 1.1 / 1.2 / 1.3\n(aria.ts)"]
+        graphicsAria["Graphics ARIA\n(aria.ts)"]
+        htmlAria["HTML-ARIA マッピング\n(aria.ts)"]
+    end
+
+    subgraph local ["ローカルデータ"]
+        specFiles["spec.*.jsonc ファイル\n(read-json.ts)"]
+        commonAttrs["spec-common.attributes.jsonc\n(read-json.ts)"]
+        commonContents["spec-common.contents.jsonc\n(read-json.ts)"]
+    end
+
+    subgraph output ["出力"]
+        extendedSpec["ExtendedSpec JSON\n{ cites, def, specs }"]
+    end
+
+    main --> |"Promise.all"| getElements
+    main --> |"Promise.all"| getGlobalAttrs
+    main --> |"Promise.all"| getAria
+
+    getElements --> specFiles
+    getElements --> mdnHTML
+    getElements --> mdnSVG
+    getGlobalAttrs --> commonAttrs
+    getAria --> ariaSpecs
+    getAria --> graphicsAria
+    getAria --> htmlAria
+
+    getElements --> extendedSpec
+    getGlobalAttrs --> extendedSpec
+    getAria --> extendedSpec
+    main --> commonContents
+    main --> extendedSpec
+```
+
+## モジュール一覧
+
+| モジュール         | 主要エクスポート                                                                                                      | 役割                                                                 |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `index.ts`         | `main()`, `Options`                                                                                                   | 全データ収集のオーケストレーション、出力の組み立て、ファイル書き込み |
+| `html-elements.ts` | `getElements()`                                                                                                       | 要素仕様ファイルの読み込み、MDN データでの補完、非推奨要素の追加     |
+| `scraping.ts`      | `fetchHTMLElement()`, `fetchObsoleteElements()`                                                                       | MDN 要素ページからメタデータと属性をスクレイピング                   |
+| `aria.ts`          | `getAria()`                                                                                                           | W3C ARIA 仕様からロール、プロパティ、ステートをスクレイピング        |
+| `global-attrs.ts`  | `getGlobalAttrs()`                                                                                                    | JSON からグローバル属性定義を読み込み                                |
+| `svg.ts`           | `getSVGElementList()`                                                                                                 | MDN から非推奨 SVG 要素名を取得                                      |
+| `fetch.ts`         | `fetch()`, `fetchText()`, `getReferences()`                                                                           | 2層キャッシュとプログレスバー付き HTTP フェッチ                      |
+| `read-json.ts`     | `readJson()`, `readJsons()`                                                                                           | コメント除去と glob マッチング付き JSON 読み込み                     |
+| `utils.ts`         | `nameCompare()`, `sortObjectByKey()`, `arrayUnique()`, `getName()`, `getThisOutline()`, `mergeAttributes()`, `keys()` | 共有ユーティリティ                                                   |
+
+## 公開 API
+
+パッケージは単一のエントリーポイントをエクスポートします:
+
+```typescript
+export type Options = {
+  readonly outputFilePath: string; // 生成 JSON の出力先パス
+  readonly htmlFilePattern: string; // 要素仕様ファイルの glob パターン
+  readonly commonAttrsFilePath: string; // グローバル属性 JSON のパス
+  readonly commonContentsFilePath: string; // コンテンツモデル JSON のパス
+};
+
+export async function main(options: Options): Promise<void>;
+```
+
+## データフロー
+
+1. **並列データ収集** -- `main()` は `Promise.all` で3つのタスクを同時実行:
+   - `getElements(htmlFilePattern)` -- ローカル仕様ファイルを読み込み、各要素について MDN をスクレイピングし、非推奨要素を追加
+   - `getGlobalAttrs(commonAttrsFilePath)` -- グローバル属性定義を読み込み
+   - `getAria()` -- W3C ARIA 仕様（1.1, 1.2, 1.3）および Graphics ARIA、HTML-ARIA をスクレイピング
+
+2. **組み立て** -- 結果を `ExtendedSpec` オブジェクトに統合:
+   - `cites` -- フェッチした全 URL のソート済みリスト（`getReferences()` から）
+   - `def["#globalAttrs"]` -- グローバル属性カテゴリ
+   - `def["#aria"]` -- バージョンごとの ARIA ロール、プロパティ、グラフィックスロール
+   - `def["#contentModels"]` -- コンテンツモデルカテゴリ（`readJson()` から）
+   - `specs` -- 要素仕様の配列
+
+3. **出力** -- 組み立てた JSON を `outputFilePath` に書き込み
+
+## 外部依存
+
+| パッケージ        | 用途                                                      |
+| ----------------- | --------------------------------------------------------- |
+| `cheerio`         | スクレイピングしたウェブページの HTML 解析と DOM クエリ   |
+| `cli-progress`    | フェッチ操作のターミナルプログレスバー                    |
+| `ajv`             | JSON スキーマバリデーション（利用可能だが実行時は未使用） |
+| `fast-xml-parser` | XML パース（利用可能だが現在のモジュールでは未使用）      |
+| `glob`            | `readJsons()` 用のファイル glob パターンマッチング        |
+| `jsonc-parser`    | JSONC ファイル（コメント付き JSON）のパース               |
+
+**開発依存:**
+
+| パッケージ            | 用途                                                                     |
+| --------------------- | ------------------------------------------------------------------------ |
+| `@markuplint/ml-spec` | 型定義（`ExtendedSpec`, `ExtendedElementSpec`, `ARIARoleInSchema` など） |
+| `type-fest`           | `WritableDeep` ユーティリティ型                                          |
+
+## 統合ポイント
+
+```mermaid
+flowchart LR
+    subgraph upstream ["型プロバイダ"]
+        mlSpec["@markuplint/ml-spec\n(型: ExtendedSpec,\nExtendedElementSpec など)"]
+    end
+
+    subgraph pkg ["@markuplint/spec-generator"]
+        main["main()"]
+    end
+
+    subgraph consumer ["消費者"]
+        htmlSpec["@markuplint/html-spec\n(build.mjs が main() を呼び出し)"]
+    end
+
+    subgraph external ["外部ソース"]
+        mdn["MDN Web Docs"]
+        w3c["W3C ARIA / HTML-ARIA"]
+    end
+
+    mlSpec -->|"型"| pkg
+    external -->|"HTTP スクレイピング"| pkg
+    pkg -->|"index.json を生成"| consumer
+```
+
+### 上流
+
+- **`@markuplint/ml-spec`** はこのパッケージで使用される全 TypeScript 型を提供: `ExtendedSpec`, `ExtendedElementSpec`, `ARIARoleInSchema`, `ARIAProperty`, `Category`, `Attribute` など
+
+### 下流
+
+- **`@markuplint/html-spec`** が唯一の消費者。`build.mjs` がこのパッケージから `main()` をインポートし、仕様ソースと出力先のファイルパスを渡す
+
+## ドキュメントマップ
+
+- [モジュールリファレンス](docs/modules.ja.md) -- 各ソースモジュールの詳細ドキュメント
+- [スクレイピング詳細](docs/scraping.ja.md) -- スクレイピング対象、セレクタ、エラー処理
+- [メンテナンスガイド](docs/maintenance.ja.md) -- トラブルシューティング、レシピ、デバッグ

package/ARCHITECTURE.md

@@ -0,0 +1,180 @@
+# @markuplint/spec-generator
+
+## Overview
+
+`@markuplint/spec-generator` is a build tool that generates the markuplint extended specification JSON. It scrapes W3C and MDN web standards documentation, aggregates HTML/SVG element specs, global attributes, ARIA roles and properties, and content model definitions into a single `index.json` file consumed by `@markuplint/html-spec`.
+
+This package is not published for direct use. It is invoked exclusively from `@markuplint/html-spec/build.mjs`.
+
+## Directory Structure
+
+```
+src/
+├── index.ts          — main() orchestrator and public API
+├── html-elements.ts  — Element specification assembly, obsolete element list
+├── scraping.ts       — MDN element page scraping (descriptions, categories, attributes)
+├── aria.ts           — W3C ARIA specification scraping (roles, properties, states)
+├── global-attrs.ts   — Global attribute definition loader
+├── svg.ts            — SVG deprecated element list fetcher
+├── fetch.ts          — HTTP fetch with in-process caching and progress bar
+├── read-json.ts      — JSON file reader with comment stripping and glob support
+└── utils.ts          — Shared helper functions (sorting, deduplication, name parsing)
+
+lib/                  — Compiled output (generated by `yarn build`)
+```
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph entry ["Entry Point"]
+        main["main(options)"]
+    end
+
+    subgraph parallel ["Parallel Data Gathering"]
+        getElements["getElements()\n(html-elements.ts)"]
+        getGlobalAttrs["getGlobalAttrs()\n(global-attrs.ts)"]
+        getAria["getAria()\n(aria.ts)"]
+    end
+
+    subgraph scraping ["Web Scraping"]
+        mdnHTML["MDN HTML Element Pages\n(scraping.ts)"]
+        mdnSVG["MDN SVG Element Index\n(svg.ts)"]
+        ariaSpecs["W3C ARIA 1.1 / 1.2 / 1.3\n(aria.ts)"]
+        graphicsAria["Graphics ARIA\n(aria.ts)"]
+        dpubAria["DPub ARIA\n(aria.ts)"]
+        htmlAria["HTML-ARIA Mapping\n(aria.ts)"]
+    end
+
+    subgraph local ["Local Data"]
+        specFiles["spec.*.jsonc files\n(read-json.ts)"]
+        commonAttrs["spec-common.attributes.jsonc\n(read-json.ts)"]
+        commonContents["spec-common.contents.jsonc\n(read-json.ts)"]
+    end
+
+    subgraph output ["Output"]
+        extendedSpec["ExtendedSpec JSON\n{ cites, def, specs }"]
+    end
+
+    main --> |"Promise.all"| getElements
+    main --> |"Promise.all"| getGlobalAttrs
+    main --> |"Promise.all"| getAria
+
+    getElements --> specFiles
+    getElements --> mdnHTML
+    getElements --> mdnSVG
+    getGlobalAttrs --> commonAttrs
+    getAria --> ariaSpecs
+    getAria --> graphicsAria
+    getAria --> dpubAria
+    getAria --> htmlAria
+
+    getElements --> extendedSpec
+    getGlobalAttrs --> extendedSpec
+    getAria --> extendedSpec
+    main --> commonContents
+    main --> extendedSpec
+```
+
+## Module Overview
+
+| Module             | Primary Export(s)                                                                                                     | Role                                                             |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `index.ts`         | `main()`, `Options`                                                                                                   | Orchestrates all data gathering, assembles output, writes file   |
+| `html-elements.ts` | `getElements()`                                                                                                       | Reads element spec files, enriches with MDN data, adds obsoletes |
+| `scraping.ts`      | `fetchHTMLElement()`, `fetchObsoleteElements()`                                                                       | Scrapes MDN element pages for metadata and attributes            |
+| `aria.ts`          | `getAria()`                                                                                                           | Scrapes W3C ARIA specs for roles, properties, states             |
+| `global-attrs.ts`  | `getGlobalAttrs()`                                                                                                    | Reads global attribute definitions from JSON                     |
+| `svg.ts`           | `getSVGElementList()`                                                                                                 | Fetches deprecated SVG element names from MDN                    |
+| `fetch.ts`         | `fetch()`, `fetchText()`, `getReferences()`                                                                           | HTTP fetching with dual-layer cache and progress bar             |
+| `read-json.ts`     | `readJson()`, `readJsons()`                                                                                           | JSON reading with comment stripping and glob matching            |
+| `utils.ts`         | `nameCompare()`, `sortObjectByKey()`, `arrayUnique()`, `getName()`, `getThisOutline()`, `mergeAttributes()`, `keys()` | Shared utilities                                                 |
+
+## Public API
+
+The package exports a single entry point:
+
+```typescript
+export type Options = {
+  readonly outputFilePath: string; // Where to write the generated JSON
+  readonly htmlFilePattern: string; // Glob pattern for element spec files
+  readonly commonAttrsFilePath: string; // Path to global attributes JSON
+  readonly commonContentsFilePath: string; // Path to content models JSON
+};
+
+export async function main(options: Options): Promise<void>;
+```
+
+## Data Flow
+
+1. **Parallel data gathering** -- `main()` launches three tasks concurrently via `Promise.all`:
+   - `getElements(htmlFilePattern)` -- reads local spec files, scrapes MDN for each element, appends obsolete elements
+   - `getGlobalAttrs(commonAttrsFilePath)` -- reads global attribute definitions
+   - `getAria()` -- scrapes W3C ARIA specs (1.1, 1.2, 1.3) plus Graphics ARIA, DPub ARIA, and HTML-ARIA
+
+2. **Assembly** -- The results are combined into an `ExtendedSpec` object:
+   - `cites` -- sorted list of all fetched URLs (from `getReferences()`)
+   - `def["#globalAttrs"]` -- global attribute categories
+   - `def["#aria"]` -- ARIA roles, properties, graphics roles, and DPub roles per version
+   - `def["#contentModels"]` -- content model categories (from `readJson()`)
+   - `specs` -- element specification array
+
+3. **Output** -- The assembled JSON is written to `outputFilePath`
+
+## External Dependencies
+
+| Package           | Purpose                                                  |
+| ----------------- | -------------------------------------------------------- |
+| `cheerio`         | HTML parsing and DOM querying of scraped web pages       |
+| `cli-progress`    | Terminal progress bar for fetch operations               |
+| `ajv`             | JSON Schema validation (available but unused in runtime) |
+| `fast-xml-parser` | XML parsing (available but unused in current modules)    |
+| `glob`            | File glob pattern matching for `readJsons()`             |
+| `jsonc-parser`    | Parse JSONC files (JSON with comments) for spec data     |
+
+**Dev dependencies:**
+
+| Package               | Purpose                                                                            |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| `@markuplint/ml-spec` | Type definitions (`ExtendedSpec`, `ExtendedElementSpec`, `ARIARoleInSchema`, etc.) |
+| `type-fest`           | `WritableDeep` utility type                                                        |
+
+## Integration Points
+
+```mermaid
+flowchart LR
+    subgraph upstream ["Type Provider"]
+        mlSpec["@markuplint/ml-spec\n(types: ExtendedSpec,\nExtendedElementSpec, etc.)"]
+    end
+
+    subgraph pkg ["@markuplint/spec-generator"]
+        main["main()"]
+    end
+
+    subgraph consumer ["Consumer"]
+        htmlSpec["@markuplint/html-spec\n(build.mjs calls main())"]
+    end
+
+    subgraph external ["External Sources"]
+        mdn["MDN Web Docs"]
+        w3c["W3C ARIA / DPub ARIA / HTML-ARIA"]
+    end
+
+    mlSpec -->|"types"| pkg
+    external -->|"HTTP scraping"| pkg
+    pkg -->|"generates index.json"| consumer
+```
+
+### Upstream
+
+- **`@markuplint/ml-spec`** provides all TypeScript types used in this package: `ExtendedSpec`, `ExtendedElementSpec`, `ARIARoleInSchema`, `ARIAProperty`, `Category`, `Attribute`, etc.
+
+### Downstream
+
+- **`@markuplint/html-spec`** is the sole consumer. Its `build.mjs` imports `main()` from this package and passes file paths for the spec sources and output destination.
+
+## Documentation Map
+
+- [Module Reference](docs/modules.md) -- Detailed documentation for each source module
+- [Scraping Details](docs/scraping.md) -- Web scraping targets, selectors, and error handling
+- [Maintenance Guide](docs/maintenance.md) -- Troubleshooting, common recipes, and debugging

package/CHANGELOG.md

@@ -3,13 +3,27 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.8.1](https://github.com/markuplint/markuplint/compare/@markuplint/spec-generator@4.8.0...@markuplint/spec-generator@4.8.1) (2025-11-05)
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
 
-**Note:** Version bump only for package @markuplint/spec-generator
+### Bug Fixes
 
+- resolve additional eslint-plugin-unicorn v63 errors ([e58a72c](https://github.com/markuplint/markuplint/commit/e58a72c17c97bbec522f9513b99777fac6904d64))
+- **spec-generator:** add windowsPathsNoEscape option to glob call ([77189eb](https://github.com/markuplint/markuplint/commit/77189ebaa7511c32e50246a4b70dbe495117b784))
+- **spec-generator:** disable progress bar in CI and run up:gen twice daily ([526044d](https://github.com/markuplint/markuplint/commit/526044d26ed207e0c2a04c266c9491a14c56b3e1))
 
+### Features
+
+- **spec-generator:** scrape DPub ARIA roles from W3C spec ([681abed](https://github.com/markuplint/markuplint/commit/681abed45c1e61facba040fc3535e3e46ea410be))
 
+## [4.8.2](https://github.com/markuplint/markuplint/compare/@markuplint/spec-generator@4.8.1...@markuplint/spec-generator@4.8.2) (2026-02-10)
 
+### Bug Fixes
+
+- **spec-generator:** merge MDN data into spec-defined attributes ([ae4db37](https://github.com/markuplint/markuplint/commit/ae4db37b109bac3daed22d8ba0a147acf2d71787))
+
+## [4.8.1](https://github.com/markuplint/markuplint/compare/@markuplint/spec-generator@4.8.0...@markuplint/spec-generator@4.8.1) (2025-11-05)
+
+**Note:** Version bump only for package @markuplint/spec-generator
 
 # [4.8.0](https://github.com/markuplint/markuplint/compare/@markuplint/spec-generator@4.7.0...@markuplint/spec-generator@4.8.0) (2025-08-24)
 

package/README.md

@@ -3,7 +3,7 @@
 Private builder used to generate `@markuplint/html-spec`.
 
 It assembles an Extended Spec JSON from the HTML element source files and external references
-(MDN, WAI‑ARIA, HTML‑ARIA), then writes `index.json` in `@markuplint/html-spec`.
+(MDN, WAI-ARIA, HTML-ARIA), then writes `index.json` in `@markuplint/html-spec`.
 
 ## How it is invoked
 
@@ -12,9 +12,9 @@ Called from `packages/@markuplint/html-spec/build.mjs`:
 ```ts
 await main({
   outputFilePath: 'index.json',
-  htmlFilePattern: 'src/spec.*.json',
-  commonAttrsFilePath: 'src/spec-common.attributes.json',
-  commonContentsFilePath: 'src/spec-common.contents.json',
+  htmlFilePattern: 'src/spec.*.jsonc',
+  commonAttrsFilePath: 'src/spec-common.attributes.jsonc',
+  commonContentsFilePath: 'src/spec-common.contents.jsonc',
 });
 ```
 
@@ -25,58 +25,46 @@ You normally don't run this directly; use:
 
 ## What it does
 
-1. Read element sources
+1. **Read element sources** -- Load every `src/spec.*.jsonc` and infer the element name from the filename
+2. **Enrich from MDN** -- Fetch MDN element pages for descriptions, categories, and attribute metadata (manual specs take precedence)
+3. **Add obsolete elements** -- Inject HTML obsolete elements and deprecated SVG elements
+4. **Load shared data** -- Read global attributes and content model definitions
+5. **Build ARIA definitions** -- Scrape WAI-ARIA (1.1/1.2/1.3), Graphics-ARIA, DPub-ARIA, and HTML-ARIA
+6. **Emit Extended Spec JSON** -- Write `{ cites, def, specs }` to `index.json`
 
-- Load every `src/spec.*.json` and infer the element name from the filename (e.g. `spec.a.json` → `a`).
+For detailed architecture and data flow, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
-2. Enrich from MDN
+## Precedence rules
 
-- Fetch the MDN element page and populate missing metadata:
-  - `cite`, `description`, `categories`, `omission`, attribute flags
-  - Existing fields in `src/spec.*.json` take precedence over scraped values
-  - Attributes are merged name-by-name; manual entries win
-
-3. Add obsolete elements
-
-- Inject HTML obsolete elements (WHATWG list) and some deprecated SVG elements if not present.
-
-4. Load shared data
-
-- `def['#globalAttrs']` from `src/spec-common.attributes.json`
-- `def['#contentModels']` from `src/spec-common.contents.json` (`models` key)
-
-5. Build ARIA definitions
-
-- Scrape WAI‑ARIA (1.1/1.2/1.3) and Graphics‑ARIA, plus HTML‑ARIA cross‑refs, to produce
-  `def['#aria']` (roles, properties, synonyms, defaults, and equivalent HTML attrs).
-
-6. Emit Extended Spec JSON
-
-- `{ cites, def: { #globalAttrs, #aria, #contentModels }, specs: [...] }` → `index.json`
-  (Pretty‑printed by the caller)
-
-## Source of truth vs. generated data
-
-- Source of truth for element specs is in `@markuplint/html-spec/src/`.
-- This generator is purely a build step; do not edit the output `index.json` by hand.
-
-## Precedence rules (important)
-
-- Manual data in `src/spec.*.json` overrides MDN‑scraped values on conflict.
+- Manual data in `src/spec.*.jsonc` overrides MDN-scraped values on conflict.
 - Attribute objects are merged per name; manual keys win, MDN may fill missing flags.
-- Shared files under `src/spec-common.*.json` are imported as‑is.
+- Shared files under `src/spec-common.*.jsonc` are imported as-is.
 
 ## Network and caching
 
-- Uses live HTTP fetch against MDN/W3C specs. There is an in‑process cache for the current run only.
-- If a fetch fails, the entry may be left empty; re‑run later or edit your manual source to cover it.
+- Uses live HTTP fetch against MDN/W3C specs. There is an in-process cache for the current run only.
+- If a fetch fails, the entry may be left empty; re-run later or edit your manual source to cover it.
 
 ## When to change this package
 
 - Only when the scraping targets change (DOM structure/URLs), or when the Extended Spec shape evolves
   in `@markuplint/ml-spec`.
 
+## Documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) -- Package overview, module structure, data flow
+- [docs/modules.md](docs/modules.md) -- Detailed reference for each source module
+- [docs/scraping.md](docs/scraping.md) -- Web scraping targets, CSS selectors, and error handling
+- [docs/maintenance.md](docs/maintenance.md) -- Troubleshooting, common recipes, and debugging
+
+Japanese versions are also available:
+
+- [ARCHITECTURE.ja.md](ARCHITECTURE.ja.md)
+- [docs/modules.ja.md](docs/modules.ja.md)
+- [docs/scraping.ja.md](docs/scraping.ja.md)
+- [docs/maintenance.ja.md](docs/maintenance.ja.md)
+
 ## See also
 
-- `@markuplint/html-spec` README — how to edit the element sources.
-- `@markuplint/ml-spec` README — schema shapes, generation, and spec merging.
+- `@markuplint/html-spec` README -- how to edit the element sources.
+- `@markuplint/ml-spec` README -- schema shapes, generation, and spec merging.

package/SKILL.md

@@ -0,0 +1,134 @@
+---
+description: Perform maintenance tasks for @markuplint/spec-generator
+---
+
+# spec-generator-maintenance
+
+Perform maintenance tasks for `@markuplint/spec-generator`: fix scraping breakages,
+add ARIA versions, update the obsolete element list, and debug scraping issues.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                     | Description                                           |
+| ------------------------ | ----------------------------------------------------- |
+| `fix-scraping <source>`  | Fix scraping breakage caused by upstream page changes |
+| `add-aria-version <ver>` | Add support for a new ARIA specification version      |
+| `add-obsolete <element>` | Add an element to the obsolete list                   |
+| `debug-element <name>`   | Debug scraping results for a specific element         |
+| `update-deps`            | Update dependencies and verify compatibility          |
+
+If omitted, defaults to `fix-scraping`.
+
+## Reference
+
+Before executing any task, read `docs/maintenance.md` (or `docs/maintenance.ja.md`)
+for the full guide. The recipes there are the source of truth for procedures.
+
+Also read:
+
+- `docs/scraping.md` -- Scraping targets, CSS selectors, and fragile points
+- `docs/modules.md` -- Module reference for all source files
+- `ARCHITECTURE.md` -- Package overview and data flow
+
+## Task: fix-scraping
+
+Fix CSS selectors that have broken due to upstream page structure changes.
+
+### Step 1: Identify the scope
+
+The `<source>` argument specifies which scraping target is affected:
+
+| Source      | Module        | Upstream Site                        |
+| ----------- | ------------- | ------------------------------------ |
+| `mdn`       | `scraping.ts` | MDN Web Docs element reference pages |
+| `aria`      | `aria.ts`     | W3C ARIA specification pages         |
+| `svg`       | `svg.ts`      | MDN SVG element index page           |
+| `html-aria` | `aria.ts`     | W3C HTML-ARIA mapping page           |
+
+### Step 2: Diagnose
+
+1. Run `yarn up:gen` and check the `index.json` diff:
+   ```bash
+   git diff packages/@markuplint/html-spec/index.json
+   ```
+2. Identify which data is missing or incorrect
+3. Open the affected upstream page in a browser
+4. Compare the actual HTML structure with the CSS selectors in the module
+5. Refer to `docs/scraping.md` for the complete selector reference
+
+### Step 3: Fix
+
+1. Update the CSS selectors in the identified module to match the new page structure
+2. Build: `yarn build --scope @markuplint/spec-generator`
+3. Regenerate: `yarn up:gen`
+4. Verify the `index.json` diff shows correct data restoration
+
+### Step 4: Test and commit
+
+1. Run `yarn workspace @markuplint/html-spec run test`
+2. Stage and commit both the selector fix and the regenerated `index.json`
+
+## Task: add-aria-version
+
+Add support for a new ARIA specification version. Follow recipe #2 in `docs/maintenance.md`.
+
+1. Read `src/aria.ts` to understand the current version handling
+2. Add the new version URL in `getARIASpecURLByVersion()`
+3. Add the new version data fetching in `getAria()`
+4. **Cross-package:** Update `ARIAVersion` type in `@markuplint/ml-spec`
+5. Build: `yarn build --scope @markuplint/spec-generator`
+6. Regenerate: `yarn up:gen`
+7. Verify the new version's data appears in `index.json`
+8. Run tests: `yarn workspace @markuplint/html-spec run test`
+
+## Task: add-obsolete
+
+Add an element to the hardcoded obsolete list. Follow recipe #3 in `docs/maintenance.md`.
+
+1. Read `src/html-elements.ts`
+2. Add the element name to the `obsoleteList` array
+3. Build: `yarn build --scope @markuplint/spec-generator`
+4. Regenerate: `yarn up:gen`
+5. Verify the element appears in `index.json` with `"obsolete": true`
+6. Run tests: `yarn workspace @markuplint/html-spec run test`
+
+## Task: debug-element
+
+Debug the scraping results for a specific element to understand what data is being extracted.
+
+1. Read `src/scraping.ts` and `src/html-elements.ts`
+2. Construct the MDN URL for the element:
+   - 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>`
+   - Heading elements (`h1`-`h6`): use `Heading_Elements` as the name
+3. Use WebFetch to inspect the MDN page structure
+4. Compare the page structure with the CSS selectors in `scraping.ts`
+5. Report findings: which selectors match, which data is extracted, and any discrepancies
+
+## Task: update-deps
+
+Update package dependencies and verify compatibility.
+
+1. Read `package.json` for current dependency versions
+2. Check for available updates
+3. For `cheerio` updates:
+   - Review the changelog for breaking API changes
+   - Refer to recipe #5 in `docs/maintenance.md` for the API surface used
+4. For `@markuplint/ml-spec` updates:
+   - Check for type changes that affect this package
+   - Refer to recipe #4 in `docs/maintenance.md`
+5. Update dependencies
+6. Build: `yarn build --scope @markuplint/spec-generator`
+7. Regenerate: `yarn up:gen`
+8. Run tests: `yarn workspace @markuplint/html-spec run test`
+9. Review `index.json` diff for unexpected changes
+
+## Rules
+
+1. **Always build after source changes.** Run `yarn build --scope @markuplint/spec-generator` before `yarn up:gen`.
+2. **Always check the index.json diff.** The diff is the primary way to verify scraping correctness.
+3. **Use the actual page structure as the source of truth.** When selectors break, inspect the live page -- do not guess.
+4. **Cross-package changes may be required.** ARIA version additions and type changes often affect `@markuplint/ml-spec`.
+5. **Failed fetches are cached as empty strings.** If a URL fails during `yarn up:gen`, the data will be empty. Re-running will re-fetch.