CSS Code Quality

The passes and violations arrays in the result object contain objects describing specific metrics. Each object includes an id, a score (representing points deducted), and a value (the actual measured value). Some metrics also include an actuals array showing the raw data points used for the calculation.

// Example violation object
{
  "id": "AverageSelectorsPerRule",
  "score": 0,
  "value": 1.5,
  "actuals": [
    2,
    1
  ]
}

Install the CSS Code Quality calculator package using npm to begin analyzing your CSS files.

npm install @projectwallace/css-code-quality

Use the calculate function to analyze a CSS string. The function returns a result object containing overall scores and detailed breakdowns for Performance, Maintainability, and Complexity. Each category includes lists of violations and passes.

import { calculate } from '@projectwallace/css-code-quality'

let css = `my_css { /* ... */ }`
let result = calculate(css)

/*
Result shape:
{
  "violations": [ ],
  "passes": [ ],
  "performance": {
    "score": 90,
    "violations": [ ],
    "passes": [ ]
  },
  "maintainability": {
    "score": 100,
    "violations": [ ],
    "passes": [ ]
  },
  "complexity": {
    "score": 97,
    "violations": [ ],
    "passes": [ ]
  }
}
*/

The project uses tsdown for its build configuration. You can define entry points, output formats, and build-time checks like dts (declaration file generation) and publint (package publishing validation) within the defineConfig function.

import { defineConfig } from 'tsdown'

export default defineConfig({
	entry: ['./src/index.ts', './src/core.ts'],
	format: 'esm',
	platform: 'neutral',
	dts: true,
	publint: true,
})

The project uses knip for dependency and unused file analysis. You can configure the analysis scope by defining the project paths and specifying dependencies to be ignored via ignoreDependencies. In the current setup, the project analyzes TypeScript files in the src directory and ignores @projectwallace/preset-oxlint to prevent false positives in dependency reporting.

import type { KnipConfig } from 'knip'

const config: KnipConfig = {
	project: ['src/**/*.ts'],
	ignoreDependencies: ['@projectwallace/preset-oxlint'],
}

export default config

The Performance score measures the likelihood of negative impact on performance. Metrics include:

The calculate function is the primary entrypoint for assessing the quality of a CSS string. It performs a full analysis of the provided CSS and returns quality metrics. Internally, it uses @projectwallace/css-analyzer to parse the CSS and then applies the calculation logic to the resulting analysis object.

import { calculate } from '@projectwallace/css-code-quality';

const css = '.my-class { color: red; font-size: 16px; }';
const qualityMetrics = calculate(css);
console.log(qualityMetrics);

The guards array contains functions used to calculate complexity scores for CSS analysis. Each guard takes an Analysis object and returns an outcome object containing an id, a score (typically 0-10), the value being measured, and the actuals (the raw data points used for the calculation). These guards monitor selector complexity, specificity, ID selector ratios, and the use of !important declarations.

import { guards } from '@projectwallace/css-code-quality';

// The guards array is used by the engine to evaluate the quality of a CSS Analysis result.
// Each guard follows the signature: (result: Analysis) => Outcome