correctly 0.0.0

package/examples/basic/project.json

@@ -0,0 +1 @@
+{ "name": "Correctly", "color": "blue" }

package/examples/basic/project.jsonc

@@ -0,0 +1,5 @@
+{
+	// Comments and trailing commas are allowed in JSONC mode.
+	"name": "Correctly",
+	"color": "red",
+}

package/examples/basic/project.schema.json

@@ -0,0 +1,10 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"required": ["name"],
+	"additionalProperties": false,
+	"properties": {
+		"name": { "type": "string", "description": "The project name" },
+		"color": { "enum": ["red", "blue"], "description": "A primary color" }
+	}
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "correctly",
+	"version": "0.0.0",
+	"description": "Shared JSON Schema validation for CI and editors",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jeremybanka/correctly.git",
+		"directory": "packages/correctly"
+	},
+	"license": "MPL-2.0",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/core.d.mts",
+			"import": "./dist/core.mjs"
+		},
+		"./config.schema.json": "./src/core/config.schema.json"
+	},
+	"bin": {
+		"correctly": "./dist/cli.mjs",
+		"correctly-lsp": "./dist/lsp.mjs"
+	},
+	"files": [
+		"dist",
+		"src",
+		"docs",
+		"LICENSE",
+		"README.md",
+		"AGENTS.md",
+		"examples"
+	],
+	"scripts": {
+		"build": "vp pack",
+		"build:vsix": "node src/cli/vsix.ts",
+		"test": "vp test",
+		"test:public": "vp test tests/public",
+		"test:private": "vp test tests/private",
+		"test:watch": "vp test watch"
+	},
+	"dependencies": {
+		"ajv": "8.20.0",
+		"ajv-formats": "3.0.1",
+		"jsonc-parser": "3.3.1",
+		"picomatch": "4.0.7",
+		"tinyglobby": "0.2.17",
+		"vscode-json-languageservice": "5.7.2",
+		"vscode-languageserver": "10.1.2",
+		"vscode-languageserver-textdocument": "1.0.15"
+	},
+	"devDependencies": {
+		"@types/node": "26.6.3",
+		"@types/picomatch": "4.0.3",
+		"@types/vscode": "1.138.0",
+		"@vscode/vsce": "4.0.0",
+		"rolldown": "1.2.11",
+		"vscode-languageclient": "10.1.2"
+	},
+	"engines": {
+		"node": ">=22.18.0"
+	}
+}

package/src/cli/check.ts

@@ -0,0 +1,83 @@
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+import { glob } from "tinyglobby"
+import {
+	discoverConfig,
+	exclusions,
+	isIncluded,
+	loadProject,
+} from "../core/config.ts"
+import { Engine } from "../core/engine.ts"
+import { failure, type Report } from "../core/types.ts"
+
+export type CheckOptions = {
+	cwd?: string
+	config?: string
+	offline?: boolean
+	files?: string[]
+	onRead?: (file: string, text: string) => void
+}
+export async function check(options: CheckOptions = {}): Promise<Report> {
+	const report: Report = {
+		reportVersion: 1,
+		config: null,
+		files: [],
+		failures: [],
+		summary: {
+			checked: 0,
+			schemaCovered: 0,
+			syntaxOnly: 0,
+			invalid: 0,
+			failures: 0,
+		},
+		exitCode: 0,
+	}
+	try {
+		const cwd = path.resolve(options.cwd ?? process.cwd())
+		const configPath = options.config
+			? path.resolve(cwd, options.config)
+			: await discoverConfig(cwd)
+		report.config = configPath
+		const project = await loadProject(configPath)
+		const engine = new Engine(
+			project,
+			options.offline === undefined ? {} : { offline: options.offline },
+		)
+		await engine.prepare()
+		const files = options.files?.length
+			? options.files.map((f) => path.resolve(cwd, f))
+			: await glob(project.config.files ?? ["**/*.json", "**/*.jsonc"], {
+					cwd: project.root,
+					ignore: exclusions(project),
+					absolute: true,
+					dot: true,
+					onlyFiles: true,
+				})
+		for (const file of [...new Set(files)].sort()) {
+			try {
+				const included = isIncluded(project, file)
+				const text = included ? await readFile(file, "utf8") : ""
+				if (included) options.onRead?.(file, text)
+				report.files.push(await engine.validate(file, text))
+			} catch (error) {
+				report.failures.push(failure(error, file))
+			}
+		}
+	} catch (error) {
+		report.failures.push(failure(error))
+	}
+	const checked = report.files.filter((f) => f.coverage !== "excluded")
+	report.summary = {
+		checked: checked.length,
+		schemaCovered: checked.filter((f) => f.coverage === "schema").length,
+		syntaxOnly: checked.filter((f) => f.coverage === "syntax-only").length,
+		invalid: checked.filter((f) => f.diagnostics.length > 0).length,
+		failures:
+			report.failures.length +
+			report.files.reduce((n, f) => n + f.failures.length, 0),
+	}
+	report.exitCode = report.summary.failures ? 2 : report.summary.invalid ? 1 : 0
+	return report
+}
+
+export { readableReport } from "./readable.ts"

package/src/cli/main.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util"
+import { check, readableReport } from "./check.ts"
+import { failure, type Report } from "../core/types.ts"
+
+const HELP = `correctly check [files...] [--config path] [--offline] [--format readable|json]
+correctly-lsp --stdio
+
+Validate JSON/JSONC using associations in correctly.config.json.
+Exit 0: valid; 1: document errors; 2: configuration, schema, or execution errors.
+Formatting does not affect validation. See the package guide for configuration.
+`
+
+export async function run(
+	args: string[],
+	cwd = process.cwd(),
+): Promise<{ output: string; exitCode: number }> {
+	let json =
+		args.includes("--format=json") ||
+		args.some((arg, i) => arg === "--format" && args[i + 1] === "json")
+	try {
+		const { values, positionals } = parseArgs({
+			args,
+			allowPositionals: true,
+			strict: true,
+			options: {
+				config: { type: "string", short: "c" },
+				offline: { type: "boolean" },
+				format: { type: "string", default: "readable" },
+				help: { type: "boolean", short: "h" },
+			},
+		})
+		json = values.format === "json"
+		if (values.help || positionals.length === 0)
+			return { output: HELP, exitCode: 0 }
+		if (positionals[0] !== "check")
+			throw new Error(`Unknown command: ${positionals[0]}`)
+		if (values.format !== "json" && values.format !== "readable")
+			throw new Error(`Unknown report format: ${values.format}`)
+		const sources = new Map<string, string>()
+		const report = await check({
+			cwd,
+			files: positionals.slice(1),
+			...(values.config ? { config: values.config } : {}),
+			...(values.offline === undefined ? {} : { offline: values.offline }),
+			...(json
+				? {}
+				: {
+						onRead: (file: string, text: string) => {
+							sources.set(file, text)
+						},
+					}),
+		})
+		return {
+			output: json
+				? JSON.stringify(report, null, 2)
+				: readableReport(report, { cwd, sources }),
+			exitCode: report.exitCode,
+		}
+	} catch (error) {
+		const report: Report = {
+			reportVersion: 1,
+			config: null,
+			files: [],
+			failures: [failure(error)],
+			summary: {
+				checked: 0,
+				schemaCovered: 0,
+				syntaxOnly: 0,
+				invalid: 0,
+				failures: 1,
+			},
+			exitCode: 2,
+		}
+		return {
+			output: json
+				? JSON.stringify(report, null, 2)
+				: readableReport(report, { cwd }),
+			exitCode: 2,
+		}
+	}
+}
+
+const result = await run(process.argv.slice(2))
+process.stdout.write(`${result.output}\n`)
+process.exitCode = result.exitCode

package/src/cli/readable.ts

@@ -0,0 +1,295 @@
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { styleText } from "node:util"
+import type { Diagnostic, Failure, FileResult, Report } from "../core/types.ts"
+import { diagnosticViews, type DiagnosticView } from "../core/diagnostics.ts"
+
+export type ReadableOptions = {
+	cwd?: string
+	sources?: ReadonlyMap<string, string>
+	color?: boolean
+}
+
+// Node's automatic color detection respects the output stream and NO_COLOR,
+// NODE_DISABLE_COLORS, and FORCE_COLOR. Use the same palette as Lasertag.
+function createStyler(color?: boolean) {
+	const apply = (format: Parameters<typeof styleText>[0], text: string) =>
+		color === false
+			? text
+			: styleText(format, text, {
+					stream: process.stdout,
+					...(color === true ? { validateStream: false } : {}),
+				})
+	return {
+		bold: (text: string) => apply("bold", text),
+		bad: (text: string) => apply(["bold", "red"], text),
+		caret: (text: string) => apply(["bold", "yellow"], text),
+		code: (text: string) => apply("cyan", text),
+		dim: (text: string) => apply("dim", text),
+		success: (text: string) => apply(["bold", "green"], text),
+		warning: (text: string) => apply(["bold", "yellow"], text),
+	}
+}
+type Styler = ReturnType<typeof createStyler>
+
+function displayPath(cwd: string, file: string): string {
+	const relative = path.relative(cwd, file)
+	return relative &&
+		relative !== ".." &&
+		!relative.startsWith(`..${path.sep}`) &&
+		!path.isAbsolute(relative)
+		? relative
+		: file
+}
+
+function displaySchema(cwd: string, uri: string): string {
+	const url = new URL(uri)
+	if (url.protocol !== "file:") return uri
+	return `${displayPath(cwd, fileURLToPath(url))}${url.hash}`
+}
+
+function countLabel(count: number, label: string): string {
+	return `${count} ${label}${count === 1 ? "" : "s"}`
+}
+
+function lastSelectedLine(diagnostic: Diagnostic): number {
+	const { start, end } = diagnostic.range
+	return Math.max(
+		start.line,
+		end.line - (end.line > start.line && end.character === 0 ? 1 : 0),
+	)
+}
+
+// Like Lasertag, keep one context line on either side and collapse long ranges
+// to their first/last lines. Tabs are expanded equally in source and carets.
+function excerpt(
+	source: string[],
+	diagnostic: Diagnostic,
+	diagnosedLines: ReadonlySet<number>,
+	styler: Styler,
+) {
+	const start = diagnostic.range.start.line
+	const end = Math.min(lastSelectedLine(diagnostic), source.length - 1)
+	if (start < 0 || start >= source.length) return undefined
+	const visible: (number | undefined)[] = []
+	if (start > 0 && !diagnosedLines.has(start - 1)) visible.push(start - 1)
+	visible.push(start)
+	if (end > start + 1) visible.push(undefined)
+	if (end > start) visible.push(end)
+	if (
+		end + 1 < source.length &&
+		!diagnosedLines.has(end + 1) &&
+		(end + 1 < source.length - 1 || source[end + 1] !== "")
+	)
+		visible.push(end + 1)
+	const width = Math.max(
+		...visible.map((line) =>
+			line === undefined ? 1 : String(line + 1).length,
+		),
+	)
+	const output: string[] = []
+	for (const line of visible) {
+		if (line === undefined) {
+			output.push(styler.dim(`${" ".repeat(width)} │ …`))
+			continue
+		}
+		const text = source[line]!
+		const selected = line >= start && line <= end
+		const expanded = text.replaceAll("\t", "    ").trimEnd()
+		output.push(
+			`${styler.dim(`${String(line + 1).padStart(width)} │`)} ${selected ? expanded : styler.dim(expanded)}`,
+		)
+		if (!selected) continue
+		const from = line === start ? diagnostic.range.start.character : 0
+		const to =
+			line === diagnostic.range.end.line
+				? diagnostic.range.end.character
+				: text.length
+		const caretStart = text.slice(0, from).replaceAll("\t", "    ").length
+		const caretWidth = Math.max(
+			1,
+			text.slice(from, to).replaceAll("\t", "    ").length,
+		)
+		output.push(
+			`${styler.dim(`${" ".repeat(width)} │`)} ${" ".repeat(caretStart)}${styler.caret("^".repeat(caretWidth))}`,
+		)
+	}
+	return { lines: output, width }
+}
+
+type FileGroup = { file: string; result?: FileResult; failures: Failure[] }
+
+function renderDiagnostic(
+	issue: DiagnosticView,
+	prefix: string,
+	last: boolean,
+	source: string[] | undefined,
+	diagnosedLines: ReadonlySet<number>,
+	styler: Styler,
+	shownRegions = new Set<string>(),
+): string[] {
+	const branch = last ? "└─" : "├─"
+	const continuation = `${prefix}${last ? "   " : "│  "}`
+	const output = [
+		`${styler.dim(`${prefix}${branch}`)} ${styler.dim(`${issue.range.start.line + 1}:${issue.range.start.character + 1}`)}  ${styler.code(issue.code)}`,
+	]
+	const region = source
+		? excerpt(source, issue, diagnosedLines, styler)
+		: undefined
+	const regionKey = `${issue.offset}:${issue.length}`
+	if (region && !shownRegions.has(regionKey))
+		output.push(
+			...region.lines.map((line) => `${styler.dim(continuation)}${line}`),
+		)
+	shownRegions.add(regionKey)
+	const indentation = `${continuation}${" ".repeat(region ? region.width + 1 : 0)}`
+	output.push(
+		`${styler.dim(continuation)}${" ".repeat(region ? region.width + 1 : 0)}${styler.dim("╰─")} ${issue.message}`,
+	)
+	for (const [index, branch] of issue.branches.entries()) {
+		const finalBranch = index === issue.branches.length - 1
+		output.push(
+			`${styler.dim(`${indentation}${finalBranch ? "└─" : "├─"}`)} ${styler.bold(branch.label)}`,
+		)
+		const children = branch.diagnostics.toSorted((a, b) => a.offset - b.offset)
+		for (const [childIndex, child] of children.entries())
+			output.push(
+				...renderDiagnostic(
+					child,
+					`${indentation}${finalBranch ? "   " : "│  "}`,
+					childIndex === children.length - 1,
+					source,
+					diagnosedLines,
+					styler,
+					shownRegions,
+				),
+			)
+	}
+	return output
+}
+
+function fileSection(
+	group: FileGroup,
+	options: ReadableOptions,
+	styler: Styler,
+): string {
+	const cwd = options.cwd ?? process.cwd()
+	const diagnostics = diagnosticViews(group.result?.diagnostics ?? []).toSorted(
+		(a, b) => a.offset - b.offset,
+	)
+	const counts = [
+		...(diagnostics.length ? [countLabel(diagnostics.length, "error")] : []),
+		...(group.failures.length
+			? [countLabel(group.failures.length, "failure")]
+			: []),
+	]
+	const status =
+		counts.join(", ") ||
+		(group.result?.coverage === "excluded" ? "excluded" : "valid")
+	const statusColor = counts.length
+		? styler.bad
+		: group.result?.coverage === "excluded"
+			? styler.dim
+			: styler.success
+	let header = `${styler.bold(displayPath(cwd, group.file))}  ${statusColor(status)}`
+	if (group.result) {
+		const { mode, coverage, association } = group.result
+		const format = mode.toUpperCase()
+		const schema = association?.schema
+		const description =
+			coverage === "excluded"
+				? format
+				: schema
+					? `${format} against ${association.name} (${displaySchema(cwd, schema)})`
+					: `${format} syntax only (${association ? `association: ${association.name}` : "no schema association"})`
+		header += `  ${styler.dim(`·  ${description}`)}`
+	}
+	const output = [header]
+	const text = options.sources?.get(group.file)
+	const source = text === undefined ? undefined : text.split(/\r\n|\r|\n/)
+	const diagnosedLines = new Set<number>()
+	if (source)
+		for (const diagnostic of group.result?.diagnostics ?? []) {
+			for (
+				let line = diagnostic.range.start.line;
+				line <= Math.min(lastSelectedLine(diagnostic), source.length - 1);
+				line++
+			)
+				diagnosedLines.add(line)
+		}
+	const issues: (DiagnosticView | Failure)[] = [
+		...diagnostics,
+		...group.failures,
+	]
+	for (const [index, issue] of issues.entries()) {
+		const last = index === issues.length - 1
+		const branch = last ? "└─" : "├─"
+		if ("range" in issue) {
+			output.push(
+				...renderDiagnostic(issue, "", last, source, diagnosedLines, styler),
+			)
+		} else
+			output.push(
+				`${styler.dim(branch)} ${styler.bad(issue.code)}: ${issue.message}`,
+			)
+		if (!last) output.push(styler.dim("│"))
+	}
+	return output.join("\n")
+}
+
+export function readableReport(
+	report: Report,
+	options: ReadableOptions = {},
+): string {
+	const styler = createStyler(options.color)
+	const groups = new Map<string, FileGroup>()
+	for (const result of report.files)
+		groups.set(result.file, {
+			file: result.file,
+			result,
+			failures: [...result.failures],
+		})
+	const globalFailures: Failure[] = []
+	for (const error of report.failures) {
+		if (!error.file) {
+			globalFailures.push(error)
+			continue
+		}
+		let group = groups.get(error.file)
+		if (!group) {
+			group = { file: error.file, failures: [] }
+			groups.set(error.file, group)
+		}
+		group.failures.push(error)
+	}
+	const output = [...groups.values()]
+		.toSorted((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0))
+		.map((group) => fileSection(group, options, styler))
+	for (const error of globalFailures)
+		output.push(`${styler.bad(error.code)}: ${error.message}`)
+	const errors = report.files.reduce(
+		(count, file) => count + diagnosticViews(file.diagnostics).length,
+		0,
+	)
+	const s = report.summary
+	const status =
+		report.exitCode === 2
+			? `▲ Check failed with ${countLabel(s.failures, "failure")}`
+			: report.exitCode === 1
+				? `▲ Check found ${countLabel(errors, "error")} in ${countLabel(s.invalid, "file")}`
+				: "✓ Check passed"
+	output.push(
+		[
+			styler.dim("─".repeat(56)),
+			"",
+			(report.exitCode === 2
+				? styler.bad
+				: report.exitCode === 1
+					? styler.warning
+					: styler.success)(status),
+			"",
+			`${s.checked} checked, ${s.schemaCovered} schema-covered, ${s.syntaxOnly} syntax-only, ${s.invalid} invalid, ${s.failures} failures`,
+		].join("\n"),
+	)
+	return output.join("\n\n")
+}

package/src/cli/vsix.ts

@@ -0,0 +1,86 @@
+import { spawn } from "node:child_process"
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import { createRequire } from "node:module"
+import path from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+import { rolldown } from "rolldown"
+
+export async function buildVsix(
+	packageRoot: string,
+	outdir: string,
+): Promise<string> {
+	const buildRoot = path.join(outdir, ".correctly-vsix")
+	await rm(buildRoot, { force: true, recursive: true })
+	await mkdir(path.join(buildRoot, "dist"), { recursive: true })
+	for (const [entry, outfile] of [
+		["vscode/extension", "extension"],
+		["lsp/server", "server"],
+	]) {
+		const bundle = await rolldown({
+			input: path.join(packageRoot, `src/${entry}.ts`),
+			platform: "node",
+			resolve: { mainFields: ["module", "main"] },
+			external: ["vscode"],
+			onLog: (level, log, handler) =>
+				handler(log.code === "UNRESOLVED_IMPORT" ? "error" : level, log),
+		})
+		try {
+			await bundle.write({
+				file: path.join(buildRoot, `dist/${outfile}.mjs`),
+				format: "esm",
+				sourcemap: true,
+			})
+		} finally {
+			await bundle.close()
+		}
+	}
+	const pkg = JSON.parse(
+		await readFile(path.join(packageRoot, "package.json"), "utf8"),
+	) as { version: string }
+	const manifest = JSON.parse(
+		await readFile(path.join(packageRoot, "src/vscode/package.json"), "utf8"),
+	) as { version: string }
+	manifest.version = pkg.version
+	await writeFile(
+		path.join(buildRoot, "package.json"),
+		`${JSON.stringify(manifest, null, 2)}\n`,
+	)
+	await cp(path.join(packageRoot, "LICENSE"), path.join(buildRoot, "LICENSE"))
+	await cp(
+		path.join(packageRoot, "src/vscode/README.md"),
+		path.join(buildRoot, "README.md"),
+	)
+	const require = createRequire(import.meta.url)
+	const vsceRoot = path.dirname(require.resolve("@vscode/vsce/package.json"))
+	const destination = path.join(outdir, `Correctly-${pkg.version}.vsix`)
+	const child = spawn(
+		process.execPath,
+		[
+			path.join(vsceRoot, "vsce"),
+			"package",
+			"--no-dependencies",
+			"--allow-missing-repository",
+			"--out",
+			destination,
+		],
+		{ cwd: buildRoot, stdio: "inherit" },
+	)
+	const code = await new Promise<number | null>((resolve, reject) => {
+		child.on("error", reject)
+		child.on("close", resolve)
+	})
+	if (code !== 0) throw new Error(`VSCE failed with exit code ${code}`)
+	return destination
+}
+
+if (
+	process.argv[1] &&
+	pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url
+) {
+	const packageRoot = fileURLToPath(new URL("../../", import.meta.url))
+	const output = await buildVsix(
+		packageRoot,
+		path.resolve(packageRoot, "../../artifacts"),
+	)
+	process.stdout.write(`${output}\n`)
+}

package/src/core/config.schema.json

@@ -0,0 +1,47 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["associations"],
+	"properties": {
+		"$schema": { "type": "string" },
+		"files": { "$ref": "#/definitions/patterns" },
+		"exclude": { "$ref": "#/definitions/patterns" },
+		"associations": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["files", "schema"],
+				"properties": {
+					"name": { "type": "string", "minLength": 1 },
+					"files": { "$ref": "#/definitions/patterns" },
+					"schema": { "type": ["string", "null"], "minLength": 1 },
+					"mode": { "enum": ["json", "jsonc"] }
+				}
+			}
+		},
+		"remote": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"offline": { "type": "boolean" },
+				"cacheDir": { "type": "string", "minLength": 1 },
+				"timeoutMs": { "type": "integer", "minimum": 1, "maximum": 60000 },
+				"maxBytes": { "type": "integer", "minimum": 1, "maximum": 16777216 },
+				"maxRequests": { "type": "integer", "minimum": 1, "maximum": 256 }
+			}
+		}
+	},
+	"definitions": {
+		"patterns": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "string",
+				"minLength": 1,
+				"pattern": "^(?![/!])(?![A-Za-z]:)(?!.*(?:^|/)\\.\\.(?:/|$)).+"
+			}
+		}
+	}
+}