#!/usr/bin/env python3 """Check src/vendors/cohere/calls.cpp against Cohere's published OpenAPI document. Cohere publishes cohere-openapi.yaml in the cohere-ai/cohere-developer-experience repository (the file their Fern SDK generation reads). This checker parses that file with a small block-YAML reader (Python 3 standard library only, no PyYAML) and fails (exit 1) when: row a declared call's HTTP method + path or operationId is not in the spec; field a request body field or query parameter we send is not in the spec's request body / parameters of that operation; required a field or parameter the spec marks required is not declared in the row; schema a field we read (SCHEMAS table) is not a property of that schema; response a declared response schema is neither a component nor an operationId; coverage a spec operation is neither in the table nor in EXCLUDED_OPERATIONS. python3 -I src/vendors/cohere/tools/check_spec.py [--spec path-to-openapi.yaml] [alternative calls.cpp] Network required unless --spec is given. No credentials. """ import os import re import sys import urllib.request HERE = os.path.dirname(os.path.abspath(__file__)) CALLS = os.path.join(HERE, "..", "calls.cpp") SPEC_URL = ("https://raw.githubusercontent.com/cohere-ai/cohere-developer-experience/main/" "cohere-openapi.yaml") # Operations that exist in the spec but are deliberately not wrapped (reason each). EXCLUDED_OPERATIONS = {} STR = re.compile(r'"([^"]*)"') METHODS = ("get", "post", "put", "patch", "delete") # ---------------------------------------------------------------- YAML reader class Yaml: """Block-style YAML subset: mappings, sequences, plain / quoted scalars (single line or folded continuation), block scalars (| >), empty flow [] and {}.""" def __init__(self, text): self.lines = [] for raw in text.replace("\t", " ").split("\n"): self.lines.append(raw.rstrip("\r")) self.i = 0 @staticmethod def indent_of(line): return len(line) - len(line.lstrip(" ")) def skip_blank(self): while self.i < len(self.lines): s = self.lines[self.i].strip() if s == "" or s.startswith("#") or s == "---": self.i += 1 else: return def parse(self): self.skip_blank() return self.node(self.indent_of(self.lines[self.i])) def node(self, indent): self.skip_blank() if self.i >= len(self.lines): return None line = self.lines[self.i] if self.indent_of(line) < indent: return None body = line.strip() if body.startswith("- ") or body == "-": return self.seq(self.indent_of(line)) if self.key_split(body) is not None: return self.mapping(self.indent_of(line)) self.i += 1 return self.scalar(body, self.indent_of(line)) @staticmethod def key_split(body): """(key, rest) for `key: rest`, else None. Handles quoted keys.""" if body[:1] in ("'", '"'): q = body[0] j = 1 while j < len(body): if body[j] == q and (q == "'" or body[j - 1] != "\\"): break j += 1 if j + 1 < len(body) and body[j + 1] == ":" and (j + 2 == len(body) or body[j + 2] == " "): return body[1:j], body[j + 2:].strip() return None if body[:1] in ("[", "{", "|", ">", "#", "*", "&", "!"): return None m = re.match(r"^([^:#]+?|[^:#]*?[^:\s#][^#]*?):(?:\s+(.*))?$", body) if not m: return None key = m.group(1) if " #" in key: return None return key.strip(), (m.group(2) or "").strip() def mapping(self, indent): out = {} while True: self.skip_blank() if self.i >= len(self.lines): break line = self.lines[self.i] if self.indent_of(line) != indent: break body = line.strip() kv = self.key_split(body) if kv is None or body.startswith("- "): break key, rest = kv self.i += 1 out[key] = self.value(rest, indent) return out def seq(self, indent): out = [] while True: self.skip_blank() if self.i >= len(self.lines): break line = self.lines[self.i] if self.indent_of(line) != indent: break body = line.strip() if not (body.startswith("- ") or body == "-"): break rest = body[1:].strip() if rest == "": self.i += 1 out.append(self.node(indent + 1)) elif self.key_split(rest) is not None and not rest.startswith(("'", '"')) or \ (rest[:1] in ("'", '"') and self.key_split(rest) is not None): # `- key: value`: treat the text after "- " as a mapping line at indent+2 self.lines[self.i] = " " * (indent + 2) + rest out.append(self.mapping(indent + 2)) else: self.i += 1 out.append(self.scalar(rest, indent)) return out def value(self, rest, indent): if rest == "" or rest.startswith("#"): self.skip_blank() if self.i < len(self.lines): nxt = self.lines[self.i] ni = self.indent_of(nxt) nb = nxt.strip() if ni > indent or (ni == indent and (nb.startswith("- ") or nb == "-")): return self.node(ni) return None if rest[0] in "|>": return self.block_scalar(rest, indent) return self.scalar(rest, indent) def block_scalar(self, header, indent): fold = header[0] == ">" buf = [] block_indent = None while self.i < len(self.lines): line = self.lines[self.i] if line.strip() == "": buf.append("") self.i += 1 continue li = self.indent_of(line) if li <= indent: break if block_indent is None: block_indent = li buf.append(line[block_indent:] if li >= block_indent else line.strip()) self.i += 1 text = ("\n" if not fold else " ").join(buf).strip() return text def scalar(self, text, indent): if text[0] in ("'", '"'): q = text[0] acc = text # continuation lines until the closing quote while not self.closed(acc, q) and self.i < len(self.lines): acc += " " + self.lines[self.i].strip() self.i += 1 body = acc[1:Yaml.end_of(acc, q)] if q == '"': body = body.replace('\\"', '"').replace("\\n", "\n").replace("\\\\", "\\") else: body = body.replace("''", "'") return body if text in ("[]", "{}"): return [] if text == "[]" else {} if text[0] in "[{": acc = text while acc.count("[") + acc.count("{") > acc.count("]") + acc.count("}") and self.i < len(self.lines): acc += " " + self.lines[self.i].strip() self.i += 1 return acc # flow collections beyond [] and {} are kept as text (not used by the checker) # plain scalar: strip trailing comment, fold continuation lines that are more indented text = re.sub(r"\s+#.*$", "", text) while self.i < len(self.lines): nxt = self.lines[self.i] if nxt.strip() == "" or self.indent_of(nxt) <= indent: break if self.key_split(nxt.strip()) is not None and nxt.strip()[:1] not in ("'", '"'): break text += " " + nxt.strip() self.i += 1 return text @staticmethod def end_of(acc, q): j = 1 while j < len(acc): c = acc[j] if q == '"' and c == "\\": j += 2 continue if c == q: if q == "'" and j + 1 < len(acc) and acc[j + 1] == "'": j += 2 continue return j j += 1 return len(acc) @staticmethod def closed(acc, q): """True when the quoted scalar that starts acc has its closing quote.""" j = 1 while j < len(acc): c = acc[j] if q == '"' and c == "\\": j += 2 continue if c == q: if q == "'" and j + 1 < len(acc) and acc[j + 1] == "'": j += 2 continue return True j += 1 return False # ------------------------------------------------------------------ spec model class Spec: def __init__(self, doc): self.doc = doc self.schemas = doc["components"]["schemas"] self.params = doc["components"].get("parameters", {}) def ref(self, node): seen = 0 while isinstance(node, dict) and "$ref" in node and seen < 20: name = node["$ref"].split("/")[-1] kind = node["$ref"].split("/")[-2] node = (self.params if kind == "parameters" else self.schemas).get(name) seen += 1 return node def props(self, node, depth=0): """Union of property names (and required names) through $ref / allOf / oneOf / anyOf / items.""" props, required = {}, set() node = self.ref(node) if not isinstance(node, dict) or depth > 12: return props, required for key in ("allOf", "oneOf", "anyOf"): for sub in node.get(key) or []: p, r = self.props(sub, depth + 1) props.update(p) if key == "allOf": required |= r if isinstance(node.get("properties"), dict): props.update(node["properties"]) if isinstance(node.get("required"), list): required |= set(node["required"]) return props, required def descend(self, node, path): """Follow a dotted property path; arrays are entered through items.""" for step in [p for p in path.split(".") if p]: node = self.ref(node) if isinstance(node, dict) and node.get("type") == "array" and "items" in node: node = self.ref(node["items"]) props, _ = self.props(node) if step not in props: return None node = props[step] node = self.ref(node) if isinstance(node, dict) and node.get("type") == "array" and "items" in node: node = self.ref(node["items"]) return node def operations(self): for path, item in self.doc["paths"].items(): for method, op in item.items(): if method in METHODS and isinstance(op, dict): yield method.upper(), path, op def op_params(self, op): out = {} for p in op.get("parameters") or []: p = self.ref(p) if isinstance(p, dict) and p.get("in") in ("query", "path"): out[p["name"]] = (p["in"], bool(p.get("required"))) return out def op_body(self, op): rb = op.get("requestBody") if not rb: return None, set() content = rb.get("content") or {} for ct in ("application/json", "multipart/form-data"): if ct in content: return self.props(content[ct].get("schema")) return {}, set() def op_response(self, op): r = (op.get("responses") or {}).get("200") or {} content = r.get("content") or {} if "application/json" in content: return content["application/json"].get("schema") return None # ------------------------------------------------------------------------ main def rows(text, begin, end): a, b = text.index(begin), text.index(end) out = [] for line in text[a:b].splitlines()[1:]: s = line.strip() if s.startswith("{") and '"' in s: out.append(STR.findall(s)) return out def load_spec(argv): if "--spec" in argv: i = argv.index("--spec") path = argv[i + 1] del argv[i:i + 2] with open(path, encoding="utf-8") as f: return f.read() req = urllib.request.Request(SPEC_URL, headers={"User-Agent": "molo-cohere-spec-check/1"}) with urllib.request.urlopen(req, timeout=120) as r: return r.read().decode("utf-8", "replace") def main(): argv = sys.argv[1:] spec_text = load_spec(argv) calls_path = argv[0] if argv else CALLS text = open(calls_path).read() calls = rows(text, "// CALLS-BEGIN", "// CALLS-END") schemas = rows(text, "// SCHEMAS-BEGIN", "// SCHEMAS-END") spec = Spec(Yaml(spec_text).parse()) ops = {(m, p): op for m, p, op in spec.operations()} by_id = {op.get("operationId"): op for op in ops.values()} bad = [] covered = set() for method, path, op_id, body, query, response in calls: op = ops.get((method, path)) if op is None: bad.append("%s %s: not a path of the spec" % (method, path)) continue covered.add((method, path)) if op.get("operationId") != op_id: bad.append("%s %s: operationId is %s in the spec, %s in the table" % (method, path, op.get("operationId"), op_id)) params = spec.op_params(op) body_props, body_required = spec.op_body(op) declared_body = {f for f in body.split(",") if f} declared_query = {q for q in query.split(",") if q} for f in sorted(declared_body): if f not in body_props: bad.append("%s %s: body field %s is not in the request body" % (method, path, f)) for q in sorted(declared_query): if q not in params or params[q][0] != "query": bad.append("%s %s: query parameter %s is not in the spec" % (method, path, q)) for name, (where, required) in params.items(): if where == "query" and required and name not in declared_query: bad.append("%s %s: required query parameter %s missing in the row" % (method, path, name)) for f in sorted(body_required): if f in body_props and f not in declared_body: bad.append("%s %s: required body field %s missing in the row" % (method, path, f)) if response and response not in spec.schemas and response not in by_id: bad.append("%s %s: response schema %s is neither a component nor an operationId" % (method, path, response)) for (method, path), op in sorted(ops.items()): if (method, path) not in covered and op.get("operationId") not in EXCLUDED_OPERATIONS: bad.append("unwrapped operation %s %s (%s): add a row or an exclusion" % (method, path, op.get("operationId"))) checked_fields = 0 for name, fields in schemas: head, _, tail = name.partition(".") if head in spec.schemas: node = spec.schemas[head] elif head in by_id: node = spec.op_response(by_id[head]) else: bad.append("schema %s: neither a component nor an operationId" % head) continue target = spec.descend(node, tail) if tail else spec.ref(node) if target is None: bad.append("schema %s: property path not found" % name) continue props, _ = spec.props(target) for f in filter(None, fields.split(",")): checked_fields += 1 if f not in props: bad.append("schema %s: field %s is not a property" % (name, f)) if bad: print("SPEC CHECK FAILED") for b in bad: print(" " + b) return 1 print("cohere spec ok: %d calls of %d spec operations (exclusions: %d), %d schema rows, %d fields" % (len(calls), len(ops), len(EXCLUDED_OPERATIONS), len(schemas), checked_fields)) return 0 if __name__ == "__main__": sys.exit(main())