@alint-js/core 0.0.19 → 0.0.20

package/README.md

@@ -4,39 +4,21 @@ The public SDK and run engine for `alint`.
 
 ## What it does
 
-This package provides the core APIs used by configs, plugins, rules, language processors, and agent adapters:
+This package provides the core SDK and run engine APIs used by plugins, rules, language processors, embedding tools, and agent adapters:
 
-- `defineConfig`, `definePlugin`, and `defineRule`
+- `definePlugin` and `defineRule`
+- `runAlint`
 - rule registry and flat config normalization
 - source runtime helpers
 - built-in JavaScript source extraction
 - model resolution by size and capability
 - diagnostics and progress payload types
-- `runAlint`
 - framework-neutral agent contracts under `@alint-js/core/agent`
+- tool-call structured output under `@alint-js/core/structured-output`
+- config DSL and types for advanced SDK consumers
 
 ## How to use
 
-Define an `alint` config:
-
-```ts
-import examplePlugin from '@alint-js/plugin-example'
-
-import { defineConfig } from '@alint-js/core'
-
-export default defineConfig([
-  {
-    files: ['**/*.{js,ts,jsx,tsx}'],
-    plugins: {
-      example: examplePlugin,
-    },
-    rules: {
-      'example/no-redundant-jsdoc': 'warn',
-    },
-  },
-])
-```
-
 Write a rule:
 
 ```ts
@@ -65,6 +47,39 @@ import { requireAgent } from '@alint-js/core/agent'
 const agent = requireAgent(ctx)
 ```
 
+Ask a model for one validated, typed result with `@alint-js/core/structured-output`. It forces
+the model to call a single reporting tool whose arguments match a valibot schema, validates
+them, and retries with the validation error fed back to the model:
+
+```ts
+import { generateStructured } from '@alint-js/core/structured-output'
+import { array, description, object, pipe } from 'valibot'
+
+const responseSchema = pipe(
+  object({ findings: array(findingSchema) }),
+  description('Report findings for this file.'),
+)
+
+const { findings } = await generateStructured({
+  createMessages: retryFeedback => [
+    { content: prompt, role: 'system' },
+    ...(retryFeedback ? [{ content: retryFeedback, role: 'user' as const }] : []),
+    { content: numberedSource, role: 'user' },
+  ],
+  logger: ctx.logger,
+  metering: ctx.metering,
+  model: await ctx.model(),
+  operation: 'my-rule-judge',
+  schema: responseSchema,
+})
+```
+
+The reporting tool is named `reportFindings` by default (`toolName` overrides it) and its
+description defaults to the schema's valibot `description(...)`. `toolParametersFromSchema`,
+`formatSourceWithLineNumbers`, and `formatOutputLanguageInstruction` are exported for callers
+that build their own tools or prompts. Use `ctx.agent` instead when the model needs to
+explore with tools before answering, because a forced tool call is a single shot, not a loop.
+
 ## When to use
 
 - You are writing an `alint` plugin or rule package.
@@ -74,5 +89,5 @@ const agent = requireAgent(ctx)
 
 ## When not to use
 
-- Use `@alint-js/cli` for command-line usage.
-- Use `@alint-js/config` for setup TOML and config-file helpers only.
+- Use `@alint-js/cli` for command-line usage and ordinary `alint.config.*` files.
+- Use `@alint-js/config` for setup TOML, config loading, and config-file tooling only.

package/dist/index.mjs

@@ -653,7 +653,7 @@ function createBuiltInLanguageRegistry() {
 }
 //#endregion
 //#region package.json
-var version = "0.0.19";
+var version = "0.0.20";
 //#endregion
 //#region src/dsl/registry.ts
 function buildRuleRegistry(config) {

package/dist/structured-output.d.mts

@@ -0,0 +1,48 @@
+import { W as ResolvedModel, g as RuleContext } from "./types-DQfoxG8J.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> {
+  /**
+   * Builds the chat messages for each attempt. On retries, `retryFeedback`
+   * carries a ready-to-send validation-failure message; insert it wherever it
+   * fits the conversation, usually right before the final user message.
+   */
+  createMessages: (retryFeedback?: string) => Message[];
+  logger?: RuleContext['logger'];
+  /** Maximum number of attempts when validation fails. Defaults to 3. */
+  maxAttempts?: number;
+  metering?: RuleContext['metering'];
+  model: ResolvedModel;
+  /** Label recorded in metering metadata and debug logs, e.g. `go-responsibility-boundary-judge`. */
+  operation: string;
+  /** Milliseconds to wait before the given (1-based) attempt is retried. */
+  retryDelay?: (attempt: number) => number;
+  schema: Schema;
+  temperature?: number;
+  /** Shown to the model as the tool description. Defaults to the schema's valibot description. */
+  toolDescription?: string;
+  toolName?: string;
+}
+declare class InvalidStructuredOutputError extends Error {
+  constructor(message: string);
+}
+/** Standard instruction line for localized judge findings; undefined when no language is configured. */
+declare function formatOutputLanguageInstruction(outputLanguage: string | undefined): string | undefined;
+/** Prefixes each line with its 1-based number so schemas can ask for "left-column line numbers". */
+declare function formatSourceWithLineNumbers(source: string): string;
+/**
+ * Forces the model to call a single reporting tool and returns the validated
+ * tool arguments, so a tool call doubles as structured output. Unlike
+ * `response_format`-based structured output (xsai's `generateObject`), a
+ * forced tool call works on any provider with function calling, and invalid
+ * payloads are retried with validation feedback instead of failing outright.
+ */
+declare function generateStructured<Schema extends GenericSchema>(options: GenerateStructuredOptions<Schema>): Promise<InferOutput<Schema>>;
+declare function normalizeToolJsonSchema(schema: JsonSchema): JsonSchema;
+/** Converts a valibot schema into provider-compliant strict tool parameters. */
+declare function toolParametersFromSchema(schema: GenericSchema): JsonSchema;
+//#endregion
+export { GenerateStructuredOptions, InvalidStructuredOutputError, formatOutputLanguageInstruction, formatSourceWithLineNumbers, generateStructured, normalizeToolJsonSchema, toolParametersFromSchema };

package/dist/structured-output.mjs

@@ -0,0 +1,186 @@
+import { errorMessageFrom } from "@moeru/std/error";
+import { getDescription, parse } from "valibot";
+import { sleep } from "@moeru/std/sleep";
+import { toJsonSchema } from "@valibot/to-json-schema";
+import { generateText } from "@xsai/generate-text";
+import { rawTool } from "@xsai/tool";
+//#region src/structuredOutput/index.ts
+const defaultMaxAttempts = 3;
+const defaultToolName = "reportFindings";
+var InvalidStructuredOutputError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "InvalidStructuredOutputError";
+	}
+};
+/** Standard instruction line for localized judge findings; undefined when no language is configured. */
+function formatOutputLanguageInstruction(outputLanguage) {
+	return outputLanguage ? `Write all human-readable finding messages and suggestions in this language: ${outputLanguage}.` : void 0;
+}
+/** Prefixes each line with its 1-based number so schemas can ask for "left-column line numbers". */
+function formatSourceWithLineNumbers(source) {
+	return source.split("\n").map((line, index) => `${index + 1} | ${line}`).join("\n");
+}
+/**
+* Forces the model to call a single reporting tool and returns the validated
+* tool arguments, so a tool call doubles as structured output. Unlike
+* `response_format`-based structured output (xsai's `generateObject`), a
+* forced tool call works on any provider with function calling, and invalid
+* payloads are retried with validation feedback instead of failing outright.
+*/
+async function generateStructured(options) {
+	const maxAttempts = options.maxAttempts ?? defaultMaxAttempts;
+	const retryDelay = options.retryDelay ?? exponentialRetryDelay;
+	const toolName = options.toolName ?? defaultToolName;
+	const tool = rawTool({
+		description: options.toolDescription ?? getDescription(options.schema),
+		execute: (input) => asRecord(input) ?? {},
+		name: toolName,
+		parameters: toolParametersFromSchema(options.schema),
+		strict: true
+	});
+	let previousError;
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		let response;
+		try {
+			response = await generateText({
+				baseURL: options.model.provider.endpoint,
+				headers: options.model.provider.headers,
+				messages: options.createMessages(previousError ? retryFeedbackFrom(toolName, previousError) : void 0),
+				model: options.model.id,
+				parallelToolCalls: false,
+				temperature: options.temperature ?? 0,
+				toolChoice: {
+					function: { name: toolName },
+					type: "function"
+				},
+				tools: [tool]
+			});
+		} catch (error) {
+			previousError = `Tool call failed before validation: ${errorMessageFrom(error) ?? String(error)}`;
+			options.logger?.debug(`${options.operation} attempt ${attempt} failed while calling the model: ${previousError}`);
+			if (!isRetriableCallError(error) || attempt === maxAttempts) throw error;
+			await sleep(retryDelay(attempt));
+			continue;
+		}
+		recordAttemptUsage(options, response);
+		const result = parseStructuredResponse(options.schema, toolName, response);
+		if (result.ok) return result.value;
+		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));
+	}
+	throw new InvalidStructuredOutputError("Model did not return a valid structured result");
+}
+function normalizeToolJsonSchema(schema) {
+	const normalized = normalizeJsonSchemaDefinition(schema);
+	return typeof normalized === "boolean" ? {} : normalized;
+}
+/** Converts a valibot schema into provider-compliant strict tool parameters. */
+function toolParametersFromSchema(schema) {
+	return normalizeToolJsonSchema(toJsonSchema(schema));
+}
+function asRecord(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function exponentialRetryDelay(attempt) {
+	return 500 * 2 ** (attempt - 1);
+}
+function isRetriableCallError(error) {
+	if (!(error instanceof Error)) return true;
+	return error.name === "InvalidToolCallError" || error.name === "InvalidToolInputError" || error.name === "ToolExecutionError";
+}
+function normalizeJsonSchemaDefinition(schema) {
+	if (typeof schema === "boolean") return schema;
+	const normalized = { ...schema };
+	delete normalized.$schema;
+	if (normalized.type === "object") normalized.additionalProperties = false;
+	if (normalized.properties) {
+		normalized.properties = Object.fromEntries(Object.entries(normalized.properties).map(([key, propertySchema]) => [key, normalizeJsonSchemaDefinition(propertySchema)]));
+		normalized.required = Object.keys(normalized.properties);
+	}
+	if (normalized.items) normalized.items = Array.isArray(normalized.items) ? normalized.items.map((item) => normalizeJsonSchemaDefinition(item)) : normalizeJsonSchemaDefinition(normalized.items);
+	if (normalized.$defs) normalized.$defs = normalizeJsonSchemaMap(normalized.$defs);
+	if (normalized.definitions) normalized.definitions = normalizeJsonSchemaMap(normalized.definitions);
+	for (const key of [
+		"allOf",
+		"anyOf",
+		"oneOf"
+	]) if (normalized[key]) normalized[key] = normalized[key].map((item) => normalizeJsonSchemaDefinition(item));
+	if (normalized.not) normalized.not = normalizeJsonSchemaDefinition(normalized.not);
+	return normalized;
+}
+function normalizeJsonSchemaMap(map) {
+	return Object.fromEntries(Object.entries(map).map(([key, schema]) => [key, normalizeJsonSchemaDefinition(schema)]));
+}
+function normalizeUsage(usage) {
+	const record = asRecord(usage);
+	if (!record) return;
+	const normalized = {
+		inputTokens: numberFromRecord(record, "inputTokens") ?? numberFromRecord(record, "input_tokens") ?? numberFromRecord(record, "prompt_tokens"),
+		outputTokens: numberFromRecord(record, "outputTokens") ?? numberFromRecord(record, "output_tokens") ?? numberFromRecord(record, "completion_tokens"),
+		totalTokens: numberFromRecord(record, "totalTokens") ?? numberFromRecord(record, "total_tokens")
+	};
+	return Object.values(normalized).some((value) => value !== void 0) ? normalized : void 0;
+}
+function numberFromRecord(record, key) {
+	const value = record[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function parseStructuredResponse(schema, toolName, response) {
+	if (response.finishReason === "content_filter") return {
+		error: `${toolName} was not returned because the model finished with content_filter`,
+		ok: false,
+		retriable: false
+	};
+	if (response.finishReason === "length") return {
+		error: `${toolName} was not returned completely because the model finished with length`,
+		ok: false,
+		retriable: true
+	};
+	const toolResults = response.toolResults.filter((result) => result.toolName === toolName);
+	if (toolResults.length === 0) return {
+		error: `Missing ${toolName} tool result; finishReason=${response.finishReason}`,
+		ok: false,
+		retriable: true
+	};
+	if (toolResults.length > 1) return {
+		error: `Expected one ${toolName} tool result, received ${toolResults.length}`,
+		ok: false,
+		retriable: true
+	};
+	try {
+		return {
+			ok: true,
+			value: parse(schema, toolResults[0].result)
+		};
+	} catch (error) {
+		return {
+			error: errorMessageFrom(error) ?? String(error),
+			ok: false,
+			retriable: true
+		};
+	}
+}
+function recordAttemptUsage(options, response) {
+	const usage = normalizeUsage(response.usage);
+	if (!options.metering || !usage) return;
+	options.metering.recordUsage({
+		inputTokens: usage.inputTokens,
+		metadata: { operation: options.operation },
+		modelId: options.model.id,
+		outputTokens: usage.outputTokens,
+		providerId: options.model.provider.id,
+		totalTokens: usage.totalTokens
+	});
+}
+function retryFeedbackFrom(toolName, error) {
+	return [
+		"Your previous tool call could not be validated.",
+		`Validation error: ${error}`,
+		`Call ${toolName} again with arguments that exactly match the tool schema.`
+	].join("\n");
+}
+//#endregion
+export { InvalidStructuredOutputError, formatOutputLanguageInstruction, formatSourceWithLineNumbers, generateStructured, normalizeToolJsonSchema, toolParametersFromSchema };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alint-js/core",
   "type": "module",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -11,6 +11,10 @@
       "types": "./dist/agent.d.mts",
       "default": "./dist/agent.mjs"
     },
+    "./structured-output": {
+      "types": "./dist/structured-output.d.mts",
+      "default": "./dist/structured-output.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -18,6 +22,10 @@
   ],
   "dependencies": {
     "@moeru/std": "^0.1.0-beta.18",
+    "@valibot/to-json-schema": "^1.7.1",
+    "@xsai/generate-text": "^0.5.0-beta.6",
+    "@xsai/shared-chat": "^0.5.0-beta.6",
+    "@xsai/tool": "^0.5.0-beta.6",
     "es-toolkit": "^1.49.0",
     "minimatch": "^10.2.5",
     "oxc-parser": "^0.137.0",