@docker-doctor/cli 0.5.3 → 0.6.1

package/README.md

@@ -14,7 +14,7 @@
 
 Your Dockerfiles are probably wrong. Docker Doctor finds out why.
 
-Docker Doctor is an opinionated static analysis tool for Dockerfile and Docker Compose files. It scans your project, runs 31 rules across security, performance, best practices, Compose, and image size — then gives you a health score and fix guidance.
+Docker Doctor is an opinionated static analysis tool for Dockerfile and Docker Compose files. It scans your project, runs 33 rules across security, performance, best practices, Compose, and image size — then gives you a health score and fix guidance.
 
 Works with any project that uses Docker.
 

package/dist/cli.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_src = require('./src-D4rVJg36.cjs');
+const require_src = require('./src-C7XK6Kp-.cjs');
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_src.__toESM(node_fs_promises, 1);
 let node_path = require("node:path");
@@ -587,8 +587,13 @@ const writeDiagnosticsDirectory = async (diagnostics, report, rootDir) => {
 			...d,
 			file: sanitizePath(d.file),
 			message: sanitizeMessage(d.message)
+		})),
+		failures: report.failures.map((failure) => ({
+			file: sanitizePath(failure.file),
+			message: sanitizeMessage(failure.message)
 		}))
 	};
+	await node_fs_promises.default.writeFile(node_path.default.join(dir, ".gitignore"), "*\n", "utf-8");
 	await node_fs_promises.default.writeFile(node_path.default.join(dir, "diagnostics.json"), JSON.stringify({
 		note: TRUST_BOUNDARY_NOTE,
 		...sanitizedReport
@@ -659,6 +664,7 @@ const buildHandoffPayload = (input) => {
 	const ruleWord = groups.length === 1 ? "rule" : "rules";
 	const lines = [
 		`Fix the ${issueCount} Docker Doctor ${issueWord} (${groups.length} ${ruleWord}) in ${sanitizePath(input.projectName)}.`,
+		`Every path below is relative to ${sanitizePath(input.projectDir)}. Work from that directory.`,
 		TRUST_BOUNDARY_NOTE,
 		""
 	];
@@ -723,8 +729,11 @@ const detectLaunchableAgents = () => {
 
 //#endregion
 //#region src/agents/launch-agent.ts
-const launchAgent = (agentId, prompt) => new Promise((resolve) => {
-	const child = (0, node_child_process.spawn)(AGENT_BINARIES[agentId], [...AGENT_AUTO_FLAGS[agentId], prompt], { stdio: "inherit" });
+const launchAgent = (agentId, prompt, cwd) => new Promise((resolve) => {
+	const child = (0, node_child_process.spawn)(AGENT_BINARIES[agentId], [...AGENT_AUTO_FLAGS[agentId], prompt], {
+		cwd,
+		stdio: "inherit"
+	});
 	child.once("error", () => {
 		resolve(false);
 	});
@@ -778,9 +787,9 @@ const printDiscoveredFiles = (project) => {
 	console.log(`  Dockerfile(s): ${project.dockerfiles.length ? project.dockerfiles.map((f) => chalk.cyan(f)).join(", ") : chalk.dim("None")}`);
 	console.log(`  Compose file(s):  ${project.composeFiles.length ? project.composeFiles.map((f) => chalk.cyan(f)).join(", ") : chalk.dim("None")}`);
 };
-const printDiagnostics = (diagnostics, verbose, fileContents, categoryIssueCounts) => {
+const printDiagnostics = (diagnostics, verbose, fileContents, categoryIssueCounts, unanalyzedCount) => {
 	if (diagnostics.length === 0) {
-		console.log(`\n${chalk.green.bold("✔ No issues found! Your Docker setup looks healthy.")}`);
+		console.log(unanalyzedCount === 0 ? `\n${chalk.green.bold("✔ No issues found! Your Docker setup looks healthy.")}` : `\n${chalk.yellow.bold("⚠ No issues found in the files that could be analyzed.")}`);
 		return;
 	}
 	if (!verbose) {
@@ -797,13 +806,24 @@ const printDiagnostics = (diagnostics, verbose, fileContents, categoryIssueCount
 			console.log(`  ${cat} › ${chalk.dim(issueLabel)}`);
 		}
 		console.log(`\n  Run ${chalk.cyan("docker-doctor --verbose")} to list every error and warning`);
-		const ruleCounts = {};
-		for (const d of diagnostics) ruleCounts[d.rule] = (ruleCounts[d.rule] || 0) + 1;
-		const migrationRules = Object.entries(ruleCounts).filter(([, count]) => count >= 5);
+		const findingsByRule = /* @__PURE__ */ new Map();
+		for (const d of diagnostics) {
+			const findings = findingsByRule.get(d.rule) ?? {
+				count: 0,
+				files: /* @__PURE__ */ new Set()
+			};
+			findings.count += 1;
+			findings.files.add(d.file);
+			findingsByRule.set(d.rule, findings);
+		}
+		const migrationRules = [...findingsByRule].filter(([, { count }]) => count >= 5);
 		if (migrationRules.length > 0) {
 			console.log();
 			console.log(`  ${chalk.yellow("⚠ Migration-scale change: sample before you sweep")}`);
-			for (const [rule, count] of migrationRules) console.log(`    ${chalk.cyan(rule)} ×${count} across ${count} files`);
+			for (const [rule, { count, files }] of migrationRules) {
+				const fileWord = files.size === 1 ? "file" : "files";
+				console.log(`    ${chalk.cyan(rule)} ×${count} across ${files.size} ${fileWord}`);
+			}
 			console.log(`    Fixing all of them at once is hard to review and prone to`);
 			console.log(`    subtle mistakes across the whole repo. Fix a representative`);
 			console.log(`    few first and confirm the recipe holds. Then get the code`);
@@ -858,7 +878,7 @@ const getWhaleMascot = (score, border) => {
 	];
 };
 const easeOutCubic = (x) => 1 - (1 - x) ** 3;
-const printScoreBox = async (score, label, categoryIssueCounts, warningsCount, errorsCount) => {
+const printScoreBox = async (score, label, warningsCount, errorsCount, unanalyzedCount) => {
 	const { isTTY } = process.stdout;
 	const shouldAnimate = isTTY && !process.env.CI && !process.env.NO_ANIMATION && process.env.TERM !== "dumb" && process.env.NODE_ENV !== "test";
 	let scoreColor = chalk.red.bold;
@@ -902,15 +922,21 @@ const printScoreBox = async (score, label, categoryIssueCounts, warningsCount, e
 		console.log(`  ${whaleLines[3]}`);
 	}
 	console.log(`\n  ${chalk.dim("────────────────────────────────────────────────────────────")}\n`);
-	console.log(`  Share: ${chalk.cyan(shareUrl)}`);
-	console.log(`  Tell others how you did on socials\n`);
+	if (unanalyzedCount === 0) {
+		console.log(`  Share: ${chalk.cyan(shareUrl)}`);
+		console.log(`  Tell others how you did on socials\n`);
+	} else {
+		const fileWord = unanalyzedCount === 1 ? "file" : "files";
+		console.log(`  ${chalk.yellow(`⚠ Incomplete scan: ${unanalyzedCount} ${fileWord} could not be analyzed.`)}`);
+		console.log(`  The score covers only the analyzed files.\n`);
+	}
 	console.log(`  Docs: ${chalk.cyan("https://docker-doctor.vercel.app")}`);
 	console.log(`  Learn more about fixing issues, setting up CI/CD, and`);
 	console.log(`  configuring rules with a config file\n`);
 	console.log(`  GitHub: ${chalk.cyan("https://github.com/PunGrumpy/docker-doctor")}`);
 	console.log(`  Report issues and star the repository!`);
 };
-const formatTerminal = async (diagnostics, score, label, project, verbose = false, fileContents = {}) => {
+const formatTerminal = async (diagnostics, score, label, project, verbose = false, fileContents = {}, unanalyzedCount = 0) => {
 	if (verbose) {
 		console.log(`\n${chalk.bold("Docker Doctor Diagnostics")}`);
 		console.log(`=================================`);
@@ -931,8 +957,8 @@ const formatTerminal = async (diagnostics, score, label, project, verbose = fals
 		if (d.severity === "warning") warningsCount += 1;
 		else if (d.severity === "error") errorsCount += 1;
 	}
-	printDiagnostics(diagnostics, verbose, fileContents, categoryIssueCounts);
-	await printScoreBox(score, label, categoryIssueCounts, warningsCount, errorsCount);
+	printDiagnostics(diagnostics, verbose, fileContents, categoryIssueCounts, unanalyzedCount);
+	await printScoreBox(score, label, warningsCount, errorsCount, unanalyzedCount);
 };
 
 //#endregion
@@ -946,8 +972,25 @@ const fileExists = async (filePath) => {
 		return false;
 	}
 };
+const selfAndAncestors = (dir) => {
+	const dirs = [dir];
+	let parent = node_path.default.dirname(dir);
+	while (parent !== dirs.at(-1)) {
+		dirs.push(parent);
+		parent = node_path.default.dirname(parent);
+	}
+	return dirs;
+};
+const findRepositoryRoot = async (dir) => {
+	const candidates = selfAndAncestors(dir);
+	const nearest = (await Promise.all(candidates.map((candidate) => fileExists(node_path.default.join(candidate, ".git"))))).indexOf(true);
+	return nearest === -1 ? null : candidates[nearest];
+};
 const scaffoldActionWorkflow = async (options) => {
-	const workflowDir = node_path.default.join(options.rootDir, ".github", "workflows");
+	const repositoryRoot = await findRepositoryRoot(options.rootDir) ?? options.rootDir;
+	const scanDirectory = node_path.default.relative(repositoryRoot, options.rootDir).split(node_path.default.sep).join("/");
+	const directoryInput = scanDirectory === "" ? "" : `        with:\n          directory: ${JSON.stringify(scanDirectory)}\n`;
+	const workflowDir = node_path.default.join(repositoryRoot, ".github", "workflows");
 	const workflowPath = node_path.default.join(workflowDir, "docker-doctor.yml");
 	const existing = await fileExists(workflowPath);
 	if (existing && !await options.confirmOverwrite()) return "kept";
@@ -958,13 +1001,14 @@ permissions:
   contents: read
   pull-requests: write
   issues: write
+  statuses: write
 jobs:
   docker-doctor:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
       - uses: ${options.actionRef}
-`;
+${directoryInput}`;
 	await node_fs_promises.default.mkdir(workflowDir, { recursive: true });
 	await node_fs_promises.default.writeFile(workflowPath, workflowYaml, "utf-8");
 	return existing ? "updated" : "created";
@@ -1156,6 +1200,7 @@ const runAgentHandoff = async (context) => {
 	await ensureGitignoreEntry(context.rootDir);
 	const payload = buildHandoffPayload({
 		diagnostics: context.diagnostics,
+		projectDir: context.rootDir,
 		projectName: node_path.default.basename(context.rootDir)
 	});
 	if (choice === clipboardIndex) {
@@ -1164,14 +1209,14 @@ const runAgentHandoff = async (context) => {
 		return;
 	}
 	const agentId = launchable[choice];
-	if (!await askConfirm(`Launch ${AGENT_BINARIES[agentId]} with ${AGENT_AUTO_FLAGS[agentId].join(" ")}? It will edit files without asking for approval.`)) {
+	if (!await askConfirm(`Launch ${AGENT_BINARIES[agentId]} with ${AGENT_AUTO_FLAGS[agentId].join(" ")} in ${context.rootDir}? It will edit files without asking for approval.`)) {
 		printAgentPrompt(payload);
 		return;
 	}
 	const installResult = await installSkillForAgents([agentId], { projectRoot: context.rootDir });
 	if (installResult && installResult.installed.length > 0) console.log(`\n  ${chalk.green("✔")} Installed the docker-doctor skill for ${agentDisplayName(agentId)}`);
 	console.log(`\n  Handing off to ${agentDisplayName(agentId)}...\n`);
-	if (!await launchAgent(agentId, payload)) {
+	if (!await launchAgent(agentId, payload, context.rootDir)) {
 		console.log(`  ${chalk.yellow("⚠")} Couldn't launch ${AGENT_BINARIES[agentId]}. Here's the prompt instead:`);
 		printAgentPrompt(payload);
 	}
@@ -1267,12 +1312,45 @@ const reportScanFailures = (failures) => {
 	console.error(`Docker Doctor could not analyze ${failures.length} ${fileWord}; the score below covers only the files that were analyzed.`);
 	for (const failure of failures) console.error(`  - ${failure.file}: ${flattenMessage(failure.message)}`);
 };
+const noFilesFoundMessage = (rootDir) => `No Dockerfiles or Compose files found in ${rootDir}`;
+const printNothingScanned = (rootDir) => {
+	console.log(`\n${chalk.yellow("⚠")} ${noFilesFoundMessage(rootDir)}.`);
+	console.log(`  docker-doctor scans files named Dockerfile, Dockerfile.*, *.dockerfile,`);
+	console.log(`  compose.yaml, docker-compose.yaml and variants such as compose.prod.yaml`);
+	console.log(`  (.yaml or .yml). Check the directory and your ignore.files patterns.`);
+};
+const pathExists = async (filePath) => {
+	try {
+		await node_fs_promises.default.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const resolveConfigPath = async (configOption, rootDir) => {
+	if (!configOption) return;
+	const fromCwd = node_path.default.resolve(process.cwd(), configOption);
+	if (await pathExists(fromCwd)) return fromCwd;
+	const fromRoot = node_path.default.resolve(rootDir, configOption);
+	if (fromRoot !== fromCwd && await pathExists(fromRoot)) {
+		console.error(`Warning: --config ${configOption} was found relative to the scanned directory, not the current directory. Pass a path relative to the current directory or an absolute path.`);
+		return fromRoot;
+	}
+	return fromCwd;
+};
+const findScanTargetProblem = async (rootDir) => {
+	const rootStat = await node_fs_promises.default.stat(rootDir).catch(() => null);
+	if (rootStat === null) return `Directory not found: ${rootDir}`;
+	if (!rootStat.isDirectory()) return `${rootDir} is not a directory. Pass the directory that contains your Dockerfile or Compose file.`;
+	return null;
+};
 const program = new commander.Command();
 program.name("docker-doctor").description("Static analysis for Dockerfile and Docker Compose files").version(require_src.version, "-V, --version", "display the version number");
 program.argument("[dir]", "directory to scan", ".").option("-v, --verbose", "show verbose diagnostics description", false).option("-s, --score", "only output numeric health score", false).option("-j, --json", "output results as JSON report", false).option("-c, --config <path>", "custom config file path").action(async (dir, options) => {
 	const isSilent = options.score || options.json;
+	const showProgress = Boolean(process.stdout.isTTY) && !isSilent;
 	const restoreCursor = () => {
-		if (process.stdout.isTTY && !isSilent) process.stdout.write("\x1B[?25h");
+		if (showProgress) process.stdout.write("\x1B[?25h");
 	};
 	process.on("exit", restoreCursor);
 	process.once("SIGINT", () => {
@@ -1285,6 +1363,12 @@ program.argument("[dir]", "directory to scan", ".").option("-v, --verbose", "sho
 	});
 	try {
 		const rootDir = node_path.default.resolve(dir);
+		const scanTargetProblem = await findScanTargetProblem(rootDir);
+		if (scanTargetProblem !== null) {
+			console.error(`Error: ${scanTargetProblem}`);
+			process.exitCode = 1;
+			return;
+		}
 		const startTime = Date.now();
 		let statusText = "Discovering workspace...";
 		const spinnerFrames = [
@@ -1304,7 +1388,7 @@ program.argument("[dir]", "directory to scan", ".").option("-v, --verbose", "sho
 		const setStatus = (text) => {
 			statusText = text;
 		};
-		if (process.stdout.isTTY && !isSilent) {
+		if (showProgress) {
 			process.stdout.write("\x1B[?25l");
 			process.stdout.write(`${chalk.cyan(spinnerFrames[0])} ${statusText}`);
 			spinnerInterval = setInterval(() => {
@@ -1313,19 +1397,26 @@ program.argument("[dir]", "directory to scan", ".").option("-v, --verbose", "sho
 			}, 80);
 		}
 		try {
-			if (process.stdout.isTTY && !isSilent) await (0, node_timers_promises.setTimeout)(150);
+			if (showProgress) await (0, node_timers_promises.setTimeout)(150);
 			setStatus("Loading configuration...");
-			const config = await require_src.loadConfig(rootDir, options.config, (message) => {
+			const configPath = await resolveConfigPath(options.config, rootDir);
+			const config = await require_src.loadConfig(rootDir, configPath, (message) => {
 				console.error(`Warning: ${message}`);
 			});
 			setStatus("Scanning workspace files...");
-			const project = await require_src.discoverProject(rootDir, { ignoreFiles: config.ignore?.files });
+			const project = await require_src.discoverProject(rootDir, {
+				ignoreFiles: config.ignore?.files,
+				onSkippedDirectory: (skippedDir) => {
+					console.error(`Warning: skipped unreadable directory ${skippedDir} (permission denied)`);
+				}
+			});
 			const fileContents = {};
 			const projectFilesList = [
 				...project.dockerfiles,
 				...project.composeFiles,
 				...project.dockerignores || []
 			];
+			const scannedFileCount = project.dockerfiles.length + project.composeFiles.length;
 			const { diagnostics, failures } = await runRulesEngine(rootDir, project, config.rules, config.categories, projectFilesList, fileContents, options, setStatus);
 			const { score, label } = require_src.calculateScore(diagnostics);
 			const duration = ((Date.now() - startTime) / 1e3).toFixed(1);
@@ -1335,25 +1426,33 @@ program.argument("[dir]", "directory to scan", ".").option("-v, --verbose", "sho
 				spinnerInterval = null;
 				process.stdout.write("\r\x1B[K\x1B[?25h");
 			}
-			if (process.stdout.isTTY && !isSilent) console.log(`${chalk.green("✔")} Scanned ${projectFilesList.length} files in ${duration}s [~${concurrency} workers]`);
+			if (showProgress) console.log(`${chalk.green("✔")} Scanned ${scannedFileCount} files in ${duration}s [~${concurrency} workers]`);
 			reportScanFailures(failures);
 			const scanIncomplete = failures.length > 0;
+			if (scannedFileCount === 0) {
+				if (isSilent) console.error(`Warning: ${noFilesFoundMessage(rootDir)}`);
+				else {
+					printNothingScanned(rootDir);
+					process.exitCode = 0;
+					return;
+				}
+			}
 			const hasErrors = diagnostics.some((d) => d.severity === "error");
 			if (options.score) {
 				console.log(score);
 				process.exitCode = scanExitCode(scanIncomplete, hasErrors);
 				return;
 			} else if (options.json) {
-				const report = require_src.toJsonReport(diagnostics, score, label, project);
+				const report = require_src.toJsonReport(diagnostics, score, label, project, failures);
 				console.log(JSON.stringify(report, null, 2));
 				process.exitCode = scanExitCode(scanIncomplete, hasErrors);
 				return;
 			}
-			await formatTerminal(diagnostics, score, label, project, options.verbose, fileContents);
+			await formatTerminal(diagnostics, score, label, project, options.verbose, fileContents, failures.length);
 			let wizardOk = true;
 			if (process.stdout.isTTY && process.stdin.isTTY) wizardOk = await runInteractiveWizard({
 				diagnostics,
-				report: require_src.toJsonReport(diagnostics, score, label, project),
+				report: require_src.toJsonReport(diagnostics, score, label, project, failures),
 				rootDir
 			});
 			const exitCode = scanExitCode(scanIncomplete, hasErrors);
@@ -1441,7 +1540,7 @@ rules.command("list").description("list all available rules").action(() => {
 	}
 });
 rules.command("explain <rule>").description("explain a specific rule in detail").action((ruleKey) => {
-	const rule = require_src.findRule(ruleKey);
+	const rule = require_src.findRule(ruleKey) ?? require_src.findRule(`docker-doctor/${ruleKey}`);
 	if (!rule) {
 		console.error(`Rule '${ruleKey}' not found.`);
 		process.exitCode = 1;