@effected/schemastore 0.1.0

package/AnnotationCarriers.js

@@ -0,0 +1,137 @@
+import { KeywordFamilies } from "./KeywordFamilies.js";
+import { Effect, Result, Schema } from "effect";
+
+//#region src/AnnotationCarriers.ts
+/**
+* Indicates that the carrier re-graft walk nested past the package's
+* hardening cap (256 levels), which also intercepts cyclic inputs before
+* they can recurse forever.
+*
+* Raised by {@link AnnotationCarriers.carry}.
+*
+* @public
+*/
+var CarrierDepthExceededError = class extends Schema.TaggedErrorClass()("CarrierDepthExceededError", {
+	/** JSON pointer (in the lowered document's coordinates) where the cap was hit. */
+	path: Schema.String,
+	/** The nesting cap that was exceeded. */
+	maxDepth: Schema.Number
+}) {
+	get message() {
+		return `Carrier re-graft nesting exceeds ${this.maxDepth} levels at "${this.path}"`;
+	}
+};
+var CarryFailure = class {
+	error;
+	constructor(error) {
+		this.error = error;
+	}
+};
+const escapePointerSegment = (segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1");
+const isSchemaObject = (node) => typeof node === "object" && node !== null && !Array.isArray(node);
+const graftMap = (source, target, path, depth) => {
+	if (!isSchemaObject(source) || !isSchemaObject(target)) return target;
+	const out = { ...target };
+	for (const [name, subschema] of Object.entries(source)) if (Object.hasOwn(target, name)) out[name] = graft(subschema, target[name], `${path}/${escapePointerSegment(name)}`, depth + 1);
+	return out;
+};
+const graftArray = (source, target, path, depth) => {
+	if (!Array.isArray(source) || !Array.isArray(target)) return target;
+	return target.map((element, index) => index < source.length ? graft(source[index], element, `${path}/${index}`, depth + 1) : element);
+};
+const graft = (source, target, path, depth) => {
+	if (depth >= 256) throw new CarryFailure(CarrierDepthExceededError.make({
+		path,
+		maxDepth: 256
+	}));
+	if (!isSchemaObject(source) || !isSchemaObject(target)) return target;
+	const out = { ...target };
+	for (const [key, value] of Object.entries(source)) {
+		if (KeywordFamilies.isDeclared(key)) {
+			out[key] = value;
+			continue;
+		}
+		const keyPath = `${path}/${escapePointerSegment(key)}`;
+		switch (key) {
+			case "properties":
+			case "patternProperties":
+				if (Object.hasOwn(out, key)) out[key] = graftMap(value, out[key], keyPath, depth);
+				break;
+			case "additionalProperties":
+			case "propertyNames":
+				if (Object.hasOwn(out, key)) out[key] = graft(value, out[key], keyPath, depth + 1);
+				break;
+			case "allOf":
+			case "anyOf":
+			case "oneOf":
+				if (Object.hasOwn(out, key)) out[key] = graftArray(value, out[key], keyPath, depth);
+				break;
+			case "prefixItems":
+				if (Object.hasOwn(out, "items")) out.items = Array.isArray(value) ? graftArray(value, out.items, `${path}/items`, depth) : graft(value, out.items, `${path}/items`, depth + 1);
+				break;
+			case "items": if (Object.hasOwn(source, "prefixItems")) {
+				if (Object.hasOwn(out, "additionalItems")) out.additionalItems = graft(value, out.additionalItems, `${path}/additionalItems`, depth + 1);
+			} else if (Object.hasOwn(out, "items")) out.items = graft(value, out.items, keyPath, depth + 1);
+		}
+	}
+	return out;
+};
+/**
+* Re-grafts the declared non-standard keyword families
+* ({@link KeywordFamilies}) from a Draft 2020-12 schema node onto its
+* lowered Draft-07 counterpart.
+*
+* Why this exists: annotation keys admitted into the Draft 2020-12 document
+* (core's `includeAnnotationKey`) are **dropped by core's Draft-07 lowering**,
+* whose keyword walk copies a fixed subset — verified against the installed
+* beta. Carrying `x-taplo`, `x-tombi-*`, `x-intellij-*` or the vscode set
+* into an emitted SchemaStore document therefore requires this post-lowering
+* step; it cannot ride `ToJsonSchemaOptions` alone.
+*
+* The walk mirrors the lowering's own structural rules, so every carrier
+* lands on the node the annotation was attached to — including the one
+* coordinate move the lowering makes (2020-12 `prefixItems[i]` → Draft-07
+* `items[i]`, trailing `items` → `additionalItems`). Only declared-family
+* keys are copied; nothing else about the target changes.
+*
+* `StoreDocument.fromSchema` applies this automatically to the root schema
+* and every `$defs` pool entry — annotate a schema node
+* (`Schema.String.annotate({ "x-taplo": { hidden: true } })`) and the key
+* appears in the built document. Call this directly only when driving core's
+* pipeline yourself.
+*
+* Know the boundary (core behavior, probed at the installed beta): an
+* annotation must sit on the schema **definition** node. Annotating a
+* hoisted (identifier-carrying) schema at its *usage* site — e.g.
+* `Person.annotate({...})` inside a struct field — reaches neither the
+* `$ref` node nor the pool entry, even in the 2020-12 document, so there is
+* nothing to carry.
+*
+* @public
+*/
+var AnnotationCarriers = class AnnotationCarriers {
+	constructor() {}
+	/**
+	* Grafts declared-family keys from `source` (a Draft 2020-12 schema
+	* node) onto `target` (its lowered Draft-07 counterpart), returning a
+	* new node. Pure and synchronous — the primitive form;
+	* {@link AnnotationCarriers.carry} is the same walk behind a span.
+	*/
+	static carryResult(source, target) {
+		try {
+			return Result.succeed(graft(source, target, "", 0));
+		} catch (cause) {
+			if (cause instanceof CarryFailure) return Result.fail(cause.error);
+			throw cause;
+		}
+	}
+	/**
+	* Effect form of {@link AnnotationCarriers.carryResult}, adding only the
+	* `AnnotationCarriers.carry` span. Defined in terms of the `Result`
+	* primitive — synchronous callers can use that variant directly.
+	*/
+	static carry = Effect.fn("AnnotationCarriers.carry")((source, target) => Effect.fromResult(AnnotationCarriers.carryResult(source, target)));
+};
+
+//#endregion
+export { AnnotationCarriers, CarrierDepthExceededError };

package/CanonicalJson.js

@@ -0,0 +1,135 @@
+import { Effect, Result, Schema } from "effect";
+
+//#region src/CanonicalJson.ts
+/**
+* Indicates that a value reachable from the serialization input is not a
+* JSON value: `undefined`, a function, a symbol, a `bigint`, a non-finite
+* number, or an object that is neither an array nor a plain object.
+*
+* Raised by {@link CanonicalJson.serialize}. Unlike `JSON.stringify` — which
+* silently drops `undefined` members and rewrites `NaN`/`Infinity` to
+* `null` — canonical serialization refuses to alter the document, so every
+* non-JSON value is a typed failure carrying the path to fix.
+*
+* @public
+*/
+var NonJsonValueError = class extends Schema.TaggedErrorClass()("NonJsonValueError", {
+	/** JSON pointer to the offending value (`""` is the document root). */
+	path: Schema.String,
+	/** The `typeof`/structural description of the rejected value. */
+	found: Schema.String
+}) {
+	get message() {
+		return `Non-JSON value (${this.found}) at "${this.path}"`;
+	}
+};
+/**
+* Indicates that the serialization input nests deeper than the package's
+* hardening cap (256 levels), which also intercepts cyclic values before
+* they can recurse forever.
+*
+* Raised by {@link CanonicalJson.serialize}.
+*
+* @public
+*/
+var JsonDepthExceededError = class extends Schema.TaggedErrorClass()("JsonDepthExceededError", {
+	/** JSON pointer to the node where the cap was hit. */
+	path: Schema.String,
+	/** The nesting cap that was exceeded. */
+	maxDepth: Schema.Number
+}) {
+	get message() {
+		return `JSON nesting exceeds ${this.maxDepth} levels at "${this.path}"`;
+	}
+};
+var SerializeFailure = class {
+	error;
+	constructor(error) {
+		this.error = error;
+	}
+};
+const escapePointerSegment = (segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1");
+/**
+* Deterministic, canonical JSON text: the package's owned serializer, so a
+* consumer never shells out to an external formatter to produce a stable
+* committed schema file.
+*
+* The canonical form is fully specified: object keys in insertion order
+* (document assembly owns meaningful ordering — keys are never sorted),
+* every array element and object member on its own line, the configured
+* indent (tab by default), `"` string escaping exactly as `JSON.stringify`
+* produces it, LF line endings and a single trailing newline. Equal inputs
+* serialize to equal bytes.
+*
+* Values that are not JSON fail typed rather than being silently rewritten
+* (see {@link NonJsonValueError}); nesting past the hardening cap — which
+* includes cyclic values — fails with {@link JsonDepthExceededError}.
+*
+* @public
+*/
+var CanonicalJson = class CanonicalJson {
+	constructor() {}
+	/**
+	* Serializes `value` to canonical JSON text. Pure and synchronous — the
+	* primitive form; {@link CanonicalJson.serialize} is the same engine
+	* behind a span.
+	*/
+	static serializeResult(value, options) {
+		const unit = options?.indent === void 0 || options.indent === "tab" ? "	" : indentUnit(options.indent);
+		try {
+			return Result.succeed(`${emit(value, "", 0, unit)}\n`);
+		} catch (cause) {
+			if (cause instanceof SerializeFailure) return Result.fail(cause.error);
+			throw cause;
+		}
+	}
+	/**
+	* Effect form of {@link CanonicalJson.serializeResult}, adding only the
+	* `CanonicalJson.serialize` span. Defined in terms of the `Result`
+	* primitive — synchronous callers can use that variant directly.
+	*/
+	static serialize = Effect.fn("CanonicalJson.serialize")((value, options) => Effect.fromResult(CanonicalJson.serializeResult(value, options)));
+};
+const indentUnit = (indent) => {
+	if (!Number.isInteger(indent) || indent < 0) throw new Error(`indent must be "tab" or a non-negative integer space count, got ${indent}`);
+	return " ".repeat(indent);
+};
+const emit = (value, path, depth, unit) => {
+	if (value === null) return "null";
+	switch (typeof value) {
+		case "boolean": return value ? "true" : "false";
+		case "number":
+			if (!Number.isFinite(value)) throw new SerializeFailure(NonJsonValueError.make({
+				path,
+				found: String(value)
+			}));
+			return JSON.stringify(value);
+		case "string": return JSON.stringify(value);
+		case "object": break;
+		default: throw new SerializeFailure(NonJsonValueError.make({
+			path,
+			found: typeof value
+		}));
+	}
+	if (depth >= 256) throw new SerializeFailure(JsonDepthExceededError.make({
+		path,
+		maxDepth: 256
+	}));
+	const indent = unit.repeat(depth + 1);
+	const closing = unit.repeat(depth);
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		return `[\n${value.map((item, index) => `${indent}${emit(item, `${path}/${index}`, depth + 1, unit)}`).join(",\n")}\n${closing}]`;
+	}
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new SerializeFailure(NonJsonValueError.make({
+		path,
+		found: "non-plain object"
+	}));
+	const entries = Object.entries(value);
+	if (entries.length === 0) return "{}";
+	return `{\n${entries.map(([key, member]) => `${indent}${JSON.stringify(key)}: ${emit(member, `${path}/${escapePointerSegment(key)}`, depth + 1, unit)}`).join(",\n")}\n${closing}}`;
+};
+
+//#endregion
+export { CanonicalJson, JsonDepthExceededError, NonJsonValueError };

package/CatalogEntry.js

@@ -0,0 +1,127 @@
+import { SchemaVersioning } from "./SchemaVersioning.js";
+import { Schema } from "effect";
+
+//#region src/CatalogEntry.ts
+/**
+* A fileMatch hygiene finding: a value in a lint report, not an error —
+* SchemaStore reviewers reject entries over these, so surfacing them
+* locally is the point, but a warned entry is still a valid entry.
+*
+* @public
+*/
+var CatalogLintFinding = class extends Schema.Class("CatalogLintFinding")({
+	/** Which hygiene check fired. */
+	check: Schema.Literals(["GenericFileMatch", "ComplexFileMatch"]),
+	/** The `fileMatch` pattern the finding is about. */
+	pattern: Schema.String,
+	/** Human-readable explanation with the SchemaStore rationale. */
+	message: Schema.String
+}) {};
+const CONFIG_EXTENSIONS = /* @__PURE__ */ new Set([
+	"cfg",
+	"conf",
+	"env",
+	"ini",
+	"json",
+	"json5",
+	"jsonc",
+	"properties",
+	"toml",
+	"xml",
+	"yaml",
+	"yml"
+]);
+const GENERIC_BASENAMES = /* @__PURE__ */ new Set([
+	"conf",
+	"config",
+	"configuration",
+	"options",
+	"settings"
+]);
+const COMPLEX_GLOB = /[{}[\]]|[?*+@!]\(|^!/;
+const lintPattern = (pattern) => {
+	const findings = [];
+	const basename = pattern.slice(pattern.lastIndexOf("/") + 1);
+	const dot = basename.lastIndexOf(".");
+	const stem = dot === -1 ? basename : basename.slice(0, dot);
+	const extension = dot === -1 ? "" : basename.slice(dot + 1).toLowerCase();
+	if (stem === "*" && CONFIG_EXTENSIONS.has(extension)) findings.push(CatalogLintFinding.make({
+		check: "GenericFileMatch",
+		pattern,
+		message: `"${pattern}" claims every .${extension} file; SchemaStore rejects generic patterns — match the specific file name(s) the schema owns`
+	}));
+	else if (GENERIC_BASENAMES.has(stem.toLowerCase()) && CONFIG_EXTENSIONS.has(extension)) findings.push(CatalogLintFinding.make({
+		check: "GenericFileMatch",
+		pattern,
+		message: `"${pattern}" matches the generic name "${basename}", which other tools also use; SchemaStore rejects generic patterns — qualify it with a tool-specific name or directory`
+	}));
+	if (COMPLEX_GLOB.test(pattern)) findings.push(CatalogLintFinding.make({
+		check: "ComplexFileMatch",
+		pattern,
+		message: `"${pattern}" uses complex glob constructs; SchemaStore asks for simple patterns — expand alternations into multiple entries`
+	}));
+	return findings;
+};
+/**
+* A SchemaStore `catalog.json` entry: the class is the schema, so decoding
+* an existing entry and encoding one for submission are the same artifact.
+* `versions` is present only for versioned catalogs
+* ({@link SchemaVersioning.catalogUrls} assembles both modes).
+*
+* @public
+*/
+var CatalogEntry = class CatalogEntry extends Schema.Class("CatalogEntry")({
+	/** The schema's display name in the catalog. */
+	name: Schema.String,
+	/** The catalog description. */
+	description: Schema.String,
+	/** Glob patterns editors match files against. */
+	fileMatch: Schema.Array(Schema.String),
+	/** The schema URL — the unversioned file, or the latest version. */
+	url: Schema.String,
+	/**
+	* Versioned mode only: label → schema URL. Inserted ascending, but key
+	* order is not a contract — bare-major labels enumerate first (see
+	* `SchemaVersioning.catalogUrls`); derive ordering from the labels.
+	*/
+	versions: Schema.optionalKey(Schema.Record(Schema.String, Schema.String))
+}) {
+	/**
+	* Assembles an entry from a catalog identity plus
+	* {@link SchemaVersioning.catalogUrls}' inputs: pass `versions` for the
+	* versioned mode (the `versions` map and latest-pointing `url` are
+	* derived), omit it for the unversioned mode.
+	*/
+	static assemble(options) {
+		const urls = SchemaVersioning.catalogUrls({
+			baseUrl: options.baseUrl,
+			name: options.fileBaseName ?? options.name,
+			...options.versions !== void 0 ? { versions: options.versions } : {}
+		});
+		return CatalogEntry.make({
+			name: options.name,
+			description: options.description,
+			fileMatch: options.fileMatch,
+			url: urls.url,
+			...urls.versions !== void 0 ? { versions: urls.versions } : {}
+		});
+	}
+	/**
+	* The fileMatch hygiene lint over this entry's patterns — pure shape
+	* analysis (no glob engine): generic patterns SchemaStore rejects and
+	* complex constructs it asks contributors to expand.
+	*/
+	lint() {
+		return CatalogEntry.lintFileMatch(this.fileMatch);
+	}
+	/**
+	* {@link CatalogEntry.lint} over a bare pattern list, for callers
+	* checking patterns before an entry exists.
+	*/
+	static lintFileMatch(patterns) {
+		return patterns.flatMap(lintPattern);
+	}
+};
+
+//#endregion
+export { CatalogEntry, CatalogLintFinding };

package/DocumentLint.js

@@ -0,0 +1,201 @@
+import { KeywordFamilies } from "./KeywordFamilies.js";
+import { Schema } from "effect";
+
+//#region src/DocumentLint.ts
+/**
+* A structural lint finding over an assembled document: a value in a
+* report, never an error channel — a document with findings is still a
+* document, and the consumer decides what a finding gates.
+*
+* @public
+*/
+var DocumentLintFinding = class extends Schema.Class("DocumentLintFinding")({
+	/** Which check fired. */
+	check: Schema.Literals([
+		"UnresolvedRef",
+		"UnknownKeyword",
+		"DescriptionWithoutUrl",
+		"DepthExceeded"
+	]),
+	/** `"warning"` for structural defects, `"advisory"` for best practices. */
+	severity: Schema.Literals(["warning", "advisory"]),
+	/** JSON pointer into the flat document (`""` is the root schema). */
+	path: Schema.String,
+	/** Human-readable explanation. */
+	message: Schema.String
+}) {};
+const DRAFT_07_KEYWORDS = /* @__PURE__ */ new Set([
+	"$comment",
+	"$defs",
+	"$id",
+	"$ref",
+	"$schema",
+	"additionalItems",
+	"additionalProperties",
+	"allOf",
+	"anyOf",
+	"const",
+	"contains",
+	"contentEncoding",
+	"contentMediaType",
+	"default",
+	"definitions",
+	"dependencies",
+	"description",
+	"else",
+	"enum",
+	"examples",
+	"exclusiveMaximum",
+	"exclusiveMinimum",
+	"format",
+	"if",
+	"items",
+	"maxItems",
+	"maxLength",
+	"maxProperties",
+	"maximum",
+	"minItems",
+	"minLength",
+	"minProperties",
+	"minimum",
+	"multipleOf",
+	"not",
+	"oneOf",
+	"pattern",
+	"patternProperties",
+	"properties",
+	"propertyNames",
+	"readOnly",
+	"required",
+	"then",
+	"title",
+	"type",
+	"uniqueItems",
+	"writeOnly"
+]);
+const URL_LINE = /^https?:\/\/\S+$/;
+const escapePointerSegment = (segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1");
+const unescapePointerSegment = (segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~");
+const isSchemaObject = (node) => typeof node === "object" && node !== null && !Array.isArray(node);
+const checkRef = (value, path, context) => {
+	if (typeof value !== "string") return;
+	if (value === "#") return;
+	const match = /^#\/\$defs\/([^/]+)/.exec(value);
+	if (match !== null && Object.hasOwn(context.defs, unescapePointerSegment(match[1]))) return;
+	context.findings.push(DocumentLintFinding.make({
+		check: "UnresolvedRef",
+		severity: "warning",
+		path,
+		message: `$ref "${value}" does not resolve against the document's $defs pool`
+	}));
+};
+const lintSchema = (node, path, depth, context) => {
+	if (!isSchemaObject(node)) return;
+	if (depth >= 256) {
+		context.findings.push(DocumentLintFinding.make({
+			check: "DepthExceeded",
+			severity: "warning",
+			path,
+			message: `schema nests deeper than ${256} levels; lint did not descend further`
+		}));
+		return;
+	}
+	for (const [key, value] of Object.entries(node)) {
+		const keyPath = `${path}/${escapePointerSegment(key)}`;
+		if (!DRAFT_07_KEYWORDS.has(key) && !KeywordFamilies.isDeclared(key)) {
+			context.findings.push(DocumentLintFinding.make({
+				check: "UnknownKeyword",
+				severity: "warning",
+				path: keyPath,
+				message: `"${key}" is not a Draft-07 keyword or a declared non-standard family (x-taplo*, x-tombi-*, x-intellij-*, vscode); ajv strict mode rejects it`
+			}));
+			continue;
+		}
+		switch (key) {
+			case "$ref":
+				checkRef(value, keyPath, context);
+				break;
+			case "properties":
+			case "patternProperties":
+			case "$defs":
+			case "definitions":
+				if (isSchemaObject(value)) for (const [name, subschema] of Object.entries(value)) lintSchema(subschema, `${keyPath}/${escapePointerSegment(name)}`, depth + 1, context);
+				break;
+			case "dependencies":
+				if (isSchemaObject(value)) {
+					for (const [name, dependency] of Object.entries(value)) if (!Array.isArray(dependency)) lintSchema(dependency, `${keyPath}/${escapePointerSegment(name)}`, depth + 1, context);
+				}
+				break;
+			case "items":
+				if (Array.isArray(value)) value.forEach((subschema, index) => {
+					lintSchema(subschema, `${keyPath}/${index}`, depth + 1, context);
+				});
+				else lintSchema(value, keyPath, depth + 1, context);
+				break;
+			case "additionalItems":
+			case "additionalProperties":
+			case "propertyNames":
+			case "contains":
+			case "if":
+			case "then":
+			case "else":
+			case "not":
+				lintSchema(value, keyPath, depth + 1, context);
+				break;
+			case "allOf":
+			case "anyOf":
+			case "oneOf": if (Array.isArray(value)) value.forEach((subschema, index) => {
+				lintSchema(subschema, `${keyPath}/${index}`, depth + 1, context);
+			});
+		}
+	}
+};
+/**
+* Owned structural checks over an assembled {@link StoreDocument} — the
+* always-available half of the validation story (a real-engine gate like
+* ajv strict mode stays at the consumer's edge):
+*
+* - `UnresolvedRef` — every `$ref` resolves against the `$defs` pool
+*   (`#` self-refs allowed; anything else, including a surviving
+*   `#/definitions/...` pointer, is a warning).
+* - `UnknownKeyword` — no keyword outside Draft-07 plus the declared
+*   non-standard families ({@link KeywordFamilies}: `x-taplo*`, `x-tombi-*`,
+*   `x-intellij-*` and the vscode set), which ajv strict mode would reject.
+* - `DescriptionWithoutUrl` — advisory: SchemaStore's description
+*   convention ends the root description with a docs URL line.
+*
+* Tractable because the input is bounded `toJsonSchemaDocument` output;
+* this is not a general JSON Schema validator.
+*
+* @public
+*/
+var DocumentLint = class {
+	constructor() {}
+	/**
+	* Runs every check; total — hostile nesting degrades to a
+	* `DepthExceeded` finding rather than an error.
+	*/
+	static lint(document) {
+		const context = {
+			defs: document.defs,
+			findings: []
+		};
+		lintSchema(document.root, "", 0, context);
+		for (const [name, definition] of Object.entries(document.defs)) lintSchema(definition, `/$defs/${escapePointerSegment(name)}`, 1, context);
+		const description = document.root.description;
+		if (typeof description === "string") {
+			const lines = description.split("\n");
+			const last = lines[lines.length - 1] ?? "";
+			if (!URL_LINE.test(last.trim())) context.findings.push(DocumentLintFinding.make({
+				check: "DescriptionWithoutUrl",
+				severity: "advisory",
+				path: "/description",
+				message: "SchemaStore's description convention ends with a documentation URL on its own line (<description>\\n<docs-url>)"
+			}));
+		}
+		return context.findings;
+	}
+};
+
+//#endregion
+export { DocumentLint, DocumentLintFinding };

package/KeywordFamilies.js

@@ -0,0 +1,51 @@
+//#region src/KeywordFamilies.ts
+/**
+* The one owner of the declared non-standard keyword families — the
+* language-server keyword sets SchemaStore's CONTRIBUTING enumerates as
+* legitimately consumed by editor toolchains, which ajv strict mode would
+* otherwise reject:
+*
+* - **vscode-json-languageservice** (exact names): `allowTrailingCommas`,
+*   `defaultSnippets`, `enumDescriptions`, `markdownDescription`,
+*   `markdownEnumDescriptions`.
+* - **taplo**: the `x-taplo` prefix (`x-taplo`, `x-taplo-info`, ...).
+* - **tombi**: the `x-tombi-` prefix (`x-tombi-toml-version`,
+*   `x-tombi-array-values-order`, `x-tombi-array-values-order-by`,
+*   `x-tombi-table-keys-order`, `x-tombi-string-formats`,
+*   `x-tombi-additional-key-label`).
+* - **IntelliJ**: the `x-intellij-` prefix (`x-intellij-language-injection`,
+*   `x-intellij-html-description`, `x-intellij-enum-metadata`).
+*
+* Both consumers of the registry route through {@link KeywordFamilies.isDeclared}:
+* `DocumentLint`'s `UnknownKeyword` check (a declared key is not flagged) and
+* `AnnotationCarriers` (only declared keys are re-grafted after the Draft-07
+* lowering). One predicate, so the lint and the carriers cannot drift.
+*/
+const VSCODE_KEYWORDS = /* @__PURE__ */ new Set([
+	"allowTrailingCommas",
+	"defaultSnippets",
+	"enumDescriptions",
+	"markdownDescription",
+	"markdownEnumDescriptions"
+]);
+/**
+* The declared non-standard keyword families as one predicate: the
+* vscode-json-languageservice set by exact name, plus the `x-taplo`,
+* `x-tombi-` and `x-intellij-` prefixes.
+*
+* @public
+*/
+var KeywordFamilies = class {
+	constructor() {}
+	/**
+	* Whether `key` belongs to a declared non-standard keyword family.
+	* Draft-07's own keywords are a separate vocabulary — this predicate
+	* answers only for the language-server extension families.
+	*/
+	static isDeclared(key) {
+		return VSCODE_KEYWORDS.has(key) || key.startsWith("x-taplo") || key.startsWith("x-tombi-") || key.startsWith("x-intellij-");
+	}
+};
+
+//#endregion
+export { KeywordFamilies };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.