chore(scopes): split and sync configuration schema

This changes split the configuration codes and sync it from the engine.

This will allow to build a CI job to sync the ci/scopes/config/scopes.py file.

Change-Id: Ib976077362efebc9f3d1548e48cbad370372ecd3

Author: sileht

mergify_cli/ci/scopes/cli.py

@@ -6,11 +6,11 @@
 
 import click
 import pydantic
-import yaml
 
 from mergify_cli import utils
 from mergify_cli.ci.scopes import base_detector
 from mergify_cli.ci.scopes import changed_files
+from mergify_cli.ci.scopes import config
 from mergify_cli.ci.scopes import exceptions
 
 
@@ -19,65 +19,11 @@
 
 
 SCOPE_PREFIX = "scope_"
-SCOPE_NAME_RE = r"^[A-Za-z0-9_-]+$"
-
-
-class ConfigInvalidError(exceptions.ScopesError):
-    pass
-
-
-ScopeName = typing.Annotated[
-    str,
-    pydantic.StringConstraints(pattern=SCOPE_NAME_RE, min_length=1),
-]
-
-
-class FileFilters(pydantic.BaseModel):
-    include: tuple[str, ...] = pydantic.Field(default_factory=lambda: ("**/*",))
-    exclude: tuple[str, ...] = pydantic.Field(default_factory=tuple)
-
-
-class SourceFiles(pydantic.BaseModel):
-    files: dict[ScopeName, FileFilters]
-
-
-class SourceManual(pydantic.BaseModel):
-    manual: None
-
-
-class ScopesConfig(pydantic.BaseModel):
-    model_config = pydantic.ConfigDict(extra="forbid")
-
-    source: SourceFiles | SourceManual | None = None
-    merge_queue_scope: str | None = "merge-queue"
-
-
-class Config(pydantic.BaseModel):
-    model_config = pydantic.ConfigDict(extra="ignore")
-
-    scopes: ScopesConfig
-
-    @classmethod
-    def from_dict(cls, data: dict[str, typing.Any] | typing.Any) -> Config:  # noqa: ANN401
-        try:
-            return cls.model_validate(data)
-        except pydantic.ValidationError as e:
-            raise ConfigInvalidError(e)
-
-    @classmethod
-    def from_yaml(cls, path: str) -> Config:
-        with pathlib.Path(path).open(encoding="utf-8") as f:
-            try:
-                data = yaml.safe_load(f) or {}
-            except yaml.YAMLError as e:
-                raise ConfigInvalidError(e)
-
-            return cls.from_dict(data)
 
 
 def match_scopes(
     files: abc.Iterable[str],
-    filters: dict[ScopeName, FileFilters],
+    filters: dict[config.ScopeName, config.FileFilters],
 ) -> tuple[set[str], dict[str, list[str]]]:
     scopes_hit: set[str] = set()
     per_scope: dict[str, list[str]] = {s: [] for s in filters}
@@ -142,7 +88,7 @@ def load_from_file(cls, filename: str) -> DetectedScope:
 
 
 def detect(config_path: str) -> DetectedScope:
-    cfg = Config.from_yaml(config_path)
+    cfg = config.Config.from_yaml(config_path)
     base = base_detector.detect()
 
     scopes_hit: set[str]
@@ -153,11 +99,11 @@ def detect(config_path: str) -> DetectedScope:
         all_scopes = set()
         scopes_hit = set()
         per_scope = {}
-    elif isinstance(source, SourceFiles):
+    elif isinstance(source, config.SourceFiles):
         changed = changed_files.git_changed_files(base.ref)
         all_scopes = set(source.files.keys())
         scopes_hit, per_scope = match_scopes(changed, source.files)
-    elif isinstance(source, SourceManual):
+    elif isinstance(source, config.SourceManual):
         msg = "source `manual` has been set, scopes must be send with `scopes-send` or API"
         raise exceptions.ScopesError(msg)
     else:

mergify_cli/ci/scopes/config/__init__.py

@@ -0,0 +1,20 @@
+from mergify_cli.ci.scopes import exceptions
+from mergify_cli.ci.scopes.config.root import Config
+from mergify_cli.ci.scopes.config.root import ConfigInvalidError
+from mergify_cli.ci.scopes.config.scopes import FileFilters
+from mergify_cli.ci.scopes.config.scopes import ScopeName
+from mergify_cli.ci.scopes.config.scopes import Scopes
+from mergify_cli.ci.scopes.config.scopes import SourceFiles
+from mergify_cli.ci.scopes.config.scopes import SourceManual
+
+
+__all__ = [
+    "Config",
+    "ConfigInvalidError",
+    "FileFilters",
+    "ScopeName",
+    "Scopes",
+    "SourceFiles",
+    "SourceManual",
+    "exceptions",
+]

mergify_cli/ci/scopes/config/root.py

@@ -0,0 +1,38 @@
+import pathlib
+import typing
+
+import pydantic
+import yaml
+
+from mergify_cli.ci.scopes import exceptions
+from mergify_cli.ci.scopes.config.scopes import Scopes
+
+
+class ConfigInvalidError(exceptions.ScopesError):
+    pass
+
+
+class Config(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(extra="ignore")
+
+    scopes: Scopes
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: dict[str, typing.Any] | typing.Any,  # noqa: ANN401
+    ) -> typing.Self:
+        try:
+            return cls.model_validate(data)
+        except pydantic.ValidationError as e:
+            raise ConfigInvalidError(e)
+
+    @classmethod
+    def from_yaml(cls, path: str) -> typing.Self:
+        with pathlib.Path(path).open(encoding="utf-8") as f:
+            try:
+                data = yaml.safe_load(f) or {}
+            except yaml.YAMLError as e:
+                raise ConfigInvalidError(e)
+
+            return cls.from_dict(data)

mergify_cli/ci/scopes/config/scopes.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import typing
+
+import pydantic
+
+
+SCOPE_NAME_RE = r"^[A-Za-z0-9_-]+$"
+
+
+ScopeName = typing.Annotated[
+    str,
+    pydantic.StringConstraints(pattern=SCOPE_NAME_RE, min_length=1),
+]
+
+
+class FileFilters(pydantic.BaseModel):
+    include: tuple[str, ...] = pydantic.Field(
+        default_factory=lambda: ("**/*",),
+        description=(
+            "Glob patterns of files to include for this scope. "
+            "Empty means 'include everything' before exclusions. "
+            "Examples: ('src/**/*.py', 'Makefile')"
+        ),
+    )
+    exclude: tuple[str, ...] = pydantic.Field(
+        default_factory=tuple,
+        description=(
+            "Glob patterns of files to exclude from this scope. "
+            "Evaluated after `include` and takes precedence. "
+            "Examples: ('**/tests/**', '*.md')"
+        ),
+    )
+
+
+class SourceFiles(pydantic.BaseModel):
+    files: dict[ScopeName, FileFilters] = pydantic.Field(
+        description=(
+            "Mapping of scope name to its file filters. "
+            "A file belongs to a scope if it matches the scope's `include` "
+            "patterns and not its `exclude` patterns."
+        ),
+    )
+
+
+class SourceManual(pydantic.BaseModel):
+    manual: None = pydantic.Field(
+        description="Scopes are manually sent via API or `mergify scopes-send`",
+    )
+
+
+class Scopes(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(extra="ignore")
+
+    source: SourceFiles | SourceManual | None = pydantic.Field(
+        default=None,
+        description=(
+            "Where scopes come from. "
+            "`files` uses file-pattern rules (`gha-mergify-ci-scopes` must have been setup on your pull request); "
+            "`manual` uses scopes sent via API or `mergify scopes-send`; "
+            "`None` disables scoping."
+        ),
+    )
+    merge_queue_scope: str | None = pydantic.Field(
+        default="merge-queue",
+        description=(
+            "Optional scope name automatically applied to merge queue PRs. "
+            "Set to `None` to disable."
+        ),
+    )