From 2bc5ce8ae1f1ad52909b4656444c1e9988e23cab Mon Sep 17 00:00:00 2001
From: Henry Schreiner <HenrySchreinerIII@gmail.com>
Date: Mon, 29 Jan 2024 10:56:48 -0500
Subject: [PATCH] feat: add schema and validate-pyproject support (#4181)

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 .github/workflows/lint.yml            |   5 +
 .github/workflows/test.yml            |   2 +-
 .pre-commit-config.yaml               |  11 +-
 CHANGES.md                            |   2 +
 pyproject.toml                        |   3 +
 scripts/generate_schema.py            |  74 +++++++++++++
 src/black/resources/__init__.py       |   0
 src/black/resources/black.schema.json | 149 ++++++++++++++++++++++++++
 src/black/schema.py                   |  20 ++++
 tests/test_schema.py                  |  17 +++
 tox.ini                               |  10 +-
 11 files changed, 288 insertions(+), 5 deletions(-)
 create mode 100644 scripts/generate_schema.py
 create mode 100644 src/black/resources/__init__.py
 create mode 100644 src/black/resources/black.schema.json
 create mode 100644 src/black/schema.py
 create mode 100644 tests/test_schema.py

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 2d016cef7a6..8cb335bffb5 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -40,3 +40,8 @@ jobs:
       - name: Format ourselves
         run: |
           tox -e run_self
+
+      - name: Regenerate schema
+        run: |
+          tox -e generate_schema
+          git diff --exit-code
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 55359a23303..fc274208258 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -106,4 +106,4 @@ jobs:
           python -m pip install -e ".[uvloop]"
 
       - name: Format ourselves
-        run: python -m black --check .
+        run: python -m black --check src/ tests/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 13479565527..05569eed8db 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -42,9 +42,9 @@ repos:
     rev: v1.8.0
     hooks:
       - id: mypy
-        exclude: ^docs/conf.py
-        args: ["--config-file", "pyproject.toml"]
-        additional_dependencies:
+        exclude: ^(docs/conf.py|scripts/generate_schema.py)$
+        args: []
+        additional_dependencies: &mypy_deps
           - types-PyYAML
           - tomli >= 0.2.6, < 2.0.0
           - click >= 8.1.0, != 8.1.4, != 8.1.5
@@ -56,6 +56,11 @@ repos:
           - types-commonmark
           - urllib3
           - hypothesmith
+      - id: mypy
+        name: mypy (Python 3.10)
+        files: scripts/generate_schema.py
+        args: ["--python-version=3.10"]
+        additional_dependencies: *mypy_deps
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v4.0.0-alpha.8
diff --git a/CHANGES.md b/CHANGES.md
index 6da30afc707..4fd030df6df 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -45,6 +45,8 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Add a JSONSchema and provide a validate-pyproject entry-point (#4181)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes
diff --git a/pyproject.toml b/pyproject.toml
index fa3654b8d67..143c4845a94 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -89,6 +89,9 @@ jupyter = [
 black = "black:patched_main"
 blackd = "blackd:patched_main [d]"
 
+[project.entry-points."validate_pyproject.tool_schema"]
+black = "black.schema:get_schema"
+
 [project.urls]
 Changelog = "https://github.com/psf/black/blob/main/CHANGES.md"
 Homepage = "https://github.com/psf/black"
diff --git a/scripts/generate_schema.py b/scripts/generate_schema.py
new file mode 100644
index 00000000000..f3437cc8fee
--- /dev/null
+++ b/scripts/generate_schema.py
@@ -0,0 +1,74 @@
+import json
+from typing import IO, Any
+
+import click
+
+import black
+
+
+def generate_schema_from_click(
+    cmd: click.Command,
+) -> dict[str, Any]:
+    result: dict[str, dict[str, Any]] = {}
+    for param in cmd.params:
+        if not isinstance(param, click.Option) or param.is_eager:
+            continue
+
+        assert param.name
+        name = param.name.replace("_", "-")
+
+        result[name] = {}
+
+        match param.type:
+            case click.types.IntParamType():
+                result[name]["type"] = "integer"
+            case click.types.StringParamType() | click.types.Path():
+                result[name]["type"] = "string"
+            case click.types.Choice(choices=choices):
+                result[name]["enum"] = choices
+            case click.types.BoolParamType():
+                result[name]["type"] = "boolean"
+            case _:
+                msg = f"{param.type!r} not a known type for {param}"
+                raise TypeError(msg)
+
+        if param.multiple:
+            result[name] = {"type": "array", "items": result[name]}
+
+        result[name]["description"] = param.help
+
+        if param.default is not None and not param.multiple:
+            result[name]["default"] = param.default
+
+    return result
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option("--schemastore", is_flag=True, help="SchemaStore format")
+@click.option("--outfile", type=click.File(mode="w"), help="Write to file")
+def main(schemastore: bool, outfile: IO[str]) -> None:
+    properties = generate_schema_from_click(black.main)
+    del properties["line-ranges"]
+
+    schema: dict[str, Any] = {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "$id": (
+            "https://github.com/psf/black/blob/main/black/resources/black.schema.json"
+        ),
+        "$comment": "tool.black table in pyproject.toml",
+        "type": "object",
+        "additionalProperties": False,
+        "properties": properties,
+    }
+
+    if schemastore:
+        schema["$id"] = ("https://json.schemastore.org/partial-black.json",)
+        # The precise list of unstable features may change frequently, so don't
+        # bother putting it in SchemaStore
+        schema["properties"]["enable-unstable-feature"]["items"] = {"type": "string"}
+
+    print(json.dumps(schema, indent=2), file=outfile)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/black/resources/__init__.py b/src/black/resources/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/src/black/resources/black.schema.json b/src/black/resources/black.schema.json
new file mode 100644
index 00000000000..40bf39137f7
--- /dev/null
+++ b/src/black/resources/black.schema.json
@@ -0,0 +1,149 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/psf/black/blob/main/black/resources/black.schema.json",
+  "$comment": "tool.black table in pyproject.toml",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "Format the code passed in as a string."
+    },
+    "line-length": {
+      "type": "integer",
+      "description": "How many characters per line to allow.",
+      "default": 88
+    },
+    "target-version": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "py33",
+          "py34",
+          "py35",
+          "py36",
+          "py37",
+          "py38",
+          "py39",
+          "py310",
+          "py311",
+          "py312"
+        ]
+      },
+      "description": "Python versions that should be supported by Black's output. You should include all versions that your code supports. By default, Black will infer target versions from the project metadata in pyproject.toml. If this does not yield conclusive results, Black will use per-file auto-detection."
+    },
+    "pyi": {
+      "type": "boolean",
+      "description": "Format all input files like typing stubs regardless of file extension. This is useful when piping source on standard input.",
+      "default": false
+    },
+    "ipynb": {
+      "type": "boolean",
+      "description": "Format all input files like Jupyter Notebooks regardless of file extension. This is useful when piping source on standard input.",
+      "default": false
+    },
+    "python-cell-magics": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "When processing Jupyter Notebooks, add the given magic to the list of known python-magics (capture, prun, pypy, python, python3, time, timeit). Useful for formatting cells with custom python magics."
+    },
+    "skip-source-first-line": {
+      "type": "boolean",
+      "description": "Skip the first line of the source code.",
+      "default": false
+    },
+    "skip-string-normalization": {
+      "type": "boolean",
+      "description": "Don't normalize string quotes or prefixes.",
+      "default": false
+    },
+    "skip-magic-trailing-comma": {
+      "type": "boolean",
+      "description": "Don't use trailing commas as a reason to split lines.",
+      "default": false
+    },
+    "preview": {
+      "type": "boolean",
+      "description": "Enable potentially disruptive style changes that may be added to Black's main functionality in the next major release.",
+      "default": false
+    },
+    "unstable": {
+      "type": "boolean",
+      "description": "Enable potentially disruptive style changes that have known bugs or are not currently expected to make it into the stable style Black's next major release. Implies --preview.",
+      "default": false
+    },
+    "enable-unstable-feature": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "hex_codes_in_unicode_sequences",
+          "string_processing",
+          "hug_parens_with_braces_and_square_brackets",
+          "unify_docstring_detection",
+          "no_normalize_fmt_skip_whitespace",
+          "wrap_long_dict_values_in_parens",
+          "multiline_string_handling",
+          "typed_params_trailing_comma"
+        ]
+      },
+      "description": "Enable specific features included in the `--unstable` style. Requires `--preview`. No compatibility guarantees are provided on the behavior or existence of any unstable features."
+    },
+    "check": {
+      "type": "boolean",
+      "description": "Don't write the files back, just return the status. Return code 0 means nothing would change. Return code 1 means some files would be reformatted. Return code 123 means there was an internal error.",
+      "default": false
+    },
+    "diff": {
+      "type": "boolean",
+      "description": "Don't write the files back, just output a diff to indicate what changes Black would've made. They are printed to stdout so capturing them is simple.",
+      "default": false
+    },
+    "color": {
+      "type": "boolean",
+      "description": "Show (or do not show) colored diff. Only applies when --diff is given.",
+      "default": false
+    },
+    "fast": {
+      "type": "boolean",
+      "description": "By default, Black performs an AST safety check after formatting your code. The --fast flag turns off this check and the --safe flag explicitly enables it. [default: --safe]",
+      "default": false
+    },
+    "required-version": {
+      "type": "string",
+      "description": "Require a specific version of Black to be running. This is useful for ensuring that all contributors to your project are using the same version, because different versions of Black may format code a little differently. This option can be set in a configuration file for consistent results across environments."
+    },
+    "exclude": {
+      "type": "string",
+      "description": "A regular expression that matches files and directories that should be excluded on recursive searches. An empty value means no paths are excluded. Use forward slashes for directories on all platforms (Windows, too). By default, Black also ignores all paths listed in .gitignore. Changing this value will override all default exclusions. [default: /(\\.direnv|\\.eggs|\\.git|\\.hg|\\.ipynb_checkpoints|\\.mypy_cache|\\.nox|\\.pytest_cache|\\.ruff_cache|\\.tox|\\.svn|\\.venv|\\.vscode|__pypackages__|_build|buck-out|build|dist|venv)/]"
+    },
+    "extend-exclude": {
+      "type": "string",
+      "description": "Like --exclude, but adds additional files and directories on top of the default values instead of overriding them."
+    },
+    "force-exclude": {
+      "type": "string",
+      "description": "Like --exclude, but files and directories matching this regex will be excluded even when they are passed explicitly as arguments. This is useful when invoking Black programmatically on changed files, such as in a pre-commit hook or editor plugin."
+    },
+    "include": {
+      "type": "string",
+      "description": "A regular expression that matches files and directories that should be included on recursive searches. An empty value means all files are included regardless of the name. Use forward slashes for directories on all platforms (Windows, too). Overrides all exclusions, including from .gitignore and command line options.",
+      "default": "(\\.pyi?|\\.ipynb)$"
+    },
+    "workers": {
+      "type": "integer",
+      "description": "When Black formats multiple files, it may use a process pool to speed up formatting. This option controls the number of parallel workers. This can also be specified via the BLACK_NUM_WORKERS environment variable. Defaults to the number of CPUs in the system."
+    },
+    "quiet": {
+      "type": "boolean",
+      "description": "Stop emitting all non-critical output. Error messages will still be emitted (which can silenced by 2>/dev/null).",
+      "default": false
+    },
+    "verbose": {
+      "type": "boolean",
+      "description": "Emit messages about files that were not changed or were ignored due to exclusion patterns. If Black is using a configuration file, a message detailing which one it is using will be emitted.",
+      "default": false
+    }
+  }
+}
diff --git a/src/black/schema.py b/src/black/schema.py
new file mode 100644
index 00000000000..78e9564cdbc
--- /dev/null
+++ b/src/black/schema.py
@@ -0,0 +1,20 @@
+import importlib.resources
+import json
+import sys
+from typing import Any
+
+
+def get_schema(tool_name: str = "black") -> Any:
+    """Get the stored complete schema for black's settings."""
+    assert tool_name == "black", "Only black is supported."
+
+    pkg = "black.resources"
+    fname = "black.schema.json"
+
+    if sys.version_info < (3, 9):
+        with importlib.resources.open_text(pkg, fname, encoding="utf-8") as f:
+            return json.load(f)
+
+    schema = importlib.resources.files(pkg).joinpath(fname)  # type: ignore[unreachable]
+    with schema.open(encoding="utf-8") as f:
+        return json.load(f)
diff --git a/tests/test_schema.py b/tests/test_schema.py
new file mode 100644
index 00000000000..1ea95130f86
--- /dev/null
+++ b/tests/test_schema.py
@@ -0,0 +1,17 @@
+import importlib.metadata
+import sys
+
+
+def test_schema_entrypoint() -> None:
+    if sys.version_info < (3, 10):
+        eps = importlib.metadata.entry_points()["validate_pyproject.tool_schema"]
+        (black_ep,) = [ep for ep in eps if ep.name == "black"]
+    else:
+        (black_ep,) = importlib.metadata.entry_points(
+            group="validate_pyproject.tool_schema", name="black"
+        )
+
+    black_fn = black_ep.load()
+    schema = black_fn()
+    assert schema == black_fn("black")
+    assert schema["properties"]["line-length"]["type"] == "integer"
diff --git a/tox.ini b/tox.ini
index 8b4175d23fe..f7357e3b8af 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,6 +1,6 @@
 [tox]
 isolated_build = true
-envlist = {,ci-}py{38,39,310,311,py3},fuzz,run_self
+envlist = {,ci-}py{38,39,310,311,py3},fuzz,run_self,generate_schema
 
 [testenv]
 setenv =
@@ -96,3 +96,11 @@ skip_install = True
 commands =
     pip install -e .
     black --check {toxinidir}/src {toxinidir}/tests
+
+[testenv:generate_schema]
+setenv = PYTHONWARNDEFAULTENCODING =
+skip_install = True
+deps =
+commands =
+    pip install -e .
+    python {toxinidir}/scripts/generate_schema.py --outfile {toxinidir}/src/black/resources/black.schema.json