stylestats_analyze-css.node_cli.txt

                                  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
                                  ┃   STYLESTATS_ANALYZE-CSS   ┃
                                  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

ALTERNATIVES ==>                  #  - stylestats: best stats and output
                                  #  - analyze-css: some interesting stats, e.g. comments, specificity, errors
                                  #  - cssstats: less stats, and only runs as a local app
                                  #Prefer stylestats + analyze-css

SUMMARY ==>                       #Static analysis on CSS
                                  #stylestats can also run tests
                                  #Interesting metrics are:
                                  #  - size:
                                  #     - total, gzipped, number of files, rulesets, SELECTORS, SELECTOR, PROPS
                                  #  - complexity:
                                  #     - average|max number of SELECTORS, SELECTOR, PROPS
                                  #     - prevent: use linters, promote naming scheme or CSS modules
                                  #  - consistency:
                                  #     - unique colors, media queries, font sizes, font families, background images
                                  #     - prevent: use variables
                                  #  - maintability:
                                  #     - number of comments
                                  #     - prevent: write comments
                                  #  - bad architecture:
                                  #     - repetitive selectors, complex selectors, specificity, !important
                                  #     - prevent: use linters, promote naming scheme or CSS modules

                                  ┌────────────────┐
                                  │   STYLESTATS   │
                                  └────────────────┘

VERSION ==>                       #6.3.0

CONF ==>                          #Can be:
                                  #  - stylestats --VAR VAL
                                  #  - stylestats --config CONF.json
                                  #  - new STYLESTATS(..., CONF|'CONF.json')

stylestats [FILE|DIR|URL...]      #Def: stdin
                                  #Can be CSS or HTML (extract <style> and CSS <link>)
--format STR                      #Can be: json, html, md (markdown), csv
                                  #Def: CLI table
--template FILE.html              #When format is html
--number                          #Only show numeral metrics

--specs OBJ|JSON                  #Creates and run unit tests (using Mocha) testing values.
                                  #OBJ:
                                  #  - defaults:
                                  #     - reporter STR (def: 'spec')
                                  #     - suiteName STR (def: 'StyleStats Test')
                                  #     - operation '<' (def), '>', '<>', '=='
                                  #  - VARR VAL:
                                  #     - compares to RESULT[VARR]
                                  #     - VAL can be:
                                  #        - NUM|STR|BOOL: actual OP NUM|STR|BOOL (according to defaults.operation)
                                  #        - { min|max: NUM }: actual < > NUM
                                  #     - VAL.text STR: test name (def: auto)

--mobile                          #Sets mobile user agent (when requesting URL)

new STYLESTATS
('FILE'[_ARR], CONF|'CONF.json')  #
STYLES.parse(FUNC(ERROR, RESULT)) #RESULT:
                                  #  - paths 'FILE'[_ARR]
                                  #  - METRIC VAL

                                  ┌─────────────────┐
                                  │   ANALYZE-CSS   │
                                  └─────────────────┘

VERSION ==>                       #0.12.0

analyze-css                       #Prints stats
                                  #Also prints problematic stats: 'offenders'
--file FILE.css                   #Def: stdin
--url URL                         #
--auth-user|pass VAL              #HTTP authentication
--ignore-ssl-errors               #

--pretty                          #Table output instead of JSON
--no-offenders                    #


ANALYZE-CSS                       #As Node module
('CSS'[, CONF], FUNC(ERROR, OBJ)) #OBJ: metrics.METRIC VAL, offenders.METRIC 'CSS'_ARR

                                  ┌─────────────┐
                                  │   METRICS   │
                                  └─────────────┘

NOTATION ==>                      #  - for analyze-css
                                  #  + for stylestats

Size:
  -+ total size
  + gzipped size
  + number of files
  + number of <style>
  -+ number of rulesets
  - number of SELECTOR:
     -+ all, #ID, *
     - .CLASS, TAG, :PSEUDO, [ATTR]
  - number of PROPS
  + number of PROPS for each PROP

Complexity:
  -+ average SELECTOR per SELECTORS
  + max SELECTOR per SELECTORS
  + average SELECTORS per ruleset
  + average PROPS per ruleset
  + max PROPS per ruleset

Consistency:
  -+ unique colors
  -+ unique media queries
  + unique font sizes
  + unique font families
  + unique background images

Redundancy:
  - redundant selectors
  - redundant body selectors
  - redundant child nodes selectors

Specificity:
  - .CLASS.CLASS2
  - SELECTOR#ID, TAG
  - SELECTORS with 4+ SELECTOR
  - selectors with complex [ATTR]
  + [ATTR] at end of SELECTORS
  -+ !important
  - average|total specificity for: NUM, NUM2, NUM3

Comments:
  - number of comments
  - size of comments

Performance:
  - @import
  - not minified
  - vendor-prefixes no longer needed
  -+ amount/size of data URIs
  + size of data URIs / total size

Errors:
  - CSS parsing error
  - redundant props within same ruleset
  - empty ruleset
  - shorthand property overriding specific property
  + js-CLASS, or any other REGEXP

Non-standard:
  - expression()
  - IE fixes