AG-33771 Add config file schema generator

totadavid95 · totadavid95 · commit 14af24f53786 · 2025-11-27T13:46:28.000+03:00
Squashed commit of the following: commit 83a062c Merge: 520df1b 6561059 Author: scripthunter7 <d.tota@adguard.com> Date: Thu Nov 27 11:45:21 2025 +0100 Merge branch 'release/v4.0' into fix/AG-33771 commit 520df1b Merge: 9d67052 af7da8f Author: scripthunter7 <d.tota@adguard.com> Date: Thu Nov 27 10:58:30 2025 +0100 Merge branch 'release/v4.0' into fix/AG-33771 commit 9d67052 Author: scripthunter7 <d.tota@adguard.com> Date: Tue Nov 25 16:50:01 2025 +0100 refactor linterRuleTextSeveritySchema to use Object.keys() and add LinterRuleTextSeverity type - Added LinterRuleTextSeverity type as keyof typeof linterRuleSeverityMap - Modified linterRuleTextSeveritySchema to generate picklist from Object.keys(linterRuleSeverityMap) instead of hardcoded array - Updated normalizeSeverity() parameter type to use LinterRuleTextSeverity instead of string literals commit cd09c0a Merge: 4958c77 d122069 Author: scripthunter7 <d.tota@adguard.com> Date: Mon Nov 24 21:01:13 2025 +0100 Merge branch 'release/v4.0' into fix/AG-33771 commit 4958c77 Author: scripthunter7 <d.tota@adguard.com> Date: Mon Nov 24 20:15:31 2025 +0100 add unreleased section to changelog for JSON schema feature - Added Unreleased section with JSON schema for config files feature - Added link references for Unreleased comparison and issue #210 - Added missing version comparison link for 4.0.0-alpha.8 commit 0eb1c56 Author: scripthunter7 <d.tota@adguard.com> Date: Mon Nov 24 20:11:18 2025 +0100 add support for yaml config files and .aglintrc without extension in schema fileMatch patterns - Extended VS Code settings.json fileMatch array to include aglint.config.yaml, aglint.config.yml, .aglintrc, .aglintrc.yaml, and .aglintrc.yml - Enables JSON schema validation and autocomplete for YAML config files and extensionless .aglintrc files commit 4c7d224 Author: scripthunter7 <d.tota@adguard.com> Date: Mon Nov 24 20:09:09 2025 +0100 simplify schema descriptions to be more concise and remove redundant information about enum values and defaults - Shortened extends description to remove specific preset examples - Reduced syntax description to single line without listing all possible values or defaults - Simplified numeric and string severity descriptions to remove value enumerations - Updated schema/aglint-config.schema.json with matching simplified descriptions commit ae7c2ed Author: scripthunter7 <d.tota@adguard.com> Date: Mon Nov 24 20:07:10 2025 +0100 refactor config schema generator to use async fs/promises API instead of sync methods - Changed fs import to use mkdir and writeFile from node:fs/promises - Modified main() function to be async and return Promise<void> - Replaced fs.existsSync() and fs.mkdirSync() with await mkdir() using recursive option - Replaced fs.writeFileSync() with await writeFile() - Removed unnecessary existence check since mkdir with recursive handles it commit ba17ec7 Author: scripthunter7 <d.tota@adguard.com> Date: Mon Nov 24 20:05:41 2025 +0100 add descriptions to config file and rule schemas for better IDE autocomplete and documentation - Added description metadata to linterConfigFileSchema fields (root, extends, syntax, rules) - Added description metadata to rule severity schemas (numeric, text, and union variants) - Added description to linterRuleConfigSchema explaining severity and options format - Updated schema/aglint-config.schema.json with matching descriptions for all properties - Wrapped schema definitions in v.pipe() to attach commit e9cf033 Author: scripthunter7 <d.tota@adguard.com> Date: Mon Nov 24 19:55:58 2025 +0100 Add config file schema generator - Removed valibot transform from linterRuleTextSeveritySchema to keep it as picklist - Added normalizeSeverity() helper function to convert 'off'/'warn'/'error' strings to LinterRuleSeverity enum values - Added normalizeConfig() method to ConfigResolver to normalize rule severity values in configs - Modified ConfigResolver.resolveChain() to normalize merged config before returning - Modifie
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,15 @@ The format is based on [Keep a Changelog], and this project adheres to [Semantic
 [Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
 
+## [Unreleased]
+
+### Added
+
+- JSON schema for config files. [#210]
+
+[Unreleased]: https://github.com/AdguardTeam/AGLint/compare/v4.0.0-alpha.8...HEAD
+[#210]: https://github.com/AdguardTeam/AGLint/issues/210
+
 ## [4.0.0-alpha.8] - 2025-11-24
 
 ### Added
@@ -34,6 +43,8 @@ The format is based on [Keep a Changelog], and this project adheres to [Semantic
 
 - `getAglintRuleDocumentationUrl` from public exports.
 
+[4.0.0-alpha.8]: https://github.com/AdguardTeam/AGLint/compare/v4.0.0-alpha.7...v4.0.0-alpha.8
+
 
 ## [4.0.0-alpha.7] - 2025-11-19
 
diff --git a/package.json b/package.json
@@ -142,7 +142,8 @@
     "files": [
         "dist/**",
         "!dist/build.txt",
-        "config-presets/**"
+        "config-presets/**",
+        "schema/**"
     ],
     "engines": {
         "node": ">=20"
@@ -159,7 +160,8 @@
         "prepare": "node .husky/install.js",
         "increment": "pnpm version patch --no-git-tag-version",
         "test": "vitest",
-        "rules:update": "npx tsx tasks/generate-rule-exports.ts && npx tsx tasks/generate-rules-readme.ts && npx tsx tasks/generate-presets.ts"
+        "rules:update": "npx tsx tasks/generate-rule-exports.ts && npx tsx tasks/generate-rules-readme.ts && npx tsx tasks/generate-presets.ts",
+        "schema:generate": "npx tsx tasks/generate-config-schema.ts"
     },
     "devDependencies": {
         "@rollup/plugin-commonjs": "^25.0.2",
diff --git a/schema/README.md b/schema/README.md
@@ -0,0 +1,59 @@
+# AGLint JSON Schema
+
+This folder contains JSON Schema files for AGLint configuration files.
+
+## Files
+
+- **aglint-config.schema.json** - JSON Schema for AGLint configuration files (aglint.config.json, .aglintrc.json, etc.)
+
+## Usage
+
+### Visual Studio Code
+
+Add the schema to your configuration file to get autocompletion and validation:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/AdguardTeam/AGLint/main/schema/aglint-config.schema.json",
+  "rules": {
+    "no-short-rules": "error"
+  }
+}
+```
+
+Or configure it in your VS Code settings.json:
+
+```json
+{
+  "json.schemas": [
+    {
+      "fileMatch": [
+        "aglint.config.json",
+        "aglint.config.yaml",
+        "aglint.config.yml",
+        ".aglintrc",
+        ".aglintrc.json",
+        ".aglintrc.yaml",
+        ".aglintrc.yml"
+      ],
+      "url": "./node_modules/@adguard/aglint/schema/aglint-config.schema.json"
+    }
+  ]
+}
+```
+
+### Other IDEs
+
+Most modern IDEs support JSON Schema validation. Refer to your IDE's documentation for how to associate JSON files
+with schemas.
+
+## Generating the Schema
+
+The schema is automatically generated from the Valibot schema defined in the source code.
+To regenerate it:
+
+```bash
+pnpm schema:generate
+```
+
+This ensures the schema always stays in sync with the actual configuration validation logic.
diff --git a/schema/aglint-config.schema.json b/schema/aglint-config.schema.json
@@ -0,0 +1,92 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/AdguardTeam/AGLint/schema/aglint-config.schema.json",
+  "title": "AGLint Configuration",
+  "description": "AGLint configuration file schema for aglint.config.json, .aglintrc.json, or package.json",
+  "type": "object",
+  "properties": {
+    "root": {
+      "type": "boolean",
+      "default": false,
+      "description": "Indicates whether this configuration file is the root. When true, AGLint stops looking for configuration files in parent directories."
+    },
+    "extends": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "List of configuration files or presets to extend from. Configurations are merged with later entries overriding earlier ones. Presets can be referenced with the \"aglint:\" prefix."
+    },
+    "syntax": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "Common",
+          "AdblockPlus",
+          "UblockOrigin",
+          "AdGuard"
+        ]
+      },
+      "description": "AdBlock syntax variants to support"
+    },
+    "rules": {
+      "type": "object",
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "anyOf": [
+              {
+                "enum": [
+                  0,
+                  1,
+                  2
+                ],
+                "description": "Rule severity as numeric value"
+              },
+              {
+                "enum": [
+                  "off",
+                  "warn",
+                  "error"
+                ],
+                "description": "Rule severity as string"
+              }
+            ],
+            "description": "Rule severity level controlling whether the rule is disabled, reports warnings, or reports errors"
+          },
+          {
+            "type": "array",
+            "items": [
+              {
+                "anyOf": [
+                  {
+                    "enum": [
+                      0,
+                      1,
+                      2
+                    ],
+                    "description": "Rule severity as numeric value"
+                  },
+                  {
+                    "enum": [
+                      "off",
+                      "warn",
+                      "error"
+                    ],
+                    "description": "Rule severity as string"
+                  }
+                ],
+                "description": "Rule severity level controlling whether the rule is disabled, reports warnings, or reports errors"
+              }
+            ],
+            "minItems": 1
+          }
+        ],
+        "description": "Rule configuration: either a severity level alone, or an array with severity and additional options"
+      },
+      "description": "Rule configurations as key-value pairs where keys are rule names and values are severity levels or arrays with severity and options."
+    }
+  },
+  "required": []
+}
diff --git a/src/cli/config-file/config-file.ts b/src/cli/config-file/config-file.ts
@@ -44,12 +44,36 @@ export enum LinterConfigFileFormat {
     PackageJson = 'package.json',
 }
 
-export const linterConfigFileSchema = v.object({
-    root: v.optional(v.boolean(), false),
-    extends: v.optional(v.array(v.pipe(v.string(), v.minLength(1)))),
-    syntax: v.optional(syntaxArraySchema),
-    rules: v.optional(linterRulesConfigSchema),
-});
+export const linterConfigFileSchema = v.pipe(
+    v.object({
+        root: v.pipe(
+            v.optional(v.boolean(), false),
+            v.description(
+                'Indicates whether this configuration file is the root. When true, AGLint stops looking for '
+                + 'configuration files in parent directories.',
+            ),
+        ),
+        extends: v.pipe(
+            v.optional(v.array(v.pipe(v.string(), v.minLength(1)))),
+            v.description(
+                'List of configuration files or presets to extend from. Configurations are merged with later '
+                + 'entries overriding earlier ones. Presets can be referenced with the "aglint:" prefix.',
+            ),
+        ),
+        syntax: v.pipe(
+            v.optional(syntaxArraySchema),
+            v.description('AdBlock syntax variants to support'),
+        ),
+        rules: v.pipe(
+            v.optional(linterRulesConfigSchema),
+            v.description(
+                'Rule configurations as key-value pairs where keys are rule names and values are severity '
+                + 'levels or arrays with severity and options.',
+            ),
+        ),
+    }),
+    v.description('AGLint configuration file schema for aglint.config.json, .aglintrc.json, or package.json'),
+);
 
 export type LinterConfigFile = v.InferInput<typeof linterConfigFileSchema>;
 
diff --git a/src/cli/utils/config-resolver/config-resolver.ts b/src/cli/utils/config-resolver/config-resolver.ts
@@ -2,6 +2,7 @@ import * as v from 'valibot';
 import { parse as parseYaml } from 'yaml';
 
 import { type LinterConfig } from '../../../linter/config';
+import { normalizeSeverity } from '../../../linter/rule';
 import { type ModuleDebug } from '../../../utils/debug';
 import { deepMerge } from '../../../utils/deep-merge';
 import {
@@ -156,7 +157,7 @@ export class ConfigResolver {
         if (this.debug) {
             this.debug.log(`Final merged config: ${JSON.stringify(merged)}`);
         }
-        return merged;
+        return ConfigResolver.normalizeConfig(merged);
     }
 
     /**
@@ -270,9 +271,12 @@ export class ConfigResolver {
             this.debug.log(`Flattened config for ${absPath}: ${JSON.stringify(flattened)}`);
         }
 
+        // Normalize severity values before caching
+        const normalized = ConfigResolver.normalizeConfig(flattened);
+
         // Cache result
         const entry: ConfigCacheEntry = {
-            config: flattened,
+            config: normalized,
             isRoot: parsed.root === true,
             timestamp: Date.now(),
         };
@@ -283,6 +287,39 @@ export class ConfigResolver {
         return entry;
     }
 
+    /**
+     * Normalizes rule severity values from strings to enum values.
+     *
+     * @param config The config to normalize.
+     *
+     * @returns The normalized config.
+     */
+    private static normalizeConfig(config: LinterConfig): LinterConfig {
+        if (!config.rules) {
+            return config;
+        }
+
+        const normalizedRules: typeof config.rules = {};
+
+        for (const [ruleName, ruleConfig] of Object.entries(config.rules)) {
+            if (Array.isArray(ruleConfig)) {
+                // Tuple format: [severity, ...options]
+                normalizedRules[ruleName] = [
+                    normalizeSeverity(ruleConfig[0]),
+                    ...ruleConfig.slice(1),
+                ] as any;
+            } else {
+                // Single severity
+                normalizedRules[ruleName] = normalizeSeverity(ruleConfig);
+            }
+        }
+
+        return {
+            ...config,
+            rules: normalizedRules,
+        };
+    }
+
     /**
      * Parses config file content.
      *
diff --git a/src/linter/rule-registry/rule-instance.ts b/src/linter/rule-registry/rule-instance.ts
@@ -19,6 +19,7 @@ import {
     type LinterRuleSeverity,
     type LinterRuleType,
     type LinterRuleVisitors,
+    normalizeSeverity,
     type WithMessages,
 } from '../rule';
 
@@ -201,7 +202,7 @@ export class LinterRuleInstance {
             // [severity[, ...config]] case
 
             // eslint-disable-next-line prefer-destructuring
-            this.severity = parsedConfig[0];
+            this.severity = normalizeSeverity(parsedConfig[0]);
 
             // If there are more than one element in the array, it means that there are additional config options
             // In this case we need to validate them against the rule's config schema
@@ -232,7 +233,7 @@ export class LinterRuleInstance {
             }
         } else {
             // severity-only case
-            this.severity = parsedConfig;
+            this.severity = normalizeSeverity(parsedConfig);
 
             if (this.rule.meta.configSchema) {
                 this.config.length = 0;
diff --git a/src/linter/rule.ts b/src/linter/rule.ts
diff --git a/tasks/generate-config-schema.ts b/tasks/generate-config-schema.ts
diff --git a/test/cli/utils/config-resolver.test.ts b/test/cli/utils/config-resolver.test.ts
