#!/usr/bin/env python3 """Checks calls_table.inc and ops.h against Mistral's published OpenAPI documents. python3 check_spec.py fetch both documents and check python3 check_spec.py --docs F --pd G check against local copies Fails (exit 1) when: - a table row is absent from the document it names (method + path key), - a row's operationId, request kind, response kind, body fields or query parameters differ from the document, - a document operation is neither in the table nor in EXCLUDED, - an Op constant in ops.h is not a table row. python3 stdlib only. Self-tests the bundled YAML reader against PyYAML when PyYAML happens to be installed. """ import argparse import os import re import sys HERE = os.path.dirname(os.path.abspath(__file__)) sys.path.insert(0, HERE) import specdoc # noqa: E402 PKG = os.path.join(HERE, "..") # Operations deliberately not in the table. Empty: the table covers every # operation of both documents (the generic Operations class reaches the ones # without a typed service). EXCLUDED = set() def parse_table(path): rows = [] in_table = False for line in open(path): if "CALLS-BEGIN" in line: in_table = True continue if "CALLS-END" in line: break if in_table and line.startswith("{"): parts = re.findall(r'"((?:[^"\\]|\\.)*)"|\b(true|false)\b', line) vals = [b if b else a.replace('\\"', '"').replace("\\\\", "\\") for a, b in parts] if len(vals) != 11: raise SystemExit("bad table row: " + line[:100]) rows.append({ "op": vals[0], "method": vals[1], "key": vals[2], "area": vals[3], "source": vals[4], "request": vals[5], "body": [x for x in vals[6].split(",") if x], "query": [x for x in vals[7].split(",") if x], "rkind": vals[8], "response": vals[9], "deprecated": vals[10] == "true", }) return rows def parse_ops_h(path): return re.findall(r'static constexpr const char\* k\w+ = "([^"]+)";', open(path).read()) def selftest_yaml(text): try: import yaml # noqa: WPS433 except ImportError: return "skipped (PyYAML not installed)" import minyaml def norm(v): if isinstance(v, dict): return {str(k): norm(x) for k, x in v.items()} if isinstance(v, list): return [norm(x) for x in v] if isinstance(v, str): return " ".join(v.split()) if isinstance(v, float): return round(v, 12) if isinstance(v, str) and re.fullmatch(r"[-+]?\d+(\.\d+)?e[-+]?\d+", v): return round(float(v), 12) return v a, b = norm(minyaml.loads(text)), norm(yaml.safe_load(text)) # PyYAML (YAML 1.1) leaves "1e-08" a string; the bundled reader makes it a float. return "equal" if str(a).replace("'", "") == str(b).replace("'", "") or _close(a, b) else "DIFFERENT" def _close(a, b): if isinstance(a, dict) and isinstance(b, dict): return a.keys() == b.keys() and all(_close(a[k], b[k]) for k in a) if isinstance(a, list) and isinstance(b, list): return len(a) == len(b) and all(_close(x, y) for x, y in zip(a, b)) if isinstance(a, float) and isinstance(b, str): try: return abs(a - float(b)) < 1e-12 * max(1, abs(a)) except ValueError: return False return a == b def main(): ap = argparse.ArgumentParser() ap.add_argument("--docs") ap.add_argument("--pd") ap.add_argument("--no-selftest", action="store_true") a = ap.parse_args() table = parse_table(os.path.join(PKG, "calls_table.inc")) problems = [] docs = {} for src, local in (("docs", a.docs), ("pd", a.pd)): data = open(local, "rb").read() if local else specdoc.fetch(specdoc.SOURCES[src]) import hashlib digest = hashlib.sha256(data).hexdigest() text = data.decode("utf-8") doc = specdoc.minyaml.loads(text) ops = {(r["method"], r["key"]): r for r in specdoc.operations(doc, src)} docs[src] = ops st = "not run" if a.no_selftest else selftest_yaml(text) print("%-4s sha256 %s operations %d yaml reader vs PyYAML: %s" % (src, digest[:16], len(ops), st)) seen = set() for r in table: ident = (r["method"], r["key"]) d = docs[r["source"]].get(ident) if d is None: problems.append("row not in %s document: %s %s" % (r["source"], r["method"], r["key"])) continue seen.add((r["source"],) + ident) for field in ("op", "area", "request", "rkind", "response", "deprecated"): dv = d[field if field != "op" else "op"] if r[field] != dv: problems.append("%s %s: %s differs: table %r document %r" % (r["method"], r["key"], field, r[field], dv)) for field in ("body", "query"): missing = [f for f in r[field] if f not in d[field]] extra = [f for f in d[field] if f not in r[field]] if missing: problems.append("%s: %s fields absent from the document: %s" % (r["op"], field, missing)) if extra: problems.append("%s: %s fields in the document but not in the table: %s" % (r["op"], field, extra)) table_ids = {(r["method"], r["key"]) for r in table} for src, ops in docs.items(): for ident, d in ops.items(): if d["op"] in EXCLUDED: continue # a pd operation also present in docs is covered by the docs row if ident not in table_ids: problems.append("%s operation not in the table: %s %s (%s)" % (src, ident[0], ident[1], d["op"])) if len({r["op"] for r in table}) != len(table): problems.append("duplicate operationId in the table") ids = {r["op"] for r in table} for op in parse_ops_h(os.path.join(PKG, "ops.h")): if op not in ids: problems.append("ops.h names an operation that is not a table row: " + op) print("table rows %d, ops.h constants %d, excluded %d" % ( len(table), len(parse_ops_h(os.path.join(PKG, "ops.h"))), len(EXCLUDED))) if problems: for p in problems[:60]: print("FAIL", p) print("%d problem(s)" % len(problems)) return 1 print("OK: every table row matches the documents and every document operation is in the table") return 0 if __name__ == "__main__": sys.exit(main())