feat: preprocess jsonc, fallback for json5

Adds a preprocessor that can deal with most comments and trailing commas in JSONC and JSON%, but will fall back to an optional json5 for full format support.

Author: abkfenris

.pre-commit-config.yaml

@@ -50,6 +50,7 @@ repos:
         args: []
         additional_dependencies:
           - click
+          - json5>=0.15.0
           - markdown-it-py
           - pytest
           - nox

docs/guides/gha_basic.md

@@ -159,7 +159,7 @@ static. And old versioned images are decommissioned.
 
 ## Updating
 
-{rr}`DEP200` {rr}`GH200` {rr}`GH210` {rr}`REN200` {rr}`REN210`
+{rr}`DEP200` {rr}`GH200` {rr}`GH210`
 If you use non-default actions in your repository
 (you will see some in the following pages), then it's a good idea to keep them
 up to date. GitHub provided a way to do this with dependabot. Just add the
@@ -190,9 +190,9 @@ which is both cleaner and sometimes required for dependent actions, like
 
 You can use this for other ecosystems too, including Python.
 
-[Renovate](https://docs.renovatebot.com/) can also be used for keeping GitHub
-Actions (and other ecosystems) up to date as well. A good starting point for
-`renovate.json` with the
+{rr}`REN200` {rr}`REN210` [Renovate](https://docs.renovatebot.com/) can also be
+used for keeping GitHub Actions (and other ecosystems) up to date as well. A
+good starting point for `renovate.json` with the
 [hosted version](https://docs.renovatebot.com/getting-started/installing-onboarding/)
 which will cover GitHub Actions and most other ecosystems is:
 
@@ -202,6 +202,12 @@ which will cover GitHub Actions and most other ecosystems is:
 }
 ```
 
+:::{tip}
+Most Renovate `.jsonc` or `.json5` configs can be parsed without extra
+dependencies, but include the `json5` optional dependency in order to load the
+full range of the formats.
+:::
+
 ## Common needs
 
 ### Single OS steps

pyproject.toml

@@ -48,7 +48,10 @@ async = [
   "repo-review[async]",
 ]
 all = [
-  "sp-repo-review[cli,pyproject,async]",
+  "sp-repo-review[cli,pyproject,async,json5]",
+]
+json5 = [
+    "json5>=0.15.0",
 ]
 
 [project.urls]

src/sp_repo_review/checks/_jsonc.py

@@ -0,0 +1,91 @@
+"""Minimal, string-aware JSONC preprocessing.
+
+Strips ``//`` and ``/* */`` comments and trailing commas so that JSONC (and the
+subset of JSON5 that only uses those features) can be parsed by the standard
+library :mod:`json`. Full JSON5 (single-quoted strings, unquoted keys, hex
+numbers, etc.) is *not* handled here and requires the optional ``json5``
+dependency.
+"""
+
+from __future__ import annotations
+
+_WHITESPACE = " \t\r\n"
+
+
+def _copy_string(text: str, i: int, out: list[str]) -> int:
+    """Copy a double-quoted string verbatim, returning the index after it."""
+    length = len(text)
+    out.append(text[i])  # opening quote
+    i += 1
+    while i < length:
+        char = text[i]
+        out.append(char)
+        if char == "\\" and i + 1 < length:
+            # Copy the escaped character so an escaped quote does not
+            # prematurely close the string.
+            out.append(text[i + 1])
+            i += 2
+        elif char == '"':
+            i += 1
+            break
+        else:
+            i += 1
+    return i
+
+
+def _skip_line_comment(text: str, i: int) -> int:
+    """Skip a ``// ...`` comment, returning the index of the line ending."""
+    i += 2
+    length = len(text)
+    while i < length and text[i] not in "\r\n":
+        i += 1
+    return i
+
+
+def _skip_block_comment(text: str, i: int) -> int:
+    """Skip a ``/* ... */`` comment, returning the index after it."""
+    i += 2
+    length = len(text)
+    while i + 1 < length and not (text[i] == "*" and text[i + 1] == "/"):
+        i += 1
+    return i + 2  # Past the end is harmless; the caller re-checks bounds.
+
+
+def _drop_trailing_comma(out: list[str]) -> None:
+    """Remove a trailing comma before a closing bracket, ignoring whitespace."""
+    last = len(out) - 1
+    while last >= 0 and out[last] in _WHITESPACE:
+        last -= 1
+    if last >= 0 and out[last] == ",":
+        del out[last]
+
+
+def strip_jsonc(text: str) -> str:
+    """Remove comments and trailing commas from JSONC ``text``.
+
+    The scan is string-aware: characters inside double-quoted strings (and their
+    backslash escapes) are copied verbatim, so comment markers or commas that
+    appear inside string values are left untouched. The function is total and
+    never raises; validating the result is left to the caller's ``json.loads``.
+    """
+    out: list[str] = []
+    i = 0
+    length = len(text)
+
+    while i < length:
+        char = text[i]
+        if char == '"':
+            i = _copy_string(text, i, out)
+        elif char == "/" and text.startswith("//", i):
+            i = _skip_line_comment(text, i)
+        elif char == "/" and text.startswith("/*", i):
+            i = _skip_block_comment(text, i)
+        elif char in "}]":
+            _drop_trailing_comma(out)
+            out.append(char)
+            i += 1
+        else:
+            out.append(char)
+            i += 1
+
+    return "".join(out)

src/sp_repo_review/checks/dependencies.py

@@ -41,7 +41,9 @@ def check(dependabot: dict[str, Any], renovate: dict[str, Any]) -> bool:
         }}
         ```
         Renovate configurations in `package.json` are not supported.
-        Configurations in `.jsonc` or `.json5` files are not fully supported.
+        `.jsonc` files (and `.json5` files that only use comments or trailing
+        commas) are supported out of the box. Full JSON5 configs require the
+        optional `json5` dependency (`pip install sp-repo-review[json5]`).
         """
         return bool(dependabot or renovate)
 

src/sp_repo_review/checks/renovate.py

@@ -8,6 +8,7 @@
 from typing import TYPE_CHECKING, Any
 
 from . import mk_url
+from ._jsonc import strip_jsonc
 
 if TYPE_CHECKING:
     from .._compat.importlib.resources.abc import Traversable
@@ -35,14 +36,31 @@ def renovate(root: Traversable) -> dict[str, Any]:
     renovate_paths = [root.joinpath(f) for f in SUPPORTED_RENOVATE_FILES]
 
     for renovate_path in renovate_paths:
-        if renovate_path.is_file():
-            with renovate_path.open() as f:
-                try:
-                    result: dict[str, Any] = json.load(f)
-                except json.JSONDecodeError:
-                    continue
-                else:
-                    return result
+        if not renovate_path.is_file():
+            continue
+        with renovate_path.open() as f:
+            text = f.read()
+        try:
+            # Handles JSON and JSONC (comments / trailing commas) with no
+            # dependency, plus JSON5 files that use only those features.
+            result: dict[str, Any] = json.loads(strip_jsonc(text))
+        except json.JSONDecodeError:
+            # Full JSON5 (single quotes, unquoted keys, ...) needs a real
+            # parser, provided by the optional json5 extra.
+            try:
+                import json5  # noqa: PLC0415
+            except ImportError:
+                msg = (
+                    f"{renovate_path} could not be parsed as JSON/JSONC and needs "
+                    "full JSON5 support. Install the extra: "
+                    "pip install sp-repo-review[json5]"
+                )
+                raise ImportError(msg) from None
+            try:
+                result = json5.loads(text)
+            except ValueError:
+                continue
+        return result
     return {}
 
 
@@ -69,7 +87,9 @@ def check(renovate: dict[str, Any]) -> bool | None:
         ```
 
         Renovate configurations in `package.json` are not supported.
-        Configurations in `.jsonc` or `.json5` files are not fully supported.
+        `.jsonc` files (and `.json5` files that only use comments or trailing
+        commas) are supported out of the box. Full JSON5 configs require the
+        optional `json5` dependency (`pip install sp-repo-review[json5]`).
         """
         if not renovate:
             return None

tests/test_renovate.py

@@ -1,5 +1,131 @@
+import json
+import sys
+
+import pytest
+from repo_review.ghpath import GHPath
 from repo_review.testing import compute_check
 
+from sp_repo_review.checks._jsonc import strip_jsonc
+from sp_repo_review.checks.renovate import renovate
+
+# Real-world Renovate configs, one per supported format/location, pinned to a
+# specific commit so upstream edits cannot break this. Skipped by default
+# (network access, GitHub rate limits); run manually to confirm coverage.
+REAL_WORLD_CONFIGS = [
+    (
+        "gulfofmaine/climatology_py_dash",
+        "e4ead74d17d7c07dbb40b9c99fc1138f927abdd3",
+        "renovate.json",
+    ),
+    (
+        "jumpstarter-dev/jumpstarter",
+        "8bae226d0a2d9cbe156bded24628e85c6d9f6cd9",
+        "renovate.jsonc",
+    ),
+    (
+        "SonarSource/docker-sonarqube",
+        "9f00ce57d8654a3737ae0b22997d7198f71660d8",
+        "renovate.json5",
+    ),
+    (
+        "adobe/spectrum-css",
+        "37620864c60c4c142a506017e1a15348a26abb0e",
+        ".github/renovate.json",
+    ),
+    (
+        "paddyroddy/.github",
+        "c97ca7c448df211268616ce438777228fe103733",
+        ".renovaterc.json5",
+    ),
+    (
+        "zammad/zammad",
+        "93fb7f107b07b4b4294e21249b277bc48c431da5",
+        ".gitlab/renovate.json",
+    ),
+    (
+        "prettier/eslint-config-prettier",
+        "07829b4912d173986610a4985247896b09f9fcaf",
+        ".renovaterc",
+    ),
+    (
+        "Esri/calcite-design-system",
+        "5613d9f8000ba12bf55c7da50e2f119c12435302",
+        ".renovaterc.json",
+    ),
+]
+
+
+def test_strip_jsonc_line_comment() -> None:
+    text = '{\n  // a comment\n  "a": 1 // trailing\n}'
+    assert json.loads(strip_jsonc(text)) == {"a": 1}
+
+
+def test_strip_jsonc_block_comment() -> None:
+    text = '{\n  /* multi\n     line */ "a": 1\n}'
+    assert json.loads(strip_jsonc(text)) == {"a": 1}
+
+
+def test_strip_jsonc_preserves_string_content() -> None:
+    # Comment markers and commas inside strings must survive untouched.
+    text = '{"url": "https://x/y", "csv": "a,b,", "block": "/* not a comment */"}'
+    assert json.loads(strip_jsonc(text)) == {
+        "url": "https://x/y",
+        "csv": "a,b,",
+        "block": "/* not a comment */",
+    }
+
+
+def test_strip_jsonc_escaped_quote_in_string() -> None:
+    text = r'{"a": "she said \"hi\" // ok"}'
+    assert json.loads(strip_jsonc(text)) == {"a": 'she said "hi" // ok'}
+
+
+def test_strip_jsonc_trailing_commas() -> None:
+    text = '{\n  "a": [1, 2, 3,],\n  "b": {"c": 1,},\n}'
+    assert json.loads(strip_jsonc(text)) == {"a": [1, 2, 3], "b": {"c": 1}}
+
+
+def test_strip_jsonc_plain_json_unchanged() -> None:
+    text = '{"a": 1, "b": [1, 2]}'
+    assert strip_jsonc(text) == text
+
+
+def test_renovate_fixture_jsonc(tmp_path) -> None:
+    (tmp_path / "renovate.jsonc").write_text(
+        '{\n  // pin digests\n  "extends": ["config:recommended"],\n}',
+        encoding="utf-8",
+    )
+    assert renovate(tmp_path) == {"extends": ["config:recommended"]}
+
+
+def test_renovate_fixture_json5_fallback(tmp_path) -> None:
+    pytest.importorskip("json5")
+    # Unquoted keys are true JSON5 and cannot be stripped to plain JSON.
+    (tmp_path / "renovate.json5").write_text(
+        '{\n  extends: ["config:recommended"],\n}',
+        encoding="utf-8",
+    )
+    assert renovate(tmp_path) == {"extends": ["config:recommended"]}
+
+
+def test_renovate_fixture_json5_missing_errors(tmp_path, monkeypatch) -> None:
+    (tmp_path / "renovate.json5").write_text(
+        '{\n  extends: ["config:recommended"],\n}',
+        encoding="utf-8",
+    )
+    # Simulate the json5 extra not being installed.
+    monkeypatch.setitem(sys.modules, "json5", None)
+    with pytest.raises(ImportError, match=r"sp-repo-review\[json5\]"):
+        renovate(tmp_path)
+
+
+@pytest.mark.skip(reason="Network access, can be rate limited")
+@pytest.mark.parametrize(("repo", "sha", "location"), REAL_WORLD_CONFIGS)
+def test_renovate_real_world(repo, sha, location) -> None:
+    root = GHPath(repo=repo, branch=sha)
+    assert root.joinpath(location).is_file()
+    assert renovate(root)
+
 
 def test_ren200() -> None:
     renovate = {"extends": ["config:recommended"]}