@alint-js/config 0.7.0 → 0.7.2

package/dist/index.d.mts

@@ -104,7 +104,7 @@ declare const declarativeFindingSchema: import("valibot").SchemaWithPipe<readonl
   readonly confidence: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").PicklistSchema<["high", "medium", "low"], undefined>, import("valibot").DescriptionAction<"high" | "medium" | "low", "Confidence in this finding. Use exactly \"high\", \"medium\", or \"low\" when confidence is known.">]>, undefined>;
   readonly filePath: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").DescriptionAction<string, "Path to the file that owns this finding. Omit when the finding belongs to the reviewed target file.">]>, undefined>;
   readonly line: import("valibot").SchemaWithPipe<readonly [import("valibot").NumberSchema<undefined>, import("valibot").DescriptionAction<number, "Use the left-column line number from the numbered source block.">]>;
-  readonly message: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").DescriptionAction<string, "Human-readable diagnostic message describing the issue.">]>;
+  readonly message: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").DescriptionAction<string, "Human-readable diagnostic message describing the problem the target must fix. Never describe the absence of a problem.">]>;
   readonly suggestion: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").DescriptionAction<string, "Concrete remediation direction for the finding.">]>, undefined>;
 }, undefined>, import("valibot").DescriptionAction<{
   confidence?: "high" | "medium" | "low" | undefined;
@@ -112,13 +112,13 @@ declare const declarativeFindingSchema: import("valibot").SchemaWithPipe<readonl
   line: number;
   message: string;
   suggestion?: string | undefined;
-}, "One declarative rule finding.">]>;
+}, "One declarative rule finding. Report only a change the reviewed target must make.">]>;
 declare const declarativeFindingResponseSchema: import("valibot").SchemaWithPipe<readonly [import("valibot").ObjectSchema<{
   readonly findings: import("valibot").SchemaWithPipe<readonly [import("valibot").ArraySchema<import("valibot").SchemaWithPipe<readonly [import("valibot").ObjectSchema<{
     readonly confidence: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").PicklistSchema<["high", "medium", "low"], undefined>, import("valibot").DescriptionAction<"high" | "medium" | "low", "Confidence in this finding. Use exactly \"high\", \"medium\", or \"low\" when confidence is known.">]>, undefined>;
     readonly filePath: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").DescriptionAction<string, "Path to the file that owns this finding. Omit when the finding belongs to the reviewed target file.">]>, undefined>;
     readonly line: import("valibot").SchemaWithPipe<readonly [import("valibot").NumberSchema<undefined>, import("valibot").DescriptionAction<number, "Use the left-column line number from the numbered source block.">]>;
-    readonly message: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").DescriptionAction<string, "Human-readable diagnostic message describing the issue.">]>;
+    readonly message: import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").DescriptionAction<string, "Human-readable diagnostic message describing the problem the target must fix. Never describe the absence of a problem.">]>;
     readonly suggestion: import("valibot").OptionalSchema<import("valibot").SchemaWithPipe<readonly [import("valibot").StringSchema<undefined>, import("valibot").DescriptionAction<string, "Concrete remediation direction for the finding.">]>, undefined>;
   }, undefined>, import("valibot").DescriptionAction<{
     confidence?: "high" | "medium" | "low" | undefined;
@@ -126,13 +126,13 @@ declare const declarativeFindingResponseSchema: import("valibot").SchemaWithPipe
     line: number;
     message: string;
     suggestion?: string | undefined;
-  }, "One declarative rule finding.">]>, undefined>, import("valibot").DescriptionAction<{
+  }, "One declarative rule finding. Report only a change the reviewed target must make.">]>, undefined>, import("valibot").DescriptionAction<{
     confidence?: "high" | "medium" | "low" | undefined;
     filePath?: string | undefined;
     line: number;
     message: string;
     suggestion?: string | undefined;
-  }[], "All findings for the declarative rule. Return an empty array when there are no issues.">]>;
+  }[], "All findings for the declarative rule. Return an empty array when there are no issues, and never add a finding that only states the target is already correct.">]>;
 }, undefined>, import("valibot").DescriptionAction<{
   findings: {
     confidence?: "high" | "medium" | "low" | undefined;

package/dist/index.mjs

@@ -1,8 +1,8 @@
+import { access, mkdir, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, normalize, posix, relative, resolve, sep, win32 } from "node:path";
 import { loadConfig } from "c12";
 import { createJiti } from "jiti/static";
 import { createHash, randomUUID } from "node:crypto";
-import { access, mkdir, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { array, boolean, check, description, finite, integer, literal, looseObject, maxValue, minValue, nonEmpty, number, object, optional, parse, picklist, pipe, record, strictObject, string, transform, tupleWithRest, undefined_, union, unknown, variant } from "valibot";
 import process from "node:process";
 import { homedir } from "node:os";
@@ -104,10 +104,10 @@ const declarativeFindingSchema = pipe(object({
 	]), description("Confidence in this finding. Use exactly \"high\", \"medium\", or \"low\" when confidence is known."))),
 	filePath: optional(pipe(string(), description("Path to the file that owns this finding. Omit when the finding belongs to the reviewed target file."))),
 	line: pipe(number(), description("Use the left-column line number from the numbered source block.")),
-	message: pipe(string(), description("Human-readable diagnostic message describing the issue.")),
+	message: pipe(string(), description("Human-readable diagnostic message describing the problem the target must fix. Never describe the absence of a problem.")),
 	suggestion: optional(pipe(string(), description("Concrete remediation direction for the finding.")))
-}), description("One declarative rule finding."));
-const declarativeFindingResponseSchema = pipe(object({ findings: pipe(array(declarativeFindingSchema), description("All findings for the declarative rule. Return an empty array when there are no issues.")) }), description("Structured declarative rule findings."));
+}), description("One declarative rule finding. Report only a change the reviewed target must make."));
+const declarativeFindingResponseSchema = pipe(object({ findings: pipe(array(declarativeFindingSchema), description("All findings for the declarative rule. Return an empty array when there are no issues, and never add a finding that only states the target is already correct.")) }), description("Structured declarative rule findings."));
 function isBuiltInAgentName(value) {
 	return builtInAgentNames.includes(value);
 }
@@ -195,6 +195,89 @@ function parseDeclarativeRuleFileInput(input, filePath) {
 	}
 }
 //#endregion
+//#region src/plugins/declarative/cache-key.ts
+/**
+* Behavior version of each built-in agent.
+*
+* A declarative rule is built from a shared factory, so the rule source that the run engine
+* hashes is identical for every declarative rule. Nothing in that source tells the engine what
+* the preset actually sends to the model: the instruction, the supplemental files, and the
+* message layout all sit in the rule definition or in this package.
+*
+* Bump the version of an agent when its prompt assembly, message layout, or finding reporting
+* changes, so cached findings never outlive the behavior that produced them.
+*/
+const builtInAgentVersions = {
+	"basic-coding-agent": 1,
+	"basic-structured": 1
+};
+/**
+* Cache key for one declarative rule: every declared input that changes its findings.
+*
+* Without it, editing `instruction` in `rule.alint.toml` leaves the rule source untouched, the
+* cache fingerprint stays equal, and the next run replays findings the new rule text would never
+* produce. The run only reports that the entry was a cache hit, so the stale result is silent.
+*
+* @see {@link builtInAgentVersions}
+*/
+function createDeclarativeCacheKey(rule) {
+	return {
+		agent: rule.builtInAgent,
+		agentVersion: builtInAgentVersions[rule.builtInAgent],
+		excludeFiles: rule.excludeFiles,
+		includeFiles: rule.includeFiles,
+		instruction: rule.instruction
+	};
+}
+//#endregion
+//#region src/plugins/declarative/findings.ts
+/**
+* Phrases that report the absence of a problem instead of reporting nothing.
+*
+* A clean target makes some models answer with a finding that asserts compliance, for example
+* "No violations found." The finding has the shape of a real one, so it reaches the reporter and
+* renders as a diagnostic whose remediation is "change nothing", with a confidence that makes it
+* look as trustworthy as a real hit.
+*
+* Every pattern requires an explicit compliance verb ("found", "needed", "compliant") so a real
+* finding that merely starts with a negative word survives: "No guard clause before the loop" is
+* a missing guard, not a statement that the file is clean.
+*/
+const compliancePatterns = [
+	/\bno\s+(?:\w+\s+){0,4}(?:violations?|issues?|problems?)\s+(?:\w+\s+){0,3}(?:found|detected|identified|present)\b/iu,
+	/\bno\s+(?:\w+\s+){0,3}(?:action|change|changes|fix|fixes|modification|modifications)\s+(?:\w+\s+){0,2}(?:needed|required|necessary)\b/iu,
+	/\bnothing\s+(?:to|needs?\s+to)\s+(?:address|change|do|fix|report)\b/iu,
+	/\b(?:is|are|looks?|appears?|seems?)\s+(?:fully\s+|otherwise\s+)?compliant\b/iu,
+	/\bcompl(?:y|ies|iant)\s+with\b/iu,
+	/\b(?:is|are)\s+(?:already\s+)?(?:correct|fine|good)\b/iu,
+	/\b(?:lgtm|looks good|looks fine)\b/iu
+];
+/**
+* Compliance phrased in Simplified Chinese, which the output language option can request.
+*
+* "不符合规范" negates the same characters, so the pattern refuses to match right after 不 or 未.
+*/
+const chineseCompliancePattern = /没有(?:违规|问题)|未发现(?:问题|违规|异常)|(?<![不未])符合(?:规范|要求|约定|预期)|(?<![不未])无需(?:修改|改动)/u;
+/**
+* A negation anywhere in the message keeps the finding: the message may describe a violation,
+* such as "The module is not compliant with the rule."
+*/
+const negationPattern = /\b(?:can(?:no|'?t)|didn'?t|doesn'?t|don'?t|isn'?t|aren'?t|never|no longer|not)\b/iu;
+/**
+* Whether a finding asks for a change the reviewed target can act on.
+*
+* Judged on the message alone: a real violation whose suggestion happens to say "no further
+* change needed" is still a violation the reader has to see.
+*/
+function isActionableFinding(finding) {
+	return !isComplianceStatement(finding.message);
+}
+function isComplianceStatement(message) {
+	if (chineseCompliancePattern.test(message)) return true;
+	if (negationPattern.test(message)) return false;
+	return compliancePatterns.some((pattern) => pattern.test(message));
+}
+//#endregion
 //#region src/plugins/declarative/scope.ts
 function createReportScope(options) {
 	const includeFiles = options.includeFiles;
@@ -228,6 +311,7 @@ const maxSupplementalFiles = 12;
 function createBasicStructuredRule(rule) {
 	return {
 		cache: rule.includeFiles === void 0 || rule.includeFiles.length === 0,
+		cacheKey: createDeclarativeCacheKey(rule),
 		create: (ctx) => ({ 
 		/**
 		* Runs one structured declarative review for a planned file.
@@ -313,6 +397,10 @@ function reportDeclarativeFindings(options) {
 		targetFilePath: options.targetFilePath
 	});
 	for (const finding of options.findings) {
+		if (!isActionableFinding(finding)) {
+			options.ctx.logger.debug("Ignoring declarative finding that reports no issue", { message: finding.message });
+			continue;
+		}
 		const filePath = resolveFindingFilePath(options.ctx.cwd, options.targetFilePath, finding.filePath);
 		if (!scope.canReport(filePath)) {
 			options.ctx.logger.debug("Ignoring out-of-scope declarative finding", {
@@ -461,7 +549,7 @@ function createCodingAgent(model, runner = chat({
 			parameters: agentTool.parameters
 		}));
 		tools.push(rawTool({
-			description: "Submit all findings and finish the review. Submit an empty findings array when there are no issues.",
+			description: "Submit all findings and finish the review. Submit an empty findings array when there are no issues, instead of a finding that states the target is already correct.",
 			execute: async (input) => {
 				report = parse(declarativeFindingResponseSchema, input);
 				return report;
@@ -484,7 +572,7 @@ function createCodingAgent(model, runner = chat({
 			instructions: [
 				options.instruction,
 				"Use the filesystem tools to inspect the project as needed before reaching a conclusion.",
-				`When the review is complete, call ${reportFindingsToolName} exactly once with all findings. Submit an empty findings array when there are no issues.`
+				`When the review is complete, call ${reportFindingsToolName} exactly once with all findings. Submit an empty findings array when there are no issues, instead of a finding that states the target is already correct.`
 			].join("\n\n"),
 			tools,
 			turnId: "alint"
@@ -1167,6 +1255,38 @@ function toAlintConfigItems(value, options = {}) {
 }
 //#endregion
 //#region src/config/load.ts
+/**
+* Config file names a nested config may use, mirroring what c12 resolves for the root.
+*
+* @see {@link loadConfig} `configFile`
+*/
+const nestedConfigFileNames = [
+	"alint.config.cjs",
+	"alint.config.cts",
+	"alint.config.js",
+	"alint.config.json",
+	"alint.config.json5",
+	"alint.config.jsonc",
+	"alint.config.mjs",
+	"alint.config.mts",
+	"alint.config.toml",
+	"alint.config.ts",
+	"alint.config.yaml",
+	"alint.config.yml"
+];
+/**
+* Directories that never hold a config a project means to run.
+*
+* Hidden directories are skipped wholesale so `.git`, `.cache`, and `.next` cost no lookups.
+*/
+const skippedDiscoveryDirectoryNames = /* @__PURE__ */ new Set([
+	"build",
+	"coverage",
+	"dist",
+	"node_modules",
+	"out",
+	"vendor"
+]);
 async function loadAlintConfig(cwd, configFile) {
 	return (await loadAlintConfigWithMetadata(cwd, configFile)).config;
 }
@@ -1197,10 +1317,88 @@ async function loadAlintConfigWithMetadata(cwd, configFile) {
 async function loadStaticConfig(cwd, configFile) {
 	return (await loadStaticConfigSource(cwd, configFile)).config;
 }
+/**
+* Rejects two config files claiming one plugin alias with different plugins.
+*
+* The lock file is keyed by alias, so the second specifier would silently win and every rule id
+* from the first plugin would come from the wrong plugin.
+*/
+function assertDistinctPluginAliases(sources) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const source of sources) for (const group of source.config.groups) for (const reference of group.plugins) {
+		const key = getPluginSpecifierKey(reference.specifier);
+		const previous = seen.get(reference.alias);
+		if (previous === void 0) {
+			seen.set(reference.alias, {
+				configFile: source.configFile,
+				key
+			});
+			continue;
+		}
+		if (previous.key === key) continue;
+		throw new Error(`Static plugin "${reference.alias}" is configured in ${formatConfigOrigin(previous.configFile)} and ${formatConfigOrigin(source.configFile)} with different specifiers ("${previous.key}" and "${key}"). Nested configs share one plugin lock file, so give each plugin a distinct alias.`);
+	}
+}
+async function collectNestedConfigFiles(root, directory, found) {
+	let entries;
+	try {
+		entries = await readdir(directory, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	const childDirectories = [];
+	for (const entry of entries) {
+		const path = join(directory, entry.name);
+		if (entry.isDirectory()) {
+			if (!shouldSkipDiscoveryDirectory(entry.name)) childDirectories.push(path);
+			continue;
+		}
+		if (entry.isFile() && directory !== root && nestedConfigFileNames.includes(entry.name)) found.push(path);
+	}
+	for (const child of childDirectories.sort()) await collectNestedConfigFiles(root, child, found);
+}
+function directoryDepth(path) {
+	return path.split(sep).length;
+}
+async function discoverNestedConfigFiles(cwd) {
+	const found = [];
+	await collectNestedConfigFiles(cwd, cwd, found);
+	return found.sort((left, right) => {
+		const depthDifference = directoryDepth(left) - directoryDepth(right);
+		return depthDifference === 0 ? left.localeCompare(right) : depthDifference;
+	});
+}
+function formatConfigOrigin(configFile) {
+	return configFile ?? "the inline config";
+}
 function formatPluginReferences(references) {
 	return references.map((reference) => `${reference.alias} (${reference.specifier.raw})`).join(", ");
 }
-async function loadStaticConfigSource(cwd, configFile) {
+/**
+* Loads every `alint.config.*` below `cwd`, except the root config itself.
+*
+* A package that owns its rules writes one config next to its code instead of registering a
+* directory plugin in the root config, scoping the plugin, and repeating that scope in every
+* tool that reads it. Discovery is depth-first, parents before children, so a deeper config
+* overrides an outer one the same way a later flat-config item does.
+*/
+async function loadNestedStaticConfigSources(cwd) {
+	const configFiles = await discoverNestedConfigFiles(cwd);
+	const sources = [];
+	for (const configFile of configFiles) {
+		const directory = dirname(configFile);
+		const source = await loadSingleStaticConfigSource(directory, basename(configFile), { dotenv: false });
+		if (source.configFile === void 0) continue;
+		sources.push({
+			config: source.config,
+			configFile: source.configFile,
+			relativeDirectory: toPosixPath(relative(cwd, directory))
+		});
+	}
+	return sources;
+}
+/** Loads one config file in one directory. The root and every nested config go through here. */
+async function loadSingleStaticConfigSource(cwd, configFile, options = {}) {
 	const jiti = createJiti(resolve(cwd, configFile ?? "alint.config"), {
 		interopDefault: true,
 		moduleCache: false
@@ -1208,7 +1406,7 @@ async function loadStaticConfigSource(cwd, configFile) {
 	const result = await loadConfig({
 		configFile,
 		cwd,
-		dotenv: true,
+		dotenv: options.dotenv ?? true,
 		import: (id) => jiti.import(id),
 		name: "alint"
 	});
@@ -1219,6 +1417,51 @@ async function loadStaticConfigSource(cwd, configFile) {
 		configFile: resolvedConfigFile
 	};
 }
+async function loadStaticConfigSource(cwd, configFile) {
+	const root = await loadSingleStaticConfigSource(cwd, configFile);
+	if (configFile !== void 0) return root;
+	const nested = await loadNestedStaticConfigSources(cwd);
+	if (nested.length === 0) return root;
+	assertDistinctPluginAliases([{
+		config: root.config,
+		configFile: root.configFile
+	}, ...nested]);
+	return {
+		config: { groups: [...root.config.groups, ...nested.flatMap((source) => scopeNestedGroups(source))] },
+		configFile: root.configFile
+	};
+}
+/**
+* Scopes one nested config item to the directory that declares it.
+*
+* `basePath` makes every pattern in the item resolve against that directory, so an `ignores`
+* entry or a plugin config the item extends stays inside it. The two defaults cover the item
+* shapes that declare no patterns at all: without them a rule set written next to a package
+* would silently apply to the whole repository.
+*
+* Limits: an item cannot target the project root (`onTargetProject`) from a nested config,
+* because the project target sits outside the item's base path.
+*/
+function scopeNestedConfigItem(item, relativeDirectory) {
+	return {
+		...item,
+		basePath: item.basePath === void 0 ? relativeDirectory : `${relativeDirectory}/${toPosixPath(item.basePath)}`,
+		directories: item.directories ?? ["**"],
+		files: item.files ?? ["**/*"]
+	};
+}
+function scopeNestedGroups(source) {
+	return source.config.groups.map((group) => ({
+		...group,
+		item: scopeNestedConfigItem(group.item, source.relativeDirectory)
+	}));
+}
+function shouldSkipDiscoveryDirectory(name) {
+	return name.startsWith(".") || skippedDiscoveryDirectoryNames.has(name);
+}
+function toPosixPath(path) {
+	return path.split(sep).join("/");
+}
 //#endregion
 //#region src/config/stop-gate-write.ts
 async function setStopGateConfig(options) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alint-js/config",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Configuration loading and setup utilities for alint",
   "license": "MIT",
   "repository": {
@@ -41,9 +41,9 @@
     "tar-stream": "^3.2.0",
     "valibot": "^1.4.2",
     "xdg-basedir": "^5.1.0",
-    "@alint-js/core": "0.7.0",
-    "@alint-js/tools-fs": "0.7.0",
-    "@alint-js/utils": "0.7.0"
+    "@alint-js/core": "0.7.2",
+    "@alint-js/utils": "0.7.2",
+    "@alint-js/tools-fs": "0.7.2"
   },
   "devDependencies": {
     "@types/tar-stream": "^3.1.4",