Repository navigation
docs(lint): add a reference page for every lint finding code - #5493
Conversation
docs/reference/lint-rules.mdx lists every code emitted by the linter (132: the 121 rule codes in packages/lint/src/rules/*.ts plus the 11 project-level probes that run as part of a project lint) with its severity, what it catches, and how to fix it, grouped by the rule file the code comes from. Conditional severities (Studio-host structure checks, GSAP seek-order hazards) say when they escalate. Link it from docs/packages/lint.mdx and add it to the Composition reference group in docs.json. Issue: heygen-com#5385
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Thanks for this, it's a big, useful page. I checked it against packages/lint/src. All 132 code: "..." literals are covered with no extras, the fixed severities match, and docs.json is valid. There are a few things to fix before it merges:
Needed
- Three codes are missing.
color_grading_non_media,color_grading_invalid_jsonandcolor_grading_invalid_structureare error-severity codes emitted through areport(code, …)helper inrules/media.ts(lines 499, 513, 521), so acode:grep misses them. The page says it lists every code, so they belong in "Media elements". html_dir_attribute_breaks_rendernames the wrong trigger. The page saysrtl"(orltr)", but the rule fires onrtlorauto(composition.ts:normalizedDir !== "rtl" && normalizedDir !== "auto"), andltrproduces no finding.
Should fix
3. system_font_will_alias only runs for distributed/Lambda renders (if (!options.distributed) return [];), but the entry reads as if it always applies.
4. inaccessible_media_url is only emitted by the exported lintMediaUrls() API, and the CLI doesn't call it. So hyperframes lint/check never show it, which contradicts the intro. Note that it's API-only.
Nits
timeline_track_too_dense: "many timed elements" means more than 3 per track (MAX_TIMED_ELEMENTS_PER_TRACK = 3).gsap_infinite_repeat: the fix text only covers the error case. When the composition has a finitedata-duration, it's a warning and nothing needs changing.
— Rames
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Approving at eef6c28a. I pushed one commit on top of yours, with the fixes from my earlier review:
- Added
color_grading_invalid_json,color_grading_invalid_structureandcolor_grading_non_mediaunder "Media elements". html_dir_attribute_breaks_rendernow names the real trigger (rtlorauto;ltrisn't flagged).system_font_will_aliasnow says it only runs withdistributed: true.inaccessible_media_urlnow says only thelintMediaUrls()API reports it;lint/checkdon't.timeline_track_too_densenow says "more than 3".
The page now lists all 135 codes the rules emit (both code: literals and report() helper calls), with nothing extra. docs.json is valid, and mint validate and mint broken-links pass. Thanks for the thorough page!
— Rames
What
Adds
docs/reference/lint-rules.mdx(859 lines, 12 groups): one###anchor section per lint finding code, each giving its severity, one sentence on what it catches, and how to fix it, grouped by the rule file the code comes from. Links it from the top of "What the Linter Catches" indocs/packages/lint.mdxand addsreference/lint-rulesto the "Composition reference" group indocs.json.Why
hyperframes lintandcheckprint finding codes, but the docs only describe categories — there is no per-code reference, so the user has only the message itself to go on. The codes live ascode: "..."literals scattered acrosspackages/lint/src/rules/*.ts(121 codes) plus 11 project-level codes inpackages/lint/src/project.ts,hyperframeLinter.tsandhevcPreviewLint.tsthat reach users through the samelintProjectpipeline.A note on the count in the issue: the issue's 120 comes from its own suggested grep,
code: "[a-z_]+". Exactly one code contains a digit (base64_media_prohibited), which that character class cannot match. Withcode: "[a-z_0-9]+"the count is 121 — and it was 121 with an identical set already at b20f3f7, the commit two minutes before the issue was filed, so nothing merged since.Related work
Fixes #5385. Claim: comment on the issue. No overlapping PR found (open-PR search returned nothing for this).
How
### \code`` anchor section: severity, what it catches, and a fix. Content is drawn from the rule's own message and fixHint, then tightened into prose. The 11 project-level checks get the same treatment under "Project-level checks".docs.json"Composition reference" group gainsreference/lint-rules, anddocs/packages/lint.mdxlinks to it from "What the Linter Catches".Test plan
Coverage (the issue's acceptance criterion):
git grep -hoE 'code: "[a-z_0-9]+"' -- 'packages/lint/src/rules/*.ts' ':!*.test.ts' | sort -u→ 121 unique codes; the 11 project-level codes come fromproject.ts/hyperframeLinter.ts/hevcPreviewLint.ts, zero overlap with the rules set.^### \code`$indocs/reference/lint-rules.mdx` → 121/121 rule codes and 11/11 project codes hit, 0 missing.Docs checks (the same commands
.github/workflows/docs.ymlruns, undertimeout 300since they need more than the default 120 on this machine):cd docs && npx mint validate→ exit 0, "success build validation passed".cd docs && npx mint broken-links --check-redirects→ exit 0, "success no broken links found".Unit tests added/updated (not applicable: docs only)
Manual testing performed (coverage loop and docs checks above)
Documentation updated (this is the documentation)
Comments follow CONTRIBUTING.md "Comments": no code comments were added; rationale lives here