@markuplint/types 4.8.0 → 4.8.2

package/docs/check-pipeline.md

@@ -0,0 +1,494 @@
+# Check Pipeline
+
+## Overview
+
+The `@markuplint/types` package provides a type validation pipeline for HTML attribute values. Given a string value and a type definition, the pipeline determines whether the value conforms to the expected type, returning either a successful match or a detailed mismatch report with location information, reason codes, and suggested corrections.
+
+The pipeline supports five categories of type definitions:
+
+| Category      | Description                                        | Example                                   |
+| ------------- | -------------------------------------------------- | ----------------------------------------- |
+| **Keyword**   | Named types resolved via a definitions registry    | `"URL"`, `"<color>"`, `"BCP47"`           |
+| **List**      | Space-separated or comma-separated token sequences | `{ separator: "comma", token: "URL" }`    |
+| **Enum**      | Fixed set of allowed string values                 | `{ enum: ["auto", "lazy", "eager"] }`     |
+| **Number**    | Integer or float with optional range constraints   | `{ type: "integer", gte: 0 }`             |
+| **Directive** | Prefix-pattern followed by a token value           | `{ directive: ["/path/"], token: "URL" }` |
+
+## Entry Point: `check()`
+
+**Source:** `src/check.ts`
+
+The `check()` function is the primary entry point for all type validation in the package. It accepts a string value and a type definition, then delegates to the core dispatcher with the combined HTML and CSS definition registries.
+
+```typescript
+// src/check.ts
+export function check(value: string, type: ReadonlyDeep<Type>, ref?: string, cache = true): Result {
+  return checkBase(value, type, { ...defs, ...cssDefs }, ref, cache);
+}
+```
+
+**Parameters:**
+
+| Parameter | Type      | Description                                     |
+| --------- | --------- | ----------------------------------------------- |
+| `value`   | `string`  | The attribute value to validate                 |
+| `type`    | `Type`    | The type definition to validate against         |
+| `ref`     | `string?` | Optional reference URL for error context        |
+| `cache`   | `boolean` | Whether to use cached results (default: `true`) |
+
+**Return value:** A `Result` type, which is a discriminated union:
+
+- `MatchedResult` -- `{ matched: true }`
+- `UnmatchedResult` -- `{ matched: false, raw, offset, length, line, column, reason, ref, ... }`
+
+## Dispatch Logic: `checkBase()`
+
+**Source:** `src/check-base.ts`
+
+The `checkBase()` function inspects the shape of the type definition and routes to the appropriate checker. The type discrimination uses a series of type guard functions:
+
+```typescript
+// src/check-base.ts
+export function checkBase(value: string, type: ReadonlyDeep<Type>, defs: Defs, ref?: string, cache = true): Result {
+  if (isKeyword(type)) return checkKeywordType(value, type, defs, cache);
+  if (isList(type)) return checkList(value, type, defs, ref, cache);
+  if (isEnum(type)) return checkEnum(value, type, ref);
+  if (isNumber(type)) return checkNumber(value, type, ref);
+  if (isDirective(type)) return checkDirective(value, type, defs, ref, cache);
+  throw new Error('Unknown type');
+}
+```
+
+### Type Guard Decision Table
+
+| Guard         | Condition                                            | Resulting Checker  |
+| ------------- | ---------------------------------------------------- | ------------------ |
+| `isKeyword`   | `typeof type === 'string'`                           | `checkKeywordType` |
+| `isList`      | object with `separator` property                     | `checkList`        |
+| `isEnum`      | object with `enum` property                          | `checkEnum`        |
+| `isNumber`    | object with `type` equal to `'float'` or `'integer'` | `checkNumber`      |
+| `isDirective` | object with `directive` property                     | `checkDirective`   |
+
+### Dispatch Flowchart
+
+```mermaid
+flowchart TD
+    A["checkBase(value, type, defs)"] --> B{typeof type === 'string'?}
+    B -->|Yes| C["checkKeywordType()"]
+    B -->|No| D{"'separator' in type?"}
+    D -->|Yes| E["checkList()"]
+    D -->|No| F{"'enum' in type?"}
+    F -->|Yes| G["checkEnum()"]
+    F -->|No| H{"type.type === 'float' | 'integer'?"}
+    H -->|Yes| I["checkNumber()"]
+    H -->|No| J{"'directive' in type?"}
+    J -->|Yes| K["checkDirective()"]
+    J -->|No| L["throw Error('Unknown type')"]
+```
+
+## Individual Checkers
+
+### `checkEnum()`
+
+**Source:** `src/enum.ts`
+
+Validates a value against a fixed set of allowed strings.
+
+```typescript
+// src/enum.ts
+export function checkEnum(value: string, type: ReadonlyDeep<Enum>, ref?: string): Result;
+```
+
+**Behavior:**
+
+1. By default, surrounding spaces are **disallowed** (`disallowToSurroundBySpaces` defaults to `true`). If allowed, the value is trimmed.
+2. By default, comparison is **case-insensitive** (`caseInsensitive` defaults to `true`). Both the value and enum entries are lowercased before comparison.
+3. If the value matches an entry, returns `matched()`.
+4. Otherwise, returns `unmatched()` with reason `'doesnt-exist-in-enum'` and the full list of expected values.
+
+**Example type definition:**
+
+```json
+{
+  "enum": ["auto", "lazy", "eager"],
+  "caseInsensitive": true
+}
+```
+
+### `checkList()`
+
+**Source:** `src/list.ts`
+
+Validates a value as a separated list of tokens, where each token is validated against a nested type definition.
+
+```typescript
+// src/list.ts
+export function checkList(value: string, type: ReadonlyDeep<List>, defs: Defs, ref?: string, cache = true): Result;
+```
+
+**Behavior:**
+
+1. Parses the value into a `TokenCollection` based on the list's `separator` (`'space'` or `'comma'`).
+2. Performs structural checks on the token collection (token count, uniqueness, ordering).
+3. Extracts identifier tokens and validates each one by recursively calling `checkBase()` with the list's `token` type.
+4. On per-token failure, adjusts the error offset/line/column using `Token.shiftLocation()` to point to the exact failing token.
+
+**List type properties:**
+
+| Property                     | Type                   | Description                             |
+| ---------------------------- | ---------------------- | --------------------------------------- |
+| `separator`                  | `'space' \| 'comma'`   | Token separator                         |
+| `token`                      | `ExtendedType \| Enum` | Type definition for each token          |
+| `allowEmpty`                 | `boolean?`             | Whether an empty value is valid         |
+| `ordered`                    | `boolean?`             | Whether token order matters             |
+| `unique`                     | `boolean?`             | Whether duplicate tokens are disallowed |
+| `number`                     | `string \| object?`    | Constraints on the number of tokens     |
+| `caseInsensitive`            | `boolean?`             | Case sensitivity for token comparison   |
+| `disallowToSurroundBySpaces` | `boolean?`             | Whether outer spaces are allowed        |
+
+### `checkNumber()`
+
+**Source:** `src/number.ts`
+
+Validates a value as a numeric type with optional range constraints.
+
+```typescript
+// src/number.ts
+export function checkNumber(value: string, type: Readonly<TypeNumber>, ref?: string): Result;
+```
+
+**Behavior:**
+
+1. Returns `unmatched` with `'empty-token'` if the value is empty.
+2. Tests the value's format using `isFloat()` or `isInt()` based on `type.type`.
+3. If the format matches, parses the number and checks range constraints:
+   - `gt` -- value must be strictly greater than
+   - `gte` -- value must be greater than or equal to
+   - `lt` -- value must be strictly less than
+   - `lte` -- value must be less than or equal to
+4. When `clampable` is `true` and a range violation occurs, suggests the nearest boundary value as a `candidate`.
+
+**Range check flow:**
+
+```mermaid
+flowchart TD
+    A["checkNumber(value, type)"] --> B{value is empty?}
+    B -->|Yes| C["unmatched: 'empty-token'"]
+    B -->|No| D{matches format?}
+    D -->|No| E["unmatched: 'unexpected-token'"]
+    D -->|Yes| F["Parse as number"]
+    F --> G{Check gt constraint}
+    G -->|Fail| H["unmatched: 'out-of-range'"]
+    G -->|Pass| I{Check gte constraint}
+    I -->|Fail| H
+    I -->|Pass| J{Check lt constraint}
+    J -->|Fail| H
+    J -->|Pass| K{Check lte constraint}
+    K -->|Fail| H
+    K -->|Pass| L["matched()"]
+```
+
+### `checkDirective()`
+
+**Source:** `src/directive.ts`
+
+Validates a value that consists of a prefix pattern (directive) followed by a token portion. Directives are used for attribute values where a known prefix leads into a typed value (for example, an interpolation syntax or a URL scheme prefix).
+
+```typescript
+// src/directive.ts
+export function checkDirective(
+  value: string,
+  type: ReadonlyDeep<Directive>,
+  defs: Defs,
+  ref?: string,
+  cache = true,
+): Result;
+```
+
+**Behavior:**
+
+1. Iterates through each directive pattern in `type.directive`.
+2. Each pattern can be either a **plain string** prefix or a **regex** (parsed by `regexParser()`).
+   - For regex patterns: executes against the value, extracting the token from a named group `token` or capture group `[1]`.
+   - For string patterns: checks if the value starts with the directive, then slices off the prefix.
+3. The extracted token portion is validated via `checkBase()` with `type.token`.
+4. Returns the first successful match, or the first unmatched result if all directives fail.
+
+### `checkKeywordType()`
+
+**Source:** `src/keyword-type.ts`
+
+Resolves a keyword type name through the definitions registry and validates the value accordingly. This is the gateway to both custom programmatic validators and CSS syntax matching.
+
+```typescript
+// src/keyword-type.ts
+export function checkKeywordType(value: string, type: KeywordDefinedType, defs: Defs, cache = true): Result;
+```
+
+**Behavior:**
+
+1. **Cache lookup:** If caching is enabled, checks for a previously computed result using the key `value + type`.
+2. **Definition lookup:** Searches for `type` in the `defs` registry.
+3. **If the type is not found in `defs`:** Falls back to `cssSyntaxMatch(value, type)`. If CSS syntax matching throws `MARKUPLINT_TYPE_NO_EXIST`, the value is permissively accepted (returns `matched()`).
+4. **If the type is found:** Determines whether the definition is a CSS syntax definition or a custom syntax definition:
+   - **CSS syntax** (`isCSSSyntax`): Delegates to `cssSyntaxMatch()`.
+   - **Custom syntax** (`isCustomSyntax`): Calls the definition's `is(value)` function.
+5. On mismatch, enriches the result with the definition's `ref` and `expects` if not already set.
+
+```mermaid
+flowchart TD
+    A["checkKeywordType(value, type, defs)"] --> B{Cached?}
+    B -->|Yes| C["Return cached result"]
+    B -->|No| D{type in defs?}
+    D -->|No| E["cssSyntaxMatch(value, type)"]
+    E --> F{MARKUPLINT_TYPE_NO_EXIST?}
+    F -->|Yes| G["matched()"]
+    F -->|No| H["Return CSS result"]
+    D -->|Yes| I{isCSSSyntax(def)?}
+    I -->|Yes| J["cssSyntaxMatch(value, def)"]
+    I -->|No| K["def.is(value)"]
+    J --> L{matched?}
+    K --> L
+    L -->|Yes| M["Return matched"]
+    L -->|No| N["Enrich with ref/expects, return unmatched"]
+```
+
+## CSS Syntax Matching
+
+**Source:** `src/css-syntax.ts`
+
+The `cssSyntaxMatch()` function validates values against CSS value definition syntax using the [css-tree](https://github.com/csstree/csstree) library.
+
+```typescript
+// src/css-syntax.ts
+export function cssSyntaxMatch(value: string, type: CssSyntax | CustomCssSyntax): Result;
+```
+
+### How It Works
+
+1. **Configuration:** Depending on whether `type` is a plain string or a `CustomCssSyntax` object:
+   - **String:** Used directly as a CSS type or property name (e.g., `"<color>"`).
+   - **Object:** Extracts `syntax.apply` as the definition name, `syntax.def` for extended types and custom tokenizers, and `syntax.properties` for CSS property extensions.
+
+2. **Lexer creation:** Creates a forked css-tree lexer with:
+   - **CSS overrides** (`css-overrides.ts`): Alternative syntax for transform functions and legacy SVG types.
+   - **Extended type definitions:** Merged from the custom syntax definition.
+   - **Custom tokenizers** (`css-tokenizers.ts`): Programmatic token-level matchers (e.g., BCP-47 language tags).
+
+3. **Name detection:** Determines whether the definition is a CSS property (e.g., `<'color'>`) or a CSS type (e.g., `<color>`) and sets up the appropriate matcher.
+
+4. **Case sensitivity:** When `caseSensitive` is `true`, uppercase letters are wrapped in mimic tags to preserve case during css-tree matching (which is normally case-insensitive).
+
+5. **Matching:** Calls `lexer.match(defName, value)`. If no error, returns `matched()`. If a `var()` function is encountered, returns `matched()` (known css-tree limitation).
+
+6. **Error handling:** On mismatch, extracts position information from the `SyntaxMatchError` and returns an `UnmatchedResult` with the CSS syntax expectation.
+
+### CSS Overrides
+
+**Source:** `src/css-overrides.ts`
+
+Provides alternative syntax definitions for CSS transform functions to support SVG attribute validation:
+
+```typescript
+export const cssOverrides: Record<string, string> = {
+  'legacy-length-percentage': '<length> | <percentage> | <svg-length>',
+  'legacy-angle': '<angle> | <zero> | <number>',
+  'translate()': 'translate( <legacy-length-percentage> , ... )',
+  'scale()': 'scale( [ <number> | <percentage> ]#{1,2} )',
+  'rotate()': 'rotate( <legacy-angle> )',
+  'skew()': 'skew( <legacy-angle> , <legacy-angle>? ) | ...',
+};
+```
+
+### Custom Tokenizers
+
+**Source:** `src/css-tokenizers.ts`
+
+Provides token-level matchers for types that require custom parsing:
+
+```typescript
+export const cssTokenizers: Record<string, CssSyntaxTokenizer> = {
+  'bcp-47'(token) {
+    if (!token) return 0;
+    return isBCP47()(token.value) ? 1 : 0;
+  },
+};
+```
+
+## Multi-Type Checking
+
+**Source:** `src/check-multi-types.ts`
+
+The `checkMultiTypes()` function tries multiple type checker functions against a single value, returning the first match or the best failure.
+
+```typescript
+// src/check-multi-types.ts
+export function checkMultiTypes(value: string, checks: readonly CustomSyntaxCheck[]): Result;
+```
+
+**Behavior:**
+
+1. Iterates through each check function in order.
+2. If a check returns `matched`, immediately returns that result.
+3. If no check matches, selects the "best" unmatched result using the following heuristic:
+   - Prefers the result with the higher `passCount` (more sub-checks passed before failing).
+   - On equal `passCount`, prefers the result with the greater `offset` (the failure occurred later in the value string).
+4. If no checks were provided, returns `matched()` as a fallback.
+
+```mermaid
+flowchart TD
+    A["checkMultiTypes(value, checks)"] --> B["For each check function"]
+    B --> C["result = check(value)"]
+    C --> D{result.matched?}
+    D -->|Yes| E["Return matched result"]
+    D -->|No| F{passCount > best?}
+    F -->|Yes| G["Update best unmatched"]
+    F -->|No| H{passCount == best AND offset >= best?}
+    H -->|Yes| G
+    H -->|No| I["Keep current best"]
+    G --> B
+    I --> B
+    B -->|All done| J["Return best unmatched or matched()"]
+```
+
+**Usage example** (from `defs.ts`, `ItemProp` type):
+
+```typescript
+is(value) {
+  return checkMultiTypes(value, [
+    value => (isAbsURL()(value) ? matched() : unmatched(value, 'unexpected-token')),
+    value => (isItempropName()(value) ? matched() : unmatched(value, 'unexpected-token')),
+  ]);
+}
+```
+
+## Candidate Suggestion
+
+**Source:** `src/get-candidate.ts`
+
+The `getCandidate()` function finds the closest matching string from a set of candidates using [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) (via the `leven` library).
+
+```typescript
+// src/get-candidate.ts
+export function getCandidate(
+  value: NullableString,
+  ...candidates: readonly (NullableString | readonly NullableString[])[]
+): string | undefined;
+```
+
+**Algorithm:**
+
+1. Flattens the candidate arrays (up to 2 levels deep) and filters out null/undefined entries.
+2. For each candidate, computes the similarity ratio: `ratio = 1 - levenshtein(value, candidate) / candidate.length`.
+3. Both value and candidate are lowercased and trimmed before comparison.
+4. **Threshold:** Only candidates with `ratio >= 0.5` (at least 50% similar) are considered.
+5. Returns the candidate with the highest ratio, or `undefined` if none meets the threshold.
+6. If the value exactly matches a candidate, returns `undefined` (no suggestion needed).
+
+**Usage context:** `getCandidate()` is called in specific type validators (e.g., `NavigableTargetNameOrKeyword`) to suggest corrections for typos in attribute values (e.g., a misspelled `_blank`).
+
+## Complete Flow Diagram
+
+The following diagram shows the full pipeline from entry point to result:
+
+```mermaid
+flowchart TD
+    START["check(value, type)"] --> MERGE["Merge defs + cssDefs"]
+    MERGE --> BASE["checkBase(value, type, defs)"]
+
+    BASE --> KW{Keyword?}
+    KW -->|Yes| CKT["checkKeywordType()"]
+    KW -->|No| LS{List?}
+    LS -->|Yes| CL["checkList()"]
+    LS -->|No| EN{Enum?}
+    EN -->|Yes| CE["checkEnum()"]
+    EN -->|No| NM{Number?}
+    NM -->|Yes| CN["checkNumber()"]
+    NM -->|No| DR{Directive?}
+    DR -->|Yes| CD["checkDirective()"]
+    DR -->|No| ERR["throw Error"]
+
+    CKT --> LOOKUP{Found in defs?}
+    LOOKUP -->|No| CSS1["cssSyntaxMatch()"]
+    LOOKUP -->|Yes| DEFTYPE{isCSSSyntax?}
+    DEFTYPE -->|Yes| CSS2["cssSyntaxMatch()"]
+    DEFTYPE -->|No| CUSTOM["def.is(value)"]
+
+    CSS1 --> CSSTREE["css-tree lexer.match()"]
+    CSS2 --> CSSTREE
+
+    CL --> PARSE["TokenCollection(value, type)"]
+    PARSE --> STRUCT["Structural check"]
+    STRUCT -->|Fail| UNMATCH1["UnmatchedResult"]
+    STRUCT -->|Pass| TOKENS["For each ident token"]
+    TOKENS --> RECURSE["checkBase(token, type.token, defs)"]
+    RECURSE -->|Fail| UNMATCH2["UnmatchedResult with shifted location"]
+    RECURSE -->|Pass| MATCH1["matched()"]
+
+    CE --> COMPARE["Compare against enum values"]
+    COMPARE -->|Match| MATCH2["matched()"]
+    COMPARE -->|No match| UNMATCH3["unmatched: 'doesnt-exist-in-enum'"]
+
+    CN --> FORMAT{Format ok?}
+    FORMAT -->|No| UNMATCH4["unmatched: 'unexpected-token'"]
+    FORMAT -->|Yes| RANGE{Range ok?}
+    RANGE -->|No| UNMATCH5["unmatched: 'out-of-range'"]
+    RANGE -->|Yes| MATCH3["matched()"]
+
+    CD --> DIRS["For each directive pattern"]
+    DIRS --> EXTRACT["Extract token portion"]
+    EXTRACT --> RECURSE2["checkBase(tokenPart, type.token, defs)"]
+    RECURSE2 -->|Match| MATCH4["matched()"]
+    RECURSE2 -->|No match| NEXT["Try next directive"]
+
+    CUSTOM --> RESULT["Result"]
+    CSSTREE --> RESULT
+    MATCH1 --> RESULT
+    MATCH2 --> RESULT
+    MATCH3 --> RESULT
+    MATCH4 --> RESULT
+    UNMATCH1 --> RESULT
+    UNMATCH2 --> RESULT
+    UNMATCH3 --> RESULT
+    UNMATCH4 --> RESULT
+    UNMATCH5 --> RESULT
+```
+
+## Type Definitions Registry
+
+**Source:** `src/defs.ts`, `src/css-defs.ts`
+
+The definitions registry (`Defs`) is a map from type name strings to either `CustomSyntax` or `CustomCssSyntax` objects. There are two registries that are merged at the entry point:
+
+| Registry  | Source            | Contents                                                                                                          |
+| --------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `defs`    | `src/defs.ts`     | HTML attribute types: `Any`, `URL`, `Number`, `DOMID`, `DateTime`, `BCP47`, `MIMEType`, `CustomElementName`, etc. |
+| `cssDefs` | `src/css-defs.ts` | CSS/SVG types: `<css-declaration-list>`, `<view-box>`, `<preserve-aspect-ratio>`, `<dasharray>`, etc.             |
+
+Each definition is one of two forms:
+
+**Custom syntax** (programmatic checker):
+
+```typescript
+{
+  ref: 'https://...',
+  expects: [{ type: 'format', value: 'date time' }],
+  is: (value: string) => Result
+}
+```
+
+**CSS syntax** (css-tree grammar):
+
+```typescript
+{
+  ref: 'https://...',
+  syntax: {
+    apply: '<view-box>',
+    def: {
+      'view-box': '<min-x> [,]? <min-y> [,]? <width> [,]? <height>',
+      'min-x': '<number>',
+      // ...
+    }
+  }
+}
+```