@projectwallace/css-code-quality 0.2.1 → 0.3.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@projectwallace/css-code-quality",
   "description": "Calculate the Code Quality score of your CSS based on a range of different quality guards",
-  "version": "0.2.1",
+  "version": "0.3.2",
   "repository": "git@github.com:projectwallace/css-code-quality.git",
   "author": {
     "email": "bart@projectwallace.com",
@@ -17,7 +17,8 @@
     "maintainability"
   ],
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "source": "src/index.js",
@@ -25,8 +26,13 @@
   "module": "./dist/css-code-quality.module.js",
   "unpkg": "./dist/css-code-quality.umd.js",
   "exports": {
-    "require": "./dist/css-code-quality.cjs",
-    "default": "./dist/css-code-quality.modern.js"
+    ".": {
+      "import": "./dist/css-code-quality.modern.js",
+      "require": "./dist/css-code-quality.cjs"
+    },
+    "./core": {
+      "import": "./src/core.js"
+    }
   },
   "types": "./dist/index.d.ts",
   "scripts": {
@@ -34,10 +40,10 @@
     "build": "microbundle"
   },
   "dependencies": {
-    "@projectwallace/css-analyzer": "^5.5.0"
+    "@projectwallace/css-analyzer": "^5.7.1"
   },
   "devDependencies": {
-    "microbundle": "^0.15.0",
-    "uvu": "^0.5.3"
+    "microbundle": "^0.15.1",
+    "uvu": "^0.5.6"
   }
 }

package/src/complexity.js

@@ -0,0 +1,126 @@
+import { compareSpecificity } from '@projectwallace/css-analyzer'
+
+export const guards = [
+
+  // Complexity per Selector should not differ too much from the most common Complexity
+  result => {
+    const mode = result.selectors.complexity.mode
+    const selectorsAboveMode = result.selectors.complexity.items
+      .filter(c => c > mode)
+      .length
+
+    const outcome = {
+      id: 'MoreThanMostCommonSelectorComplexity',
+      score: 0,
+      value: result.selectors.total === 0 ? 0 : selectorsAboveMode / result.selectors.total,
+      actuals: result.selectors.complexity.items,
+    }
+
+    if (selectorsAboveMode > result.selectors.total * 0.1) {
+      const score = Math.floor(selectorsAboveMode * 0.01)
+      outcome.score = Math.min(10, score)
+    }
+
+    return outcome
+  },
+
+  // Specificity per Selector should not differ too much from the most common Specificity
+  result => {
+    const mode = result.selectors.specificity.mode
+    const selectorsAboveMode = result.selectors.specificity.items
+      .filter(c => compareSpecificity(c, mode) < 0)
+      .length
+
+    const outcome = {
+      id: 'MoreThanMostCommonSelectorSpecificity',
+      score: 0,
+      value: result.selectors.total === 0 ? 0 : selectorsAboveMode / result.selectors.total,
+      actuals: result.selectors.specificity.items,
+    }
+
+    if (selectorsAboveMode > result.selectors.total * 0.1) {
+      const score = Math.floor(selectorsAboveMode * 0.01)
+      outcome.score = Math.min(10, score)
+    }
+
+    return outcome
+  },
+
+  // Maximum Selector Complexity should be low
+  result => {
+    const MAX_SELECTOR_COMPLEXITY = 5
+    const actual = result.selectors.complexity.max
+
+    const outcome = {
+      id: 'MaxSelectorComplexity',
+      score: 0,
+      value: result.selectors.complexity.max,
+      actuals: result.selectors.complexity.items,
+    }
+
+    // Deduct 0.5 points per complexity over 5, up to 5 points
+    if (actual > MAX_SELECTOR_COMPLEXITY) {
+      const score = Math.ceil((actual - MAX_SELECTOR_COMPLEXITY) * 0.5)
+      outcome.score = Math.min(5, score)
+    }
+
+    return outcome
+  },
+
+  // Average Selector Complexity should be low
+  result => {
+    const ALLOWED_COMPLEXITY = 2
+    const actual = result.selectors.complexity.mean
+
+    const outcome = {
+      id: 'AverageSelectorComplexity',
+      score: 0,
+      value: actual,
+      actuals: result.selectors.complexity.items,
+    }
+
+    // Deduct 2 points per selector over 2
+    if (actual > ALLOWED_COMPLEXITY) {
+      const score = Math.ceil((actual - ALLOWED_COMPLEXITY) * 2)
+      outcome.score = Math.min(10, score)
+    }
+
+    return outcome
+  },
+
+  result => {
+    const ALLOWED = 0.01
+    const actual = result.selectors.id.ratio
+    const outcome = {
+      id: 'IdSelectorRatio',
+      score: 0,
+      value: actual,
+      actuals: Object.keys(result.selectors.id.unique)
+    }
+
+    if (actual > ALLOWED) {
+      const score = Math.floor((actual - ALLOWED) * 10)
+      outcome.score = Math.min(score, 5)
+    }
+
+    return outcome
+  },
+
+  result => {
+    const ALLOWED = 0.01
+    const actual = result.declarations.importants.ratio
+    const outcome = {
+      id: 'ImportantRatio',
+      score: 0,
+      value: actual,
+      actuals: result.declarations.importants.total,
+    }
+
+    if (actual > ALLOWED) {
+      const score = Math.floor((actual - ALLOWED) * 10)
+      outcome.score = Math.min(score, 5)
+    }
+
+    return outcome
+  },
+]

package/src/complexity.test.js

@@ -0,0 +1,126 @@
+import * as assert from 'uvu/assert'
+import { suite } from 'uvu'
+import { calculate } from './index.js'
+
+const Complexity = suite('Complexity')
+
+Complexity('should deduct points for a lot of Selectors more complex than most common Complexity', () => {
+  const fixture = `
+    ${new Array(1000)
+      .fill('')
+      .map(_ => `selector { }`)
+      .join('')
+    }
+
+    ${new Array(500)
+      .fill('')
+      .map(_ => `:where(selector) { }`)
+      .join('')
+    }
+  `
+  const actual = calculate(fixture)
+
+  assert.equal(actual.complexity.violations, [
+    {
+      id: 'MoreThanMostCommonSelectorComplexity',
+      score: 5,
+      value: 1 / 3,
+      actuals: (new Array(1000).fill(1)).concat(new Array(500).fill(2)),
+    }
+  ])
+  assert.is(actual.complexity.score, 95)
+})
+
+Complexity('should deduct points for a lot of Selectors more complex than most common Specificity', () => {
+  const fixture = `
+    ${new Array(500)
+      .fill('')
+      .map(_ => `selector1 { }`)
+      .join('')
+    }
+
+    ${new Array(200)
+      .fill('')
+      .map(_ => `.selector { }`)
+      .join('')
+    }
+  `
+  const actual = calculate(fixture)
+
+  assert.equal(actual.complexity.violations, [
+    {
+      id: 'MoreThanMostCommonSelectorSpecificity',
+      score: 2,
+      value: 200 / 700,
+      actuals: (new Array(500).fill([0, 0, 1])).concat(new Array(200).fill([0, 1, 0])),
+    }
+  ])
+  assert.is(actual.complexity.score, 98)
+})
+
+Complexity('deducts points for selectors with high complexity', () => {
+  const fixture = `
+    a b c d e f {}
+  `
+  const actual = calculate(fixture)
+
+  assert.equal(actual.complexity.violations, [
+    {
+      id: 'MaxSelectorComplexity',
+      score: 3,
+      value: 11,
+      actuals: [11],
+    },
+    {
+      id: 'AverageSelectorComplexity',
+      score: 10,
+      value: 11,
+      actuals: [11],
+    }
+  ])
+  assert.is(actual.complexity.score, 87)
+})
+
+Complexity('deducts points for having a high ratio of ID selectors', () => {
+  const fixture = `
+    a {}
+    b {}
+    c {}
+    #a {}
+  `
+  const actual = calculate(fixture)
+
+  assert.equal(actual.complexity.violations, [
+    {
+      id: 'IdSelectorRatio',
+      score: 2,
+      value: 0.25,
+      actuals: ['#a'],
+    }
+  ])
+  assert.is(actual.complexity.score, 98)
+})
+
+Complexity('deducts points for having a high ratio !importants', () => {
+  const fixture = `
+    selector {
+      a: b;
+      c: d;
+      e: f;
+      g: h !important;
+    }
+  `
+  const actual = calculate(fixture)
+
+  assert.equal(actual.complexity.violations, [
+    {
+      id: 'ImportantRatio',
+      score: 2,
+      value: 0.25,
+      actuals: 1,
+    }
+  ])
+  assert.is(actual.complexity.score, 98)
+})
+
+Complexity.run()

package/src/core.js

@@ -0,0 +1,47 @@
+import { guards as performanceGuards } from './performance.js'
+import { guards as maintainabilityGuards } from './maintainability.js'
+import { guards as complexityGuards } from './complexity.js'
+
+function calculateScore({ result, guards }) {
+	let score = 100
+	let violations = []
+	let passes = []
+
+	for (const guard of guards) {
+		/** @type {{score: number, value: number, id: string}} */
+		const outcome = guard(result)
+
+		if (outcome.score > 0) {
+			score -= outcome.score
+			violations.push(outcome)
+		} else {
+			passes.push(outcome)
+		}
+	}
+
+	return {
+		score: Math.max(score, 0),
+		violations,
+		passes,
+	}
+}
+
+export function calculate(analysis) {
+	const performance = calculateScore({ result: analysis, guards: performanceGuards })
+	const maintainability = calculateScore({ result: analysis, guards: maintainabilityGuards })
+	const complexity = calculateScore({ result: analysis, guards: complexityGuards })
+
+	return {
+		/** @deprecated */
+		score: 0,
+		violations: performance.violations
+			.concat(maintainability.violations)
+			.concat(complexity.violations),
+		passes: performance.passes
+			.concat(maintainability.passes)
+			.concat(complexity.passes),
+		performance,
+		maintainability,
+		complexity,
+	}
+}

package/src/core.test.js

@@ -0,0 +1,11 @@
+import * as assert from 'uvu/assert'
+import { suite } from 'uvu'
+import { calculate } from './core.js'
+
+const Core = suite('Core')
+
+Core('exports calculate', () => {
+	assert.is(typeof calculate, 'function')
+})
+
+Core.run()

package/src/index.js

@@ -0,0 +1,7 @@
+import { analyze } from '@projectwallace/css-analyzer'
+import { calculate as calculateFromAnalysis } from './core.js'
+
+export function calculate(css) {
+	const analysis = analyze(css)
+	return calculateFromAnalysis(analysis)
+}

package/src/index.test.js

@@ -0,0 +1,20 @@
+import * as assert from 'uvu/assert'
+import { suite } from 'uvu'
+import { calculate } from './index.js'
+import { calculate as pkgCalculate } from '../dist/css-code-quality.modern.js'
+
+const Index = suite('Index')
+
+Index('exposes a calculcate function', () => {
+	assert.is(typeof calculate, 'function')
+})
+
+Index.run()
+
+const Package = suite('NPM Package')
+
+Package('exposes a calculate function', () => {
+	assert.is(typeof pkgCalculate, 'function')
+})
+
+Package.run()

package/src/maintainability.js

@@ -0,0 +1,150 @@
+export const guards = [
+
+  // Source Lines of Code should be low'
+  result => {
+    const outcome = {
+      id: 'SourceLinesOfCode',
+      score: 0,
+      value: result.stylesheet.sourceLinesOfCode,
+    }
+
+    if (result.stylesheet.sourceLinesOfCode > 10000) {
+      // deduct 1 point per 1000 lines of code over 10,000
+      const score = Math.floor((result.stylesheet.sourceLinesOfCode - 10000) / 1000)
+      outcome.score = Math.min(15, score)
+    }
+
+    return outcome
+  },
+
+  // Average count of Selectors per RuleSet should be low
+  result => {
+    const ALLOWED_SELECTORS_PER_RULESET = 2
+    const actual = result.rules.selectors.mean
+
+    const outcome = {
+      id: 'AverageSelectorsPerRule',
+      score: 0,
+      value: actual,
+      actuals: result.rules.selectors.items,
+    }
+
+    // Deduct 5 points per selector over 2
+    if (actual > ALLOWED_SELECTORS_PER_RULESET) {
+      const score = Math.floor((actual - ALLOWED_SELECTORS_PER_RULESET) * 5)
+      outcome.score = Math.min(15, score)
+    }
+
+    return outcome
+  },
+
+  // Average count of Declarations per RuleSet should be low
+  result => {
+    const ALLOWED_DECLARATIONS_PER_RULESET = 5
+
+    const outcome = {
+      id: 'AverageDeclarationsPerRule',
+      score: 0,
+      value: result.rules.declarations.mean,
+      actuals: result.rules.declarations.items,
+    }
+
+    // Deduct 5 points per declaration over 5
+    if (result.rules.declarations.mean > ALLOWED_DECLARATIONS_PER_RULESET) {
+      const score = Math.floor((result.rules.declarations.mean - ALLOWED_DECLARATIONS_PER_RULESET) * 5)
+      outcome.score = Math.min(15, score)
+    }
+
+    return outcome
+  },
+
+  // Max number of Selectors per Rule should be low
+  result => {
+    const MAX_SELECTORS_PER_RULESET = 10
+
+    const outcome = {
+      id: 'MaxSelectorsPerRule',
+      score: 0,
+      value: result.rules.selectors.max,
+      actuals: result.rules.selectors.items,
+    }
+
+    // Deduct 0.5 points per selectors over 10
+    if (result.rules.selectors.max > MAX_SELECTORS_PER_RULESET) {
+      const score = Math.ceil((result.rules.selectors.max - MAX_SELECTORS_PER_RULESET) * 0.5)
+      outcome.score = Math.min(score, 15)
+    }
+
+    return outcome
+  },
+
+  // Max number of Declarations per Rule should be low
+  result => {
+    const MAX_DECLARATIONS_PER_RULESET = 10
+
+    const outcome = {
+      id: 'MaxDeclarationsPerRule',
+      score: 0,
+      value: result.rules.declarations.max,
+      actuals: result.rules.declarations.items,
+    }
+
+    // Deduct 0.5 points per declarations over 10
+    if (result.rules.declarations.max > MAX_DECLARATIONS_PER_RULESET) {
+      const score = Math.ceil((result.rules.declarations.max - MAX_DECLARATIONS_PER_RULESET) * 0.5)
+      outcome.score = Math.min(15, score)
+    }
+
+    return outcome
+  },
+
+  // Number of Selectors per RuleSet should not differ too much from the most common amount of
+  // Selectors per RuleSet
+  result => {
+    const mode = result.rules.selectors.mode
+    const rulesHavingMoreThanMode = result.rules.selectors.items
+      .filter(item => item > mode)
+      .length
+
+    const outcome = {
+      id: 'MoreThanMostCommonSelectorsPerRule',
+      score: 0,
+      value: result.rules.selectors.mode,
+      actuals: result.rules.selectors.items,
+    }
+
+    // if more than 10% of RuleSets has more Selectors than most common:
+    if (rulesHavingMoreThanMode > result.rules.total * 0.1) {
+      // then deduct 0.01 for ever applicable RuleSet
+      const score = Math.floor(rulesHavingMoreThanMode * 0.01)
+      // with a maximum of 10 points
+      outcome.score = Math.min(15, score)
+    }
+
+    return outcome
+  },
+
+  // Number of Declarations per RuleSet should not differ too much from the most common amount of
+  // Declarations per RuleSet
+  result => {
+    const mode = result.rules.selectors.mode
+    const rulesHavingMoreThanMode = result.rules.declarations.items.filter(item => item > mode).length
+
+    const outcome = {
+      id: 'MoreThanMostCommonDeclarationsPerRule',
+      score: 0,
+      value: result.rules.declarations.mode,
+      actuals: result.rules.declarations.items,
+    }
+
+    // if more than 10% of RuleSets has more Declarations than most common:
+    if (rulesHavingMoreThanMode > result.rules.total * 0.1) {
+      // then deduct 0.01 for ever applicable RuleSet
+      const score = Math.floor(rulesHavingMoreThanMode * 0.01)
+      // with a maximum of 10 points
+      outcome.score = Math.min(15, score)
+    }
+
+    return outcome
+  },
+]