@alint-js/core 0.0.25 → 0.0.28

package/dist/agent.d.mts

@@ -1,7 +1,16 @@
-import { J as AgentResult, K as AgentAdapter, X as AgentUsage, Y as AgentTool, q as AgentRequest, v as RuleContext } from "./types-CIqhJ96f.mjs";
-
+import { J as AgentResult, K as AgentAdapter, X as AgentUsage, Y as AgentTool, q as AgentRequest, v as RuleContext } from "./types-BM_nUu_Z.mjs";
+//#region src/agent/retry.d.ts
+/**
+ * Declares that the complete adapter invocation can be safely replayed.
+ * Adapters must not throw this after a tool or another externally visible side effect starts.
+ */
+declare class RetryableAgentError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+declare function isRetryableAgentError(error: unknown): error is RetryableAgentError;
+//#endregion
 //#region src/agent/index.d.ts
 declare function defineTool(tool: AgentTool): AgentTool;
-declare function requireAgent(context: Pick<RuleContext, 'agent' | 'id'>): AgentAdapter;
+declare function requireAgent(context: Pick<RuleContext, 'agent' | 'id' | 'signal'>): AgentAdapter;
 //#endregion
-export { type AgentAdapter, type AgentRequest, type AgentResult, type AgentTool, type AgentUsage, defineTool, requireAgent };
+export { type AgentAdapter, type AgentRequest, type AgentResult, type AgentTool, type AgentUsage, RetryableAgentError, defineTool, isRetryableAgentError, requireAgent };

package/dist/agent.mjs

@@ -1,10 +1,15 @@
+import { n as isRetryableAgentError, t as RetryableAgentError } from "./retry-C4sGjSE5.mjs";
 //#region src/agent/index.ts
 function defineTool(tool) {
 	return tool;
 }
 function requireAgent(context) {
 	if (!context.agent) throw new TypeError(`Rule "${context.id}" requires an agent, but none is configured. Set "agent" in alint config (e.g. agent: createApeiraAdapter()).`);
-	return context.agent;
+	const agent = context.agent;
+	return async (request) => agent({
+		...request,
+		signal: request.signal ?? context.signal
+	});
 }
 //#endregion
-export { defineTool, requireAgent };
+export { RetryableAgentError, defineTool, isRetryableAgentError, requireAgent };

package/dist/index.d.mts

@@ -1,5 +1,4 @@
-import { $ as ResolvedModel, A as LanguageContext, B as SourceRuntime, C as RuleSeverity, D as ClassTarget, E as Target, F as ProcessorPostprocessContext, G as SourceText, H as SourceTargetKind, I as SourceFile, L as SourceLocation, M as ProcessedSource, N as ProcessedSourceOrigin, O as FileTarget, P as ProcessorContext, Q as ResolveModelOptions, R as SourcePosition, S as RuleRegistry, T as RuleWithHandler, U as SourceTargetOfKind, V as SourceTarget, W as SourceTargetOrigin, Z as ModelRequirement, _ as RuleConfigEntry, a as AlintLinterOptions, at as RunnerStatsConfig, b as RuleHandlers, c as DiagnosticLocation, d as IgnoreConfig, et as ResolvedProvider, f as LanguageDefinition, g as RuleCacheConfig, h as ProjectTarget, i as AlintConfigItem, it as RunnerConfig, j as LineRange, k as FunctionTarget, l as DirectoryTarget, m as ProcessorDefinition, n as AlintConfigExtends, nt as ProviderDefinition, o as Awaitable, ot as SetupConfig, p as PluginDefinition, r as AlintConfigInput, rt as ProviderType, s as DiagnosticDescriptor, st as SetupModelDefinition, t as AlintConfig, tt as ModelSize, u as EnabledRule, v as RuleContext, w as RuleSpecializedHandlers, x as RuleInferenceUsageRecord, y as RuleDefinition, z as SourceRange } from "./types-CIqhJ96f.mjs";
-
+import { $ as ResolvedModel, A as LanguageContext, B as SourceRuntime, C as RuleSeverity, D as ClassTarget, E as Target, F as ProcessorPostprocessContext, G as SourceText, H as SourceTargetKind, I as SourceFile, L as SourceLocation, M as ProcessedSource, N as ProcessedSourceOrigin, O as FileTarget, P as ProcessorContext, Q as ResolveModelOptions, R as SourcePosition, S as RuleRegistry, T as RuleWithHandler, U as SourceTargetOfKind, V as SourceTarget, W as SourceTargetOrigin, Z as ModelRequirement, _ as RuleConfigEntry, a as AlintLinterOptions, at as RunnerStatsConfig, b as RuleHandlers, c as DiagnosticLocation, d as IgnoreConfig, et as ResolvedProvider, f as LanguageDefinition, g as RuleCacheConfig, h as ProjectTarget, i as AlintConfigItem, it as RunnerConfig, j as LineRange, k as FunctionTarget, l as DirectoryTarget, m as ProcessorDefinition, n as AlintConfigExtends, nt as ProviderDefinition, o as Awaitable, ot as SetupConfig, p as PluginDefinition, r as AlintConfigInput, rt as ProviderType, s as DiagnosticDescriptor, st as SetupModelDefinition, t as AlintConfig, tt as ModelSize, u as EnabledRule, v as RuleContext, w as RuleSpecializedHandlers, x as RuleInferenceUsageRecord, y as RuleDefinition, z as SourceRange } from "./types-BM_nUu_Z.mjs";
 //#region src/config/config-array.d.ts
 interface EffectiveAlintConfig {
   agent?: AlintConfigItem['agent'];
@@ -126,7 +125,11 @@ interface RuleEndPayload {
   endedAt?: number;
   path: ProgressPath;
   startedAt?: number;
-  state: 'completed' | 'errored';
+  /**
+   * `skipped` only occurs under {@link RunOptions.cacheOnly}: the rule missed the cache and was
+   * never executed, so it produced no diagnostics. `cache` is still `'miss'` in that case.
+   */
+  state: 'completed' | 'errored' | 'skipped';
 }
 interface RuleStartPayload {
   path: ProgressPath;
@@ -139,6 +142,8 @@ interface RunEndPayload {
   endedAt?: number;
   errored: number;
   planned: number;
+  /** Rules left unexecuted because they missed the cache under {@link RunOptions.cacheOnly}. Always 0 otherwise. */
+  skipped: number;
   startedAt?: number;
   usage: RunUsage;
 }
@@ -147,9 +152,22 @@ interface RunExecution {
   completed: number;
   errored: number;
   planned: number;
+  /** Rules left unexecuted because they missed the cache under {@link RunOptions.cacheOnly}. Always 0 otherwise. */
+  skipped: number;
 }
 type RunnerOptions = RunnerConfig;
 interface RunOptions {
+  /**
+   * Return only diagnostics that are already cached, without calling any model.
+   *
+   * Rules that miss the cache are skipped instead of executed, and the run leaves the cache
+   * file untouched. Read {@link RunExecution.skipped} to see how many rules a full run would
+   * still have to execute.
+   *
+   * Intended for callers that want to show known results for free, such as an editor
+   * displaying diagnostics on file open.
+   */
+  cacheOnly?: boolean;
   config?: AlintConfig;
   cwd?: string;
   directories?: string[];
@@ -159,6 +177,15 @@ interface RunOptions {
   progress?: ProgressReporter;
   runner?: RunnerOptions;
   setupConfig?: SetupConfig;
+  /**
+   * Cancels the run. Aborting stops the engine from starting further rules and cancels the
+   * in-flight model call, so a cancelled run stops spending tokens.
+   *
+   * `runAlint` rejects with {@link AlintAbortError}, which carries the diagnostics gathered
+   * before the abort. Rules that already finished keep their cache entries: cancelling never
+   * throws away work you already paid for.
+   */
+  signal?: AbortSignal;
 }
 interface RunResult {
   diagnostics: Diagnostic[];

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { r as withAgentRetry } from "./retry-C4sGjSE5.mjs";
 import { minimatch } from "minimatch";
 import { isAbsolute, relative, resolve } from "pathe";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
@@ -967,7 +968,7 @@ function createDirectoryExecutionPlans(directories, fileOffset) {
 }
 //#endregion
 //#region package.json
-var version = "0.0.25";
+var version = "0.0.28";
 //#endregion
 //#region src/core/targets/execution.ts
 var AlintRuleExecutionError = class extends Error {
@@ -1048,7 +1049,8 @@ function emitErroredRuleEnd(progress, clock, path, startedAt, cache) {
 	} catch {}
 }
 async function executeRule(execution, path, target, options) {
-	const { cache, clock, counters, diagnostics, progress, usage } = options;
+	const { cache, clock, counters, diagnostics, progress, signal, usage } = options;
+	signal?.throwIfAborted();
 	const startedAt = clock();
 	const cacheKey = createExecutionCacheKey(execution.runtime, target, path, cache);
 	const cachedEntry = cacheKey ? cache.store.get(cacheKey) : void 0;
@@ -1075,6 +1077,17 @@ async function executeRule(execution, path, target, options) {
 		});
 		return;
 	}
+	if (options.cacheOnly) {
+		counters.skip();
+		progress?.onRuleEnd?.({
+			cache: "miss",
+			endedAt: clock(),
+			path,
+			startedAt,
+			state: "skipped"
+		});
+		return;
+	}
 	let handlerError;
 	let handlerFailed = false;
 	const cacheDiagnostics = cacheKey ? [] : void 0;
@@ -1091,6 +1104,7 @@ async function executeRule(execution, path, target, options) {
 		handlerFailed = true;
 	}
 	if (handlerFailed) {
+		signal?.throwIfAborted();
 		counters.error();
 		emitErroredRuleEnd(progress, clock, path, startedAt, "miss");
 		throw new AlintRuleExecutionError(handlerError, path);
@@ -1397,6 +1411,18 @@ var AlintRunError = class extends Error {
 		this.result = result;
 	}
 };
+/**
+* Thrown when {@link RunOptions.signal} aborts a run.
+*
+* Extends {@link AlintRunError} so existing handlers still receive the partial `result`, while
+* callers that treat cancellation differently from failure can test for this type.
+*/
+var AlintAbortError = class extends AlintRunError {
+	constructor(result, options = {}) {
+		super("alint run was aborted", result, { cause: options.cause });
+		this.name = "AlintAbortError";
+	}
+};
 async function runAlint(options = {}) {
 	const cwd$1 = options.cwd ?? cwd();
 	const config = options.config ?? [];
@@ -1511,6 +1537,7 @@ async function runAlint(options = {}) {
 	let runStartedAt;
 	let runError;
 	try {
+		options.signal?.throwIfAborted();
 		filePlans = createSourceExecutionPlans(files, cwd$1);
 		directoryPlans = createDirectoryExecutionPlans(directories, filePlans.length);
 		projectPlan = resolvedProjectConfig.ignored ? void 0 : createProjectExecutionPlan({
@@ -1535,38 +1562,44 @@ async function runAlint(options = {}) {
 		});
 		await runConcurrently(filePlans.filter((filePlan) => filePlan.targets.length > 0), resolveFileConcurrency(options.runner?.fileConcurrency), (filePlan) => executeTargetPlans({
 			cache: cacheContext,
+			cacheOnly: options.cacheOnly,
 			clock,
 			counters,
 			diagnostics,
 			filesTotal: inputsTotal,
 			plans: [filePlan],
 			progress: options.progress,
+			signal: options.signal,
 			usage
 		}));
 		await runConcurrently(activeDirectoryPlans, resolveFileConcurrency(options.runner?.fileConcurrency), (directoryPlan) => executeTargetPlans({
 			cache: cacheContext,
+			cacheOnly: options.cacheOnly,
 			clock,
 			counters,
 			diagnostics,
 			filesTotal: inputsTotal,
 			plans: [directoryPlan],
 			progress: options.progress,
+			signal: options.signal,
 			usage
 		}));
 		if (projectPlan) await executeTargetPlans({
 			cache: cacheContext,
+			cacheOnly: options.cacheOnly,
 			clock,
 			counters,
 			diagnostics,
 			filesTotal: inputsTotal,
 			plans: [projectPlan],
 			progress: options.progress,
+			signal: options.signal,
 			usage
 		});
 	} catch (error) {
 		runError = error;
 	} finally {
-		await reconcileCache(filePlans, cacheContext);
+		if (!options.cacheOnly) await reconcileCache(filePlans, cacheContext);
 		try {
 			options.progress?.onRunEnd?.({
 				...counters.snapshot(planned),
@@ -1584,7 +1617,10 @@ async function runAlint(options = {}) {
 		execution: counters.snapshot(planned),
 		usage: usage.toJSON()
 	};
-	if (runError) throw createAlintRunError(runError, result);
+	if (runError) {
+		if (options.signal?.aborted) throw new AlintAbortError(result, { cause: runError });
+		throw createAlintRunError(runError, result);
+	}
 	return result;
 }
 function addTokenCount(base, value) {
@@ -1612,6 +1648,7 @@ function createRuleEndCounters() {
 	let cached = 0;
 	let completed = 0;
 	let errored = 0;
+	let skipped = 0;
 	return {
 		cache() {
 			cached += 1;
@@ -1622,21 +1659,26 @@ function createRuleEndCounters() {
 		error() {
 			errored += 1;
 		},
+		skip() {
+			skipped += 1;
+		},
 		snapshot(planned) {
 			return {
 				cached,
 				completed,
 				errored,
-				planned
+				planned,
+				skipped
 			};
 		}
 	};
 }
 function createRuleRuntimes(options) {
+	const agent = options.effectiveAgent ? withAgentRetry(options.effectiveAgent, options.options.runner?.agentRetries) : void 0;
 	return options.registry.enabledRules.map((enabledRule) => {
 		const executionState = new AsyncLocalStorage();
 		const context = {
-			agent: options.effectiveAgent,
+			agent,
 			cwd: options.cwd,
 			id: enabledRule.id,
 			localId: enabledRule.localId,
@@ -1691,6 +1733,7 @@ function createRuleRuntimes(options) {
 				});
 			},
 			settings: options.effectiveSettings,
+			signal: options.options.signal,
 			src: options.src
 		};
 		return {

package/dist/retry-C4sGjSE5.mjs

@@ -0,0 +1,50 @@
+import { withRetry } from "@moeru/std/with-retry";
+//#region src/agent/retry.ts
+/**
+* Declares that the complete adapter invocation can be safely replayed.
+* Adapters must not throw this after a tool or another externally visible side effect starts.
+*/
+var RetryableAgentError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "RetryableAgentError";
+	}
+};
+function isRetryableAgentError(error) {
+	return error instanceof RetryableAgentError;
+}
+function withAgentRetry(adapter, retries = 2) {
+	const invoke = withRetry(async (request) => {
+		try {
+			request.signal?.throwIfAborted();
+			const result = await adapter(request);
+			request.signal?.throwIfAborted();
+			return {
+				ok: true,
+				result
+			};
+		} catch (error) {
+			if (request.signal?.aborted) return {
+				error: request.signal.reason,
+				ok: false
+			};
+			if (isRetryableAgentError(error)) throw error;
+			return {
+				error,
+				ok: false
+			};
+		}
+	}, {
+		retry: retries,
+		retryDelay: 500,
+		retryDelayFactor: 2,
+		retryDelayMax: 3e4
+	});
+	return async (request) => {
+		const attempt = await invoke(request);
+		if (!attempt.ok) throw attempt.error;
+		return attempt.result;
+	};
+}
+//#endregion
+export { isRetryableAgentError as n, withAgentRetry as r, RetryableAgentError as t };

package/dist/structured-output.d.mts

@@ -1,8 +1,7 @@
-import { $ as ResolvedModel, v as RuleContext } from "./types-CIqhJ96f.mjs";
+import { $ as ResolvedModel, v as RuleContext } from "./types-BM_nUu_Z.mjs";
 import { GenericSchema, InferOutput } from "valibot";
 import { JsonSchema } from "@valibot/to-json-schema";
 import { Message } from "@xsai/shared-chat";
-
 //#region src/structuredOutput/index.d.ts
 interface GenerateStructuredOptions<Schema extends GenericSchema> {
   /**
@@ -21,6 +20,8 @@ interface GenerateStructuredOptions<Schema extends GenericSchema> {
   /** Milliseconds to wait before the given (1-based) attempt is retried. */
   retryDelay?: (attempt: number) => number;
   schema: Schema;
+  /** Cancels the model call and any pending retry backoff. Pass `ctx.signal` from a rule. */
+  signal?: AbortSignal;
   temperature?: number;
   /** Shown to the model as the tool description. Defaults to the schema's valibot description. */
   toolDescription?: string;

package/dist/structured-output.mjs

@@ -1,6 +1,6 @@
 import { errorMessageFrom } from "@moeru/std/error";
 import { getDescription, parse } from "valibot";
-import { sleep } from "@moeru/std/sleep";
+import { setTimeout } from "node:timers/promises";
 import { toJsonSchema } from "@valibot/to-json-schema";
 import { generateText } from "@xsai/generate-text";
 import { rawTool } from "@xsai/tool";
@@ -41,9 +41,11 @@ async function generateStructured(options) {
 	});
 	let previousError;
 	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		options.signal?.throwIfAborted();
 		let response;
 		try {
 			response = await generateText({
+				abortSignal: options.signal,
 				baseURL: options.model.provider.endpoint,
 				headers: options.model.provider.headers,
 				messages: options.createMessages(previousError ? retryFeedbackFrom(toolName, previousError) : void 0),
@@ -57,11 +59,12 @@ async function generateStructured(options) {
 				tools: [tool]
 			});
 		} catch (error) {
+			options.signal?.throwIfAborted();
 			const callError = `Tool call failed before validation: ${errorMessageFrom(error) ?? String(error)}`;
 			previousError = isRetriableHttpError(error) ? void 0 : callError;
 			options.logger?.debug(`${options.operation} attempt ${attempt} failed while calling the model: ${callError}`);
 			if (!isRetriableCallError(error) || attempt === maxAttempts) throw error;
-			await sleep(retryDelay(attempt));
+			await setTimeout(retryDelay(attempt), void 0, { signal: options.signal });
 			continue;
 		}
 		recordAttemptUsage(options, response);
@@ -70,7 +73,7 @@ async function generateStructured(options) {
 		previousError = result.error;
 		options.logger?.debug(`${options.operation} attempt ${attempt} returned an invalid structured result: ${previousError}`);
 		if (!result.retriable || attempt === maxAttempts) throw new InvalidStructuredOutputError(`Invalid structured model response: ${previousError}`);
-		await sleep(retryDelay(attempt));
+		await setTimeout(retryDelay(attempt), void 0, { signal: options.signal });
 	}
 	throw new InvalidStructuredOutputError("Model did not return a valid structured result");
 }

package/dist/{types-CIqhJ96f.d.mts → types-BM_nUu_Z.d.mts}

@@ -13,6 +13,8 @@ interface RunnerCacheConfig {
   location?: string;
 }
 interface RunnerConfig {
+  /** Retries after the initial attempt for replay-safe agent failures. @default 2 */
+  agentRetries?: number;
   cache?: boolean | RunnerCacheConfig;
   fileConcurrency?: number;
   ruleConcurrency?: number;
@@ -275,6 +277,13 @@ interface RuleContext {
   outputLanguage?: string;
   report: (diagnostic: DiagnosticDescriptor) => void;
   settings: Record<string, unknown>;
+  /**
+   * Cancels the run. Forward it to anything long-running a rule starts, so cancelling stops
+   * the work instead of letting it finish and bill.
+   *
+   * `ctx.agent` already injects it, and `generateStructured` accepts it as `signal`.
+   */
+  signal?: AbortSignal;
   src: SourceRuntime;
 }
 interface RuleDefinition {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alint-js/core",
   "type": "module",
-  "version": "0.0.25",
+  "version": "0.0.28",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -28,13 +28,13 @@
     "@xsai/tool": "^0.5.0-beta.7",
     "es-toolkit": "^1.49.0",
     "minimatch": "^10.2.5",
-    "oxc-parser": "^0.137.0",
+    "oxc-parser": "^0.140.0",
     "pathe": "^2.0.3",
-    "valibot": "^1.4.1"
+    "valibot": "^1.4.2"
   },
   "devDependencies": {
     "effect": "^3.22.0",
-    "sury": "^10.0.4"
+    "sury": "^11.0.0-alpha.10"
   },
   "scripts": {
     "build": "tsdown",