@projectwallace/css-code-coverage 0.1.3 → 0.2.1

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,14 +20,32 @@ 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')
+}
+
+let report = calculcate_coverage(coverage_data, parse_html)
+```
+
+See [src/index.ts](https://github.com/projectwallace/css-code-coverage/blob/main/src/index.ts) for the data that's returned.
+
+## Collecting CSS Coverage
+
+There are two principal ways of collecting CSS Coverage data:
+
+### Browser devtools
 
-You have collected browser coverage data of your CSS. There are several ways to do this:
+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.  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.
+- 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/
 
-Either way you end up with one or more JSON files that contain coverage data.
+Additionally, DevTools Tips writes about it in their [explainer](https://devtoolstips.org/tips/en/detect-unused-code/).
+
+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
@@ -47,19 +68,31 @@ for (let file of files) {
 }
 ```
 
-### Bringing it together
+### Coverage API
+
+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')
+}
 
-See [src/index.ts](https://github.com/projectwallace/css-code-coverage/blob/main/src/index.ts) for the data that's returned.
+let report = calculcate_coverage(coverage, parse_html)
+```
 
 ### Optional: coverage from `<style>` blocks
 
-Covergae 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:
+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
@@ -67,7 +100,7 @@ Covergae generators also create coverage ranges for `<style>` blocks in HTML. If
     	return new DOMParser().parseFromString(html, 'text/html')
     }
     ```
-1.  Node (using [linkedom](https://github.com/WebReflection/linkedom) in this example):
+1.  Node (using [linkedom](https://github.com/WebReflection/linkedom) in this example, but other parsers could work, too):
 
     ```ts
     // $ npm install linkedom

package/dist/css-code-coverage.js

@@ -1,98 +1,98 @@
-import * as v from "valibot";
-import { format as q } from "@projectwallace/format-css";
-import { tokenTypes as b, tokenize as N } from "css-tree/tokenizer";
-let z = v.array(
-  v.object({
-    text: v.optional(v.string()),
-    url: v.string(),
-    ranges: v.array(
-      v.object({
-        start: v.number(),
-        end: v.number()
+import * as h from "valibot";
+import { format as F } from "@projectwallace/format-css";
+import { tokenTypes as x, tokenize as $ } from "css-tree/tokenizer";
+let J = h.array(
+  h.object({
+    text: h.optional(h.string()),
+    url: h.string(),
+    ranges: h.array(
+      h.object({
+        start: h.number(),
+        end: h.number()
       })
     )
   })
 );
-function T(t) {
-  return v.safeParse(z, t).success;
+function q(t) {
+  return h.safeParse(J, t).success;
 }
-function Q(t) {
+function X(t) {
   try {
     let e = JSON.parse(t);
-    return T(e) ? e : [];
+    return q(e) ? e : [];
   } catch {
     return [];
   }
 }
-function F(t) {
-  return t.map(({ url: e, text: l, ranges: n }) => {
-    if (!l)
-      return { url: e, text: l, ranges: n };
-    let d = q(l), u = /* @__PURE__ */ new Set([
-      b.EOF,
-      b.BadString,
-      b.BadUrl,
-      b.WhiteSpace,
-      b.Semicolon,
-      b.Comment,
-      b.Colon
-    ]), o = n.map(({ start: i, end: s }) => ({ start: i, end: s, tokens: [] }));
-    function p(i, s) {
-      let r = 0;
-      for (let _ of o) {
-        if (_.start > s) return -1;
-        if (_.start <= i && _.end >= s)
-          return r;
-        r++;
+function P(t) {
+  return t.map(({ url: e, text: s, ranges: r }) => {
+    if (!s)
+      return { url: e, text: s, ranges: r };
+    let c = F(s), f = /* @__PURE__ */ new Set([
+      x.EOF,
+      x.BadString,
+      x.BadUrl,
+      x.WhiteSpace,
+      x.Semicolon,
+      x.Comment,
+      x.Colon
+    ]), o = r.map(({ start: a, end: i }) => ({ start: a, end: i, tokens: [] }));
+    function v(a, i) {
+      let l = 0;
+      for (let u of o) {
+        if (u.start > i) return -1;
+        if (u.start <= a && u.end >= i)
+          return l;
+        l++;
       }
       return -1;
     }
-    let a = 0;
-    N(l, (i, s, r) => {
-      if (u.has(i)) return;
-      a++, i === b.Url && (a += 2);
-      let _ = p(s, r);
-      _ !== -1 && o[_].tokens.push(a);
+    let _ = 0;
+    $(s, (a, i, l) => {
+      if (f.has(a)) return;
+      _++, a === x.Url && (_ += 2);
+      let u = v(i, l);
+      u !== -1 && o[u].tokens.push(_);
     });
-    let c = /* @__PURE__ */ new Map();
-    a = 0, N(d, (i, s, r) => {
-      u.has(i) || (a++, i === b.Url && (a += 2), c.set(a, { start: s, end: r }));
+    let g = /* @__PURE__ */ new Map();
+    _ = 0, $(c, (a, i, l) => {
+      f.has(a) || (_++, a === x.Url && (_ += 2), g.set(_, { start: i, end: l }));
     });
-    let g = [];
-    for (let i of o) {
-      let s = c.get(i.tokens.at(0)), r = c.get(i.tokens.at(-1));
-      s !== void 0 && r !== void 0 && g.push({
-        start: s.start,
-        end: r.end
+    let y = [];
+    for (let a of o) {
+      let i = g.get(a.tokens.at(0)), l = g.get(a.tokens.at(-1));
+      i !== void 0 && l !== void 0 && y.push({
+        start: i.start,
+        end: l.end
       });
     }
-    return { url: e, text: d, ranges: g };
+    return { url: e, text: c, ranges: y };
   });
 }
-function J(t) {
+function R(t) {
   let e = /* @__PURE__ */ new Map();
-  for (let l of t) {
-    let n = l.text || "";
-    if (e.has(n)) {
-      let u = e.get(n).ranges;
-      for (let o of l.ranges) {
-        let p = !1;
-        for (let a of u)
-          if (a.start === o.start && a.end === o.end) {
-            p = !0;
+  for (let s of t) {
+    let r = s.text || "";
+    if (e.has(r)) {
+      let f = e.get(r).ranges;
+      for (let o of s.ranges) {
+        let v = !1;
+        for (let _ of f)
+          if (_.start === o.start && _.end === o.end) {
+            v = !0;
             break;
           }
-        p || u.push(o);
+        v || f.push(o);
       }
     } else
-      e.set(n, {
-        url: l.url,
-        ranges: l.ranges
+      e.set(r, {
+        url: s.url,
+        ranges: s.ranges
       });
   }
   return e;
 }
-function P(t) {
+function D(t) {
   try {
     let e = new URL(t);
     return e.pathname.slice(e.pathname.lastIndexOf(".") + 1);
@@ -101,102 +101,123 @@ function P(t) {
     return t.slice(e, t.indexOf("/", e) + 1);
   }
 }
-function R(t, e, l) {
-  let n = t(e), d = "", u = [], o = 0, p = n.querySelectorAll("style");
-  for (let a of Array.from(p)) {
-    let c = a.textContent;
-    if (!c.trim()) continue;
-    d += c;
-    let g = e.indexOf(c), i = g + c.length;
-    for (let s of l)
-      s.start >= g && s.end <= i && u.push({
-        start: o + (s.start - g),
-        end: o + (s.end - g)
+function G(t, e, s) {
+  let r = t(e), c = "", f = [], o = 0, v = r.querySelectorAll("style");
+  for (let _ of Array.from(v)) {
+    let g = _.textContent;
+    if (!g.trim()) continue;
+    c += g;
+    let y = e.indexOf(g), a = y + g.length;
+    for (let i of s)
+      i.start >= y && i.end <= a && f.push({
+        start: o + (i.start - y),
+        end: o + (i.end - y)
       });
-    o += c.length;
+    o += g.length;
   }
   return {
-    css: d,
-    ranges: u
+    css: c,
+    ranges: f
   };
 }
-function D(t) {
+function H(t) {
   return /<\/?(html|body|head|div|span|script|style)/i.test(t);
 }
-function G(t, e) {
-  let l = [];
-  for (let n of t) {
-    if (!n.text) continue;
-    let d = P(n.url).toLowerCase();
-    if (d !== "js") {
-      if (d === "css") {
-        l.push(n);
+function K(t, e) {
+  let s = [];
+  for (let r of t) {
+    if (!r.text) continue;
+    let c = D(r.url).toLowerCase();
+    if (c !== "js") {
+      if (c === "css") {
+        s.push(r);
         continue;
       }
-      if (D(n.text)) {
+      if (H(r.text)) {
         if (!e)
           continue;
-        let { css: u, ranges: o } = R(e, n.text, n.ranges);
-        l.push({
-          url: n.url,
-          text: u,
+        let { css: f, ranges: o } = G(e, r.text, r.ranges);
+        s.push({
+          url: r.url,
+          text: f,
           ranges: o
         });
         continue;
       }
-      l.push({
-        url: n.url,
-        text: n.text,
-        ranges: n.ranges
+      s.push({
+        url: r.url,
+        text: r.text,
+        ranges: r.ranges
       });
     }
   }
-  return l;
+  return s;
 }
-function A(t, e) {
+function j(t, e) {
   return e === 0 ? 0 : t / e;
 }
-function V(t, e) {
-  let l = t.length;
-  if (!T(t))
+function Y(t, e) {
+  let s = t.length;
+  if (!q(t))
     throw new TypeError("No valid coverage data found");
-  let n = G(t, e), d = F(n), u = J(d), o = Array.from(u).map(([r, { url: _, ranges: E }]) => {
-    function I(f, y) {
-      let m = y + f.length, L = m + 1, U = /^\s*$/.test(f), x = f.endsWith("}");
-      if (!U && !x) {
-        for (let h of E)
-          if (!(h.start > m || h.end < y)) {
-            if (h.start <= y && h.end >= m)
+  let r = K(t, e), c = P(r), f = R(c), o = Array.from(f).map(([l, { url: u, ranges: L }]) => {
+    function M(n, d) {
+      let b = d + n.length, N = b + 1, W = /^\s*$/.test(n), k = n.endsWith("}");
+      if (!W && !k) {
+        for (let m of L)
+          if (!(m.start > b || m.end < d)) {
+            if (m.start <= d && m.end >= b)
               return !0;
-            if (f.startsWith("@") && h.start > y && h.start < L)
+            if (n.startsWith("@") && m.start > d && m.start < N)
               return !0;
           }
       }
       return !1;
     }
-    let w = r.split(`
-`), S = w.length, W = new Uint8Array(S), O = 0, j = r.length, C = 0, B = 0;
-    for (let f = 0; f < w.length; f++) {
-      let y = w[f], m = B, U = B + y.length + 1, x = /^\s*$/.test(y), h = y.endsWith("}"), $ = I(y, m), k = !1, M = f > 0 && W[f - 1] === 1;
-      ($ && !h && !x || (x || h) && M || x && !M && I(w[f + 1], U)) && (k = !0), W[f] = k ? 1 : 0, k && (O++, C += y.length + 1), B = U;
+    let S = l.split(`
+`), O = S.length, p = new Uint8Array(O), C = 0, B = l.length, U = 0, E = 0;
+    for (let n = 0; n < S.length; n++) {
+      let d = S[n], b = E, W = E + d.length + 1, k = /^\s*$/.test(d), m = d.endsWith("}"), z = M(d, b), w = !1, T = n > 0 && p[n - 1] === 1;
+      (z && !m && !k || (k || m) && T || k && !T && M(S[n + 1], W)) && (w = !0), p[n] = w ? 1 : 0, w && (C++, U += d.length + 1), E = W;
+    }
+    let A = [
+      {
+        start_line: 1,
+        is_covered: p[0] === 1,
+        end_line: 0,
+        total_lines: 0
+      }
+    ];
+    for (let n = 0; n < p.length; n++) {
+      let d = p[n];
+      if (n > 0 && d !== p[n - 1]) {
+        let b = A.at(-1);
+        b.end_line = n, b.total_lines = n - b.start_line + 1, A.push({
+          start_line: n,
+          is_covered: d === 1,
+          end_line: n,
+          total_lines: 0
+        });
+      }
     }
-    return {
-      url: _,
-      text: r,
-      ranges: E,
-      unused_bytes: j - C,
-      used_bytes: C,
-      total_bytes: j,
-      line_coverage_ratio: A(O, S),
-      byte_coverage_ratio: A(C, j),
-      line_coverage: W,
-      total_lines: S,
-      covered_lines: O,
-      uncovered_lines: S - O
-      // TODO: { is_covered: boolean, start_offset: number, start_line: number, end_offset: number, end_line: number }[]
+    let I = A.at(-1);
+    return I.total_lines = p.length - I.start_line + 1, I.end_line = p.length, {
+      url: u,
+      text: l,
+      ranges: L,
+      unused_bytes: B - U,
+      used_bytes: U,
+      total_bytes: B,
+      line_coverage_ratio: j(C, O),
+      byte_coverage_ratio: j(U, B),
+      line_coverage: p,
+      total_lines: O,
+      covered_lines: C,
+      uncovered_lines: O - C,
+      chunks: A
     };
-  }), { total_lines: p, total_covered_lines: a, total_uncovered_lines: c, total_bytes: g, total_used_bytes: i, total_unused_bytes: s } = o.reduce(
-    (r, _) => (r.total_lines += _.total_lines, r.total_covered_lines += _.covered_lines, r.total_uncovered_lines += _.uncovered_lines, r.total_bytes += _.total_bytes, r.total_used_bytes += _.used_bytes, r.total_unused_bytes += _.unused_bytes, r),
+  }), { total_lines: v, total_covered_lines: _, total_uncovered_lines: g, total_bytes: y, total_used_bytes: a, total_unused_bytes: i } = o.reduce(
+    (l, u) => (l.total_lines += u.total_lines, l.total_covered_lines += u.covered_lines, l.total_uncovered_lines += u.uncovered_lines, l.total_bytes += u.total_bytes, l.total_used_bytes += u.used_bytes, l.total_unused_bytes += u.unused_bytes, l),
     {
       total_lines: 0,
       total_covered_lines: 0,
@@ -207,20 +228,20 @@ function V(t, e) {
     }
   );
   return {
-    total_files_found: l,
-    total_bytes: g,
-    total_lines: p,
-    used_bytes: i,
-    covered_lines: a,
-    unused_bytes: s,
-    uncovered_lines: c,
-    byte_coverage_ratio: A(i, g),
-    line_coverage_ratio: A(a, p),
+    total_files_found: s,
+    total_bytes: y,
+    total_lines: v,
+    used_bytes: a,
+    covered_lines: _,
+    unused_bytes: i,
+    uncovered_lines: g,
+    byte_coverage_ratio: j(a, y),
+    line_coverage_ratio: j(_, v),
     coverage_per_stylesheet: o,
     total_stylesheets: o.length
   };
 }
 export {
-  V as calculate_coverage,
-  Q as parse_coverage
+  Y as calculate_coverage,
+  X as parse_coverage
 };

package/dist/src/index.d.ts

@@ -15,6 +15,12 @@ export type StylesheetCoverage = CoverageData & {
     text: string;
     ranges: Range[];
     line_coverage: Uint8Array;
+    chunks: {
+        is_covered: boolean;
+        start_line: number;
+        end_line: number;
+        total_lines: number;
+    }[];
 };
 export type CoverageResult = CoverageData & {
     total_files_found: number;

package/package.json

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