← Files SEO & Growth CopilotARCHIVED FILE
tools/seo_checks.py
3.33 KB · Nov 20, 2026 · 06:39 UTC
"""Deterministic checks for provided SEO JSON data. No network, Search Console access or indexing claims."""
from __future__ import annotations
import json
from urllib.parse import urlsplit
PASS = 'PASS'; FAIL = 'FAIL'; NOT_RUN = 'NOT_RUN'
def check_page(page: dict) -> list[dict]:
if not isinstance(page, dict): raise TypeError('page must be a dict')
url = page.get('url')
if not isinstance(url,str) or urlsplit(url).scheme not in ('http','https') or not urlsplit(url).netloc:
raise ValueError('absolute http(s) url required')
issues=[]
status=page.get('status')
if status is None: issues.append({'check':'http_status','status':NOT_RUN,'reason':'status not supplied'})
elif not isinstance(status,int) or isinstance(status,bool) or status < 100 or status > 599: raise ValueError('invalid HTTP status')
elif status >= 400: issues.append({'check':'http_status','status':FAIL,'reason':f'HTTP {status}'})
else: issues.append({'check':'http_status','status':PASS,'reason':f'HTTP {status}'})
if page.get('in_sitemap') and status is not None and status != 200:
issues.append({'check':'sitemap_status','status':FAIL,'reason':'sitemap URL does not return 200'})
if page.get('in_sitemap') and page.get('noindex'):
issues.append({'check':'sitemap_indexability','status':FAIL,'reason':'sitemap URL marked noindex'})
canonical=page.get('canonical')
if canonical is not None and (not isinstance(canonical,str) or urlsplit(canonical).scheme not in ('http','https') or not urlsplit(canonical).netloc):
issues.append({'check':'canonical_format','status':FAIL,'reason':'canonical must be an absolute http(s) URL'})
if page.get('robots_blocked') and page.get('noindex'):
issues.append({'check':'robots_noindex','status':FAIL,'reason':'crawler may not fetch the noindex directive when robots-blocked'})
# Not checking actual Google indexing. This is only consistency review from supplied fields.
return issues
def evaluate_release(checks: list[dict], mandatory: list[str]) -> dict:
by_name={c.get('name'):c.get('status') for c in checks}
if len(by_name)!=len(checks): return {'decision':'NO_GO','reason':'duplicate check names'}
invalid=[x for x in mandatory if by_name.get(x)!=PASS]
return {'decision':'GO' if not invalid else 'NO_GO','missing_or_failed':invalid}
def summarize_gsc(current: dict, previous: dict) -> dict:
def value(data,k):
v=data.get(k)
if not isinstance(v,(int,float)) or isinstance(v,bool) or v<0: raise ValueError(f'nonnegative numeric {k} required')
return v
c=value(current,'clicks'); ci=value(current,'impressions')
p=value(previous,'clicks'); pi=value(previous,'impressions')
if c>ci or p>pi: raise ValueError('clicks cannot exceed impressions')
def delta(a,b):return None if b==0 else round((a-b)/b*100,2)
return {'current_ctr':round(c/ci*100,2) if ci else None,'previous_ctr':round(p/pi*100,2) if pi else None,'click_change_pct':delta(c,p),'impression_change_pct':delta(ci,pi),'note':'Descriptive comparison only; changes do not establish cause.'}
if __name__=='__main__':
import argparse
ap=argparse.ArgumentParser();ap.add_argument('file');args=ap.parse_args()
data=json.load(open(args.file,encoding='utf-8'))
print(json.dumps([{'url':p.get('url'),'checks':check_page(p)} for p in data['pages']],indent=2))
SHA-256: 0dbbdcfa73c54d47bb2018695b6d6d8d20a0b706856f28ee5d8478203786a9fa