shopify-image-audit 0.3.0__tar.gz

shopify_image_audit-0.3.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: shopify-image-audit
+Version: 0.3.0
+Summary: Shopify store image audit - Lighthouse-based analysis with heuristic and ML scoring
+Author: xopsio
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xopsio/shopify-image-audit
+Project-URL: Repository, https://github.com/xopsio/shopify-image-audit
+Project-URL: Issues, https://github.com/xopsio/shopify-image-audit/issues
+Keywords: shopify,lighthouse,image-audit,performance,pagespeed,audit,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: pydantic>=2.6
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: requests>=2.31
+Requires-Dist: weasyprint<70,>=69.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# Shopify Image Audit
+
+[![CI](https://github.com/xopsio/shopify-image-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/xopsio/shopify-image-audit/actions)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![ruff](https://img.shields.io/badge/lint-ruff-green)](https://docs.astral.sh/ruff/)
+[![tests](https://img.shields.io/badge/tests-489_passing-brightgreen)](#testing)
+
+A Lighthouse-based image audit tool for Shopify stores. Produces per-image
+scores, role assignments, optimisation recommendations, and a **before/after
+comparison** workflow that proves image-optimisation ROI to paying customers.
+
+Designed for the 99–199 € audit-on-demand business model: run the audit,
+deliver a customer-ready HTML report, optionally compare live metrics after
+the customer implements the recommendations.
+
+---
+
+## Quickstart
+
+```bash
+git clone https://github.com/xopsio/shopify-image-audit.git
+cd shopify-image-audit
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+
+# Verify the install
+audit version
+pytest -q                                              # 390 tests
+```
+
+---
+
+## CLI commands
+
+The tool ships with a single Typer app. Run `audit --help` for the full list;
+below are the high-value entry points.
+
+### `audit run <url>` — full Lighthouse + audit pipeline
+```bash
+audit run https://kauppa.myshopify.com --device mobile --runs 3 \
+    --out-dir artifacts
+# -> artifacts/lhr_run1.json, audit_result.json (schema-compliant)
+```
+
+### `audit baseline <lhr.json> --save baseline.json` — capture baseline
+```bash
+audit baseline fixtures/before_after/before_lcp.json \
+    --save baseline.json \
+    --url https://demo.myshopify.com
+# -> Baseline saved to baseline.json
+```
+
+### `audit compare <baseline> <current>` — before/after (file or URL)
+```bash
+# File vs file (offline)
+audit compare baseline.json fixtures/before_after/after_lcp.json \
+    -o comparison.html --json comparison.json
+
+# File vs live URL (fetches via PageSpeed Insights API)
+audit compare baseline.json https://demo.myshopify.com \
+    --strategy mobile --api-key YOUR_KEY \
+    -o comparison.html
+
+# HTML report includes a per-image delta table (bytes, score, status per image).
+# PDF export via --pdf flag.
+```
+Exit codes: `0` success, `2` invalid args, `10` backend failure.
+
+### `audit report <audit_result.json>` — HTML or PDF report
+```bash
+audit report baseline.json -o report.html          # HTML
+audit report baseline.json -o report.pdf --pdf     # PDF (WeasyPrint)
+```
+
+### `audit measure <url>` — live PageSpeed metrics only
+```bash
+audit measure https://demo.myshopify.com --strategy mobile
+# -> JSON metrics to stdout (or --output metrics.json)
+```
+
+### `audit shopify <auth|inventory> <store>` — Shopify Admin API
+```bash
+# Verify a token
+audit shopify auth mystore.myshopify.com --access-token shpat_xxx
+# -> Token valid, prints shop info
+
+# List all image URLs (products + theme assets)
+audit shopify inventory mystore.myshopify.com --access-token shpat_xxx -o inventory.json
+```
+Read-only scopes required (`read_products`, `read_themes`, `read_shop`).
+See `docs/integrations/SHOPIFY_ADMIN.md` for token-acquisition steps.
+
+### `audit score <audit_input.json> --ranker {heuristic|ml}`
+```bash
+audit score extracted.json                    # default: heuristic
+audit score extracted.json --ranker ml        # weighted feature ensemble
+```
+
+Full reference: [`docs/spec/cli_v0_1.md`](docs/spec/cli_v0_1.md).
+
+---
+
+## Scoring algorithms
+
+The pipeline assigns each image a `role`, a `score` (0–100), and a
+`recommendation`. Two rankers ship, switchable via `--ranker ml`:
+
+| Ranker | Formula | Use case |
+|--------|---------|----------|
+| `heuristic` (default) | bytes per displayed pixel (bpp) + LCP penalty | fast, predictable baseline |
+| `ml` | weighted ensemble: f_size, f_density, f_format, f_dim_match + LCP strictness | richer signal, more honest scoring |
+
+Both produce the same output contract (role + score + recommendation). The ML
+ranker is a hand-coded feature ensemble, not a statistical model — see
+[`src/audit/ranker_ml.py`](src/audit/ranker_ml.py) for the design rationale
+(no model deps, deterministic, fully explainable via `ml_features()`).
+
+---
+
+## Architecture
+
+```
+src/
+├── audit/                    # scoring + reporting
+│   ├── models.py             # Pydantic v2 schemas (AuditResult, ComparisonResult, ImageDelta)
+│   ├── parser.py             # Lighthouse / fixture JSON parser
+│   ├── ranker_heuristic.py   # default ranker (bpp-based)
+│   ├── ranker_ml.py          # opt-in ML-style ranker (weighted ensemble)
+│   └── report.py             # HTML/PDF report renderer (split into _render_* funcs)
+├── core/                     # core algorithms
+│   ├── image_extractor.py    # LHR image audit extraction
+│   ├── image_signals.py      # shared displayed_area, assign_role, _safe_int
+│   └── baseline_manager.py   # save/load baselines + compare() + per-image matching
+├── engine/                   # orchestration + CLI
+│   ├── cli.py                # Typer app (run, measure, baseline, compare, shopify, ...)
+│   ├── cli_helpers/          # extracted CLI helpers (validators, dispatchers, table, errors)
+│   └── audit_orchestrator.py # run_audit() pipeline
+└── integrations/             # external APIs
+    ├── pagespeed_api.py      # PageSpeed Insights (measure + fetch_lighthouse_json)
+    └── shopify_admin.py      # Shopify Admin API (auth, products, theme_assets)
+
+schemas/audit_result.schema.json    # JSON Schema contract (validated by tests)
+tests/                              # 390 tests, single-writer (ZCode)
+docs/examples/                       # live demo report + comparison JSON
+docs/integrations/                   # Shopify Admin API token guide
+```
+
+The codebase is governed by **a single ZCode agent** (see
+[`docs/governance.md`](docs/governance.md) v1.3).
+
+---
+
+## Testing
+
+```bash
+pytest -q                                # 489 tests, single-writer discipline
+pytest --cov=src --cov-report=term       # ~87% coverage
+ruff check src/ tests/                   # 0 violations
+```
+
+The CI workflow runs `pytest -q` + `ruff check` on Python 3.11 and 3.12 for
+every PR. Branch protection on `main` requires both checks to pass before
+merge. See [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+---
+
+## Customer deliverables (Phase 1)
+
+- **Customer report template** — [`docs/CUSTOMER_REPORT_TEMPLATE.md`](docs/CUSTOMER_REPORT_TEMPLATE.md)
+- **Onboarding workflow** — [`docs/CUSTOMER_ONBOARDING.md`](docs/CUSTOMER_ONBOARDING.md)
+- **Example audit report** (Nordic Lifestyle demo store, LCP 4200ms → 1800ms) — [`docs/examples/demo_audit_report.html`](docs/examples/demo_audit_report.html)
+- **Example comparison data** — [`docs/examples/demo_comparison.json`](docs/examples/demo_comparison.json)
+
+---
+
+## Roadmap
+
+- ✅ Sprint 1 — v0.1.0 baseline (parser, ranker, orchestrator, CLI, HTML report, 103 tests)
+- ✅ Sprint 2 — before/after workflow, customer docs, ML ranker, live URL compare, CI, governance cleanup (276 tests)
+- ✅ Sprint 3 — PDF export, per-image deltas, Shopify Admin API, v0.2.0 release prep (390 tests)
+- ✅ Sprint 4 — Branded reports, ROI-ranked recs, audit history, v0.3.0 (489 tests)
+  - Branded report templates (--brand-logo, --brand-color)
+  - ROI-ranked recommendations (ComparisonRecommendation model)
+  - Audit history + trend view (HistoryStore, `audit history list/show`)
+
+---
+
+## Further reading
+
+- [`docs/spec/cli_v0_1.md`](docs/spec/cli_v0_1.md) — full CLI specification
+- [`docs/governance.md`](docs/governance.md) — ownership + workflow
+- [`docs/runbook/measurement_protocol.md`](docs/runbook/measurement_protocol.md) — how LCP/CLS/INP are measured deterministically
+- [`docs/SPRINT_1_COMPLETE.md`](docs/SPRINT_1_COMPLETE.md) — what shipped in Sprint 1
+- [`docs/SPRINT_3_PLAN.md`](docs/SPRINT_3_PLAN.md) — Sprint 3 breakdown (all done)
+- [`docs/SPRINT_4_PLAN.md`](docs/SPRINT_4_PLAN.md) — Sprint 4 breakdown (all done)
+- [`QA_CHECKLIST.md`](QA_CHECKLIST.md) — quality gates

shopify_image_audit-0.3.0/README.md

@@ -0,0 +1,196 @@
+# Shopify Image Audit
+
+[![CI](https://github.com/xopsio/shopify-image-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/xopsio/shopify-image-audit/actions)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![ruff](https://img.shields.io/badge/lint-ruff-green)](https://docs.astral.sh/ruff/)
+[![tests](https://img.shields.io/badge/tests-489_passing-brightgreen)](#testing)
+
+A Lighthouse-based image audit tool for Shopify stores. Produces per-image
+scores, role assignments, optimisation recommendations, and a **before/after
+comparison** workflow that proves image-optimisation ROI to paying customers.
+
+Designed for the 99–199 € audit-on-demand business model: run the audit,
+deliver a customer-ready HTML report, optionally compare live metrics after
+the customer implements the recommendations.
+
+---
+
+## Quickstart
+
+```bash
+git clone https://github.com/xopsio/shopify-image-audit.git
+cd shopify-image-audit
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+
+# Verify the install
+audit version
+pytest -q                                              # 390 tests
+```
+
+---
+
+## CLI commands
+
+The tool ships with a single Typer app. Run `audit --help` for the full list;
+below are the high-value entry points.
+
+### `audit run <url>` — full Lighthouse + audit pipeline
+```bash
+audit run https://kauppa.myshopify.com --device mobile --runs 3 \
+    --out-dir artifacts
+# -> artifacts/lhr_run1.json, audit_result.json (schema-compliant)
+```
+
+### `audit baseline <lhr.json> --save baseline.json` — capture baseline
+```bash
+audit baseline fixtures/before_after/before_lcp.json \
+    --save baseline.json \
+    --url https://demo.myshopify.com
+# -> Baseline saved to baseline.json
+```
+
+### `audit compare <baseline> <current>` — before/after (file or URL)
+```bash
+# File vs file (offline)
+audit compare baseline.json fixtures/before_after/after_lcp.json \
+    -o comparison.html --json comparison.json
+
+# File vs live URL (fetches via PageSpeed Insights API)
+audit compare baseline.json https://demo.myshopify.com \
+    --strategy mobile --api-key YOUR_KEY \
+    -o comparison.html
+
+# HTML report includes a per-image delta table (bytes, score, status per image).
+# PDF export via --pdf flag.
+```
+Exit codes: `0` success, `2` invalid args, `10` backend failure.
+
+### `audit report <audit_result.json>` — HTML or PDF report
+```bash
+audit report baseline.json -o report.html          # HTML
+audit report baseline.json -o report.pdf --pdf     # PDF (WeasyPrint)
+```
+
+### `audit measure <url>` — live PageSpeed metrics only
+```bash
+audit measure https://demo.myshopify.com --strategy mobile
+# -> JSON metrics to stdout (or --output metrics.json)
+```
+
+### `audit shopify <auth|inventory> <store>` — Shopify Admin API
+```bash
+# Verify a token
+audit shopify auth mystore.myshopify.com --access-token shpat_xxx
+# -> Token valid, prints shop info
+
+# List all image URLs (products + theme assets)
+audit shopify inventory mystore.myshopify.com --access-token shpat_xxx -o inventory.json
+```
+Read-only scopes required (`read_products`, `read_themes`, `read_shop`).
+See `docs/integrations/SHOPIFY_ADMIN.md` for token-acquisition steps.
+
+### `audit score <audit_input.json> --ranker {heuristic|ml}`
+```bash
+audit score extracted.json                    # default: heuristic
+audit score extracted.json --ranker ml        # weighted feature ensemble
+```
+
+Full reference: [`docs/spec/cli_v0_1.md`](docs/spec/cli_v0_1.md).
+
+---
+
+## Scoring algorithms
+
+The pipeline assigns each image a `role`, a `score` (0–100), and a
+`recommendation`. Two rankers ship, switchable via `--ranker ml`:
+
+| Ranker | Formula | Use case |
+|--------|---------|----------|
+| `heuristic` (default) | bytes per displayed pixel (bpp) + LCP penalty | fast, predictable baseline |
+| `ml` | weighted ensemble: f_size, f_density, f_format, f_dim_match + LCP strictness | richer signal, more honest scoring |
+
+Both produce the same output contract (role + score + recommendation). The ML
+ranker is a hand-coded feature ensemble, not a statistical model — see
+[`src/audit/ranker_ml.py`](src/audit/ranker_ml.py) for the design rationale
+(no model deps, deterministic, fully explainable via `ml_features()`).
+
+---
+
+## Architecture
+
+```
+src/
+├── audit/                    # scoring + reporting
+│   ├── models.py             # Pydantic v2 schemas (AuditResult, ComparisonResult, ImageDelta)
+│   ├── parser.py             # Lighthouse / fixture JSON parser
+│   ├── ranker_heuristic.py   # default ranker (bpp-based)
+│   ├── ranker_ml.py          # opt-in ML-style ranker (weighted ensemble)
+│   └── report.py             # HTML/PDF report renderer (split into _render_* funcs)
+├── core/                     # core algorithms
+│   ├── image_extractor.py    # LHR image audit extraction
+│   ├── image_signals.py      # shared displayed_area, assign_role, _safe_int
+│   └── baseline_manager.py   # save/load baselines + compare() + per-image matching
+├── engine/                   # orchestration + CLI
+│   ├── cli.py                # Typer app (run, measure, baseline, compare, shopify, ...)
+│   ├── cli_helpers/          # extracted CLI helpers (validators, dispatchers, table, errors)
+│   └── audit_orchestrator.py # run_audit() pipeline
+└── integrations/             # external APIs
+    ├── pagespeed_api.py      # PageSpeed Insights (measure + fetch_lighthouse_json)
+    └── shopify_admin.py      # Shopify Admin API (auth, products, theme_assets)
+
+schemas/audit_result.schema.json    # JSON Schema contract (validated by tests)
+tests/                              # 390 tests, single-writer (ZCode)
+docs/examples/                       # live demo report + comparison JSON
+docs/integrations/                   # Shopify Admin API token guide
+```
+
+The codebase is governed by **a single ZCode agent** (see
+[`docs/governance.md`](docs/governance.md) v1.3).
+
+---
+
+## Testing
+
+```bash
+pytest -q                                # 489 tests, single-writer discipline
+pytest --cov=src --cov-report=term       # ~87% coverage
+ruff check src/ tests/                   # 0 violations
+```
+
+The CI workflow runs `pytest -q` + `ruff check` on Python 3.11 and 3.12 for
+every PR. Branch protection on `main` requires both checks to pass before
+merge. See [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+---
+
+## Customer deliverables (Phase 1)
+
+- **Customer report template** — [`docs/CUSTOMER_REPORT_TEMPLATE.md`](docs/CUSTOMER_REPORT_TEMPLATE.md)
+- **Onboarding workflow** — [`docs/CUSTOMER_ONBOARDING.md`](docs/CUSTOMER_ONBOARDING.md)
+- **Example audit report** (Nordic Lifestyle demo store, LCP 4200ms → 1800ms) — [`docs/examples/demo_audit_report.html`](docs/examples/demo_audit_report.html)
+- **Example comparison data** — [`docs/examples/demo_comparison.json`](docs/examples/demo_comparison.json)
+
+---
+
+## Roadmap
+
+- ✅ Sprint 1 — v0.1.0 baseline (parser, ranker, orchestrator, CLI, HTML report, 103 tests)
+- ✅ Sprint 2 — before/after workflow, customer docs, ML ranker, live URL compare, CI, governance cleanup (276 tests)
+- ✅ Sprint 3 — PDF export, per-image deltas, Shopify Admin API, v0.2.0 release prep (390 tests)
+- ✅ Sprint 4 — Branded reports, ROI-ranked recs, audit history, v0.3.0 (489 tests)
+  - Branded report templates (--brand-logo, --brand-color)
+  - ROI-ranked recommendations (ComparisonRecommendation model)
+  - Audit history + trend view (HistoryStore, `audit history list/show`)
+
+---
+
+## Further reading
+
+- [`docs/spec/cli_v0_1.md`](docs/spec/cli_v0_1.md) — full CLI specification
+- [`docs/governance.md`](docs/governance.md) — ownership + workflow
+- [`docs/runbook/measurement_protocol.md`](docs/runbook/measurement_protocol.md) — how LCP/CLS/INP are measured deterministically
+- [`docs/SPRINT_1_COMPLETE.md`](docs/SPRINT_1_COMPLETE.md) — what shipped in Sprint 1
+- [`docs/SPRINT_3_PLAN.md`](docs/SPRINT_3_PLAN.md) — Sprint 3 breakdown (all done)
+- [`docs/SPRINT_4_PLAN.md`](docs/SPRINT_4_PLAN.md) — Sprint 4 breakdown (all done)
+- [`QA_CHECKLIST.md`](QA_CHECKLIST.md) — quality gates

shopify_image_audit-0.3.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shopify-image-audit"
+version = "0.3.0"
+description = "Shopify store image audit - Lighthouse-based analysis with heuristic and ML scoring"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    {name = "xopsio"},
+]
+keywords = [
+    "shopify",
+    "lighthouse",
+    "image-audit",
+    "performance",
+    "pagespeed",
+    "audit",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = [
+    "jsonschema>=4.20",
+    "pydantic>=2.6",
+    "typer>=0.12",
+    "rich>=13.7",
+    "requests>=2.31",
+    "weasyprint>=69.0,<70",
+]
+
+[project.urls]
+Homepage = "https://github.com/xopsio/shopify-image-audit"
+Repository = "https://github.com/xopsio/shopify-image-audit"
+Issues = "https://github.com/xopsio/shopify-image-audit/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4",
+    "responses>=0.25",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+audit = "engine.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+# B008: Typer's official pattern is typer.Option()/typer.Argument() in default
+# arguments — this is how Typer documents CLI definition, so the lint is a
+# false positive for this framework.
+ignore = ["B008"]

shopify_image_audit-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+