@alint-js/cli 0.0.6 → 0.0.8

package/dist/bin/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as executeCli } from "../cli-C4PnKXoK.mjs";
+import { t as executeCli } from "../cli-D7cUTZnE.mjs";
 import process from "node:process";
 //#region src/bin/index.ts
 executeCli(process.argv, {

package/dist/{cli-C4PnKXoK.mjs → cli-D7cUTZnE.mjs}

@@ -6,18 +6,20 @@ import { AlintRunError, hasDiscoveryFilePatterns, matchesDiscoveryFile, normaliz
 import { relative, resolve } from "pathe";
 import { getBorderCharacters, table } from "table";
 import { errorMessageFrom } from "@moeru/std/error";
-import { readdir, stat } from "node:fs/promises";
+import { readFile, readdir, stat } from "node:fs/promises";
 import c, { createColors } from "tinyrainbow";
 import cliSpinners from "cli-spinners";
 import { relative as relative$1 } from "node:path";
 import Gitignore from "gitignore-fs";
 import { minimatch } from "minimatch";
+import { errorMessageFrom as errorMessageFrom$1 } from "@moeru/std";
 //#region src/cli/commands/command.ts
 function defineCommand(node) {
 	return node;
 }
-function registerCommandTree(cli, nodes, context, setPendingResult) {
+function registerCommandTree(cli, nodes, context, setPendingResult, help = {}) {
 	for (const node of nodes) registerRootCommand(cli, node, context, setPendingResult);
+	cli.globalCommand.helpCallback = (sections) => formatCommandHelp(sections, nodes, cli.rawArgs, help);
 }
 function collectCommandOptions(node) {
 	const options = /* @__PURE__ */ new Map();
@@ -36,9 +38,91 @@ function dispatchCommand(context, node, args, options, path) {
 	if (!node.action) return Promise.resolve(reportUnknownCommand(context, path, args));
 	return Promise.resolve(node.action(context, ...parseCommandArguments(node, args), options));
 }
+function formatChildCommandHelp(parentPath, child) {
+	const parts = [...parentPath, child.name];
+	if (!child.children && child.arguments) parts.push(child.arguments);
+	return {
+		description: child.description,
+		pattern: parts.join(" ")
+	};
+}
+function formatCommandHelp(sections, nodes, argv, rootHelp) {
+	const helpPath = resolveHelpPath(nodes, argv);
+	const node = helpPath.at(-1)?.node;
+	if (!node) return insertExamplesSection(insertHelpSection(sections, rootHelp), rootHelp);
+	const path = helpPath.map((item) => item.node.name);
+	const normalizedSections = rewriteUsageSection(insertExamplesSection(insertHelpSection(sections.filter((section) => section.title !== "Options"), node), node), path, node);
+	if (!node.children) {
+		const optionSection = formatOptionsSection(node.options ?? []);
+		return optionSection ? [...normalizedSections, optionSection] : normalizedSections;
+	}
+	const commands = (node.children ?? []).map((child) => formatChildCommandHelp(path, child));
+	const longestCommand = Math.max(...commands.map((command) => command.pattern.length));
+	const commandSection = {
+		body: commands.map((command) => `  ${command.pattern.padEnd(longestCommand)}  ${command.description}`).join("\n"),
+		title: "Commands"
+	};
+	const usageIndex = normalizedSections.findIndex((section) => section.title === "Usage");
+	if (usageIndex === -1) return [commandSection, ...normalizedSections];
+	return [
+		...normalizedSections.slice(0, usageIndex + 1),
+		commandSection,
+		...normalizedSections.slice(usageIndex + 1)
+	];
+}
+function formatExamples(examples) {
+	return examples.map((example) => example.split("\n").map((line) => `  ${line}`).join("\n")).join("\n\n");
+}
+function formatOptionDescription(option) {
+	if (option.config?.default === void 0) return option.description;
+	return `${option.description} (default: ${option.config.default})`;
+}
+function formatOptionsSection(options) {
+	if (options.length === 0) return;
+	const rows = options.map((option) => ({
+		description: formatOptionDescription(option),
+		flags: option.flags
+	}));
+	const longestFlag = Math.max(...rows.map((row) => row.flags.length));
+	return {
+		body: rows.map((row) => `  ${row.flags.padEnd(longestFlag)}  ${row.description}`).join("\n"),
+		title: "Options"
+	};
+}
 function formatUnknownCommand(path, args) {
 	return [...path, ...args].filter(Boolean).join(" ");
 }
+function formatUsagePattern(path, node) {
+	const parts = [...path];
+	if (!node.children && node.arguments) parts.push(node.arguments);
+	return parts.join(" ");
+}
+function insertExamplesSection(sections, node) {
+	if (!node.examples?.length) return sections;
+	const usageIndex = sections.findIndex((section) => section.title === "Usage");
+	const examplesSection = {
+		body: formatExamples(node.examples),
+		title: "Examples"
+	};
+	if (usageIndex === -1) return [...sections, examplesSection];
+	return [
+		...sections.slice(0, usageIndex),
+		examplesSection,
+		...sections.slice(usageIndex)
+	];
+}
+function insertHelpSection(sections, node) {
+	const help = node.help ?? node.description;
+	if (!help) return sections;
+	const usageIndex = sections.findIndex((section) => section.title === "Usage");
+	const helpSection = { body: help };
+	if (usageIndex === -1) return [...sections, helpSection];
+	return [
+		...sections.slice(0, usageIndex),
+		helpSection,
+		...sections.slice(usageIndex)
+	];
+}
 function parseCommandArguments(node, args) {
 	if (!node.arguments) return [];
 	const parts = node.arguments.split(/\s+/u).filter(Boolean);
@@ -67,12 +151,56 @@ function registerRootCommand(cli, node, context, setPendingResult) {
 	});
 }
 function reportUnknownCommand(context, path, args) {
-	context.io.stderr.write(`unknown config command: ${formatUnknownCommand(path, args)}\n`);
+	context.io.stderr.write(`unknown command: ${formatUnknownCommand(path, args)}\n`);
 	return 2;
 }
+function resolveHelpPath(nodes, argv) {
+	const path = [];
+	let currentNodes = nodes;
+	let skipNext = false;
+	for (const arg of argv.slice(2)) {
+		if (skipNext) {
+			skipNext = false;
+			continue;
+		}
+		if (arg.startsWith("-")) {
+			skipNext = shouldSkipOptionValue(arg);
+			continue;
+		}
+		const node = currentNodes.find((item) => item.name === arg || item.alias?.includes(arg));
+		if (!node) break;
+		path.push({ node });
+		currentNodes = node.children ?? [];
+	}
+	return path;
+}
+function rewriteUsageSection(sections, path, node) {
+	return sections.map((section) => section.title === "Usage" ? {
+		...section,
+		body: `  $ alint ${formatUsagePattern(path, node)}`
+	} : section);
+}
+function shouldSkipOptionValue(arg) {
+	if (arg.includes("=")) return false;
+	return [
+		"--cache-location",
+		"--config",
+		"--file-concurrency",
+		"--format",
+		"--model",
+		"--provider-endpoint",
+		"--provider-header",
+		"--provider-id",
+		"--provider-model",
+		"--rule-concurrency",
+		"--timeout-ms",
+		"-f",
+		"-l"
+	].includes(arg);
+}
 //#endregion
 //#region src/cli/commands/config/inspect.ts
-const inspect$1 = defineCommand({
+const inspect$2 = defineCommand({
 	action: (context, file, options) => runConfigInspectCommand(file, options.config, context.io),
 	arguments: "<file>",
 	description: "Inspect resolved config for a file",
@@ -243,6 +371,8 @@ const models = defineCommand({
 				}
 			},
 			description: "Probe OpenAI-compatible models",
+			examples: [["# Probe a provider endpoint and print available model ids", "alint config models probe --endpoint https://openrouter.ai/api/v1"].join("\n"), ["# Probe an endpoint that requires an authorization header", "alint config models probe --endpoint https://api.example.com/v1 --provider-header \"Authorization=Bearer $TOKEN\""].join("\n")],
+			help: ["Probe an OpenAI-compatible models endpoint before saving it in setup config.", "The command calls the provider models endpoint using the supplied endpoint and optional headers, then prints the model ids returned by that provider."].join("\n\n"),
 			name: "probe",
 			options: [{
 				description: "Provider endpoint",
@@ -269,6 +399,7 @@ const models = defineCommand({
 		})
 	],
 	description: "Manage configured models",
+	help: ["Inspect, list, and probe model entries from alint setup configuration.", "Model entries describe the provider/model ids alint can use for model-backed rules. Probe endpoints before saving them when you want to verify what model ids a provider exposes."].join("\n\n"),
 	name: "models"
 });
 //#endregion
@@ -313,7 +444,7 @@ const probe = defineCommand({
 //#region src/cli/commands/config/config.ts
 const config = defineCommand({
 	children: [
-		inspect$1,
+		inspect$2,
 		models,
 		defineCommand({
 			children: [
@@ -339,6 +470,26 @@ const config = defineCommand({
 		})
 	],
 	description: "Manage alint configuration",
+	examples: [
+		["# Show the effective alint config for a file", "alint config inspect src/index.ts"].join("\n"),
+		["# Inspect a file using a custom config path", "alint --config alint.config.ts config inspect src/index.ts"].join("\n"),
+		[
+			"# List configured providers and models",
+			"alint config providers list",
+			"alint config models list"
+		].join("\n"),
+		[
+			"# Show one configured provider or model by id",
+			"alint config providers show openrouter",
+			"alint config models show z-ai/glm-5.2"
+		].join("\n"),
+		[
+			"# Probe an OpenAI-compatible endpoint before saving it",
+			"alint config providers probe --endpoint https://openrouter.ai/api/v1",
+			"alint config models probe --endpoint https://openrouter.ai/api/v1"
+		].join("\n")
+	],
+	help: ["Inspect and update alint setup/configuration state.", "Use these commands to understand the effective config for a file, inspect saved provider/model setup, and probe OpenAI-compatible endpoints before using them in model-backed rules."].join("\n\n"),
 	name: "config"
 });
 //#endregion
@@ -900,7 +1051,10 @@ function resolveRunnerCacheConfig(setupCache, configCache, options) {
 //#endregion
 //#region src/cli/commands/lint/index.ts
 const lint = defineCommand({
-	action: (context, files = [], options) => runLintCommand(files, options, context.io, context.interceptConsoleOutput),
+	action: (context, files = [], options) => runLintCommand(files, {
+		...options,
+		outputLanguage: options.lang ?? context.globalOptions.outputLanguage
+	}, context.io, context.interceptConsoleOutput),
 	alias: ["!"],
 	arguments: "[...files]",
 	default: true,
@@ -939,6 +1093,7 @@ async function runLintCommand(files, options, io, interceptConsoleOutput) {
 			cwd: io.cwd,
 			files: lintFiles,
 			modelOverride: options.model,
+			outputLanguage: options.outputLanguage,
 			progress: progress?.reporter,
 			runner,
 			setupConfig
@@ -962,6 +1117,85 @@ function shouldEnableProgress(options, io) {
 	return options.format === "stylish" && io.stderr.isTTY === true;
 }
 //#endregion
+//#region src/cli/commands/output-inspect/inspect.ts
+const inspect$1 = defineCommand({
+	action: (context, file, options) => inspectOutputFile(context.io, file, options),
+	arguments: "<file>",
+	description: "Inspect saved alint JSON output",
+	examples: [
+		["# Pretty-print saved JSON output", "alint output inspect alint-output.json"].join("\n"),
+		["# Validate and reprint normalized JSON", "alint output inspect alint-output.json --format json"].join("\n"),
+		[
+			"# Save a run as JSON, then inspect it later",
+			"alint --format json src > alint-output.json",
+			"alint output inspect alint-output.json"
+		].join("\n")
+	],
+	help: ["Read a saved alint JSON run result and render it with a reporter.", "Defaults to the human-friendly stylish reporter, which groups diagnostics by file and prints the same summary style as a normal alint run. Use `--format json` to validate the file and reprint normalized JSON."].join("\n\n"),
+	name: "inspect",
+	options: [{
+		config: { default: "stylish" },
+		description: "Reporter used to render the parsed run result. One of: stylish, json",
+		flags: "-f, --format <format>"
+	}]
+});
+async function inspectOutputFile(io, file, options) {
+	const filePath = resolve(io.cwd, file);
+	let text;
+	try {
+		text = await readFile(filePath, "utf8");
+	} catch (error) {
+		io.stderr.write(`Could not read output file "${file}": ${errorMessageFrom$1(error)}\n`);
+		return 2;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		io.stderr.write(`Could not parse output file "${file}": ${errorMessageFrom$1(error)}\n`);
+		return 2;
+	}
+	if (!isRunResult(parsed)) {
+		io.stderr.write(`Invalid alint output "${file}": expected a run result with diagnostics and usage.\n`);
+		return 2;
+	}
+	try {
+		io.stdout.write(formatDiagnostics(options.format, parsed, { color: io.stdout.isTTY === true }));
+	} catch (error) {
+		io.stderr.write(`${errorMessageFrom$1(error)}\n`);
+		return 2;
+	}
+	return parsed.diagnostics.length > 0 ? 1 : 0;
+}
+function isDiagnostic(value) {
+	if (!isRecord(value)) return false;
+	if (typeof value.filePath !== "string" || typeof value.message !== "string" || typeof value.ruleId !== "string" || value.severity !== "warn" && value.severity !== "error") return false;
+	if (value.loc === void 0) return true;
+	if (!isRecord(value.loc)) return false;
+	if (value.loc.start === void 0) return true;
+	if (!isRecord(value.loc.start)) return false;
+	return (value.loc.start.line === void 0 || typeof value.loc.start.line === "number") && (value.loc.start.column === void 0 || typeof value.loc.start.column === "number");
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRunResult(value) {
+	if (!isRecord(value)) return false;
+	if (!Array.isArray(value.diagnostics) || !value.diagnostics.every(isDiagnostic)) return false;
+	return isUsage(value.usage);
+}
+function isUsage(value) {
+	return isRecord(value) && typeof value.inputTokens === "number" && typeof value.outputTokens === "number" && Array.isArray(value.records) && typeof value.totalTokens === "number";
+}
+//#endregion
+//#region src/cli/commands/output-inspect/output.ts
+const output = defineCommand({
+	children: [inspect$1],
+	description: "Inspect alint output files",
+	help: ["Inspect saved alint run outputs without rerunning rules or model calls.", "Use this when you already have JSON from `alint --format json` and want to render, validate, or transform that result for humans or tools."].join("\n\n"),
+	name: "output"
+});
+//#endregion
 //#region src/cli/commands/setup/interactive.ts
 const nonTtyMessage = "interactive setup requires a TTY. Use -N/--no-interactive with --provider-id and --provider-endpoint.\n";
 const backValue = "__alint_back__";
@@ -1225,6 +1459,12 @@ const setup = defineCommand({
 		noInteractive: context.setupNoInteractive
 	}, context.io),
 	description: "Write alint provider configuration",
+	examples: [
+		["# Configure a provider interactively", "alint setup"].join("\n"),
+		["# Write a project-local provider config without prompts", "alint setup --local -N --provider-id openrouter --provider-endpoint https://openrouter.ai/api/v1 --provider-model z-ai/glm-5.2"].join("\n"),
+		["# Add an authorization header for an OpenAI-compatible provider", "alint setup --local -N --provider-id openrouter --provider-endpoint https://openrouter.ai/api/v1 --provider-model z-ai/glm-5.2 --provider-header \"Authorization=Bearer $OPENROUTER_API_KEY\""].join("\n")
+	],
+	help: ["Write alint provider and model configuration.", "Run without flags for interactive setup, or use `-N` with provider flags in scripts and CI. Use `--local` when the provider config should live with the current project instead of the user-level setup file."].join("\n\n"),
 	name: "setup",
 	options: [
 		{
@@ -1295,6 +1535,7 @@ function toArray(value) {
 const commandTree = [
 	setup,
 	config,
+	output,
 	lint
 ];
 //#endregion
@@ -1302,17 +1543,36 @@ const commandTree = [
 async function executeCli(argv, io) {
 	const cli = cac("alint");
 	const setupNoInteractive = argv.includes("-N") || argv.includes("--no-interactive");
+	const globalOptions = { outputLanguage: parseStringOption(argv, ["--lang", "-l"]) };
 	let pendingResult;
 	const setPendingResult = (result) => {
 		pendingResult = result;
 		return result;
 	};
-	cli.option("--no-cache", "Disable cache for this run").option("--cache-location <path>", "Path to the alint cache file or directory").option("--config <path>", "Path to alint config file").option("--file-concurrency <count>", "Number of files to lint concurrently").option("--format <format>", "Reporter format", { default: "stylish" }).option("--model <model>", "Force a model override").option("--progress", "Show run progress").option("--rule-concurrency <count>", "Number of rules to run concurrently within a file").option("--timeout-ms <ms>", "Rule execution timeout in milliseconds").help();
+	cli.option("--no-cache", "Disable cache for this run").option("--cache-location <path>", "Path to the alint cache file or directory").option("--config <path>", "Path to alint config file").option("--file-concurrency <count>", "Number of files to lint concurrently").option("--format <format>", "Reporter format", { default: "stylish" }).option("--model <model>", "Force a model override").option("-l, --lang <language>", "Ask model-backed rules to write diagnostics in this language").option("--progress", "Show run progress").option("--rule-concurrency <count>", "Number of rules to run concurrently within a file").option("--timeout-ms <ms>", "Rule execution timeout in milliseconds").help();
 	registerCommandTree(cli, commandTree, {
+		globalOptions,
 		interceptConsoleOutput,
 		io,
 		setupNoInteractive
-	}, setPendingResult);
+	}, setPendingResult, {
+		examples: [
+			["# Configure a provider interactively", "alint setup"].join("\n"),
+			["# Run alint on source files with the default stylish reporter", "alint src"].join("\n"),
+			[
+				"# Run alint and save machine-readable JSON for later inspection",
+				"alint --format json src > alint-output.json",
+				"alint output inspect alint-output.json"
+			].join("\n"),
+			["# Inspect the effective config that applies to a file", "alint config inspect src/index.ts"].join("\n"),
+			[
+				"# List configured providers and models",
+				"alint config providers list",
+				"alint config models list"
+			].join("\n")
+		],
+		help: ["AI-assisted linting for source files, saved run outputs, and provider/model setup.", "Start with `alint setup` to configure a model provider, run `alint <files>` to analyze files, and use `alint output inspect` to read saved JSON output without rerunning rules."].join("\n\n")
+	});
 	const restoreConsole = interceptConsoleOutput(shouldCaptureHelp(argv) ? io.stdout : io.stderr);
 	try {
 		cli.parse(argv);
@@ -1344,6 +1604,16 @@ function interceptConsoleOutput(stdout) {
 		cliConsole.log = originalConsoleLog;
 	};
 }
+function parseStringOption(argv, flags) {
+	for (let index = 0; index < argv.length; index += 1) {
+		const value = argv[index];
+		for (const flag of flags) {
+			const equalsPrefix = `${flag}=`;
+			if (value?.startsWith(equalsPrefix)) return value.slice(equalsPrefix.length);
+			if (value === flag) return argv[index + 1];
+		}
+	}
+}
 function shouldCaptureHelp(argv) {
 	return argv.includes("--help") || argv.includes("-h");
 }

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { i as formatJson, n as formatDiagnostics, r as formatStylish, t as executeCli } from "./cli-C4PnKXoK.mjs";
+import { i as formatJson, n as formatDiagnostics, r as formatStylish, t as executeCli } from "./cli-D7cUTZnE.mjs";
 export { executeCli, formatDiagnostics, formatJson, formatStylish };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alint-js/cli",
   "type": "module",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -25,8 +25,8 @@
     "pathe": "^2.0.3",
     "table": "^6.9.0",
     "tinyrainbow": "^3.1.0",
-    "@alint-js/config": "0.0.6",
-    "@alint-js/core": "0.0.6"
+    "@alint-js/core": "0.0.8",
+    "@alint-js/config": "0.0.8"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",