Weblate outbound POST JSON schema + schema-driven bats

[whisper67265]

Close #57.

Summary by CodeRabbit

• Documentation
  • Added a JSON Schema as the source of truth for Weblate add/update request payloads, including field constraints.
  • Documented Weblate success handling for both HTTP 202 (task_id) and HTTP 200 (status: "ok"), and clarified request/response payload expectations.
• Quality Improvements
  • Strengthened CI linting to validate JSON Schemas and the Weblate request contract.
  • Updated Weblate trigger tests to validate the logged request body against the schema and assert response details for HTTP 200/202.
• Chores
  • Updated CI scripts and test helpers to ensure schema validation tooling is installed and reused consistently.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 16220af0-65aa-4954-8b26-27c19e5a6140

📥 Commits

Reviewing files that changed from the base of the PR and between 343e4be and ca50f58.

📒 Files selected for processing (3)

• CHANGELOG.md
• docs/schemas/weblate-add-or-update.request.schema.json
• tests/test_trigger_weblate.bats

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/schemas/weblate-add-or-update.request.schema.json
• tests/test_trigger_weblate.bats

---

📝 Walkthrough

Walkthrough

The PR adds a JSON Schema for Weblate add-or-update requests, documents request and response contracts, bootstraps pinned schema-validation tooling, and updates CI and Bats tests to validate payloads and response fields.

Changes

Weblate schema validation

Layer / File(s)	Summary
Weblate request contract docs/schemas/*, docs/endpoint-contract.md, tests/helpers/fixtures/*	Defines the Weblate request schema, documents HTTP 200 and 202 responses, and adds a valid request fixture.
Validator bootstrap and CI integration scripts/ensure_check_jsonschema.sh, scripts/lint.sh, scripts/test.sh, .github/workflows/lint.yml	Installs or reuses pinned check-jsonschema tooling and runs schema validation during linting and test setup.
Schema-driven Weblate tests tests/helpers/schema.bash, tests/helpers/test_helper.bash, tests/test_trigger_weblate.bats	Adds JSON extraction and validation helpers and verifies Weblate request and response bodies in HTTP 200 and 202 tests.
Release documentation CHANGELOG.md	Records the Weblate schema, response contract, and CI validation changes.

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

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant lint.sh
  participant ensure_check_jsonschema
  participant check-jsonschema
  participant schema
  CI->>lint.sh: run lint job
  lint.sh->>ensure_check_jsonschema: initialize pinned validator
  ensure_check_jsonschema->>check-jsonschema: reuse or install validator
  lint.sh->>check-jsonschema: validate schemas and fixture
  check-jsonschema->>schema: check metaschema and request payload

Loading

Possibly related PRs

• cppalliance/boost-docs-translation#4: Also updates the Weblate integration contract documentation.

Suggested reviewers: henry0816191, wpak-ai

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding a Weblate outbound POST JSON schema and schema-driven Bats tests.
Linked Issues check	✅ Passed	The PR appears to satisfy issue #57 by adding the schema, updating lint and tests, installing tooling, and documenting the contract.
Out of Scope Changes check	✅ Passed	The changes stay focused on schema validation, test support, CI setup, and related docs with no obvious unrelated additions.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/ensure_check_jsonschema.sh`:
- Around line 14-18: Validate CHECK_JSONSCHEMA_VERSION immediately after
assigning version and before constructing venv_dir, rejecting path separators
and .. segments so it cannot escape cache_dir. Keep the existing cache paths and
cleanup behavior unchanged for valid version values.

In `@tests/helpers/schema.bash`:
- Around line 38-46: Replace the manual brace-counting extraction loop in the
schema helper with JSON-aware parsing using json.JSONDecoder.raw_decode or an
equivalent parser, so braces inside quoted strings are ignored and valid objects
such as task identifiers containing braces are extracted correctly. Preserve the
existing candidate collection behavior for multiple JSON values and malformed
text.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ba0fd8b5-3a70-4824-bccf-b108a7de80c6

📥 Commits

Reviewing files that changed from the base of the PR and between 9c9a3b3 and 950a620.

📒 Files selected for processing (10)

• .github/workflows/lint.yml
• docs/endpoint-contract.md
• docs/schemas/weblate-add-or-update.request.schema.json
• scripts/ensure_check_jsonschema.sh
• scripts/lint.sh
• scripts/test.sh
• tests/helpers/fixtures/weblate-add-or-update-request-valid.json
• tests/helpers/schema.bash
• tests/helpers/test_helper.bash
• tests/test_trigger_weblate.bats

[henry0816191]

update CHANGELOG.md with changes