Merge branch 'main' into dependabot/npm_and_yarn/playwright/test-1.56.1

Author: bartveneman

package-lock.json

@@ -2,7 +2,7 @@ import { test, expect } from '@playwright/test'
 import { parse_arguments, validate_arguments } from './arguments'
 
 test.describe('--coverage-dir', () => {
-	let cov = '--min-line-coverage=1'
+	let cov = '--min-coverage=1'
 
 	test('missing --coverage-dir', () => {
 		expect(() => validate_arguments(parse_arguments([cov]))).toThrowError()
@@ -18,51 +18,51 @@ test.describe('--coverage-dir', () => {
 	})
 })
 
-test.describe('--min-line-coverage', () => {
+test.describe('--min-coverage', () => {
 	let dir = '--coverage-dir=coverage'
 
-	test('missing --min-line-coverage', () => {
+	test('missing --min-coverage', () => {
 		expect(() => validate_arguments(parse_arguments([dir]))).toThrowError()
 	})
 
-	test('empty --min-line-coverage', () => {
-		expect(() => validate_arguments(parse_arguments([dir, '--min-line-coverage']))).toThrowError()
+	test('empty --min-coverage', () => {
+		expect(() => validate_arguments(parse_arguments([dir, '--min-coverage']))).toThrowError()
 	})
 
-	test('invalid --min-line-coverage=-1', () => {
-		expect(() => validate_arguments(parse_arguments([dir, '--min-line-coverage=-1']))).toThrowError()
+	test('invalid --min-coverage=-1', () => {
+		expect(() => validate_arguments(parse_arguments([dir, '--min-coverage=-1']))).toThrowError()
 	})
 
-	test('valid --min-line-coverage=.8', () => {
-		let result = validate_arguments(parse_arguments([dir, '--min-line-coverage=.8']))
-		expect(result['min-line-coverage']).toEqual(0.8)
+	test('valid --min-coverage=.8', () => {
+		let result = validate_arguments(parse_arguments([dir, '--min-coverage=.8']))
+		expect(result['min-coverage']).toEqual(0.8)
 	})
 })
 
-test.describe('--min-file-line-coverage', () => {
-	let args = ['--coverage-dir=coverage', '--min-line-coverage=1']
+test.describe('--min-file-coverage', () => {
+	let args = ['--coverage-dir=coverage', '--min-coverage=1']
 
-	test('missing --min-file-line-coverage', () => {
+	test('missing --min-file-coverage', () => {
 		expect.soft(() => validate_arguments(parse_arguments([...args]))).not.toThrowError()
-		expect.soft(validate_arguments(parse_arguments([...args]))['min-file-line-coverage']).toEqual(0)
+		expect.soft(validate_arguments(parse_arguments([...args]))['min-file-coverage']).toEqual(0)
 	})
 
-	test('empty --min-file-line-coverage', () => {
-		expect.soft(() => validate_arguments(parse_arguments([...args, '--min-file-line-coverage']))).toThrowError()
+	test('empty --min-file-coverage', () => {
+		expect.soft(() => validate_arguments(parse_arguments([...args, '--min-file-coverage']))).toThrowError()
 	})
 
-	test('invalid --min-file-line-coverage=-1', () => {
-		expect(() => validate_arguments(parse_arguments([...args, '--min-file-line-coverage=-1']))).toThrowError()
+	test('invalid --min-file-coverage=-1', () => {
+		expect(() => validate_arguments(parse_arguments([...args, '--min-file-coverage=-1']))).toThrowError()
 	})
 
-	test('valid --min-file-line-coverage=.8', () => {
-		let result = validate_arguments(parse_arguments([...args, '--min-file-line-coverage=.8']))
-		expect(result['min-file-line-coverage']).toEqual(0.8)
+	test('valid --min-file-coverage=.8', () => {
+		let result = validate_arguments(parse_arguments([...args, '--min-file-coverage=.8']))
+		expect(result['min-file-coverage']).toEqual(0.8)
 	})
 })
 
 test.describe('--reporter', () => {
-	let args = ['--coverage-dir=coverage', '--min-line-coverage=1']
+	let args = ['--coverage-dir=coverage', '--min-coverage=1']
 
 	test('missing --reporter', () => {
 		expect.soft(() => validate_arguments(parse_arguments([...args]))).not.toThrowError()
@@ -89,7 +89,7 @@ test.describe('--reporter', () => {
 })
 
 test.describe('--show-uncovered', () => {
-	let args = ['--coverage-dir=coverage', '--min-line-coverage=1']
+	let args = ['--coverage-dir=coverage', '--min-coverage=1']
 
 	test('missing --show-uncovered', () => {
 		expect.soft(() => validate_arguments(parse_arguments([...args]))).not.toThrowError()

src/cli/arguments.test.ts

@@ -21,16 +21,16 @@ 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),
 })
 
 export type CliArguments = {
 	'coverage-dir': string
-	'min-line-coverage': number
-	'min-file-line-coverage'?: number
+	'min-coverage': number
+	'min-file-coverage'?: number
 	'show-uncovered': keyof typeof show_uncovered_options
 	reporter: keyof typeof reporters
 }
@@ -64,15 +64,14 @@ export function validate_arguments(args: ReturnType<typeof parse_arguments>): Cl
 export function parse_arguments(args: string[]) {
 	let { values } = parseArgs({
 		args,
-		allowPositionals: true,
 		options: {
 			'coverage-dir': {
 				type: 'string',
 			},
-			'min-line-coverage': {
+			'min-coverage': {
 				type: 'string',
 			},
-			'min-file-line-coverage': {
+			'min-file-coverage': {
 				type: 'string',
 				default: '0',
 			},

src/cli/arguments.ts

@@ -5,14 +5,19 @@ import { program } from './program.js'
 import { read } from './file-reader.js'
 import { print as pretty } from './reporters/pretty.js'
 import { print as tap } from './reporters/tap.js'
+import { help } from './help.js'
 
 async function cli(cli_args: string[]) {
+	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 = program(
 		{
-			min_file_coverage: params['min-line-coverage'],
-			min_file_line_coverage: params['min-file-line-coverage'],
+			min_coverage: params['min-coverage'],
+			min_file_coverage: params['min-file-coverage'],
 		},
 		coverage_data,
 	)

src/cli/cli.ts

@@ -0,0 +1,37 @@
+import { styleText } from 'node:util'
+
+export 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()
+}

src/cli/help.ts

@@ -12,31 +12,31 @@ let coverage = [
 ] satisfies Coverage[]
 
 test('returns context', () => {
-	let result = program({ min_file_coverage: 0.5 }, coverage)
+	let result = program({ min_coverage: 0.5 }, coverage)
 	expect.soft(result.context.coverage.covered_lines).toEqual(4)
 	expect.soft(result.context.coverage.total_files_found).toEqual(1)
 })
 
-test.describe('--min-file-coverage', () => {
-	test('Success: --min-file-coverage=0.5', () => {
-		let result = program({ min_file_coverage: 0.5 }, coverage)
+test.describe('--min-coverage', () => {
+	test('Success: --min-coverage=0.5', () => {
+		let result = program({ min_coverage: 0.5 }, coverage)
 		expect(result.report.ok).toBeTruthy()
 	})
 
-	test('Failure: --min-file-coverage=1', () => {
-		let result = program({ min_file_coverage: 1 }, coverage)
+	test('Failure: --min-coverage=1', () => {
+		let result = program({ min_coverage: 1 }, coverage)
 		expect(result.report.ok).toBeFalsy()
 	})
 })
 
-test.describe('--min-file-line-coverage', () => {
-	test('Success: --min-file-line-coverage=0.5', () => {
-		let result = program({ min_file_coverage: 0, min_file_line_coverage: 0.5 }, coverage)
+test.describe('--min-file-coverage', () => {
+	test('Success: --min-file-coverage=0.5', () => {
+		let result = program({ min_coverage: 0, min_file_coverage: 0.5 }, coverage)
 		expect(result.report.ok).toBeTruthy()
 	})
 
-	test('Failure: --min-file-line-coverage=1', () => {
-		let result = program({ min_file_coverage: 0, min_file_line_coverage: 1 }, coverage)
+	test('Failure: --min-file-coverage=1', () => {
+		let result = program({ min_coverage: 0, min_file_coverage: 1 }, coverage)
 		expect(result.report.ok).toBeFalsy()
 	})
 })

src/cli/program.test.ts

@@ -1,11 +1,5 @@
 import { calculate_coverage, type Coverage, type CoverageResult } from '../lib/index.js'
 
-class MissingDataError extends Error {
-	constructor() {
-		super('No data to analyze')
-	}
-}
-
 export type Report = {
 	context: {
 		coverage: CoverageResult
@@ -51,29 +45,29 @@ function validate_min_file_line_coverage(actual: number, expected: number | unde
 
 export function program(
 	{
+		min_coverage,
 		min_file_coverage,
-		min_file_line_coverage,
 	}: {
-		min_file_coverage: number
-		min_file_line_coverage?: number
+		min_coverage: number
+		min_file_coverage?: number
 	},
 	coverage_data: Coverage[],
 ) {
 	let coverage = 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(
+	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_line_coverage,
+		min_file_coverage,
 	)
 
 	let result: Report = {
 		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,
 		},
 	}
 

src/cli/program.ts

@@ -164,15 +164,23 @@ test.describe('only --min-line-coverage', () => {
 
 	test('failure', () => {
 		const report = {
-			...context_empty,
+			context: {
+				coverage: {
+					total_lines: 10_000,
+					covered_lines: 5022,
+				} as CoverageResult,
+			},
 			report: {
 				ok: false,
 				...min_line_coverage_failure,
 				...min_file_line_coverage_unset,
 			},
 		} satisfies Report
 		let result = print(report, show_none, dependencies)
-		expect(result).toEqual(['Failed: line coverage is 50.22%% which is lower than the threshold of 1'])
+		expect(result).toEqual([
+			'Failed: line coverage is 50.22%% which is lower than the threshold of 1',
+			'Tip: cover 4978 more lines to meet the threshold of 100%',
+		])
 	})
 })
 

src/cli/reporters/pretty.test.ts

@@ -29,10 +29,15 @@ export function print_lines({ report, context }: Report, params: CliArguments, {
 	if (report.min_line_coverage.ok) {
 		output.push(`${styleText(['bold', 'green'], 'Success')}: total line coverage is ${percentage(report.min_line_coverage.actual)}`)
 	} else {
+		let { actual, expected } = report.min_line_coverage
 		output.push(
-			`${styleText(['bold', 'red'], 'Failed')}: line coverage is ${percentage(
-				report.min_line_coverage.actual,
-			)}% which is lower than the threshold of ${report.min_line_coverage.expected}`,
+			`${styleText(['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,
+			)}`,
 		)
 	}
 
@@ -60,6 +65,9 @@ export function print_lines({ report, context }: Report, params: CliArguments, {
 		print_width = print_width ?? 80
 		let min_file_line_coverage = report.min_file_line_coverage.expected
 
+		// Show empty line between report header and chunks output
+		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') ||

src/cli/reporters/pretty.ts

@@ -10,6 +10,8 @@ export type ChunkedCoverage = Omit<Coverage, 'ranges'> & {
 	chunks: Chunk[]
 }
 
+const WHITESPACE_ONLY_REGEX = /^\s+$/
+
 function merge(stylesheet: ChunkedCoverage): ChunkedCoverage {
 	let new_chunks: Chunk[] = []
 	let previous_chunk: Chunk | undefined
@@ -18,7 +20,7 @@ function merge(stylesheet: ChunkedCoverage): ChunkedCoverage {
 		let chunk = stylesheet.chunks.at(i)!
 
 		// If the current chunk is only whitespace or empty, ignore it
-		if (/^\s+$/.test(stylesheet.text.slice(chunk.start_offset, chunk.end_offset))) {
+		if (WHITESPACE_ONLY_REGEX.test(stylesheet.text.slice(chunk.start_offset, chunk.end_offset))) {
 			continue
 		}
 
@@ -32,7 +34,10 @@ function merge(stylesheet: ChunkedCoverage): ChunkedCoverage {
 				continue
 			}
 			// If the current chunk is only whitespace or empty, add it to the previous
-			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
 				// do not update previous_chunk
 				continue