From 38697ab14c80ccb09f952c7e171d312e37a690c2 Mon Sep 17 00:00:00 2001 From: Bart Veneman Date: Sat, 16 Mar 2024 12:02:19 +0100 Subject: [PATCH] improve readme with related projects, installation and usage --- readme.md | 75 +++++++++- src/index.test.js | 371 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 443 insertions(+), 3 deletions(-) diff --git a/readme.md b/readme.md index a2c3565..9d2e4eb 100644 --- a/readme.md +++ b/readme.md @@ -22,8 +22,77 @@ --- -This package analyzes your CSS on a high level and comes up with a score, divided in three areas: +This package analyzes your CSS on a high level and comes up with a score, divided into three areas: - **Maintainability**: how difficult is it for someone looking at the CSS from a high level to find the exact spot to fix a bug? -- **Complexity**: how difficult is it for someone to make a change and them being confident that they can make that change without side-effects? -- **Performance**: How likely is the CSS to have a negative impact on performance, based on high-level metrics? (Not including using hardware accelerated transforms and the like, because other tools are more suite for that.) +- **Complexity**: how difficult is it for someone to make a change and be confident that they can make that change without side effects? +- **Performance**: How likely is the CSS to have a negative impact on performance, based on high-level metrics? (Not including using hardware accelerated transforms and the like, because other tools are more suited for that.) + +## Installation + +```bash +npm install @projectwallace/css-code-quality +``` + +## Usage + +```js +import { calculate } from "@projectwallace/css-code-quality"; + +let css = `my_css { /* ... */ }`; +let result = calculate(css); + +/* +The result shape looks something like this: + +{ + "violations": [ ], + "passes": [ ], + "performance": { + "score": 90, + "violations": [ ], + "passes": [ ] + }, + "maintainability": { + "score": 100, + "violations": [ ], + "passes": [ ] + }, + "complexity": { + "score": 97, + "violations": [ ], + "passes": [ ] + } +} + +Each `passes` or `violations` array contains an object that looks like this: + +{ + "id": "EmptyRules", + "score": 0, + "value": 0 +}, +{ + "id": "AverageSelectorsPerRule", + "score": 0, + "value": 1.5, + "actuals": [ + 2, + 1 + ] +} + +etc. etc. + +*/ +``` + +## Related projects + +- [CSS Analyzer](https://github.com/projectwallace/css-analyzer) - + A CSS Analyzer that goes through your CSS to find all kinds of relevant statistics. +- [Wallace CLI](https://github.com/projectwallace/wallace-cli) - CLI tool for + @projectwallace/css-analyzer +- [Constyble](https://github.com/projectwallace/constyble) - CSS Complexity linter +- [Color Sorter](https://github.com/projectwallace/color-sorter) - Sort CSS colors + by hue, saturation, lightness and opacity diff --git a/src/index.test.js b/src/index.test.js index f403421..032b3a6 100644 --- a/src/index.test.js +++ b/src/index.test.js @@ -9,6 +9,377 @@ Index('exposes a calculcate function', () => { assert.is(typeof calculate, 'function') }) +Index('smoke test', () => { + let css = ` + @import url('https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap'); + + .my_test, + .my_extra_test { + color: red; + } + + #my_test { + color: green; + } + ` + let result = calculate(css) + assert.equal(result, { + "score": 0, + "violations": [ + { + "id": "Imports", + "score": 10, + "value": 1, + "actuals": [ + "url('https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap')" + ] + }, + { + "id": "IdSelectorRatio", + "score": 3, + "value": 0.3333333333333333, + "actuals": [ + "#my_test" + ] + } + ], + "passes": [ + { + "id": "EmptyRules", + "score": 0, + "value": 0 + }, + { + "id": "SelectorDuplications", + "score": 0, + "value": 0 + }, + { + "id": "DeclarationDuplications", + "score": 0, + "value": 0 + }, + { + "id": "CssSize", + "score": 0, + "value": 180 + }, + { + "id": "TooMuchComments", + "score": 0, + "value": 0 + }, + { + "id": "TooMuchEmbeddedContent", + "score": 0, + "value": 0, + "actuals": [] + }, + { + "id": "SourceLinesOfCode", + "score": 0, + "value": 6 + }, + { + "id": "AverageSelectorsPerRule", + "score": 0, + "value": 1.5, + "actuals": [ + 2, + 1 + ] + }, + { + "id": "AverageDeclarationsPerRule", + "score": 0, + "value": 1, + "actuals": [ + 1, + 1 + ] + }, + { + "id": "MaxSelectorsPerRule", + "score": 0, + "value": 2, + "actuals": [ + 2, + 1 + ] + }, + { + "id": "MaxDeclarationsPerRule", + "score": 0, + "value": 1, + "actuals": [ + 1, + 1 + ] + }, + { + "id": "MoreThanMostCommonSelectorsPerRule", + "score": 0, + "value": 1.5, + "actuals": [ + 2, + 1 + ] + }, + { + "id": "MoreThanMostCommonDeclarationsPerRule", + "score": 0, + "value": 1, + "actuals": [ + 1, + 1 + ] + }, + { + "id": "MoreThanMostCommonSelectorComplexity", + "score": 0, + "value": 0, + "actuals": [ + 1, + 1, + 1 + ] + }, + { + "id": "MoreThanMostCommonSelectorSpecificity", + "score": 0, + "value": 0.3333333333333333, + "actuals": [ + [ + 0, + 1, + 0 + ], + [ + 0, + 1, + 0 + ], + [ + 1, + 0, + 0 + ] + ] + }, + { + "id": "MaxSelectorComplexity", + "score": 0, + "value": 1, + "actuals": [ + 1, + 1, + 1 + ] + }, + { + "id": "AverageSelectorComplexity", + "score": 0, + "value": 1, + "actuals": [ + 1, + 1, + 1 + ] + }, + { + "id": "ImportantRatio", + "score": 0, + "value": 0, + "actuals": 0 + } + ], + "performance": { + "score": 90, + "violations": [ + { + "id": "Imports", + "score": 10, + "value": 1, + "actuals": [ + "url('https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap')" + ] + } + ], + "passes": [ + { + "id": "EmptyRules", + "score": 0, + "value": 0 + }, + { + "id": "SelectorDuplications", + "score": 0, + "value": 0 + }, + { + "id": "DeclarationDuplications", + "score": 0, + "value": 0 + }, + { + "id": "CssSize", + "score": 0, + "value": 180 + }, + { + "id": "TooMuchComments", + "score": 0, + "value": 0 + }, + { + "id": "TooMuchEmbeddedContent", + "score": 0, + "value": 0, + "actuals": [] + } + ] + }, + "maintainability": { + "score": 100, + "violations": [], + "passes": [ + { + "id": "SourceLinesOfCode", + "score": 0, + "value": 6 + }, + { + "id": "AverageSelectorsPerRule", + "score": 0, + "value": 1.5, + "actuals": [ + 2, + 1 + ] + }, + { + "id": "AverageDeclarationsPerRule", + "score": 0, + "value": 1, + "actuals": [ + 1, + 1 + ] + }, + { + "id": "MaxSelectorsPerRule", + "score": 0, + "value": 2, + "actuals": [ + 2, + 1 + ] + }, + { + "id": "MaxDeclarationsPerRule", + "score": 0, + "value": 1, + "actuals": [ + 1, + 1 + ] + }, + { + "id": "MoreThanMostCommonSelectorsPerRule", + "score": 0, + "value": 1.5, + "actuals": [ + 2, + 1 + ] + }, + { + "id": "MoreThanMostCommonDeclarationsPerRule", + "score": 0, + "value": 1, + "actuals": [ + 1, + 1 + ] + } + ] + }, + "complexity": { + "score": 97, + "violations": [ + { + "id": "IdSelectorRatio", + "score": 3, + "value": 0.3333333333333333, + "actuals": [ + "#my_test" + ] + } + ], + "passes": [ + { + "id": "MoreThanMostCommonSelectorComplexity", + "score": 0, + "value": 0, + "actuals": [ + 1, + 1, + 1 + ] + }, + { + "id": "MoreThanMostCommonSelectorSpecificity", + "score": 0, + "value": 0.3333333333333333, + "actuals": [ + [ + 0, + 1, + 0 + ], + [ + 0, + 1, + 0 + ], + [ + 1, + 0, + 0 + ] + ] + }, + { + "id": "MaxSelectorComplexity", + "score": 0, + "value": 1, + "actuals": [ + 1, + 1, + 1 + ] + }, + { + "id": "AverageSelectorComplexity", + "score": 0, + "value": 1, + "actuals": [ + 1, + 1, + 1 + ] + }, + { + "id": "ImportantRatio", + "score": 0, + "value": 0, + "actuals": 0 + } + ] + } + }) +}) + Index.run() const Package = suite('NPM Package')