metrolith 4.0.0__py3-none-any.whl

archlens_json.py

@@ -0,0 +1,489 @@
+"""Neutral bounded JSON input and output for external ArchLens documents.
+
+This module deliberately has no dependency on Policy, Ratchet, CLI, or the
+validation package.  Those domains translate :class:`StrictJsonError` into
+their own public error types while sharing one byte-exact JSON boundary.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class StrictJsonLimits:
+    """Resource limits applied before and after JSON decoding."""
+
+    max_bytes: int
+    max_depth: int
+    max_collection_items: int
+    max_total_items: int
+    max_string_bytes: int
+
+
+POLICY_JSON_LIMITS = StrictJsonLimits(
+    max_bytes=4 * 1024 * 1024,
+    max_depth=64,
+    max_collection_items=20_000,
+    max_total_items=100_000,
+    max_string_bytes=1 * 1024 * 1024,
+)
+BASELINE_JSON_LIMITS = StrictJsonLimits(
+    max_bytes=64 * 1024 * 1024,
+    max_depth=64,
+    max_collection_items=1_000_000,
+    max_total_items=2_000_000,
+    max_string_bytes=16 * 1024 * 1024,
+)
+EVIDENCE_JSON_LIMITS = StrictJsonLimits(
+    max_bytes=512 * 1024 * 1024,
+    max_depth=64,
+    max_collection_items=5_000_000,
+    max_total_items=10_000_000,
+    max_string_bytes=64 * 1024 * 1024,
+)
+CHECK_JSON_LIMITS = StrictJsonLimits(
+    max_bytes=512 * 1024 * 1024,
+    max_depth=64,
+    max_collection_items=5_000_000,
+    max_total_items=10_000_000,
+    max_string_bytes=64 * 1024 * 1024,
+)
+SARIF_JSON_LIMITS = CHECK_JSON_LIMITS
+ARTIFACT_JSON_LIMITS = EVIDENCE_JSON_LIMITS
+
+
+class StrictJsonError(ValueError):
+    """One bounded JSON admission or serialization failure."""
+
+    def __init__(
+        self,
+        code: str,
+        source: str,
+        message: str,
+        *,
+        location: str | None = None,
+        detail: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.source = source
+        self.message = message
+        self.location = location
+        self.detail = detail or {}
+
+    def __str__(self) -> str:
+        where = f" at {self.location}" if self.location else ""
+        return f"[{self.code}] {self.source}{where}: {self.message}"
+
+
+_UTF8_BOM = b"\xef\xbb\xbf"
+_UTF16_LE_BOM = b"\xff\xfe"
+_UTF16_BE_BOM = b"\xfe\xff"
+_UTF32_LE_BOM = b"\xff\xfe\x00\x00"
+_UTF32_BE_BOM = b"\x00\x00\xfe\xff"
+
+
+def read_bounded_bytes(
+    path: Path | str,
+    *,
+    source: str | None = None,
+    limits: StrictJsonLimits,
+) -> bytes:
+    """Read a regular external JSON payload without unbounded allocation."""
+
+    candidate = Path(path)
+    label = source or str(candidate)
+    try:
+        size = candidate.stat().st_size
+    except OSError as exc:
+        raise StrictJsonError(
+            "artifact_unreadable", label, f"cannot stat JSON input: {exc}"
+        ) from exc
+    if size > limits.max_bytes:
+        raise StrictJsonError(
+            "artifact_too_large",
+            label,
+            f"JSON input is {size} bytes; limit is {limits.max_bytes}",
+            detail={"actual_bytes": size, "max_bytes": limits.max_bytes},
+        )
+    try:
+        # The stat check gives an early, cheap rejection.  The bounded read is
+        # still required because an external file can grow between stat/open.
+        with candidate.open("rb") as handle:
+            payload = handle.read(limits.max_bytes + 1)
+    except OSError as exc:
+        raise StrictJsonError(
+            "artifact_unreadable", label, f"cannot read JSON input: {exc}"
+        ) from exc
+    _check_byte_count(payload, label, limits)
+    return payload
+
+
+def _check_byte_count(
+    payload: bytes, source: str, limits: StrictJsonLimits
+) -> None:
+    if len(payload) > limits.max_bytes:
+        raise StrictJsonError(
+            "artifact_too_large",
+            source,
+            f"JSON input is {len(payload)} bytes; limit is {limits.max_bytes}",
+            detail={"actual_bytes": len(payload), "max_bytes": limits.max_bytes},
+        )
+
+
+def decode_utf8(
+    payload: bytes,
+    *,
+    source: str,
+    limits: StrictJsonLimits,
+) -> str:
+    """Decode strict UTF-8 bytes without universal-newline translation."""
+
+    if not isinstance(payload, bytes):
+        raise StrictJsonError("invalid_input_type", source, "JSON input must be bytes")
+    _check_byte_count(payload, source, limits)
+    if payload.startswith(_UTF32_LE_BOM) or payload.startswith(_UTF32_BE_BOM):
+        raise StrictJsonError(
+            "unsupported_encoding", source, "UTF-32 JSON is not supported; use UTF-8"
+        )
+    if payload.startswith(_UTF16_LE_BOM) or payload.startswith(_UTF16_BE_BOM):
+        raise StrictJsonError(
+            "unsupported_encoding", source, "UTF-16 JSON is not supported; use UTF-8"
+        )
+    if payload.startswith(_UTF8_BOM):
+        raise StrictJsonError(
+            "unexpected_byte_order_mark", source, "a UTF-8 BOM is not permitted"
+        )
+    try:
+        return payload.decode("utf-8", errors="strict")
+    except UnicodeDecodeError as exc:
+        raise StrictJsonError(
+            "invalid_utf8",
+            source,
+            f"JSON input is not valid UTF-8: {exc.reason}",
+            location=f"byte offset {exc.start}",
+            detail={"byte_offset": exc.start},
+        ) from exc
+
+
+def _text_as_utf8(
+    text: str, *, source: str, limits: StrictJsonLimits
+) -> bytes:
+    if not isinstance(text, str):
+        raise StrictJsonError("invalid_input_type", source, "JSON input must be text")
+    if text.startswith("\ufeff"):
+        raise StrictJsonError(
+            "unexpected_byte_order_mark", source, "a Unicode BOM is not permitted"
+        )
+    try:
+        encoded = text.encode("utf-8", errors="strict")
+    except UnicodeEncodeError as exc:
+        raise StrictJsonError(
+            "invalid_utf8",
+            source,
+            "JSON text contains a value that cannot be encoded as UTF-8",
+            location=f"character offset {exc.start}",
+        ) from exc
+    _check_byte_count(encoded, source, limits)
+    return encoded
+
+
+def _check_text_depth(text: str, source: str, limit: int) -> None:
+    """Bound container nesting before ``json.loads`` can recurse."""
+
+    depth = 0
+    in_string = False
+    escaped = False
+    for offset, character in enumerate(text):
+        if in_string:
+            if escaped:
+                escaped = False
+            elif character == "\\":
+                escaped = True
+            elif character == '"':
+                in_string = False
+            continue
+        if character == '"':
+            in_string = True
+        elif character in "[{":
+            depth += 1
+            if depth > limit:
+                raise StrictJsonError(
+                    "json_depth_exceeded",
+                    source,
+                    f"JSON nesting exceeds the {limit} level limit",
+                    location=f"character offset {offset}",
+                    detail={"max_depth": limit},
+                )
+        elif character in "]}":
+            depth -= 1
+
+
+def _duplicate_hook(source: str):
+    def hook(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        for key, value in pairs:
+            if key in result:
+                raise StrictJsonError(
+                    "json_duplicate_key",
+                    source,
+                    f"duplicate JSON object key {key!r}",
+                    location=f"key {key!r}",
+                    detail={"key": key},
+                )
+            result[key] = value
+        return result
+
+    return hook
+
+
+def _constant_hook(source: str):
+    def reject(value: str) -> Any:
+        raise StrictJsonError(
+            "json_non_standard_number",
+            source,
+            f"{value} is not valid JSON; numbers must be finite",
+            detail={"constant": value},
+        )
+
+    return reject
+
+
+def _expected_name(expect: type | tuple[type, ...]) -> str:
+    if isinstance(expect, type):
+        return expect.__name__
+    return "/".join(item.__name__ for item in expect)
+
+
+def validate_json_value(
+    value: Any,
+    *,
+    source: str,
+    limits: StrictJsonLimits,
+    expect: type | tuple[type, ...] | None = None,
+) -> Any:
+    """Recursively enforce JSON types, finite numbers, and item bounds."""
+
+    if expect is not None and not isinstance(value, expect):
+        raise StrictJsonError(
+            "json_root_type_unexpected",
+            source,
+            f"root value is {type(value).__name__}, expected {_expected_name(expect)}",
+        )
+
+    stack: list[tuple[Any, int, str, bool]] = [(value, 1, "$", False)]
+    active_containers: set[int] = set()
+    total = 0
+    while stack:
+        item, depth, location, leaving = stack.pop()
+        if leaving:
+            active_containers.remove(id(item))
+            continue
+        total += 1
+        if total > limits.max_total_items:
+            raise StrictJsonError(
+                "json_item_count_exceeded",
+                source,
+                f"JSON value contains more than {limits.max_total_items} items",
+                location=location,
+                detail={"max_total_items": limits.max_total_items},
+            )
+        if item is None or isinstance(item, bool) or isinstance(item, int):
+            continue
+        if isinstance(item, float):
+            if not math.isfinite(item):
+                raise StrictJsonError(
+                    "json_non_standard_number",
+                    source,
+                    "JSON numbers must be finite",
+                    location=location,
+                )
+            continue
+        if isinstance(item, str):
+            if len(item) > limits.max_string_bytes:
+                raise StrictJsonError(
+                    "json_item_too_large",
+                    source,
+                    f"JSON string exceeds the {limits.max_string_bytes} byte limit",
+                    location=location,
+                )
+            try:
+                item_size = len(item.encode("utf-8", errors="strict"))
+            except UnicodeEncodeError as exc:
+                raise StrictJsonError(
+                    "invalid_utf8",
+                    source,
+                    "JSON string cannot be encoded as UTF-8",
+                    location=location,
+                ) from exc
+            if item_size > limits.max_string_bytes:
+                raise StrictJsonError(
+                    "json_item_too_large",
+                    source,
+                    f"JSON string is {item_size} bytes; limit is "
+                    f"{limits.max_string_bytes}",
+                    location=location,
+                )
+            continue
+        if isinstance(item, (dict, list)):
+            identity = id(item)
+            if identity in active_containers:
+                raise StrictJsonError(
+                    "json_circular_reference",
+                    source,
+                    "JSON value contains a circular reference",
+                    location=location,
+                )
+            if depth > limits.max_depth:
+                raise StrictJsonError(
+                    "json_depth_exceeded",
+                    source,
+                    f"JSON nesting exceeds the {limits.max_depth} level limit",
+                    location=location,
+                    detail={"max_depth": limits.max_depth},
+                )
+            active_containers.add(identity)
+            stack.append((item, depth, location, True))
+            if len(item) > limits.max_collection_items:
+                raise StrictJsonError(
+                    "json_collection_size_exceeded",
+                    source,
+                    f"JSON collection contains {len(item)} items; limit is "
+                    f"{limits.max_collection_items}",
+                    location=location,
+                )
+            if isinstance(item, dict):
+                children: list[tuple[Any, int, str, bool]] = []
+                for key, child in item.items():
+                    if not isinstance(key, str):
+                        raise StrictJsonError(
+                            "json_object_key_type_invalid",
+                            source,
+                            "JSON object keys must be strings",
+                            location=location,
+                        )
+                    children.append((key, depth, f"{location}.<key>", False))
+                    children.append((child, depth + 1, f"{location}.{key}", False))
+                stack.extend(reversed(children))
+            else:
+                for index in range(len(item) - 1, -1, -1):
+                    stack.append(
+                        (item[index], depth + 1, f"{location}[{index}]", False)
+                    )
+            continue
+        raise StrictJsonError(
+            "json_value_type_invalid",
+            source,
+            f"{type(item).__name__} is not a JSON value type",
+            location=location,
+        )
+    return value
+
+
+def loads_text(
+    text: str,
+    *,
+    source: str,
+    limits: StrictJsonLimits,
+    expect: type | tuple[type, ...] | None = dict,
+) -> Any:
+    """Parse bounded JSON text with duplicate-key and finite-number rejection."""
+
+    _text_as_utf8(text, source=source, limits=limits)
+    _check_text_depth(text, source, limits.max_depth)
+    try:
+        value = json.loads(
+            text,
+            object_pairs_hook=_duplicate_hook(source),
+            parse_constant=_constant_hook(source),
+        )
+    except json.JSONDecodeError as exc:
+        raise StrictJsonError(
+            "json_malformed",
+            source,
+            f"malformed JSON: {exc.msg}",
+            location=f"line {exc.lineno}, column {exc.colno}",
+            detail={"line": exc.lineno, "column": exc.colno},
+        ) from exc
+    return validate_json_value(value, source=source, limits=limits, expect=expect)
+
+
+def loads_bytes(
+    payload: bytes,
+    *,
+    source: str,
+    limits: StrictJsonLimits,
+    expect: type | tuple[type, ...] | None = dict,
+) -> Any:
+    text = decode_utf8(payload, source=source, limits=limits)
+    return loads_text(text, source=source, limits=limits, expect=expect)
+
+
+def load_file(
+    path: Path | str,
+    *,
+    source: str | None = None,
+    limits: StrictJsonLimits,
+    expect: type | tuple[type, ...] | None = dict,
+) -> Any:
+    label = source or str(path)
+    payload = read_bounded_bytes(path, source=label, limits=limits)
+    return loads_bytes(payload, source=label, limits=limits, expect=expect)
+
+
+def dumps_strict(
+    value: Any,
+    *,
+    source: str,
+    limits: StrictJsonLimits,
+    ensure_ascii: bool = False,
+    sort_keys: bool = True,
+    separators: tuple[str, str] | None = None,
+    indent: int | None = None,
+    trailing_newline: bool = False,
+) -> str:
+    """Serialize only bounded, recursively valid JSON with ``allow_nan=False``."""
+
+    validate_json_value(value, source=source, limits=limits)
+    try:
+        rendered = json.dumps(
+            value,
+            ensure_ascii=ensure_ascii,
+            sort_keys=sort_keys,
+            separators=separators,
+            indent=indent,
+            allow_nan=False,
+        )
+    except (TypeError, ValueError) as exc:
+        raise StrictJsonError(
+            "json_serialization_failed", source, f"cannot serialize JSON: {exc}"
+        ) from exc
+    if trailing_newline:
+        rendered += "\n"
+    encoded = _text_as_utf8(rendered, source=source, limits=limits)
+    _check_byte_count(encoded, source, limits)
+    return rendered
+
+
+__all__ = [
+    "ARTIFACT_JSON_LIMITS",
+    "BASELINE_JSON_LIMITS",
+    "CHECK_JSON_LIMITS",
+    "EVIDENCE_JSON_LIMITS",
+    "POLICY_JSON_LIMITS",
+    "SARIF_JSON_LIMITS",
+    "StrictJsonError",
+    "StrictJsonLimits",
+    "decode_utf8",
+    "dumps_strict",
+    "load_file",
+    "loads_bytes",
+    "loads_text",
+    "read_bounded_bytes",
+    "validate_json_value",
+]

config/__init__.py

@@ -0,0 +1 @@
+"""Packaged Metrolith policy data."""

config/exclusions.v1.json

@@ -0,0 +1,39 @@
+{
+  "version": "1.5.0",
+  "excluded_directories": [
+    ".git", ".gradle", ".hg", ".idea", ".mypy_cache", ".next",
+    ".nuxt", ".pytest_cache", ".svn", ".tox", ".venv", ".vscode",
+    "__pycache__", "bin", "bower_components", "build", "coverage",
+    "deps", "dist", "generated", "node_modules", "obj", "out",
+    "target", "third-party", "third_party", "vendor", "vendors", "venv"
+  ],
+  "dependency_directories": [
+    "bower_components", "deps", "node_modules", "third-party",
+    "third_party", "vendor", "vendors"
+  ],
+  "build_output_directories": [
+    ".next", ".nuxt", "bin", "build", "coverage", "dist", "obj", "out", "target"
+  ],
+  "cache_directories": [
+    ".gradle", ".mypy_cache", ".pytest_cache", ".tox", ".venv",
+    "__pycache__", "venv"
+  ],
+  "test_directories": [
+    "__tests__", "componenttest", "componenttests", "contracttest",
+    "contracttests", "e2e", "fixture", "fixtures", "functionaltest",
+    "functionaltests", "integration-test", "integration-tests",
+    "integrationtest", "integrationtests", "spec", "specs", "test",
+    "testdata", "tests", "unittest", "unittests"
+  ],
+  "generated_suffixes": [
+    ".gen.go", ".gen.java", ".gen.js", ".gen.jsx", ".gen.ts", ".gen.tsx",
+    ".generated.go", ".generated.java", ".generated.js", ".generated.jsx",
+    ".generated.ts", ".generated.tsx", ".generated.mjs", ".generated.cjs",
+    ".generated.mts", ".generated.cts", ".pb.go", ".pb.gw.go", "_generated.go"
+  ],
+  "minified_or_bundle_suffixes": [
+    ".bundle.js", ".bundle.mjs", ".bundle.cjs", ".bundle.ts", ".bundle.tsx",
+    ".bundle.min.js", ".chunk.js", ".chunk.mjs", ".min.js", ".min.mjs",
+    ".min.cjs", ".min.ts", ".min.tsx"
+  ]
+}

examples/README.md

@@ -0,0 +1,33 @@
+# Examples
+
+The beginner example is `local_project/app.py` and `local_project/web.js`.
+Use CPython 3.13 (`>=3.13,<3.14`; tested 3.13.9) and Git on PATH.
+Git is required even though these files are not a Git repository.
+Run it without network access after installation:
+
+```console
+metrolith example run --local
+```
+
+The command copies the packaged sources into controlled temporary storage and
+runs the normal analysis pipeline. Read the printed Run path and `summary.md`;
+`metrolith report RUN` creates an offline HTML report.
+
+From the source project you can use the same files directly:
+
+```console
+metrolith analyze examples/local_project --workspace ../metrolith-demo
+```
+
+`quickstart_repositories.csv` supports the existing optional `example run`
+language selections. It contains exact frozen commits; network access or an
+already populated cache is required. `input_template.csv` documents the CSV
+columns for explicit repository-list workflows and is not an offline demo.
+
+`ratchet-rules.json` is an illustrative rule array for `baseline capture`.
+Choose your own tolerance. Capture requires a qualifying exact-revision Run;
+the baseline's `.source-run/` sidecar and the current CLI ancestry limitation
+are explained in [USAGE](../docs/USAGE.md) in the source distribution.
+
+Start with the [source setup](../README.md); see [USAGE](../docs/USAGE.md)
+for quoted Run paths and the example wrapper's exit 1 on preflight refusal.

examples/__init__.py

@@ -0,0 +1 @@
+"""Packaged Metrolith quickstart inputs."""

examples/input_template.csv

@@ -0,0 +1,2 @@
+url,architecture_type,expected_language,commit_sha,enabled,notes
+https://github.com/owner/project,unknown,,,,Replace this demonstration URL before running

examples/local_project/app.py

@@ -0,0 +1,16 @@
+"""Small, deterministic Python half of the network-free tutorial fixture."""
+
+
+def classify_order(total: float, item_count: int) -> str:
+    if item_count <= 0:
+        return "empty"
+    if total >= 100 and item_count >= 3:
+        return "large"
+    if total >= 25:
+        return "medium"
+    return "small"
+
+
+def summarize_orders(orders: list[dict[str, float]]) -> dict[str, float]:
+    total = sum(float(order.get("total", 0)) for order in orders)
+    return {"count": len(orders), "total": total}

examples/local_project/web.js

@@ -0,0 +1,12 @@
+/** Small JavaScript half of the network-free tutorial fixture. */
+export function visibleOrders(orders, includeArchived = false) {
+  return orders.filter((order) => {
+    if (includeArchived) return true;
+    return order.status !== "archived";
+  });
+}
+
+export function orderLabel(order) {
+  const customer = order.customer || "Anonymous";
+  return `${customer}: ${order.status || "unknown"}`;
+}

examples/quickstart_repositories.csv

@@ -0,0 +1,5 @@
+url,architecture_type,expected_language,commit_sha,enabled,notes
+https://github.com/MstfTurgut/hotel-reservation-system,unknown,Java,0912d283fc54caadc361740e675271b0c69be336,true,Frozen Java tutorial
+https://github.com/googlecodelabs/monolith-to-microservices,unknown,JavaScript,deeb3099f6a29c0ec8b92a20013fdc94f69f0d47,true,Frozen JavaScript tutorial
+https://github.com/allegro/ralph,unknown,Python,f0d695e9b24a7d1fa475b81bbee87a897e389eb2,true,Frozen Python tutorial; Complete repository and Python metrics in candidate evidence
+https://github.com/golang-app/ecommerce,unknown,Go,5708b2b784f83825c2550abdc35d1d330e4b1283,true,Frozen Go tutorial

examples/ratchet-rules.json

@@ -0,0 +1,11 @@
+[
+  {
+    "rule_id": "ratchet.source-files",
+    "metric": "repository.source_files",
+    "metric_contract": "metrics",
+    "scope": "repository",
+    "direction": "increase_is_worse",
+    "max_regression": 0,
+    "severity": "violation"
+  }
+]