Skip to content

feat(mint): add CSS nesting depth audit - #114

Draft
nujovich wants to merge 3 commits into
mainfrom
hermes/build/mint-css-nesting-audit
Draft

feat(mint): add CSS nesting depth audit#114
nujovich wants to merge 3 commits into
mainfrom
hermes/build/mint-css-nesting-audit

Conversation

@nujovich

@nujovich nujovich commented Sep 8, 2026

Copy link
Copy Markdown
Owner

Card: https://github.com/nujovich/mint-radar/issues/23

What: Adds a CSS nesting audit that flags nesting depth and specificity
anti-patterns. Milestone 1 added the NestingAudit type to lib/types.ts
with maxDepth, specificityGrowth, and unnecessaryAmpersand fields, plus
a nesting field on AuditReport. Milestone 2 adds parseNestedRules and
lintNesting to lib/css-lint-rules.mjs, which walk nested selectors,
measure maximum nesting depth, and flag redundant & prefixes. Remaining
milestones add the complexity heatmap output and fixture tests.

Why: CSS nesting is widely available since 2024, but recent write-ups
(Piccalilli, Kilian Valkhof) warn about the same pitfalls teams hit with Sass
nesting: excessive depth, uncontrolled specificity growth, and redundant &
selectors. Stylelint has basic nesting rules but no dedicated auditor that
measures maximum depth or detects unnecessary specificity growth. This closes
that gap.

Decision: PLAN defined 4 concrete code milestones.

Milestones

  • Milestone 1 -- Add NestingAudit type to lib/types.ts with maxDepth,
    specificityGrowth, and unnecessaryAmpersand fields, plus a nesting
    field on AuditReport
  • Milestone 2 -- Implement a parser that walks nested selectors with &,
    measuring maximum depth and flagging unnecessary & (when the nested
    selector is already specific)
  • Milestone 3 -- Add a nesting complexity heatmap to the audit output with
    a configurable --max-nesting-depth threshold
  • Milestone 4 -- Add test fixtures and tests based on Piccalilli and Kilian
    Valkhof nesting pitfalls

How to test:

npm run typecheck
npm test

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant