Repository navigation
Description
Problem
The linter has 120 finding codes, but there is no reference page for them. 70 of the codes are not mentioned anywhere in docs/ or skills/ (for example self_closing_media_tag, gsap_timeline_not_registered, caption_transcript_not_inline, media_missing_src). When hyperframes lint or check prints one, the user has only the message itself to go on.
docs/packages/lint.mdx has a short "What the Linter Catches" section, but it describes categories, not individual codes.
Proposed solution
Add a lint rule reference page (for example docs/reference/lint-rules.mdx) and link it from docs/packages/lint.mdx and the navigation in docs/docs.json.
For each code: severity, one sentence on what it catches, and how to fix it. Group them by the rule file they come from (packages/lint/src/rules/*.ts), since that already groups them by topic (captions, media, gsap, composition, fonts, textures, slideshow, structure, core, adapters, linked clips).
To list every code: git grep -hoE 'code: "[a-z_]+"' -- packages/lint/src/rules | sort -u
Acceptance criteria
- Every code in
packages/lint/src/rules/*.ts(excluding tests) appears on the page with its severity and a fix. - The page is reachable from the docs navigation and from
docs/packages/lint.mdx. - The docs checks pass:
npx mint validateandnpx mint broken-linksfromdocs/(what.github/workflows/docs.ymlruns).
It's fine to split this into several PRs by rule file. Please say which files you're taking in a comment so two people don't write the same section.
Activity
akushonkamen commentedon Oct 12, 2026
Taking this one. I confirmed the gap: all finding codes live in
packages/lint/src/rules/*.ts(code: ...literals), whiledocs/packages/lint.mdxonly describes categories and there is no per-code reference underdocs/reference/.Plan: add
docs/reference/lint-rules.mdxcovering every code (all rule files in one pass) with severity, one-line meaning, and a fix, grouped by rule file; link it fromdocs/packages/lint.mdxand add it todocs/docs.json. Will verify withnpx mint validate+npx mint broken-links.Disclosure: this contribution is prepared with AI assistance (coding agent), reviewed and submitted by me.
akushonkamen commentedon Oct 12, 2026
PR is up: #5493 —
docs/reference/lint-rules.mdxcovers every code (121 rule codes + 11 project-level, all with severity, meaning and a fix), linked fromdocs/packages/lint.mdxand the docs nav.mint validateandmint broken-links --check-redirectspass.docs(lint): add a reference page for every lint finding code (#5493)