@cldmv/eslint-plugin-jsonv 1.0.12 → 1.0.13

package/dist/index.mjs

@@ -12,7 +12,8 @@
  * - Reports parse errors with accurate source locations
  * - Supports all ES2011-2025 features (JSON5, binary/octal literals, BigInt, numeric separators, etc.)
  * - Detects internal reference errors (circular refs, undefined refs)
- * - Configurable year-based feature detection
+ * - Configurable language options: target ES year, parse mode, strict BigInt and octal checks,
+ *   and internal reference resolution
  * - Exposes a positioned AST (objects, arrays, properties, literals, references, templates),
  *   comments and tokens, so rules can select nodes and inline `eslint-disable` comments work
  *
@@ -38,6 +39,254 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+//-----------------------------------------------------------------------------
+// Types
+//
+// The language, its SourceCode and the plugin are typed against @eslint/core's
+// generics (`Language`, `TextSourceCode`, `OkParseResult`, `Plugin`, ...), the same
+// way @eslint/json types its JSON language. `tsc -p .configs/tsconfig.types.json`
+// type-checks this JSDoc (`checkJs`) and emits it as `dist/index.d.mts`.
+//-----------------------------------------------------------------------------
+
+/**
+ * @import { ConfigObject, File, FileError, FileProblem, Language, OkParseResult, ParseResult, Plugin, RulesConfig, RuleVisitor, SourceLocation, SourceRange } from "@eslint/core";
+ * @import { CustomRuleDefinitionType, CustomRuleTypeDefinitions, CustomRuleVisitorWithExit, DirectiveType } from "@eslint/plugin-kit";
+ * @import { AstResult, SourceLocation as JsonvParserLocation, TokenType } from "@cldmv/jsonv/parser";
+ */
+
+/**
+ * The ES years the `year` language option accepts, matching @cldmv/jsonv's `ParseOptions["year"]`.
+ *
+ * @public
+ * @typedef {2011 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025} JsonvYear
+ */
+
+/**
+ * The parse modes the `mode` language option accepts, matching @cldmv/jsonv's `ParseOptions["mode"]`:
+ * `"jsonv"` (every jsonv feature of the selected year), `"json5"` (JSON5 only) or `"json"` (strict JSON).
+ *
+ * @public
+ * @typedef {"jsonv" | "json5" | "json"} JsonvMode
+ */
+
+/**
+ * Language options for `language: "jsonv/jsonv"`. Each one is forwarded to @cldmv/jsonv's
+ * `parseWithOptions()` and `parseToAst()`. Any other key is rejected by `validateLanguageOptions`,
+ * so the type is closed.
+ *
+ * @public
+ * @typedef {object} JsonvLanguageOptions
+ * @property {JsonvYear} [year] The ES year whose jsonv features are allowed. Defaults to `2025`.
+ * @property {JsonvMode} [mode] The parse mode. Defaults to `"jsonv"`.
+ * @property {boolean} [strictBigInt] When `true`, an integer outside the safe range without an `n` suffix is an error instead of
+ *   being converted to a BigInt. Defaults to `false`.
+ * @property {boolean} [strictOctal] When `true`, a legacy octal literal such as `0755` is an error (`0o755` is still allowed).
+ *   Defaults to `false`.
+ * @property {boolean} [allowInternalReferences] When `false`, internal references are left unresolved, so an undefined or
+ *   circular reference is no longer reported. Defaults to `true`.
+ */
+
+/**
+ * A `Literal`: string, number, BigInt, boolean, `null`, `Infinity` or `NaN`, with its source text in `raw`.
+ *
+ * @public
+ * @typedef {object} JsonvLiteral
+ * @property {"Literal"} type The node type.
+ * @property {string | number | bigint | boolean | null} value The evaluated value.
+ * @property {string} raw The source text.
+ * @property {string} [bigint] The BigInt digits, for a BigInt literal.
+ * @property {SourceLocation} loc The location (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets.
+ */
+
+/**
+ * An `Identifier`: an unquoted key, or an internal reference such as `backup: port`.
+ *
+ * @public
+ * @typedef {object} JsonvIdentifier
+ * @property {"Identifier"} type The node type.
+ * @property {string} name The identifier text.
+ * @property {SourceLocation} loc The location (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets.
+ */
+
+/**
+ * An `ObjectExpression`: `{ ... }`.
+ *
+ * @public
+ * @typedef {object} JsonvObjectExpression
+ * @property {"ObjectExpression"} type The node type.
+ * @property {JsonvProperty[]} properties The properties, in source order.
+ * @property {SourceLocation} loc The location (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets.
+ */
+
+/**
+ * A `Property`: `key: value`. The key is a `Literal` (quoted or numeric key) or an `Identifier` (unquoted key).
+ *
+ * @public
+ * @typedef {object} JsonvProperty
+ * @property {"Property"} type The node type.
+ * @property {JsonvLiteral | JsonvIdentifier} key The key.
+ * @property {JsonvExpression} value The value.
+ * @property {boolean} computed Always `false` in jsonv.
+ * @property {SourceLocation} loc The location (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets.
+ */
+
+/**
+ * An `ArrayExpression`: `[ ... ]`.
+ *
+ * @public
+ * @typedef {object} JsonvArrayExpression
+ * @property {"ArrayExpression"} type The node type.
+ * @property {JsonvExpression[]} elements The elements, in source order.
+ * @property {SourceLocation} loc The location (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets.
+ */
+
+/**
+ * A `MemberExpression`: a dotted internal reference such as `server.port`.
+ *
+ * @public
+ * @typedef {object} JsonvMemberExpression
+ * @property {"MemberExpression"} type The node type.
+ * @property {JsonvExpression} object The object being accessed.
+ * @property {JsonvIdentifier} property The accessed property.
+ * @property {false} computed Always `false`.
+ * @property {SourceLocation} loc The location (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets.
+ */
+
+/**
+ * A `TemplateElement`: one string segment of a template literal.
+ *
+ * @public
+ * @typedef {object} JsonvTemplateElement
+ * @property {"TemplateElement"} type The node type.
+ * @property {{raw: string, cooked: string}} value The raw and cooked segment text.
+ * @property {boolean} tail Whether this is the last segment.
+ * @property {SourceLocation} loc The location (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets.
+ */
+
+/**
+ * A `TemplateLiteral`: a backtick string and its `${...}` interpolations.
+ *
+ * @public
+ * @typedef {object} JsonvTemplateLiteral
+ * @property {"TemplateLiteral"} type The node type.
+ * @property {JsonvTemplateElement[]} quasis The string segments.
+ * @property {JsonvExpression[]} expressions The interpolated expressions.
+ * @property {SourceLocation} loc The location (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets.
+ */
+
+/**
+ * Any value node.
+ *
+ * @public
+ * @typedef {JsonvLiteral | JsonvObjectExpression | JsonvArrayExpression | JsonvIdentifier | JsonvTemplateLiteral | JsonvMemberExpression} JsonvExpression
+ */
+
+/**
+ * A `Line` (`// ...`) or `Block` (`/* ... *\/`) comment. `value` excludes the delimiters; `loc` and `range` include them.
+ *
+ * @public
+ * @typedef {object} JsonvComment
+ * @property {"Line" | "Block"} type The comment kind.
+ * @property {string} value The comment text without its delimiters.
+ * @property {SourceLocation} loc The location (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets.
+ */
+
+/**
+ * A token (comments and the end-of-file token are not included).
+ *
+ * @public
+ * @typedef {object} JsonvToken
+ * @property {`${TokenType}`} type The token type, e.g. `"{"`, `"String"`, `"Identifier"`, `"TemplateHead"`.
+ * @property {string | number | bigint | boolean | null} value The token's value.
+ * @property {string} raw The source text.
+ * @property {SourceLocation} loc The location (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets.
+ */
+
+/**
+ * The `Program` root: `body` is the root value; `comments` and `tokens` are in source order.
+ *
+ * @public
+ * @typedef {object} JsonvProgram
+ * @property {"Program"} type The node type.
+ * @property {JsonvExpression} body The root value.
+ * @property {JsonvComment[]} comments The comments.
+ * @property {JsonvToken[]} tokens The tokens, excluding comments.
+ * @property {SourceLocation} loc The location of the whole document (1-based lines and columns).
+ * @property {SourceRange} range The `[start, end)` source offsets of the whole document.
+ */
+
+/**
+ * Any AST node.
+ *
+ * @public
+ * @typedef {JsonvProgram | JsonvExpression | JsonvProperty | JsonvTemplateElement} JsonvNode
+ */
+
+/**
+ * Anything with a location: a node, a token or a comment.
+ *
+ * @public
+ * @typedef {JsonvNode | JsonvToken | JsonvComment} JsonvSyntaxElement
+ */
+
+/**
+ * The jsonv language, typed with @eslint/core's `Language` generics.
+ *
+ * @public
+ * @typedef {Language<{LangOptions: JsonvLanguageOptions, Code: JsonvSourceCode, RootNode: JsonvProgram, Node: JsonvNode}>} JsonvLanguage
+ */
+
+/**
+ * A successful `parse()` result. Besides `ast` it carries `jsonvValue`, the evaluated document
+ * (references resolved).
+ *
+ * @public
+ * @typedef {OkParseResult<JsonvProgram>} JsonvOkParseResult
+ */
+
+/**
+ * A `parse()` result: {@link JsonvOkParseResult}, or a failure carrying `errors`.
+ *
+ * @public
+ * @typedef {ParseResult<JsonvProgram>} JsonvParseResult
+ */
+
+/**
+ * The visitor a jsonv rule returns: a handler per node type (plus `:exit` variants), each called
+ * with the node and its parent.
+ *
+ * @public
+ * @typedef {RuleVisitor & CustomRuleVisitorWithExit<{
+ *   Program?: (node: JsonvProgram) => void,
+ *   ObjectExpression?: (node: JsonvObjectExpression, parent?: JsonvNode) => void,
+ *   Property?: (node: JsonvProperty, parent?: JsonvObjectExpression) => void,
+ *   ArrayExpression?: (node: JsonvArrayExpression, parent?: JsonvNode) => void,
+ *   Literal?: (node: JsonvLiteral, parent?: JsonvNode) => void,
+ *   Identifier?: (node: JsonvIdentifier, parent?: JsonvNode) => void,
+ *   MemberExpression?: (node: JsonvMemberExpression, parent?: JsonvNode) => void,
+ *   TemplateLiteral?: (node: JsonvTemplateLiteral, parent?: JsonvNode) => void,
+ *   TemplateElement?: (node: JsonvTemplateElement, parent?: JsonvTemplateLiteral) => void
+ * }>} JsonvRuleVisitor
+ */
+
+/**
+ * A rule for jsonv files. `Options` sets `RuleOptions`, `MessageIds` and `ExtRuleDocs`.
+ *
+ * @public
+ * @template {Partial<CustomRuleTypeDefinitions>} [Options={}]
+ * @typedef {CustomRuleDefinitionType<{LangOptions: JsonvLanguageOptions, Code: JsonvSourceCode, Visitor: JsonvRuleVisitor, Node: JsonvNode}, Options>} JsonvRuleDefinition
+ */
+
 /**
  * Reads this package's own `name` and `version` from its `package.json`.
  *
@@ -61,14 +310,43 @@ function readPackageMeta() {
 }
 
 /**
- * Language options `jsonvLanguage#parse` reads from `context.languageOptions` and
- * forwards to `@cldmv/jsonv`'s `parseWithOptions`. Any other key is rejected by
- * `validateLanguageOptions` since it would silently do nothing.
+ * The default of every language option `jsonvLanguage#parse` reads from `context.languageOptions`
+ * and forwards to @cldmv/jsonv's `parseWithOptions()` and `parseToAst()`. The defaults are
+ * @cldmv/jsonv's own (`ParseOptions` in its `src/api-types.mts`), except `year`, which jsonv
+ * derives from the current date and the plugin pins to the latest supported year.
+ *
+ * @public
+ * @type {Readonly<Required<JsonvLanguageOptions>>}
+ */
+const DEFAULT_LANGUAGE_OPTIONS = Object.freeze({
+	year: 2025,
+	mode: "jsonv",
+	strictBigInt: false,
+	strictOctal: false,
+	allowInternalReferences: true
+});
+
+/**
+ * The language options the plugin accepts: exactly the keys of {@link DEFAULT_LANGUAGE_OPTIONS}.
+ * Any other key is rejected by `validateLanguageOptions`, since it would silently do nothing.
  *
  * @public
  * @type {Set<string>}
  */
-const SUPPORTED_LANGUAGE_OPTIONS = new Set(["year", "strictBigInt"]);
+const SUPPORTED_LANGUAGE_OPTIONS = new Set(Object.keys(DEFAULT_LANGUAGE_OPTIONS));
+
+/**
+ * @cldmv/jsonv parse options the plugin deliberately does not accept, each with the reason
+ * `validateLanguageOptions` gives when a config sets it.
+ *
+ * @public
+ * @type {Readonly<Record<string, string>>}
+ */
+const UNSUPPORTED_JSONV_OPTIONS = Object.freeze({
+	reviver: "a reviver only transforms the evaluated value, which linting does not use",
+	preserveComments: "the AST always carries the comments",
+	tolerant: "the plugin controls how parse errors are collected"
+});
 
 /**
  * Valid `year` language option values, matching @cldmv/jsonv's `ParseOptions["year"]`
@@ -79,6 +357,22 @@ const SUPPORTED_LANGUAGE_OPTIONS = new Set(["year", "strictBigInt"]);
  */
 const VALID_YEARS = new Set([2011, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025]);
 
+/**
+ * Valid `mode` language option values, matching @cldmv/jsonv's `ParseOptions["mode"]` union.
+ *
+ * @public
+ * @type {Set<string>}
+ */
+const VALID_MODES = new Set(["jsonv", "json5", "json"]);
+
+/**
+ * The language options that take a boolean.
+ *
+ * @public
+ * @type {ReadonlyArray<"strictBigInt" | "strictOctal" | "allowInternalReferences">}
+ */
+const BOOLEAN_LANGUAGE_OPTIONS = Object.freeze(["strictBigInt", "strictOctal", "allowInternalReferences"]);
+
 /**
  * Child keys of every node type in the AST `jsonvLanguage#parse` produces, in source order
  * where that is defined. The node types and their shapes come from @cldmv/jsonv's own AST
@@ -138,19 +432,26 @@ const commentParser = new ConfigCommentParser();
  * Tests whether a value is a positioned @cldmv/jsonv AST node.
  * @public
  * @param {unknown} value - Any property value of a node.
- * @returns {boolean} `true` for an object with a string `type` and a `loc`.
+ * @returns {value is {type: string, [key: string]: unknown}} `true` for an object with a string `type` and a `loc`.
  * @example
  * isJsonvNode({ type: "Literal", loc: { start: {}, end: {} } }); // true
  */
 function isJsonvNode(value) {
-	return value !== null && typeof value === "object" && typeof value.type === "string" && typeof value.loc === "object";
+	return (
+		value !== null &&
+		typeof value === "object" &&
+		"type" in value &&
+		typeof value.type === "string" &&
+		"loc" in value &&
+		typeof value.loc === "object"
+	);
 }
 
 /**
  * Returns the child keys to visit for a node: its entry in {@link VISITOR_KEYS}, or — for a
  * node type @cldmv/jsonv may add later — every key holding a node or an array of nodes.
  * @public
- * @param {Object} node - An AST node.
+ * @param {{type: string, [key: string]: unknown}} node - An AST node.
  * @returns {ReadonlyArray<string>} Child property names.
  * @example
  * getChildKeys({ type: "Property", key, value }); // ["key", "value"]
@@ -170,8 +471,8 @@ function getChildKeys(node) {
  * ESLint `loc`/`range` pair for this language. The language declares `lineStart: 1` and
  * `columnStart: 1`, so columns are shifted to 1-based; `range` comes from the offsets.
  * @public
- * @param {{start: {line: number, column: number, offset: number}, end: {line: number, column: number, offset: number}}} loc - A jsonv location.
- * @returns {{loc: {start: {line: number, column: number}, end: {line: number, column: number}}, range: [number, number]}} The ESLint location and range.
+ * @param {JsonvParserLocation} loc - A jsonv location.
+ * @returns {{loc: SourceLocation, range: SourceRange}} The ESLint location and range.
  * @example
  * toEslintPosition({ start: { line: 1, column: 0, offset: 0 }, end: { line: 1, column: 3, offset: 3 } });
  * // { loc: { start: { line: 1, column: 1 }, end: { line: 1, column: 4 } }, range: [0, 3] }
@@ -191,28 +492,36 @@ function toEslintPosition(loc) {
  * Tokens are never walked for children: some token types share a name with a node type
  * (`Identifier`, `TemplateLiteral`) but carry no child nodes.
  * @public
- * @param {Object} element - A jsonv comment or token.
- * @returns {Object} The converted copy.
+ * @template {{loc: JsonvParserLocation}} T
+ * @param {T} element - A jsonv comment or token.
+ * @returns {{[K in keyof T]: K extends "loc" ? SourceLocation : T[K]} & {range: SourceRange}} The converted copy.
  * @example
  * convertLeaf(parseToAst("// note\n1").comments[0]);
  */
 function convertLeaf(element) {
-	return { ...element, ...toEslintPosition(element.loc) };
+	// TypeScript types a spread of a generic as an intersection (`T & {loc, range}`), which keeps
+	// the jsonv `loc` type alongside the ESLint one; the cast states the actual replacement.
+	return /** @type {{[K in keyof T]: K extends "loc" ? SourceLocation : T[K]} & {range: SourceRange}} */ ({
+		...element,
+		...toEslintPosition(element.loc)
+	});
 }
 
 /**
  * Deep-copies a jsonv AST node with ESLint positions: every node gets a 1-based `loc` and a
  * `range`, and child nodes are converted recursively.
  * @public
- * @param {Object} node - A jsonv AST node.
- * @returns {Object} The converted copy.
+ * @param {{type: string, loc: JsonvParserLocation, [key: string]: unknown}} node - A jsonv AST node.
+ * @returns {{type: string, [key: string]: unknown}} The converted copy.
  * @example
  * convertNode(parseToAst("{ a: 1 }").program.body);
  */
 function convertNode(node) {
+	/** @type {{type: string, [key: string]: unknown}} */
 	const converted = convertLeaf(node);
 	for (const key of getChildKeys(node)) {
-		const child = node[key];
+		// getChildKeys() only returns keys that hold a node or an array of nodes.
+		const child = /** @type {Parameters<typeof convertNode>[0] | Parameters<typeof convertNode>[0][]} */ (node[key]);
 		converted[key] = Array.isArray(child) ? child.map(convertNode) : convertNode(child);
 	}
 	return converted;
@@ -222,14 +531,19 @@ function convertNode(node) {
  * Builds the ESLint AST for a document from @cldmv/jsonv's `parseToAst()` result: the
  * `Program` root (whose `body` is the root value) with positioned `comments` and `tokens`.
  * @public
- * @param {{program: Object, comments: Object[], tokens: Object[]}} astResult - The `parseToAst()` result.
- * @returns {Object} The `Program` node.
+ * @param {AstResult} astResult - The `parseToAst()` result.
+ * @returns {JsonvProgram} The `Program` node.
  * @example
  * buildProgram(parseToAst("// note\n{ a: 1 }"));
  */
 function buildProgram({ program, comments, tokens }) {
+	// @cldmv/jsonv positions every node it produces (`ASTNode#loc` is only optional in its type), and
+	// convertNode() keeps each node's shape while swapping in ESLint positions, so the copy is a
+	// JsonvProgram. The generic, runtime-keyed walk cannot express that per node type, hence the casts.
+	const rawProgram = /** @type {Parameters<typeof convertNode>[0]} */ (/** @type {unknown} */ (program));
+	const root = /** @type {Omit<JsonvProgram, "comments" | "tokens">} */ (convertNode(rawProgram));
 	return {
-		...convertNode(program),
+		...root,
 		comments: comments.map(convertLeaf),
 		tokens: tokens.map(convertLeaf)
 	};
@@ -242,6 +556,7 @@ function buildProgram({ program, comments, tokens }) {
  * directives and `/* eslint rule: ... *\/` config comments).
  *
  * @public
+ * @extends {TextSourceCodeBase<{LangOptions: JsonvLanguageOptions, RootNode: JsonvProgram, SyntaxElementWithLoc: JsonvSyntaxElement, ConfigNode: JsonvComment}>}
  */
 class JsonvSourceCode extends TextSourceCodeBase {
 	/**
@@ -252,13 +567,13 @@ class JsonvSourceCode extends TextSourceCodeBase {
 
 	/**
 	 * Parent of every non-root node.
-	 * @type {WeakMap<Object, Object>}
+	 * @type {WeakMap<object, JsonvNode>}
 	 */
 	#parents = new WeakMap();
 
 	/**
 	 * Cached inline configuration comments.
-	 * @type {Object[]|undefined}
+	 * @type {JsonvComment[]|undefined}
 	 */
 	#inlineConfigComments;
 
@@ -266,13 +581,13 @@ class JsonvSourceCode extends TextSourceCodeBase {
 	 * Creates a SourceCode object.
 	 * @param {Object} options - Options.
 	 * @param {string} options.text - The source text.
-	 * @param {Object} options.ast - The `Program` node built by `jsonvLanguage#parse`.
+	 * @param {JsonvProgram} options.ast - The `Program` node built by `jsonvLanguage#parse`.
 	 */
 	constructor({ text, ast }) {
 		super({ text, ast, lineEndingPattern: LINE_ENDING_PATTERN });
-		/** @type {Object[]} Comments in source order. */
+		/** @type {JsonvComment[]} Comments in source order. */
 		this.comments = ast.comments;
-		/** @type {Object[]} Tokens in source order, excluding comments. */
+		/** @type {JsonvToken[]} Tokens in source order, excluding comments. */
 		this.tokens = ast.tokens;
 		/** @type {boolean} Whether the text starts with a byte order mark. */
 		this.hasBOM = text.charCodeAt(0) === 0xfeff;
@@ -293,12 +608,18 @@ class JsonvSourceCode extends TextSourceCodeBase {
 	 */
 	#ensureTraversal() {
 		if (!this.#steps) {
+			/** @type {VisitNodeStep[]} */
 			const steps = [];
+			/**
+			 * @param {JsonvNode} node - The node to visit.
+			 * @param {JsonvNode|undefined} parent - Its parent (`undefined` for the root).
+			 */
 			const visit = (node, parent) => {
 				if (parent) this.#parents.set(node, parent);
 				steps.push(new VisitNodeStep({ target: node, phase: 1, args: [node, parent] }));
 				for (const key of getChildKeys(node)) {
-					const child = node[key];
+					// getChildKeys() only returns keys that hold a node or an array of nodes.
+					const child = /** @type {JsonvNode | JsonvNode[]} */ (/** @type {{type: string, [key: string]: unknown}} */ (node)[key]);
 					for (const item of Array.isArray(child) ? child : [child]) visit(item, node);
 				}
 				steps.push(new VisitNodeStep({ target: node, phase: 2, args: [node, parent] }));
@@ -312,7 +633,7 @@ class JsonvSourceCode extends TextSourceCodeBase {
 	/**
 	 * Returns the enter/exit visit steps for every node, depth first in source order.
 	 * @public
-	 * @returns {Iterator<VisitNodeStep>} The traversal steps.
+	 * @returns {IterableIterator<VisitNodeStep>} The traversal steps.
 	 */
 	traverse() {
 		return this.#ensureTraversal().values();
@@ -321,8 +642,8 @@ class JsonvSourceCode extends TextSourceCodeBase {
 	/**
 	 * Returns the parent of a node, or `undefined` for the `Program` root.
 	 * @public
-	 * @param {Object} node - An AST node.
-	 * @returns {Object|undefined} The parent node.
+	 * @param {JsonvSyntaxElement} node - An AST node.
+	 * @returns {JsonvNode|undefined} The parent node.
 	 */
 	getParent(node) {
 		this.#ensureTraversal();
@@ -333,7 +654,7 @@ class JsonvSourceCode extends TextSourceCodeBase {
 	 * Returns the comments that hold inline configuration (`eslint`, `eslint-enable`,
 	 * `eslint-disable`, `eslint-disable-line`, `eslint-disable-next-line`).
 	 * @public
-	 * @returns {Object[]} The inline configuration comments.
+	 * @returns {JsonvComment[]} The inline configuration comments.
 	 */
 	getInlineConfigNodes() {
 		if (!this.#inlineConfigComments) {
@@ -346,14 +667,20 @@ class JsonvSourceCode extends TextSourceCodeBase {
 	 * Returns the `eslint-disable*` / `eslint-enable` directives, plus problems for malformed
 	 * ones (an `eslint-disable-line` spanning several lines).
 	 * @public
-	 * @returns {{problems: Object[], directives: Directive[]}} Directives and problems.
+	 * @returns {{problems: FileProblem[], directives: Directive[]}} Directives and problems.
 	 */
 	getDisableDirectives() {
+		/** @type {FileProblem[]} */
 		const problems = [];
+		/** @type {Directive[]} */
 		const directives = [];
 
 		for (const comment of this.getInlineConfigNodes()) {
-			const { label, value, justification } = commentParser.parseDirective(comment.value);
+			// parseDirective() returns undefined only for text that doesn't start with a directive label;
+			// every comment here matched INLINE_CONFIG, which requires one.
+			const { label, value, justification } = /** @type {NonNullable<ReturnType<ConfigCommentParser["parseDirective"]>>} */ (
+				commentParser.parseDirective(comment.value)
+			);
 
 			if (label === "eslint-disable-line" && comment.loc.start.line !== comment.loc.end.line) {
 				problems.push({ ruleId: null, message: `${label} comment should not span multiple lines.`, loc: comment.loc });
@@ -361,7 +688,10 @@ class JsonvSourceCode extends TextSourceCodeBase {
 			}
 
 			if (label !== "eslint") {
-				directives.push(new Directive({ type: label.slice("eslint-".length), node: comment, value, justification }));
+				// The comment matched INLINE_CONFIG, so any label other than "eslint" is an
+				// `eslint-disable*` / `eslint-enable` label, i.e. a DirectiveType once unprefixed.
+				const type = /** @type {DirectiveType} */ (label.slice("eslint-".length));
+				directives.push(new Directive({ type, node: comment, value, justification }));
 			}
 		}
 
@@ -372,14 +702,19 @@ class JsonvSourceCode extends TextSourceCodeBase {
 	 * Returns the rule configurations from `/* eslint rule: ... *\/` comments, plus problems for
 	 * ones that fail to parse.
 	 * @public
-	 * @returns {{problems: Object[], configs: Array<{config: {rules: Object}, loc: Object}>}} Configs and problems.
+	 * @returns {{problems: FileProblem[], configs: Array<{config: {rules: RulesConfig}, loc: SourceLocation}>}} Configs and problems.
 	 */
 	applyInlineConfig() {
+		/** @type {FileProblem[]} */
 		const problems = [];
+		/** @type {Array<{config: {rules: RulesConfig}, loc: SourceLocation}>} */
 		const configs = [];
 
 		for (const comment of this.getInlineConfigNodes()) {
-			const { label, value } = commentParser.parseDirective(comment.value);
+			// Defined for the same reason as in getDisableDirectives().
+			const { label, value } = /** @type {NonNullable<ReturnType<ConfigCommentParser["parseDirective"]>>} */ (
+				commentParser.parseDirective(comment.value)
+			);
 			if (label !== "eslint") continue;
 
 			const parseResult = commentParser.parseJSONLikeConfig(value);
@@ -398,7 +733,7 @@ class JsonvSourceCode extends TextSourceCodeBase {
  * Language definition for jsonv files
  *
  * @public
- * @type {Object}
+ * @type {JsonvLanguage}
  */
 const jsonvLanguage = {
 	/** File type - must be "text" for text-based languages */
@@ -409,28 +744,38 @@ const jsonvLanguage = {
 	columnStart: 1,
 	/** Property name for node types */
 	nodeTypeKey: "type",
-	/** Child keys of each AST node type, used for selector matching */
-	visitorKeys: VISITOR_KEYS,
+	/**
+	 * Child keys of each AST node type, used for selector matching. `Language#visitorKeys` is typed
+	 * with mutable arrays; ESLint only reads them, and VISITOR_KEYS stays frozen at runtime.
+	 */
+	visitorKeys: /** @type {Record<string, string[]>} */ (VISITOR_KEYS),
 
 	/**
 	 * Parse jsonv source code - ESLint Language API.
 	 *
 	 * The file is first parsed and evaluated with `parseWithOptions` — that is what reports
-	 * syntax errors, year-gated features, `strictBigInt` violations and unresolved/circular
-	 * internal references, each with its source position. A file that passes is then parsed
-	 * with `parseToAst` to build the positioned AST, comments and tokens ESLint traverses.
+	 * syntax errors, year-gated features, `mode`, `strictBigInt` and `strictOctal` violations
+	 * and unresolved/circular internal references (unless `allowInternalReferences` is `false`),
+	 * each with its source position. A file that passes is then parsed with `parseToAst` to
+	 * build the positioned AST, comments and tokens ESLint traverses. Both calls receive every
+	 * language option, with the defaults filled in.
 	 *
-	 * @param {Object} file - File object with body property containing source text
-	 * @param {Object} context - Context with languageOptions
-	 * @returns {Object} Parse result {ok, ast, jsonvValue} or {ok: false, errors}
+	 * @param {File} file - File object with body property containing source text
+	 * @param {{languageOptions: JsonvLanguageOptions}} context - Context with languageOptions
+	 * @returns {JsonvParseResult} Parse result {ok, ast, jsonvValue} or {ok: false, errors}
 	 */
 	parse(file, context) {
-		const text = file.body;
+		// `fileType: "text"` means ESLint reads the file as text, so `body` is a string.
+		const text = /** @type {string} */ (file.body);
+		/** @type {JsonvLanguageOptions} */
 		const options = context.languageOptions || {};
 		const parseOptions = {
-			year: options.year || 2025,
-			strictBigInt: options.strictBigInt !== undefined ? options.strictBigInt : false,
-			mode: "jsonv"
+			// `||`, not `??`: a falsy year (e.g. `0` from a direct `parse()` call) has always meant the default.
+			year: options.year || DEFAULT_LANGUAGE_OPTIONS.year,
+			mode: options.mode ?? DEFAULT_LANGUAGE_OPTIONS.mode,
+			strictBigInt: options.strictBigInt ?? DEFAULT_LANGUAGE_OPTIONS.strictBigInt,
+			strictOctal: options.strictOctal ?? DEFAULT_LANGUAGE_OPTIONS.strictOctal,
+			allowInternalReferences: options.allowInternalReferences ?? DEFAULT_LANGUAGE_OPTIONS.allowInternalReferences
 		};
 
 		try {
@@ -454,9 +799,18 @@ const jsonvLanguage = {
 			// nesting) has no position — fall back to line 1, column 1.
 			const hasPosition = error instanceof JsonvSyntaxError || error instanceof JsonvReferenceError;
 
+			// Everything the parser and buildProgram() throw is an Error instance (the RangeError
+			// above included), hence the cast in the fallback branch.
+			/** @type {FileError} */
 			const errorInfo = hasPosition
-				? { message: error.message, line: error.line, column: error.column + 1, endLine: error.loc.end.line, endColumn: error.loc.end.column + 1 }
-				: { message: error.message, line: 1, column: 1 };
+				? {
+						message: error.message,
+						line: error.line,
+						column: error.column + 1,
+						endLine: error.loc.end.line,
+						endColumn: error.loc.end.column + 1
+					}
+				: { message: /** @type {Error} */ (error).message, line: 1, column: 1 };
 
 			return {
 				ok: false,
@@ -469,8 +823,8 @@ const jsonvLanguage = {
 	 * Create the SourceCode object ESLint hands to rules
 	 *
 	 * @public
-	 * @param {Object} file - The file object
-	 * @param {Object} parseResult - The successful result from parse()
+	 * @param {File} file - The file object
+	 * @param {JsonvOkParseResult} parseResult - The successful result from parse()
 	 * @returns {JsonvSourceCode} SourceCode object
 	 */
 	createSourceCode(file, parseResult) {
@@ -485,16 +839,21 @@ const jsonvLanguage = {
 	 * reflects the effective options that will reach `parse()`.
 	 *
 	 * @public
-	 * @param {Object} languageOptions - The (already-merged) language options to validate
+	 * @param {JsonvLanguageOptions} languageOptions - The (already-merged) language options to validate
 	 * @returns {void}
 	 * @throws {TypeError} When an unsupported key is present, or a supported key holds an invalid value
 	 */
 	validateLanguageOptions(languageOptions) {
 		const options = languageOptions ?? {};
 
+		const supported = `Supported options are: ${[...SUPPORTED_LANGUAGE_OPTIONS].join(", ")}.`;
+
 		for (const key of Object.keys(options)) {
+			if (Object.hasOwn(UNSUPPORTED_JSONV_OPTIONS, key)) {
+				throw new TypeError(`Language option "${key}" is not supported: ${UNSUPPORTED_JSONV_OPTIONS[key]}. ${supported}`);
+			}
 			if (!SUPPORTED_LANGUAGE_OPTIONS.has(key)) {
-				throw new TypeError(`Unknown language option "${key}". Supported options are: ${[...SUPPORTED_LANGUAGE_OPTIONS].join(", ")}.`);
+				throw new TypeError(`Unknown language option "${key}". ${supported}`);
 			}
 		}
 
@@ -504,8 +863,16 @@ const jsonvLanguage = {
 			);
 		}
 
-		if (options.strictBigInt !== undefined && typeof options.strictBigInt !== "boolean") {
-			throw new TypeError(`Invalid "strictBigInt" language option: expected a boolean, got ${typeof options.strictBigInt}.`);
+		if (options.mode !== undefined && !VALID_MODES.has(options.mode)) {
+			throw new TypeError(
+				`Invalid "mode" language option: ${JSON.stringify(options.mode)}. Supported modes are: ${[...VALID_MODES].join(", ")}.`
+			);
+		}
+
+		for (const key of BOOLEAN_LANGUAGE_OPTIONS) {
+			if (options[key] !== undefined && typeof options[key] !== "boolean") {
+				throw new TypeError(`Invalid "${key}" language option: expected a boolean, got ${typeof options[key]}.`);
+			}
 		}
 	},
 
@@ -516,12 +883,9 @@ const jsonvLanguage = {
 	 * calling `validateLanguageOptions` and `parse()`.
 	 *
 	 * @public
-	 * @type {Object}
+	 * @type {JsonvLanguageOptions}
 	 */
-	defaultLanguageOptions: {
-		year: 2025,
-		strictBigInt: false
-	}
+	defaultLanguageOptions: { ...DEFAULT_LANGUAGE_OPTIONS }
 };
 
 /**
@@ -532,7 +896,7 @@ const jsonvLanguage = {
  * `language` such as `jsonv/jsonv` never consults it, so setting it here was inert.
  *
  * @public
- * @type {Object}
+ * @satisfies {ConfigObject}
  */
 const recommendedConfig = {
 	rules: {
@@ -542,10 +906,11 @@ const recommendedConfig = {
 };
 
 /**
- * ESLint plugin export
+ * ESLint plugin export. `@satisfies` checks it against @eslint/core's `Plugin` (which ESLint's
+ * own `ESLint.Plugin` is) while keeping its literal keys (`languages.jsonv`, `configs.recommended`).
  *
  * @public
- * @type {Object}
+ * @satisfies {Plugin}
  */
 const plugin = {
 	meta: readPackageMeta(),
@@ -566,3 +931,4 @@ const plugin = {
 };
 
 export default plugin;
+export { JsonvSourceCode };