Skip to content
This repository was archived by the owner on Jan 27, 2019. It is now read-only.

Commit 151a60e

Browse files
jxnblkjxnblk
committed
Merge pull request #42 from cssstats/v2
V2
2 parents fef4673 + e9d8a43 commit 151a60e

31 files changed

+4802
-57585
lines changed

‎.jshintrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@
3737

3838

3939
// Personal styling preferences.
40+
"asi" : true,
4041
"newcap" : true, // Require capitalization of all constructor functions e.g. `new F()`.
4142
"noempty" : true, // Prohibit use of empty blocks.
4243
"nomen" : true, // Prohibit use of initial or trailing underbars in names.

‎README.md‎

Lines changed: 208 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,48 @@
1-
# CSS Statistics
1+
# cssstats
22
Parses stylesheets and returns an object with statistics
33

4-
Used in http://cssstats.com
4+
This is the core module used in http://cssstats.com
55

66
## Installation
77

88
```sh
9-
npm install --save cssstats
9+
npm install cssstats
1010
```
1111

1212
## Usage
1313

14+
### Node
15+
1416
```js
15-
var fs = require('fs');
16-
var cssstats = require('csstats');
17+
var fs = require('fs')
18+
var cssstats = require('csstats')
1719

18-
var css = fs.readFileSync('./styles.css', 'utf8');
19-
var obj = cssstats(css);
20+
var css = fs.readFileSync('./styles.css', 'utf8')
21+
var stats = cssstats(css)
2022
```
2123

22-
Instead of a CSS string, you can also pass the [PostCSS AST](https://github.com/postcss/postcss):
24+
### PostCSS Plugin
2325

24-
```js
25-
var fs = require('fs');
26-
var postcss = require('postcss');
27-
var cssstats = require('csstats');
26+
CSS Stats can be used as a [PostCSS](https://github.com/postcss/postcss) plugin.
27+
The stats will be added to PostCSS's messages array.
2828

29-
var css = fs.readFileSync('./styles.css', 'utf8');
30-
var ast = postcss.parse(css);
31-
var obj = cssstats(ast);
29+
```js
30+
var fs = require('fs')
31+
var postcss = require('postcss')
32+
var cssstats = require('csstats')
33+
34+
var css = fs.readFileSync('./styles.css', 'utf8')
35+
postcss()
36+
.use(cssstats())
37+
.process(css)
38+
.then(function (result) {
39+
result.messages.forEach(function (message) {
40+
console.log(message)
41+
})
42+
})
3243
```
3344

34-
### Using the CLI
45+
#### CLI
3546

3647
```sh
3748
npm i -g cssstats
@@ -45,41 +56,195 @@ cat some-css-file.css | cssstats
4556
getcss google.com | cssstats
4657
```
4758

59+
#### Options
60+
61+
Options may be passed as a second argument.
62+
63+
```js
64+
var stats = cssstats(css, { mediaQueries: false })
65+
```
66+
67+
- `safe` (boolean, default: `true`) - enables [PostCSS safe mode](https://github.com/postcss/postcss#safe-mode) for parsing CSS with syntax errors
68+
- `mediaQueries` (boolean, default `true`) - determines whether or not to generate stats for each media query block
69+
- `importantDeclarations` (boolean, default `false`) - include an array of declarations with `!important`
70+
71+
The following options add the results of helper methods to the returned object. This is helpful when using `JSON.stringify()`.
72+
73+
- `specificityGraph` (boolean, deault `false`)
74+
- `sortedSpecificityGraph` (boolean, deault `false`)
75+
- `repeatedSelectors` (boolean, deault `false`)
76+
- `propertyResets` (boolean, deault `false`)
77+
- `vendorPrefixedProperties` (boolean, deault `false`)
78+
4879
### Returned Object
4980

50-
__`size`:__ The size of the file in bytes
81+
```js
82+
// Example
83+
{
84+
size: n,
85+
gzipSize: n,
86+
rules: {
87+
total: n,
88+
size: {
89+
graph: [n],
90+
max: n,
91+
average: n
92+
}
93+
},
94+
selectors: {
95+
total: n,
96+
id: n,
97+
class: n,
98+
type: n,
99+
pseudoClass: n,
100+
psuedoElement: n,
101+
values: [str],
102+
specificity: {
103+
max: n
104+
average: n
105+
},
106+
getSpecificityGraph(),
107+
getRepeatedValues(),
108+
getSortedSpecificity()
109+
},
110+
declarations: {
111+
total: n,
112+
important: n,
113+
properties:
114+
prop: [str]
115+
},
116+
getPropertyResets(),
117+
getUniquePropertyCount(),
118+
getPropertyValueCount(),
119+
getVendorPrefixed(),
120+
getAllFontSizes(),
121+
getAllFontFamilies(),
122+
},
123+
mediaQueries: {
124+
total: n,
125+
unique: n,
126+
values: [str],
127+
contents: [
128+
{
129+
value: str,
130+
rules: {
131+
total: n,
132+
size: {
133+
graph: [n],
134+
max: n,
135+
average: n
136+
}
137+
},
138+
selectors: {
139+
total: n,
140+
id: n,
141+
class: n,
142+
type: n,
143+
pseudoClass: n,
144+
pseudoElement: n,
145+
values: [str],
146+
specificity: {
147+
max: n,
148+
average: n
149+
}
150+
},
151+
declarations: {
152+
total: n,
153+
important: n,
154+
vendorPrefix: n,
155+
properties: {
156+
prop: [str]
157+
}
158+
}
159+
}
160+
]
161+
}
162+
}
163+
```
164+
165+
#### `size` number
166+
The size of the file in bytes
167+
168+
#### `gzipSize` number
169+
The size of the stylesheet gzipped in bytes
51170

52-
__`gzipSize`:__ The size of the stylesheet gzipped in bytes
171+
#### `rules` object
53172

54-
__`selectors`:__ An array of selectors sorted by source order with the selector string, specificity score, and parts array
173+
- `total` number - total number of rules
174+
- `size` object
175+
- `size.graph` array - ruleset sizes (number of declarations per rule) in source order
176+
- `size.max` number - maximum ruleset size
177+
- `size.average` number - average ruleset size
55178

56-
__`declarations`:__ An object of declarations.
57-
- `declarations.all`: An array of declaration objects from PostCSS.
58-
- `declarations.byProperty`: An object with keys for each property found in the stylesheet.
59-
- `declarations.unique`: An object with keys for each unique property/value found in the stylesheet.
60-
- `declarations.byMedia`: An object with keys for each media query found in the stylesheet.
61-
- `declarations.propertyResetDeclarations`: An object with keys for each property with a value of `0` found in the stylesheet. (Actually only margins and paddings are counted)
62-
- `declarations.importantCount`: The number of declarations with values that contain `!important`
63-
- `declarations.vendorPrefixCount`: The number of declaration properties that have vendor prefixes.
64-
- `declarations.displayNoneCount`: The number of `display: none;` declarations.
65-
- `declarations.uniqueDeclarationsCount`: The number of unique declarations.
179+
#### `selectors` object
66180

67-
__`rules`:__ Flattened array of rules from PostCSS.
181+
- `total` number - total number of selectors
182+
- `type` number - total number of type selectors
183+
- `class` number - total number of class selectors
184+
- `id` number - total number of id selectors
185+
- `pseudoClass` number - total number of pseudo class selectors
186+
- `pseudoElement` number - total number of pseudo element selectors
187+
- `values` array - array of strings for all selectors
188+
- `specificity` object
189+
- `specificity.max` number - maximum specificity as a base 10 number
190+
- `specificity.average` number - average specificity as a base 10 number
191+
- `getSpecificityGraph()` function - returns an array of numbers for each selector’s specificity as a base 10 number
192+
- `getRepeatedValues()` function - returns an array of strings of repeated selectors
193+
- `getSortedSpecificity()` function - returns an array of selectors with base 10 specificity score, sorted from highest to lowest
68194

69-
__`aggregates`:__ Aggregate data for the entire stylesheet.
70-
- `selectors` - total number of selectors
71-
- `declarations` - total number of declarations
72-
- `properties` - an array of properties used in the stylesheet
73-
- `mediaQueries` - an array of media query strings used in the stylesheet
74-
- `idSelectors` - total number of selectors containing an id
75-
- `classSelectors` - total number of selectors containing a class
76-
- `pseudoElementSelectors` - total number of selectors containing an pseudo element
77-
- `pseudoClassSelectors` - total number of selectors containing a pseudo class
78-
- `repeatedSelectors` - array of selectors that were declared more than once
195+
#### `declarations` object
79196

80-
For every unique property found in the stylesheet, `aggregates` also includes these values:
81-
- `[property].total` - total number of [property] declarations
82-
- `[property].unique` - number of unique [property] declarations
197+
- `total` number - total number of declarations
198+
- `properties` object - object with each unique property and an array of that property’s values
199+
- `getPropertyResets()` function - returns an object with the number of times margin or padding is reset for each property
200+
- `getUniquePropertyCount(property)` function - returns the number of unique values for the given property
201+
- `getPropertyValueCount(property, value)` function - returns the number of times a declaration occurs for the given property and value
202+
- `getVendorPrefixed()` function - returns an array of declarations with vendor prefixed properties
203+
- `getAllFontSizes()` function - returns an array of font sizes from both `font-size` and `font` shorthand declarations
204+
- `getAllFontFamilies()` function - returns an array of font families from both `font-family` and `font` shorthand declarations
205+
- `important` array (optional) - `!important` declaration objects with `property` and `value`
206+
207+
#### `mediaQueries` object
208+
209+
- `total` number - total number of media queries
210+
- `unique` number - total unique media queries
211+
- `values` array - array of values for each media query
212+
- `contents` array - array of media query blocks with full stats object for each
83213

84214

85215
See the `/test/results` folder for example JSON results.
216+
217+
### Usage examples
218+
219+
```js
220+
var cssstats = require('cssstats')
221+
var stats = cssstats(css)
222+
```
223+
224+
#### Generate a [specificity graph](http://csswizardry.com/2014/10/the-specificity-graph/)
225+
226+
```js
227+
var specificityGraph = stats.selectors.getSpecificityGraph()
228+
```
229+
230+
#### Sort selectors by highest specificity
231+
232+
```js
233+
var sortedSelectors = stats.selectors.getSortedSpecificity()
234+
```
235+
236+
#### Get total number of unique colors
237+
238+
```js
239+
var uniqueColorsCount = stats.declarations.getUniquePropertyCount('color')
240+
```
241+
242+
#### `display: none` count
243+
244+
```js
245+
var displayNoneCount = stats.declarations.getPropertyValueCount('display', 'none')
246+
```
247+
248+
249+
MIT License
250+

‎bin/cssstats.js‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,43 @@
11
#!/usr/bin/env node
22

3-
var program = require('commander');
4-
var cssstats = require('..');
5-
var fs = require('fs');
6-
var stdin = require('stdin');
3+
var program = require('commander')
4+
var cssstats = require('..')
5+
var fs = require('fs')
6+
var stdin = require('stdin')
77

88
var version = '1.6.0'
99

10-
console.log('CSS Statistics CLI (' + version + ')');
10+
console.log('CSS Statistics CLI (' + version + ')')
1111

1212
program
13-
.version(version);
13+
.version(version)
1414

1515
program
1616
.command('file [file]')
1717
.description('read a local css file')
18-
.action(function(file) {
18+
.action(function (file) {
1919
if (!file) {
20-
console.log('Please specify a CSS file');
21-
return;
20+
console.log('Please specify a CSS file')
21+
return
2222
}
2323

2424
try {
25-
var css = fs.readFileSync(file, 'utf8');
26-
console.log(JSON.stringify(cssstats(css), null, 2));
25+
var css = fs.readFileSync(file, 'utf8')
26+
console.log(JSON.stringify(cssstats(css), null, 2))
2727
} catch (e) {
28-
console.log('CSS Statistics encountered an error reading ' + file);
29-
console.log(e);
28+
console.log('CSS Statistics encountered an error reading ' + file)
29+
console.log(e)
3030
}
31-
});
31+
})
3232

33-
program.parse(process.argv);
33+
program.parse(process.argv)
3434

3535
if (!program.args.length) {
36-
console.log('Input some CSS\n^C to cancel\n^D when complete');
36+
console.log('Input some CSS\n^C to cancel\n^D when complete')
3737

38-
stdin(function(css) {
38+
stdin(function (css) {
3939
if (css) {
40-
console.log(JSON.stringify(cssstats(css), null, 2));
40+
console.log(JSON.stringify(cssstats(css), null, 2))
4141
}
42-
});
42+
})
4343
}

0 commit comments

Comments
 (0)