Image SEO Audit Claude Skill

#!/usr/bin/env python3
"""Crawl a website (or scan local HTML files) and build an image inventory as JSON.

Usage:
    python3 extract_images.py https://example.com [--max-pages 500] [--check-files]
        [--output image_inventory.json]
    python3 extract_images.py ./site-folder --local [--output image_inventory.json]
    python3 extract_images.py urls.txt --url-list [--output image_inventory.json]

With --check-files the script also issues a lightweight request per unique image URL
to record HTTP status, content type, and byte size (needed for the broken-image,
oversized-file, and format checks).

Output JSON schema:
{
  "site": "https://example.com",
  "checked_files": true,
  "pages": {
    "<url>": {
      "status": 200,
      "images": [
        {
          "src": "<absolute url or null>",
          "alt": "<string, or null if the attribute is absent>",
          "width": "<attr value or null>",
          "height": "<attr value or null>",
          "loading": "<attr value or null>",
          "has_srcset": false,
          "in_picture": false,
          "position": 0            # 0-based order within the page
        }
      ]
    }
  },
  "files": {                       # only present with --check-files
    "<image url>": {"status": 200, "content_type": "image/webp", "bytes": 12345}
  }
}

Uses only the Python standard library.
"""

import argparse
import json
import os
import sys
import urllib.error
import urllib.parse
import urllib.request
import xml.etree.ElementTree as ET
from collections import deque
from html.parser import HTMLParser

USER_AGENT = "ImageSeoAuditBot/1.0 (+claude-skill)"
TIMEOUT = 15


class ImageParser(HTMLParser):
    """Extract <img> elements (with attributes), <picture> context, and same-host links."""

    def __init__(self, base_url):
        super().__init__(convert_charrefs=True)
        self.base_url = base_url
        self.images = []
        self.links = []
        self._picture_depth = 0
        self._position = 0

    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag == "picture":
            self._picture_depth += 1
        elif tag == "img":
            src = a.get("src") or a.get("data-src")
            self.images.append({
                "src": urllib.parse.urljoin(self.base_url, src.strip()) if src else None,
                "alt": a["alt"] if "alt" in a else None,
                "width": a.get("width"),
                "height": a.get("height"),
                "loading": (a.get("loading") or "").lower() or None,
                "has_srcset": bool(a.get("srcset") or a.get("data-srcset")),
                "in_picture": self._picture_depth > 0,
                "position": self._position,
            })
            self._position += 1
        elif tag == "a" and a.get("href"):
            href = a["href"].strip()
            if not href.startswith(("mailto:", "tel:", "javascript:", "#")):
                target = urllib.parse.urljoin(self.base_url, href)
                self.links.append(urllib.parse.urldefrag(target)[0])

    def handle_endtag(self, tag):
        if tag == "picture" and self._picture_depth > 0:
            self._picture_depth -= 1


def fetch(url):
    """Return (status, final_url, html_or_none)."""
    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
    try:
        with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
            ctype = resp.headers.get("Content-Type", "")
            body = None
            if "html" in ctype or "xml" in ctype:
                body = resp.read(2_000_000).decode("utf-8", errors="replace")
            return resp.status, resp.geturl(), body
    except urllib.error.HTTPError as e:
        return e.code, url, None
    except Exception:
        return 0, url, None  # 0 = network/connection error


def head(url):
    """Return (status, content_type, byte_size) for an image URL using a HEAD request."""
    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT}, method="HEAD")
    try:
        with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
            length = resp.headers.get("Content-Length")
            return resp.status, resp.headers.get("Content-Type", "") or "", int(length) if length else None
    except urllib.error.HTTPError as e:
        return e.code, "", None
    except Exception:
        return 0, "", None


def norm_host(url):
    host = urllib.parse.urlparse(url).netloc.lower()
    return host[4:] if host.startswith("www.") else host


def pages_from_sitemap(site):
    status, _final, body = fetch(urllib.parse.urljoin(site, "/sitemap.xml"))
    if status != 200 or not body:
        return []
    urls = []
    try:
        root = ET.fromstring(body)
        for loc in root.iter("{http://www.sitemaps.org/schemas/sitemap/0.9}loc"):
            if loc.text:
                urls.append(loc.text.strip())
    except ET.ParseError:
        return []
    return urls


def parse_page(url, html):
    parser = ImageParser(url)
    try:
        parser.feed(html)
    except Exception:
        pass
    return {"images": parser.images}, parser.links


def extract_from_cache(cache_path):
    """Pure: turn a shared page cache (from fetch_pages.py) into an image inventory.

    No network — parses the cached HTML for exactly the fields this audit needs.
    (The optional --check-files image HEAD-probe still hits the network if asked.)
    """
    with open(cache_path, encoding="utf-8") as f:
        cache = json.load(f)
    pages = {}
    for url, page in cache.get("pages", {}).items():
        html = page.get("html")
        status = page.get("status", 0)
        if not html:
            pages[url] = {"status": status, "images": []}
            continue
        info, _links = parse_page(page.get("final_url") or url, html)
        info["status"] = status
        pages[url] = info
    return cache.get("site", cache_path), pages


def crawl(site, max_pages):
    start = site.rstrip("/")
    host = norm_host(start)
    seeds = pages_from_sitemap(start) or [start]
    queue = deque(seeds[:max_pages])
    seen = set(queue)
    pages = {}
    while queue and len(pages) < max_pages:
        url = queue.popleft()
        status, final_url, html = fetch(url)
        print(f"[{status}] {url}", file=sys.stderr)
        if html is None:
            pages[url] = {"status": status, "images": []}
            continue
        info, links = parse_page(final_url, html)
        info["status"] = status
        pages[url] = info
        for link in links:
            if norm_host(link) == host and link not in seen:
                seen.add(link)
                queue.append(link)
    return pages


def scan_local(folder):
    pages = {}
    for root, _dirs, files in os.walk(folder):
        for name in files:
            if name.lower().endswith((".html", ".htm")):
                path = os.path.join(root, name)
                with open(path, encoding="utf-8", errors="replace") as f:
                    html = f.read()
                info, _links = parse_page("file://" + os.path.abspath(path), html)
                info["status"] = 200
                pages[os.path.relpath(path, folder)] = info
    return pages


def scan_url_list(path, max_pages):
    pages = {}
    with open(path, encoding="utf-8") as f:
        urls = [line.strip() for line in f if line.strip() and not line.startswith("#")]
    for url in urls[:max_pages]:
        status, final_url, html = fetch(url)
        print(f"[{status}] {url}", file=sys.stderr)
        if html is None:
            pages[url] = {"status": status, "images": []}
            continue
        info, _links = parse_page(final_url, html)
        info["status"] = status
        pages[url] = info
    return pages


def check_files(pages):
    files = {}
    unique = set()
    for page in pages.values():
        for img in page.get("images", []):
            if img.get("src") and img["src"].startswith(("http://", "https://")):
                unique.add(img["src"])
    for i, src in enumerate(sorted(unique), 1):
        status, ctype, size = head(src)
        files[src] = {"status": status, "content_type": ctype, "bytes": size}
        print(f"  file {i}/{len(unique)} [{status}] {src}", file=sys.stderr)
    return files


def main():
    ap = argparse.ArgumentParser(description="Build an image inventory for a site.")
    ap.add_argument("source", nargs="?",
                    help="Site root URL, local folder (--local), or URL list file (--url-list)")
    ap.add_argument("--from-cache",
                    help="Extract from a shared page cache produced by fetch_pages.py (no network)")
    ap.add_argument("--max-pages", type=int, default=500)
    ap.add_argument("--output", default="image_inventory.json")
    ap.add_argument("--local", action="store_true", help="Treat source as a local folder of HTML files")
    ap.add_argument("--url-list", action="store_true", help="Treat source as a text file of URLs")
    ap.add_argument("--check-files", action="store_true",
                    help="HEAD-request each image URL to record status, type, and byte size")
    args = ap.parse_args()

    if args.from_cache:
        site, pages = extract_from_cache(args.from_cache)
    elif not args.source:
        ap.error("provide a source, or --from-cache page_cache.json")
    elif args.local:
        site, pages = args.source, scan_local(args.source)
    elif args.url_list:
        site, pages = args.source, scan_url_list(args.source, args.max_pages)
    else:
        site, pages = args.source, crawl(args.source, args.max_pages)

    out = {"site": site, "checked_files": bool(args.check_files), "pages": pages}
    if args.check_files:
        out["files"] = check_files(pages)

    with open(args.output, "w", encoding="utf-8") as f:
        json.dump(out, f, indent=2, ensure_ascii=False)
    total_imgs = sum(len(p.get("images", [])) for p in pages.values())
    print(f"Wrote {len(pages)} pages ({total_imgs} images) to {args.output}", file=sys.stderr)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Audit an image inventory JSON (from extract_images.py) and emit audit findings.

Usage:
    python3 audit_images.py image_inventory.json [--output audit_report.json]
        [--max-bytes 200000] [--lazy-after 1]

Checks implemented (see references/audit-checks.md):
- missing_alt: <img> with no alt attribute at all (high)
- broken_image: image URL returns a non-200 status (high, needs --check-files)
- empty_alt: alt="" — valid only for decorative images, flagged for review (info)
- missing_dimensions: no width and/or height attribute, risking layout shift (medium)
- oversized_file: image larger than --max-bytes (medium, needs --check-files)
- not_lazy_loaded: img beyond --lazy-after on the page without loading="lazy" (low)
- legacy_format: jpg/png/gif served without a modern <picture> source (low)
- generic_filename: uninformative filename (e.g. IMG_1234, screenshot, untitled) (low)
- alt_too_long: alt text over 125 characters (low)
- redundant_alt: alt text starting with "image of"/"photo of"/"picture of" (low)
- duplicate_alt: identical non-empty alt reused across many distinct images (info)

Uses only the Python standard library.
"""

import argparse
import json
import os
import re
import sys
import urllib.parse
from collections import Counter, defaultdict

ALT_MAX = 125
MODERN_FORMATS = {"webp", "avif", "svg"}
LEGACY_EXTENSIONS = {"jpg", "jpeg", "png", "gif", "bmp", "tiff"}
GENERIC_PATTERNS = [
    re.compile(r"^img[\W_]*\d+$", re.I),
    re.compile(r"^image[\W_]*\d*$", re.I),
    re.compile(r"^dsc[\W_]*\d+$", re.I),
    re.compile(r"^dscn[\W_]*\d+$", re.I),
    re.compile(r"^photo[\W_]*\d*$", re.I),
    re.compile(r"^pic[\W_]*\d*$", re.I),
    re.compile(r"^screen ?shot.*$", re.I),
    re.compile(r"^screenshot.*$", re.I),
    re.compile(r"^untitled.*$", re.I),
    re.compile(r"^download.*$", re.I),
    re.compile(r"^[0-9a-f]{16,}$", re.I),      # hash-like names
    re.compile(r"^\d{6,}$"),                     # all-digit names
]
REDUNDANT_PREFIXES = ("image of", "picture of", "photo of", "graphic of", "a picture of")


def filename_stem(src):
    path = urllib.parse.urlparse(src).path
    base = os.path.basename(path)
    stem, _ext = os.path.splitext(base)
    return urllib.parse.unquote(stem)


def extension(src):
    path = urllib.parse.urlparse(src).path
    return os.path.splitext(path)[1].lower().lstrip(".")


def main():
    ap = argparse.ArgumentParser(description="Run image SEO audit checks.")
    ap.add_argument("inventory", help="image_inventory.json from extract_images.py")
    ap.add_argument("--output", default="audit_report.json")
    ap.add_argument("--max-bytes", type=int, default=200_000,
                    help="flag images larger than this many bytes (default 200000)")
    ap.add_argument("--lazy-after", type=int, default=1,
                    help="images at this 0-based position or later should be lazy-loaded")
    args = ap.parse_args()

    with open(args.inventory, encoding="utf-8") as f:
        data = json.load(f)
    pages = data.get("pages", {})
    files = data.get("files", {})
    checked = data.get("checked_files", False)

    findings = {
        "missing_alt": [], "broken_image": [], "empty_alt": [],
        "missing_dimensions": [], "oversized_file": [], "not_lazy_loaded": [],
        "legacy_format": [], "generic_filename": [], "alt_too_long": [],
        "redundant_alt": [], "duplicate_alt": [],
    }

    total_images = 0
    with_alt = 0
    alt_to_srcs = defaultdict(set)

    for url, page in pages.items():
        if page.get("status", 200) != 200:
            continue
        for img in page.get("images", []):
            total_images += 1
            src = img.get("src")
            alt = img.get("alt")
            where = {"page": url, "src": src}

            # Alt text
            if alt is None:
                findings["missing_alt"].append(where)
            elif alt.strip() == "":
                findings["empty_alt"].append(where)
            else:
                with_alt += 1
                alt_to_srcs[" ".join(alt.lower().split())].add(src)
                if len(alt) > ALT_MAX:
                    findings["alt_too_long"].append({**where, "alt": alt, "length": len(alt)})
                if alt.lower().lstrip().startswith(REDUNDANT_PREFIXES):
                    findings["redundant_alt"].append({**where, "alt": alt})

            # Dimensions
            if not img.get("width") or not img.get("height"):
                findings["missing_dimensions"].append(where)

            # Lazy loading
            if (img.get("position", 0) >= args.lazy_after
                    and img.get("loading") != "lazy"):
                findings["not_lazy_loaded"].append({**where, "position": img.get("position")})

            # Format / filename (need a real src)
            if src:
                ext = extension(src)
                if ext in LEGACY_EXTENSIONS and not img.get("in_picture"):
                    findings["legacy_format"].append({**where, "format": ext})
                stem = filename_stem(src)
                if stem and any(p.match(stem) for p in GENERIC_PATTERNS):
                    findings["generic_filename"].append({**where, "filename": stem})

            # File-level checks (only when extract was run with --check-files)
            if checked and src in files:
                info = files[src]
                if info.get("status", 0) >= 400 or info.get("status", 0) == 0:
                    findings["broken_image"].append({**where, "status": info.get("status")})
                size = info.get("bytes")
                if size and size > args.max_bytes:
                    findings["oversized_file"].append({**where, "bytes": size})

    # Duplicate alt: same alt text across 3+ distinct image URLs
    for alt, srcs in alt_to_srcs.items():
        if len(srcs) >= 3:
            findings["duplicate_alt"].append({"alt": alt, "count": len(srcs),
                                              "examples": sorted(srcs)[:5]})

    severity = {
        "missing_alt": "high", "broken_image": "high",
        "missing_dimensions": "medium", "oversized_file": "medium",
        "not_lazy_loaded": "low", "legacy_format": "low",
        "generic_filename": "low", "alt_too_long": "low", "redundant_alt": "low",
        "empty_alt": "info", "duplicate_alt": "info",
    }
    summary = {
        "pages_analyzed": sum(1 for p in pages.values() if p.get("status", 200) == 200),
        "images_found": total_images,
        "images_with_alt": with_alt,
        "alt_coverage_pct": round(100 * with_alt / total_images, 1) if total_images else 0,
        "checked_files": checked,
        "issues_by_check": {k: len(v) for k, v in findings.items()},
        "issues_by_severity": {
            level: sum(len(findings[k]) for k, s in severity.items() if s == level)
            for level in ("high", "medium", "low", "info")
        },
    }
    report = {"summary": summary, "severity": severity, "findings": findings}

    with open(args.output, "w", encoding="utf-8") as f:
        json.dump(report, f, indent=2, ensure_ascii=False)
    print(json.dumps(summary, indent=2))
    print(f"Full report written to {args.output}", file=sys.stderr)


if __name__ == "__main__":
    main()