correctly 0.0.0

package/src/core/config.ts

@@ -0,0 +1,200 @@
+import { readFile, stat } from "node:fs/promises"
+import path from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+import { Ajv } from "ajv"
+import picomatch from "picomatch"
+import configSchema from "./config.schema.json" with { type: "json" }
+import { parseDocument } from "./parse.ts"
+import { CorrectlyError, type Association, type Mode } from "./types.ts"
+
+export const CONFIG_NAME = "correctly.config.json"
+export const DEFAULT_EXCLUDES = [
+	"**/node_modules/**",
+	"**/.git/**",
+	"**/dist/**",
+	"**/artifacts/**",
+	"**/.correctly-cache/**",
+]
+export type ProjectConfig = {
+	files?: string[]
+	exclude?: string[]
+	associations: {
+		name?: string
+		files: string[]
+		schema: string | null
+		mode?: Mode
+	}[]
+	remote?: {
+		offline?: boolean
+		cacheDir?: string
+		timeoutMs?: number
+		maxBytes?: number
+		maxRequests?: number
+	}
+}
+export type Project = {
+	configPath: string
+	root: string
+	config: ProjectConfig
+}
+export type ReadText = (uri: string) => Promise<string>
+export const readText: ReadText = (uri) => readFile(fileURLToPath(uri), "utf8")
+const validateConfig = new Ajv({ allErrors: true, strict: true }).compile(
+	configSchema,
+)
+
+export function contains(root: string, file: string): boolean {
+	const relative = path.relative(root, file)
+	return (
+		relative !== ".." &&
+		!relative.startsWith(`..${path.sep}`) &&
+		!path.isAbsolute(relative)
+	)
+}
+
+export async function discoverConfig(
+	start: string,
+	boundary?: string,
+	virtualFiles: ReadonlySet<string> = new Set(),
+): Promise<string> {
+	let directory = path.resolve(start)
+	if (boundary && !contains(boundary, directory))
+		throw new CorrectlyError("config", `Path is outside workspace ${boundary}`)
+	while (true) {
+		const candidate = path.join(directory, CONFIG_NAME)
+		if (virtualFiles.has(candidate)) return candidate
+		try {
+			const info = await stat(candidate)
+			if (info.isFile()) return candidate
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error
+		}
+		const parent = path.dirname(directory)
+		if (directory === boundary || parent === directory) break
+		directory = parent
+	}
+	throw new CorrectlyError(
+		"config",
+		`No ${CONFIG_NAME} found from ${start}${boundary ? ` within ${boundary}` : ""}`,
+	)
+}
+
+export async function loadProject(
+	configPath: string,
+	read: ReadText = readText,
+): Promise<Project> {
+	const resolved = path.resolve(configPath)
+	let text: string
+	try {
+		text = await read(pathToFileURL(resolved).href)
+	} catch (error) {
+		throw new CorrectlyError(
+			"config",
+			`Cannot read configuration ${resolved}: ${String(error)}`,
+		)
+	}
+	const parsed = parseDocument(text, "json")
+	if (parsed.diagnostics.length) {
+		const d = parsed.diagnostics[0]!
+		throw new CorrectlyError(
+			"config",
+			`${resolved}:${d.range.start.line + 1}:${d.range.start.character + 1}: ${d.message}`,
+		)
+	}
+	if (!validateConfig(parsed.value)) {
+		throw new CorrectlyError(
+			"config",
+			`${resolved}: ${validateConfig.errors?.map((e) => `${e.instancePath || "/"} ${e.message}`).join("; ")}`,
+		)
+	}
+	const config = parsed.value as ProjectConfig
+	for (const pattern of [
+		...(config.files ?? []),
+		...(config.exclude ?? []),
+		...config.associations.flatMap((a) => a.files),
+	]) {
+		if (pattern.includes("\\"))
+			throw new CorrectlyError(
+				"config",
+				`Use forward slashes in patterns: ${pattern}`,
+			)
+	}
+	return { configPath: resolved, root: path.dirname(resolved), config }
+}
+
+export function schemaUri(value: string, root: string): string {
+	if (
+		/^[A-Za-z][A-Za-z\d+.-]*:/.test(value) &&
+		!/^[A-Za-z]:[\\/]/.test(value)
+	) {
+		const uri = new URL(value)
+		if (!["file:", "http:", "https:"].includes(uri.protocol))
+			throw new CorrectlyError(
+				"schema",
+				`Unsupported schema protocol: ${uri.protocol}`,
+			)
+		return uri.href
+	}
+	const hash = value.indexOf("#")
+	const filename = hash === -1 ? value : value.slice(0, hash)
+	const uri = pathToFileURL(path.resolve(root, filename))
+	if (hash !== -1) uri.hash = value.slice(hash + 1)
+	return uri.href
+}
+
+export function exclusions(project: Project): string[] {
+	const cachePath = path.resolve(
+		project.root,
+		project.config.remote?.cacheDir ?? ".correctly-cache",
+	)
+	const relative = path
+		.relative(project.root, cachePath)
+		.split(path.sep)
+		.join("/")
+	return [
+		...DEFAULT_EXCLUDES,
+		...(project.config.exclude ?? []),
+		...(relative && contains(project.root, cachePath)
+			? [`${relative}/**`]
+			: []),
+	]
+}
+
+export function isIncluded(project: Project, file: string): boolean {
+	if (!contains(project.root, file)) return false
+	const relative = path.relative(project.root, file).split(path.sep).join("/")
+	const options = { dot: true }
+	return (
+		picomatch(
+			project.config.files ?? ["**/*.json", "**/*.jsonc"],
+			options,
+		)(relative) && !picomatch(exclusions(project), options)(relative)
+	)
+}
+
+export function associationFor(
+	project: Project,
+	file: string,
+): Association | null {
+	const relative = path.relative(project.root, file).split(path.sep).join("/")
+	for (
+		let index = project.config.associations.length - 1;
+		index >= 0;
+		index--
+	) {
+		const rule = project.config.associations[index]!
+		if (picomatch(rule.files, { dot: true })(relative)) {
+			return {
+				index,
+				name: rule.name ?? `association ${index + 1}`,
+				schema:
+					rule.schema === null ? null : schemaUri(rule.schema, project.root),
+				mode: rule.mode ?? modeFor(file),
+			}
+		}
+	}
+	return null
+}
+export function modeFor(file: string): Mode {
+	return path.extname(file).toLowerCase() === ".jsonc" ? "jsonc" : "json"
+}

package/src/core/diagnostics.ts

@@ -0,0 +1,114 @@
+import type { ErrorObject } from "ajv"
+import type { Diagnostic } from "./types.ts"
+
+export type DiagnosticView = Diagnostic & {
+	branches: { label: string; diagnostics: DiagnosticView[] }[]
+}
+
+// Ajv emits branch failures before the applicator's summary. Keep the complete
+// flat report and annotate only relationships established by schema paths.
+// Reference paths can lose their caller; leave those errors standalone.
+export function validationContexts(
+	errors: readonly ErrorObject[],
+	diagnostics: Diagnostic[],
+): Diagnostic[] {
+	const summaries = errors.flatMap((error, index) => {
+		if (error.keyword === "anyOf" || error.keyword === "oneOf")
+			return [
+				{ index, error, prefix: `${error.schemaPath}/`, alternative: true },
+			]
+		if (
+			error.keyword === "if" &&
+			["then", "else"].includes(error.params.failingKeyword as string)
+		)
+			return [
+				{
+					index,
+					error,
+					prefix: `${error.schemaPath.slice(0, -3)}/${error.params.failingKeyword}`,
+					alternative: false,
+				},
+			]
+		return []
+	})
+	return diagnostics.map((diagnostic, index) => {
+		const error = errors[index]!
+		const candidates = summaries.filter(
+			(parent) =>
+				parent.index > index &&
+				(error.instancePath === parent.error.instancePath ||
+					error.instancePath.startsWith(`${parent.error.instancePath}/`)) &&
+				(parent.error.propertyName === undefined ||
+					error.propertyName === parent.error.propertyName) &&
+				(parent.alternative
+					? error.schemaPath.startsWith(parent.prefix)
+					: error.schemaPath === parent.prefix ||
+						error.schemaPath.startsWith(`${parent.prefix}/`)),
+		)
+		const parent = candidates.toSorted(
+			(a, b) => b.prefix.length - a.prefix.length || a.index - b.index,
+		)[0]
+		if (!parent) return diagnostic
+		const branch = parent.alternative
+			? error.schemaPath.slice(parent.prefix.length).split("/")[0]!
+			: (parent.error.params.failingKeyword as string)
+		if (parent.alternative && !/^\d+$/.test(branch)) return diagnostic
+		return {
+			...diagnostic,
+			context: {
+				parent: parent.index,
+				label: parent.alternative
+					? `Alternative ${Number(branch) + 1}`
+					: branch === "then"
+						? "Then branch"
+						: "Else branch",
+			},
+		}
+	})
+}
+
+export function diagnosticViews(
+	diagnostics: readonly Diagnostic[],
+): DiagnosticView[] {
+	const views = diagnostics.map((diagnostic): DiagnosticView => ({
+		...diagnostic,
+		branches: [],
+	}))
+	const roots: DiagnosticView[] = []
+	for (const [index, view] of views.entries()) {
+		const context = view.context
+		// Parents must follow their children, so malformed metadata cannot create
+		// cycles or make a diagnostic disappear from the displayed report.
+		const parent =
+			context && Number.isInteger(context.parent) && context.parent > index
+				? views[context.parent]
+				: undefined
+		if (!parent) {
+			roots.push(view)
+			continue
+		}
+		let branch = parent.branches.find(
+			(branch) => branch.label === context!.label,
+		)
+		if (!branch) {
+			branch = { label: context!.label, diagnostics: [] }
+			parent.branches.push(branch)
+		}
+		branch.diagnostics.push(view)
+	}
+	return roots
+}
+
+export function diagnosticDetails(
+	view: DiagnosticView,
+): { label: string; diagnostic: DiagnosticView }[] {
+	return view.branches.flatMap((branch) =>
+		branch.diagnostics.flatMap((child) => [
+			{ label: branch.label, diagnostic: child },
+			...diagnosticDetails(child).map((detail) => ({
+				...detail,
+				label: `${branch.label} / ${detail.label}`,
+			})),
+		]),
+	)
+}

package/src/core/engine.ts

@@ -0,0 +1,247 @@
+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"
+
+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
+	}
+}
+
+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 = {}) {
+		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)
+		}
+		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)}`,
+			)
+		}
+	}
+
+	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))
+		}
+	}
+
+	async validate(file: string, text: string): Promise<FileResult> {
+		const association = associationFor(this.project, file)
+		const mode = association?.mode ?? modeFor(file)
+		const result: FileResult = {
+			file,
+			mode,
+			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.diagnostics.push(
+						...validationContexts(
+							validate.errors ?? [],
+							(validate.errors ?? []).map((e) =>
+								validationDiagnostic(text, parsed, e),
+							),
+						),
+					)
+				}
+			} catch (error) {
+				result.failures.push(failure(error, file))
+			}
+		}
+		return result
+	}
+}

package/src/core/index.ts

@@ -0,0 +1,10 @@
+export * from "./types.ts"
+export * from "./parse.ts"
+export * from "./config.ts"
+export * from "./schemas.ts"
+export * from "./engine.ts"
+export {
+	diagnosticViews,
+	diagnosticDetails,
+	type DiagnosticView,
+} from "./diagnostics.ts"