Automate CSS Refactoring with Lemonj: A TypeScript‑Powered Analyzer

Tool Overview

Lemonj (GitHub: https://github.com/twfe/lemonj) is a TypeScript‑based static analysis and automated refactoring tool for CSS, LESS and SCSS. It uses Antlr + Antlr4TS to generate a parser, walks the AST, detects code smells such as !important, records the file path and line number, and can apply fixes automatically.

Implementation Details

Detection logic checks AST nodes for important declarations. Example:

if (Checker.hasImportant(propertyValue)) {
    if (!this.metadata.importants) {
        this.metadata.importants = [];
    }
    this.metadata.importants.push({
        type: '!important',
        file: this.metadata.filePath,
        line: ctx._start.line,
    });
}

Comparison with Conventional CSS Converters

Typical converters transform a single file’s syntax tree to another format and require separate tools for each target language. Lemonj performs static analysis across an entire codebase, identifies problems, and applies automated fixes at the recorded locations.

Usage

Install globally:

npm install -g lemonj
# or
yarn global add lemonj

Run analysis on a directory (e.g., _fixtures): lemonj analysis _fixtures The command produces a JSON‑like report, for example:

{
  "colors": 24,
  "importants": 4,
  "issues": 8,
  "mediaQueries": 1,
  "absolute": 0,
  "oddWidth": 1
}

Additional files such as color‑mapping files may be emitted.

Apply automated refactoring based on the analysis: lemonj refactor _fixtures The tool updates all files containing the identified !important declarations.

Future Work

Planned enhancements include richer smell detection and integration with design‑system naming conventions.