@markuplint/ml-spec 4.10.1 → 4.10.2

package/docs/maintenance.md

@@ -0,0 +1,340 @@
+# 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 15 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/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) |
+| `dom-accessibility-api` | 0.7.1   | AccName computation                    | Medium (spec compliance)  |
+| `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
+
+- **`dom-accessibility-api`**: Updates may change AccName computation behavior. Run `accname-computation.spec.ts` tests after updating.
+- **`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                | `Map<Specs, Map<Element, ...>>`                  | Nested, per-specs + per-element |
+| `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.
+
+### Test failures after `dom-accessibility-api` update
+
+**Symptom:** `accname-computation.spec.ts` fails after updating `dom-accessibility-api`.
+
+**Cause:** The library updated its AccName algorithm implementation, changing computed accessible names.
+
+**Fix:** Verify the new behavior against the [AccName 1.1 specification](https://www.w3.org/TR/accname-1.1/). If the library is now more spec-compliant, update the test expectations.
+
+### 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.