Files
Unified_Dashboard_Suite_Go/scratch/detailed_param_check.py
T

308 lines
11 KiB
Python
Raw Normal View History

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)}")