Skip to content

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

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

nujovich wants to merge 5 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. Milestone 3
adds a nesting-complexity heatmap to the lint output with a configurable
--max-nesting-depth threshold.

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

Milestone 3 detail

Added a nesting-complexity heatmap to the mint-ds lint output:

  • lib/css-lint-rules.mjs — new nestingDepthHeatmap(css, opts) function that
    aggregates parseNestedRules() into a per-depth rule-count distribution
    (depth 0 through maxDepth) and flags every rule nested deeper than the
    threshold (default 3) in excessive.
  • bin/mint-ds.mjscmdLint now renders the heatmap as an ASCII bar chart
    (green below the threshold, yellow at it, red above it) and lists a WARN line
    for each rule exceeding the threshold. New --max-nesting-depth <n> flag
    (documented under LINT OPTIONS in --help); invalid or missing values fall
    back to the default of 3.
  • lib/__tests__/css-lint-rules.test.mjs — 5 new tests covering flat CSS,
    multi-level distribution, default/custom thresholds, and empty input.

How to test:

npm run typecheck
npm test
npx mint-ds lint <dir> --max-nesting-depth 2

@nujovich

Copy link
Copy Markdown
Owner Author

All milestones complete. Ready for review when you are.

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