@projectwallace/css-code-coverage 0.6.0 → 0.8.0

package/README.md

@@ -53,7 +53,7 @@ let coverage = await page.coverage.stopCSSCoverage()
 // Now we can process it
 import { calculate_coverage } from '@projectwallace/css-code-coverage'
 
-let report = await calculcate_coverage(coverage)
+let report = calculcate_coverage(coverage)
 ```
 
 ### Browser devtools

package/dist/cli.js

@@ -13,7 +13,8 @@ const show_uncovered_options = {
 };
 const reporters = {
 	pretty: "pretty",
-	tap: "tap"
+	tap: "tap",
+	json: "json"
 };
 let CoverageDirSchema = v.pipe(v.string(), v.nonEmpty());
 let RatioPercentageSchema = v.pipe(v.string(), v.transform(Number), v.number(), v.minValue(0), v.maxValue(1));
@@ -21,8 +22,8 @@ let ShowUncoveredSchema = v.pipe(v.string(), v.enum(show_uncovered_options));
 let ReporterSchema = v.pipe(v.string(), v.enum(reporters));
 let CliArgumentsSchema = v.object({
 	"coverage-dir": CoverageDirSchema,
-	"min-line-coverage": RatioPercentageSchema,
-	"min-file-line-coverage": v.optional(RatioPercentageSchema),
+	"min-coverage": RatioPercentageSchema,
+	"min-file-coverage": v.optional(RatioPercentageSchema),
 	"show-uncovered": v.optional(ShowUncoveredSchema, show_uncovered_options.violations),
 	reporter: v.optional(ReporterSchema, reporters.pretty)
 });
@@ -44,11 +45,10 @@ function validate_arguments(args) {
 function parse_arguments(args) {
 	let { values } = parseArgs({
 		args,
-		allowPositionals: true,
 		options: {
 			"coverage-dir": { type: "string" },
-			"min-line-coverage": { type: "string" },
-			"min-file-line-coverage": {
+			"min-coverage": { type: "string" },
+			"min-file-coverage": {
 				type: "string",
 				default: "0"
 			},
@@ -90,19 +90,20 @@ function parse_coverage(input) {
 
 //#endregion
 //#region src/lib/chunkify.ts
+const WHITESPACE_ONLY_REGEX = /^\s+$/;
 function merge(stylesheet) {
 	let new_chunks = [];
 	let previous_chunk;
 	for (let i = 0; i < stylesheet.chunks.length; i++) {
 		let chunk = stylesheet.chunks.at(i);
-		if (/^\s+$/.test(stylesheet.text.slice(chunk.start_offset, chunk.end_offset))) continue;
+		if (WHITESPACE_ONLY_REGEX.test(stylesheet.text.slice(chunk.start_offset, chunk.end_offset))) continue;
 		let latest_chunk = new_chunks.at(-1);
 		if (i > 0 && previous_chunk && latest_chunk) {
 			if (previous_chunk.is_covered === chunk.is_covered) {
 				latest_chunk.end_offset = chunk.end_offset;
 				previous_chunk = chunk;
 				continue;
-			} else if (/^\s+$/.test(stylesheet.text.slice(chunk.start_offset, chunk.end_offset)) || chunk.end_offset === chunk.start_offset) {
+			} else if (WHITESPACE_ONLY_REGEX.test(stylesheet.text.slice(chunk.start_offset, chunk.end_offset)) || chunk.end_offset === chunk.start_offset) {
 				latest_chunk.end_offset = chunk.end_offset;
 				continue;
 			}
@@ -152,10 +153,10 @@ function prettify(stylesheet) {
 	let line = 1;
 	let offset = 0;
 	let pretty_chunks = stylesheet.chunks.map((chunk, index) => {
-		let css = format(stylesheet.text.slice(chunk.start_offset, chunk.end_offset - 1)).trim();
+		let css = format(stylesheet.text.substring(chunk.start_offset, chunk.end_offset - 1)).trim();
 		if (chunk.is_covered) {
-			let is_last = index === stylesheet.chunks.length - 1;
-			if (index === 0) css = css + (is_last ? "" : "\n");
+			let is_last_chunk = index === stylesheet.chunks.length - 1;
+			if (index === 0) css = css + (is_last_chunk ? "" : "\n");
 			else if (index === stylesheet.chunks.length - 1) css = "\n" + css;
 			else css = "\n" + css + "\n";
 		}
@@ -185,65 +186,46 @@ function prettify(stylesheet) {
 
 //#endregion
 //#region src/lib/decuplicate.ts
-function concatenate(ranges) {
-	let result = [];
-	for (let range of ranges) if (result.length > 0 && (result.at(-1).end === range.start - 1 || result.at(-1).end === range.start)) result.at(-1).end = range.end;
-	else result.push(range);
-	return result;
-}
-function dedupe_list(ranges) {
-	let new_ranges = /* @__PURE__ */ new Set();
-	outer: for (let range of ranges) {
-		for (let processed_range of new_ranges) {
-			if (range.start <= processed_range.start && range.end >= processed_range.end) {
-				new_ranges.delete(processed_range);
-				new_ranges.add(range);
-				continue outer;
-			}
-			if (range.start >= processed_range.start && range.end <= processed_range.end) continue outer;
-			if (range.start < processed_range.end && range.start > processed_range.start && range.end > processed_range.end) {
-				new_ranges.delete(processed_range);
-				new_ranges.add({
-					start: processed_range.start,
-					end: range.end
-				});
-				continue outer;
-			}
+function merge_ranges(ranges) {
+	if (ranges.length === 0) return [];
+	ranges.sort((a, b) => a.start - b.start);
+	let merged = [ranges[0]];
+	for (let r of ranges.slice(1)) {
+		let last = merged.at(-1);
+		if (last && r.start <= last.end + 1) {
+			if (r.end > last.end) last.end = r.end;
+		} else merged.push({
+			start: r.start,
+			end: r.end
+		});
+	}
+	return merged;
+}
+function merge_entry_ranges(sheet, entry) {
+	if (!sheet) return {
+		url: entry.url,
+		ranges: [...entry.ranges]
+	};
+	let seen = new Set(sheet.ranges.map((r) => `${r.start}:${r.end}`));
+	for (let range of entry.ranges) {
+		let id = `${range.start}:${range.end}`;
+		if (!seen.has(id)) {
+			seen.add(id);
+			sheet.ranges.push({ ...range });
 		}
-		new_ranges.add(range);
 	}
-	return new_ranges;
+	return sheet;
 }
-/**
-* @description
-* prerequisites
-* - we check each stylesheet content only once (to avoid counting the same content multiple times)
-* - if a duplicate stylesheet enters the room, we add it's ranges to the existing stylesheet's ranges
-* - only bytes of deduplicated stylesheets are counted
-*/
 function deduplicate_entries(entries) {
-	let checked_stylesheets = /* @__PURE__ */ new Map();
-	for (let entry of entries) {
-		let text = entry.text;
-		if (checked_stylesheets.has(text)) {
-			let ranges = checked_stylesheets.get(text).ranges;
-			for (let range of entry.ranges) {
-				let found = false;
-				for (let checked_range of ranges) if (checked_range.start === range.start && checked_range.end === range.end) {
-					found = true;
-					break;
-				}
-				if (!found) ranges.push(range);
-			}
-		} else checked_stylesheets.set(text, {
-			url: entry.url,
-			ranges: entry.ranges
-		});
-	}
-	return Array.from(checked_stylesheets, ([text, { url, ranges }]) => ({
+	let grouped = entries.reduce((acc, entry) => {
+		let key = entry.text;
+		acc[key] = merge_entry_ranges(acc[key], entry);
+		return acc;
+	}, Object.create(null));
+	return Object.entries(grouped).map(([text, { url, ranges }]) => ({
 		text,
 		url,
-		ranges: concatenate(dedupe_list(ranges.sort((a, b) => a.start - b.start))).sort((a, b) => a.start - b.start)
+		ranges: merge_ranges(ranges)
 	}));
 }
 
@@ -259,15 +241,43 @@ function ext(url) {
 	}
 }
 
+//#endregion
+//#region src/lib/html-parser.ts
+/**
+* @description
+* Very, very naive but effective DOMParser.
+* It can only find <style> elements and their .textContent
+*/
+var DOMParser = class {
+	parseFromString(html, _type) {
+		let styles = [];
+		let lower = html.toLowerCase();
+		let pos = 0;
+		while (true) {
+			let open = lower.indexOf("<style", pos);
+			if (open === -1) break;
+			let start = lower.indexOf(">", open);
+			if (start === -1) break;
+			let close = lower.indexOf("</style>", start);
+			if (close === -1) break;
+			let text = html.slice(start + 1, close);
+			styles.push({ textContent: text });
+			pos = close + 8;
+		}
+		return { querySelectorAll(selector) {
+			return styles;
+		} };
+	}
+};
+
 //#endregion
 //#region src/lib/remap-html.ts
-async function get_dom_parser() {
+function get_dom_parser() {
 	if (typeof window !== "undefined" && "DOMParser" in window) return new window.DOMParser();
-	let { DOMParser } = await import("./esm--VCpEgdH.js");
 	return new DOMParser();
 }
-async function remap_html(html, old_ranges) {
-	let doc = (await get_dom_parser()).parseFromString(html, "text/html");
+function remap_html(html, old_ranges) {
+	let doc = get_dom_parser().parseFromString(html, "text/html");
 	let combined_css = "";
 	let new_ranges = [];
 	let current_offset = 0;
@@ -295,31 +305,44 @@ async function remap_html(html, old_ranges) {
 function is_html(text) {
 	return /<\/?(html|body|head|div|span|script|style)/i.test(text);
 }
-async function filter_coverage(coverage) {
-	let result = [];
-	for (let entry of coverage) {
-		let extension = ext(entry.url).toLowerCase();
-		if (extension === "js") continue;
-		if (extension === "css") {
-			result.push(entry);
-			continue;
-		}
-		if (is_html(entry.text)) {
-			let { css, ranges } = await remap_html(entry.text, entry.ranges);
-			result.push({
-				url: entry.url,
-				text: css,
-				ranges
-			});
-			continue;
-		}
-		result.push({
+const SELECTOR_REGEX = /(@[a-z-]+|\[[^\]]+\]|[a-zA-Z_#.-][a-zA-Z0-9_-]*)\s*\{/;
+const DECLARATION_REGEX = /^\s*[a-zA-Z-]+\s*:\s*.+;?\s*$/m;
+function is_css_like(text) {
+	return SELECTOR_REGEX.test(text) || DECLARATION_REGEX.test(text);
+}
+function is_js_like(text) {
+	try {
+		new Function(text);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function filter_coverage(acc, entry) {
+	let extension = ext(entry.url).toLowerCase();
+	if (extension === "js") return acc;
+	if (extension === "css") {
+		acc.push(entry);
+		return acc;
+	}
+	if (is_html(entry.text)) {
+		let { css, ranges } = remap_html(entry.text, entry.ranges);
+		acc.push({
+			url: entry.url,
+			text: css,
+			ranges
+		});
+		return acc;
+	}
+	if (is_css_like(entry.text) && !is_js_like(entry.text)) {
+		acc.push({
 			url: entry.url,
 			text: entry.text,
 			ranges: entry.ranges
 		});
+		return acc;
 	}
-	return result;
+	return acc;
 }
 
 //#endregion
@@ -327,38 +350,37 @@ async function filter_coverage(coverage) {
 const AT_SIGN = 64;
 const LONGEST_ATRULE_NAME = 28;
 function extend_ranges(coverage) {
-	return coverage.map(({ text, ranges, url }) => {
-		return {
-			text,
-			ranges: ranges.map((range, index) => {
-				let prev_range = ranges[index - 1];
-				for (let i = range.start; i >= range.start - LONGEST_ATRULE_NAME; i--) {
-					if (prev_range && prev_range.end > i) break;
-					let char_position = i;
-					if (text.charCodeAt(char_position) === AT_SIGN) {
-						range.start = char_position;
-						let next_offset = range.end;
-						let next_char$1 = text.charAt(next_offset);
-						while (/\s/.test(next_char$1)) {
-							next_offset++;
-							next_char$1 = text.charAt(next_offset);
-						}
-						if (next_char$1 === "{") range.end = range.end + 1;
-						break;
+	let { ranges, url, text } = coverage;
+	return {
+		text,
+		ranges: ranges.map((range, index) => {
+			let prev_range = ranges[index - 1];
+			for (let i = range.start; i >= range.start - LONGEST_ATRULE_NAME; i--) {
+				if (prev_range && prev_range.end > i) break;
+				let char_position = i;
+				if (text.charCodeAt(char_position) === AT_SIGN) {
+					range.start = char_position;
+					let next_offset = range.end;
+					let next_char$1 = text.charAt(next_offset);
+					while (/\s/.test(next_char$1)) {
+						next_offset++;
+						next_char$1 = text.charAt(next_offset);
 					}
+					if (next_char$1 === "{") range.end = range.end + 1;
+					break;
 				}
-				let offset = range.end;
-				let next_char = text.charAt(offset);
-				while (/\s/.test(next_char)) {
-					offset++;
-					next_char = text.charAt(offset);
-				}
-				if (next_char === "}") range.end = offset + 1;
-				return range;
-			}),
-			url
-		};
-	});
+			}
+			let offset = range.end;
+			let next_char = text.charAt(offset);
+			while (/\s/.test(next_char)) {
+				offset++;
+				next_char = text.charAt(offset);
+			}
+			if (next_char === "}") range.end = offset + 1;
+			return range;
+		}),
+		url
+	};
 }
 
 //#endregion
@@ -401,20 +423,9 @@ function calculate_stylesheet_coverage({ text, url, chunks }) {
 		chunks
 	};
 }
-/**
-* @description
-* CSS Code Coverage calculation
-*
-* These are the steps performed to calculate coverage:
-* 1. Filter eligible files / validate input
-* 2. Prettify the CSS dicovered in each Coverage and update their ranges
-* 3. De-duplicate Coverages: merge all ranges for CSS sources occurring multiple times
-* 4. Calculate used/unused CSS bytes (fastest path, no inspection of the actual CSS needed)
-* 5. Calculate line-coverage, byte-coverage per stylesheet
-*/
-async function calculate_coverage(coverage) {
+function calculate_coverage(coverage) {
 	let total_files_found = coverage.length;
-	let coverage_per_stylesheet = extend_ranges(deduplicate_entries(await filter_coverage(coverage))).map((sheet) => chunkify(sheet)).map((sheet) => prettify(sheet)).map((stylesheet) => calculate_stylesheet_coverage(stylesheet));
+	let coverage_per_stylesheet = coverage.reduce((acc, entry) => filter_coverage(acc, entry), []).reduce((entries, entry) => deduplicate_entries(entries.concat(entry)), []).map((coverage$1) => extend_ranges(coverage$1)).map((sheet) => chunkify(sheet)).map((sheet) => prettify(sheet)).map((stylesheet) => calculate_stylesheet_coverage(stylesheet));
 	let { total_lines, total_covered_lines, total_uncovered_lines, total_bytes, total_used_bytes, total_unused_bytes } = coverage_per_stylesheet.reduce((totals, sheet) => {
 		totals.total_lines += sheet.total_lines;
 		totals.total_covered_lines += sheet.covered_lines;
@@ -448,11 +459,6 @@ async function calculate_coverage(coverage) {
 
 //#endregion
 //#region src/cli/program.ts
-var MissingDataError = class extends Error {
-	constructor() {
-		super("No data to analyze");
-	}
-};
 function validate_min_line_coverage(actual, expected) {
 	return {
 		ok: actual >= expected,
@@ -472,17 +478,16 @@ function validate_min_file_line_coverage(actual, expected) {
 		expected
 	};
 }
-async function program({ min_file_coverage, min_file_line_coverage }, coverage_data) {
-	if (coverage_data.length === 0) throw new MissingDataError();
-	let coverage = await calculate_coverage(coverage_data);
-	let min_line_coverage_result = validate_min_line_coverage(coverage.line_coverage_ratio, min_file_coverage);
-	let min_file_line_coverage_result = validate_min_file_line_coverage(Math.min(...coverage.coverage_per_stylesheet.map((sheet) => sheet.line_coverage_ratio)), min_file_line_coverage);
+function program({ min_coverage, min_file_coverage }, coverage_data) {
+	let coverage = calculate_coverage(coverage_data);
+	let min_coverage_result = validate_min_line_coverage(coverage.line_coverage_ratio, min_coverage);
+	let min_file_coverage_result = validate_min_file_line_coverage(Math.min(...coverage.coverage_per_stylesheet.map((sheet) => sheet.line_coverage_ratio)), min_file_coverage);
 	return {
 		context: { coverage },
 		report: {
-			ok: min_line_coverage_result.ok && min_file_line_coverage_result.ok,
-			min_line_coverage: min_line_coverage_result,
-			min_file_line_coverage: min_file_line_coverage_result
+			ok: min_coverage_result.ok && min_file_coverage_result.ok,
+			min_line_coverage: min_coverage_result,
+			min_file_line_coverage: min_file_coverage_result
 		}
 	};
 }
@@ -506,43 +511,61 @@ async function read(coverage_dir) {
 function indent(line) {
 	return (line || "").replace(/^\t+/, (tabs) => " ".repeat(tabs.length * 4));
 }
-function print({ report, context }, params) {
-	if (report.min_line_coverage.ok) console.log(`${styleText(["bold", "green"], "Success")}: total line coverage is ${(report.min_line_coverage.actual * 100).toFixed(2)}%`);
-	else console.error(`${styleText(["bold", "red"], "Failed")}: line coverage is ${(report.min_line_coverage.actual * 100).toFixed(2)}% which is lower than the threshold of ${report.min_line_coverage.expected}`);
+let line_number = (num, covered = true) => `${num.toString().padStart(5, " ")} ${covered ? "│" : "━"} `;
+function percentage(ratio$1, decimals = 2) {
+	return `${(ratio$1 * 100).toFixed(ratio$1 === 1 ? 0 : decimals)}%`;
+}
+function print_lines({ report, context }, params, { styleText: styleText$1, print_width }) {
+	let output = [];
+	if (report.min_line_coverage.ok) output.push(`${styleText$1(["bold", "green"], "Success")}: total line coverage is ${percentage(report.min_line_coverage.actual)}`);
+	else {
+		let { actual, expected } = report.min_line_coverage;
+		output.push(`${styleText$1(["bold", "red"], "Failed")}: line coverage is ${percentage(actual)}% which is lower than the threshold of ${expected}`);
+		let lines_to_cover = expected * context.coverage.total_lines - context.coverage.covered_lines;
+		output.push(`Tip: cover ${Math.ceil(lines_to_cover)} more ${lines_to_cover === 1 ? "line" : "lines"} to meet the threshold of ${percentage(expected)}`);
+	}
 	if (report.min_file_line_coverage.expected !== void 0) {
 		let { expected, actual, ok: ok$1 } = report.min_file_line_coverage;
-		if (ok$1) console.log(`${styleText(["bold", "green"], "Success")}: all files pass minimum line coverage of ${expected * 100}%`);
+		if (ok$1) output.push(`${styleText$1(["bold", "green"], "Success")}: all files pass minimum line coverage of ${percentage(expected)}`);
 		else {
 			let num_files_failed = context.coverage.coverage_per_stylesheet.filter((sheet) => sheet.line_coverage_ratio < expected).length;
-			console.error(`${styleText(["bold", "red"], "Failed")}: ${num_files_failed} files do not meet the minimum line coverage of ${expected * 100}% (minimum coverage was ${(actual * 100).toFixed(2)}%)`);
-			if (params["show-uncovered"] === "none") console.log(`  Hint: set --show-uncovered=violations to see which files didn't pass`);
+			output.push(`${styleText$1(["bold", "red"], "Failed")}: ${num_files_failed} ${num_files_failed === 1 ? "file does" : "files do"} not meet the minimum line coverage of ${percentage(expected)} (minimum coverage was ${percentage(actual)})`);
+			if (params["show-uncovered"] === "none") output.push(`  Hint: set --show-uncovered=violations to see which files didn't pass`);
 		}
 	}
 	if (params["show-uncovered"] !== "none") {
 		const NUM_LEADING_LINES = 3;
 		const NUM_TRAILING_LINES = NUM_LEADING_LINES;
-		let terminal_width = process.stdout.columns || 80;
-		let line_number = (num, covered = true) => `${num.toString().padStart(5, " ")} ${covered ? "│" : "━"} `;
+		print_width = print_width ?? 80;
 		let min_file_line_coverage = report.min_file_line_coverage.expected;
+		output.push();
 		for (let sheet of context.coverage.coverage_per_stylesheet.sort((a, b) => a.line_coverage_ratio - b.line_coverage_ratio)) if (sheet.line_coverage_ratio !== 1 && params["show-uncovered"] === "all" || min_file_line_coverage !== void 0 && min_file_line_coverage !== 0 && sheet.line_coverage_ratio < min_file_line_coverage && params["show-uncovered"] === "violations") {
-			console.log();
-			console.log(styleText("dim", "─".repeat(terminal_width)));
-			console.log(sheet.url);
-			console.log(`Coverage: ${(sheet.line_coverage_ratio * 100).toFixed(2)}%, ${sheet.covered_lines}/${sheet.total_lines} lines covered`);
+			output.push();
+			output.push(styleText$1("dim", "─".repeat(print_width)));
+			output.push(sheet.url);
+			output.push(`Coverage: ${percentage(sheet.line_coverage_ratio)}, ${sheet.covered_lines}/${sheet.total_lines} lines covered`);
 			if (min_file_line_coverage && min_file_line_coverage !== 0 && sheet.line_coverage_ratio < min_file_line_coverage) {
 				let lines_to_cover = min_file_line_coverage * sheet.total_lines - sheet.covered_lines;
-				console.log(`Tip: cover ${Math.ceil(lines_to_cover)} more lines to meet the file threshold of ${min_file_line_coverage * 100}%`);
+				output.push(`Tip: cover ${Math.ceil(lines_to_cover)} more ${lines_to_cover === 1 ? "line" : "lines"} to meet the file threshold of ${percentage(min_file_line_coverage)}`);
 			}
-			console.log(styleText("dim", "─".repeat(terminal_width)));
+			output.push(styleText$1("dim", "─".repeat(print_width)));
 			let lines = sheet.text.split("\n");
 			for (let chunk of sheet.chunks.filter((chunk$1) => !chunk$1.is_covered)) {
-				for (let x = Math.max(chunk.start_line - NUM_LEADING_LINES, 0); x < chunk.start_line; x++) console.log(styleText("dim", line_number(x)), styleText("dim", indent(lines[x - 1])));
-				for (let i = chunk.start_line; i <= chunk.end_line; i++) console.log(styleText("red", line_number(i, false)), indent(lines[i - 1]));
-				for (let y = chunk.end_line; y < Math.min(chunk.end_line + NUM_TRAILING_LINES, lines.length); y++) console.log(styleText("dim", line_number(y)), styleText("dim", indent(lines[y - 1])));
-				console.log();
+				for (let x = Math.max(chunk.start_line - NUM_LEADING_LINES, 1); x < chunk.start_line; x++) output.push([styleText$1("dim", line_number(x)), styleText$1("dim", indent(lines[x - 1]))].join(""));
+				for (let i = chunk.start_line; i <= chunk.end_line; i++) output.push([styleText$1("red", line_number(i, false)), indent(lines[i - 1])].join(""));
+				for (let y = chunk.end_line + 1; y < Math.min(chunk.end_line + NUM_TRAILING_LINES, lines.length); y++) output.push([styleText$1("dim", line_number(y)), styleText$1("dim", indent(lines[y - 1]))].join(""));
+				output.push();
 			}
 		}
 	}
+	return output;
+}
+function print(report, params) {
+	let logger = report.report.ok ? console.log : console.error;
+	for (let line of print_lines(report, params, {
+		styleText,
+		print_width: process.stdout.columns
+	})) logger(line);
 }
 
 //#endregion
@@ -557,7 +580,7 @@ function ok(n, description) {
 	console.log(`ok ${n} ${description ? `- ${description}` : ""}`);
 }
 function not_ok(n, description) {
-	console.log(`not ok ${n} ${description ? `- ${description}` : ""}`);
+	console.error(`not ok ${n} ${description ? `- ${description}` : ""}`);
 }
 function meta(data) {
 	console.log("  ---");
@@ -601,18 +624,80 @@ function print$1({ report, context }, params) {
 	}
 }
 
+//#endregion
+//#region src/cli/reporters/json.ts
+function prepare({ report, context }, params) {
+	context.coverage.coverage_per_stylesheet = context.coverage.coverage_per_stylesheet.filter((sheet) => {
+		if (params["show-uncovered"] === "violations" && report.min_file_line_coverage.expected !== void 0 && sheet.line_coverage_ratio < report.min_file_line_coverage.expected) return true;
+		if (params["show-uncovered"] === "all" && sheet.line_coverage_ratio < 1) return true;
+		return false;
+	});
+	return {
+		report,
+		context
+	};
+}
+function print$2({ report, context }, params) {
+	let logger = report.ok ? console.log : console.error;
+	let data = prepare({
+		context,
+		report
+	}, params);
+	logger(JSON.stringify(data));
+}
+
+//#endregion
+//#region src/cli/help.ts
+function help() {
+	return `
+${styleText(["bold"], "USAGE")}
+  $ css-coverage --coverage-dir=<dir> --min-coverage=<number> [options]
+
+${styleText("bold", "OPTIONS")}
+Required:
+  --coverage-dir        Where your Coverage JSON files are
+  --min-coverage        Minimum overall CSS coverage [0-1]
+
+Optional:
+  --min-file-coverage   Minimal coverage per file [0-1]
+
+  --show-uncovered      Which files to show when not meeting 
+                        the --min-file-line-coverage threshold
+                        • violations [default] ${styleText("dim", "show under-threshold files")}
+                        • all ${styleText("dim", "show partially covered files")}
+                        • none ${styleText("dim", "do not show files")}
+
+  --reporter            How to show the results 
+                        • pretty [default]
+                        • tap
+                        • json
+
+${styleText("bold", "EXAMPLES")}
+  ${styleText("dim", "# analyze all .json files in ./coverage; require 80% overall coverage")}
+  $ css-coverage --coverage-dir=./coverage --min-coverage=0.8
+
+  ${styleText("dim", "# Require 50% coverage per file")}
+  $ css-coverage --coverage-dir=./coverage --min-coverage=0.8 --min-file-coverage=0.5
+
+  ${styleText("dim", "Report JSON")}
+  $ css-coverage --coverage-dir=./coverage --min-coverage=0.8 --reporter=json
+  `.trim();
+}
+
 //#endregion
 //#region src/cli/cli.ts
 async function cli(cli_args) {
+	if (!cli_args || cli_args.length === 0 || cli_args.includes("--help") || cli_args.includes("-h")) return console.log(help());
 	let params = validate_arguments(parse_arguments(cli_args));
 	let coverage_data = await read(params["coverage-dir"]);
-	let report = await program({
-		min_file_coverage: params["min-line-coverage"],
-		min_file_line_coverage: params["min-file-line-coverage"]
+	let report = program({
+		min_coverage: params["min-coverage"],
+		min_file_coverage: params["min-file-coverage"]
 	}, coverage_data);
 	if (report.report.ok === false) process.exitCode = 1;
-	if (params.reporter === "pretty") print(report, params);
-	else if (params.reporter === "tap") print$1(report, params);
+	if (params.reporter === "tap") return print$1(report, params);
+	if (params.reporter === "json") return print$2(report, params);
+	return print(report, params);
 }
 try {
 	await cli(process.argv.slice(2));

package/dist/index.d.ts

@@ -63,17 +63,6 @@ type CoverageResult = CoverageData & {
   total_stylesheets: number;
   coverage_per_stylesheet: StylesheetCoverage[];
 };
-/**
- * @description
- * CSS Code Coverage calculation
- *
- * These are the steps performed to calculate coverage:
- * 1. Filter eligible files / validate input
- * 2. Prettify the CSS dicovered in each Coverage and update their ranges
- * 3. De-duplicate Coverages: merge all ranges for CSS sources occurring multiple times
- * 4. Calculate used/unused CSS bytes (fastest path, no inspection of the actual CSS needed)
- * 5. Calculate line-coverage, byte-coverage per stylesheet
- */
-declare function calculate_coverage(coverage: Coverage[]): Promise<CoverageResult>;
+declare function calculate_coverage(coverage: Coverage[]): CoverageResult;
 //#endregion
 export { type Coverage, CoverageData, CoverageResult, type Range, StylesheetCoverage, calculate_coverage, parse_coverage };