fix: allow additional properties in CSSLanguageOptions (#538)

* fix: allow additional properties in `CSSLanguageOptions`

* wip

* wip

Author: lumirlumir

src/languages/css-language.js

@@ -25,23 +25,11 @@ import { visitorKeys } from "./css-visitor-keys.js";
 /**
  * @import { CssNodePlain, Comment, Lexer, StyleSheetPlain, SyntaxConfig } from "@eslint/css-tree"
  * @import { Language, OkParseResult, ParseResult, File, FileError } from "@eslint/core";
+ * @import { CSSLanguageOptions } from "../types.js";
  */
 
 /** @typedef {OkParseResult<StyleSheetPlain> & { comments: Comment[], lexer: Lexer }} CSSOkParseResult */
 /** @typedef {ParseResult<StyleSheetPlain>} CSSParseResult */
-/**
- * DefaultSyntaxConfig type representing the structure returned by `@eslint/css-tree/definition-syntax-data`.
- * This type is defined inline because it's not exported from the main `@eslint/css-tree` package.
- * @typedef {Pick<SyntaxConfig, "atrules" | "types" | "properties">} DefaultSyntaxConfig
- */
-/**
- * @typedef {(defaultSyntax: DefaultSyntaxConfig) => Partial<SyntaxConfig>} SyntaxExtensionCallback
- */
-/**
- * @typedef {Object} CSSLanguageOptions
- * @property {boolean} [tolerant] Whether to be tolerant of recoverable parsing errors.
- * @property {Partial<SyntaxConfig> | SyntaxExtensionCallback} [customSyntax] Custom syntax to use for parsing.
- */
 
 //-----------------------------------------------------------------------------
 // Helpers

src/languages/css-source-code.js

@@ -22,8 +22,7 @@ import { visitorKeys } from "./css-visitor-keys.js";
 /**
  * @import { CssNode, CssNodePlain, CssLocationRange, Comment, Lexer, StyleSheetPlain } from "@eslint/css-tree"
  * @import { SourceRange, FileProblem, DirectiveType, RulesConfig } from "@eslint/core"
- * @import { CSSSyntaxElement } from "../types.js"
- * @import { CSSLanguageOptions } from "./css-language.js"
+ * @import { CSSLanguageOptions, CSSSyntaxElement } from "../types.js"
  */
 
 //-----------------------------------------------------------------------------

src/types.ts

@@ -7,19 +7,52 @@
 // Imports
 //------------------------------------------------------------------------------
 
-import type { RuleVisitor } from "@eslint/core";
-import type { CssNodePlain, StyleSheetPlain } from "@eslint/css-tree";
+import type { LanguageOptions, RuleVisitor } from "@eslint/core";
+import type { DefaultSyntaxConfig as CSSTreeDefaultSyntaxConfig } from "@eslint/css-tree/definition-syntax-data";
+import type {
+	CssNodePlain,
+	StyleSheetPlain,
+	SyntaxConfig,
+} from "@eslint/css-tree";
 import type {
 	CustomRuleDefinitionType,
 	CustomRuleTypeDefinitions,
 	CustomRuleVisitorWithExit,
 } from "@eslint/plugin-kit";
-import type { CSSLanguageOptions, CSSSourceCode } from "./index.js";
+import type { CSSSourceCode } from "./index.js";
 
 //------------------------------------------------------------------------------
 // Types
 //------------------------------------------------------------------------------
 
+/**
+ * Default syntax configuration representing the structure returned by `@eslint/css-tree/definition-syntax-data`.
+ */
+export type DefaultSyntaxConfig = CSSTreeDefaultSyntaxConfig;
+
+/**
+ * A callback used to extend the default CSS syntax configuration.
+ */
+export type SyntaxExtensionCallback = (
+	defaultSyntax: DefaultSyntaxConfig,
+) => Partial<SyntaxConfig>;
+
+/**
+ * Language options provided for CSS files.
+ */
+export interface CSSLanguageOptions extends LanguageOptions {
+	/**
+	 * Whether to be tolerant of recoverable parsing errors.
+	 * @default false
+	 */
+	tolerant?: boolean;
+
+	/**
+	 * Custom syntax to use for parsing.
+	 */
+	customSyntax?: Partial<SyntaxConfig> | SyntaxExtensionCallback;
+}
+
 /**
  * A CSS syntax element, including nodes and comments.
  */

tests/types/types.test.ts

@@ -1,8 +1,11 @@
 import css from "@eslint/css";
 import type {
+	CSSLanguageOptions,
 	CSSRuleDefinition,
 	CSSRuleVisitor,
 	CSSSourceCode,
+	DefaultSyntaxConfig,
+	SyntaxExtensionCallback,
 } from "@eslint/css";
 import type { Plugin, SourceLocation, SourceRange } from "@eslint/core";
 import type { ESLint } from "eslint";
@@ -76,6 +79,74 @@ css.rules[ruleName] satisfies CSSRuleDefinition;
 // Check that `plugins` in the recommended config is defined:
 css.configs.recommended.plugins satisfies object;
 
+const validLanguageOptions1: CSSLanguageOptions = {};
+const validLanguageOptions2: CSSLanguageOptions = {
+	tolerant: true,
+};
+const validLanguageOptions3: CSSLanguageOptions = {
+	tolerant: false,
+};
+const validLanguageOptions4: CSSLanguageOptions = {
+	customSyntax: {
+		atrules: {},
+		properties: {},
+		types: {},
+	},
+};
+const validLanguageOptions5: CSSLanguageOptions = {
+	customSyntax: defaultSyntax => {
+		defaultSyntax satisfies DefaultSyntaxConfig;
+
+		return {
+			properties: {
+				foo: "<ident>",
+			},
+		};
+	},
+};
+const validLanguageOptions6: CSSLanguageOptions = {
+	tolerant: true,
+	unknownOption: "unknown",
+};
+
+const invalidLanguageOptions1: CSSLanguageOptions = {
+	// @ts-expect-error -- Invalid value for `tolerant`
+	tolerant: "true",
+};
+const invalidLanguageOptions2: CSSLanguageOptions = {
+	// @ts-expect-error -- Invalid value for `customSyntax`
+	customSyntax: "invalid",
+};
+
+const defaultSyntaxConfig: DefaultSyntaxConfig = {
+	atrules: {},
+	types: {},
+	properties: {},
+};
+
+// @ts-expect-error -- Default syntax configuration requires `properties`.
+const invalidDefaultSyntaxConfig: DefaultSyntaxConfig = {
+	atrules: {},
+	types: {},
+};
+
+const syntaxExtensionCallback: SyntaxExtensionCallback = defaultSyntax => {
+	defaultSyntax satisfies DefaultSyntaxConfig;
+
+	return {
+		properties: {
+			foo: "<ident>",
+		},
+	};
+};
+
+const invalidSyntaxExtensionCallback: SyntaxExtensionCallback = () => ({
+	properties: {
+		// @ts-expect-error -- CSS property syntax definitions must be strings.
+		foo: 1,
+	},
+});
+
 {
 	type RecommendedRuleName = keyof typeof css.configs.recommended.rules;
 	type RuleName = `css/${keyof typeof css.rules}`;