@markuplint/ml-spec 4.10.1 → 4.18.0

package/README.md

@@ -126,195 +126,13 @@ yarn add @markuplint/ml-spec
 - "HTML Schema" and "Specs" are used interchangeably in markuplint to mean the JSON Schema that
   describes HTML element specs (attributes, ARIA, content models, etc) and their TypeScript types.
 
-### Editing workflow (HTML Schema/Specs)
+### Contributing
 
-1. Make changes to the schemas
+For schema editing workflows, generation commands, common recipes, dependency management, and troubleshooting, see the [Maintenance Guide](docs/maintenance.md).
 
-- Attributes schema shape: update `gen/gen.ts` if you need to change the structure of
-  `AttributeJSON`/`GlobalAttributes` (because `attributes.schema.json` is generated).
-- ARIA schema shape: edit `schemas/aria.schema.json`.
-- Content model schema shape: edit `schemas/content-models.schema.json`.
-- Element schema aggregator: edit `schemas/element.schema.json` (it composes refs to the above).
-- Global attribute categories/sets: edit `gen/global-attribute.data.*`, then regenerate via the commands below.
+For schema merging and spec extension details, see [Spec Resolution](docs/spec-resolution.md).
 
-If you want to change the concrete HTML element data (e.g., add/update element- or attribute-level
-entries), update `@markuplint/html-spec` (and, if necessary, `@markuplint/spec-generator`).
-
-2. Regenerate schemas and types
-
-From the repository root (recommended):
-
-```bash
-yarn up:schema
-```
-
-or only for this package:
-
-```bash
-yarn workspace @markuplint/ml-spec run schema
-```
-
-This will:
-
-- Run `gen/gen.ts` to output `global-attributes.schema.json` and `attributes.schema.json`
-- Convert JSON Schema to TypeScript via `json2ts` into `src/types/*.ts`
-- Format with Prettier and ESLint
-
-#### What `yarn up:schema` does
-
-From the repository root, this executes schema maintenance across packages in order:
-
-1. `@markuplint/types`
-
-- Run `gen/types.ts` to build `types.schema.json` from css-tree keywords/types and
-  `gen/specific-schema.json`
-- Generate TypeScript types: `types.schema.json` → `src/types.schema.ts` (via `json2ts`)
-- Format (`prettier`/`eslint`) and build the package
-
-2. `@markuplint/ml-spec` (this package)
-
-- Run `gen/gen.ts` to output `schemas/global-attributes.schema.json` and `schemas/attributes.schema.json`
-- Generate TypeScript types from schemas:
-  - `schemas/content-models.schema.json` → `src/types/permitted-structures.ts`
-  - `schemas/attributes.schema.json` → `src/types/attributes.ts`
-  - `schemas/aria.schema.json` → `src/types/aria.ts`
-- Format (`prettier`/`eslint`)
-
-Dependency note: `schemas/attributes.schema.json` references
-`@markuplint/types/types.schema.json#/definitions/type`. Updating types first ensures references stay
-consistent; `yarn up:schema` takes care of this order.
-
-3. Build (optional) and sanity-check
-
-```bash
-yarn build
-```
-
-### Do not edit generated files
-
-- Do not modify files under `src/types/*.ts` or `schemas/attributes.schema.json` directly.
-  Change the source schema or generator instead and re-run the generation scripts.
-
-### How schema merging works (Specs extension)
-
-At runtime, markuplint can merge multiple specs. The merger in
-`src/utils/schema-to-spec.ts` follows these rules:
-
-- `def.#globalAttrs.#extends` from an extended spec augments the base `#HTMLGlobalAttrs` map.
-- For a given element, if both base and extended specs define the same attribute, the extended spec
-  wins on conflicting fields (shallow override per attribute). Arrays like `categories` are merged.
-
-This enables framework-specific specs (Vue/React/Svelte, etc.) to extend the HTML spec safely.
-
-### Relationship to @markuplint/types
-
-- Attribute value types (CSS keywords, extended types such as `URL`, `JSON`, etc.) are defined in
-  `@markuplint/types` and exposed via `types.schema.json`.
-- If you need a new attribute value type, modify `@markuplint/types` (e.g.
-  `packages/@markuplint/types/gen/specific-schema.json`) and regenerate that package first. Then
-  regenerate this package so references stay consistent.
-
-### Versioning policy
-
-- HTML Schema/Specs are not part of the public API surface of markuplint. Changes here are treated
-  as a minor release. Publishing is handled by Lerna during the normal release process.
-
-### Common tasks (quick recipes)
-
-- Add a new global attribute category or items
-  - Edit `gen/global-attribute.data.*`
-  - Run the generation script (see above)
-
-- Add a new optional field to `AttributeJSON`
-  - Update the shape in `gen/gen.ts` under `AttributeJSON`
-  - Regenerate and ensure the new field appears in `schemas/attributes.schema.json` and in
-    `src/types/attributes.ts`
-
-- Adjust ARIA fields (e.g., `permittedRoles` variants)
-  - Edit `schemas/aria.schema.json`
-  - Regenerate types via the schema scripts
-
-### Content model quick reference
-
-Content models describe allowed children for each element. See the JSON Schema
-`schemas/content-models.schema.json` and the generated TS types `src/types/permitted-structures.ts`.
-Also refer to the website docs: [Rule: permitted-contents](https://markuplint.dev/rules/permitted-contents).
-
-- Basic categories (strings): `"#flow"`, `"#phrasing"`, `"#interactive"`, …
-- Model item forms:
-  - `require` | `optional` | `oneOrMore` | `zeroOrMore`: a string, category, or nested patterns
-  - `choice`: 2–5 alternative pattern arrays
-  - `transparent`: inherits parent model filtered by selector string
-
-Examples:
-
-```json
-{
-  "contentModel": {
-    "contents": [{ "require": "#phrasing" }, { "optional": [{ "oneOrMore": "#interactive" }] }]
-  }
-}
-```
-
-Transparent selector syntax
-
-- A CSS-like selector string with an extra pseudo: `:model(<CATEGORY>)`
-- You can combine standard selectors: type, class, id, attribute selectors, `:not(...)`, `:has(...)`,
-  combinators, etc.
-- `:model(<CATEGORY>)` matches any element belonging to the specified content category.
-
-Examples:
-
-```text
-:not(:model(interactive))
-:has(:model(interactive), a, [tabindex])
-```
-
-SVG categories
-
-The following categories are available for SVG elements (see `schemas/content-models.schema.json`):
-
-- `#SVGAnimation`
-- `#SVGBasicShapes`
-- `#SVGContainer`
-- `#SVGDescriptive`
-- `#SVGFilterPrimitive`
-- `#SVGFont`
-- `#SVGGradient`
-- `#SVGGraphics`
-- `#SVGGraphicsReferencing`
-- `#SVGLightSource`
-- `#SVGNeverRendered`
-- `#SVGNone`
-- `#SVGPaintServer`
-- `#SVGRenderable`
-- `#SVGShape`
-- `#SVGStructural`
-- `#SVGStructurallyExternal`
-- `#SVGTextContent`
-- `#SVGTextContentChild`
-
-```json
-{
-  "contentModel": {
-    "contents": [{ "choice": [[{ "oneOrMore": "#flow" }], [{ "require": "#phrasing" }]] }]
-  }
-}
-```
-
-```json
-{
-  "contentModel": {
-    "contents": [{ "transparent": ":not(:model(interactive))" }],
-    "conditional": [
-      {
-        "condition": "[type=button]",
-        "contents": [{ "require": "#phrasing" }]
-      }
-    ]
-  }
-}
-```
+For content model categories and pattern format, see [HTML Algorithms](docs/html-algorithms.md).
 
 ### License
 

package/SKILL.md

@@ -0,0 +1,116 @@
+---
+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).