@alint-js/cli 0.7.0 → 0.7.2

package/README.md

@@ -189,6 +189,18 @@ Ask model-backed rules to write diagnostics in a specific language:
 alint --lang zh-CN src
 ```
 
+#### --rule
+
+Run only the rules a filter names, to read one rule's findings without paying for every other rule in the run:
+
+```bash
+alint --rule docs/review-copy src
+alint --rule 'docs/*' src
+alint --rule docs/review-copy,docs/naming src
+```
+
+A pattern matches the configured rule id (`plugin/rule`) or the rule's own name. The flag is repeatable and accepts a comma-separated list. Filtered rules are left unplanned, so the run neither calls their models nor reports their diagnostics. When the filter matches no enabled rule, the run fails and lists the rule ids it did enable, because a silent empty run is indistinguishable from a clean one.
+
 `alint` returns exit code `0` when diagnostics contain no errors, including warning-only runs. It returns `1` when at least one error diagnostic is reported and `2` when the command cannot complete because of a configuration, input, or runtime failure. `alint output inspect` uses the same exit-code behavior for saved results.
 
 ### Inspect Configuration and Output
@@ -421,6 +433,31 @@ export default defineConfig([
 ])
 ```
 
+#### Nested configs
+
+Every `alint.config.*` below the repository root is loaded together with the root config, and each file is scoped to the directory that contains it:
+
+```ts
+// packages/app/alint.config.ts
+import { defineConfig } from '@alint-js/cli'
+
+import { appPlugin } from './alint/plugin'
+
+export default defineConfig([
+  {
+    plugins: { app: appPlugin },
+    rules: { 'app/layer-boundary': 'error' },
+  },
+])
+```
+
+The item above reaches `packages/app/**` only. `files`, `directories`, and `ignores` resolve against the directory of the config that declares them, an item that declares no target patterns covers its whole subtree, and a deeper config overrides an outer one for its own directory. A package that owns a rule therefore needs one file, not an entry in the root config plus the same scope repeated in every tool that reads it.
+
+- Discovery skips hidden directories, `node_modules`, and build output (`build`, `coverage`, `dist`, `out`, `vendor`).
+- `--config <path>` pins exactly one config file and disables discovery, so a CI job can run one specific config.
+- Every config file shares one plugin alias namespace and one plugin lockfile, and `alint plugin install` installs the plugins nested configs declare. Two files that bind one alias to different specifiers fail the load instead of resolving silently to one of them.
+- Keep project-scoped rules (`onTargetProject`) in the root config: the project target sits outside a nested item's base path, so a nested config cannot claim it.
+
 #### Executable and static configs
 
 `alint` supports executable configs (`.js`, `.ts`, `.mjs`, `.cjs`, `.mts`, and `.cts`) and data-only static configs (`.toml`, `.yaml`, `.yml`, `.json`, `.jsonc`, and `.json5`).
@@ -488,6 +525,8 @@ arch = "./rules/architecture"
 
 `name` becomes the local rule id. `builtInAgent` can be `basic-structured` for a prompt-only structured-output rule or `basic-coding-agent` for a small built-in agent with filesystem tools. `includeFiles` and `excludeFiles` define where diagnostics may be reported; they do not limit what `basic-coding-agent` can inspect.
 
+Editing a rule's `instruction`, `includeFiles`, or `excludeFiles` invalidates the findings it cached: a declarative rule declares those inputs as its cache key, so a changed rule text never replays stale findings.
+
 Run the install command again after changing a source string, moving a local directory, or changing its symlink target. Changes inside the same local directory are loaded by the next CLI process without reinstalling.
 
 Local plugins execute as trusted Node.js code. Directory containment checks validate the installed source; they are not a sandbox.
@@ -651,6 +690,19 @@ defineRule({
 })
 ```
 
+Rules whose findings depend on inputs their source does not show must declare those inputs as `cacheKey`: an imported prompt, a shared message builder, or the text of a preset that builds the rule. `alint` hashes the rule source and `cacheKey` into every cache entry:
+
+```ts
+import prompt from './prompt.md?raw'
+
+defineRule({
+  cacheKey: { agentVersion: 1, prompt },
+  create: ctx => ({ /* ... */ }),
+})
+```
+
+Without a cache key, editing the prompt changes what the rule asks the model while the cache entry stays valid, and the next run replays the previous findings as cache hits without running the rule at all.
+
 ## Packages
 
 | Package | Purpose |

package/dist/bin/index.mjs

@@ -1,17 +1,54 @@
 #!/usr/bin/env node
-import { t as executeCli } from "../cli-BsBgbtds.mjs";
+import { t as executeCli } from "../cli-_dmEoPTZ.mjs";
 import process from "node:process";
+//#region src/cli/runtime/interrupt.ts
+/** Binds one graceful process interrupt to an abort signal for the active CLI run. */
+function bindInterruptSignal(source) {
+	const controller = new AbortController();
+	/**
+	* Aborts active CLI work when the process receives its first interrupt signal.
+	*
+	* Triggering workflow:
+	*
+	* {@link bindInterruptSignal}
+	*   -> `InterruptSignalSource.once('SIGINT' | 'SIGTERM')`
+	*     -> `handleInterrupt`
+	*       -> `AbortController.abort()`
+	*
+	* Upstream:
+	* - {@link bindInterruptSignal} registers this handler for `SIGINT` and `SIGTERM`.
+	*
+	* Downstream:
+	* - Aborts {@link InterruptSignalBinding.signal}, which the lint command passes to `runAlint`.
+	*/
+	const handleInterrupt = () => {
+		controller.abort();
+	};
+	source.once("SIGINT", handleInterrupt);
+	source.once("SIGTERM", handleInterrupt);
+	return {
+		dispose: () => {
+			source.off("SIGINT", handleInterrupt);
+			source.off("SIGTERM", handleInterrupt);
+		},
+		signal: controller.signal
+	};
+}
+//#endregion
 //#region src/bin/index.ts
+const interrupt = bindInterruptSignal(process);
 executeCli(process.argv, {
 	cwd: process.cwd(),
 	stderr: process.stderr,
 	stdin: process.stdin,
 	stdout: process.stdout
-}).then((exitCode) => {
+}, { signal: interrupt.signal }).then((exitCode) => {
 	process.exitCode = exitCode;
 }).catch((error) => {
 	process.stderr.write(`${formatError(error)}\n`);
 	process.exitCode = 2;
+}).finally(() => {
+	interrupt.dispose();
 });
 function formatError(error) {
 	if (error instanceof Error) return error.message;

package/dist/{cli-BsBgbtds.mjs → cli-_dmEoPTZ.mjs}

@@ -24,7 +24,7 @@ import { Minimatch, minimatch } from "minimatch";
 import fastStringTruncatedWidth from "fast-string-truncated-width";
 import { formatDuration, intervalToDuration } from "date-fns";
 //#region package.json
-var version = "0.7.0";
+var version = "0.7.2";
 //#endregion
 //#region src/cli/output.ts
 function escapeLineValue(value) {
@@ -2940,6 +2940,7 @@ async function createRunSession(io, options = {}) {
 				outputLanguage: runOptions.outputLanguage,
 				progress: runOptions.progress,
 				projectTargets: runOptions.projectTargets,
+				ruleFilter: runOptions.ruleFilter,
 				runner: runOptions.runner,
 				setupConfig,
 				signal: runOptions.signal
@@ -3497,8 +3498,9 @@ async function executeLint(options) {
 			modelOverride: options.modelOverride,
 			outputLanguage: options.outputLanguage,
 			progress: mergeProgressReporters(options.progress, statsCollector?.reporter),
+			ruleFilter: options.ruleFilter,
 			runner,
-			signal: options.createSignal?.()
+			signal: options.signal ?? options.createSignal?.()
 		});
 	} catch (error) {
 		if (error instanceof AlintRunError || error instanceof AlintRunCancelledError || error instanceof AlintCachePersistenceError) await persistStats(error.result);
@@ -4253,55 +4255,29 @@ function createCliProgressReporter(options) {
 	};
 }
 function createRenderingProgressReporter(summary, renderer) {
+	/**
+	* Resets the summary and starts its bounded TTY render interval.
+	*
+	* Triggering workflow:
+	*
+	* `runAlint`
+	*   -> `ProgressReporter.onPrepareStart`
+	*     -> `handlePrepareStart`
+	*       -> `TtyProgressRenderer.start`
+	*
+	* Upstream:
+	* - `runAlint` emits `onPrepareStart` before source discovery.
+	*
+	* Downstream:
+	* - Delegates state reset to `summary.onPrepareStart` and starts the renderer interval.
+	*/
+	const handlePrepareStart = (payload) => {
+		summary.onPrepareStart?.(payload);
+		renderer.start();
+	};
 	return {
-		onDiagnostic: (payload) => {
-			summary.onDiagnostic?.(payload);
-			renderer.render();
-		},
-		onExecuteEnd: (payload) => {
-			summary.onExecuteEnd?.(payload);
-			renderer.render();
-		},
-		onExecuteStart: (payload) => {
-			summary.onExecuteStart?.(payload);
-			renderer.render();
-		},
-		onFileReady: (payload) => {
-			summary.onFileReady?.(payload);
-			renderer.render();
-		},
-		onJobEnd: (payload) => {
-			summary.onJobEnd?.(payload);
-			renderer.render();
-		},
-		onJobQueued: (payload) => {
-			summary.onJobQueued?.(payload);
-			renderer.render();
-		},
-		onJobRetry: (payload) => {
-			summary.onJobRetry?.(payload);
-			renderer.render();
-		},
-		onJobStart: (payload) => {
-			summary.onJobStart?.(payload);
-			renderer.render();
-		},
-		onPrepareEnd: (payload) => {
-			summary.onPrepareEnd?.(payload);
-			renderer.render();
-		},
-		onPrepareStart: (payload) => {
-			summary.onPrepareStart?.(payload);
-			renderer.start();
-		},
-		onRunEnd: (payload) => {
-			summary.onRunEnd?.(payload);
-			renderer.render();
-		},
-		onUsage: (payload) => {
-			summary.onUsage?.(payload);
-			renderer.render();
-		}
+		...summary,
+		onPrepareStart: handlePrepareStart
 	};
 }
 //#endregion
@@ -4371,12 +4347,26 @@ function groupFailuresByRule(failures) {
 	return [...groups];
 }
 //#endregion
+//#region src/cli/commands/lint/rule-filter.ts
+/**
+* Reads `--rule` into the patterns the run filters rules with.
+*
+* The flag accepts one pattern, a comma-separated list, or repeated `--rule` flags, because a
+* debugging session usually narrows to one rule but sometimes compares a plugin's rules.
+*/
+function resolveRuleFilter(value) {
+	if (value === void 0) return;
+	const patterns = (Array.isArray(value) ? value : [value]).flatMap((entry) => entry.split(",")).map((entry) => entry.trim()).filter((entry) => entry !== "");
+	if (patterns.length === 0) throw new Error("--rule requires a rule id, a rule name, or a glob pattern.");
+	return [...new Set(patterns)];
+}
+//#endregion
 //#region src/cli/commands/lint/index.ts
 const lint = defineCommand({
 	action: (context, files = [], options) => runLintCommand(files, {
 		...options,
 		outputLanguage: options.lang ?? context.globalOptions.outputLanguage
-	}, context.io, context.interceptConsoleOutput),
+	}, context.io, context.interceptConsoleOutput, context.signal),
 	alias: ["!"],
 	arguments: "[...files]",
 	default: true,
@@ -4396,7 +4386,7 @@ async function assertConfigExists(cwd, configPath) {
 		throw error;
 	}
 }
-async function runLintCommand(files, options, io, interceptConsoleOutput) {
+async function runLintCommand(files, options, io, interceptConsoleOutput, signal) {
 	if (options.dirty && files.length > 0) {
 		io.stderr.write("The --dirty option does not accept file arguments.\n");
 		return 2;
@@ -4445,8 +4435,10 @@ async function runLintCommand(files, options, io, interceptConsoleOutput) {
 				modelOverride: options.model,
 				outputLanguage: options.outputLanguage,
 				progress: progress?.reporter,
+				ruleFilter: resolveRuleFilter(options.rule),
 				runnerOptions: options,
-				session
+				session,
+				signal
 			});
 		} catch (error) {
 			if (error instanceof NoFilesFoundError) {
@@ -4487,7 +4479,7 @@ function shouldEnableProgress(options, io) {
 //#endregion
 //#region src/cli/commands/lsp/index.ts
 const lsp = defineCommand({
-	action: async (context) => (await import("./server-C-kuoGl1.mjs")).startLspServer(context.io),
+	action: async (context) => (await import("./server-Dxaq_DPo.mjs")).startLspServer(context.io),
 	description: "Run alint as a language server over stdio",
 	examples: [["# Point an editor at the project's own alint", "alint lsp"].join("\n")],
 	help: ["Serve alint diagnostics over the Language Server Protocol on stdin/stdout.", "The server is cache-first. It publishes diagnostics that are already cached, and it never calls a model on its own. Runs that spend tokens happen only through the `alint.runFile` and `alint.runWorkspace` commands."].join("\n\n"),
@@ -5163,7 +5155,7 @@ const commandTree = [
 ];
 //#endregion
 //#region src/cli/cli.ts
-async function executeCli(argv, io) {
+async function executeCli(argv, io, runtime = {}) {
 	if (argv.includes("--version") || argv.includes("-v")) {
 		io.stdout.write(`${version}\n`);
 		return 0;
@@ -5176,12 +5168,13 @@ async function executeCli(argv, io) {
 		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("--cache-only", "Report only cached diagnostics; skip rules that miss the cache and call no model").option("-c, --config <path>", "Path to alint config file").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>", "Maximum rule executions across the entire run").option("--no-stats", "Do not record run stats for this run").option("--timeout-ms <ms>", "Rule execution timeout in milliseconds").version(version).help();
+	cli.option("--no-cache", "Disable cache for this run").option("--cache-location <path>", "Path to the alint cache file or directory").option("--cache-only", "Report only cached diagnostics; skip rules that miss the cache and call no model").option("-c, --config <path>", "Path to alint config file").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 <pattern>", "Only run rules whose id, name, or glob matches (repeatable, comma-separated)").option("--rule-concurrency <count>", "Maximum rule executions across the entire run").option("--no-stats", "Do not record run stats for this run").option("--timeout-ms <ms>", "Rule execution timeout in milliseconds").version(version).help();
 	registerCommandTree(cli, commandTree, {
 		globalOptions,
 		interceptConsoleOutput,
 		io,
-		setupNoInteractive
+		setupNoInteractive,
+		signal: runtime.signal
 	}, setPendingResult, {
 		examples: [
 			["# Configure a provider interactively", "alint setup"].join("\n"),

package/dist/index.d.mts

@@ -27,7 +27,10 @@ interface CliWritable {
 }
 //#endregion
 //#region src/cli/cli.d.ts
-declare function executeCli(argv: string[], io: CliIo): Promise<number>;
+interface CliRuntimeOptions {
+  signal?: AbortSignal;
+}
+declare function executeCli(argv: string[], io: CliIo, runtime?: CliRuntimeOptions): Promise<number>;
 //#endregion
 //#region src/cli/reporters/index.d.ts
 interface FormatDiagnosticsOptions {
@@ -45,4 +48,4 @@ interface StylishReporterOptions {
 }
 declare function formatStylish(input: Diagnostic[] | RunResult, options?: StylishReporterOptions): string;
 //#endregion
-export { type AlintConfig, type AlintConfigItem, type CliIo, type ReporterName, type RunnerConfig, defineConfig, executeCli, formatDiagnostics, formatJson, formatStylish, ignorePatternsAIAgents, ignorePatternsBuildOutputs, ignorePatternsCaches, ignorePatternsCommon, ignorePatternsEslintDefaults, ignorePatternsGenerated };
+export { type AlintConfig, type AlintConfigItem, type CliIo, type CliRuntimeOptions, type ReporterName, type RunnerConfig, defineConfig, executeCli, formatDiagnostics, formatJson, formatStylish, ignorePatternsAIAgents, ignorePatternsBuildOutputs, ignorePatternsCaches, ignorePatternsCommon, ignorePatternsEslintDefaults, ignorePatternsGenerated };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { i as formatJson, n as formatDiagnostics, r as formatStylish, t as executeCli } from "./cli-BsBgbtds.mjs";
+import { i as formatJson, n as formatDiagnostics, r as formatStylish, t as executeCli } from "./cli-_dmEoPTZ.mjs";
 import { ignorePatternsAIAgents, ignorePatternsBuildOutputs, ignorePatternsCaches, ignorePatternsCommon, ignorePatternsEslintDefaults, ignorePatternsGenerated } from "@alint-js/config";
 import { defineConfig } from "@alint-js/core";
 export { defineConfig, executeCli, formatDiagnostics, formatJson, formatStylish, ignorePatternsAIAgents, ignorePatternsBuildOutputs, ignorePatternsCaches, ignorePatternsCommon, ignorePatternsEslintDefaults, ignorePatternsGenerated };

package/dist/{server-C-kuoGl1.mjs → server-Dxaq_DPo.mjs}

@@ -1,4 +1,4 @@
-import { a as createRunSession } from "./cli-BsBgbtds.mjs";
+import { a as createRunSession } from "./cli-_dmEoPTZ.mjs";
 import { CLEAR_CACHE_COMMAND, RUN_FILE_COMMAND, RUN_WORKSPACE_COMMAND } from "./lsp-commands.mjs";
 import { realpath, rm } from "node:fs/promises";
 import { AlintRunCancelledError, AlintRunError } from "@alint-js/core";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alint-js/cli",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Agentic code analysis CLI for model-backed lint rules",
   "license": "MIT",
   "repository": {
@@ -50,10 +50,10 @@
     "tinyexec": "^1.2.4",
     "tinyrainbow": "^3.1.1",
     "vscode-languageserver": "^10.1.0",
-    "@alint-js/model-adapter-acp": "0.7.0",
-    "@alint-js/core": "0.7.0",
-    "@alint-js/config": "0.7.0",
-    "@alint-js/utils": "0.7.0"
+    "@alint-js/config": "0.7.2",
+    "@alint-js/core": "0.7.2",
+    "@alint-js/model-adapter-acp": "0.7.2",
+    "@alint-js/utils": "0.7.2"
   },
   "devDependencies": {
     "@pnpm/find-workspace-dir": "^1000.1.5",