Return typed crop results and safe JSON diagnostics

[leblancfg]

JSON/result layer above typing PR #221

Native stack #222, from master upward: #221 → #213 → #214 → #219. Review/merge bottom-up using GitHub's stack controls after approval and green CI. A group merge includes all lower unmerged PRs; GitHub rebases the remaining stack after a partial merge. Do not use the former reverse-order/manual-base-edit recipe.

Nothing has been merged, tagged, released, or published. The restack preserves the existing PRs and review discussions.

API introduced here

result = cropper.crop(source)
if result.image is not None:
    Image.fromarray(result.image).save('cropped.jpg')
print(result.diagnostics.crop_rectangle)

• crop() always returns CropResult with image and a CropDiagnostics dataclass.
• No diagnostics flag, tuple unpacking, array impersonation, or per-call state stored on Cropper.
• No-face/uncroppable results have image=None and a reason; unreadable inputs and invalid configuration still raise.
• Independent per-call diagnostics; generated ndarray equality is disabled on the result record.
• V1 callers must read .image and check that field for None. README, API/quickstart/overview, notebook, and tests reflect this contract; Prepare v2 migration FAQ and actionable compatibility errors #219 adds the full migration FAQ.

Implementation

• diagnostics.py contains typed result records, independent of printing/file handling.
• reporting.py owns CLI serialization, atomic writes, and source/output/redirected-stream alias safeguards.
• The CLI has a direct read/crop/write flow rather than callback plumbing or shared mutable diagnostic dictionaries.
• The detector adapter decodes named boxes, landmarks, and scores before consumers use them.
• The flat JSON schema and JSON-only stderr remain intact on errors and with verbose output.
• Module naming cleanup includes timing.py; alignment/migration modules arrive in their own PRs.
• New feature code and consumer examples obey the strict typing checks inherited from Add type hints with ty and Ruff checks #221.

Validation

• This layer independently passes lint, ty and Ruff lint/format checks, and 118 tests.
• The full stack passes 174 tests and preserves the previously tested final implementation; all 15 updated CI matrix configurations are green. Final wheel/sdist and installed-package checks also passed.

Closes #211. SDK decisions #215–#218 remain for discussion before publication.

Toolchain sync

The ty/Ruff configuration, dependencies, recipes, and CI changes live in #221. This layer inherits them, uses Ruff formatting/import order, and updates consumer checks to ty-specific expected diagnostics. Local ty, Ruff lint/format, and all 118 tests pass. Runtime API and stack order are unchanged.