framework-parsers

Files (1)

• SKILL.md

SKILL.md (first lines)

# framework-parsers

Create and maintain framework parser and spec packages for markuplint.

## Architecture

The parser hierarchy, extension points, and design rationale are documented in the `Parser` class JSDoc in `packages/@markuplint/parser-utils/src/parser.ts`. Read it before extending. For concrete patterns, read an existing sibling package (template engine: `ejs-parser`; full framework: `astro-parser`; spec: `react-spec`) — new packages follow the sibling's structure.

## Package types and naming

- `@markuplint/<lang>-parser` — parser package. Two kinds:
  - **Template engine parsers** extend `HtmlParser` and configure only `ignoreTags`.
  - **Full framework parsers** extend `Parser` and implement `tokenize()`, `nodeize()`, `visitAttr()`, `detectElementType()`, delegating tokenization to the framework's own parser library.
- `@markuplint/<lang>-spec` — spec package exporting an `ExtendedSpec` object (global attributes + per-element overrides).

## Rules (constraints — violations break the build or runtime contracts)

1. **Template parsers must only configure `ignoreTags`** — never override `tokenize()` or `nodeize()`.
2. **Full parsers must delegate tokenization to an external parser library** — never implement framework parsing from scratch.
3. **Spec packages must only export an `ExtendedSpec` object** — no parsing logic.
4. **Use `potentialName` for attribute mapping** — it tells markuplint which standard HTML attribute a framework attribute corresponds to.
5. **Test with `nodeListToDebugMaps`** — the standard assertion pattern across all parsers.
6. **Parsers for formats that define components in the template file (vue, svelte, astro) must ship a `component-scanner` subpath export** (`"./component-scanner"` in `package.json` `exports`) — `@markuplint/pretenders` dynamically imports it at runtime for auto scan. Without it, the framework's components are not detected. `jsx-parser` and `pug-parser` ship none: their components are not declared in the template file.
7. **Never import from `@markuplint/pretenders` inside component-scanner** — define local types structurally compatible with its `ComponentScanner` interface. Importing pretenders creates a circular dependency in the lerna build graph.

From markuplint/markuplint, MIT.

More from markuplint/markuplint