hermex 2.0.2 → 2.1.0

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import { Command, Option } from "commander";
 import chalk from "chalk";
 import Table from "cli-table3";
-import fs, { existsSync, readFileSync } from "node:fs";
+import fs, { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import path, { dirname, join, resolve } from "node:path";
 import { z } from "zod";
@@ -158,7 +158,7 @@ function printComponentsChart(components) {
 //#endregion
 //#region src/utils/print-patterns.ts
 function printHeader$1() {
-	console.log(chalk.blue.bold("\n🔍 Code Patterns\n"));
+	console.log(chalk.blue.bold("\n🧩 Code Patterns\n"));
 }
 function printPatterns(aggregated, mode) {
 	const patterns = aggregated.patternCounts.filter((p) => p.count > 0);
@@ -233,10 +233,14 @@ function resolveColorLevel(opts) {
 	if (opts.noColorEnv !== void 0) return 0;
 }
 const ANSI_ESCAPE_PATTERN = /\x1b\[[0-9;]*m/g;
+/** Removes ANSI color escapes — for output destinations (files, PR comments) that can't render them. */
+function stripAnsi(text) {
+	return text.replace(ANSI_ESCAPE_PATTERN, "");
+}
 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);
+		return originalWrite(typeof chunk === "string" ? stripAnsi(chunk) : chunk, ...rest);
 	});
 }
 /**
@@ -266,6 +270,10 @@ function formatPackageName(pkg, banned) {
 	else if (pkg.internal) prefix += severityColor("warn")("[int] ");
 	return prefix + pkg.packageName;
 }
+function describeUpgradeTarget(top) {
+	const overdue = top.releasedDaysAgo > top.thresholdDays ? "no compliant release available" : formatDaysOverdue(top.breachReleasedDaysAgo, top.thresholdDays);
+	return `${top.semverBump} ${top.version} (${overdue})`;
+}
 function formatUpgradeCell(releaseAge) {
 	if (!releaseAge) return "";
 	const { worstLevel, upgrades, severity, pendingUpgrade } = releaseAge;
@@ -276,9 +284,9 @@ function formatUpgradeCell(releaseAge) {
 	const top = upgrades[0];
 	if (!top) return severityIcon("success");
 	const suffix = severity === "warn" ? chalk.gray(" [not enforced]") : "";
-	const overdue = top.releasedDaysAgo > top.thresholdDays ? "no compliant release available" : formatDaysOverdue(top.breachReleasedDaysAgo, 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}`;
+	const description = describeUpgradeTarget(top);
+	if (worstLevel === "major_overdue") return `${severityIcon(severity === "warn" ? "warn" : "error")} ${description}${suffix}`;
+	return `${severityIcon("warn")} ${description}${suffix}`;
 }
 function getBannedViolation(pkg, violations) {
 	return violations.find((v) => v.packageName === pkg.packageName);
@@ -296,13 +304,7 @@ function printPackagesTable(packages, violations) {
 		return;
 	}
 	const hasReleaseAge = packages.some((p) => p.releaseAge !== void 0);
-	const head = [
-		"Package",
-		"Version",
-		"Components",
-		"Usage",
-		"Percentage"
-	];
+	const head = ["Package", "Version"];
 	if (hasReleaseAge) head.push("Upgrades");
 	const table = new Table({
 		head,
@@ -313,20 +315,12 @@ function printPackagesTable(packages, violations) {
 	});
 	packages.forEach((pkg) => {
 		const versionCell = pkg.hasVersionConflict ? chalk.yellow(`⚠ ${pkg.allVersions.join(", ")} (${pkg.allVersions.length} versions — bundle impact)`) : pkg.version || "N/A";
-		const row = [
-			formatPackageName(pkg, getBannedViolation(pkg, violations)),
-			versionCell,
-			formatCount(pkg.componentCount),
-			formatCount(pkg.usageCount),
-			`${pkg.percentage.toFixed(1)}%`
-		];
+		const row = [formatPackageName(pkg, getBannedViolation(pkg, violations)), versionCell];
 		if (hasReleaseAge) row.push(formatUpgradeCell(pkg.releaseAge));
 		table.push(row);
 	});
 	console.log(table.toString());
-	const totalComponents = packages.reduce((sum, p) => sum + p.componentCount, 0);
-	const totalExternalUsage = packages.reduce((sum, p) => sum + p.usageCount, 0);
-	console.log(chalk.gray(`\nTotal: ${formatCount(packages.length)} packages | ${formatCount(totalComponents)} unique components | ${formatCount(totalExternalUsage)} total usages`));
+	console.log(chalk.gray(`\nTotal: ${formatCount(packages.length)} packages`));
 }
 function printPackagesChart(packages, violations) {
 	printHeader();
@@ -362,15 +356,14 @@ 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(`  ${formatTruncatedList(entry.components, "component")}`) : "";
-		console.log(`  ${name}  ${bar} ${pct} ${usage}${components}`);
+		console.log(`  ${name}  ${bar} ${pct} ${usage}`);
 	}
 	if (result.totalCount === 0) console.log(chalk.gray("  No usage detected for any package in this group."));
 	console.log();
 }
 function printVersus(aggregated) {
 	if (aggregated.versusResults.length === 0) return;
-	console.log(chalk.magentaBright.bold("\n⚖️  Versus\n"));
+	console.log(chalk.magentaBright.bold("\n⚖️ Versus\n"));
 	for (const result of aggregated.versusResults) printVersusResult(result);
 }
 //#endregion
@@ -417,11 +410,11 @@ function printRules(aggregated) {
 	const hasRuleViolations = ruleViolations.length > 0;
 	const hasBannedViolations = bannedPackageViolations.length > 0;
 	if (!hasRuleViolations && !hasBannedViolations) {
-		console.log(chalk.greenBright.bold(`\n${severityIcon("success")} Compliance\n`));
-		console.log(chalk.gray("  All compliance checks passed"));
+		console.log(chalk.greenBright.bold(`\n${severityIcon("success")} Rules\n`));
+		console.log(chalk.gray("  All rule checks passed"));
 		return;
 	}
-	console.log(chalk.blueBright.bold("\n🔍 Compliance\n"));
+	console.log(chalk.blueBright.bold("\n🔍 Rules\n"));
 	if (hasRuleViolations) for (const v of ruleViolations) console.log(formatViolationLine({
 		icon: severityIcon(v.severity),
 		label: formatRuleType(v.type),
@@ -2099,7 +2092,7 @@ function pickNewest(versions) {
 function upgradeLevel(daysAgo, bump, thresholds) {
 	const threshold = thresholds[bump];
 	if (threshold === false || threshold === void 0) return null;
-	if (daysAgo > threshold) return bump === "major" ? "mandatory_upgrade" : "needs_upgrade";
+	if (daysAgo > threshold) return bump === "major" ? "major_overdue" : "minor_overdue";
 	return null;
 }
 function computeReleaseAge(installedVersion, timeMap, deprecated, thresholds, distTags, severity) {
@@ -2145,14 +2138,12 @@ function computeReleaseAge(installedVersion, timeMap, deprecated, thresholds, di
 	const latestVersion = distTags?.["latest"];
 	const latestEntry = latestVersion ? timeMap[latestVersion] : void 0;
 	const latestReleasedDaysAgo = latestEntry ? daysSince(latestEntry) : void 0;
-	const hadInWindowCandidate = minCompliantVersion !== void 0;
-	if (!hadInWindowCandidate && latestVersion && latestReleasedDaysAgo !== void 0 && !semver.prerelease(latestVersion) && semver.gt(latestVersion, installedVersion)) {
+	if (!(minCompliantVersion !== void 0) && latestVersion && latestReleasedDaysAgo !== void 0 && !semver.prerelease(latestVersion) && semver.gt(latestVersion, installedVersion)) {
 		minCompliantVersion = latestVersion;
 		minCompliantReleasedDaysAgo = latestReleasedDaysAgo;
 	}
-	const compliantByLatestFallback = !hadInWindowCandidate && minCompliantVersion !== void 0;
 	for (const upgrade of finalUpgrades) if (latestVersion && upgrade.version === latestVersion) upgrade.isLatest = true;
-	const worstLevel = compliantByLatestFallback ? null : finalUpgrades.some((u) => u.level === "mandatory_upgrade") ? "mandatory_upgrade" : finalUpgrades.length > 0 ? "needs_upgrade" : null;
+	const worstLevel = finalUpgrades.some((u) => u.level === "major_overdue") ? "major_overdue" : finalUpgrades.length > 0 ? "minor_overdue" : null;
 	let pendingUpgrade;
 	if (worstLevel === null) for (const [bump, versions] of byBump.entries()) {
 		const threshold = thresholds[bump];
@@ -2239,20 +2230,20 @@ function isDeclarationFile(filePath) {
 */
 async function runPipeline(config, spinner, isJson) {
 	const lockfileResult = findAndParseLockfile(process.cwd());
-	spinner.succeed(chalk.blue(`📦 Found ${lockfileResult.lockfileType} lockfile (supports: ${lockfileResult.supportedVersions.join(", ")}) - ${Object.keys(lockfileResult.versions).length} packages`));
-	spinner.start("Finding files...");
+	spinner.succeed(chalk.blue(`Found ${lockfileResult.lockfileType} lockfile (supports: ${lockfileResult.supportedVersions.join(", ")}) - ${Object.keys(lockfileResult.versions).length} packages`));
+	if (spinner.isEnabled) spinner.start("Finding files...");
 	const files = (await findFiles(config.includes, config.excludes)).filter((f) => !isDeclarationFile(f));
 	if (files.length === 0) {
 		spinner.fail(chalk.red(`No files found matching includes: ${config.includes.join(", ")}`));
 		return null;
 	}
-	spinner.succeed(chalk.green(` Found ${files.length} files`));
-	spinner.start("Analyzing files...");
+	spinner.succeed(chalk.green(`Found ${files.length} files`));
+	if (spinner.isEnabled) spinner.start("Analyzing files...");
 	const reports = [];
 	const parseErrors = [];
 	for (let i = 0; i < files.length; i++) {
 		const file = files[i];
-		spinner.text = `Analyzing files... (${i + 1}/${files.length})`;
+		if (spinner.isEnabled) spinner.text = `Analyzing files... (${i + 1}/${files.length})`;
 		try {
 			const report = parseFile(file);
 			if (report) reports.push(report);
@@ -2270,10 +2261,10 @@ async function runPipeline(config, spinner, isJson) {
 	const evaluatorViolations = evaluateRules(process.cwd(), config.rules, config.excludes, files);
 	aggregated.ruleViolations = [...aggregated.ruleViolations, ...evaluatorViolations];
 	if (config.releaseAge.enabled) {
-		spinner.start("Fetching release age from registry...");
+		if (spinner.isEnabled) spinner.start("Fetching release age from registry...");
 		const { enriched, skipped } = await enrichWithReleaseAge(aggregated.packageDistribution, config.releaseAge);
 		aggregated.packageDistribution = enriched;
-		spinner.succeed(chalk.blue(`📅 Release age fetched${skipped > 0 ? chalk.gray(` (${skipped} packages skipped — registry unreachable or not found)`) : ""}`));
+		spinner.succeed(chalk.blue(`Release age fetched${skipped > 0 ? chalk.gray(` (${skipped} packages skipped — registry unreachable or not found)`) : ""}`));
 	}
 	return aggregated;
 }
@@ -2334,12 +2325,12 @@ function printScanResults(aggregated, config) {
 //#endregion
 //#region src/utils/print-compliance.ts
 /**
-* Prints only the bottom-line verdict — the Compliance and Packages sections
+* Prints only the bottom-line verdict — the Rules 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;
+	const mandatoryCount = result.errorRuleViolations.length + result.errorBannedPackageViolations.length + result.releaseAgeViolations.length;
 	if (result.compliant) {
 		console.log(chalk.greenBright.bold(`\n${severityIcon("success")} COMPLIANT\n`));
 		return;
@@ -2351,34 +2342,85 @@ function printComplianceVerdict(result) {
 //#endregion
 //#region src/utils/compliance.ts
 /**
-* A package is a mandatory compliance failure only when its releaseAge
-* severity is 'error' (i.e. it's in scope per `releaseAge.enforceOn`) AND
-* its worstLevel is 'mandatory_upgrade' — 'needs_upgrade' (patch/minor) is
-* advisory even for enforced packages, matching the existing "mandatory"
-* vocabulary already used by upgradeLevel().
+* A package is a compliance failure when its releaseAge severity is 'error'
+* (i.e. it's in scope per `releaseAge.enforceOn`) AND it has any breached
+* threshold at all (worstLevel is non-null) — both 'minor_overdue' and
+* 'major_overdue' fail comply for an enforced package; only severity
+* decides mandatory vs advisory, not which tier breached (#28).
 */
 function computeCompliance(aggregated) {
 	const errorRuleViolations = aggregated.ruleViolations.filter((v) => v.severity === "error");
 	const errorBannedPackageViolations = aggregated.bannedPackageViolations.filter((v) => v.severity === "error");
-	const mandatoryReleaseAgeViolations = aggregated.packageDistribution.filter((p) => p.releaseAge?.severity === "error" && p.releaseAge?.worstLevel === "mandatory_upgrade");
+	const releaseAgeViolations = aggregated.packageDistribution.filter((p) => p.releaseAge?.severity === "error" && p.releaseAge?.worstLevel !== null);
 	return {
-		compliant: errorRuleViolations.length === 0 && errorBannedPackageViolations.length === 0 && mandatoryReleaseAgeViolations.length === 0,
+		compliant: errorRuleViolations.length === 0 && errorBannedPackageViolations.length === 0 && releaseAgeViolations.length === 0,
 		errorRuleViolations,
 		errorBannedPackageViolations,
-		mandatoryReleaseAgeViolations
+		releaseAgeViolations
 	};
 }
 //#endregion
+//#region src/utils/write-summary-file.ts
+function buildRulesSection(aggregated) {
+	const ruleViolations = aggregated.ruleViolations.filter((v) => v.severity !== "info");
+	const bannedPackageViolations = aggregated.bannedPackageViolations.filter((v) => v.severity !== "info");
+	if (ruleViolations.length === 0 && bannedPackageViolations.length === 0) return "### Rules\n\nAll rule checks passed\n";
+	const lines = ["### Rules", ""];
+	for (const v of ruleViolations) lines.push(`- ${severityIcon(v.severity)} ${formatRuleType(v.type)} — ${describeViolation(v)}`);
+	for (const v of bannedPackageViolations) {
+		const msg = v.message ? ` — ${v.message}` : "";
+		lines.push(`- ${severityIcon(v.severity)} forbid_packages — ${v.packageName} is forbidden${msg}`);
+	}
+	const allViolations = [...ruleViolations, ...bannedPackageViolations];
+	const errorCount = allViolations.filter((v) => v.severity === "error").length;
+	const warnCount = allViolations.filter((v) => v.severity === "warn").length;
+	const parts = [];
+	if (errorCount > 0) parts.push(`${errorCount} error${errorCount > 1 ? "s" : ""}`);
+	if (warnCount > 0) parts.push(`${warnCount} warning${warnCount > 1 ? "s" : ""}`);
+	lines.push("", parts.join(", "));
+	return lines.join("\n") + "\n";
+}
+function buildPackagesSection(compliance) {
+	if (compliance.releaseAgeViolations.length === 0) return "";
+	const lines = ["### Packages", ""];
+	for (const pkg of compliance.releaseAgeViolations) {
+		const top = pkg.releaseAge?.upgrades[0];
+		const reasons = [];
+		if (top) reasons.push(describeUpgradeTarget(top));
+		if (pkg.releaseAge?.deprecated) reasons.push("deprecated");
+		lines.push(`- ${severityIcon("error")} ${pkg.packageName} — ${reasons.join(", ")}`);
+	}
+	return lines.join("\n") + "\n";
+}
+function buildVerdictSection(compliance) {
+	if (compliance.compliant) return `### ${severityIcon("success")} COMPLIANT\n`;
+	const mandatoryCount = compliance.errorRuleViolations.length + compliance.errorBannedPackageViolations.length + compliance.releaseAgeViolations.length;
+	return `### ${severityIcon("error")} NOT COMPLIANT\n\n${mandatoryCount} mandatory violation${mandatoryCount > 1 ? "s" : ""} found\n`;
+}
+/**
+* Writes a concise, ANSI-free markdown summary (rules, mandatory package
+* violations, verdict) for CI surfaces that can't render the full human
+* report — a sticky PR comment or job summary (#31). Omits Versus and
+* progress chrome by construction; never touches ora or the Versus renderer.
+*/
+function writeSummaryFile(path, aggregated, compliance) {
+	writeFileSync(path, stripAnsi([
+		buildRulesSection(aggregated),
+		buildPackagesSection(compliance),
+		buildVerdictSection(compliance)
+	].filter((section) => section.length > 0).join("\n")));
+}
+//#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)").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) => {
+	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)").option("--summary-file <path>", "Write a concise, ANSI-free markdown summary (rules, flagged packages, verdict) to this path, for a CI job summary or PR comment").action(async (options) => {
 		await executeComply(await loadConfig(process.cwd(), options.config), {
 			format: options.format,
 			color: options.color
-		});
+		}, options.summaryFile);
 	});
 }
-async function executeComply(config, contextOptions = {}) {
+async function executeComply(config, contextOptions = {}, summaryFile) {
 	const { isJson, spinner } = createCommandContext(config, contextOptions);
 	try {
 		const aggregated = await runPipeline(config, spinner, isJson);
@@ -2394,6 +2436,7 @@ async function executeComply(config, contextOptions = {}) {
 			if (config.output.versus) printVersus(aggregated);
 			printComplianceVerdict(compliance);
 		}
+		if (summaryFile) writeSummaryFile(summaryFile, aggregated, compliance);
 		process.exitCode = compliance.compliant ? 0 : 1;
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);