← Files SEO & Growth CopilotARCHIVED FILE

tools/seo_checks.py

3.33 KB · Nov 20, 2026 · 06:39 UTC

↓ Download file

See the change to this file →

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