hermex 2.0.0-beta.9 → 2.0.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import chalk from "chalk";
 import Table from "cli-table3";
 import fs, { existsSync, readFileSync } from "node:fs";
@@ -27,6 +27,31 @@ import ora from "ora";
 function formatCount(num) {
 	return num.toLocaleString();
 }
+/**
+* Format how far an upgrade candidate is past its age threshold
+* @returns Formatted string (e.g., "40 days overdue", "1 day overdue")
+*/
+function formatDaysOverdue(releasedDaysAgo, thresholdDays) {
+	const overdue = releasedDaysAgo - thresholdDays;
+	return `${overdue} day${overdue === 1 ? "" : "s"} overdue`;
+}
+/**
+* Format how long until an upgrade candidate breaches its age threshold
+* @returns Formatted string (e.g., "12 days remaining", "1 day remaining")
+*/
+function formatDaysRemaining(daysRemaining) {
+	return `${daysRemaining} day${daysRemaining === 1 ? "" : "s"} remaining`;
+}
+/**
+* Join a list of items, showing only the first `limit` and summarizing the rest
+* @returns Formatted string (e.g., "a, b and 3 other files", "a, b and 1 other file")
+*/
+function formatTruncatedList(items, noun, limit = 2) {
+	const shown = items.slice(0, limit).join(", ");
+	const rest = items.length - limit;
+	if (rest <= 0) return shown;
+	return `${shown} and ${rest} other ${noun}${rest === 1 ? "" : "s"}`;
+}
 //#endregion
 //#region src/utils/print-summary.ts
 function printHeader$4() {
@@ -171,26 +196,88 @@ function printPatternsChart(patterns) {
 	})), { maxWidth: 50 });
 }
 //#endregion
+//#region src/utils/severity-format.ts
+const ICONS = {
+	error: "🔴",
+	warn: "🟡",
+	info: "🔵",
+	success: "🟢"
+};
+const COLORS = {
+	error: chalk.red,
+	warn: chalk.yellow,
+	info: chalk.blue,
+	success: chalk.green
+};
+/** Colored-circle glyph for a severity — carries meaning without relying on ANSI color. */
+function severityIcon(severity) {
+	return ICONS[severity];
+}
+/** chalk color function for a severity, for text that needs coloring. */
+function severityColor(severity) {
+	return COLORS[severity];
+}
+function formatViolationLine(opts) {
+	return `  ${opts.icon}  ${opts.label.padEnd(14)} ${opts.description}`;
+}
+/**
+* Resolves an explicit color-on/off override from CLI flags or the NO_COLOR
+* convention (https://no-color.org). Returns `undefined` when there's no
+* explicit signal, meaning chalk's own auto-detection should be left alone
+* (including its GitHub-Actions-aware detection of non-TTY streams).
+*/
+function resolveColorLevel(opts) {
+	if (opts.colorFlag === false) return 0;
+	if (opts.colorFlag === true) return 1;
+	if (opts.noColorEnv !== void 0) return 0;
+}
+const ANSI_ESCAPE_PATTERN = /\x1b\[[0-9;]*m/g;
+function stripAnsiWrites(stream) {
+	const originalWrite = stream.write.bind(stream);
+	stream.write = ((chunk, ...rest) => {
+		return originalWrite(typeof chunk === "string" ? chunk.replace(ANSI_ESCAPE_PATTERN, "") : chunk, ...rest);
+	});
+}
+/**
+* Beyond setting chalk's own level, this strips ANSI codes at the stream
+* boundary when color is explicitly disabled. hermex also prints through
+* cli-table3 and ora (whose spinner symbols come from log-symbols/yoctocolors)
+* — neither shares hermex's chalk instance or honors chalk.level, so mutating
+* chalk alone can't make NO_COLOR/--no-color hold for their output too.
+*/
+function applyColorLevel(level) {
+	if (level === void 0) return;
+	chalk.level = level;
+	if (level === 0) {
+		stripAnsiWrites(process.stdout);
+		stripAnsiWrites(process.stderr);
+	}
+}
+//#endregion
 //#region src/utils/print-packages.ts
 function printHeader() {
 	console.log(chalk.blueBright.bold("\n📦 Packages\n"));
 }
 function formatPackageName(pkg, banned) {
 	let prefix = "";
-	if (pkg.releaseAge?.deprecated) prefix += chalk.red("[DEPRECATED] ");
-	if (banned) prefix += banned.severity === "error" ? chalk.red("[BANNED] ") : chalk.yellow("[RESTRICTED] ");
-	else if (pkg.internal) prefix += chalk.yellow("[int] ");
+	if (pkg.releaseAge?.deprecated) prefix += severityColor("error")("[DEPRECATED] ");
+	if (banned) prefix += banned.severity === "error" ? severityColor("error")("[BANNED] ") : severityColor("warn")("[RESTRICTED] ");
+	else if (pkg.internal) prefix += severityColor("warn")("[int] ");
 	return prefix + pkg.packageName;
 }
 function formatUpgradeCell(releaseAge) {
 	if (!releaseAge) return "";
-	const { worstLevel, upgrades, severity } = releaseAge;
-	if (!worstLevel) return chalk.green("✓");
+	const { worstLevel, upgrades, severity, pendingUpgrade } = releaseAge;
+	if (!worstLevel) {
+		if (pendingUpgrade) return `${severityIcon("info")} ${pendingUpgrade.semverBump} ${pendingUpgrade.version} (${formatDaysRemaining(pendingUpgrade.daysRemaining)})`;
+		return severityIcon("success");
+	}
 	const top = upgrades[0];
-	if (!top) return chalk.green("✓");
+	if (!top) return severityIcon("success");
 	const suffix = severity === "warn" ? chalk.gray(" [not enforced]") : "";
-	if (worstLevel === "mandatory_upgrade") return (severity === "warn" ? chalk.yellow : chalk.red)(`⚠ ${top.semverBump} ${top.version} (${top.releasedDaysAgo}d)`) + suffix;
-	return chalk.yellow(`↑ ${top.semverBump} ${top.version} (${top.releasedDaysAgo}d)`) + suffix;
+	const overdue = formatDaysOverdue(top.releasedDaysAgo, top.thresholdDays);
+	if (worstLevel === "mandatory_upgrade") return `${severityIcon(severity === "warn" ? "warn" : "error")} ${top.semverBump} ${top.version} (${overdue})${suffix}`;
+	return `${severityIcon("warn")} ${top.semverBump} ${top.version} (${overdue})${suffix}`;
 }
 function getBannedViolation(pkg, violations) {
 	return violations.find((v) => v.packageName === pkg.packageName);
@@ -265,13 +352,6 @@ function renderBar(percentage) {
 	const empty = BAR_WIDTH - filled;
 	return chalk.cyan("█".repeat(filled)) + chalk.gray("░".repeat(empty));
 }
-function formatComponents(components, max = 3) {
-	if (components.length === 0) return "";
-	const shown = components.slice(0, max);
-	const rest = components.length - max;
-	const list = shown.join(", ");
-	return rest > 0 ? `${list} (+${rest} more)` : list;
-}
 function printVersusResult(result) {
 	console.log(chalk.bold(`  ${result.name}`));
 	console.log(chalk.gray(`  ${"─".repeat(50)}`));
@@ -281,7 +361,7 @@ function printVersusResult(result) {
 		const bar = renderBar(entry.percentage);
 		const pct = chalk.bold(`${entry.percentage.toFixed(1)}%`);
 		const usage = chalk.gray(`(${entry.count} usages)`);
-		const components = entry.components.length > 0 ? chalk.gray(`  ${formatComponents(entry.components)}`) : "";
+		const components = entry.components.length > 0 ? chalk.gray(`  ${formatTruncatedList(entry.components, "component")}`) : "";
 		console.log(`  ${name}  ${bar} ${pct} ${usage}${components}`);
 	}
 	if (result.totalCount === 0) console.log(chalk.gray("  No usage detected for any package in this group."));
@@ -298,30 +378,23 @@ function formatRuleType(type) {
 	switch (type) {
 		case "detect_files": return "detect_files";
 		case "require_files": return "require_files";
-		case "forbid_packages": return "forbid_packages";
 		case "require_packages": return "require_packages";
 		case "require_scripts": return "require_scripts";
-		case "require_package_fields": return "pkg_fields";
-		case "forbid_package_fields": return "pkg_fields";
+		case "require_package_fields": return "package_fields";
+		case "forbid_package_fields": return "package_fields";
 		case "engine_version": return "engine_version";
 		case "codeowners": return "codeowners";
 	}
 }
-function ruleIcon(violation) {
-	if (violation.severity === "error") return chalk.red("✗");
-	if (violation.severity === "info") return chalk.blue("ℹ");
-	return chalk.yellow("⚠");
-}
 function describeViolation(v) {
 	const patterns = v.patterns.join(", ");
 	const suffix = v.message ? chalk.gray(` — ${v.message}`) : "";
-	if (v.type === "detect_files") return `${patterns} detected (${v.matchedFiles.map((f) => {
+	if (v.type === "detect_files") return `${patterns} detected (${formatTruncatedList(v.matchedFiles.map((f) => {
 		const parts = f.replace(/\\/g, "/").split("/");
 		return parts[parts.length - 1];
-	}).join(", ")})${suffix}`;
+	}), "file")})${suffix}`;
 	if (v.type === "require_files") return `${patterns} not found${suffix}`;
 	if (v.type === "require_packages") return `${patterns} not installed${suffix}`;
-	if (v.type === "forbid_packages") return `${patterns} is forbidden${suffix}`;
 	if (v.type === "require_scripts") return `script ${patterns} missing in package.json${suffix}`;
 	if (v.type === "require_package_fields") {
 		if (v.fieldPath && v.actualValue !== void 0) return `field ${v.fieldPath} is ${chalk.yellow(v.actualValue)}, does not match required value${suffix}`;
@@ -334,9 +407,7 @@ function describeViolation(v) {
 	}
 	if (v.type === "codeowners") {
 		if (v.matchedFiles.length === 0) return `CODEOWNERS not found (looked in ${patterns})${suffix}`;
-		const shown = v.matchedFiles.slice(0, 3).join(", ");
-		const more = v.matchedFiles.length > 3 ? ` and ${v.matchedFiles.length - 3} more` : "";
-		return `${v.matchedFiles.length} scanned file(s) have no owner: ${shown}${more}${suffix}`;
+		return `${v.matchedFiles.length} scanned file(s) have no owner: ${formatTruncatedList(v.matchedFiles, "file")}${suffix}`;
 	}
 	return `${patterns} not present${suffix}`;
 }
@@ -345,25 +416,23 @@ function printRules(aggregated) {
 	const hasRuleViolations = ruleViolations.length > 0;
 	const hasBannedViolations = bannedPackageViolations.length > 0;
 	if (!hasRuleViolations && !hasBannedViolations) {
-		console.log(chalk.greenBright.bold("\n✓ Compliance\n"));
+		console.log(chalk.greenBright.bold(`\n${severityIcon("success")} Compliance\n`));
 		console.log(chalk.gray("  All compliance checks passed"));
 		return;
 	}
 	console.log(chalk.blueBright.bold("\n🔍 Compliance\n"));
-	if (hasRuleViolations) for (const v of ruleViolations) {
-		const icon = ruleIcon(v);
-		const type = chalk.gray(formatRuleType(v.type).padEnd(14));
-		const severityTag = v.severity === "error" ? chalk.red("[ERROR]") : v.severity === "info" ? chalk.blue("[INFO]") : chalk.yellow("[WARN]");
-		console.log(`  ${icon}  ${type} ${describeViolation(v)}  ${severityTag}`);
-	}
-	if (hasBannedViolations) {
-		if (hasRuleViolations) console.log();
-		for (const v of bannedPackageViolations) {
-			const icon = v.severity === "error" ? chalk.red("✗") : chalk.yellow("⚠");
-			const tag = v.severity === "error" ? chalk.red("[BANNED]") : chalk.yellow("[RESTRICTED]");
-			const msg = v.message ? chalk.gray(` — ${v.message}`) : "";
-			console.log(`  ${icon}  ${tag} ${v.packageName}${msg}`);
-		}
+	if (hasRuleViolations) for (const v of ruleViolations) console.log(formatViolationLine({
+		icon: severityIcon(v.severity),
+		label: formatRuleType(v.type),
+		description: describeViolation(v)
+	}));
+	if (hasBannedViolations) for (const v of bannedPackageViolations) {
+		const msg = v.message ? chalk.gray(` — ${v.message}`) : "";
+		console.log(formatViolationLine({
+			icon: severityIcon(v.severity),
+			label: "forbid_packages",
+			description: `${v.packageName} is forbidden${msg}`
+		}));
 	}
 	const errorCount = [...ruleViolations.filter((v) => v.severity === "error"), ...bannedPackageViolations.filter((v) => v.severity === "error")].length;
 	const warnCount = [...ruleViolations.filter((v) => v.severity === "warn"), ...bannedPackageViolations.filter((v) => v.severity === "warn")].length;
@@ -2003,6 +2072,9 @@ function classifyBump(installed, candidate) {
 	if (diff === "major" || diff === "premajor") return "major";
 	return null;
 }
+function pickNewest(versions) {
+	return versions.reduce((a, b) => a.daysAgo < b.daysAgo ? a : b);
+}
 function upgradeLevel(daysAgo, bump, thresholds) {
 	const threshold = thresholds[bump];
 	if (threshold === false || threshold === void 0) return null;
@@ -2037,12 +2109,13 @@ function computeReleaseAge(installedVersion, timeMap, deprecated, thresholds, di
 	for (const [bump, versions] of byBump.entries()) {
 		const level = upgradeLevel(Math.max(...versions.map((v) => v.daysAgo)), bump, thresholds);
 		if (!level) continue;
-		const newest = versions.reduce((a, b) => a.daysAgo < b.daysAgo ? a : b);
+		const newest = pickNewest(versions);
 		upgrades.push({
 			version: newest.version,
 			releasedDaysAgo: newest.daysAgo,
 			semverBump: bump,
-			level
+			level,
+			thresholdDays: thresholds[bump]
 		});
 	}
 	const finalUpgrades = upgrades.sort((a, b) => b.releasedDaysAgo - a.releasedDaysAgo);
@@ -2050,10 +2123,29 @@ function computeReleaseAge(installedVersion, timeMap, deprecated, thresholds, di
 	const latestEntry = latestVersion ? timeMap[latestVersion] : void 0;
 	const latestReleasedDaysAgo = latestEntry ? daysSince(latestEntry) : void 0;
 	for (const upgrade of finalUpgrades) if (latestVersion && upgrade.version === latestVersion) upgrade.isLatest = true;
+	const worstLevel = finalUpgrades.some((u) => u.level === "mandatory_upgrade") ? "mandatory_upgrade" : finalUpgrades.length > 0 ? "needs_upgrade" : null;
+	let pendingUpgrade;
+	if (worstLevel === null) for (const [bump, versions] of byBump.entries()) {
+		const threshold = thresholds[bump];
+		if (threshold === false || threshold === void 0) continue;
+		const daysRemaining = threshold - Math.max(...versions.map((v) => v.daysAgo));
+		if (daysRemaining <= 0) continue;
+		if (!pendingUpgrade || daysRemaining < pendingUpgrade.daysRemaining) {
+			const newest = pickNewest(versions);
+			pendingUpgrade = {
+				version: newest.version,
+				semverBump: bump,
+				releasedDaysAgo: newest.daysAgo,
+				thresholdDays: threshold,
+				daysRemaining
+			};
+		}
+	}
 	return {
 		installedVersion,
 		upgrades: finalUpgrades,
-		worstLevel: finalUpgrades.some((u) => u.level === "mandatory_upgrade") ? "mandatory_upgrade" : finalUpgrades.length > 0 ? "needs_upgrade" : null,
+		worstLevel,
+		pendingUpgrade,
 		deprecated,
 		latestVersion,
 		latestReleasedDaysAgo,
@@ -2162,8 +2254,12 @@ async function runPipeline(config, spinner, isJson) {
 * Shared command preamble: routes human-readable chrome (version line,
 * spinner) to stderr when the command emits JSON on stdout.
 */
-function createCommandContext(config) {
-	const isJson = config.output.format === "json";
+function createCommandContext(config, options = {}) {
+	applyColorLevel(resolveColorLevel({
+		colorFlag: options.color === false ? false : void 0,
+		noColorEnv: process.env["NO_COLOR"]
+	}));
+	const isJson = (options.format ?? config.output.format) === "json";
 	const stream = isJson ? process.stderr : process.stdout;
 	stream.write(chalk.gray(`hermex v${getVersion()}\n`));
 	return {
@@ -2177,12 +2273,15 @@ function createCommandContext(config) {
 //#endregion
 //#region src/commands/scan.ts
 function registerScanCommand(program) {
-	program.command("scan").description("Scan and analyze local files").option("--config <path>", "Path to hermex config file (overrides CWD discovery)").action(async (options) => {
-		await executeScan(await loadConfig(process.cwd(), options.config));
+	program.command("scan").description("Scan and analyze local files").option("--config <path>", "Path to hermex config file (overrides CWD discovery)").addOption(new Option("--format <format>", "Output format, overrides output.format in the config file").choices(["human", "json"])).option("--no-color", "Disable colored output (see also NO_COLOR env var)").action(async (options) => {
+		await executeScan(await loadConfig(process.cwd(), options.config), {
+			format: options.format,
+			color: options.color
+		});
 	});
 }
-async function executeScan(config) {
-	const { isJson, spinner } = createCommandContext(config);
+async function executeScan(config, contextOptions = {}) {
+	const { isJson, spinner } = createCommandContext(config, contextOptions);
 	try {
 		const aggregated = await runPipeline(config, spinner, isJson);
 		if (!aggregated) return;
@@ -2205,21 +2304,19 @@ function printScanResults(aggregated, config) {
 }
 //#endregion
 //#region src/utils/print-compliance.ts
+/**
+* Prints only the bottom-line verdict — the Compliance and Packages sections
+* printed above this already itemize every violation (rule and release-age
+* alike), so repeating them here would just restate the same 🔴 rows.
+*/
 function printComplianceVerdict(result) {
 	const mandatoryCount = result.errorRuleViolations.length + result.errorBannedPackageViolations.length + result.mandatoryReleaseAgeViolations.length;
 	if (result.compliant) {
-		console.log(chalk.greenBright.bold("\n✓ COMPLIANT\n"));
+		console.log(chalk.greenBright.bold(`\n${severityIcon("success")} COMPLIANT\n`));
 		return;
 	}
-	console.log(chalk.redBright.bold(`\n✗ NOT COMPLIANT`));
+	console.log(chalk.redBright.bold(`\n${severityIcon("error")} NOT COMPLIANT`));
 	console.log(chalk.red(`  ${mandatoryCount} mandatory violation${mandatoryCount > 1 ? "s" : ""} found`));
-	if (result.mandatoryReleaseAgeViolations.length > 0) {
-		console.log();
-		for (const pkg of result.mandatoryReleaseAgeViolations) {
-			const top = pkg.releaseAge?.upgrades[0];
-			console.log(chalk.red(`  ✗  releaseAge     ${pkg.packageName} is ${top?.semverBump} version behind (${top?.releasedDaysAgo}d) — mandatory upgrade  [ERROR]`));
-		}
-	}
 	console.log();
 }
 //#endregion
@@ -2245,12 +2342,15 @@ function computeCompliance(aggregated) {
 //#endregion
 //#region src/commands/comply.ts
 function registerComplyCommand(program) {
-	program.command("comply").description("Check compliance with hermex.config.ts rules and release-age policy (exits non-zero if not compliant)").option("--config <path>", "Path to hermex config file (overrides CWD discovery)").action(async (options) => {
-		await executeComply(await loadConfig(process.cwd(), options.config));
+	program.command("comply").description("Check compliance with hermex.config.ts rules and release-age policy (exits non-zero if not compliant)").option("--config <path>", "Path to hermex config file (overrides CWD discovery)").addOption(new Option("--format <format>", "Output format, overrides output.format in the config file").choices(["human", "json"])).option("--no-color", "Disable colored output (see also NO_COLOR env var)").action(async (options) => {
+		await executeComply(await loadConfig(process.cwd(), options.config), {
+			format: options.format,
+			color: options.color
+		});
 	});
 }
-async function executeComply(config) {
-	const { isJson, spinner } = createCommandContext(config);
+async function executeComply(config, contextOptions = {}) {
+	const { isJson, spinner } = createCommandContext(config, contextOptions);
 	try {
 		const aggregated = await runPipeline(config, spinner, isJson);
 		if (!aggregated) {
@@ -2262,6 +2362,7 @@ async function executeComply(config) {
 		else {
 			printRules(aggregated);
 			if (config.releaseAge.enabled) printPackages(aggregated, "table");
+			if (config.output.versus) printVersus(aggregated);
 			printComplianceVerdict(compliance);
 		}
 		process.exitCode = compliance.compliant ? 0 : 1;