feat(import): complete OpenAPI onboarding and verify delivery
CI / Rust Checks (pull_request) Failing after 1s
CI / UI Checks (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Deploy (pull_request) Skipped

This commit is contained in:
bsodfather committed 2026-10-09 17:50:38 +03:00
1 parent bb3e376767
commit e93de7015a
244 files changed
+57020 -5139

No files matched your search

+189
View File
@@ -0,0 +1,189 @@
#!/usr/bin/env python3
"""Require versioned, explained compatibility changes to OpenAPI contracts."""
from __future__ import annotations
import argparse
import json
import re
import subprocess
import sys
from typing import Any
MATRIX_PATH = "crates/crank-import/tests/support-matrix.yaml"
MANIFEST_PATH = "crates/crank-import/tests/corpus/manifest.json"
DOCS_PATH = "docs/openapi-import.md"
def git_show(revision: str, path: str) -> str | None:
result = subprocess.run(
["git", "show", f"{revision}:{path}"],
check=False,
capture_output=True,
text=True,
)
return result.stdout if result.returncode == 0 else None
def matrix_version(contents: str | None) -> str | None:
if contents is None:
return None
match = re.search(r"(?m)^matrix_version:\s*['\"]?([^\s'\"]+)", contents)
return match.group(1) if match else None
def parse_manifest(contents: str | None, label: str) -> dict[str, Any] | None:
if contents is None:
return None
try:
value = json.loads(contents)
except json.JSONDecodeError as error:
raise ValueError(f"{label} is not valid JSON: {error}") from error
if not isinstance(value, dict):
raise ValueError(f"{label} must be a JSON object")
return value
def require(condition: bool, message: str, errors: list[str]) -> None:
if not condition:
errors.append(message)
def valid_version(value: Any) -> bool:
return isinstance(value, str) and re.fullmatch(
r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)", value
) is not None
def version_increases(old: Any, new: Any) -> bool:
"""Compare the numeric contract versions used by the matrix and corpus."""
if not valid_version(old) or not valid_version(new):
return False
return tuple(map(int, new.split("."))) > tuple(map(int, old.split(".")))
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--base", required=True, help="base commit or ref to compare against")
args = parser.parse_args()
try:
subprocess.run(
["git", "rev-parse", "--verify", f"{args.base}^{{commit}}"],
check=True,
capture_output=True,
text=True,
)
except subprocess.CalledProcessError:
print(f"OpenAPI compatibility guard: base revision {args.base!r} is unavailable", file=sys.stderr)
return 2
try:
old_matrix_text = git_show(args.base, MATRIX_PATH)
old_manifest_text = git_show(args.base, MANIFEST_PATH)
with open(MATRIX_PATH, encoding="utf-8") as matrix_file:
new_matrix_text = matrix_file.read()
with open(MANIFEST_PATH, encoding="utf-8") as manifest_file:
new_manifest_text = manifest_file.read()
with open(DOCS_PATH, encoding="utf-8") as docs_file:
new_docs_text = docs_file.read()
old_manifest = parse_manifest(old_manifest_text, "base manifest")
new_manifest = parse_manifest(new_manifest_text, "working manifest")
except (OSError, ValueError) as error:
print(f"OpenAPI compatibility guard: {error}", file=sys.stderr)
return 2
matrix_changed = old_matrix_text != new_matrix_text
manifest_changed = old_manifest_text != new_manifest_text
errors: list[str] = []
old_matrix_version = matrix_version(old_matrix_text)
new_matrix_version = matrix_version(new_matrix_text)
new_corpus_version = new_manifest.get("corpus_version")
new_impact = new_manifest.get("compatibility_impact")
require(bool(new_matrix_version), "support matrix must declare matrix_version", errors)
require(bool(new_corpus_version), "corpus manifest must declare corpus_version", errors)
require(valid_version(new_matrix_version), "matrix_version must be numeric SemVer", errors)
require(valid_version(new_corpus_version), "corpus_version must be numeric SemVer", errors)
require(
new_manifest.get("matrix_version") == new_matrix_version,
"manifest matrix_version must match support matrix",
errors,
)
require(
isinstance(new_impact, str) and bool(new_impact.strip()),
"corpus manifest must include a non-empty compatibility_impact note",
errors,
)
if matrix_changed and old_matrix_text is not None:
require(
version_increases(old_matrix_version, new_matrix_version),
"support-matrix.yaml changed without a matrix_version bump (must increase SemVer)",
errors,
)
old_matrix_was_present = old_matrix_text is not None
if matrix_changed and old_matrix_was_present:
old_impact = old_manifest.get("compatibility_impact") if old_manifest else None
require(
new_impact != old_impact,
"support matrix changed without updating compatibility_impact",
errors,
)
# The published documentation states concrete matrix/corpus versions;
# a stale or mixed version in docs must not outlive the machine source.
matrix_decls = re.findall(
r"матриц[аы] версии `([0-9]+\.[0-9]+\.[0-9]+)`", new_docs_text, re.IGNORECASE
)
corpus_decls = re.findall(
r"corpus version — `([0-9]+\.[0-9]+\.[0-9]+)`", new_docs_text, re.IGNORECASE
)
require(
bool(matrix_decls) and all(version == new_matrix_version for version in matrix_decls),
f"{DOCS_PATH} matrix version declaration must state matrix_version {new_matrix_version}",
errors,
)
require(
bool(corpus_decls) and all(version == new_corpus_version for version in corpus_decls),
f"{DOCS_PATH} corpus version declaration must state corpus_version {new_corpus_version}",
errors,
)
require(
bool(matrix_decls) and bool(corpus_decls)
and all(version == new_matrix_version for version in matrix_decls)
and all(version == new_corpus_version for version in corpus_decls),
f"{DOCS_PATH} must state the current support matrix and corpus versions",
errors,
)
if old_manifest is not None:
if old_manifest != new_manifest:
require(
version_increases(old_manifest.get("corpus_version"), new_corpus_version),
"corpus manifest changed without a corpus_version bump (must increase SemVer)",
errors,
)
require(
new_impact != old_manifest.get("compatibility_impact"),
"corpus manifest changed without updating compatibility_impact",
errors,
)
if errors:
print("OpenAPI compatibility guard failed:", file=sys.stderr)
for error in errors:
print(f"- {error}", file=sys.stderr)
return 1
print(
"OpenAPI compatibility guard passed: "
f"matrix {old_matrix_version or '<new>'} -> {new_matrix_version}; "
f"corpus {old_manifest.get('corpus_version') if old_manifest else '<new>'} -> {new_corpus_version}"
)
if not matrix_changed and not manifest_changed:
print("OpenAPI compatibility guard: matrix and corpus manifest are unchanged")
return 0
if __name__ == "__main__":
raise SystemExit(main())
+36 -3
View File
@@ -153,15 +153,40 @@ validate_backup_migration() {
return 1
fi
shadow_target_file="$(mktemp)"
if ! timeout 2m docker run --rm \
"$admin_image" crank-migrate plan --target-version > "$shadow_target_file"; then
rm -f "$shadow_target_file"
echo "Migration plan target version could not be read" >&2
return 1
fi
if ! IFS= read -r shadow_target_version < "$shadow_target_file" \
|| ! printf '%s\n' "$shadow_target_version" | cmp -s - "$shadow_target_file"; then
rm -f "$shadow_target_file"
echo "Migration plan returned an invalid target version" >&2
return 1
fi
rm -f "$shadow_target_file"
case "$shadow_target_version" in
''|0*|*[!0-9]*)
echo "Migration plan returned an invalid target version" >&2
return 1
;;
esac
shadow_id="crank-migration-check-$$"
shadow_network="${shadow_id}-network"
shadow_postgres="${shadow_id}-postgres"
shadow_password="crank-shadow-migration-password"
shadow_admin="crank_shadow_admin"
shadow_user="crank_shadow_owner"
shadow_preflight_file=""
shadow_cleanup() {
docker rm -fv "$shadow_postgres" >/dev/null 2>&1 || true
docker network rm "$shadow_network" >/dev/null 2>&1 || true
if [ -n "$shadow_preflight_file" ]; then
rm -f "$shadow_preflight_file"
fi
}
trap shadow_cleanup EXIT
trap 'exit 130' HUP INT TERM
@@ -206,10 +231,18 @@ validate_backup_migration() {
timeout 10m docker run --rm --network "$shadow_network" \
-e CRANK_DATABASE_URL="$shadow_database_url" \
"$admin_image" crank-migrate apply
shadow_preflight="$(timeout 2m docker run --rm --network "$shadow_network" \
shadow_preflight_file="$(mktemp)"
if ! timeout 2m docker run --rm --network "$shadow_network" \
-e CRANK_DATABASE_URL="$shadow_database_url" \
"$admin_image" crank-migrate preflight)"
printf '%s\n' "$shadow_preflight" | grep -Fxq '{"status":"current","version":13}'
"$admin_image" crank-migrate preflight > "$shadow_preflight_file"; then
echo "Shadow migration preflight command failed" >&2
return 1
fi
if ! printf '%s\n' "{\"status\":\"current\",\"version\":${shadow_target_version}}" \
| cmp -s - "$shadow_preflight_file"; then
echo "Shadow migration preflight did not confirm the target schema" >&2
return 1
fi
shadow_cleanup
trap - EXIT HUP INT TERM
+9 -1
View File
@@ -30,6 +30,10 @@ def reject_duplicates(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
return result
def reject_constant(_value: str) -> Any:
raise ValidationError('/', 'invalid JSON constant')
def load_json(path: Path) -> Any:
try:
raw = path.read_bytes()
@@ -38,7 +42,11 @@ def load_json(path: Path) -> Any:
if len(raw) > MAX_INPUT_BYTES:
raise ValidationError('/', 'input exceeds 64 KiB')
try:
return json.loads(raw.decode('utf-8'), object_pairs_hook=reject_duplicates)
return json.loads(
raw.decode('utf-8'),
object_pairs_hook=reject_duplicates,
parse_constant=reject_constant,
)
except (UnicodeDecodeError, json.JSONDecodeError, RecursionError) as error:
raise ValidationError('/', 'invalid JSON') from error