code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/repository/rule_changes.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from operator import itemgetter
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Final, Literal, TypedDict
+
+from sarj_standards.libs.release.process import ProcessRunner, run_process
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+SCHEMA_VERSION: Final = 1
+_INVENTORY_PATH: Final = "packages/standards/src/sarj_standards/configs/rule-inventory.v1.json"
+_CATALOG_PATH: Final = "packages/standards/src/sarj_standards/schemas/rule-catalog.v1.json"
+_ENGINE_BY_FAMILY: Final = MappingProxyType(
+    {
+        "typescript": "eslint",
+        "iac": "iac",
+        "python": "python",
+        "sql": "sql",
+        "text": "text",
+    }
+)
+_RELEASE_TARGET_BY_ENGINE: Final = MappingProxyType(
+    {
+        "eslint": "typescript",
+        "iac": "iac",
+        "python": "python",
+        "sql": "sql",
+        "text": "standards",
+    }
+)
+_POLICY_FIELDS: Final = frozenset({"defaultLevel", "optionsSchema"})
+_INVENTORY_ENTRY_FIELDS: Final = frozenset({"code", "family", "id", "source", "test"})
+_GIT_SHA_LENGTH: Final = 40
+
+
+class RuleDescriptorV1(TypedDict):
+    key: str
+    engine: str
+    family: str
+    id: str
+    code: str | None
+    defaultLevel: str
+    releaseTarget: str
+    source: str
+    test: str
+
+
+type ChangeKind = Literal["added", "removed", "implementation-changed", "policy-changed"]
+
+
+class RuleChangeV1(TypedDict):
+    kind: ChangeKind
+    key: str
+    releaseTarget: str
+    before: RuleDescriptorV1 | None
+    after: RuleDescriptorV1 | None
+
+
+class RuleChangeSetV1(TypedDict):
+    schemaVersion: int
+    beforeSha: str
+    afterSha: str
+    changedSelectors: list[str]
+    changeSetDigest: str
+    changes: list[RuleChangeV1]
+
+
+class _RevisionRules(TypedDict):
+    descriptors: dict[str, RuleDescriptorV1]
+    catalog: dict[str, dict[str, object]]
+    implementation_blobs: dict[str, tuple[str, str]]
+
+
+def compare(
+    root: Path,
+    *,
+    before: str,
+    after: str,
+    runner: ProcessRunner = run_process,
+) -> RuleChangeSetV1:
+    resolved = root.resolve()
+    before_sha = _resolve_revision(resolved, before, runner=runner)
+    after_sha = _resolve_revision(resolved, after, runner=runner)
+    old = _load_revision(resolved, before_sha, runner=runner)
+    new = _load_revision(resolved, after_sha, runner=runner)
+    changes: list[RuleChangeV1] = []
+    for key in sorted(old["descriptors"].keys() | new["descriptors"].keys()):
+        old_descriptor = old["descriptors"].get(key)
+        new_descriptor = new["descriptors"].get(key)
+        if old_descriptor is None:
+            changes.append(_change("added", key, None, new_descriptor))
+            continue
+        if new_descriptor is None:
+            changes.append(_change("removed", key, old_descriptor, None))
+            continue
+        old_catalog = old["catalog"][key]
+        new_catalog = new["catalog"][key]
+        if any(old_catalog.get(field) != new_catalog.get(field) for field in _POLICY_FIELDS):
+            changes.append(_change("policy-changed", key, old_descriptor, new_descriptor))
+        if (
+            _implementation_projection(old_catalog) != _implementation_projection(new_catalog)
+            or old["implementation_blobs"][key] != new["implementation_blobs"][key]
+        ):
+            changes.append(_change("implementation-changed", key, old_descriptor, new_descriptor))
+    changes.sort(key=itemgetter("key", "kind"))
+    changed_selectors = sorted({change["key"] for change in changes})
+    identity: dict[str, object] = {
+        "schemaVersion": SCHEMA_VERSION,
+        "beforeSha": before_sha,
+        "afterSha": after_sha,
+        "changedSelectors": changed_selectors,
+        "changes": changes,
+    }
+    digest = hashlib.sha256(
+        json.dumps(identity, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode()
+    ).hexdigest()
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "beforeSha": before_sha,
+        "afterSha": after_sha,
+        "changedSelectors": changed_selectors,
+        "changeSetDigest": digest,
+        "changes": changes,
+    }
+
+
+def _change(
+    kind: ChangeKind,
+    key: str,
+    before: RuleDescriptorV1 | None,
+    after: RuleDescriptorV1 | None,
+) -> RuleChangeV1:
+    current = after if after is not None else before
+    if current is None:  # pragma: no cover - compare only emits changes with at least one descriptor
+        msg = "a rule change must contain a before or after descriptor"
+        raise ValueError(msg)
+    return {
+        "kind": kind,
+        "key": key,
+        "releaseTarget": current["releaseTarget"],
+        "before": before,
+        "after": after,
+    }
+
+
+def _implementation_projection(rule: dict[str, object]) -> dict[str, object]:
+    return {key: value for key, value in rule.items() if key not in _POLICY_FIELDS}
+
+
+def _resolve_revision(root: Path, revision: str, *, runner: ProcessRunner) -> str:
+    if not revision:
+        msg = "rule comparison revisions must not be empty"
+        raise ValueError(msg)
+    result = runner(("git", "rev-parse", "--verify", f"{revision}^{{commit}}"), cwd=root, capture_output=True)
+    sha = result.stdout.strip()
+    if len(sha) != _GIT_SHA_LENGTH or any(character not in "0123456789abcdef" for character in sha):
+        msg = f"git did not resolve {revision!r} to a full lowercase commit SHA"
+        raise ValueError(msg)
+    return sha
+
+
+def _load_revision(  # ruff: ignore[too-many-locals] -- validates and joins two generated wire artifacts.
+    root: Path,
+    sha: str,
+    *,
+    runner: ProcessRunner,
+) -> _RevisionRules:
+    inventory = _git_json(root, sha, _INVENTORY_PATH, runner=runner)
+    catalog = _git_json(root, sha, _CATALOG_PATH, runner=runner)
+    inventory_entries = _rules_array(inventory, label="rule inventory")
+    catalog_entries = _rules_array(catalog, label="rule catalog")
+
+    inventory_by_key: dict[str, dict[str, object]] = {}
+    for index, raw in enumerate(inventory_entries, start=1):
+        entry = _object(raw, label=f"rule inventory entry {index}")
+        if frozenset(entry) != _INVENTORY_ENTRY_FIELDS:
+            msg = f"rule inventory entry {index} has unexpected or missing fields"
+            raise ValueError(msg)
+        family = _string(entry, "family")
+        try:
+            engine = _ENGINE_BY_FAMILY[family]
+        except KeyError as exc:
+            msg = f"rule inventory entry {index} has unknown family {family!r}"
+            raise ValueError(msg) from exc
+        rule_id = _string(entry, "id")
+        key = f"{engine}:{rule_id}"
+        if key in inventory_by_key:
+            msg = f"rule inventory repeats {key}"
+            raise ValueError(msg)
+        inventory_by_key[key] = entry
+
+    catalog_by_key: dict[str, dict[str, object]] = {}
+    for index, raw in enumerate(catalog_entries, start=1):
+        entry = _object(raw, label=f"rule catalog entry {index}")
+        key = _string(entry, "key")
+        engine = _string(entry, "engine")
+        rule_id = _string(entry, "id")
+        if key != f"{engine}:{rule_id}" or engine not in _RELEASE_TARGET_BY_ENGINE:
+            msg = f"rule catalog entry {index} has inconsistent key/engine/id"
+            raise ValueError(msg)
+        if key in catalog_by_key:
+            msg = f"rule catalog repeats {key}"
+            raise ValueError(msg)
+        catalog_by_key[key] = entry
+
+    if inventory_by_key.keys() != catalog_by_key.keys():
+        missing_catalog = sorted(inventory_by_key.keys() - catalog_by_key.keys())
+        missing_inventory = sorted(catalog_by_key.keys() - inventory_by_key.keys())
+        msg = (
+            "rule inventory/catalog disagreement"
+            f"; missing catalog: {', '.join(missing_catalog) or '-'}"
+            f"; missing inventory: {', '.join(missing_inventory) or '-'}"
+        )
+        raise ValueError(msg)
+
+    descriptors: dict[str, RuleDescriptorV1] = {}
+    implementation_blobs: dict[str, tuple[str, str]] = {}
+    for key in sorted(inventory_by_key):
+        inventory_entry = inventory_by_key[key]
+        catalog_entry = catalog_by_key[key]
+        family = _string(inventory_entry, "family")
+        engine = _ENGINE_BY_FAMILY[family]
+        catalog_code = catalog_entry.get("code")
+        if catalog_code is not None and not isinstance(catalog_code, str):
+            msg = f"rule catalog {key} has invalid code"
+            raise TypeError(msg)
+        inventory_code = _string(inventory_entry, "code")
+        if catalog_code is not None and inventory_code != catalog_code:
+            msg = f"rule inventory/catalog disagreement for {key}: code differs"
+            raise ValueError(msg)
+        descriptors[key] = {
+            "key": key,
+            "engine": engine,
+            "family": family,
+            "id": _string(inventory_entry, "id"),
+            "code": catalog_code,
+            "defaultLevel": _string(catalog_entry, "defaultLevel"),
+            "releaseTarget": _RELEASE_TARGET_BY_ENGINE[engine],
+            "source": _string(inventory_entry, "source"),
+            "test": _string(inventory_entry, "test"),
+        }
+        implementation_blobs[key] = (
+            _git_blob_oid(root, sha, descriptors[key]["source"], runner=runner),
+            _git_blob_oid(root, sha, descriptors[key]["test"], runner=runner),
+        )
+    return {
+        "descriptors": descriptors,
+        "catalog": catalog_by_key,
+        "implementation_blobs": implementation_blobs,
+    }
+
+
+def _git_blob_oid(root: Path, sha: str, path: str, *, runner: ProcessRunner) -> str:
+    if path.startswith("/") or ".." in path.split("/"):
+        msg = f"rule implementation path must be repository-relative: {path!r}"
+        raise ValueError(msg)
+    result = runner(("git", "rev-parse", "--verify", f"{sha}:{path}"), cwd=root, capture_output=True)
+    oid = result.stdout.strip()
+    if len(oid) != _GIT_SHA_LENGTH or any(character not in "0123456789abcdef" for character in oid):
+        msg = f"git did not resolve rule implementation {path!r} at {sha} to a blob"
+        raise ValueError(msg)
+    return oid
+
+
+def _git_json(root: Path, sha: str, path: str, *, runner: ProcessRunner) -> dict[str, object]:
+    result = runner(("git", "show", f"{sha}:{path}"), cwd=root, capture_output=True)
+    try:
+        payload: object = json.loads(result.stdout)  # pyright: ignore[reportAny]
+    except json.JSONDecodeError as exc:
+        msg = f"{path} at {sha} is not valid JSON"
+        raise ValueError(msg) from exc
+    return _object(payload, label=path)
+
+
+def _rules_array(document: dict[str, object], *, label: str) -> list[object]:
+    if document.get("schemaVersion") != 1 or set(document) != {"schemaVersion", "rules"}:
+        msg = f"{label} must contain exactly schemaVersion 1 and rules"
+        raise ValueError(msg)
+    rules = document["rules"]
+    if not isinstance(rules, list):
+        msg = f"{label} rules must be an array"
+        raise TypeError(msg)
+    return rules  # pyright: ignore[reportUnknownVariableType]
+
+
+def _object(value: object, *, label: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        msg = f"{label} must be an object"
+        raise TypeError(msg)
+    if not all(isinstance(key, str) for key in value):  # pyright: ignore[reportUnknownVariableType]
+        msg = f"{label} must have string keys"
+        raise TypeError(msg)
+    return value  # pyright: ignore[reportUnknownVariableType]
+
+
+def _string(value: dict[str, object], key: str) -> str:
+    item = value.get(key)
+    if not isinstance(item, str) or not item:
+        msg = f"rule field {key} must be a non-empty string"
+        raise TypeError(msg)
+    return item
+
+
+def render_text(result: RuleChangeSetV1) -> str:
+    lines = [f"rules {result['beforeSha']}..{result['afterSha']}"]
+    lines.extend(f"{item['kind']}: {item['key']}" for item in result["changes"])
+    if not result["changes"]:
+        lines.append("no rule changes")
+    return "\n".join(lines)
+
+
+__all__ = ["RuleChangeSetV1", "RuleChangeV1", "RuleDescriptorV1", "compare", "render_text"]

sarj_standards/libs/repository/rule_inventory_artifact.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path, PurePosixPath
+from typing import Final, TypedDict, TypeGuard
+
+from sarj_standards._meta import CONFIGS_DIR
+
+
+SCHEMA_VERSION: Final = 1
+RULE_INVENTORY_PATH: Final = CONFIGS_DIR / "rule-inventory.v1.json"
+_REPOSITORY_INVENTORY_PATH: Final = Path("packages/standards/src/sarj_standards/configs/rule-inventory.v1.json")
+_RULE_FIELDS: Final = frozenset({"family", "id", "code", "source", "test"})
+
+
+@dataclass(frozen=True, slots=True)
+class InventorySyncResult:
+    status: int
+    message: str
+
+
+class RuleInventoryEntry(TypedDict):
+    family: str
+    id: str
+    code: str
+    source: str
+    test: str
+
+
+class RuleInventory(TypedDict):
+    schemaVersion: int
+    rules: list[RuleInventoryEntry]
+
+
+def _is_object(value: object) -> TypeGuard[dict[str, object]]:
+    return isinstance(value, dict)
+
+
+def validate(value: object) -> RuleInventory:
+    if not _is_object(value) or frozenset(value) != frozenset({"schemaVersion", "rules"}):
+        msg = "rule inventory must contain exactly schemaVersion and rules"
+        raise ValueError(msg)
+    if value["schemaVersion"] != SCHEMA_VERSION:
+        msg = f"unsupported rule inventory schemaVersion: {value['schemaVersion']!r}; expected {SCHEMA_VERSION}"
+        raise ValueError(msg)
+    raw_rules = value["rules"]
+    if not _is_array(raw_rules):
+        msg = "rule inventory rules must be an array"
+        raise ValueError(msg)
+
+    rules = [_validated_rule(rule, index=index) for index, rule in enumerate(raw_rules, start=1)]
+    keys = [(rule["family"], rule["id"]) for rule in rules]
+    if keys != sorted(keys):
+        msg = "rule inventory entries must be sorted by family and id"
+        raise ValueError(msg)
+    if len(keys) != len(set(keys)):
+        msg = "rule inventory contains duplicate family/id entries"
+        raise ValueError(msg)
+    return {"schemaVersion": SCHEMA_VERSION, "rules": rules}
+
+
+def _is_array(value: object) -> TypeGuard[list[object]]:
+    return isinstance(value, list)
+
+
+def _validated_rule(value: object, *, index: int) -> RuleInventoryEntry:
+    if not _is_object(value) or frozenset(value) != _RULE_FIELDS:
+        msg = f"rule inventory entry {index} must contain exactly: {', '.join(sorted(_RULE_FIELDS))}"
+        raise ValueError(msg)
+
+    fields: dict[str, str] = {}
+    for field in _RULE_FIELDS:
+        item = value[field]
+        if not isinstance(item, str) or not item:
+            msg = f"rule inventory entry {index} has invalid {field}"
+            raise ValueError(msg)
+        fields[field] = item
+
+    return {
+        "family": fields["family"],
+        "id": fields["id"],
+        "code": fields["code"],
+        "source": _relative_repository_path(fields["source"], field="source", index=index),
+        "test": _relative_repository_path(fields["test"], field="test", index=index),
+    }
+
+
+def _relative_repository_path(value: str, *, field: str, index: int) -> str:
+    path = PurePosixPath(value)
+    if not value or "\\" in value or path.is_absolute() or ".." in path.parts or path.as_posix() != value:
+        msg = f"rule inventory entry {index} has invalid {field}: {value!r}"
+        raise ValueError(msg)
+    return value
+
+
+def load(path: Path = RULE_INVENTORY_PATH) -> RuleInventory:
+    try:
+        payload: object = json.loads(path.read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+    except (OSError, json.JSONDecodeError) as exc:
+        msg = f"cannot load shipped rule inventory {path}: {exc}"
+        raise ValueError(msg) from exc
+    return validate(payload)
+
+
+def build(root: Path) -> RuleInventory:
+    from sarj_standards.libs.repository import rule_maintenance  # ruff: ignore[import-outside-top-level]
+
+    return validate({"schemaVersion": SCHEMA_VERSION, "rules": rule_maintenance.inventory(root)})
+
+
+def render(root: Path) -> str:
+    return (
+        json.dumps(
+            build(root),
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+        + "\n"
+    )
+
+
+def sync(root: Path, *, check: bool) -> InventorySyncResult:
+    from sarj_standards.libs.adoption import transaction  # ruff: ignore[import-outside-top-level]
+
+    destination = root.resolve() / _REPOSITORY_INVENTORY_PATH
+    expected = render(root)
+    try:
+        current = destination.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        current = ""
+
+    if current == expected:
+        return InventorySyncResult(0, "ok: rule-inventory.v1.json matches live registries")
+    if check:
+        return InventorySyncResult(
+            1,
+            "drift: rule-inventory.v1.json differs from live registries; run `code-standards maintain rules sync`",
+        )
+    transaction.atomic_write_text(root.resolve(), destination, expected)
+    return InventorySyncResult(0, "updated: rule-inventory.v1.json")

sarj_standards/libs/repository/rule_lifecycle.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from difflib import get_close_matches
+import json
+from pathlib import Path
+from types import MappingProxyType
+from typing import Final, TypeGuard
+
+from sarj_standards.libs.adoption import transaction
+from sarj_standards.libs.repository import rule_catalog_artifact, rule_inventory_artifact, rule_maintenance
+from sarj_standards.libs.rules import RuleEngine, RuleId, RuleSelector
+
+
+_WARNING_PATH: Final = Path("packages/standards/src/sarj_standards/configs/rule-warning-levels.v1.json")
+_INVENTORY_PATH: Final = Path("packages/standards/src/sarj_standards/configs/rule-inventory.v1.json")
+_CATALOG_PATH: Final = Path("packages/standards/src/sarj_standards/schemas/rule-catalog.v1.json")
+_LEDGER_PATH: Final = Path("packages/standards/src/sarj_standards/configs/rule-ledger.json")
+_ENGINE_BY_FAMILY: Final = MappingProxyType(
+    {
+        "typescript": RuleEngine.ESLINT,
+        "iac": RuleEngine.IAC,
+        "python": RuleEngine.PYTHON,
+        "sql": RuleEngine.SQL,
+        "text": RuleEngine.TEXT,
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class StageResult:
+    status: int
+    changed: bool
+    message: str
+
+
+def stage_warning(root: Path, selector: RuleSelector, *, check: bool = False) -> StageResult:
+    repository = root.resolve()
+    inventory = rule_inventory_artifact.build(repository)
+    known = {
+        RuleSelector(_ENGINE_BY_FAMILY[entry["family"]], RuleId(entry["id"]))
+        for entry in inventory["rules"]
+        if entry["family"] in _ENGINE_BY_FAMILY
+    }
+    if selector not in known:
+        raise ValueError(_unknown_selector_message(selector, known))
+
+    # Building before mutation proves source-owned metadata/examples are complete.
+    _ = rule_catalog_artifact.build(repository)
+    warning_path = repository / _WARNING_PATH
+    selected = set(_load(warning_path))
+    already_staged = selector in selected
+    selected.add(selector)
+    rendered = _render(selected)
+    warning_current = warning_path.read_text(encoding="utf-8") == rendered
+    derived_current = _derived_current(repository) if already_staged and warning_current else False
+    if already_staged and warning_current and derived_current:
+        return StageResult(status=0, changed=False, message=f"ok: {selector} is already warning-stage")
+    if check:
+        return StageResult(
+            status=1,
+            changed=False,
+            message=(
+                f"drift: synchronize derived artifacts for warning-stage {selector}"
+                if already_staged
+                else f"drift: stage {selector} as warning before publication"
+            ),
+        )
+
+    managed = (_WARNING_PATH, _INVENTORY_PATH, _CATALOG_PATH, _LEDGER_PATH)
+    paths = tuple(repository / path for path in managed)
+    mutation = transaction.FileTransaction.capture(repository, paths)
+    try:
+        if not warning_current:
+            transaction.atomic_write_text(repository, warning_path, rendered)
+            mutation.mark_written(warning_path)
+        _synchronize(repository, mutation)
+    except BaseException:
+        rollback = mutation.rollback()
+        if not rollback.ok:
+            msg = rollback.render() or "rule lifecycle rollback was incomplete"
+            raise RuntimeError(msg) from None
+        raise
+    return StageResult(
+        status=0,
+        changed=True,
+        message=(
+            f"synchronized: warning lifecycle and derived artifacts for {selector}"
+            if already_staged
+            else f"staged: {selector} will ship at warning level"
+        ),
+    )
+
+
+def _render(selectors: set[RuleSelector]) -> str:
+    return (
+        json.dumps(
+            {"schemaVersion": 1, "rules": sorted(str(item) for item in selectors)},
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+        + "\n"
+    )
+
+
+def _unknown_selector_message(selector: RuleSelector, known: set[RuleSelector]) -> str:
+    requested = str(selector)
+    suggestion = get_close_matches(requested, (str(item) for item in known), n=1, cutoff=0.6)
+    if suggestion:
+        return f"unknown live rule selector: {requested}; did you mean {suggestion[0]}?"
+    return f"unknown live rule selector: {requested}; run `code-standards maintain rules manifest` to list selectors"
+
+
+def _derived_current(repository: Path) -> bool:
+    results = (
+        rule_inventory_artifact.sync(repository, check=True),
+        rule_maintenance.sync_ledger(repository, check=True),
+        rule_catalog_artifact.sync(repository, check=True),
+    )
+    return all(result.status == 0 for result in results)
+
+
+def _synchronize(repository: Path, mutation: transaction.FileTransaction) -> None:
+    operations = (
+        (rule_maintenance.sync_ledger, repository / _LEDGER_PATH),
+        (rule_inventory_artifact.sync, repository / _INVENTORY_PATH),
+        (rule_catalog_artifact.sync, repository / _CATALOG_PATH),
+    )
+    for operation, path in operations:
+        result = operation(repository, check=False)
+        mutation.mark_written(path)
+        if result.status != 0:
+            msg = f"could not synchronize derived rule artifact: {path}"
+            raise RuntimeError(msg)
+
+
+def _load(path: Path) -> tuple[RuleSelector, ...]:
+    payload: object = json.loads(path.read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+    if not _is_object(payload):
+        msg = "rule warning lifecycle must contain exactly schemaVersion and rules"
+        raise TypeError(msg)
+    if set(payload) != {"schemaVersion", "rules"}:
+        msg = "rule warning lifecycle must contain exactly schemaVersion and rules"
+        raise ValueError(msg)
+    rules = payload.get("rules")
+    if payload.get("schemaVersion") != 1 or not _is_array(rules):
+        msg = "rule warning lifecycle must use schemaVersion 1 and a rules array"
+        raise ValueError(msg)
+    values = rules
+    if any(not isinstance(value, str) or not value for value in values):
+        msg = "rule warning lifecycle must contain unique non-empty selectors"
+        raise ValueError(msg)
+    selectors = tuple(RuleSelector.parse(value) for value in values if isinstance(value, str))
+    if len(set(selectors)) != len(selectors):
+        msg = "rule warning lifecycle must contain unique non-empty selectors"
+        raise ValueError(msg)
+    return selectors
+
+
+def _is_object(value: object) -> TypeGuard[dict[str, object]]:
+    # JSON object keys are strings by definition.
+    return isinstance(value, dict)
+
+
+def _is_array(value: object) -> TypeGuard[list[object]]:
+    return isinstance(value, list)