import json import re def clean_val(v): if v is None: return "" v = str(v).strip() if v.startswith("`") and v.endswith("`"): v = v[1:-1].strip() if v.startswith("**") and v.endswith("**"): v = v[2:-2].strip() if (v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'")): v = v[1:-1].strip() return v def normalize_type(t): t = clean_val(t).lower() if t in ["uploadfile", "file", "file (binary)", "binary"]: return "file" if "file" in t and "string" in t: return "file/string" if t in ["str", "string"]: return "string" if t in ["int", "integer"]: return "integer" if t in ["float", "number"]: return "float" if t in ["bool", "boolean"]: return "boolean" if t in ["json", "dict", "object"]: return "json" return t def normalize_default(d): d = clean_val(d) if not d or d.lower() in ["none", "null", "none (auto-extracted)", "none (unlimited)", "none (disabled)"]: return "none" return d.lower() # Load MD with open("web/docs/FASTAPI_BACKEND_API_DOCUMENTATION.md", "r") as f: md_text = f.read() # Load Nexus with open("web/docs/data.json", "r") as f: nexus_data = json.load(f) # Parse MD sections md_sections = re.split(r"\n(?=###\s+)", md_text) md_map = {} # keyed by url or key for s in md_sections[1:]: lines = s.strip().split("\n") header = lines[0].replace("###", "").strip() url_m = re.search(r"\*\*URL:\*\*\s*`([^`]+)`", s) url = url_m.group(1).strip() if url_m else "" subs_m = re.search(r"\*\(Sub-endpoints:\s*([^\)]+)\)\*", s) subs = subs_m.group(1).strip() if subs_m else "" meth_m = re.search(r"\*\*Method:\*\*\s*`?([A-Za-z0-9_\/ ]+)`?", s) method = meth_m.group(1).strip() if meth_m else "" # parse table table_lines = [] in_table = False for l in lines: ls = l.strip() if ls.startswith("|") and ls.endswith("|"): in_table = True table_lines.append(ls) elif in_table: break params = [] if len(table_lines) >= 3: raw_headers = [c.strip() for c in table_lines[0].strip("|").split("|")] for l in table_lines[2:]: cols = [c.strip() for c in l.strip("|").split("|")] if len(cols) == len(raw_headers): row = dict(zip(raw_headers, cols)) field = clean_val(row.get("Field", "")) ty = clean_val(row.get("Type", "")) req_raw = row.get("Required", "") req = "req" in req_raw.lower() and "opt" not in req_raw.lower() df = clean_val(row.get("Default", "")) ds = row.get("Description", "") params.append({ "name": field, "type": ty, "required": req, "default": df, "description": ds }) md_map[header] = { "header": header, "url": url, "subs": subs, "method": method, "params": params, "raw_text": s } print(f"Parsed {len(md_map)} MD sections.") # Map MD sections to Nexus APIs def find_md_for_nexus_api(api, md_items): # api has full_url, api_ip_link, path, id, title, api_key a_url = (api.get("full_url") or "").rstrip("/") a_link = (api.get("api_ip_link") or "").rstrip("/") a_path = (api.get("path") or "").rstrip("/") a_key = (api.get("api_key") or "").lower() a_title = (api.get("title") or "").lower() # check direct url match for m in md_items: m_url = m["url"].rstrip("/") if m_url and (m_url == a_url or m_url == a_link): return m # check sub-endpoint full_urls for se in api.get("endpoints", []): se_url = (se.get("full_url") or "").rstrip("/") for m in md_items: m_url = m["url"].rstrip("/") if m_url and m_url == se_url: return m # check path match for m in md_items: m_url = m["url"].rstrip("/") if a_path and m_url.endswith(a_path): return m # check keyword/title match for m in md_items: h = m["header"].lower() if "feedback" in a_key and "feedback" in h: return m if "reports" in a_key and ("telemetry" in h or "reports" in h): return m if "health" in a_title and "health" in h: return m if "waifu2x" in a_key and "gfpgan" in h: return m if "relight" in a_key and "relighting" in h: return m if "skin_analyzer" in a_path and "skin health" in h: return m if "trendy" in a_key and "trendy" in h: return m if "cartoon_model" in a_key and "3.9" in h: return m if "multi_segmentation" in a_key and "multi-segmentation" in h: return m if "hair_color_changer" in a_path and "1.1" in h: return m if "hair_segmentation" in a_path and "3.13" in h: return m return None def compare_params(nexus_name, nexus_params, md_header, md_params, context_label=""): diffs = [] n_param_map = {clean_val(p.get("n")): p for p in nexus_params} m_param_map = {clean_val(p["name"]): p for p in md_params} # check aliases in Nexus params n_alias_map = {} for p in nexus_params: al = clean_val(p.get("al")) if al: # could be comma separated for a in [x.strip() for x in al.split(",")]: if a and a not in n_param_map: n_alias_map[a] = p all_keys = list(dict.fromkeys(list(n_param_map.keys()) + list(m_param_map.keys()))) for k in all_keys: in_nexus = k in n_param_map in_md = k in m_param_map # If in MD but not directly in Nexus, check if it is an alias in Nexus if in_md and not in_nexus and k in n_alias_map: # Matched via alias np = n_alias_map[k] mp = m_param_map[k] # Name mismatch / alias note diffs.append({ "type": "NAME_ALIAS_DIFFERENCE", "param": k, "detail": f"MD uses field name '{k}', while Nexus uses primary name '{np.get('n')}' (with alias '{np.get('al')}')" }) continue if in_nexus and not in_md: # Check if MD mentions this in description or table under different name np = n_param_map[k] diffs.append({ "type": "MISSING_IN_MD", "param": k, "detail": f"Shown on Nexus ({np.get('ty')}, required={np.get('rq')}, default={np.get('df')}), but MISSING from MD table" }) continue if in_md and not in_nexus: mp = m_param_map[k] diffs.append({ "type": "MISSING_ON_NEXUS", "param": k, "detail": f"Documented in MD ({mp.get('type')}, required={mp.get('required')}, default={mp.get('default')}), but NOT shown on Nexus" }) continue # Both present: compare properties np = n_param_map[k] mp = m_param_map[k] # 1. Required property n_req = bool(np.get("rq")) m_req = bool(mp.get("required")) if n_req != m_req: diffs.append({ "type": "REQUIRED_MISMATCH", "param": k, "detail": f"Required mismatch: Nexus has required={n_req} ('{'Required' if n_req else 'Optional'}'), but MD has required={m_req} ('{'Required' if m_req else 'Optional'}')" }) # 2. Type property n_ty = normalize_type(np.get("ty")) m_ty = normalize_type(mp.get("type")) if n_ty != m_ty: diffs.append({ "type": "TYPE_MISMATCH", "param": k, "detail": f"Type mismatch: Nexus displays '{np.get('ty')}' (norm: '{n_ty}'), but MD documents '{mp.get('type')}' (norm: '{m_ty}')" }) # 3. Default property n_df = normalize_default(np.get("df")) m_df = normalize_default(mp.get("default")) if n_df != m_df: diffs.append({ "type": "DEFAULT_MISMATCH", "param": k, "detail": f"Default value mismatch: Nexus displays default='{np.get('df')}', but MD documents default='{mp.get('default')}'" }) return diffs all_md_items = list(md_map.values()) report = [] for sec_idx, sec in enumerate(nexus_data["sections"]): for api in sec.get("eps", []): matched_md = find_md_for_nexus_api(api, all_md_items) sub_eps = api.get("endpoints", []) entry = { "section": sec.get("title"), "api_title": api.get("title"), "api_key": api.get("api_key"), "api_url": api.get("full_url"), "md_header": matched_md["header"] if matched_md else "NO_MATCH", "md_url": matched_md["url"] if matched_md else "", "sub_endpoints_count": len(sub_eps), "top_level_diffs": [], "sub_ep_diffs": [] } if not matched_md: entry["top_level_diffs"].append({ "type": "NO_MD_SECTION", "param": "N/A", "detail": f"API exists on Nexus but has NO corresponding section in MD documentation!" }) report.append(entry) continue # Compare top-level params n_params = api.get("params", []) m_params = matched_md.get("params", []) diffs = compare_params(api.get("title"), n_params, matched_md["header"], m_params, context_label="top-level") entry["top_level_diffs"] = diffs # For sub-endpoints, compare each sub-endpoint if len(sub_eps) > 1: for s_idx, se in enumerate(sub_eps): # find if there is a specific MD section or if it uses the same MD section se_diffs = compare_params(se.get("title") or se.get("subpath"), se.get("params", []), matched_md["header"], m_params, context_label=f"sub-ep {s_idx}") entry["sub_ep_diffs"].append({ "sub_title": se.get("title"), "sub_path": se.get("subpath") or se.get("path"), "sub_url": se.get("full_url"), "diffs": se_diffs }) report.append(entry) # Print summary print("=== COMPARISON SUMMARY ===") total_apis = len(report) apis_with_diffs = [r for r in report if r["top_level_diffs"] or any(s["diffs"] for s in r.get("sub_ep_diffs", []))] print(f"Total APIs checked: {total_apis}") print(f"APIs with parameter / property differences: {len(apis_with_diffs)}")