@projectwallace/css-code-coverage 0.1.2 → 0.2.0

package/README.md

@@ -1,5 +1,8 @@
 # CSS Code Coverage
 
+> [!WARNING]
+> This is a very experimental approach to calculating CSS Code Coverage and currently very much a work in progress.
+
 Takes your generated coverage files and turns them into something actually usable. Accepts coverage reports generated by browsers (Edge/Chrome/chromium), Puppeteer, Playwright.
 
 Features include:
@@ -17,59 +20,93 @@ npm install @projectwallace/css-code-coverage
 
 ## Usage
 
-### Prerequisites
+```ts
+import { calculate_coverage } from '@projectwallace/css-code-coverage'
+
+function parse_html(html) {
+	return new DOMParser().parseFromString(html, 'text/html')
+}
 
-1. You have collected browser coverage data of your CSS. There are several ways to do this:
+let report = calculcate_coverage(coverage_data, parse_html)
+```
 
-   1. in the browser devtools in [Edge](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/coverage/)/[Chrome](https://developer.chrome.com/docs/devtools/coverage/)/chromium
-   1. Via the `coverage.startCSSCoverage()` API that headless browsers like [Playwright](https://playwright.dev/docs/api/class-coverage#coverage-start-css-coverage) or [Puppeteer](https://pptr.dev/api/puppeteer.coverage.startcsscoverage/) provide.
+See [src/index.ts](https://github.com/projectwallace/css-code-coverage/blob/main/src/index.ts) for the data that's returned.
 
-   Either way you end up with one or more JSON files that contain coverage data.
+## Collecting CSS Coverage
 
-   ```ts
-   // Read a single JSON or a folder full of JSON files with coverage data
-   // Coverage data looks like this:
-   // {
-   //   url: 'https://www.projectwallace.com/style.css',
-   //   text: 'a { color: blue; text-decoration: underline; }', etc.
-   //   ranges: [
-   //     { start: 0, end: 46 }
-   //   ]
-   // }
-   import { parse_coverage } from '@projectwallace/css-code-coverage'
+There are two principal ways of collecting CSS Coverage data:
 
-   let files = await fs.glob('./css-coverage/**/*.json')
-   let coverage_data = []
+### Browser devtools
 
-   for (let file of files) {
-   	let json_content = await fs.readFile(file, 'urf-8')
-   	coverage_data.push(...parse_coverage(json_content))
-   }
-   ```
+In Edge, Chrome or chromium you can manually collect coverage in the browser's DevTools. In all cases you'll generate coverage data manually and the browser will let you export the data to a JSON file. Note that this JSON contains both JS coverage as well as the CSS coverage. Learn how it works:
 
-1. You provide a HTML parser that we use to 'scrape' the HTML in case the browser gives us not just plain CSS contents. Depending on where you run this analysis you can use:
+- Collect coverage in Microsoft Edge: https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/coverage/
+- Collect coevrage in Google Chrome: https://developer.chrome.com/docs/devtools/coverage/
 
-   1. Browser:
-      ```ts
-      function parse_html(html) {
-      	return new DOMParser().parseFromString(html, 'text/html')
-      }
-      ```
-   1. Node (using [linkedom](https://github.com/WebReflection/linkedom) in this example):
+Additionally, DevTools Tips writes about it in their [explainer](https://devtoolstips.org/tips/en/detect-unused-code/).
 
-      ```ts
-      // $ npm install linkedom
-      import { DOMParser } from 'linkedom'
+You end up with one or more JSON files that contain coverage data. We provide a helper `parse_coverage()` that both parses the JSON and validates it so you can pass it directly into `calculate_coverage()`.
+
+```ts
+// Read a single JSON or a folder full of JSON files with coverage data
+// Coverage data looks like this:
+// {
+//   url: 'https://www.projectwallace.com/style.css',
+//   text: 'a { color: blue; text-decoration: underline; }', etc.
+//   ranges: [
+//     { start: 0, end: 46 }
+//   ]
+// }
+import { parse_coverage } from '@projectwallace/css-code-coverage'
+
+let files = await fs.glob('./css-coverage/**/*.json')
+let coverage_data = []
+
+for (let file of files) {
+	let json_content = await fs.readFile(file, 'urf-8')
+	coverage_data.push(...parse_coverage(json_content))
+}
+```
 
-      function parse_html(html: string) {
-      	return new DOMParser().parseFromString(html, 'text/html')
-      }
-      ```
+### Coverage API
 
-### Bringing it together
+Both Puppeteer and Playwright provide an API to programmatically get the coverage data, allowing you to put that directly into this library. Here is the gist:
 
 ```ts
+// Start collecting coverage
+await page.coverage.startCSSCoverage()
+// Load the page, do all sorts of interactions to increase coverage, etc.
+await page.goto('http://example.com')
+// Stop the coverage and store the result in a variable to pass along
+let coverage = await page.coverage.stopCSSCoverage()
+
+// Now we can process it
 import { calculate_coverage } from '@projectwallace/css-code-coverage'
 
-let report = calculcate_coverage(coverage_data, parse_html)
+function parse_html(html) {
+	return new DOMParser().parseFromString(html, 'text/html')
+}
+
+let report = calculcate_coverage(coverage, parse_html)
 ```
+
+### Optional: coverage from `<style>` blocks
+
+Coverage generators also create coverage ranges for `<style>` blocks in HTML. If this applies to your code you should provide a HTML parser that we use to 'scrape' the HTML in case the browser gives us not just plain CSS contents. Depending on where you run this analysis you can use:
+
+1.  Browser:
+    ```ts
+    function parse_html(html) {
+    	return new DOMParser().parseFromString(html, 'text/html')
+    }
+    ```
+1.  Node (using [linkedom](https://github.com/WebReflection/linkedom) in this example, but other parsers could work, too):
+
+    ```ts
+    // $ npm install linkedom
+    import { DOMParser } from 'linkedom'
+
+    function parse_html(html: string) {
+    	return new DOMParser().parseFromString(html, 'text/html')
+    }
+    ```

package/dist/css-code-coverage.js

@@ -134,6 +134,8 @@ function G(t, e) {
         continue;
       }
       if (D(n.text)) {
+        if (!e)
+          continue;
         let { css: u, ranges: o } = R(e, n.text, n.ranges);
         l.push({
           url: n.url,

package/dist/src/filter-entries.d.ts

@@ -1,3 +1,3 @@
 import { Coverage } from './parse-coverage.ts';
 import { Parser } from './types.ts';
-export declare function filter_coverage(coverage: Coverage[], parse_html: Parser): Coverage[];
+export declare function filter_coverage(coverage: Coverage[], parse_html?: Parser): Coverage[];

package/dist/src/index.d.ts

@@ -32,7 +32,7 @@ export type CoverageResult = CoverageData & {
  * 4. Calculate used/unused CSS bytes (fastest path, no inspection of the actual CSS needed)
  * 5. Calculate line-coverage, byte-coverage per stylesheet
  */
-export declare function calculate_coverage(coverage: Coverage[], parse_html: Parser): CoverageResult;
+export declare function calculate_coverage(coverage: Coverage[], parse_html?: Parser): CoverageResult;
 export type { Coverage, Range } from './parse-coverage.ts';
 export { parse_coverage } from './parse-coverage.ts';
 export type { Parser } from './types.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projectwallace/css-code-coverage",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "",
   "author": "Bart Veneman <bart@projectwallace.com>",
   "repository": {