[PATCH v1 01/10] kconfig-checker: Add schema for rule files

[Ahmed S. Darwish]

The kconfig-checker YAML rule files describes which kernel .config symbols
are expected to be enabled or disabled. Introduce a schema for such files.

Describe and add rational for each element in the schema as well.

Signed-off-by: Ahmed S. Darwish <darwi@xxxxxxxxxxxxx>
---
 tools/kconfig-checker/schema.yml | 115 +++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 tools/kconfig-checker/schema.yml

diff --git a/tools/kconfig-checker/schema.yml b/tools/kconfig-checker/schema.yml
new file mode 100644
index 000000000000..a7f1b0a78cc7
--- /dev/null
+++ b/tools/kconfig-checker/schema.yml
@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: GPL-2.0-only
+
+"$schema": "https://json-schema.org/draft-07/schema";
+
+title: Schema for kconfig-checker rule files
+type: object
+required: [rules]
+additionalProperties: false
+
+properties:
+  #
+  # Optional base URL for the documentation page used by rationale
+  # links.  See `docs_hint`.
+  #
+  docs_url:
+    type: string
+    format: uri
+
+  rules:
+    type: array
+    minItems: 1
+    items:
+      type: object
+      oneOf:
+        - required: [name]
+        - required: [name_pattern]
+      required: [expected, severity]
+      additionalProperties: false
+
+      properties:
+        #
+        # Exact kernel configuration symbol to check.
+        #
+        # Example: CONFIG_PREEMPT_RT
+        #
+        name:
+          type: string
+          pattern: '^CONFIG_[A-Z0-9_]+$'
+
+        #
+        # Regex matching one or more kernel configuration symbols.
+        #
+        # Example: CONFIG_DEBUG_.*
+        #
+        name_pattern:
+          type: string
+          format: regex
+
+        #
+        # Expected value for the matching kernel configuration option.
+        #
+        # Values:
+        #
+        #   y        option is expected to be enabled (built-in or module).
+        #   n        option is expected to be disabled or unset.
+        #   allowed  option is permitted and must not be reported as a violation.
+        #            This is used to exempt a specific symbol from a broader
+        #            `name_pattern` rule  with `expected: n`.
+        #
+        expected:
+          type: string
+          enum: [y, n, allowed]
+
+        #
+        # Issue severity to report when the configuration rule is not met.
+        #
+        # Higher severities should be reserved for rules affecting correctness.
+        #
+        severity:
+          type: string
+          enum: [fatal, high, medium, low, info]
+
+        #
+        # Optional documentation anchor for this rule.
+        #
+        # The rationale URL is built from `docs_url` plus an HTML fragment
+        # identifier.
+        #
+        # If `docs_hint` is set to `config`, then the HTML fragment id is
+        # derived from the kernel configuration symbol name:
+        #
+        #   CONFIG_DRM  ->  #config-drm
+        #
+        # For example, with below docs_url:
+        #
+        #   https://docs.kernel.org/core-api/real-time/kernel-configuration.html
+        #
+        # and the symbol entry:
+        #
+        #   - name: CONFIG_DRM
+        #     expected: n
+        #     severity: info
+        #     docs_hint: config
+        #
+        # the rationale URL becomes:
+        #
+        #   https://docs.kernel.org/core-api/real-time/kernel-configuration.html#config-drm
+        #
+        # If `docs_hint` is any other string, that string is used directly as
+        # the HTML fragment identifier.
+        #
+        docs_hint:
+          type: string
+          anyOf:
+            - const: config
+            - pattern: '^\S+$'   # URI fragments cannot have spaces
+
+        #
+        # Optional human-readable explanation for the rule.
+        #
+        # This text should explain why the option is expected to have the given
+        # value, and may span multiple lines.
+        #
+        rationale:
+          type: string
-- 
2.56.0