check-json5 1.3.0__py3-none-any.whl

check_json5/__init__.py

@@ -0,0 +1 @@
+"""Pre-commit hook to check JSON files for syntax parseable as JSON5 (with comments)."""

check_json5/check_json5.py

@@ -0,0 +1,269 @@
+"""Based on https://gitlab.com/bmares/check-json5/-/blob/db9b5c0f76dea9b0f28097b4421e4b40f39b2266/pypackages/pre_commit_hooks/check_json5.py."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+
+# The hook starts once per commit, so its imports are a large share of a run:
+# the type-only ones load for the type checker alone. `re` is free: json imports it.
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Iterator, Sequence
+    from typing import Any
+
+    # (line, column, message); line and column are 1-based, or None when the parser gives no position.
+    Problem = tuple[int | None, int | None, str]
+
+
+class DuplicateKeyError(ValueError):
+    """A JSON object repeats a key."""
+
+    def __init__(self, key: str) -> None:
+        """Keep the repeated key for the error message."""
+        super().__init__(f"Duplicate key: {key}")
+        self.key = key
+
+
+class NonStandardConstantError(ValueError):
+    """Strict JSON contains NaN, Infinity or -Infinity."""
+
+
+def raise_duplicate_keys(ordered_pairs: Iterable[tuple[str, Any]]) -> dict[str, Any]:
+    """Build a dict from a JSON object's pairs, refusing a repeated key.
+
+    Raises:
+        DuplicateKeyError: If a key repeats.
+
+    """
+    d = {}
+    for key, val in ordered_pairs:
+        if key in d:
+            raise DuplicateKeyError(key)
+        d[key] = val
+    return d
+
+
+def _reject_constant(name: str) -> float:
+    raise NonStandardConstantError(name)
+
+
+# Only ever run over text a parser has looked at, so it can be loose: it skips what it
+# does not recognise. Strings come before comments so a "//" inside one stays a string.
+_TOKEN = re.compile(
+    r"""(?P<str>"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')
+      | (?P<skip>\s+|//[^\n]*|/\*.*?\*/)
+      | (?P<punct>[{}\[\]:,])
+      | (?P<bare>[^\s{}\[\]:,"'/]+)""",
+    re.VERBOSE | re.DOTALL,
+)
+_IDENTIFIER = re.compile(r"[A-Za-z_$][\w$]*")
+_JSON5_ERROR = re.compile(r"<string>:(\d+) (.*) at column (\d+)", re.DOTALL)
+
+
+def _tokens(text: str) -> Iterator[tuple[str, str, int]]:
+    for m in _TOKEN.finditer(text):
+        if m.lastgroup != "skip":
+            yield m.lastgroup or "", m.group(), m.start()
+
+
+def _member(path: str, key: str) -> str:
+    return f"{path}.{key}" if _IDENTIFIER.fullmatch(key) else f"{path}[{json.dumps(key)}]"
+
+
+def _duplicates(text: str, decode: Callable[[str], Any]) -> list[tuple[int, str]]:
+    """Offset and JSONPath of every key that repeats an earlier key of the same object."""
+    found: list[tuple[int, str]] = []
+    # One frame per open container: [bracket, its path, keys seen (objects), current key or index].
+    stack: list[list[Any]] = []
+    prev = ("", "", 0)
+    for kind, tok, offset in _tokens(text):
+        top = stack[-1] if stack else None
+        if kind != "punct":
+            pass
+        elif tok in "{[":
+            stack.append([tok, _child_path(top), set(), None if tok == "{" else 0])
+        elif tok in "}]":
+            if stack:
+                stack.pop()
+        elif top is None:
+            pass
+        elif tok == "," and top[0] == "[":
+            top[3] += 1
+        elif tok == ":" and top[0] == "{":
+            key = decode(prev[1]) if prev[0] == "str" else prev[1]
+            if key in top[2]:
+                found.append((prev[2], _member(top[1], key)))
+            top[2].add(key)
+            top[3] = key
+        prev = (kind, tok, offset)
+    return found
+
+
+def _child_path(parent: list[Any] | None) -> str:
+    if parent is None:
+        return "$"
+    if parent[0] == "{":
+        return _member(parent[1], parent[3] or "")
+    return f"{parent[1]}[{parent[3]}]"
+
+
+def _position(text: str, offset: int) -> tuple[int, int]:
+    return text.count("\n", 0, offset) + 1, offset - text.rfind("\n", 0, offset)
+
+
+def _duplicate_problems(text: str, decode: Callable[[str], Any], exc: DuplicateKeyError) -> list[Problem]:
+    found = _duplicates(text, decode)
+    if not found:  # the scanner missed what the parser saw: still fail, just without a place
+        return [(None, None, f"duplicate key {exc.key!r}")]
+    return [(*_position(text, offset), f"duplicate key {path}") for offset, path in found]
+
+
+def check(text: str, *, strict: bool = False) -> list[Problem]:
+    """Check one file's text: JSON5 syntax and duplicate keys, or strict JSON when `strict`.
+
+    Returns:
+        The problems found, empty when the text passes.
+
+    Raises:
+        RecursionError: If the text nests deeper than the parser can follow.
+
+    """
+    problems = _check_json(text, strict=strict)
+    return _check_json5(text) if problems is None else problems
+
+
+def _check_json(text: str, *, strict: bool) -> list[Problem] | None:
+    """Problems as strict JSON, or None when the text is not strict JSON and may be JSON5."""
+    try:
+        # Fast path: strict JSON parses at C speed and covers most files.
+        if strict:
+            json.loads(text, object_pairs_hook=raise_duplicate_keys, parse_constant=_reject_constant)
+        else:
+            json.loads(text, object_pairs_hook=raise_duplicate_keys)
+    except DuplicateKeyError as exc:
+        return _duplicate_problems(text, json.loads, exc)
+    except NonStandardConstantError:
+        return [
+            (*_position(text, offset), f"{tok} is not valid in strict JSON")
+            for kind, tok, offset in _tokens(text)
+            if kind == "bare" and tok in {"NaN", "Infinity", "-Infinity"}
+        ]
+    except json.JSONDecodeError as exc:
+        return [(exc.lineno, exc.colno, f"not strict JSON: {exc.msg}")] if strict else None
+    return []
+
+
+def _check_json5(text: str) -> list[Problem]:
+    # Imported here so a run over strict JSON never pays json5's import time.
+    # NOTE: a top-level `lazy import` does the same, once 3.15 is the floor.
+    import json5  # noqa: PLC0415
+
+    # json5 re-raises an error from the hook as a plain ValueError, so keep the original here.
+    duplicate: list[DuplicateKeyError] = []
+
+    def hook(pairs: Iterable[tuple[str, Any]]) -> dict[str, Any]:
+        try:
+            return raise_duplicate_keys(pairs)
+        except DuplicateKeyError as exc:
+            duplicate.append(exc)
+            raise
+
+    try:
+        json5.loads(text, object_pairs_hook=hook)
+    except ValueError as exc:
+        if duplicate:
+            return _duplicate_problems(text, json5.loads, duplicate[0])
+        m = _JSON5_ERROR.fullmatch(str(exc))
+        return [(int(m[1]), int(m[3]), m[2])] if m else [(None, None, str(exc))]
+    return []
+
+
+def is_strict(filename: str, patterns: Sequence[str]) -> bool:
+    """Whether `filename` must be strict JSON: the last matching pattern decides.
+
+    A pattern without a `/` matches the file name at any depth, one with a `/` the whole
+    path, `*` matches across `/`, and a leading `!` exempts the files it matches.
+    """
+    if not patterns:
+        return False
+    from fnmatch import fnmatchcase  # noqa: PLC0415
+
+    path = filename.replace(os.sep, "/")
+    name = path.rsplit("/", 1)[-1]
+    strict = False
+    for pattern in patterns:
+        bare = pattern.removeprefix("!")
+        if fnmatchcase(path if "/" in bare else name, bare):
+            strict = not pattern.startswith("!")
+    return strict
+
+
+def _escape(value: str, *, prop: bool = False) -> str:
+    value = value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+    return value.replace(":", "%3A").replace(",", "%2C") if prop else value
+
+
+def report(filename: str, problem: Problem, *, annotate: bool = False) -> None:
+    """Print one problem as `file:line:col: message`, plus a GitHub annotation when `annotate`."""
+    line, col, msg = problem
+    print(f"{filename}: {msg}" if line is None else f"{filename}:{line}:{col}: {msg}")
+    if annotate:
+        where = "" if line is None else f",line={line},col={col}"
+        print(f"::error file={_escape(filename, prop=True)}{where},title=check-json5::{_escape(msg)}")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Check JSON5 files for syntax errors and duplicate keys.
+
+    Args:
+        argv: options and filenames. If None, defaults to sys.argv[1:].
+
+    Returns:
+        An exit code indicating success (0) or failure (1).
+
+    """
+    args = sys.argv[1:] if argv is None else list(argv)
+    strict_patterns: list[str] = []
+    if any(a.startswith("-") for a in args):  # argparse costs a few ms, so only load it for options
+        import argparse  # noqa: PLC0415
+
+        parser = argparse.ArgumentParser(prog="check-json5", description="Check JSON5 files.")
+        parser.add_argument(
+            "--strict",
+            action="append",
+            default=[],
+            metavar="GLOB",
+            help="files matching GLOB must be strict JSON; repeat it, `!GLOB` exempts (last match wins)",
+        )
+        parser.add_argument("filenames", nargs="*")
+        ns = parser.parse_args(args)
+        args, strict_patterns = ns.filenames, ns.strict
+
+    # Python caps int literals at 4300 digits (3.10.7+), which fails valid JSON with a long number.
+    if hasattr(sys, "set_int_max_str_digits"):
+        sys.set_int_max_str_digits(0)
+    annotate = os.environ.get("GITHUB_ACTIONS") == "true"
+    retval = 0
+    for filename in args:
+        if not os.path.isfile(filename):  # noqa: PTH113
+            problems: list[Problem] = [(None, None, "No such file")]
+        else:
+            try:
+                # utf-8-sig transparently strips a leading BOM if present.
+                with open(filename, encoding="utf-8-sig") as f:  # noqa: PTH123
+                    problems = check(f.read(), strict=is_strict(filename, strict_patterns))
+            except (OSError, UnicodeDecodeError) as exc:
+                problems = [(None, None, f"Failed to read ({exc})")]
+            except RecursionError:  # fails this file instead of ending the run
+                problems = [(None, None, "nested too deeply to check")]
+        for problem in problems:
+            report(filename, problem, annotate=annotate)
+        retval |= bool(problems)
+    return retval
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

check_json5-1.3.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: check-json5
+Version: 1.3.0
+Summary: pre-commit hook to check json files for syntax parseable as json5 (with comments)
+Author-email: Simon van Lierde <30519500-simonvanlierde@users.noreply.gitlab.com>
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/simonvanlierde/check-json5/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/simonvanlierde/check-json5/issues
+Project-URL: Source, https://github.com/simonvanlierde/check-json5
+Keywords: json,json5,jsonc,lint,pre-commit
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: json5>=0.15.0
+Dynamic: license-file
+
+# check-json5
+
+[![CI](https://github.com/simonvanlierde/check-json5/actions/workflows/ci.yml/badge.svg)](https://github.com/simonvanlierde/check-json5/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/simonvanlierde/check-json5/branch/main/graph/badge.svg)](https://codecov.io/gh/simonvanlierde/check-json5)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A [pre-commit](https://pre-commit.com/) hook that checks whether `.json` files parse as
+[JSON5](https://json5.org/) (JSON with comments, trailing commas, and more). It replaces the
+standard `check-json` hook, accepts JSON5 too, and keeps the speed of the C parser on ordinary
+JSON.
+
+## Features
+
+- Accepts JSON5 syntax (comments, trailing commas) that the standard `check-json` hook rejects.
+- Every failure names its place, as `file:line:col: message`, so editors and terminals link
+  straight to it. A duplicate key also gets its path, and every repeat in a file is listed:
+
+  ```text
+  config.json:4:5: duplicate key $.server.port
+  config.json:9:3: duplicate key $.plugins[2].name
+  ```
+
+- On GitHub Actions, each failure is also an annotation on the line of the pull request diff.
+- `--strict GLOB` holds chosen files to strict JSON (no comments, no `NaN`), for files that a
+  JSON parser reads at runtime, such as `package.json`.
+- Fast path: strict JSON is parsed with the C-speed stdlib `json` parser, falling back to the
+  pure-Python `json5` parser only when a file actually uses JSON5 features (~500× faster on large
+  strict-JSON files; see [Performance](#performance)).
+- Accepts `NaN` and `Infinity` (both parsers allow them) unless `--strict` covers the file.
+
+## Links
+
+- 🐙 [GitHub (main)](https://github.com/simonvanlierde/check-json5)
+- 🦊 [GitLab (mirror)](https://gitlab.com/simonvanlierde/check-json5)
+
+## Usage
+
+In `.pre-commit-config.yaml`, under `repos:`, add:
+
+```yaml
+- repo: https://github.com/simonvanlierde/check-json5
+  rev: v1.3.0
+  hooks:
+    - id: check-json5
+```
+
+Remove the original `check-json` hook if it is already included. A file passes when it parses as
+JSON5 and has no duplicate keys. The hook picks files by extension (`.json`, `.jsonc`, `.json5`,
+`.geojson`, `.jsonld`), while `check-json` picks them by type, so files such as `.babelrc` or
+`.ipynb` are no longer checked after the swap. Add them with `files:` if you need them.
+
+### Strict files
+
+Some JSON files are read by a strict parser at runtime: a comment in `package.json` passes a JSON5
+check and then breaks `npm`. Name those files with `--strict`. Each pattern matches the file name
+at any depth, or the whole path when it contains a `/`. `*` also matches across `/`. A leading `!`
+exempts files, and the last matching pattern wins:
+
+```yaml
+    - id: check-json5
+      args: [--strict, "*.json", --strict, "!tsconfig*.json", --strict, "!.vscode/*"]
+```
+
+### Without pre-commit
+
+The hook is also a command on PyPI:
+
+```bash
+uvx check-json5 --strict package.json config/*.json
+```
+
+## Introduction
+
+JSON5 is similar to JSON but permits comments, trailing commas, and more. It resembles "JSONC" (JSON
+with Comments) but, unlike JSONC, has an actual specification. Many config files in the wild are
+really JSON5, so the standard `check-json` hook, which rejects comments outright, flags them as
+invalid. This hook accepts them.
+
+Strict-JSON files are parsed with the fast built-in [`json`](https://docs.python.org/3/library/json.html)
+library; only files that use JSON5 features fall back to the pure-Python
+[`json5`](https://pypi.org/project/json5/) library.
+
+## Performance
+
+The pure-Python `json5` parser is slow on large files. Since most `.json` files are strict JSON, the
+hook tries the C-speed stdlib `json` parser first and only falls back to `json5` when a file uses
+comments or trailing commas. Duplicate-key detection works on both paths.
+
+Time for one hook call per file (strict JSON, taking the fast path), best of 10 runs of
+`uv run python scripts/bench.py` on 2026-10-11 (Intel i9-14900KF, Linux, Python 3.13.7, json5 0.15.0,
+load average 1.5):
+
+| File size | Before (`json5` only) | After (fast path) | Speedup |
+| --------- | --------------------- | ----------------- | ------- |
+| 1 KB      | 2.5 ms                | 0.02 ms           | ~100×   |
+| 47 KB     | 123 ms                | 0.19 ms           | ~660×   |
+| 483 KB    | 1.3 s                 | 1.8 ms            | ~750×   |
+| 2 MB      | 5.4 s                 | 7.7 ms            | ~700×   |
+
+The script generates its fixture files in a temporary directory, so nothing large is committed.
+Timings vary between runs by up to 2× on a loaded machine. The 1 KB fast-path time is close to
+the timer's resolution, so its speed-up ranged from ~80× to ~100× across runs.
+
+To time whole hook runs instead, run `bash scripts/bench.sh` (needs
+[hyperfine](https://github.com/sharkdp/hyperfine)). It times the hook against the `json5` parser
+on 50 KB, 500 KB and 2 MB files and prints one table; `--quick` times the 50 KB file once. Each
+run includes about 20 ms of Python startup, so its speed-ups are smaller than the ones above.
+
+Files that use JSON5 syntax still go through the `json5` parser and are unchanged. For tiny config
+files the absolute saving is negligible next to Python's own startup cost; the win matters on large
+JSON files.
+
+## Development
+
+The project uses [uv](https://github.com/astral-sh/uv) for dependency management, `pytest` for
+tests, `pre-commit` for local checks, and GitHub Actions for CI with coverage reported to Codecov.
+
+```bash
+uv sync                   # install dependencies
+uv run pytest             # run the test suite
+uv run pytest --cov       # tests with coverage
+uv run pre-commit run -a  # run the configured hooks locally
+```
+
+## Credits
+
+Adapted by Simon van Lierde from the original [check-json5](https://gitlab.com/bmares/check-json5) by
+Ben Mares, itself based on the
+[pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks) repository by Anthony Sottile and
+contributors. This version switches dependency management from Poetry to uv and adds the fast-path
+parser and benchmark above.
+
+## License
+
+[MIT](LICENSE), consistent with the upstream projects it is based on
+([Ben Mares](https://gitlab.com/bmares/check-json5/-/blob/main/LICENSE),
+[pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks/blob/main/LICENSE)).

check_json5-1.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+check_json5/__init__.py,sha256=8zSYfR0TaxiTShizu9YH8TJ4P4ddS3qM-3XfC5wO380,89
+check_json5/check_json5.py,sha256=OH11toCvP09JabJwBQcTTPV8uBrfR0UPi39t_u6EXC0,10082
+check_json5-1.3.0.dist-info/licenses/LICENSE,sha256=tVGACWS_DERmpA4nTgZ41iHhqE2-x7hmTp_rzcNfkHU,1110
+check_json5-1.3.0.dist-info/METADATA,sha256=LUlIYexzrkZDBxdY5P5URUAJaxlNqhntJbMwU2CqwCg,7432
+check_json5-1.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+check_json5-1.3.0.dist-info/entry_points.txt,sha256=-jKwoj1vJv13w_U9G1oHSzVpnkjLz6OiACRaMR0l11k,61
+check_json5-1.3.0.dist-info/top_level.txt,sha256=5_Pwwyf8-UpH80eRmR62t2odl8GW5PjB9c-qo80Nhuw,12
+check_json5-1.3.0.dist-info/RECORD,,

check_json5-1.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

check_json5-1.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+check-json5 = check_json5.check_json5:main

check_json5-1.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,10 @@
+MIT License
+
+Copyright (c) 2025 Simon van Lierde
+Copyright (c) 2021 Ben Mares
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

check_json5-1.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+check_json5