@markuplint/ml-spec 5.0.0-rc.2 → 5.0.0-rc.5

package/ARCHITECTURE.md

@@ -1,267 +0,0 @@
-# @markuplint/ml-spec
-
-## Overview
-
-`@markuplint/ml-spec` is the specification foundation layer for markuplint. It provides type definitions, W3C specification algorithms (ARIA/HTML), JSON schemas, and runtime utilities that form the bridge between raw web standard data and markuplint's lint rules.
-
-The package reads element specifications, ARIA role/property definitions, and content model data from `@markuplint/html-spec` (and framework-specific spec packages), then exposes algorithms for computing ARIA roles, resolving element specifications, evaluating content models, and determining accessibility tree inclusion. Over 15 downstream packages depend on `@markuplint/ml-spec`.
-
-## Directory Structure
-
-```
-src/
-├── index.ts                                      # Package entry point; re-exports all public APIs
-├── types/
-│   ├── index.ts                                  # Hand-written core types (MLMLSpec, ElementSpec, ARIARole, etc.)
-│   ├── aria.ts                                   # Generated types from aria.schema.json (ARIA, PermittedRoles, ImplicitRole)
-│   ├── attributes.ts                             # Generated types from attributes.schema.json (AttributeType, GlobalAttributes)
-│   └── permitted-structures.ts                   # Generated types from content-models.schema.json (ContentModel, Category)
-├── algorithm/
-│   ├── aria/
-│   │   ├── accname-computation.ts                # Accessible name computation facade (DOM resolver + reentrant guard)
-│   │   ├── accname/                              # AccName pure algorithm (HTML-AAM §4.1)
-│   │   │   ├── types.ts                          # AccnameElement/AccnameResolver interfaces
-│   │   │   ├── compute.ts                        # Core algorithm: Steps 2A-2I
-│   │   │   ├── aria-steps.ts                     # Steps 2B (aria-labelledby) and 2D (aria-label)
-│   │   │   ├── element-names.ts                  # Step 2E: element-specific name (HTML-AAM §4.1)
-│   │   │   ├── helpers.ts                        # Shared utilities (embedded controls, name-from-content)
-│   │   │   ├── label-steps.ts                    # Step 2E: label association for labelable elements
-│   │   │   ├── svg-helpers.ts                    # SVG accessible name source check
-│   │   │   └── index.ts                          # Re-exports public API
-│   │   ├── aria-specs.ts                         # Version-specific ARIA spec data retrieval
-│   │   ├── get-aria.ts                           # Element-level ARIA spec resolution with conditions
-│   │   ├── get-computed-aria-props.ts            # ARIA property resolution (explicit → HTML → default)
-│   │   ├── get-computed-role.ts                  # Core: final role computation with conflict resolution
-│   │   ├── get-explicit-role.ts                  # Explicit role from role attribute with author error handling
-│   │   ├── get-implicit-role.ts                  # Implicit (native) role from HTML-AAM
-│   │   ├── get-implicit-role-spec.ts             # Low-level implicit role name lookup
-│   │   ├── get-non-presentational-ancestor.ts    # Ancestor traversal skipping presentational roles
-│   │   ├── get-permitted-roles.ts                # Permitted roles for a DOM element
-│   │   ├── get-permitted-roles-spec.ts           # Permitted roles from tag name/namespace (low-level)
-│   │   ├── get-role-spec.ts                      # Full role spec with super-class chain
-│   │   ├── has-required-owned-elements.ts        # Required owned elements validation
-│   │   ├── is-exposed.ts                         # Accessibility tree inclusion/exclusion
-│   │   ├── is-presentational.ts                  # Presentational role check (presentation/none)
-│   │   └── matches-context-role.ts               # Required context role validation
-│   └── html/
-│       ├── content-model-category-to-tag-names.ts  # Category → tag name array (cached)
-│       ├── get-content-model.ts                    # Content model with conditional evaluation
-│       ├── get-selectors-by-content-model-category.ts  # Category → CSS selector array
-│       ├── is-nothing-content-model.ts             # "Nothing" content model check
-│       ├── is-palpable-elements.ts                 # Palpable content detection
-│       ├── is-void-element.ts                      # Void element check (13 elements)
-│       └── may-be-focusable.ts                     # Focusability heuristic
-├── const/
-│   ├── index.ts                                  # Re-exports all constants
-│   ├── dom.ts                                    # DOM constants (ELEMENT_NODE, TEXT_NODE, namespace URIs)
-│   └── accname.ts                                # AccName constants (embedded control roles, input types, defaults)
-└── utils/
-    ├── aria-version.ts                           # ARIA version constants ('1.1', '1.2', '1.3')
-    ├── get-attr-specs.ts                         # Attribute specs for a DOM element (wrapper)
-    ├── get-attr-specs-spec.ts                    # Attribute specs by tag name/namespace (core)
-    ├── get-ns.ts                                 # Namespace URI → shorthand mapping
-    ├── get-spec.ts                               # Element spec for a DOM element (wrapper)
-    ├── get-spec-by-tag-name.ts                   # Element spec by tag name/namespace (cached)
-    ├── merge-array.ts                            # Name-based array merge utility
-    ├── resolve-namespace.ts                      # Namespace resolution and prefix normalization
-    ├── resolve-version.ts                        # ARIA version-specific property resolution
-    ├── schema-to-spec.ts                         # Schema merge pipeline (base + extensions)
-    └── validate-aria-version.ts                  # ARIA version string type guard
-
-schemas/
-├── element.schema.json                           # Top-level element spec schema (11 lines)
-├── aria.schema.json                              # ARIA role/property schema (291 lines)
-├── attributes.schema.json                        # Attribute type schema (190 lines)
-├── content-models.schema.json                    # Content model pattern schema (215 lines)
-└── global-attributes.schema.json                 # Global attribute categories schema (787 lines)
-
-gen/
-├── gen.ts                                        # Schema generator for global-attributes.schema.json
-└── global-attribute.data.ts                      # Global attribute category definitions
-```
-
-## Architecture Diagram
-
-```mermaid
-flowchart TD
-    subgraph input ["Input Layer"]
-        htmlSpec["@markuplint/html-spec\n(MLMLSpec JSON)"]
-        fwSpec["Framework specs\n(ExtendedSpec)"]
-    end
-
-    subgraph merge ["Spec Resolution"]
-        schemaToSpec["schemaToSpec()"]
-        getSpec["getSpec() / getSpecByTagName()"]
-        getAttrSpecs["getAttrSpecs()"]
-        resolveNS["resolveNamespace()"]
-    end
-
-    subgraph aria ["ARIA Algorithms"]
-        getComputedRole["getComputedRole()"]
-        getExplicitRole["getExplicitRole()"]
-        getImplicitRole["getImplicitRole()"]
-        getPermittedRoles["getPermittedRoles()"]
-        getRoleSpec["getRoleSpec()"]
-        getARIA["getARIA()"]
-        getComputedAriaProps["getComputedAriaProps()"]
-        isExposed["isExposed()"]
-        getAccname["getAccname()"]
-    end
-
-    subgraph html ["HTML Algorithms"]
-        getContentModel["getContentModel()"]
-        isPalpable["isPalpableElement()"]
-        isVoid["isVoidElement()"]
-        mayBeFocusable["mayBeFocusable()"]
-    end
-
-    subgraph types ["Type Definitions"]
-        handWritten["MLMLSpec, ElementSpec\nARIARole, ComputedRole"]
-        generated["ARIA, PermittedRoles\nContentModel, Category"]
-    end
-
-    htmlSpec --> schemaToSpec
-    fwSpec --> schemaToSpec
-    schemaToSpec --> getSpec
-    getSpec --> getAttrSpecs
-    getSpec --> getARIA
-    resolveNS --> getSpec
-
-    getARIA --> getComputedRole
-    getExplicitRole --> getComputedRole
-    getImplicitRole --> getComputedRole
-    getPermittedRoles --> getExplicitRole
-    getRoleSpec --> getImplicitRole
-    getRoleSpec --> getExplicitRole
-    getComputedRole --> getComputedAriaProps
-    getComputedRole --> isExposed
-
-    getSpec --> getContentModel
-    getSpec --> isPalpable
-```
-
-## Core Components
-
-### 1. Type Definitions
-
-The type system defines the structure of markup language specifications, element specs, ARIA roles, and attributes.
-
-| File                            | Purpose                                                                                                                            |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `types/index.ts`                | Hand-written types: `MLMLSpec`, `ElementSpec`, `ExtendedSpec`, `ARIARole`, `ComputedRole`, etc.                                    |
-| `types/aria.ts`                 | Generated: `ARIA`, `PermittedRoles`, `ImplicitRole`, `PermittedARIAProperties`, `ImplicitProperties`                               |
-| `types/attributes.ts`           | Generated: `AttributeType`, `ConditionalAttributeType`, `GlobalAttributes`, `AttributeJSON`, `List`, `Enum`, `Number`, `Directive` |
-| `types/permitted-structures.ts` | Generated: `PermittedContentPattern`, `ContentModel`, `Category` (HTML 13 + SVG 19 + MathML 3 categories)                          |
-
-### 2. ARIA Algorithms
-
-ARIA algorithms implement WAI-ARIA, HTML-AAM, SVG-AAM, MathML-AAM, and AccName 1.2 specifications for role computation and accessibility tree management.
-
-| File                             | Purpose                                                                           |
-| -------------------------------- | --------------------------------------------------------------------------------- |
-| `get-computed-role.ts`           | Core algorithm: computes final role with Presentational Roles Conflict Resolution |
-| `get-explicit-role.ts`           | Resolves explicit roles from `role` attribute with author error handling          |
-| `get-implicit-role.ts`           | Determines implicit (native) ARIA role from HTML-AAM                              |
-| `get-computed-aria-props.ts`     | Resolves ARIA properties: explicit `aria-*` → HTML equivalent → spec defaults     |
-| `is-exposed.ts`                  | Determines accessibility tree inclusion/exclusion per WAI-ARIA rules              |
-| `get-permitted-roles.ts`         | Lists permitted roles for an element (Any/No/specific list)                       |
-| `get-role-spec.ts`               | Retrieves full role spec with super-class role chain                              |
-| `has-required-owned-elements.ts` | Validates required owned element constraints                                      |
-| `matches-context-role.ts`        | Validates required context role conditions in ancestor chain                      |
-| `accname-computation.ts`         | Accessible name computation facade (DOM resolver + reentrant guard)               |
-| `accname/compute.ts`             | Pure AccName algorithm: Steps 2A-2I per HTML-AAM §4.1                             |
-| `accname/element-names.ts`       | Step 2E: Element-specific name computation (HTML-AAM §4.1)                        |
-| `get-aria.ts`                    | Element-level ARIA spec with version and condition resolution                     |
-| `is-presentational.ts`           | Checks if a role is `presentation` or `none`                                      |
-
-### 3. HTML Algorithms
-
-HTML algorithms implement content model evaluation and element classification from the HTML Living Standard.
-
-| File                                         | Purpose                                                           |
-| -------------------------------------------- | ----------------------------------------------------------------- |
-| `get-content-model.ts`                       | Retrieves content model with conditional pattern evaluation       |
-| `content-model-category-to-tag-names.ts`     | Converts content model category to sorted tag name array          |
-| `get-selectors-by-content-model-category.ts` | Maps content model category to CSS selectors                      |
-| `is-palpable-elements.ts`                    | Palpable content detection with SVG/MathML/exposable extensions   |
-| `is-void-element.ts`                         | Void element check (13 HTML void elements)                        |
-| `is-nothing-content-model.ts`                | "Nothing" content model check (void + iframe + template)          |
-| `may-be-focusable.ts`                        | Focusability heuristic (interactive + tabindex + contenteditable) |
-
-### 4. Spec Resolution Utilities
-
-Utilities for merging, resolving, and caching specifications.
-
-| File                       | Purpose                                                                     |
-| -------------------------- | --------------------------------------------------------------------------- |
-| `schema-to-spec.ts`        | Merges base `MLMLSpec` with `ExtendedSpec[]` (global attrs, ARIA, elements) |
-| `get-spec-by-tag-name.ts`  | Looks up element spec by tag name + namespace (cached)                      |
-| `get-attr-specs-spec.ts`   | Retrieves merged attribute specs (global + element-specific)                |
-| `resolve-namespace.ts`     | Normalizes element names with namespace prefixes                            |
-| `resolve-version.ts`       | Resolves ARIA version-specific overrides with fallback                      |
-| `merge-array.ts`           | Name-based array merging (add/override by `name` property)                  |
-| `validate-aria-version.ts` | Type guard for valid ARIA version strings                                   |
-
-## External Dependencies
-
-| Dependency           | Purpose                                           | Where Used                    |
-| -------------------- | ------------------------------------------------- | ----------------------------- |
-| `@markuplint/ml-ast` | `NamespaceURI` type for XML namespace handling    | `types/index.ts`, utils       |
-| `@markuplint/types`  | `Type` union for attribute value type definitions | via `types/attributes.ts`     |
-| `is-plain-object`    | Plain object detection for AAM info               | `get-permitted-roles-spec.ts` |
-| `type-fest`          | `ReadonlyDeep` utility type for deep immutability | Multiple files                |
-
-## Integration Points
-
-```mermaid
-flowchart LR
-    subgraph upstream ["Upstream"]
-        htmlSpec["@markuplint/html-spec"]
-        vueSpec["@markuplint/vue-spec"]
-        reactSpec["@markuplint/react-spec"]
-        otherSpec["Other framework specs"]
-    end
-
-    subgraph pkg ["@markuplint/ml-spec"]
-        types["Type definitions"]
-        ariaAlgo["ARIA algorithms"]
-        htmlAlgo["HTML algorithms"]
-        specRes["Spec resolution"]
-    end
-
-    subgraph downstream ["Downstream"]
-        mlCore["@markuplint/ml-core"]
-        rules["@markuplint/rules"]
-        selector["@markuplint/selector"]
-    end
-
-    htmlSpec -->|"MLMLSpec JSON"| specRes
-    vueSpec -->|"ExtendedSpec"| specRes
-    reactSpec -->|"ExtendedSpec"| specRes
-    otherSpec -->|"ExtendedSpec"| specRes
-
-    specRes --> ariaAlgo
-    specRes --> htmlAlgo
-    types --> mlCore
-    ariaAlgo -->|"role computation\naccessibility tree"| rules
-    htmlAlgo -->|"content model\nelement classification"| rules
-    types --> selector
-```
-
-### Upstream
-
-`@markuplint/html-spec` provides the base `MLMLSpec` JSON containing all HTML element specifications, ARIA definitions, and content model data. Framework-specific packages (`@markuplint/vue-spec`, `@markuplint/react-spec`, etc.) provide `ExtendedSpec` objects that add or override elements, attributes, and ARIA mappings.
-
-### Downstream
-
-- **`@markuplint/ml-core`** uses the type definitions to represent parsed document elements with spec awareness.
-- **`@markuplint/rules`** calls ARIA and HTML algorithms to implement lint rules (role validation, content model checking, accessibility checks).
-- **`@markuplint/selector`** uses type definitions for element matching.
-
-## Documentation Map
-
-- [ARIA Algorithms](docs/aria-algorithms.md) -- Role computation, accessibility tree, ARIA property resolution
-- [HTML Algorithms](docs/html-algorithms.md) -- Content models, element classification, void elements
-- [Type Definitions](docs/type-definitions.md) -- Core types, generated types, JSON schemas
-- [Spec Resolution](docs/spec-resolution.md) -- Schema merging, namespace resolution, caching
-- [Maintenance Guide](docs/maintenance.md) -- Schema generation, dependency management, recipes, troubleshooting

package/SKILL.md

@@ -1,116 +0,0 @@
----
-description: Verify documentation claims against web standards and source code
----
-
-# verify-docs
-
-Verify that documentation claims in `@markuplint/ml-spec` are accurate by cross-referencing them against official web standards (WAI-ARIA, HTML-AAM, SVG-AAM, AccName, HTML Living Standard) and the actual source code implementation.
-
-## Input
-
-`$ARGUMENTS` specifies the target: a package name (e.g., `@markuplint/ml-spec`) or a specific documentation file path. If omitted, defaults to all `docs/*.md` files in `packages/@markuplint/ml-spec/`.
-
-## Phase 1: Discovery
-
-Read all target documentation files and extract every claim that references an external specification. Look for:
-
-- Specification URLs (e.g., `https://www.w3.org/TR/wai-aria-1.2/...`, `https://html.spec.whatwg.org/...`)
-- WAI-ARIA algorithm descriptions (role computation, presentational conflict resolution)
-- HTML-AAM implicit role mappings
-- SVG-AAM accessibility tree inclusion rules
-- AccName computation references
-- Content model category claims (element counts, category membership)
-- Specific numeric claims (e.g., "13 void elements", "11 error codes")
-- Function behavior claims ("returns X when Y")
-- Statements like "Implements the X spec" or "according to Y specification"
-
-Collect each claim as a structured item:
-
-```
-{ file, line, claim, specDomain, specURL }
-```
-
-## Phase 2: Categorize
-
-Group extracted claims by specification domain:
-
-| Domain        | Examples                                                                       |
-| ------------- | ------------------------------------------------------------------------------ |
-| WAI-ARIA      | Role computation, presentational roles conflict resolution, accessibility tree |
-| HTML-AAM      | Implicit role mappings, permitted roles, ARIA property defaults                |
-| AccName       | Accessible name computation algorithm, placeholder fallback                    |
-| SVG-AAM       | SVG element inclusion rules, graphics ARIA roles                               |
-| HTML Standard | Content models, void elements, interactive content, palpable content           |
-
-## Phase 3: Parallel Verification
-
-For each domain group, launch a parallel agent using the **Task tool** with `subagent_type: "general-purpose"`. Each agent:
-
-1. **Searches the official specification** using WebSearch to find the authoritative definition
-2. **Compares the documentation claim** against the spec definition
-3. **Reads the corresponding source code** to confirm the implementation matches
-4. **Assigns a verdict** to each claim:
-   - **PASS** — Documentation accurately describes the spec and matches the implementation
-   - **FAIL** — Documentation is inaccurate (wrong number, incorrect algorithm, misleading description)
-   - **WARN** — Documentation is technically correct but potentially misleading or incomplete
-
-Each agent returns its results as a structured list:
-
-```
-| # | File:Line | Claim | Spec Source | Verdict | Notes |
-```
-
-## Phase 4: Report
-
-Collect results from all parallel agents and produce a consolidated PASS/FAIL table:
-
-```markdown
-## Verification Report
-
-| #   | Domain        | File:Line              | Claim Summary                 | Verdict | Notes                                  |
-| --- | ------------- | ---------------------- | ----------------------------- | ------- | -------------------------------------- |
-| 1   | WAI-ARIA      | aria-algorithms.md:125 | 11 RoleComputationError codes | PASS    | Matches source types/index.ts          |
-| 2   | HTML Standard | html-algorithms.md:45  | 13 void elements              | PASS    | Matches is-void-element.ts Set         |
-| 3   | HTML-AAM      | aria-algorithms.md:200 | getImplicitRole returns false | WARN    | Returns ImplicitRole (false or string) |
-| ... | ...           | ...                    | ...                           | ...     | ...                                    |
-
-**Summary:** X PASS / Y FAIL / Z WARN out of N total claims
-```
-
-## Phase 5: Correction Plan
-
-For every FAIL item, produce a concrete correction instruction:
-
-```markdown
-### Correction 1: [Brief description]
-
-- **File:** `path/to/file.md`
-- **Line:** 125
-- **Current:** `(11 error codes)`
-- **Corrected:** `(12 error codes)`
-- **Reason:** Source code `types/index.ts` contains 12 entries in `RoleComputationError` union
-```
-
-For WARN items, produce an advisory note with a suggested improvement (not mandatory).
-
-## Rules
-
-1. **Source code is the source of truth for implementation behavior.** If the docs say "implements X" but the code does something slightly different, the docs should be corrected to accurately describe what the code does.
-2. **Specification is the source of truth for what the standard defines.** If the code intentionally deviates from the spec, the docs should note the deviation explicitly.
-3. **Code bugs are a separate category.** If the code itself doesn't match the spec, flag it as a code issue (not a documentation issue) and note it separately.
-4. **Numeric claims must be exact.** Count arrays, enum values, union members, and Set entries in the source code to verify numbers stated in documentation.
-5. **Algorithm descriptions must match the actual code flow.** Verify that documented step orders, condition checks, and branching logic correspond to the implementation.
-6. **Use WebSearch for spec verification.** Always fetch the latest version of the referenced specification — do not rely on cached knowledge.
-
-## Hardcoded Test Data
-
-The following test files contain hardcoded spec data that must stay in sync
-with `@markuplint/html-spec`:
-
-| Test file                                             | Data                                                       | Trigger                                                 |
-| ----------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------- |
-| `src/algorithm/aria/get-permitted-roles-spec.spec.ts` | `permittedRoles` arrays for img, button, input, form, etc. | `permittedRoles` changes in `html-spec/src/spec.*.json` |
-
-When `@markuplint/html-spec` ARIA mappings change, update these arrays.
-The arrays are version-specific — update only the correct version's expectations
-(e.g., `'1.2'` tests but not `'1.1'` tests for newly added roles).