Tighten safejson conformance gate

Author: nripankadas07

.github/workflows/ci.yml

@@ -6,9 +6,13 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
-  test:
+  quality:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     strategy:
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
@@ -20,12 +24,25 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install pytest pytest-cov mypy ruff
-          pip install -e .
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install -e ".[dev]"
       - name: Run ruff
         run: ruff check .
       - name: Run pytest with coverage
         run: pytest --cov=safejson --cov-branch --cov-report=term-missing --cov-fail-under=100
       - name: Run mypy strict
         run: mypy --strict src/safejson
+      - name: Build distribution
+        if: matrix.python-version == '3.12'
+        run: python -m build
+      - name: Smoke installed wheel
+        if: matrix.python-version == '3.12'
+        run: |
+          python -m pip install --force-reinstall dist/safejson-*.whl
+          python - <<'PY'
+          import safejson
+
+          assert safejson.loads('{"ok": [1, true, null]}') == {
+              "ok": [1, True, None],
+          }
+          PY

CONTRIBUTING.md

@@ -1,19 +1,27 @@
 # Contributing
 
-Thanks for considering a contribution to `safejson`. Keep changes small, tested, and aligned with the existing public API.
+Thanks for considering a contribution to `safejson`. Keep changes
+small, tested, and aligned with the existing public API. This project
+parses hostile input, so correctness and honest documentation matter
+more than clever shortcuts.
 
 ## Local checks
 
 ```bash
-python -m pip install -e .
-python -m pip install pytest pytest-cov ruff
+python -m pip install -e ".[dev]"
 ruff check .
-pytest -q
+pytest --cov=safejson --cov-branch --cov-fail-under=100
+mypy --strict src/safejson
+python -m build
 ```
 
 ## Contribution rules
 
 - Add or update tests for behavior changes.
+- Keep branch coverage at 100%; new scanner branches need direct tests.
 - Keep README examples in sync with the implementation.
-- Keep runtime dependencies minimal and intentional.
+- Keep runtime dependencies at zero unless there is an exceptional reason.
 - Prefer explicit errors over surprising coercions.
+- Preserve the scanner/decode split: resource limits belong in the
+  iterative scanner, while duplicate-key and type policies belong in
+  decode hooks.

QUALITY.md

@@ -1,17 +1,42 @@
 # safejson quality bar
 
-This repository is part of a public portfolio, so the bar is practical correctness, clear documentation, and reproducible checks.
+This repository is part of a public portfolio, so the bar is practical
+correctness, clear documentation, and reproducible checks. For
+`safejson`, "quality" means the parser contract is precise enough for
+untrusted input, the public docs do not overclaim, and every policy is
+covered by executable tests.
 
 ## Required checks
 
-- `ruff check .` must pass with no ignored failures.
-- `pytest -q` must pass.
-- Packaging metadata must install the same source tree that tests exercise.
-- Public behavior changes must include happy-path, edge-case, and error tests.
+- `ruff check .` must pass with the full configured rule set.
+- `pytest --cov=safejson --cov-branch --cov-fail-under=100` must
+  keep line and branch coverage at 100%.
+- `mypy --strict src/safejson` must pass with no ignores added to hide
+  public API uncertainty.
+- The Python 3.9, 3.10, 3.11, and 3.12 GitHub Actions matrix must stay
+  green.
+- `python -m build` must produce installable wheel and sdist artifacts.
+- Public behavior changes must include happy-path, edge-case, and error
+  tests, plus docs updates when the API contract changes.
+
+## Parser contract
+
+- The streaming scanner must remain iterative; deeply nested hostile
+  input should raise `LimitExceededError`, not `RecursionError`.
+- Syntax, `allow_nan`, and every `Limits` ceiling must be enforced before
+  `json.loads` constructs containers.
+- Duplicate-key and type-whitelist behavior may rely on stdlib decode
+  hooks, but README wording must continue to make that phase boundary
+  explicit.
+- RFC 8259 conformance tests must compare ordinary valid values with
+  Python's stdlib and pin the deliberate differences: `NaN`/`Infinity`
+  rejection and duplicate-key rejection by default.
 
 ## Release checklist
 
 - Run the required checks locally.
 - Confirm GitHub Actions is green on the default branch.
 - Confirm Dependabot and secret scanning have no open alerts.
 - Confirm the README still describes the actual API and scope.
+- Smoke-test the installed wheel with `safejson.loads(...)` before a
+  release tag.

README.md

@@ -3,7 +3,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python: 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
 [![Typed: strict](https://img.shields.io/badge/Typed-mypy%20strict-blueviolet.svg)](https://mypy.readthedocs.io/)
-[![Tests: 183](https://img.shields.io/badge/Tests-183%20passing-brightgreen.svg)](#running-tests)
+[![Tests: 226](https://img.shields.io/badge/Tests-226%20passing-brightgreen.svg)](#running-tests)
 [![Coverage: 100%](https://img.shields.io/badge/Coverage-100%25%20line%20%2B%20branch-brightgreen.svg)](#running-tests)
 
 Hardened JSON parser for Python. Drop-in replacement for the
@@ -20,9 +20,9 @@ when the input might be hostile:
   in with `allow_nan=True`.
 - **Type whitelisting** — restrict the result to a known set of
   Python types.
-- **Streaming pre-scan** — every limit is enforced before
-  `json.loads` is allowed to allocate, so a malicious payload can
-  never blow the stack or fill memory.
+- **Streaming pre-scan** — syntax, `NaN` policy, and every resource
+  limit are enforced before `json.loads` builds Python containers.
+  Duplicate-key and type policies run through stdlib decode hooks.
 - **Zero runtime dependencies, fully typed (`py.typed`).**
 
 ## Why?
@@ -35,8 +35,25 @@ the input is attacker-controlled.
 
 `safejson` keeps the stdlib decoder in the loop (it's the fast
 path), but wraps it with an iterative, allocation-free pre-scan
-that enforces every safety policy *before* any Python object is
-constructed.
+that rejects malformed input and resource-exhaustion shapes before
+the decoder constructs containers. Semantic policies that require
+decoded Python objects, such as duplicate-key detection and
+`allowed_types`, run through explicit stdlib hooks immediately after
+that scan.
+
+## Standards Notes
+
+`safejson` is intentionally stricter than Python's defaults where the
+JSON standard and real-world interoperability disagree. RFC 8259's
+number grammar does not include `NaN` or infinities, and object names
+are expected to be unique for interoperable behavior. Python's
+`json` module documents that it accepts those numeric constants and
+keeps the last value for repeated object names by default, while also
+exposing `parse_constant` and `object_pairs_hook` so callers can
+override that behavior.
+
+References: [RFC 8259](https://www.rfc-editor.org/rfc/rfc8259),
+[Python `json` documentation](https://docs.python.org/3/library/json.html).
 
 ## Install
 
@@ -84,7 +101,7 @@ If you only need a yes/no answer ("would this parse safely?") and
 don't want to allocate the result, use `validate`:
 
 ```python
-from safejson import validate, Limits
+from safejson import Limits, SafeJsonError, validate
 
 try:
     validate(payload, limits=Limits(max_depth=16))
@@ -110,8 +127,10 @@ Bytes are decoded as UTF-8; non-UTF-8 input raises
 ### `validate(text, *, limits=None, allow_nan=False) -> None`
 
 Run the safety scan without constructing the result. Useful for
-preflight checks or when you only need to gate an upstream
-decode.
+preflight checks or when you only need to gate an upstream decode.
+`validate` enforces syntax, resource limits, and `allow_nan`; it does
+not enforce `allow_duplicate_keys` or `allowed_types`, because those
+policies require decoded object pairs and Python values.
 
 ### `Limits(...)`
 
@@ -120,7 +139,7 @@ Immutable, hashable dataclass:
 | Field | Default | Meaning |
 |-------|---------|---------|
 | `max_depth` | `64` | Maximum container nesting. |
-| `max_string_length` | `None` | Maximum chars per string / key. |
+| `max_string_length` | `None` | Maximum decoded chars per string / key; UTF-16 surrogate-pair escapes count as one. |
 | `max_array_length` | `None` | Maximum elements per array. |
 | `max_object_keys` | `None` | Maximum keys per object. |
 | `max_total_nodes` | `None` | Maximum scalar + container starts. |
@@ -161,10 +180,11 @@ ValueError:` catches still work.
 ## Running Tests
 
 ```bash
-pip install pytest pytest-cov mypy
-pytest                                # 183 tests
-pytest --cov=safejson --cov-branch    # 100% line + 100% branch
-mypy --strict src/safejson            # strict, 0 errors
+python -m pip install -e ".[dev]"
+ruff check .
+pytest --cov=safejson --cov-branch --cov-fail-under=100  # 226 tests
+mypy --strict src/safejson                               # strict, 0 errors
+python -m build                                          # wheel + sdist
 ```
 
 ## License

SECURITY.md

@@ -8,4 +8,17 @@ The `main` branch is the supported development line for `safejson`.
 
 Please report dependency issues, malformed-input crashes, or other security concerns through GitHub's private vulnerability reporting when available, or by opening a minimal public issue without exploit payloads.
 
-For untrusted input, callers should apply reasonable size limits before passing data into this project.
+Useful reports include:
+
+- Inputs that trigger `RecursionError`, `MemoryError`, process crashes,
+  or non-linear runtime before a configured limit fires.
+- Cases where `allow_nan=False`, duplicate-key rejection, or a `Limits`
+  ceiling is bypassed.
+- Packaging or CI changes that install a different source tree than the
+  tested package.
+
+For untrusted input, callers should still apply a transport-level byte
+limit before passing data into this project. `safejson` enforces JSON
+structure and decoded string/container limits after input has already
+arrived in memory; it is not a streaming network reader and it is not a
+schema validator.

pyproject.toml

@@ -1,20 +1,28 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["setuptools>=69", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "safejson"
 version = "0.1.0"
 description = "Hardened JSON parser: configurable depth/size limits, duplicate-key detection, NaN/Infinity rejection, type whitelisting. Zero deps, fully typed."
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
 requires-python = ">=3.9"
 authors = [{ name = "nripankadas07" }]
-keywords = ["json", "safe-json", "secure", "parser", "hardened", "limits", "depth", "duplicate-keys"]
+keywords = [
+    "json",
+    "safe-json",
+    "secure",
+    "parser",
+    "hardened",
+    "limits",
+    "depth",
+    "duplicate-keys",
+]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.9",
@@ -30,6 +38,18 @@ classifiers = [
 Homepage = "https://github.com/nripankadas07/safejson"
 Repository = "https://github.com/nripankadas07/safejson"
 
+[project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "mypy>=1.10",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.5",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
 [tool.setuptools.packages.find]
 where = ["src"]
 
@@ -38,9 +58,39 @@ safejson = ["py.typed"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "-ra --strict-markers"
+addopts = "-ra --strict-markers --strict-config"
 
 [tool.mypy]
 strict = true
 files = ["src/safejson"]
 mypy_path = "src"
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C4",
+    "E",
+    "F",
+    "I",
+    "N",
+    "PERF",
+    "PYI",
+    "RET",
+    "RUF",
+    "SIM",
+    "UP",
+    "W",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["safejson"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_covered = true

src/safejson/__init__.py

@@ -7,8 +7,9 @@
 for parsing untrusted input.
 
 :mod:`safejson` wraps the stdlib decoder with a streaming
-allocation-free pre-scan that enforces configurable safety limits
-before any Python objects are constructed::
+allocation-free pre-scan that enforces configurable resource limits
+before Python containers are constructed, then applies semantic hooks
+for duplicate-key and type policy::
 
     from safejson import loads, Limits
 
@@ -44,8 +45,8 @@
     "DisallowedTypeError",
     "DuplicateKeyError",
     "JsonSyntaxError",
-    "Limits",
     "LimitExceededError",
+    "Limits",
     "SafeJsonError",
     "loads",
     "validate",

src/safejson/_errors.py

@@ -23,8 +23,6 @@
 
 from __future__ import annotations
 
-from typing import Optional
-
 
 class SafeJsonError(ValueError):
     """Base class for every :mod:`safejson` failure."""
@@ -76,8 +74,7 @@ def __init__(
         self.limit = limit
         self.position = position
         super().__init__(
-            f"{limit_name} exceeded at position {position}: "
-            f"{actual} > {limit}"
+            f"{limit_name} exceeded at position {position}: {actual} > {limit}"
         )
 
 
@@ -93,7 +90,7 @@ class DuplicateKeyError(SafeJsonError):
         since :mod:`json` does not surface per-pair positions).
     """
 
-    def __init__(self, key: str, position: Optional[int] = None) -> None:
+    def __init__(self, key: str, position: int | None = None) -> None:
         self.key = key
         self.position = position
         location = "" if position is None else f" at position {position}"
@@ -112,8 +109,7 @@ class DisallowedConstantError(SafeJsonError):
     def __init__(self, constant: str) -> None:
         self.constant = constant
         super().__init__(
-            f"disallowed constant {constant!r} "
-            "(pass allow_nan=True to permit)"
+            f"disallowed constant {constant!r} (pass allow_nan=True to permit)"
         )