correctly 0.0.0 → 0.1.0

package/src/core/engine.ts

@@ -1,247 +1,147 @@
-import {
-	Ajv,
-	type ErrorObject,
-	type ValidateFunction,
-	type SchemaObject,
-} from "ajv"
-import { Ajv2020 } from "ajv/dist/2020.js"
-import addFormats from "ajv-formats"
-import {
-	associationFor,
-	isIncluded,
-	modeFor,
-	schemaUri,
-	type Project,
-} from "./config.ts"
-import {
-	diagnostic,
-	parseDocument,
-	pointer,
-	type ParsedDocument,
-} from "./parse.ts"
-import { DIALECTS, SchemaStore, type StoreOptions } from "./schemas.ts"
-import { validationContexts } from "./diagnostics.ts"
-import {
-	CorrectlyError,
-	failure,
-	type Diagnostic,
-	type FileResult,
-} from "./types.ts"
+import { associationFor, isIncluded, readText, type Project } from "./config.ts"
+import { defaultParser } from "./parsers.ts"
+import { CorrectlyError, failure, type FileResult } from "./types.ts"
+import type { StoreOptions } from "./schemas.ts"
+import type {
+	PreparedValidator,
+	ValidationContext,
+	Validator,
+} from "./adapters.ts"
 
-const ANNOTATIONS = [
-	"markdownDescription",
-	"enumDescriptions",
-	"markdownEnumDescriptions",
-	"defaultSnippets",
-	"errorMessage",
-	"patternErrorMessage",
-	"deprecationMessage",
-	"suggestSortText",
-	"doNotSuggest",
-	"allowComments",
-	"allowTrailingCommas",
-	"deprecated",
-	"$vocabulary",
-]
-
-function registerRootAnchors(ajv: Ajv, schema: unknown, uri: string) {
-	if (typeof schema !== "object" || schema === null) return
-	const object = schema as SchemaObject
-	for (const anchor of [object.$anchor, object.$dynamicAnchor]) {
-		if (typeof anchor === "string")
-			ajv.refs[new URL(`#${anchor}`, object.$id ?? uri).href] =
-				object.$id ?? uri
-	}
+export type EngineOptions = StoreOptions & {
+	onDependency?: (uri: string) => void
 }
-
-function validationMessage(error: ErrorObject): string {
-	if (error.keyword === "anyOf")
-		return "must match at least one alternative; none matched"
-	if (
-		error.keyword === "if" &&
-		["then", "else"].includes(error.params.failingKeyword as string)
-	)
-		return `must satisfy the ${error.params.failingKeyword} branch of the conditional schema`
-	if (error.keyword === "uniqueItems") {
-		const { i, j } = error.params
-		if (Number.isInteger(i) && Number.isInteger(j))
-			return `duplicates item at ${error.instancePath}${pointer([Math.min(i, j)])}; array items must be unique`
-	}
-	if (error.keyword === "enum" && Array.isArray(error.params.allowedValues))
-		return `must be one of: ${error.params.allowedValues.map((value: unknown) => JSON.stringify(value)).join(", ")}`
-	if (error.keyword === "const" && Object.hasOwn(error.params, "allowedValue"))
-		return `must equal ${JSON.stringify(error.params.allowedValue)}`
-	if (error.keyword === "oneOf") {
-		if (error.params.passingSchemas === null)
-			return "must match exactly one alternative; none matched"
-		if (Array.isArray(error.params.passingSchemas))
-			return `must match exactly one alternative; multiple matched (alternatives ${error.params.passingSchemas.map((index: number) => index + 1).join(", ")})`
-	}
-	return error.message ?? "Schema violation"
-}
-
-function validationDiagnostic(
-	text: string,
-	parsed: ParsedDocument,
-	error: ErrorObject,
-): Diagnostic {
-	let jsonPointer = error.instancePath
-	if (
-		error.keyword === "uniqueItems" &&
-		Number.isInteger(error.params.i) &&
-		Number.isInteger(error.params.j)
-	)
-		jsonPointer += pointer([Math.max(error.params.i, error.params.j)])
-	const property: unknown =
-		error.params.additionalProperty ??
-		error.params.unevaluatedProperty ??
-		error.params.missingProperty ??
-		error.params.propertyName ??
-		error.propertyName
-	if (typeof property === "string") jsonPointer += pointer([property])
-	const node = parsed.locate(
-		jsonPointer,
-		error.keyword === "additionalProperties" ||
-			error.keyword === "unevaluatedProperties" ||
-			error.keyword === "propertyNames" ||
-			typeof error.propertyName === "string",
-	)
-	const rangeNode =
-		error.keyword === "required" && error.propertyName === undefined
-			? parsed.locate(error.instancePath)
-			: node
-	const length =
-		error.keyword === "required" && error.propertyName === undefined
-			? 1
-			: rangeNode?.length
-	return diagnostic(
-		text,
-		`schema/${error.keyword}`,
-		`${jsonPointer || "/"}: ${validationMessage(error)}`,
-		jsonPointer,
-		rangeNode?.offset ?? 0,
-		length ?? 1,
-	)
-}
-
 export class Engine {
 	readonly project: Project
-	readonly store: SchemaStore
-	private readonly compiled = new Map<string, Promise<ValidateFunction>>()
-	constructor(project: Project, options: StoreOptions = {}) {
+	readonly context: ValidationContext
+	private readonly prepared = new Map<Validator, Promise<PreparedValidator>>()
+	private registration: Promise<void> | undefined
+	constructor(project: Project, options: EngineOptions = {}) {
 		this.project = project
-		this.store = new SchemaStore(project, options)
-	}
-
-	validator(uri: string): Promise<ValidateFunction> {
-		let compiled = this.compiled.get(uri)
-		if (!compiled) {
-			compiled = this.compile(uri)
-			this.compiled.set(uri, compiled)
+		const watch = (uri: string) => options.onDependency?.(uri)
+		this.context = {
+			root: project.root,
+			configPath: project.configPath,
+			remote: {
+				...project.config.remote,
+				...(options.offline === undefined ? {} : { offline: options.offline }),
+			},
+			read: async (uri) => {
+				watch(uri)
+				return (options.read ?? readText)(uri)
+			},
+			...(options.fetch ? { fetch: options.fetch } : {}),
+			...(options.signal ? { signal: options.signal } : {}),
+			watch,
+			services: new Map(),
 		}
-		return compiled
 	}
-
-	private async compile(uri: string): Promise<ValidateFunction> {
-		try {
-			const resource = await this.store.load(uri)
-			const options = {
-				allErrors: true,
-				strictSchema: true,
-				strictTypes: false,
-				strictTuples: false,
-				strictRequired: false,
-				coerceTypes: false,
-				useDefaults: false,
-				removeAdditional: false,
-				validateSchema: true,
-				loadSchema: async (ref: string) => {
-					const loaded = await this.store.load(ref, resource.dialect)
-					if (loaded.dialect !== resource.dialect)
-						throw new CorrectlyError(
-							"unsupported-dialect",
-							`Mixed schema dialects: ${uri} references ${ref}`,
-						)
-					registerRootAnchors(ajv, loaded.schema, loaded.uri)
-					return loaded.schema as SchemaObject
-				},
-			}
-			const ajv =
-				resource.dialect === "2020-12" ? new Ajv2020(options) : new Ajv(options)
-			// CommonJS package exports retain a callable default at runtime.
-			const formats = addFormats as unknown as (instance: Ajv) => void
-			formats(ajv)
-			for (const keyword of ANNOTATIONS)
-				if (!ajv.RULES.keywords[keyword])
-					ajv.addKeyword({ keyword, valid: true })
-			// Ajv indexes plain anchors during reference resolution, but does not
-			// register the annotation keyword in its strict vocabulary.
-			if (resource.dialect === "2020-12")
-				ajv.addKeyword({
-					keyword: "$anchor",
-					schemaType: "string",
-					valid: true,
-				})
-			ajv.addSchema(resource.schema, resource.uri)
-			registerRootAnchors(ajv, resource.schema, resource.uri)
-			const validate = await ajv.compileAsync({
-				$schema: DIALECTS[resource.dialect],
-				$ref: uri,
-			})
-			return validate as ValidateFunction
-		} catch (error) {
-			if (error instanceof CorrectlyError) throw error
-			throw new CorrectlyError(
-				"schema",
-				`Cannot compile schema ${uri}: ${error instanceof Error ? error.message : String(error)}`,
-			)
+	private register(): Promise<void> {
+		return (this.registration ??= (async () => {
+			for (const rule of this.project.config.associations)
+				await rule.validate?.register?.(this.context)
+		})())
+	}
+	private validator(validator: Validator): Promise<PreparedValidator> {
+		let prepared = this.prepared.get(validator)
+		if (!prepared) {
+			prepared = (async () => {
+				await this.register()
+				const result = await validator.prepare(this.context)
+				if (!result || typeof result.validate !== "function")
+					throw new CorrectlyError(
+						"validator",
+						`Validator ${validator.id} did not prepare a validate function`,
+					)
+				return result
+			})()
+			this.prepared.set(validator, prepared)
 		}
+		return prepared
 	}
-
 	async prepare(): Promise<void> {
-		// Register configured resources before compiling references to their IDs.
-		for (const association of this.project.config.associations) {
-			if (association.schema !== null)
-				await this.store.load(schemaUri(association.schema, this.project.root))
-		}
-		for (const association of this.project.config.associations) {
-			if (association.schema !== null)
-				await this.validator(schemaUri(association.schema, this.project.root))
+		await this.register()
+		for (const rule of this.project.config.associations) {
+			if (rule.validate) {
+				if (!rule.validate.accepts.includes(rule.parse?.valueModel ?? "json"))
+					throw new CorrectlyError(
+						"adapter-incompatible",
+						`Parser ${rule.parse?.id ?? "json"} produces ${rule.parse?.valueModel ?? "json"}; validator ${rule.validate.id} accepts ${rule.validate.accepts.join(", ")}`,
+					)
+				await this.validator(rule.validate)
+			}
 		}
 	}
-
+	async editor(file: string) {
+		if (!isIncluded(this.project, file)) return undefined
+		const association = associationFor(this.project, file)
+		if (!association) return undefined
+		const rule = this.project.config.associations[association.index]!
+		const parser = rule.parse ?? defaultParser(file)
+		if (!rule.validate || !parser.editorLanguage) return undefined
+		if (!rule.validate.accepts.includes(parser.valueModel)) return undefined
+		const prepared = await this.validator(rule.validate)
+		return prepared.editor
+			? {
+					support: prepared.editor,
+					language: parser.editorLanguage,
+					association: association.index,
+				}
+			: undefined
+	}
 	async validate(file: string, text: string): Promise<FileResult> {
 		const association = associationFor(this.project, file)
-		const mode = association?.mode ?? modeFor(file)
+		const rule = association
+			? this.project.config.associations[association.index]
+			: undefined
+		const parser = rule?.parse ?? defaultParser(file)
 		const result: FileResult = {
 			file,
-			mode,
+			mode: parser.id,
 			association,
 			coverage: "excluded",
 			diagnostics: [],
 			failures: [],
 		}
 		if (!isIncluded(this.project, file)) return result
-		result.coverage = association?.schema ? "schema" : "syntax-only"
-		const parsed = parseDocument(text, mode)
-		result.diagnostics.push(...parsed.diagnostics)
-		if (association?.schema) {
-			try {
-				const validate = await this.validator(association.schema)
-				if (parsed.diagnostics.length === 0 && !validate(parsed.value)) {
+		result.coverage = rule?.validate
+			? association?.schema
+				? "schema"
+				: "validated"
+			: "syntax-only"
+		try {
+			this.context.signal?.throwIfAborted()
+			const parsed = await parser.parse(text, {
+				file,
+				...(this.context.signal ? { signal: this.context.signal } : {}),
+			})
+			result.diagnostics.push(...parsed.diagnostics)
+			if (rule?.validate) {
+				if (!rule.validate.accepts.includes(parser.valueModel))
+					throw new CorrectlyError(
+						"adapter-incompatible",
+						`Parser ${parser.id} produces ${parser.valueModel}; validator ${rule.validate.id} accepts ${rule.validate.accepts.join(", ")}`,
+					)
+				const validator = await this.validator(rule.validate)
+				if (!parsed.diagnostics.length)
 					result.diagnostics.push(
-						...validationContexts(
-							validate.errors ?? [],
-							(validate.errors ?? []).map((e) =>
-								validationDiagnostic(text, parsed, e),
-							),
-						),
+						...(await validator.validate({
+							file,
+							text,
+							parsed,
+							...(this.context.signal ? { signal: this.context.signal } : {}),
+						})),
 					)
-				}
-			} catch (error) {
-				result.failures.push(failure(error, file))
 			}
+		} catch (error) {
+			result.failures.push(failure(error, file))
 		}
 		return result
 	}
+	async dispose(): Promise<void> {
+		for (const prepared of this.prepared.values()) {
+			const result = await prepared.catch(() => undefined)
+			await result?.dispose?.()
+		}
+	}
 }

package/src/core/extensions.ts

@@ -0,0 +1,144 @@
+import type { Ajv, FormatDefinition } from "ajv"
+import { CorrectlyError } from "./types.ts"
+import { schemaChildren } from "./schema-walk.ts"
+
+/** Synchronous assertions and annotation-only keywords. Registration is explicit. */
+export type AjvExtension = {
+	id: string
+	formats?: Readonly<
+		Record<string, FormatDefinition<string> | FormatDefinition<number>>
+	>
+	annotations?: readonly string[]
+}
+
+type ExtensionSuggestion = {
+	id: string
+	formats: readonly string[]
+	guidance: string
+}
+// Discovery metadata only: implementations are installed by the consuming project.
+export const knownExtensions: readonly ExtensionSuggestion[] = [
+	{
+		id: "@correctlyjs/schemars",
+		formats: [
+			"int",
+			"uint",
+			"int8",
+			"uint8",
+			"int16",
+			"uint16",
+			"int32",
+			"uint32",
+			"int64",
+			"uint64",
+			"int128",
+			"uint128",
+			"float",
+			"double",
+			"ip",
+			"phone",
+			"partial-date-time",
+		],
+		guidance: `For a Schemars-generated schema, install @correctlyjs/schemars and import { schemars } from "@correctlyjs/schemars/ajv". Select the schema's reviewed Schemars version with schemars({ version: "..." }) in this Ajv validator's extensions in correctly.config.ts.`,
+	},
+]
+
+export function installExtensions(
+	ajv: Ajv,
+	extensions: readonly AjvExtension[],
+): void {
+	const formats = new Set<string>(),
+		annotations = new Set<string>()
+	const identifiers = new Set<string>()
+	for (const extension of extensions) {
+		if (
+			!extension ||
+			typeof extension !== "object" ||
+			typeof extension.id !== "string" ||
+			!extension.id
+		)
+			throw new CorrectlyError(
+				"extension",
+				"Pass extension implementations to ajv({ extensions: [...] }); string identifiers are not implementations.",
+			)
+		const id = extension.id
+		if (identifiers.has(id))
+			throw new CorrectlyError(
+				"extension",
+				`Duplicate extension identifier: ${id}`,
+			)
+		identifiers.add(id)
+		for (const [name, definition] of Object.entries(extension.formats ?? {})) {
+			if (formats.has(name))
+				throw new CorrectlyError(
+					"extension",
+					`Enabled extensions both define format ${JSON.stringify(name)}.`,
+				)
+			if (definition.async || typeof definition.validate !== "function")
+				throw new CorrectlyError(
+					"extension",
+					`Extension ${id} must provide a synchronous validator for format ${JSON.stringify(name)}.`,
+				)
+			formats.add(name)
+			const validate = definition.validate as (
+				value: string | number,
+			) => unknown
+			ajv.addFormat(name, {
+				...definition,
+				validate: (value: string | number) => {
+					const valid = validate(value)
+					if (typeof valid !== "boolean")
+						throw new CorrectlyError(
+							"extension",
+							`Extension ${id} returned a non-boolean result for format ${JSON.stringify(name)}. Validators must be synchronous.`,
+						)
+					return valid
+				},
+			})
+		}
+		for (const keyword of extension.annotations ?? []) {
+			if (annotations.has(keyword) || ajv.RULES.keywords[keyword])
+				throw new CorrectlyError(
+					"extension",
+					`Extension ${id} conflicts with keyword ${JSON.stringify(keyword)}.`,
+				)
+			annotations.add(keyword)
+			ajv.addKeyword({ keyword, valid: true })
+		}
+	}
+}
+
+export function assertFormats(
+	ajv: Ajv,
+	schema: unknown,
+	uri: string,
+	registry: readonly ExtensionSuggestion[],
+	location = "",
+): void {
+	if (typeof schema !== "object" || schema === null || Array.isArray(schema))
+		return
+	const object = schema as Record<string, unknown>
+	if (
+		typeof object.format === "string" &&
+		(!Object.hasOwn(ajv.formats, object.format) ||
+			ajv.formats[object.format] === true)
+	) {
+		const format = object.format
+		const extension = registry.find((entry) => entry.formats.includes(format))
+		const hint =
+			extension?.guidance ??
+			`Pass an extension implementing ${JSON.stringify(format)} to this Ajv validator's extensions in correctly.config.ts.`
+		throw new CorrectlyError(
+			"extension-required",
+			`This schema needs an extension.\nFormat ${JSON.stringify(format)} has no enabled validator; validation cannot proceed.\nSchema: ${uri}#${location}/format\n${hint}`,
+			{
+				schemaUri: uri,
+				schemaPointer: `${location}/format`,
+				format,
+				...(extension ? { suggestedExtension: extension.id } : {}),
+			},
+		)
+	}
+	for (const [path, child] of schemaChildren(object))
+		assertFormats(ajv, child, uri, registry, location + path)
+}

package/src/core/index.ts

@@ -8,3 +8,6 @@ export {
 	diagnosticDetails,
 	type DiagnosticView,
 } from "./diagnostics.ts"
+
+export * from "./adapters.ts"
+export * from "./parsers.ts"

package/src/core/parse.ts

@@ -7,13 +7,15 @@ import {
 	type Node,
 	type ParseError,
 } from "jsonc-parser"
-import type { Diagnostic, Mode, Position } from "./types.ts"
+import type { Diagnostic, Position } from "./types.ts"
 
 export type SourceSpan = { offset: number; length: number }
 export type ParsedDocument = {
 	value: unknown
 	diagnostics: Diagnostic[]
 	locate: (pointer: string, key?: boolean) => SourceSpan | undefined
+	/** Exact numeric lexeme when the parser can preserve it. */
+	rawNumber?: (pointer: string) => string | undefined
 }
 export type ParsedJsonDocument = ParsedDocument & { root: Node | undefined }
 
@@ -63,7 +65,10 @@ export function diagnostic(
 	}
 }
 
-export function parseDocument(text: string, mode: Mode): ParsedJsonDocument {
+export function parseDocument(
+	text: string,
+	mode: "json" | "jsonc",
+): ParsedJsonDocument {
 	const errors: ParseError[] = []
 	const root = parseTree(text, errors, {
 		disallowComments: mode === "json",
@@ -134,6 +139,25 @@ export function parseDocument(text: string, mode: Mode): ParsedJsonDocument {
 		root,
 		value: root ? value(root) : undefined,
 		diagnostics,
+		rawNumber: (jsonPointer) => {
+			const parts =
+				jsonPointer === ""
+					? []
+					: jsonPointer
+							.slice(1)
+							.split("/")
+							.map((p) => p.replace(/~1/g, "/").replace(/~0/g, "~"))
+			let node = root
+			for (const part of parts) {
+				if (!node) break
+				node = findNodeAtLocation(node, [
+					node.type === "array" ? Number(part) : part,
+				])
+			}
+			return node?.type === "number"
+				? text.slice(node.offset, node.offset + node.length)
+				: undefined
+		},
 		locate: (jsonPointer, key = false) => {
 			const node = locate(root, jsonPointer, key)
 			return node ? { offset: node.offset, length: node.length } : undefined

package/src/core/parsers.ts

@@ -0,0 +1,22 @@
+import type { Parser } from "./adapters.ts"
+import { parseDocument } from "./parse.ts"
+
+export function json(): Parser {
+	return {
+		id: "json",
+		valueModel: "json",
+		editorLanguage: "json",
+		parse: (text) => parseDocument(text, "json"),
+	}
+}
+export function jsonc(): Parser {
+	return {
+		id: "jsonc",
+		valueModel: "json",
+		editorLanguage: "jsonc",
+		parse: (text) => parseDocument(text, "jsonc"),
+	}
+}
+export function defaultParser(file: string): Parser {
+	return file.toLowerCase().endsWith(".jsonc") ? jsonc() : json()
+}

package/src/core/schema-walk.ts

@@ -0,0 +1,43 @@
+import { pointer } from "./parse.ts"
+
+/** Only schema positions: defaults, enums, examples and other data stay opaque. */
+export function* schemaChildren(
+	schema: Record<string, unknown>,
+): Generator<[string, unknown]> {
+	for (const key of [
+		"additionalItems",
+		"additionalProperties",
+		"contains",
+		"propertyNames",
+		"not",
+		"if",
+		"then",
+		"else",
+		"unevaluatedProperties",
+		"unevaluatedItems",
+		"contentSchema",
+	]) {
+		if (schema[key] !== undefined) yield [pointer([key]), schema[key]]
+	}
+	for (const key of [
+		"properties",
+		"patternProperties",
+		"definitions",
+		"$defs",
+		"dependentSchemas",
+		"dependencies",
+	]) {
+		const map = schema[key]
+		if (typeof map === "object" && map !== null && !Array.isArray(map))
+			for (const [name, child] of Object.entries(map))
+				yield [pointer([key, name]), child]
+	}
+	for (const key of ["allOf", "anyOf", "oneOf", "prefixItems", "items"]) {
+		const children = schema[key]
+		if (Array.isArray(children)) {
+			for (const [index, child] of children.entries())
+				yield [pointer([key, index]), child]
+		} else if (key === "items" && children !== undefined)
+			yield [pointer([key]), children]
+	}
+}