feat: publish CleanReport JSON Schema

[WilliamK112]

Description

Publish a Draft 2020-12 JSON Schema for the stable CleanReport.to_dict() / to_json() audit payload.

This adds a packaged clean_report.schema.json, exposes it through CleanReport.to_json_schema(), validates representative real report output, and documents validation and schema discovery in the audit-trail guide.

Fixes #167

Type of Change

• New feature (non-breaking change which adds functionality)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Type checks (mypy) and linter checks (ruff) pass locally

Validation

• tests/test_report.py: 15 passed
• Draft 2020-12 meta-schema check and representative JSON round-trip validation
• 38 action boundary combinations, sparse/default/full payloads, and all optional report fields validated
• 6 malformed payload classes rejected
• ruff check .
• mypy src/freshdata/report.py
• wheel and sdist built successfully; the schema is included in both and loads from the wheel
• git diff --check

Summary by CodeRabbit

• New Features

  • Added JSON Schema support for validating CleanReport audit-trail exports.
  • Added CleanReport.to_json_schema() to access the packaged schema.
  • Packaged the CleanReport schema with distributions.
  • Added validation coverage for dictionary and JSON exports, including invalid action risk values.

• Documentation

  • Added a guide covering audit-trail JSON export, persistence, and schema validation.
  • Added the new guide page to the documentation navigation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a2ab92d1-acde-4d93-9f3f-2fb018a26e15

📥 Commits

Reviewing files that changed from the base of the PR and between a79f941 and af592d1.

📒 Files selected for processing (6)

• docs/audit-trail.md
• mkdocs.yml
• pyproject.toml
• src/freshdata/report.py
• src/freshdata/schemas/clean_report.schema.json
• tests/test_report.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Adds a Draft 2020-12 JSON Schema for CleanReport payloads, packages the schema, exposes CleanReport.to_json_schema(), validates serialized reports in tests, and documents schema usage.

Changes

CleanReport JSON Schema

Layer / File(s)	Summary
Schema contract src/freshdata/schemas/clean_report.schema.json	Defines required report fields, optional metadata, reusable action rules, backend data, fallback events, and stage timings.
Schema packaging and loading pyproject.toml, src/freshdata/report.py	Packages schema JSON files and adds CleanReport.to_json_schema() for loading the schema as a dictionary.
Validation and documentation tests/test_report.py, docs/audit-trail.md, mkdocs.yml	Validates report dictionaries and JSON output, rejects invalid action risks, and adds audit-trail schema documentation to the Guide navigation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to af592

This change publishes and exposes the CleanReport JSON Schema with validation, documentation, and packaging updates; no actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: johnnywilson-portfolio, johnnywilson16

Sequence Diagram(s)

sequenceDiagram
  participant CleanReport
  participant PackagedSchema
  participant Draft202012Validator
  CleanReport->>PackagedSchema: Load clean_report.schema.json
  PackagedSchema-->>CleanReport: Return schema dictionary
  CleanReport->>Draft202012Validator: Validate serialized report
  Draft202012Validator-->>CleanReport: Return validation result

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 2 files. (4 skipped: 4 unsupported.)	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: publishing the CleanReport JSON Schema.
Description check	✅ Passed	The description follows the template, explains the feature, links issue #167, identifies the change type, and records validation results.
Linked Issues check	✅ Passed	The PR provides the schema, exposes a discovery helper, validates real report output, adds representative tests, and documents the feature as required by issue #167.
Out of Scope Changes check	✅ Passed	The schema, helper, tests, packaging update, and audit-trail documentation directly support the linked issue objectives.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[WilliamK112]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[JohnnyWilson16]

Looks great! Clean implementation using importlib.resources with no extra runtime dependencies. Schema definitions and test coverage for valid outputs and rejection cases look solid. LGTM 👍