Complete schema and JUnit contracts

[Deathcharge]

Summary

• bundle valid JSON Schema Draft 2020-12 documents for workflow and suite schema version 1
• expose schemas through the typed Python API and samsarix-spirals schema CLI
• add deterministic, value-redacted JUnit XML reports through samsarix-spirals test --junit
• preserve JSON type semantics by distinguishing booleans from numbers during exact output checks
• validate all applicable examples against both runtime validation and the published schemas
• verify schemas and JUnit output from the installed wheel in CI

Why

The contract-suite milestone needed portable editor/CI integration before expanding the workflow language. Bundled schemas make the file formats discoverable without a hosted service, while JUnit lets existing CI systems ingest contract results without a proprietary dashboard. Both preserve the zero-runtime-dependency and no-code-execution boundaries.

Impact

Existing workflows, suites, commands, and JSON reports remain compatible. --json and --junit are mutually exclusive. JUnit output contains only names and fixed mismatch categories; fixture inputs and outputs are not disclosed. External schema validation is structural and does not replace bounded runtime validation.

Verification

• 84 tests pass, 2 input fixtures intentionally skipped, with 96.16% branch coverage
• Ruff format and lint, strict mypy, compileall, Bandit, and pip-audit pass
• both Draft 2020-12 schemas pass Draft202012Validator.check_schema
• every applicable example passes its published schema and runtime model
• wheel and sdist build and pass Twine checks
• both schema resources are present in the wheel and source archive
• installed-wheel schema/JUnit smoke tests pass under isolated Python 3.14 and Python 3.11

Local artifact SHA-256 evidence:

• wheel: 91E604E0AB1114997821AB01215861E6FBF6F7B484C7FB62081B1D40F3B12E8C
• sdist: CDE6F07CCFABE5F3ABDF0A7E73CA0B6662485EF28B6CED96D9BD0A750B02EAC7

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 33f3fec5-1423-4049-83c3-b7c8589256a9

📥 Commits

Reviewing files that changed from the base of the PR and between c7d4401 and 45469f6.

📒 Files selected for processing (17)

• .github/workflows/ci.yml
• CHANGELOG.md
• MANIFEST.in
• README.md
• ROADMAP.md
• docs/WORKFLOW_FORMAT.md
• pyproject.toml
• src/samsarix_spirals/__init__.py
• src/samsarix_spirals/cli.py
• src/samsarix_spirals/schema.py
• src/samsarix_spirals/schemas/suite-v1.schema.json
• src/samsarix_spirals/schemas/workflow-v1.schema.json
• src/samsarix_spirals/suite.py
• tests/test_cli.py
• tests/test_public_api.py
• tests/test_schema.py
• tests/test_suite.py

---

Summary by CodeRabbit

• New Features

  • Added bundled JSON Schemas for validating workflows and regression suites.
  • Added CLI and Python APIs for retrieving schemas.
  • Added JUnit XML reporting for test results, with deterministic, XML-safe output that omits sensitive values.
  • Improved result comparisons to distinguish booleans from numbers while preserving numeric equivalence.

• Documentation

  • Documented schema commands, validation boundaries, JUnit reporting, and Python APIs.
  • Updated the roadmap and changelog.

Walkthrough

The package adds bundled workflow and suite JSON Schemas, schema discovery APIs, deterministic JUnit XML reporting, strict JSON output comparison, and CLI support. Documentation, package data, tests, and CI smoke checks cover the new behavior.

Changes

Schema contracts and discovery

Layer / File(s)	Summary
Schema contracts and discovery src/samsarix_spirals/schema.py, src/samsarix_spirals/schemas/*.json, tests/test_schema.py, pyproject.toml, MANIFEST.in	The package defines workflow and suite Draft 2020-12 schemas, loads them through get_schema, and includes them in distributions. Tests validate schema structure, examples, and detached results.

Strict comparison and JUnit serialization

Layer / File(s)	Summary
Strict comparison and JUnit serialization src/samsarix_spirals/suite.py, tests/test_suite.py, docs/WORKFLOW_FORMAT.md, CHANGELOG.md	Suite comparison now distinguishes booleans from numbers while preserving integer and decimal equality. Suite results serialize to deterministic, sanitized JUnit XML without sensitive values.

CLI and public API integration

Layer / File(s)	Summary
CLI and public API integration src/samsarix_spirals/cli.py, src/samsarix_spirals/__init__.py, tests/test_cli.py, tests/test_public_api.py, .github/workflows/ci.yml	The CLI adds schema commands and mutually exclusive --json and --junit reporting modes. The package root exports the new helpers. CLI tests and CI smoke tests cover the commands.

Documentation and release status

Layer / File(s)	Summary
Documentation and release status README.md, docs/WORKFLOW_FORMAT.md, ROADMAP.md	The documentation describes schema retrieval, validation boundaries, JUnit output, and the new Python APIs. The roadmap marks schema publication and JUnit reporting complete.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant SchemaAPI
  participant SchemaJSON
  CLI->>SchemaAPI: request selected schema
  SchemaAPI->>SchemaJSON: load bundled JSON
  SchemaJSON-->>SchemaAPI: schema object
  SchemaAPI-->>CLI: return schema dictionary
  CLI->>CLI: print sorted JSON

Loading

sequenceDiagram
  participant CLI
  participant Suite
  participant Serializer
  participant XML
  CLI->>Suite: run workflow tests
  Suite->>Suite: compare expected and actual output
  Suite-->>CLI: SuiteResult
  CLI->>Serializer: convert SuiteResult
  Serializer->>XML: create sanitized report
  XML-->>CLI: emit JUnit XML

Loading

Possibly related PRs

• Deathcharge/samsarix-spirals#1: Introduced CLI, package exports, CI workflow, and CLI tests extended by this change.
• Deathcharge/samsarix-spirals#9: Introduced the test CLI and suite reporting paths extended with JUnit output and strict comparison.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/schema-junit-contracts

---

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.}