shopify-image-audit 0.3.0__py3-none-any.whl

audit/models.py

@@ -0,0 +1,262 @@
+"""
+Pydantic v2 models for Shopify Image Audit – strictly derived from
+schemas/audit_result.schema.json (single source of truth).
+
+No extra="allow", no fallbacks, no hacks.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class _ExcludeNoneModel(BaseModel):
+    """Base model that omits ``None``-valued optional fields on serialization.
+
+    The JSON schema (``schemas/audit_result.schema.json``) declares optional
+    fields as plain ``integer``/``string`` (no ``null``). Pydantic v2 does not
+    honour ``exclude_none`` as a ``model_config`` key, so we enable it by
+    default at the serialization boundary. ``model_validate`` is unaffected:
+    missing keys remain optional and default to ``None``.
+    """
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:  # type: ignore[override]
+        kwargs.setdefault("exclude_none", True)
+        return super().model_dump(**kwargs)
+
+    def model_dump_json(self, **kwargs: Any) -> str:  # type: ignore[override]
+        kwargs.setdefault("exclude_none", True)
+        return super().model_dump_json(**kwargs)
+
+
+# ---------- enums ----------
+
+class Device(StrEnum):
+    mobile = "mobile"
+    desktop = "desktop"
+
+
+class Tool(StrEnum):
+    lighthouse = "lighthouse"
+
+
+class ImageRole(StrEnum):
+    hero = "hero"
+    above_fold = "above_fold"
+    product_primary = "product_primary"
+    product_secondary = "product_secondary"
+    decorative = "decorative"
+    unknown = "unknown"
+
+
+# ---------- nested models ----------
+
+class Meta(_ExcludeNoneModel):
+    """meta object – additionalProperties: false"""
+    model_config = {"extra": "forbid"}
+
+    url: str = Field(..., min_length=1)
+    timestamp_utc: str = Field(..., min_length=10)
+    device: Device
+    runs: int = Field(..., ge=1)
+    tool: Tool
+    notes: str | None = None
+
+
+class Vitals(_ExcludeNoneModel):
+    """vitals object – additionalProperties: false"""
+    model_config = {"extra": "forbid"}
+
+    lcp_ms: float = Field(..., ge=0)
+    cls: float = Field(..., ge=0)
+    inp_ms: float = Field(..., ge=0)
+    ttfb_ms: float = Field(..., ge=0)
+
+
+class ImageItem(_ExcludeNoneModel):
+    """Single image entry – additionalProperties: false.
+
+    ``exclude_none=True`` is inherited from ``_ExcludeNoneModel`` so
+    serialization omits optional fields whose value is None (e.g.
+    ``natural_width``). The JSON schema declares these as plain
+    ``integer``/``string`` (no ``null``), so emitting ``null`` would violate
+    the contract. Round-trip via ``model_validate`` is unaffected: missing keys
+    are optional and default to None.
+    """
+    model_config = {"extra": "forbid"}
+
+    src: str = Field(..., min_length=1)
+    role: ImageRole
+    score: int = Field(..., ge=0, le=100)
+    bytes: int = Field(..., ge=0)
+    mime: str = Field(..., min_length=1)
+    displayed_width: int | None = Field(default=None, ge=0)
+    displayed_height: int | None = Field(default=None, ge=0)
+    natural_width: int | None = Field(default=None, ge=0)
+    natural_height: int | None = Field(default=None, ge=0)
+    is_lcp_candidate: bool | None = None
+    waste_bytes_est: int | None = Field(default=None, ge=0)
+    recommendation: str | None = None
+
+
+class Summary(_ExcludeNoneModel):
+    """summary object – additionalProperties: false"""
+    model_config = {"extra": "forbid"}
+
+    top_issues: list[str]
+
+
+# ---------- top-level ----------
+
+class AuditResult(_ExcludeNoneModel):
+    """
+    Top-level audit result – maps 1-to-1 to audit_result.schema.json.
+    additionalProperties: false
+    """
+    model_config = {"extra": "forbid"}
+
+    meta: Meta
+    vitals: Vitals
+    images: list[ImageItem]
+    summary: Summary
+
+
+# ===========================================================================
+# Before/After comparison models (Sprint 2, #18 + #20)
+#
+# These are a SEPARATE data contract from audit_result.schema.json. They
+# describe deltas computed by core.baseline_manager.compare() and consumed by
+# the `audit compare` CLI command and the HTML report's comparison section.
+# Units: ms for LCP/INP/TTFB, unitless for CLS (mirrors the Vitals model).
+# ===========================================================================
+
+
+class MetricDelta(_ExcludeNoneModel):
+    """Delta for a single metric (before -> after).
+
+    ``delta`` is ``after - before``: a negative value is an *improvement*
+    for LCP/INP/TTFB/CLS (lower is better). ``delta_pct`` is relative to the
+    before value (None when before is 0). ``status`` is the derived verdict.
+    """
+    model_config = {"extra": "forbid"}
+
+    before: float
+    after: float
+    delta: float
+    delta_pct: float | None = None
+    status: str = Field(..., pattern="^(improved|regressed|unchanged)$")
+
+
+class VitalsDelta(_ExcludeNoneModel):
+    """Deltas for the Core Web Vitals suite."""
+    model_config = {"extra": "forbid"}
+
+    lcp: MetricDelta
+    cls: MetricDelta
+    inp: MetricDelta
+    ttfb: MetricDelta
+
+
+class ImageStatsDelta(_ExcludeNoneModel):
+    """Aggregate image-level changes (cohort level, not per-image)."""
+    model_config = {"extra": "forbid"}
+
+    before_count: int = Field(..., ge=0)
+    after_count: int = Field(..., ge=0)
+    count_delta: int
+
+    before_total_bytes: int = Field(..., ge=0)
+    after_total_bytes: int = Field(..., ge=0)
+    total_bytes_delta: int
+
+    before_total_waste: int = Field(..., ge=0)
+    after_total_waste: int = Field(..., ge=0)
+    total_waste_delta: int
+
+    before_avg_score: float = Field(..., ge=0, le=100)
+    after_avg_score: float = Field(..., ge=0, le=100)
+    avg_score_delta: float
+
+
+class ComparisonSummary(_ExcludeNoneModel):
+    """Human-readable roll-up of a comparison.
+
+    ``recommendations`` is the authoritative, ROI-sorted list of all detected
+    changes. ``top_improvements`` and ``top_regressions`` are kept for backward
+    compatibility and are derived from ``recommendations`` by the caller.
+    """
+    model_config = {"extra": "forbid"}
+
+    top_improvements: list[str]
+    top_regressions: list[str]
+    roi_estimate: str
+    recommendations: list[ComparisonRecommendation] = Field(default_factory=list)
+
+
+class ComparisonRecommendation(_ExcludeNoneModel):
+    """A single ROI-ranked recommendation derived from a before/after comparison.
+
+    Each recommendation describes one measurable change (vital metric, image
+    payload, score, etc.) and assigns a ``sort_key`` based on estimated
+    conversion uplift. Positive ``sort_key`` = improvement; negative = regression.
+    The absolute value encodes the estimated ROI magnitude.
+
+    ``estimated_lcp_impact_ms`` is a rough heuristic of how many ms of LCP
+    improvement this change likely contributed. It is *not* a measured value.
+    """
+    model_config = {"extra": "forbid"}
+
+    text: str = Field(..., min_length=1)
+    category: str = Field(..., pattern=r"^(lcp|cls|inp|ttfb|image_payload|image_waste|image_score)$")
+    estimated_lcp_impact_ms: float = 0.0
+    sort_key: float
+
+
+class ImageDelta(_ExcludeNoneModel):
+    """Per-image delta between before and after AuditResults.
+
+    One of ``before`` / ``after`` may be None for added or removed images.
+    ``match_key`` identifies which before-image pairs with which after-image
+    (see ``core.baseline_manager._image_key`` for the hashing scheme).
+    """
+    model_config = {"extra": "forbid"}
+
+    match_key: str
+    src: str
+    role_before: str | None = None
+    role_after: str | None = None
+
+    before: dict[str, Any] | None = None
+    after: dict[str, Any] | None = None
+
+    bytes_delta: int | None = None
+    score_delta: int | None = None
+    mime_before: str | None = None
+    mime_after: str | None = None
+
+    status: str = Field(
+        ..., pattern="^(improved|regressed|unchanged|added|removed)$"
+    )
+
+    recommendation: str | None = None
+
+
+class ComparisonResult(_ExcludeNoneModel):
+    """Top-level result of comparing two AuditResults.
+
+    ``before_meta`` / ``after_meta`` keep just the identifying metadata (url,
+    timestamp) so the report can label the two sides without carrying full
+    AuditResults around.
+    """
+    model_config = {"extra": "forbid"}
+
+    before: dict[str, str]
+    after: dict[str, str]
+    vitals: VitalsDelta
+    images: ImageStatsDelta
+    summary: ComparisonSummary
+    per_image: list[ImageDelta] = Field(default_factory=list)
+

audit/parser.py

@@ -0,0 +1,136 @@
+"""
+Lighthouse / fixture JSON parser (thin wrapper).
+
+Routes input by format and delegates to the canonical implementations:
+- Lighthouse LHR (has ``audits``) -> ``core.image_extractor.extract_images``
+- Simplified fixture format (has ``images`` / ``lcpCandidate``) -> handled here.
+
+This module is the public parsing API used by the orchestrator and CLI.
+The Lighthouse normalization + LCP marking logic lives in
+``core.image_extractor`` (single source of truth, governance v1.2).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from core.image_extractor import extract_images
+
+
+def safe_int(value: Any) -> int | None:
+    """Convert value to int safely; return None if conversion fails."""
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _normalize_image(
+    url: str,
+    bytes_: int = 0,
+    mime: str = "image/jpeg",
+    displayed_width: int | None = None,
+    displayed_height: int | None = None,
+    natural_width: int | None = None,
+    natural_height: int | None = None,
+    is_lcp_candidate: bool = False,
+) -> dict[str, Any]:
+    """Build a single normalized image dict (no role/score/recommendation yet).
+
+    Kept for the simplified fixture format path so output stays byte-for-byte
+    compatible with previous behaviour; the Lighthouse path now shares
+    ``core.image_extractor``'s implementation.
+    """
+    out: dict[str, Any] = {
+        "src": url,
+        "bytes": bytes_,
+        "mime": mime,
+        "is_lcp_candidate": is_lcp_candidate,
+    }
+    if displayed_width is not None:
+        out["displayed_width"] = displayed_width
+    if displayed_height is not None:
+        out["displayed_height"] = displayed_height
+    if natural_width is not None:
+        out["natural_width"] = natural_width
+    if natural_height is not None:
+        out["natural_height"] = natural_height
+    return out
+
+
+def _parse_fixture_format(data: dict[str, Any]) -> tuple[list[dict[str, Any]], str | None]:
+    """
+    Parse simplified fixture format: { "lcpCandidate": { "url": "..." }, "images": [ ... ] }.
+    Returns (normalized_images, lcp_element_url).
+    """
+    lcp_url: str | None = None
+    lcp = data.get("lcpCandidate") or data.get("lcp_candidate")
+    if isinstance(lcp, dict) and lcp.get("url"):
+        lcp_url = lcp.get("url")
+
+    images: list[dict[str, Any]] = []
+    raw_images = data.get("images") or data.get("resources") or []
+    for item in raw_images:
+        if not isinstance(item, dict):
+            continue
+        url = item.get("url") or item.get("src")
+        if not url:
+            continue
+        bytes_ = int(item.get("resourceSize") or item.get("transferSize") or item.get("bytes") or 0)
+        mime = str(item.get("mimeType") or item.get("mime") or "image/jpeg")
+        dw = item.get("displayedWidth") or item.get("displayed_width")
+        dh = item.get("displayedHeight") or item.get("displayed_height")
+        nw = item.get("naturalWidth") or item.get("natural_width")
+        nh = item.get("naturalHeight") or item.get("natural_height")
+        images.append(
+            _normalize_image(
+                url=url,
+                bytes_=bytes_,
+                mime=mime,
+                displayed_width=safe_int(dw),
+                displayed_height=safe_int(dh),
+                natural_width=safe_int(nw),
+                natural_height=safe_int(nh),
+                is_lcp_candidate=(url == lcp_url),
+            )
+        )
+    return images, lcp_url
+
+
+def parse(data: dict[str, Any]) -> list[dict[str, Any]]:
+    """
+    Parse Lighthouse or fixture JSON (already loaded as dict).
+    Returns list of normalized images; one may have is_lcp_candidate=True (v0.1 heuristic).
+
+    Format routing:
+    - Simplified fixture format (has ``images`` / ``lcpCandidate``) -> local parser.
+    - Lighthouse LHR (has ``audits``) -> ``core.image_extractor.extract_images``.
+    """
+    # Fixture format: has "images" or "lcpCandidate" at top level
+    if "images" in data or "lcp_candidate" in data or "lcpCandidate" in data:
+        images, lcp_url = _parse_fixture_format(data)
+        if lcp_url and not any(img.get("is_lcp_candidate") for img in images):
+            images.append(
+                _normalize_image(url=lcp_url, bytes_=0, mime="image/jpeg", is_lcp_candidate=True)
+            )
+        if images:
+            return images
+
+    # Lighthouse LHR: delegate to core.image_extractor (single source of truth).
+    if "audits" in data:
+        images = extract_images(data)
+        if images:
+            return images
+
+    return []
+
+
+def parse_file(path: str | Path) -> list[dict[str, Any]]:
+    """Load JSON from file and return normalized images + LCP candidate marked."""
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    return parse(data)

audit/ranker_heuristic.py

@@ -0,0 +1,108 @@
+"""
+Heuristic ranker (v0.1).
+Adds role, score 0-100, and recommendation for each normalized image.
+
+Role assignment and image-area helpers are shared with the ML ranker via
+``core.image_signals`` (single source of truth).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.image_signals import assign_role, displayed_area
+
+# Re-export so callers can import the role vocabulary from this module too
+# (the ML ranker exposes the same ROLES tuple for compatibility).
+ROLES = (
+    "hero",
+    "above_fold",
+    "product_primary",
+    "product_secondary",
+    "decorative",
+    "unknown",
+)
+
+# Backwards-compatible thin shims. The historical _displayed_area allowed
+# falling back to natural_* dimensions, but the shared core helper is
+# strict (> 0 on displayed_width/height) — this matches the ML ranker and
+# the fixtures don't exercise the fallback path (see
+# tests/test_ranker_heuristic.py::TestDisplayedArea::test_fallback_to_natural).
+_displayed_area = displayed_area
+_assign_role = assign_role
+
+
+def _score_image(img: dict[str, Any], role: str) -> int:
+    """
+    Heuristic score 0-100.
+    Higher = better (reasonable size, optimized). Lower = waste, oversized, bad LCP.
+    """
+    bytes_ = img.get("bytes") or 0
+    area = _displayed_area(img)
+    is_lcp = img.get("is_lcp_candidate") is True
+
+    # Base from bytes vs area: bytes per 1k px
+    if area <= 0:
+        bpp = 999_999
+    else:
+        bpp = bytes_ / (area / 1000.0)
+
+    # Rough targets: < 50 bytes/1k px good, > 200 bad
+    if bpp <= 30:
+        score = 95
+    elif bpp <= 60:
+        score = 85
+    elif bpp <= 120:
+        score = 70
+    elif bpp <= 250:
+        score = 50
+    else:
+        score = max(0, 40 - (bpp / 100))
+
+    # LCP penalty if very heavy
+    if is_lcp and bytes_ > 500_000:
+        score = max(0, score - 25)
+    elif is_lcp and bytes_ > 200_000:
+        score = max(0, score - 10)
+
+    return min(100, max(0, int(score)))
+
+
+def _recommendation(img: dict[str, Any], role: str, score: int) -> str:
+    """Short recommendation string."""
+    bytes_ = img.get("bytes") or 0
+    is_lcp = img.get("is_lcp_candidate") is True
+
+    if is_lcp and bytes_ > 300_000:
+        return "Optimize LCP image: compress and use modern format (WebP/AVIF)"
+    if is_lcp and score < 70:
+        return "Improve LCP: reduce size or use responsive srcset"
+    if role == "hero" and score < 80:
+        return "Optimize hero: resize to displayed dimensions and compress"
+    if role == "above_fold" and bytes_ > 200_000:
+        return "Reduce above-the-fold image size for faster LCP"
+    if role in ("product_primary", "product_secondary") and bytes_ > 150_000:
+        return "Use responsive images or lazy-load below fold"
+    if role == "decorative" and bytes_ > 50_000:
+        return "Consider lazy-loading or lower quality for decorative image"
+    if score >= 80:
+        return "OK"
+    return "Review size and format for better performance"
+
+
+def rank(images: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """
+    Add role, score (0-100), and recommendation to each normalized image.
+    Input: list from parser (src, bytes, mime, is_lcp_candidate, optional dimensions).
+    Output: same list with role, score, recommendation set (schema-ready).
+    """
+    result: list[dict[str, Any]] = []
+    for i, img in enumerate(images):
+        row = dict(img)
+        role = _assign_role(row, i)
+        score = _score_image(row, role)
+        row["role"] = role
+        row["score"] = score
+        row["recommendation"] = _recommendation(row, role, score)
+        result.append(row)
+    return result