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

package/docs/spec-resolution.md

@@ -1,588 +0,0 @@
-# Spec Resolution Pipeline
-
-This document describes how `@markuplint/ml-spec` merges a base HTML specification with framework-specific extensions, resolves element and attribute lookups, handles ARIA versioning, and manages caching throughout the pipeline.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Schema Merging (`schemaToSpec`)](#schema-merging-schematospec)
-- [Element Spec Lookup](#element-spec-lookup)
-- [Namespace Resolution](#namespace-resolution)
-- [Attribute Spec Resolution](#attribute-spec-resolution)
-- [ARIA Version Resolution](#aria-version-resolution)
-- [Array Merging (`mergeArray`)](#array-merging-mergearray)
-- [Caching Strategy](#caching-strategy)
-
----
-
-## Overview
-
-The spec resolution pipeline is the mechanism by which markuplint constructs a
-single, unified specification from multiple sources. The overall flow is:
-
-```
-@markuplint/html-spec (MLMLSpec)
-      +
-framework specs (ExtendedSpec[])    e.g., vue-spec, react-spec, svelte-spec
-      |
-      v
-  schemaToSpec()
-      |
-      v
-  merged MLMLSpec  (used by all downstream algorithms)
-```
-
-A user's configuration file may reference one or more framework plugins. Each
-plugin provides an `ExtendedSpec` that adds, overrides, or extends the base
-HTML specification with framework-specific elements, attributes, ARIA
-definitions, and content model categories.
-
-All downstream APIs -- element lookup, attribute resolution, ARIA queries,
-content model checks -- operate on the merged `MLMLSpec` returned by
-`schemaToSpec`. This design means that resolution logic does not need to know
-whether a particular definition came from the base spec or an extension.
-
-### Key Types
-
-| Type           | Role                                                                                                 |
-| -------------- | ---------------------------------------------------------------------------------------------------- |
-| `MLMLSpec`     | The full specification object: cites, defs (globalAttrs, aria, contentModels), and per-element specs |
-| `ExtendedSpec` | A partial overlay that may contribute to any section of `MLMLSpec`                                   |
-| `ElementSpec`  | Per-element definition: name, categories, attributes, globalAttrs, aria, contentModel                |
-| `Attribute`    | Single attribute definition: name, type, description, and other metadata                             |
-
----
-
-## Schema Merging (`schemaToSpec`)
-
-**File:** `src/utils/schema-to-spec.ts`
-
-```ts
-function schemaToSpec(schemas: readonly [MLMLSpec, ...ExtendedSpec[]]): MLMLSpec;
-```
-
-The function takes a tuple whose first element is always the base `MLMLSpec`
-(typically `@markuplint/html-spec`) and whose remaining elements are zero or
-more `ExtendedSpec` objects. It returns a new `MLMLSpec` containing the merged
-result.
-
-### Step-by-Step Merge Process
-
-The merge is performed iteratively. Each `ExtendedSpec` in order is folded into
-the accumulating result:
-
-```ts
-const [main, ...extendedSpecs] = schemas;
-const result = { ...main };
-
-for (const extendedSpec of extendedSpecs) {
-  // merge each section...
-}
-```
-
-#### 1. Cites
-
-If the extended spec provides `cites`, they are concatenated onto the existing
-array:
-
-```ts
-result.cites = [...result.cites, ...extendedSpec.cites];
-```
-
-This is simple array concatenation -- no deduplication is performed because
-citation sources are expected to be distinct across specs.
-
-#### 2. Global Attributes
-
-The extended spec's `#extends` property is spread into the base spec's
-`#HTMLGlobalAttrs` category:
-
-```ts
-gAttrs['#HTMLGlobalAttrs'] = {
-  ...def['#globalAttrs']?.['#HTMLGlobalAttrs'],
-  ...extendedSpec.def['#globalAttrs']?.['#extends'],
-};
-```
-
-This means a framework can introduce new global attributes (e.g., Vue's `v-if`,
-`v-for`) and they become part of `#HTMLGlobalAttrs` for all elements that
-reference that category. Existing attributes with the same key are overridden by
-the extension.
-
-#### 3. ARIA Definitions
-
-For each ARIA version (`1.1`, `1.2`, `1.3`), the four arrays -- `roles`,
-`props`, `graphicsRoles`, and `dpubRoles` -- are merged using `mergeArray`:
-
-```ts
-def['#aria'] = {
-  '1.1': {
-    roles: mergeArray(def['#aria']['1.1'].roles, extendedSpec.def['#aria']['1.1'].roles),
-    props: mergeArray(def['#aria']['1.1'].props, extendedSpec.def['#aria']['1.1'].props),
-    graphicsRoles: mergeArray(def['#aria']['1.1'].graphicsRoles, extendedSpec.def['#aria']['1.1'].graphicsRoles),
-    dpubRoles: mergeArray(def['#aria']['1.1'].dpubRoles, extendedSpec.def['#aria']['1.1'].dpubRoles),
-  },
-  // same for 1.2 and 1.3
-};
-```
-
-`mergeArray` uses name-based matching (see [Array Merging](#array-merging-mergearray)),
-so an extension can both add new ARIA roles/properties and override existing
-definitions.
-
-#### 4. Content Models
-
-All content model categories are unioned. For each category key across both the
-base and extension, the selector arrays are concatenated:
-
-```ts
-const keys = new Set([...Object.keys(def['#contentModels']), ...Object.keys(extendedSpec.def['#contentModels'])]);
-
-for (const modelName of keys) {
-  models[modelName] = [...(mainModel ?? []), ...(exModel ?? [])];
-}
-```
-
-This means a framework can add its custom elements to existing categories
-(e.g., adding `<router-link>` to `#phrasing`) or define entirely new
-categories.
-
-#### 5. Directive Patterns
-
-If the extended spec provides `directivePatterns`, they are concatenated onto the
-existing array:
-
-```ts
-result.directivePatterns = [...(result.directivePatterns ?? []), ...extendedSpec.directivePatterns];
-```
-
-This is simple array concatenation. The core engine evaluates patterns in order
-(first match wins), so framework specs should define their patterns from most
-specific to most general.
-
-#### 6. `acceptedAttrNames`
-
-If the extended spec explicitly sets `acceptedAttrNames`, it overrides the
-current value:
-
-```ts
-if (extendedSpec.acceptedAttrNames != null) {
-  result.acceptedAttrNames = extendedSpec.acceptedAttrNames;
-}
-```
-
-This is a last-write-wins semantic with explicit `null` guard -- omitting the
-property does not reset a previously set value. The value controls how
-`@markuplint/ml-core`'s `MLAttr` constructor resolves attribute names:
-
-- `'idl'` -- Enables IDL-to-content attribute name resolution (e.g.,
-  `className` -> `class`) and suggests IDL names as candidates when the
-  content attribute name is used (e.g., `tabindex` -> "Did you mean
-  `tabIndex`?"). Used by React, where only IDL property names are accepted.
-- `'both'` -- Enables IDL-to-content attribute name resolution but does
-  **not** suggest IDL names as candidates. Both content attribute names
-  (e.g., `class`) and IDL property names (e.g., `className`) are accepted
-  without warnings. Used by Svelte.
-
-#### 7. Element Specs
-
-Elements are matched by name (case-insensitive comparison). For each element in
-the base spec:
-
-- If no matching extension element exists, the base element is kept as-is.
-- If a match is found, the specs are merged:
-
-```ts
-specs.push({
-  ...elSpec, // base element spread
-  ...exSpec, // extension overrides top-level properties
-  globalAttrs: {
-    ...elSpec.globalAttrs,
-    ...exSpec?.globalAttrs,
-  },
-  attributes: mergeAttrSpec(elSpec.attributes, exSpec?.attributes),
-  categories: mergeArray(elSpec.categories, exSpec?.categories),
-});
-```
-
-The helper `mergeAttrSpec` unions all attribute keys and spreads the extension
-attribute onto the base attribute for each key, allowing partial overrides of
-individual attribute definitions.
-
----
-
-## Element Spec Lookup
-
-**Files:** `src/utils/get-spec.ts`, `src/utils/get-spec-by-tag-name.ts`
-
-The element lookup API has two layers:
-
-### DOM Wrapper: `getSpec`
-
-```ts
-function getSpec<K extends keyof ElementSpec>(
-  el: Element,
-  specs: readonly Pick<ElementSpec, 'name' | K>[],
-): Pick<ElementSpec, 'name' | K> | null;
-```
-
-A convenience wrapper that extracts `el.localName` and `el.namespaceURI` from a
-DOM `Element` and delegates to `getSpecByTagName`.
-
-### Core Lookup: `getSpecByTagName`
-
-```ts
-function getSpecByTagName<K extends keyof ElementSpec>(
-  specs: readonly Pick<ElementSpec, 'name' | K>[],
-  localName: string,
-  namespace: string | null,
-): Pick<ElementSpec, 'name' | K> | null;
-```
-
-Steps:
-
-1. Call `resolveNamespace(localName, namespace)` to get the namespace-qualified
-   name (e.g., `"svg:circle"` for an SVG circle element, or `"div"` for an HTML div).
-2. Check the module-level `Map<string, ElementSpec | null>` cache using the
-   qualified name as key.
-3. If not cached, perform a linear search through `specs` matching by `name`.
-4. Store the result (including `null` for miss) in the cache and return.
-
-The generic parameter `K` allows callers to request only specific keys from
-`ElementSpec`, reducing the amount of data carried through the type system while
-still preserving type safety.
-
----
-
-## Namespace Resolution
-
-**Files:** `src/utils/resolve-namespace.ts`, `src/utils/get-ns.ts`
-
-### `resolveNamespace`
-
-```ts
-function resolveNamespace(
-  name: string,
-  namespaceURI: string | null = 'http://www.w3.org/1999/xhtml',
-): NamespacedElementName;
-```
-
-Resolves an element name and optional namespace URI into a fully normalized
-form:
-
-```ts
-type NamespacedElementName = {
-  localNameWithNS: string; // e.g., "svg:circle" or "div"
-  localName: string; // e.g., "circle" or "div"
-  namespace: Namespace; // "html" | "svg" | "mml" | "xlink"
-  namespaceURI: NamespaceURI; // full URI string
-};
-```
-
-Resolution logic:
-
-1. **Split on colon** -- If `name` contains a colon (e.g., `"svg:circle"`), the
-   prefix is treated as an explicit namespace hint and the suffix as the local
-   name.
-2. **Determine namespace** -- The namespace is resolved from the explicit prefix
-   or by calling `getNS(namespaceURI)`. If neither yields a recognized
-   namespace, it defaults to `'html'`.
-3. **Build qualified name** -- For HTML namespace, the qualified name is just the
-   local name (no prefix). For all other namespaces, the shorthand is prepended:
-   `"svg:circle"`, `"mml:math"`, etc.
-4. **Cache** -- Results are cached in a `Map<string, NamespacedElementName>`
-   keyed by the concatenation `name + namespaceURI`.
-
-### Namespace URI Mapping
-
-| Namespace URI                        | Shorthand |
-| ------------------------------------ | --------- |
-| `http://www.w3.org/1999/xhtml`       | `html`    |
-| `http://www.w3.org/2000/svg`         | `svg`     |
-| `http://www.w3.org/1998/Math/MathML` | `mml`     |
-| `http://www.w3.org/1999/xlink`       | `xlink`   |
-
-### `getNS` Helper
-
-```ts
-function getNS(namespaceURI: string | null): Namespace;
-```
-
-A simple switch-case that maps a namespace URI string to its shorthand. Any
-unrecognized URI (including `null`) returns `'html'`.
-
----
-
-## Attribute Spec Resolution
-
-**Files:** `src/utils/get-attr-specs.ts` (DOM wrapper), `src/utils/get-attr-specs-spec.ts` (core)
-
-### DOM Wrapper: `getAttrSpecs` (from `get-attr-specs.ts`)
-
-```ts
-function getAttrSpecs(el: Element, schema: MLMLSpec): readonly Attribute[] | null;
-```
-
-Extracts `el.localName` and `el.namespaceURI`, then delegates to the core
-function.
-
-### Core Function: `getAttrSpecs` (from `get-attr-specs-spec.ts`)
-
-```ts
-function getAttrSpecs(localName: string, namespace: NamespaceURI | null, schema: MLMLSpec): readonly Attribute[] | null;
-```
-
-Resolution steps:
-
-1. **Schema invalidation** -- If the `schema` reference has changed (checked via
-   a `WeakSet<MLMLSpec>`), the entire attribute cache is cleared. This ensures
-   correctness when specs are re-merged.
-
-2. **Cache check** -- Look up the namespace-qualified name in
-   `Map<string, readonly Attribute[] | null>`.
-
-3. **Find element spec** -- Search `schema.specs` for a matching element by
-   namespace-qualified name. Return `null` (and cache it) if not found.
-
-4. **Collect global attributes** -- Iterate over the element's `globalAttrs`
-   selection map. For each category:
-   - `false` -- skip the category entirely
-   - `true` -- include all attributes from that global category
-   - `string[]` -- include only the named attributes from that category
-
-   ```ts
-   for (const catName in elSpec.globalAttrs) {
-     const catAttrs = elSpec.globalAttrs[catName];
-     if (catAttrs === false) continue;
-     if (typeof catAttrs === 'boolean') {
-       attrs = { ...attrs, ...global };
-     }
-     if (Array.isArray(catAttrs)) {
-       for (const selectedName of catAttrs) {
-         attrs[selectedName] = { ...attrs[selectedName], ...global[selectedName] };
-       }
-     }
-   }
-   ```
-
-5. **Merge element-specific attributes** -- The element's own `attributes` are
-   spread on top of the collected globals, so element-specific definitions
-   override globals:
-
-   ```ts
-   attrs[attrName] = {
-     description: '',
-     ...current, // from globals
-     ...attr, // from element spec
-   };
-   ```
-
-6. **Convert to sorted array** -- The attribute map is converted to an
-   `Attribute[]`, giving each entry a default `type: 'Any'` if none was
-   provided, then sorted alphabetically (case-insensitive) using `nameCompare`.
-
-7. **Cache and return** -- The sorted array is stored in the cache and returned.
-
-### `nameCompare`
-
-```ts
-function nameCompare(a: HasName | string, b: HasName | string): number;
-```
-
-Case-insensitive sort comparator. Extracts the `name` property (or uses the
-string directly), converts to uppercase, and performs standard lexicographic
-comparison.
-
----
-
-## ARIA Version Resolution
-
-**Files:** `src/utils/resolve-version.ts`, `src/utils/aria-version.ts`,
-`src/utils/validate-aria-version.ts`, `src/algorithm/aria/get-aria.ts`
-
-### `resolveVersion`
-
-```ts
-function resolveVersion(aria: ReadonlyDeep<ARIA>, version: ARIAVersion): Omit<ReadonlyDeep<ARIA>, ARIAVersion>;
-```
-
-Extracts a version-specific ARIA definition from a multi-version `ARIA` object.
-For each property, the version-specific value is used if present; otherwise the
-base (version-agnostic) value applies:
-
-```ts
-const implicitRole = aria[version]?.implicitRole ?? aria.implicitRole;
-const permittedRoles = aria[version]?.permittedRoles ?? aria.permittedRoles;
-// ...etc
-```
-
-Special case: `namingProhibited` for version `'1.1'` always uses the base
-value, because the naming prohibition concept was not formalized until ARIA 1.2:
-
-```ts
-const namingProhibited =
-  version === '1.1' ? aria.namingProhibited : (aria[version]?.namingProhibited ?? aria.namingProhibited);
-```
-
-The returned object contains only the resolved properties -- the version keys
-(`'1.1'`, `'1.2'`, `'1.3'`) are stripped from the type.
-
-### `getARIA`
-
-```ts
-function getARIA(
-  specs: MLMLSpec,
-  localName: string,
-  namespace: string | null,
-  version: ARIAVersion,
-  matches: Matches,
-): Omit<ReadonlyDeep<ARIA>, ARIAVersion | 'conditions'> | null;
-```
-
-The high-level ARIA resolver. It:
-
-1. Calls `getVersionResolvedARIA` (internal) to get the version-resolved spec.
-2. If the spec has `conditions` (CSS-selector-keyed overrides), iterates through
-   them and applies the first matching condition's properties. This handles
-   cases like `<input type="checkbox">` having different ARIA semantics than
-   `<input type="text">`.
-3. Optimizes `permittedRoles` -- if both `"presentation"` and `"none"` are in
-   the list, ensures both synonyms are present (per WAI-ARIA 1.2 note).
-
-The internal `getVersionResolvedARIA` function caches results in a
-`Map<string, ARIA | null>` keyed by `localName + namespace + version`.
-
-### Version Constants and Validation
-
-```ts
-// aria-version.ts
-const ariaVersions = ['1.1', '1.2', '1.3'] as const;
-const ARIA_RECOMMENDED_VERSION = '1.2';
-
-// validate-aria-version.ts
-function validateAriaVersion(version: string): version is ARIAVersion;
-```
-
-`validateAriaVersion` is a type guard that checks whether a string is a member
-of the `ariaVersions` tuple. It is used at configuration boundaries to validate
-user-supplied version strings before they enter the typed pipeline.
-
----
-
-## Array Merging (`mergeArray`)
-
-**File:** `src/utils/merge-array.ts`
-
-```ts
-function mergeArray<T extends NamedDefinition>(a: readonly T[], b: readonly T[] | null | undefined): readonly T[];
-```
-
-Where `NamedDefinition = string | { readonly name: string }`.
-
-This is the core merge utility used throughout the spec merging pipeline. It
-performs **name-based merging** rather than simple concatenation:
-
-### Algorithm
-
-1. If `b` is `null` or `undefined`, return `a` unchanged.
-2. Start with a copy of `a`.
-3. For each item in `b`:
-   - Extract the name using `getName()` (case-insensitive, trimmed).
-   - Search for an item with the same name in the result.
-   - **No match found:** append the extension item.
-   - **Match found (both are strings):** the string is a simple identifier with
-     no additional data, so the base item is kept (the splice removes it, then
-     the loop continues without pushing a replacement, effectively keeping the
-     base version).
-   - **Match found (base is string, extension is object):** replace with the
-     richer object form from the extension.
-   - **Match found (both are objects):** spread-merge the two objects, with the
-     extension's properties taking precedence:
-     ```ts
-     const exItem = { ...aItem, ...bItem };
-     ```
-
-### `getName` Helper
-
-```ts
-function getName(def: NamedDefinition): string {
-  const result = typeof def === 'string' ? def : def.name;
-  return result.toLowerCase().trim();
-}
-```
-
-Names are normalized to lowercase and trimmed before comparison, ensuring
-case-insensitive matching.
-
----
-
-## Caching Strategy
-
-The package uses multiple cache layers to avoid redundant computation. Since
-specs are typically loaded once and reused for the lifetime of a lint run, these
-caches provide significant performance benefits.
-
-### Cache Inventory
-
-| #   | Location                                        | Cache Type                                                        | Key                                                      | Value                                          | Invalidation                                              |
-| --- | ----------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
-| 1   | `getSpecByTagName`                              | `Map<string, any>`                                                | Namespace-qualified name (e.g., `"svg:circle"`)          | `ElementSpec \| null`                          | Module lifetime (never cleared)                           |
-| 2   | `getVersionResolvedARIA` (inside `get-aria.ts`) | `Map<string, ARIA \| null>`                                       | `localName + namespace + version` (string concatenation) | Version-resolved ARIA spec or null             | Module lifetime (never cleared)                           |
-| 3   | `getContentModel`                               | `WeakMap<Element, ...>`                                           | DOM Element reference                                    | `PermittedContentPattern[] \| boolean \| null` | Entries automatically removed when Element is GC'd        |
-| 4   | `contentModelCategoryToTagNames`                | `Map<Category, ReadonlyArray<string>>`                            | Category string (e.g., `"#flow"`)                        | Frozen sorted array of tag names               | Module lifetime (never cleared)                           |
-| 5   | `resolveNamespace`                              | `Map<string, NamespacedElementName>`                              | `name + namespaceURI` (string concatenation)             | Resolved namespace object                      | Module lifetime (never cleared)                           |
-| 6   | `getAttrSpecs` (in `get-attr-specs-spec.ts`)    | `Map<string, readonly Attribute[] \| null>` + `WeakSet<MLMLSpec>` | Namespace-qualified name                                 | Sorted attribute array or null                 | Cleared when schema reference changes (via WeakSet check) |
-
-### Cache Characteristics
-
-**No explicit eviction:** Most caches are module-level `Map` instances that
-persist for the entire process lifetime. This is appropriate because:
-
-- Spec data is immutable after merging.
-- The number of unique elements/attributes is bounded (HTML has ~120 elements).
-- A lint run typically processes one configuration.
-
-**Schema-aware invalidation:** The `getAttrSpecs` cache (item 6) is the
-exception. It uses a `WeakSet<MLMLSpec>` to detect when the schema reference
-changes. If a new schema is passed (e.g., when running different file patterns
-with different framework specs), the entire `cacheMap` is cleared before
-proceeding:
-
-```ts
-if (!schemaCache.has(schema)) {
-  cacheMap.clear();
-}
-```
-
-**WeakMap caching:** The `getContentModel` cache (item 3) uses a
-`WeakMap<Element, ...>` keyed by DOM Element reference. Re-querying the same
-element is O(1). When elements are garbage-collected (e.g., after a re-parse),
-their cache entries are automatically removed, preventing memory leaks.
-
-**Deterministic keys:** Caches in items 1, 2, and 5 use string concatenation
-for keys. Since `resolveNamespace` produces deterministic output for the same
-inputs, and spec data does not mutate, these concatenated keys are stable.
-
-### Data Flow with Caching
-
-```
-schemaToSpec()  -->  merged MLMLSpec (no cache; called once at startup)
-                          |
-              +-----------+-----------+
-              |           |           |
-     getSpecByTagName  getAttrSpecs  getARIA
-       (cache 1)       (cache 6)    (cache 2)
-              |                       |
-       resolveNamespace         resolveVersion
-         (cache 5)              (pure; no cache)
-                                      |
-                               getContentModel
-                                 (cache 3)
-                                      |
-                        contentModelCategoryToTagNames
-                                 (cache 4)
-```
-
-Each arrow represents a function call. Caches intercept repeated calls at each
-layer, so a second lookup for the same element hits cached results at every
-level of the call chain.