Skip to content

docs: add a reference page for every lint finding code #5385

Closed

Description

@jrusso1020

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 validate and npx mint broken-links from docs/ (what .github/workflows/docs.yml runs).

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

  1. added
    difficulty/mediumBounded work requiring subsystem knowledge, related paths, or additional regression fixtures.
    documentationImprovements or additions to documentation
    help wantedReady, available work with maintainer review support; any difficulty.
    triage/readyAccepted scope, current evidence, acceptance criteria, and validation path are recorded.
    on Oct 10, 2026
  2. akushonkamen commented on Oct 12, 2026

    @akushonkamen
    Contributor

    Taking this one. I confirmed the gap: all finding codes live in packages/lint/src/rules/*.ts (code: ... literals), while docs/packages/lint.mdx only describes categories and there is no per-code reference under docs/reference/.

    Plan: add docs/reference/lint-rules.mdx covering every code (all rule files in one pass) with severity, one-line meaning, and a fix, grouped by rule file; link it from docs/packages/lint.mdx and add it to docs/docs.json. Will verify with npx mint validate + npx mint broken-links.

    Disclosure: this contribution is prepared with AI assistance (coding agent), reviewed and submitted by me.

  3. akushonkamen commented on Oct 12, 2026

    @akushonkamen
    Contributor

    PR is up: #5493 — docs/reference/lint-rules.mdx covers every code (121 rule codes + 11 project-level, all with severity, meaning and a fix), linked from docs/packages/lint.mdx and the docs nav. mint validate and mint broken-links --check-redirects pass.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    difficulty/mediumBounded work requiring subsystem knowledge, related paths, or additional regression fixtures.documentationImprovements or additions to documentationhelp wantedReady, available work with maintainer review support; any difficulty.triage/readyAccepted scope, current evidence, acceptance criteria, and validation path are recorded.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions