@alint-js/config 0.0.21 → 0.0.23

package/dist/index.d.mts

@@ -69,6 +69,98 @@ declare function getProjectPluginStorePath(cwd: string): string;
 declare function getProjectSetupConfigPath(cwd: string): string;
 declare function getStatsDir(env?: NodeJS.ProcessEnv, options?: GlobalSetupConfigPathOptions): string;
 //#endregion
+//#region src/plugins/declarative/types.d.ts
+declare const builtInAgentNames: readonly ["basic-structured", "basic-coding-agent"];
+declare const declarativeRuleFilePattern = "**/rule.alint.{toml,yaml,yml,json,jsonc,json5}";
+type BuiltInAgentName = typeof builtInAgentNames[number];
+interface DeclarativeFinding {
+  confidence?: 'high' | 'low' | 'medium';
+  filePath?: string;
+  line: number;
+  message: string;
+  suggestion?: string;
+}
+interface DeclarativeFindingResponse {
+  findings: DeclarativeFinding[];
+}
+declare const declarativeFindingSchema: 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 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;
+  filePath?: string | undefined;
+  line: number;
+  message: string;
+  suggestion?: string | undefined;
+}, "One declarative rule finding.">]>;
+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 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;
+    filePath?: string | undefined;
+    line: number;
+    message: string;
+    suggestion?: string | undefined;
+  }, "One declarative rule finding.">]>, 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.">]>;
+}, undefined>, import("valibot").DescriptionAction<{
+  findings: {
+    confidence?: "high" | "medium" | "low" | undefined;
+    filePath?: string | undefined;
+    line: number;
+    message: string;
+    suggestion?: string | undefined;
+  }[];
+}, "Structured declarative rule findings.">]>;
+interface DeclarativeRuleDefinition {
+  builtInAgent: BuiltInAgentName;
+  excludeFiles: string[];
+  filePath: string;
+  includeFiles?: string[];
+  instruction: string;
+  name: string;
+}
+declare function isBuiltInAgentName(value: unknown): value is BuiltInAgentName;
+//#endregion
+//#region src/plugins/declarative/parse.d.ts
+interface LoadDeclarativeRulesOptions {
+  alias: string;
+  root: string;
+}
+declare function hasDeclarativeRuleFiles(root: string): Promise<boolean>;
+declare function loadDeclarativeRules(options: LoadDeclarativeRulesOptions): Promise<DeclarativeRuleDefinition[]>;
+//#endregion
+//#region src/plugins/declarative/plugin.d.ts
+interface CreateDeclarativePluginOptions {
+  rules: readonly DeclarativeRuleDefinition[];
+}
+declare function createDeclarativePlugin(options: CreateDeclarativePluginOptions): PluginDefinition;
+//#endregion
+//#region src/plugins/declarative/scope.d.ts
+interface CreateReportScopeOptions {
+  cwd: string;
+  excludeFiles: readonly string[];
+  includeFiles?: readonly string[];
+  targetFilePath?: string;
+}
+interface ReportScope {
+  canReport: (filePath: string | undefined) => boolean;
+}
+declare function createReportScope(options: CreateReportScopeOptions): ReportScope;
+//#endregion
 //#region src/plugins/types.d.ts
 interface DirectoryPluginLockEntry {
   alias: string;
@@ -153,4 +245,4 @@ declare function stringifySetupConfigToml(config: SetupConfig$1): string;
 //#region src/setup/write.d.ts
 declare function writeSetupConfig(filePath: string, config: SetupConfig$1): Promise<void>;
 //#endregion
-export { type AlintConfig, type DirectoryPluginLockEntry, type GlobalSetupConfigPathOptions, type ModelSize, type ParseStaticConfigOptions, type ParsedDirectoryPluginLockEntry, type ParsedPluginLockEntry, type ParsedPluginLockFile, type ParsedPluginSpecifier, type ParsedRegistryPluginLockEntry, type ParsedStaticConfig, type ParsedStaticConfigGroup, type PluginLockEntry, type PluginLockFile, type ProviderDefinition, type ProviderType, type RegistryPluginLockEntry, type RunnerConfig, type RunnerStatsConfig, type SetupConfig, type SetupModelDefinition, type StaticConfigInput, type StaticConfigItem, type StaticPluginInstallOptions, type StaticPluginInstallResult, type StaticPluginReference, type StaticPluginResolver, type ToAlintConfigOptions, createEmptyPluginLockFile, emptySetupConfig, getGlobalSetupConfigPath, getProjectPluginLockPath, getProjectPluginStorePath, getProjectSetupConfigPath, getStatsDir, ignorePatternsAIAgents, ignorePatternsBuildOutputs, ignorePatternsCaches, ignorePatternsCommon, ignorePatternsEslintDefaults, ignorePatternsGenerated, installStaticPlugins, listMissing, listUnresolved, loadAlintConfig, loadPluginLockFile, loadSetupConfig, loadStaticConfig, mergeSetupConfigs, parsePluginLockFile, parsePluginSpecifier, parseSetupConfigToml, parseStaticConfig, stringifySetupConfigToml, toAlintConfig, writePluginLockFile, writeSetupConfig };
+export { type AlintConfig, BuiltInAgentName, CreateDeclarativePluginOptions, CreateReportScopeOptions, DeclarativeFinding, DeclarativeFindingResponse, DeclarativeRuleDefinition, type DirectoryPluginLockEntry, type GlobalSetupConfigPathOptions, LoadDeclarativeRulesOptions, type ModelSize, type ParseStaticConfigOptions, type ParsedDirectoryPluginLockEntry, type ParsedPluginLockEntry, type ParsedPluginLockFile, type ParsedPluginSpecifier, type ParsedRegistryPluginLockEntry, type ParsedStaticConfig, type ParsedStaticConfigGroup, type PluginLockEntry, type PluginLockFile, type ProviderDefinition, type ProviderType, type RegistryPluginLockEntry, ReportScope, type RunnerConfig, type RunnerStatsConfig, type SetupConfig, type SetupModelDefinition, type StaticConfigInput, type StaticConfigItem, type StaticPluginInstallOptions, type StaticPluginInstallResult, type StaticPluginReference, type StaticPluginResolver, type ToAlintConfigOptions, builtInAgentNames, createDeclarativePlugin, createEmptyPluginLockFile, createReportScope, declarativeFindingResponseSchema, declarativeFindingSchema, declarativeRuleFilePattern, emptySetupConfig, getGlobalSetupConfigPath, getProjectPluginLockPath, getProjectPluginStorePath, getProjectSetupConfigPath, getStatsDir, hasDeclarativeRuleFiles, ignorePatternsAIAgents, ignorePatternsBuildOutputs, ignorePatternsCaches, ignorePatternsCommon, ignorePatternsEslintDefaults, ignorePatternsGenerated, installStaticPlugins, isBuiltInAgentName, listMissing, listUnresolved, loadAlintConfig, loadDeclarativeRules, loadPluginLockFile, loadSetupConfig, loadStaticConfig, mergeSetupConfigs, parsePluginLockFile, parsePluginSpecifier, parseSetupConfigToml, parseStaticConfig, stringifySetupConfigToml, toAlintConfig, writePluginLockFile, writeSetupConfig };

package/dist/index.mjs

@@ -1,16 +1,20 @@
-import { dirname, isAbsolute, join, normalize, posix, relative, resolve, sep, win32 } from "node:path";
+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 { mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
-import { array, boolean, literal, looseObject, optional, parse, picklist, record, strictObject, string, tuple, union, unknown, variant } from "valibot";
+import { access, mkdir, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { array, boolean, check, description, literal, looseObject, number, object, optional, parse, picklist, pipe, record, strictObject, string, tuple, union, unknown, variant } from "valibot";
 import process from "node:process";
 import { homedir } from "node:os";
-import { dirname as dirname$1, extname, join as join$1 } from "pathe";
+import { dirname as dirname$1, extname, join as join$1, normalize as normalize$1 } from "pathe";
 import { xdgConfig } from "xdg-basedir";
-import { isError } from "@moeru/std/error";
-import { exports } from "resolve.exports";
+import { errorMessageFrom, isError } from "@moeru/std/error";
+import { formatOutputLanguageInstruction, formatSourceWithLineNumbers, generateStructured, toolParametersFromSchema } from "@alint-js/core/structured-output";
+import { createTools, listFiles } from "@alint-js/tools-fs";
+import { chat, hasToolCall, or, rawTool, stepCountAtLeast, user } from "apeira";
 import { Buffer } from "node:buffer";
+import { minimatch } from "minimatch";
+import { exports } from "resolve.exports";
 import { createWriteStream } from "node:fs";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
@@ -88,6 +92,386 @@ function parseIntegrity(integrity, specifier) {
 	};
 }
 //#endregion
+//#region src/plugins/declarative/types.ts
+const builtInAgentNames = ["basic-structured", "basic-coding-agent"];
+const declarativeRuleFilePattern = "**/rule.alint.{toml,yaml,yml,json,jsonc,json5}";
+const declarativeFindingSchema = pipe(object({
+	confidence: optional(pipe(picklist([
+		"high",
+		"medium",
+		"low"
+	]), 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.")),
+	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."));
+function isBuiltInAgentName(value) {
+	return builtInAgentNames.includes(value);
+}
+//#endregion
+//#region src/plugins/declarative/parse.ts
+const declarativeRuleFileNamePattern = /^rule\.alint\.(?:toml|ya?ml|json|jsonc|json5)$/;
+const declarativeRuleNamePattern = /^[\w.-]+$/;
+const nonEmptyStringSchema = pipe(string(), check((value) => value.trim() !== "", "must be a non-empty string"));
+const declarativeRuleFileSchema = object({
+	builtInAgent: picklist(builtInAgentNames),
+	excludeFiles: optional(array(string())),
+	includeFiles: optional(array(string())),
+	instruction: nonEmptyStringSchema,
+	name: pipe(nonEmptyStringSchema, check((value) => declarativeRuleNamePattern.test(value), "Declarative rule \"name\" must contain only letters, numbers, dots, underscores, and hyphens."))
+});
+async function hasDeclarativeRuleFiles(root) {
+	return (await findDeclarativeRuleFiles(root)).length > 0;
+}
+async function loadDeclarativeRules(options) {
+	const files = await findDeclarativeRuleFiles(options.root);
+	if (files.length === 0) throw new Error(`Directory plugin "${options.alias}" must contain package.json or rule.alint.* files.`);
+	const rules = [];
+	const filesByName = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const rule = await loadDeclarativeRuleFile(file);
+		const duplicateFile = filesByName.get(rule.name);
+		if (duplicateFile !== void 0) throw new Error(`Duplicate declarative rule name "${rule.name}" in ${file} and ${duplicateFile}.`);
+		filesByName.set(rule.name, file);
+		rules.push(rule);
+	}
+	return rules;
+}
+async function collectDeclarativeRuleFiles(directory, files) {
+	const entries = await readdir(directory, { withFileTypes: true });
+	await Promise.all(entries.map(async (entry) => {
+		const path = join(directory, entry.name);
+		if (entry.isDirectory()) {
+			await collectDeclarativeRuleFiles(path, files);
+			return;
+		}
+		if (entry.isFile() && declarativeRuleFileNamePattern.test(entry.name)) files.push(path);
+	}));
+}
+async function findDeclarativeRuleFiles(root) {
+	const files = [];
+	await collectDeclarativeRuleFiles(root, files);
+	return files.sort((left, right) => left.localeCompare(right));
+}
+function isPlainObject$3(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function loadDeclarativeRuleFile(filePath) {
+	const input = await loadDeclarativeRuleFileContent(filePath);
+	if (!isPlainObject$3(input)) throw new Error(`Declarative rule file ${filePath} must contain an object.`);
+	const parsed = parseDeclarativeRuleFileInput(input, filePath);
+	return {
+		builtInAgent: parsed.builtInAgent,
+		excludeFiles: parsed.excludeFiles ?? [],
+		filePath,
+		includeFiles: parsed.includeFiles,
+		instruction: parsed.instruction,
+		name: parsed.name
+	};
+}
+async function loadDeclarativeRuleFileContent(filePath) {
+	try {
+		return (await loadConfig({
+			configFile: basename(filePath),
+			cwd: dirname(filePath),
+			envName: false,
+			extend: false,
+			packageJson: false,
+			rcFile: false
+		})).config;
+	} catch (error) {
+		throw new Error(`Could not parse declarative rule file ${filePath}: ${errorMessageFrom(error) ?? "Unknown error"}`, { cause: error });
+	}
+}
+function parseDeclarativeRuleFileInput(input, filePath) {
+	try {
+		return parse(declarativeRuleFileSchema, input);
+	} catch (error) {
+		if (typeof input.builtInAgent === "string" && !isBuiltInAgentName(input.builtInAgent)) throw new Error(`Unknown builtInAgent "${input.builtInAgent}" in ${filePath}.`, { cause: error });
+		throw new Error(`Invalid declarative rule file ${filePath}: ${errorMessageFrom(error) ?? "Unknown error"}`, { cause: error });
+	}
+}
+//#endregion
+//#region src/plugins/declarative/scope.ts
+function createReportScope(options) {
+	const includeFiles = options.includeFiles;
+	const excludeFiles = options.excludeFiles;
+	const rawTargetFilePath = options.targetFilePath;
+	const hasTargetFilePath = rawTargetFilePath !== void 0;
+	const targetFilePath = rawTargetFilePath === void 0 ? void 0 : toScopedRelativePath(options.cwd, rawTargetFilePath);
+	return { canReport(filePath) {
+		if (filePath === void 0) return !hasTargetFilePath && includeFiles === void 0;
+		const relativePath = toScopedRelativePath(options.cwd, filePath);
+		if (relativePath === void 0) return false;
+		if (!(includeFiles === void 0 ? targetFilePath !== void 0 && relativePath === targetFilePath : includeFiles.some((pattern) => minimatch(relativePath, pattern, { dot: true })))) return false;
+		return !excludeFiles.some((pattern) => minimatch(relativePath, pattern, { dot: true }));
+	} };
+}
+function isOutsideScopePath(path) {
+	return path === ".." || path.startsWith("../") || isAbsolute(path) || win32.isAbsolute(path) || /^[A-Za-z]:/u.test(path);
+}
+function normalizePath(path) {
+	return normalize$1(path).replace(/^\.\//u, "");
+}
+function toScopedRelativePath(cwd, filePath) {
+	const path = normalizePath(relative(cwd, filePath));
+	if (isOutsideScopePath(path)) return;
+	return path;
+}
+//#endregion
+//#region src/agents/presets/basic-structured.ts
+const maxSupplementalFileBytes = 64 * 1024;
+const maxSupplementalFiles = 12;
+function createBasicStructuredRule(rule) {
+	return {
+		cache: rule.includeFiles === void 0 || rule.includeFiles.length === 0,
+		create: (ctx) => ({ async onTargetFile(target) {
+			const model = await ctx.model();
+			const supplementalFiles = await collectSupplementalFiles({
+				cwd: ctx.cwd,
+				includeFiles: rule.includeFiles,
+				logger: ctx.logger,
+				targetFilePath: target.file.path
+			});
+			const { findings } = await generateStructured({
+				createMessages: (retryFeedback) => createStructuredMessagesSync({
+					cwd: ctx.cwd,
+					includeFiles: rule.includeFiles,
+					instruction: rule.instruction,
+					outputLanguage: ctx.outputLanguage,
+					retryFeedback,
+					ruleFilePath: rule.filePath,
+					sourceText: target.file.text,
+					supplementalFiles,
+					targetFilePath: target.file.path
+				}),
+				logger: ctx.logger,
+				metering: ctx.metering,
+				model,
+				operation: `declarative-${rule.name}-structured`,
+				schema: declarativeFindingResponseSchema
+			});
+			reportDeclarativeFindings({
+				ctx,
+				excludeFiles: rule.excludeFiles,
+				findings,
+				includeFiles: rule.includeFiles,
+				targetFilePath: target.file.path
+			});
+		} })
+	};
+}
+function createStructuredMessagesSync(options) {
+	return [
+		{
+			content: options.instruction,
+			role: "system"
+		},
+		...options.retryFeedback ? [{
+			content: options.retryFeedback,
+			role: "user"
+		}] : [],
+		{
+			content: [
+				formatOutputLanguageInstruction(options.outputLanguage),
+				`Rule file path: ${options.ruleFilePath}`,
+				`Reviewed target file path: ${options.targetFilePath}`,
+				formatSupplementalFiles(options.cwd, options.supplementalFiles ?? []),
+				`Reviewed target source with line numbers:\n\n${formatSourceWithLineNumbers(options.sourceText)}`
+			].filter(Boolean).join("\n\n"),
+			role: "user"
+		}
+	];
+}
+function reportDeclarativeFindings(options) {
+	const scope = createReportScope({
+		cwd: options.ctx.cwd,
+		excludeFiles: options.excludeFiles,
+		includeFiles: options.includeFiles,
+		targetFilePath: options.targetFilePath
+	});
+	for (const finding of options.findings) {
+		const filePath = resolveFindingFilePath(options.ctx.cwd, options.targetFilePath, finding.filePath);
+		if (!scope.canReport(filePath)) {
+			options.ctx.logger.debug("Ignoring out-of-scope declarative finding", {
+				filePath,
+				message: finding.message
+			});
+			continue;
+		}
+		const evidence = createFindingEvidence(finding);
+		options.ctx.report({
+			...evidence ? { evidence } : {},
+			filePath,
+			loc: { start: {
+				column: 0,
+				line: finding.line
+			} },
+			message: finding.message
+		});
+	}
+}
+async function collectSupplementalFiles(options) {
+	if (options.includeFiles === void 0 || options.includeFiles.length === 0) return [];
+	const targetFilePath = resolve(options.targetFilePath);
+	const filePaths = (await listFiles(options.cwd, { patterns: options.includeFiles })).map((filePath) => resolve(filePath)).filter((filePath) => filePath !== targetFilePath).sort().slice(0, maxSupplementalFiles);
+	const files = [];
+	for (const filePath of filePaths) {
+		const content = await readSupplementalFile(filePath, options.logger);
+		if (content === void 0) continue;
+		files.push({
+			content,
+			filePath
+		});
+	}
+	return files;
+}
+function createFindingEvidence(finding) {
+	const evidence = {
+		...finding.confidence ? { confidence: finding.confidence } : {},
+		...finding.suggestion ? { suggestion: finding.suggestion } : {}
+	};
+	return Object.keys(evidence).length > 0 ? evidence : void 0;
+}
+function formatSupplementalFiles(cwd, files) {
+	if (files.length === 0) return;
+	return ["Supplemental files:", ...files.map((file) => [`File: ${relative(cwd, file.filePath)}`, file.content].join("\n\n"))].join("\n\n");
+}
+async function readSupplementalFile(filePath, logger) {
+	let handle;
+	try {
+		handle = await open(filePath, "r");
+		const buffer = Buffer.alloc(65537);
+		const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+		if (bytesRead > maxSupplementalFileBytes) {
+			logger?.debug("Skipping oversized declarative supplemental file", {
+				filePath,
+				maxBytes: maxSupplementalFileBytes
+			});
+			return;
+		}
+		return buffer.subarray(0, bytesRead).toString("utf8");
+	} catch (error) {
+		logger?.debug("Skipping unreadable declarative supplemental file", {
+			error,
+			filePath
+		});
+		return;
+	} finally {
+		await handle?.close();
+	}
+}
+function resolveFindingFilePath(cwd, targetFilePath, findingFilePath) {
+	if (findingFilePath === void 0 || findingFilePath.length === 0) return targetFilePath;
+	return isAbsolute(findingFilePath) ? findingFilePath : resolve(cwd, findingFilePath);
+}
+//#endregion
+//#region src/agents/presets/basic-coding-agent.ts
+const maxAgentSteps = 8;
+const reportFindingsToolName = "report_findings";
+function createBasicCodingAgentRule(rule) {
+	return {
+		cache: false,
+		create: (ctx) => ({ async onTargetFile(target) {
+			const model = await ctx.model();
+			const result = await createCodingAgent(model).run({
+				cwd: ctx.cwd,
+				instruction: rule.instruction,
+				outputLanguage: ctx.outputLanguage,
+				sourceText: target.file.text,
+				targetFilePath: target.file.path,
+				tools: createTools(ctx.cwd)
+			});
+			if (result.usage) ctx.metering.recordUsage({
+				filePath: target.file.path,
+				inputTokens: result.usage.inputTokens,
+				metadata: { operation: `declarative-${rule.name}-coding-agent` },
+				modelId: model.id,
+				outputTokens: result.usage.outputTokens,
+				providerId: model.provider.id,
+				ruleId: ctx.id,
+				totalTokens: result.usage.totalTokens
+			});
+			reportDeclarativeFindings({
+				ctx,
+				excludeFiles: rule.excludeFiles,
+				findings: result.findings,
+				includeFiles: rule.includeFiles,
+				targetFilePath: target.file.path
+			});
+		} })
+	};
+}
+function createCodingAgent(model, runner = chat({
+	baseURL: model.provider.endpoint,
+	headers: model.provider.headers,
+	model: model.id,
+	parallelToolCalls: false,
+	stopWhen: or(hasToolCall(reportFindingsToolName), stepCountAtLeast(maxAgentSteps)),
+	toolChoice: "required"
+})) {
+	return { async run(options) {
+		let report;
+		const tools = options.tools.map((agentTool) => rawTool({
+			description: agentTool.description,
+			execute: async (input) => {
+				return await agentTool.execute(input) ?? "";
+			},
+			name: agentTool.name,
+			parameters: agentTool.parameters
+		}));
+		tools.push(rawTool({
+			description: "Submit all findings and finish the review. Submit an empty findings array when there are no issues.",
+			execute: async (input) => {
+				report = parse(declarativeFindingResponseSchema, input);
+				return report;
+			},
+			name: reportFindingsToolName,
+			parameters: toolParametersFromSchema(declarativeFindingResponseSchema),
+			strict: true
+		}));
+		const result = await runner({
+			channel: {
+				emit: () => {},
+				subscribe: () => () => {}
+			},
+			input: [user([
+				formatOutputLanguageInstruction(options.outputLanguage),
+				`Project root: ${options.cwd}`,
+				`Reviewed target file path: ${options.targetFilePath}`,
+				`Reviewed target source with line numbers:\n\n${formatSourceWithLineNumbers(options.sourceText)}`
+			].filter(Boolean).join("\n\n"))],
+			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.`
+			].join("\n\n"),
+			tools,
+			turnId: "alint"
+		});
+		if (!report) throw new Error(`basic-coding-agent stopped without calling ${reportFindingsToolName}`);
+		return {
+			findings: report.findings,
+			usage: result.usage ? {
+				inputTokens: result.usage.inputTokens,
+				outputTokens: result.usage.outputTokens,
+				totalTokens: result.usage.totalTokens
+			} : void 0
+		};
+	} };
+}
+//#endregion
+//#region src/plugins/declarative/plugin.ts
+function createDeclarativePlugin(options) {
+	return { rules: Object.fromEntries(options.rules.map((rule) => [rule.name, createDeclarativeRule(rule)])) };
+}
+function createDeclarativeRule(rule) {
+	if (rule.builtInAgent === "basic-coding-agent") return createBasicCodingAgentRule(rule);
+	return createBasicStructuredRule(rule);
+}
+//#endregion
 //#region src/plugins/sources/manifest.ts
 function resolveRelativeRootEntry(packageJson) {
 	const [entry] = exports(packageJson, ".", {
@@ -114,7 +498,7 @@ async function createLockEntry$1(installed, options) {
 }
 async function install$1(options) {
 	const packageDir = await canonicalRoot(options.alias, options.specifier.directory);
-	await validateRoot(options.alias, packageDir);
+	await validateInstallRoot(options.alias, packageDir);
 	return {
 		path: packageDir,
 		type: "directory"
@@ -124,10 +508,7 @@ async function resolve$2(entry) {
 	const lockedPath = isAbsolute(entry.lockEntry.path) || win32.isAbsolute(entry.lockEntry.path) ? entry.lockEntry.path : resolve(entry.cwd, entry.lockEntry.path);
 	const [packageDir, lockedPackageDir] = await Promise.all([lockedRoot(entry.alias, entry.specifier.directory, "configured"), lockedRoot(entry.alias, lockedPath, "locked")]);
 	if (packageDir !== lockedPackageDir) throw new Error(`Directory plugin "${entry.alias}" has moved or its symlink target changed. Run: alint plugin install`);
-	return {
-		cache: "content",
-		entry: await validateRoot(entry.alias, packageDir)
-	};
+	return validateResolvedRoot(entry.alias, packageDir);
 }
 async function canonicalRoot(alias, directory) {
 	let packageDir;
@@ -146,6 +527,15 @@ async function canonicalRoot(alias, directory) {
 	if (!directoryStat.isDirectory()) throw new Error(`Directory plugin "${alias}" path "${directory}" is not a directory.`);
 	return packageDir;
 }
+async function hasPackageJson(packageDir) {
+	try {
+		await access(join(packageDir, "package.json"));
+		return true;
+	} catch (error) {
+		if (isENOENTError(error)) return false;
+		throw error;
+	}
+}
 async function lockedRoot(alias, directory, source) {
 	try {
 		return await realpath(directory);
@@ -154,7 +544,25 @@ async function lockedRoot(alias, directory, source) {
 		throw new Error(`Could not resolve ${source} directory plugin "${alias}" at "${directory}".`, { cause: error });
 	}
 }
-async function validateRoot(alias, packageDir) {
+async function validateInstallRoot(alias, packageDir) {
+	if (await hasPackageJson(packageDir)) return {
+		alias,
+		cache: "content",
+		entry: await validatePackageRoot(alias, packageDir),
+		kind: "module"
+	};
+	await loadDeclarativeRules({
+		alias,
+		root: packageDir
+	});
+	return {
+		alias,
+		cache: "content",
+		entry: packageDir,
+		kind: "declarative"
+	};
+}
+async function validatePackageRoot(alias, packageDir) {
 	const manifestPath = join(packageDir, "package.json");
 	let packageJson;
 	try {
@@ -183,6 +591,21 @@ async function validateRoot(alias, packageDir) {
 	if (!entryStat.isFile()) throw new Error(`Directory plugin "${alias}" entry "${relativeEntry}" is not a regular file.`);
 	return physicalEntry;
 }
+async function validateResolvedRoot(alias, packageDir) {
+	if (await hasPackageJson(packageDir)) return {
+		alias,
+		cache: "content",
+		entry: await validatePackageRoot(alias, packageDir),
+		kind: "module"
+	};
+	if (!await hasDeclarativeRuleFiles(packageDir)) throw new Error(`Directory plugin "${alias}" must contain package.json or rule.alint.* files.`);
+	return {
+		alias,
+		cache: "content",
+		entry: packageDir,
+		kind: "declarative"
+	};
+}
 //#endregion
 //#region src/plugins/sources/package/index.ts
 function createLockEntry(installed, options) {
@@ -246,8 +669,10 @@ async function resolve$1(entry) {
 	if (!isPathInside(resolvedEntry, packageDir)) throw new Error(`Plugin lock entry "${entry.alias}" resolves outside the locked package directory.`);
 	JSON.parse(await readFile(join(packageDir, "package.json"), "utf8"));
 	return {
+		alias: entry.alias,
 		cache: "default",
-		entry: resolvedEntry
+		entry: resolvedEntry,
+		kind: "module"
 	};
 }
 async function extractEntry(packageDir, header, stream) {
@@ -563,6 +988,10 @@ function resolveDirectoryLockIdentity(path, cwd) {
 //#endregion
 //#region src/plugins/sources/import.ts
 async function importPlugin(target) {
+	if (target.kind === "declarative") return createDeclarativePlugin({ rules: await loadDeclarativeRules({
+		alias: target.alias,
+		root: target.entry
+	}) });
 	const url = pathToFileURL(target.entry);
 	if (target.cache === "content") url.searchParams.set("content", createHash("sha256").update(await readFile(target.entry)).digest("hex"));
 	return getDefaultExport(await import(url.href));
@@ -584,6 +1013,7 @@ const ruleConfigEntrySchema = union([ruleSeveritySchema, tuple([ruleSeveritySche
 const staticConfigItemSchema = looseObject({
 	agent: optional(unknown()),
 	basePath: optional(string()),
+	directories: optional(array(filePatternSchema)),
 	extends: optional(array(unknown())),
 	files: optional(array(filePatternSchema)),
 	ignore: optional(looseObject({ gitignore: optional(boolean()) })),
@@ -1094,4 +1524,4 @@ async function writeSetupConfig(filePath, config) {
 	await writeFile(filePath, stringifySetupConfigToml(config), "utf8");
 }
 //#endregion
-export { createEmptyPluginLockFile, emptySetupConfig, getGlobalSetupConfigPath, getProjectPluginLockPath, getProjectPluginStorePath, getProjectSetupConfigPath, getStatsDir, ignorePatternsAIAgents, ignorePatternsBuildOutputs, ignorePatternsCaches, ignorePatternsCommon, ignorePatternsEslintDefaults, ignorePatternsGenerated, installStaticPlugins, listMissing, listUnresolved, loadAlintConfig, loadPluginLockFile, loadSetupConfig, loadStaticConfig, mergeSetupConfigs, parsePluginLockFile, parsePluginSpecifier, parseSetupConfigToml, parseStaticConfig, stringifySetupConfigToml, toAlintConfig, writePluginLockFile, writeSetupConfig };
+export { builtInAgentNames, createDeclarativePlugin, createEmptyPluginLockFile, createReportScope, declarativeFindingResponseSchema, declarativeFindingSchema, declarativeRuleFilePattern, emptySetupConfig, getGlobalSetupConfigPath, getProjectPluginLockPath, getProjectPluginStorePath, getProjectSetupConfigPath, getStatsDir, hasDeclarativeRuleFiles, ignorePatternsAIAgents, ignorePatternsBuildOutputs, ignorePatternsCaches, ignorePatternsCommon, ignorePatternsEslintDefaults, ignorePatternsGenerated, installStaticPlugins, isBuiltInAgentName, listMissing, listUnresolved, loadAlintConfig, loadDeclarativeRules, loadPluginLockFile, loadSetupConfig, loadStaticConfig, mergeSetupConfigs, parsePluginLockFile, parsePluginSpecifier, parseSetupConfigToml, parseStaticConfig, stringifySetupConfigToml, toAlintConfig, writePluginLockFile, writeSetupConfig };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alint-js/config",
   "type": "module",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -15,9 +15,11 @@
   "dependencies": {
     "@moeru/std": "^0.1.0-beta.18",
     "@package-json/types": "^0.0.13",
+    "apeira": "^0.0.7",
     "c12": "^3.3.4",
     "es-toolkit": "^1.49.0",
     "jiti": "^2.7.0",
+    "minimatch": "^10.2.5",
     "ofetch": "^1.5.1",
     "pathe": "^2.0.3",
     "resolve.exports": "2.0.3",
@@ -25,15 +27,12 @@
     "tar-stream": "^3.2.0",
     "valibot": "^1.4.1",
     "xdg-basedir": "^5.1.0",
-    "@alint-js/core": "0.0.21"
+    "@alint-js/core": "0.0.23",
+    "@alint-js/tools-fs": "0.0.23"
   },
   "devDependencies": {
-    "@types/node": "^26.0.1",
     "@types/tar-stream": "^3.1.4",
-    "h3": "2.0.1-rc.25",
-    "tsdown": "^0.22.3",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "h3": "2.0.1-rc.25"
   },
   "scripts": {
     "build": "tsdown",