@markuplint/ml-spec 4.10.1 → 5.0.0-alpha.0

package/docs/maintenance.ja.md

@@ -0,0 +1,331 @@
+# メンテナンスガイド
+
+## 概要
+
+このガイドでは、`@markuplint/ml-spec` の日常的な運用・メンテナンスタスクについて説明します。スキーマ生成、依存関係管理、テスト、よく使うレシピ、トラブルシューティングを対象とします。
+
+## ビルド・開発コマンド
+
+| コマンド                                        | スコープ   | 説明                                   |
+| ----------------------------------------------- | ---------- | -------------------------------------- |
+| `yarn build --scope @markuplint/ml-spec`        | パッケージ | TypeScript を `lib/` にコンパイル      |
+| `yarn workspace @markuplint/ml-spec run dev`    | パッケージ | ウォッチモードコンパイル               |
+| `yarn workspace @markuplint/ml-spec run clean`  | パッケージ | `lib/` 出力を削除                      |
+| `yarn workspace @markuplint/ml-spec run schema` | パッケージ | スキーマと型を再生成                   |
+| `yarn up:schema`                                | モノレポ   | 全パッケージのスキーマを再生成（推奨） |
+| `yarn test`                                     | モノレポ   | vitest で全テストを実行                |
+
+## スキーマ生成パイプライン
+
+### スキーマ生成が存在する理由
+
+本パッケージは JSON Schema ファイルを複雑な型構造（ARIA 定義、属性型、コンテンツモデル、グローバル属性）の唯一の情報源として使用しています。TypeScript 型はこれらのスキーマから `json-schema-to-typescript`（`json2ts`）によって自動生成されます。これにより:
+
+- ランタイムで消費される JSON データファイルが、TypeScript 型と同じ構造に対して検証される。
+- スキーマの変更が自動的に型定義に伝播する。
+- `@markuplint/html-spec` の JSON データが型システムと一貫性を保つ。
+
+### 生成フロー
+
+```
+gen/global-attribute.data.ts   schemas/aria.schema.json
+         │                     schemas/content-models.schema.json
+         ▼                              │
+    gen/gen.ts                          │
+         │                              │
+         ▼                              ▼
+schemas/global-attributes.schema.json   │
+schemas/attributes.schema.json          │
+         │                              │
+         └──────────┬───────────────────┘
+                    ▼
+          json-schema-to-typescript
+                    │
+         ┌──────────┼──────────────┐
+         ▼          ▼              ▼
+  types/aria.ts  types/        types/permitted-
+              attributes.ts    structures.ts
+                    │
+                    ▼
+          prettier + eslint
+```
+
+### スクリプトの内訳 (`yarn workspace @markuplint/ml-spec run schema`)
+
+`schema` スクリプトは `run-s` による逐次パイプラインです:
+
+```
+schema:json → schema:content-models → schema:attributes → schema:aria → schema:prettier → schema:eslint → schema:prettier
+```
+
+| ステップ                | コマンド                                                   | 入力                                 | 出力                                                                      |
+| ----------------------- | ---------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------- |
+| `schema:json`           | `tsx ./gen/gen.ts`                                         | `gen/global-attribute.data.ts`       | `schemas/global-attributes.schema.json`, `schemas/attributes.schema.json` |
+| `schema:content-models` | `json2ts ./schemas/content-models.schema.json`             | `schemas/content-models.schema.json` | `src/types/permitted-structures.ts`                                       |
+| `schema:attributes`     | `json2ts ./schemas/attributes.schema.json --cwd ./schemas` | `schemas/attributes.schema.json`     | `src/types/attributes.ts`                                                 |
+| `schema:aria`           | `json2ts ./schemas/aria.schema.json --cwd ./schemas`       | `schemas/aria.schema.json`           | `src/types/aria.ts`                                                       |
+| `schema:prettier`       | `prettier --write`                                         | `schemas/*.json`, `src/types/*.ts`   | フォーマット済みファイル                                                  |
+| `schema:eslint`         | `eslint --fix`                                             | `src/types/*.ts`                     | lint 修正済みファイル                                                     |
+
+注意: `schema:prettier` は **2回** 実行されます -- `schema:aria` の後に生成ファイルをフォーマットし、`schema:eslint` の後に eslint の自動修正によるフォーマット変更をクリーンアップします。
+
+### パッケージ間依存: `@markuplint/types`
+
+`schemas/attributes.schema.json` は `@markuplint/types` への `$ref` を含みます:
+
+```json
+{
+  "AttributeType": {
+    "$ref": "../../types/types.schema.json#/definitions/type"
+  }
+}
+```
+
+つまり、`@markuplint/types` が `@markuplint/ml-spec` **より先に**スキーマを再生成する必要があります。モノレポレベルの `yarn up:schema` はこの順序を自動的に処理します:
+
+1. `@markuplint/types` -- `types.schema.json` を生成し、パッケージをビルド
+2. `@markuplint/ml-spec` -- `types.schema.json` を参照するスキーマを生成
+3. `schema` スクリプトを持つその他のパッケージ
+
+**パッケージ間参照を含むスキーマ更新時は、常にリポジトリルートから `yarn up:schema` を使用してください。**
+
+## ファイル分類: 編集可能 vs 生成
+
+### 直接編集してはいけないファイル
+
+これらのファイルには「DO NOT MODIFY」ヘッダーがあり、生成パイプラインによって上書きされます:
+
+| ファイル                                | 生成元                                        |
+| --------------------------------------- | --------------------------------------------- |
+| `src/types/aria.ts`                     | `schemas/aria.schema.json`                    |
+| `src/types/attributes.ts`               | `schemas/attributes.schema.json`              |
+| `src/types/permitted-structures.ts`     | `schemas/content-models.schema.json`          |
+| `schemas/global-attributes.schema.json` | `gen/gen.ts` + `gen/global-attribute.data.ts` |
+| `schemas/attributes.schema.json`        | `gen/gen.ts` + `gen/global-attribute.data.ts` |
+
+### 生成出力を変更するために編集するファイル
+
+| 変更したいもの                           | 編集するファイル                         | 実行コマンド                                    |
+| ---------------------------------------- | ---------------------------------------- | ----------------------------------------------- |
+| グローバル属性カテゴリ/項目              | `gen/global-attribute.data.ts`           | `yarn workspace @markuplint/ml-spec run schema` |
+| `AttributeJSON` の形状（フィールド追加） | `gen/gen.ts`（`AttributeJSON` 定義部分） | `yarn workspace @markuplint/ml-spec run schema` |
+| ARIA ロール/プロパティ構造               | `schemas/aria.schema.json`               | `yarn workspace @markuplint/ml-spec run schema` |
+| コンテンツモデルパターン                 | `schemas/content-models.schema.json`     | `yarn workspace @markuplint/ml-spec run schema` |
+| 属性値型（CSS キーワード等）             | `@markuplint/types` パッケージ           | `yarn up:schema`（ルートから）                  |
+
+### 直接編集するファイル（手書き）
+
+| ファイル                      | 目的                                                       |
+| ----------------------------- | ---------------------------------------------------------- |
+| `src/types/index.ts`          | コア手書き型（`MLMLSpec`, `ElementSpec`, `ARIARole` など） |
+| `src/algorithm/aria/*.ts`     | ARIA アルゴリズム実装                                      |
+| `src/algorithm/html/*.ts`     | HTML アルゴリズム実装                                      |
+| `src/utils/*.ts`              | ユーティリティ関数                                         |
+| `src/index.ts`                | 公開 API エクスポート                                      |
+| `schemas/element.schema.json` | トップレベル要素スキーマ（手書き、11行）                   |
+
+## テスト
+
+### テストファイル
+
+パッケージには vitest を使用する 18 のテストファイルがあります:
+
+| ディレクトリ                  | テストファイル数 | カバレッジ                                                                                                                                                                                                                             |
+| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/algorithm/aria/`         | 11               | `accname-computation`, `get-computed-aria-props`, `get-computed-role`, `get-implicit-role-spec`, `get-implicit-role`, `get-permitted-roles-spec`, `get-role-spec`, `has-required-owned-elements`, `is-exposed`, `matches-context-role` |
+| `src/algorithm/aria/accname/` | 3                | `aria-steps`, `compute`, `element-names`, `label-steps`                                                                                                                                                                                |
+| `src/utils/`                  | 4                | `get-attr-specs-spec`, `get-spec-by-tag-name`, `resolve-namespace`, `resolve-version`, `schema-to-spec`                                                                                                                                |
+
+### テストの実行
+
+```bash
+# モノレポ全体のテスト
+yarn test
+
+# ml-spec のテストのみ
+yarn test packages/@markuplint/ml-spec
+
+# 特定のテストファイル
+yarn test packages/@markuplint/ml-spec/src/algorithm/aria/get-computed-role.spec.ts
+```
+
+テストは `@markuplint/test-tools`（devDependency）に依存しており、テスト環境で DOM 要素を生成するための HTML パースユーティリティを提供します。
+
+## 依存関係管理
+
+### ランタイム依存
+
+| パッケージ           | バージョン | 目的                               | 更新リスク         |
+| -------------------- | ---------- | ---------------------------------- | ------------------ |
+| `@markuplint/ml-ast` | 4.4.10     | `NamespaceURI` 型                  | 低（内部）         |
+| `@markuplint/types`  | 4.8.1      | 属性値型の `Type` ユニオン         | 中（スキーマ参照） |
+| `is-plain-object`    | 5.0.0      | AAM 情報のプレーンオブジェクト検出 | 低（安定 API）     |
+| `type-fest`          | 4.41.0     | `ReadonlyDeep` ユーティリティ型    | 低（型のみ）       |
+
+### 開発依存
+
+| パッケージ                  | バージョン | 目的                               |
+| --------------------------- | ---------- | ---------------------------------- |
+| `@markuplint/test-tools`    | 4.5.22     | DOM 要素生成のテストユーティリティ |
+| `json-schema-to-typescript` | 15.0.4     | スキーマ → TypeScript 型生成       |
+
+### 依存関係の更新
+
+- **`json-schema-to-typescript`**: メジャーバージョン更新により、生成される型の出力が変わる場合があります（フォーマット、optional の扱い）。更新後は `yarn workspace @markuplint/ml-spec run schema` を実行し、`src/types/*.ts` の差分を確認してください。
+- **`@markuplint/types`**: 更新後は必ず `yarn up:schema` を実行して、スキーマ参照の一貫性を確保してください。
+- **`type-fest`**: 型のみの依存です。自由に更新できますが、ビルドが成功することを確認してください（`yarn build --scope @markuplint/ml-spec`）。
+
+## よく使うメンテナンスレシピ
+
+### 1. 新しいグローバル属性を追加する
+
+`gen/global-attribute.data.ts` を編集し、適切なカテゴリ配列に属性名を追加します:
+
+```ts
+'#HTMLGlobalAttrs': {
+  attrs: [
+    // ...既存の属性...
+    'newattribute',  // ← ここに追加
+  ],
+},
+```
+
+再生成を実行:
+
+```bash
+yarn workspace @markuplint/ml-spec run schema
+```
+
+### 2. 新しいグローバル属性カテゴリを追加する
+
+`gen/global-attribute.data.ts` を編集し、新しいエントリを追加します:
+
+```ts
+'#NewCategoryAttrs': {
+  description: '仕様リンク付きの説明',
+  attrs: ['attr1', 'attr2'],
+},
+```
+
+キーは `#${string}Attrs` パターンに一致する必要があります。ジェネレータ（`gen/gen.ts`）は `global-attributes.schema.json` と `attributes.schema.json` の両方で新しいカテゴリを自動的に処理します。
+
+再生成を実行:
+
+```bash
+yarn workspace @markuplint/ml-spec run schema
+```
+
+### 3. `AttributeJSON` に新しいフィールドを追加する
+
+`gen/gen.ts` を編集し、`AttributeJSON` 定義オブジェクト内にプロパティを追加します:
+
+```ts
+AttributeJSON: {
+  properties: {
+    // ...既存のプロパティ...
+    newField: { type: 'boolean' },  // ← ここに追加
+  },
+},
+```
+
+再生成すると、新しいフィールドが `src/types/attributes.ts` にオプショナルプロパティとして反映されます。
+
+### 4. ARIA ロール/プロパティスキーマを変更する
+
+`schemas/aria.schema.json` を直接編集します。例えば、ロール定義に新しいフィールドを追加する場合:
+
+```json
+{
+  "definitions": {
+    "role": {
+      "properties": {
+        "newField": { "type": "boolean" }
+      }
+    }
+  }
+}
+```
+
+再生成すると、新しいフィールドが `src/types/aria.ts` に反映されます。
+
+### 5. 新しいコンテンツモデルカテゴリを追加する
+
+`schemas/content-models.schema.json` を編集し、`Category` enum にカテゴリを追加してパターンを定義します。
+
+### 6. 新しい ARIA アルゴリズム関数を追加する
+
+1. `src/algorithm/aria/` に実装ファイルを作成。
+2. 対応する `.spec.ts` テストファイルを作成。
+3. `src/index.ts` から関数をエクスポート。
+4. `docs/aria-algorithms.md` と `docs/aria-algorithms.ja.md` を更新。
+
+### 7. W3C 仕様準拠を更新する
+
+W3C 仕様が更新された場合（例: WAI-ARIA 1.3 が勧告になった場合）:
+
+1. 要素レベルの ARIA マッピングが変更された場合、`@markuplint/html-spec` データを更新。
+2. アルゴリズムの動作が変更された場合、`src/algorithm/aria/*.ts` のアルゴリズム実装を更新。
+3. 新しい ARIA バージョンが追加された場合、`src/utils/aria-version.ts` を更新。
+4. `yarn up:schema` を実行して型を再生成。
+5. テストを実行して準拠を確認。
+
+## キャッシュの考慮事項
+
+パッケージは複数のランタイムキャッシュを使用しており、**プロセスのライフタイム中は無効化されません**。これは markuplint の単発実行リントモデルでは安全ですが、以下の点に注意してください:
+
+| キャッシュ場所                                | スコープ                                        | 備考                       |
+| --------------------------------------------- | ----------------------------------------------- | -------------------------- |
+| `getARIA()` 内部キャッシュ                    | `Map`（`localName + namespace + version` キー） | プロセス再起動時のみクリア |
+| `getSpecByTagName()` キャッシュ               | `Map`（`namespace:localName` キー）             | specs インスタンスごと     |
+| `getContentModel()` キャッシュ                | `WeakMap<Element, ...>`                         | 要素ごと、GC セーフ        |
+| `contentModelCategoryToTagNames()` キャッシュ | モジュールレベル `Map<Category, string[]>`      | グローバル、無効化なし     |
+| `getAttrSpecs()` キャッシュ                   | `WeakSet` + `Map`（スキーマごと）               | 新しいスキーマでリセット   |
+| `resolveNamespace()` キャッシュ               | モジュールレベル `Map`                          | グローバル、無効化なし     |
+
+コストの高い結果を計算する新しいアルゴリズム関数を追加する場合は、要素 + specs + version をキーとする同様のキャッシュ戦略の追加を検討してください。
+
+## バージョニングポリシー
+
+- HTML Schema/Specs は markuplint の公開 API サーフェスの**一部ではありません**。
+- スキーマ、生成型、アルゴリズム動作の変更は**マイナーリリース**として扱われます。
+- パブリッシュは通常のリリースプロセスで Lerna によって処理されます。
+- `package.json` の `version` フィールドは Lerna によって管理されます -- 手動で更新しないでください。
+
+## トラブルシューティング
+
+### スキーマ生成が `$ref` エラーで失敗する
+
+**症状:** `json2ts` が `schema:attributes` 実行中に未解決の `$ref` を報告する。
+
+**原因:** `../../types/types.schema.json` への `$ref` は、`@markuplint/types` が先にスキーマを生成している必要がある。
+
+**対処:** パッケージレベルの `schema` スクリプトの代わりに、リポジトリルートから `yarn up:schema` を実行してください。
+
+### `json-schema-to-typescript` 更新後に生成型が異なる
+
+**症状:** `json-schema-to-typescript` の更新後、`src/types/*.ts` に予期しない変更がある。
+
+**原因:** 新しいバージョンがフォーマット、optional の扱い、型生成戦略を変更した可能性がある。
+
+**対処:** 差分を注意深く確認してください。型が意味的に同等であれば、変更をコミットしてください。動作が変わった場合（例: 以前 optional だったフィールドが required になった）、`json-schema-to-typescript` のチェンジログを調査してください。
+
+### ビルドエラー: 生成型の不一致
+
+**症状:** `src/types/aria.ts`、`attributes.ts`、`permitted-structures.ts` の型を参照する TypeScript ビルドエラー。
+
+**原因:** JSON スキーマが編集されたが型が再生成されていない、またはパッケージ間のスキーマ参照が古い。
+
+**対処:**
+
+```bash
+yarn up:schema
+yarn build --scope @markuplint/ml-spec
+```
+
+### 長時間実行プロセスでのキャッシュ関連の問題
+
+**症状:** 異なる設定で複数のリント実行を同じ Node.js プロセスで再利用した際に、古いデータが返される。
+
+**原因:** モジュールレベルのキャッシュ（`contentModelCategoryToTagNames`、`resolveNamespace`）は無効化されない。
+
+**対処:** これは markuplint の単発実行モデルのための設計です。markuplint を長時間実行プロセス（例: 言語サーバー）に組み込む場合、スペックデータは最初のアクセス時にキャッシュされることに注意してください。プロセスの再起動で全キャッシュがクリアされます。

package/docs/maintenance.md

@@ -0,0 +1,331 @@
+# Maintenance Guide
+
+## Overview
+
+This guide covers the day-to-day operational and maintenance tasks for `@markuplint/ml-spec`. It focuses on schema generation, dependency management, testing, common recipes, and troubleshooting.
+
+## Build and Development Commands
+
+| Command                                         | Scope    | Description                                          |
+| ----------------------------------------------- | -------- | ---------------------------------------------------- |
+| `yarn build --scope @markuplint/ml-spec`        | Package  | Compile TypeScript to `lib/`                         |
+| `yarn workspace @markuplint/ml-spec run dev`    | Package  | Watch mode compilation                               |
+| `yarn workspace @markuplint/ml-spec run clean`  | Package  | Remove `lib/` output                                 |
+| `yarn workspace @markuplint/ml-spec run schema` | Package  | Regenerate schemas and types                         |
+| `yarn up:schema`                                | Monorepo | Regenerate schemas across all packages (recommended) |
+| `yarn test`                                     | Monorepo | Run all tests via vitest                             |
+
+## Schema Generation Pipeline
+
+### Why schema generation exists
+
+The package uses JSON Schema files as a single source of truth for complex type structures (ARIA definitions, attribute types, content models, global attributes). TypeScript types are auto-generated from these schemas via `json-schema-to-typescript` (`json2ts`). This ensures that:
+
+- JSON data files consumed at runtime are validated against the same structure as TypeScript types.
+- Schema changes automatically propagate to type definitions.
+- The `@markuplint/html-spec` JSON data stays consistent with the type system.
+
+### Generation flow
+
+```
+gen/global-attribute.data.ts   schemas/aria.schema.json
+         │                     schemas/content-models.schema.json
+         ▼                              │
+    gen/gen.ts                          │
+         │                              │
+         ▼                              ▼
+schemas/global-attributes.schema.json   │
+schemas/attributes.schema.json          │
+         │                              │
+         └──────────┬───────────────────┘
+                    ▼
+          json-schema-to-typescript
+                    │
+         ┌──────────┼──────────────┐
+         ▼          ▼              ▼
+  types/aria.ts  types/        types/permitted-
+              attributes.ts    structures.ts
+                    │
+                    ▼
+          prettier + eslint
+```
+
+### Script breakdown (`yarn workspace @markuplint/ml-spec run schema`)
+
+The `schema` script is a sequential pipeline using `run-s`:
+
+```
+schema:json → schema:content-models → schema:attributes → schema:aria → schema:prettier → schema:eslint → schema:prettier
+```
+
+| Step                    | Command                                                    | Input                                | Output                                                                    |
+| ----------------------- | ---------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------- |
+| `schema:json`           | `tsx ./gen/gen.ts`                                         | `gen/global-attribute.data.ts`       | `schemas/global-attributes.schema.json`, `schemas/attributes.schema.json` |
+| `schema:content-models` | `json2ts ./schemas/content-models.schema.json`             | `schemas/content-models.schema.json` | `src/types/permitted-structures.ts`                                       |
+| `schema:attributes`     | `json2ts ./schemas/attributes.schema.json --cwd ./schemas` | `schemas/attributes.schema.json`     | `src/types/attributes.ts`                                                 |
+| `schema:aria`           | `json2ts ./schemas/aria.schema.json --cwd ./schemas`       | `schemas/aria.schema.json`           | `src/types/aria.ts`                                                       |
+| `schema:prettier`       | `prettier --write`                                         | `schemas/*.json`, `src/types/*.ts`   | Formatted files                                                           |
+| `schema:eslint`         | `eslint --fix`                                             | `src/types/*.ts`                     | Lint-fixed files                                                          |
+
+Note: `schema:prettier` runs **twice** -- once after `schema:aria` to format generated files, then again after `schema:eslint` to clean up any eslint auto-fix formatting changes.
+
+### Cross-package dependency: `@markuplint/types`
+
+`schemas/attributes.schema.json` contains a `$ref` to `@markuplint/types`:
+
+```json
+{
+  "AttributeType": {
+    "$ref": "../../types/types.schema.json#/definitions/type"
+  }
+}
+```
+
+This means `@markuplint/types` must regenerate its schema **before** `@markuplint/ml-spec`. The monorepo-level `yarn up:schema` handles this order automatically:
+
+1. `@markuplint/types` -- generates `types.schema.json`, builds the package
+2. `@markuplint/ml-spec` -- generates schemas referencing `types.schema.json`
+3. Other packages with `schema` scripts
+
+**Always prefer `yarn up:schema` from the repository root** when updating schemas that may involve cross-package references.
+
+## File Classification: Editable vs Generated
+
+### Files you MUST NOT edit directly
+
+These files carry "DO NOT MODIFY" headers and are overwritten by the generation pipeline:
+
+| File                                    | Generated from                                |
+| --------------------------------------- | --------------------------------------------- |
+| `src/types/aria.ts`                     | `schemas/aria.schema.json`                    |
+| `src/types/attributes.ts`               | `schemas/attributes.schema.json`              |
+| `src/types/permitted-structures.ts`     | `schemas/content-models.schema.json`          |
+| `schemas/global-attributes.schema.json` | `gen/gen.ts` + `gen/global-attribute.data.ts` |
+| `schemas/attributes.schema.json`        | `gen/gen.ts` + `gen/global-attribute.data.ts` |
+
+### Files you edit to change generated output
+
+| To change...                               | Edit this file                                | Then run                                        |
+| ------------------------------------------ | --------------------------------------------- | ----------------------------------------------- |
+| Global attribute categories/items          | `gen/global-attribute.data.ts`                | `yarn workspace @markuplint/ml-spec run schema` |
+| `AttributeJSON` shape (add field)          | `gen/gen.ts` (the `AttributeJSON` definition) | `yarn workspace @markuplint/ml-spec run schema` |
+| ARIA role/property structure               | `schemas/aria.schema.json`                    | `yarn workspace @markuplint/ml-spec run schema` |
+| Content model patterns                     | `schemas/content-models.schema.json`          | `yarn workspace @markuplint/ml-spec run schema` |
+| Attribute value types (CSS keywords, etc.) | `@markuplint/types` package                   | `yarn up:schema` (from root)                    |
+
+### Files you edit directly (hand-written)
+
+| File                          | Purpose                                                               |
+| ----------------------------- | --------------------------------------------------------------------- |
+| `src/types/index.ts`          | Core hand-written types (`MLMLSpec`, `ElementSpec`, `ARIARole`, etc.) |
+| `src/algorithm/aria/*.ts`     | ARIA algorithm implementations                                        |
+| `src/algorithm/html/*.ts`     | HTML algorithm implementations                                        |
+| `src/utils/*.ts`              | Utility functions                                                     |
+| `src/index.ts`                | Public API exports                                                    |
+| `schemas/element.schema.json` | Top-level element schema (manual, 11 lines)                           |
+
+## Testing
+
+### Test files
+
+The package has 18 test files using vitest:
+
+| Directory                     | Test files | Coverage                                                                                                                                                                                                                               |
+| ----------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/algorithm/aria/`         | 11         | `accname-computation`, `get-computed-aria-props`, `get-computed-role`, `get-implicit-role-spec`, `get-implicit-role`, `get-permitted-roles-spec`, `get-role-spec`, `has-required-owned-elements`, `is-exposed`, `matches-context-role` |
+| `src/algorithm/aria/accname/` | 3          | `aria-steps`, `compute`, `element-names`, `label-steps`                                                                                                                                                                                |
+| `src/utils/`                  | 4          | `get-attr-specs-spec`, `get-spec-by-tag-name`, `resolve-namespace`, `resolve-version`, `schema-to-spec`                                                                                                                                |
+
+### Running tests
+
+```bash
+# All tests in the monorepo
+yarn test
+
+# Only ml-spec tests
+yarn test packages/@markuplint/ml-spec
+
+# Specific test file
+yarn test packages/@markuplint/ml-spec/src/algorithm/aria/get-computed-role.spec.ts
+```
+
+Tests depend on `@markuplint/test-tools` (devDependency) which provides HTML parsing utilities for creating DOM elements in test environments.
+
+## Dependency Management
+
+### Runtime dependencies
+
+| Package              | Version | Purpose                                | Update risk               |
+| -------------------- | ------- | -------------------------------------- | ------------------------- |
+| `@markuplint/ml-ast` | 4.4.10  | `NamespaceURI` type                    | Low (internal)            |
+| `@markuplint/types`  | 4.8.1   | `Type` union for attribute value types | Medium (schema reference) |
+| `is-plain-object`    | 5.0.0   | Plain object detection for AAM info    | Low (stable API)          |
+| `type-fest`          | 4.41.0  | `ReadonlyDeep` utility type            | Low (types only)          |
+
+### Dev dependencies
+
+| Package                     | Version | Purpose                                 |
+| --------------------------- | ------- | --------------------------------------- |
+| `@markuplint/test-tools`    | 4.5.22  | Test utilities for DOM element creation |
+| `json-schema-to-typescript` | 15.0.4  | Schema → TypeScript type generation     |
+
+### Updating dependencies
+
+- **`json-schema-to-typescript`**: Major version updates may change generated type output (formatting, optional handling). After updating, run `yarn workspace @markuplint/ml-spec run schema` and review diffs in `src/types/*.ts`.
+- **`@markuplint/types`**: Always run `yarn up:schema` after updating to ensure schema references stay consistent.
+- **`type-fest`**: Type-only dependency. Update freely, but verify the build succeeds (`yarn build --scope @markuplint/ml-spec`).
+
+## Common Maintenance Recipes
+
+### 1. Add a new global attribute
+
+Edit `gen/global-attribute.data.ts`, add the attribute name to the appropriate category array:
+
+```ts
+'#HTMLGlobalAttrs': {
+  attrs: [
+    // ...existing attributes...
+    'newattribute',  // ← add here
+  ],
+},
+```
+
+Then regenerate:
+
+```bash
+yarn workspace @markuplint/ml-spec run schema
+```
+
+### 2. Add a new global attribute category
+
+Edit `gen/global-attribute.data.ts`, add a new entry:
+
+```ts
+'#NewCategoryAttrs': {
+  description: 'Description with spec link',
+  attrs: ['attr1', 'attr2'],
+},
+```
+
+The key must match the pattern `#${string}Attrs`. The generator (`gen/gen.ts`) automatically handles the new category in both `global-attributes.schema.json` and `attributes.schema.json`.
+
+Then regenerate:
+
+```bash
+yarn workspace @markuplint/ml-spec run schema
+```
+
+### 3. Add a new field to `AttributeJSON`
+
+Edit `gen/gen.ts`, add the property inside the `AttributeJSON` definition object:
+
+```ts
+AttributeJSON: {
+  properties: {
+    // ...existing properties...
+    newField: { type: 'boolean' },  // ← add here
+  },
+},
+```
+
+Then regenerate. The new field will appear in `src/types/attributes.ts` as an optional property.
+
+### 4. Modify ARIA role/property schema
+
+Edit `schemas/aria.schema.json` directly. For example, to add a new field to the role definition:
+
+```json
+{
+  "definitions": {
+    "role": {
+      "properties": {
+        "newField": { "type": "boolean" }
+      }
+    }
+  }
+}
+```
+
+Then regenerate. The new field will appear in `src/types/aria.ts`.
+
+### 5. Add a new content model category
+
+Edit `schemas/content-models.schema.json`, add the category to the `Category` enum and define its pattern.
+
+### 6. Add a new ARIA algorithm function
+
+1. Create the implementation file in `src/algorithm/aria/`.
+2. Create a corresponding `.spec.ts` test file.
+3. Export the function from `src/index.ts`.
+4. Update `docs/aria-algorithms.md` and `docs/aria-algorithms.ja.md`.
+
+### 7. Update W3C specification compliance
+
+When a W3C specification updates (e.g., WAI-ARIA 1.3 becomes a Recommendation):
+
+1. Update `@markuplint/html-spec` data if element-level ARIA mappings changed.
+2. Update algorithm implementations in `src/algorithm/aria/*.ts` if algorithm behavior changed.
+3. Update `src/utils/aria-version.ts` if a new ARIA version is added.
+4. Run `yarn up:schema` to regenerate types.
+5. Run tests to verify compliance.
+
+## Caching Considerations
+
+The package uses several runtime caches that are **never invalidated during a process lifetime**. This is safe for markuplint's single-run lint model, but be aware of it when:
+
+| Cache location                           | Scope                                            | Notes                           |
+| ---------------------------------------- | ------------------------------------------------ | ------------------------------- |
+| `getARIA()` internal cache               | `Map` keyed by `localName + namespace + version` | Cleared only on process restart |
+| `getSpecByTagName()` cache               | `Map` keyed by `namespace:localName`             | Per-specs instance              |
+| `getContentModel()` cache                | `WeakMap<Element, ...>`                          | Per-element, GC-safe            |
+| `contentModelCategoryToTagNames()` cache | Module-level `Map<Category, string[]>`           | Global, never invalidated       |
+| `getAttrSpecs()` cache                   | `WeakSet` + `Map` per schema                     | New schema resets cache         |
+| `resolveNamespace()` cache               | Module-level `Map`                               | Global, never invalidated       |
+
+If you add a new algorithm function that computes expensive results, consider adding a similar caching strategy keyed by element + specs + version.
+
+## Versioning Policy
+
+- HTML Schema/Specs are **not** part of the public API surface of markuplint.
+- Changes to schemas, generated types, or algorithm behavior are treated as a **minor release**.
+- Publishing is handled by Lerna during the normal release process.
+- The `version` field in `package.json` is managed by Lerna -- do not manually update it.
+
+## Troubleshooting
+
+### Schema generation fails with `$ref` error
+
+**Symptom:** `json2ts` reports an unresolved `$ref` during `schema:attributes`.
+
+**Cause:** The `$ref` to `../../types/types.schema.json` requires `@markuplint/types` to have generated its schema first.
+
+**Fix:** Run `yarn up:schema` from the repository root instead of the package-level `schema` script.
+
+### Generated types differ after `json-schema-to-typescript` update
+
+**Symptom:** After updating `json-schema-to-typescript`, `src/types/*.ts` has unexpected changes.
+
+**Cause:** New versions may change formatting, optional handling, or type generation strategy.
+
+**Fix:** Review the diff carefully. If the types are semantically equivalent, commit the changes. If behavior changed (e.g., previously optional fields became required), investigate the `json-schema-to-typescript` changelog.
+
+### Build error: generated type mismatch
+
+**Symptom:** TypeScript build errors referencing types in `src/types/aria.ts`, `attributes.ts`, or `permitted-structures.ts`.
+
+**Cause:** The JSON schema was edited but types were not regenerated, or a cross-package schema reference is stale.
+
+**Fix:**
+
+```bash
+yarn up:schema
+yarn build --scope @markuplint/ml-spec
+```
+
+### Cache-related issues in long-running processes
+
+**Symptom:** Stale data when reusing the same Node.js process across multiple lint runs with different configurations.
+
+**Cause:** Module-level caches (`contentModelCategoryToTagNames`, `resolveNamespace`) are never invalidated.
+
+**Fix:** This is by design for markuplint's single-run model. If you embed markuplint in a long-running process (e.g., a language server), be aware that spec data is cached at first access. Restarting the process clears all caches.