@cleartrip/frontguard 0.2.4 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleartrip/frontguard",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Org-wide frontend PR guardrails: linting, hygiene, any-delta, cycles, dead code, bundle/CWV hints, custom rules, optional LLM brief",
   "type": "module",
   "bin": {

package/templates/bitbucket-pipelines.yml

@@ -1,17 +1,17 @@
-# FrontGuard + PR comment (Bitbucket Cloud) — FreeKit.dev report URL
+# FrontGuard + Bitbucket PR comment: Checks table screenshot + FreeKit full HTML link
 #
-# HTML report is uploaded to https://freekit.dev via their public API (no API key for POST /sites).
-# Docs: https://freekit.dev/docs
+# 1. Runs FrontGuard → full HTML + minimal checks-only HTML (--checksSnapshotOut).
+# 2. Headless Chromium screenshots the checks page → PNG.
+# 3. Uploads PNG to Repository → Downloads (needs BITBUCKET_ACCESS_TOKEN with repository:write).
+# 4. Uploads full report HTML to FreeKit → public URL.
+# 5. PR comment = markdown image (hosted on bitbucket.org/.../downloads/...) + caption + FreeKit URL.
 #
-# Per-repo setup:
-# 1. Repository variable (secured): BITBUCKET_ACCESS_TOKEN — permission to comment on pull requests.
-# 2. Add @cleartrip/frontguard as a devDependency and use this file (or merge the step).
+# Repo variable (secured): BITBUCKET_ACCESS_TOKEN — pullrequest:write + repository:write (for Downloads).
 #
-# API hostname for comments MUST be api.bitbucket.org (Bitbucket Cloud).
+# FreeKit: POST https://freekit.dev/api/v1/sites — see templates/freekit-ci-setup.md
+# Optional: FREEKIT_BASE_URL — override API host.
 #
-# The PR comment body is the hosted https://freekit.dev/s/... URL (one line).
-#
-# Caveats (see templates/freekit-ci-setup.md): public URL, third-party service, size/rate limits.
+# If Chromium fails on your runner image, switch the screenshot step to Playwright (see comments below).
 
 image: node:20
 
@@ -19,28 +19,51 @@ pipelines:
   pull-requests:
     '**':
       - step:
-          name: FrontGuard – FreeKit report + PR comment
+          name: FrontGuard – checks image + FreeKit + PR comment
           caches:
             - node
           artifacts:
             - frontguard-report.html
             - frontguard-report.md
+            - frontguard-checks.html
+            - frontguard-checks*.png
           script:
+            - apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends chromium
             - corepack enable
             - yarn install --immutable || yarn install
+            - export FG_CHECKS_PNG="frontguard-checks-b${BITBUCKET_BUILD_NUMBER}.png"
             - |
               yarn frontguard run --markdown \
                 --htmlOut frontguard-report.html \
+                --checksSnapshotOut frontguard-checks.html \
                 > frontguard-report.md
+            - |
+              FILE_URL="file://$(pwd)/frontguard-checks.html"
+              chromium --headless --no-sandbox --disable-dev-shm-usage --disable-gpu \
+                --window-size=920,2600 \
+                --hide-scrollbars \
+                --screenshot="${FG_CHECKS_PNG}" \
+                "${FILE_URL}"
+            # Playwright alternative if Chromium is missing or crashes:
+            # - npx -y playwright@1.49.1 install chromium
+            # - npx -y playwright@1.49.1 screenshot "${FILE_URL}" "${FG_CHECKS_PNG}" --viewport-size=920,2600
             - |
               python3 << 'PY'
               import json
               import os
+              import subprocess
+              import sys
               from urllib.error import HTTPError
+              from urllib.parse import quote
               from urllib.request import Request, urlopen
 
-              base = os.environ.get("FREEKIT_BASE_URL", "https://freekit.dev").rstrip("/")
+              DETAILED = "For detailed check analysis, please open the full interactive report:"
 
+              repo_full = os.environ.get("BITBUCKET_REPO_FULL_NAME", "").strip()
+              token = os.environ.get("BITBUCKET_ACCESS_TOKEN", "").strip()
+              png_path = os.environ.get("FG_CHECKS_PNG", "frontguard-checks.png").strip()
+
+              base = os.environ.get("FREEKIT_BASE_URL", "https://freekit.dev").rstrip("/")
               with open("frontguard-report.html", encoding="utf-8") as f:
                   html = f.read()
 
@@ -62,15 +85,64 @@ pipelines:
                   raise SystemExit(f"FreeKit error: {json.dumps(parsed)[:4000]}")
 
               data = parsed.get("data") or {}
-              url = (data.get("url") or "").strip()
-              if not url:
+              report_url = (data.get("url") or "").strip()
+              if not report_url:
                   raise SystemExit(f"FreeKit: missing data.url in {json.dumps(parsed)[:2000]}")
 
-              with open("frontguard-pr-comment.md", "w", encoding="utf-8") as out:
-                  out.write(url + "\n")
+              lines = []
+              img_url = None
 
+              if not os.path.isfile(png_path):
+                  raise SystemExit(f"Missing screenshot {png_path}")
+
+              if repo_full and token:
+                  try:
+                      proc = subprocess.run(
+                          [
+                              "curl",
+                              "--silent",
+                              "--show-error",
+                              "--fail",
+                              "-X",
+                              "POST",
+                              f"https://api.bitbucket.org/2.0/repositories/{repo_full}/downloads",
+                              "-H",
+                              f"Authorization: Bearer {token}",
+                              "-F",
+                              f"files=@{png_path}",
+                          ],
+                          capture_output=True,
+                          text=True,
+                          timeout=180,
+                      )
+                      if proc.returncode != 0:
+                          sys.stderr.write(
+                              f"Bitbucket Downloads upload failed (exit {proc.returncode}): {proc.stderr}\n"
+                          )
+                      else:
+                          up = json.loads(proc.stdout or "{}")
+                          name = (up.get("name") or os.path.basename(png_path)).strip()
+                          ws, slug = repo_full.split("/", 1)
+                          img_url = f"https://bitbucket.org/{ws}/{slug}/downloads/{quote(name, safe='')}"
+                  except Exception as e:
+                      sys.stderr.write(f"Bitbucket Downloads: {e}\n")
+
+              if img_url:
+                  lines.append(f"![FrontGuard — checks summary]({img_url})")
+                  lines.append("")
+              lines.append(DETAILED)
+              lines.append(report_url)
+              if not img_url:
+                  lines.append("")
+                  lines.append(
+                      "_Checks screenshot could not be uploaded. Grant `repository:write` and verify Downloads API, or host the PNG elsewhere and use FRONTGUARD_CHECKS_IMAGE_URL + `frontguard run --prCommentOut`._"
+                  )
+
+              body = "\n".join(lines) + "\n"
+              with open("frontguard-pr-comment.md", "w", encoding="utf-8") as out:
+                  out.write(body)
               with open("frontguard-payload.json", "w", encoding="utf-8") as out:
-                  json.dump({"content": {"raw": url}}, out, ensure_ascii=False)
+                  json.dump({"content": {"raw": body}}, out, ensure_ascii=False)
               PY
             - |
               test -n "${BITBUCKET_ACCESS_TOKEN:-}" || { echo "Missing secured var BITBUCKET_ACCESS_TOKEN"; exit 1; }

package/templates/freekit-ci-setup.md

@@ -1,10 +1,12 @@
 # FreeKit.dev + FrontGuard (Bitbucket Pipelines)
 
-The Bitbucket template uploads `frontguard-report.html` with **no signup or API key**, using FreeKit’s public API:
+The Bitbucket template (`templates/bitbucket-pipelines.yml`) uploads the **full** HTML report to FreeKit, **screenshots** the checks-only page, uploads that PNG to **Repository → Downloads**, and posts a PR comment with `![](bitbucket.org/.../downloads/...)` plus the FreeKit link. Your pipeline token needs **`repository:write`** (Downloads) and pull request comment permission.
+
+It also uploads `frontguard-report.html` with **no signup or API key** to FreeKit’s public API:
 
 - **Docs:** [FreeKit API](https://freekit.dev/docs)
 - **Endpoint:** `POST https://freekit.dev/api/v1/sites` with JSON `{"html": "<full report html>"}`
-- **Response:** `data.url` like `https://freekit.dev/s/<siteId>` — this URL is posted as the PR comment.
+- **Response:** `data.url` like `https://freekit.dev/s/<siteId>` — this URL is included in the PR comment below the checks screenshot caption.
 
 Optional env (advanced): **`FREEKIT_BASE_URL`** — override the API host (e.g. self‑hosted instance per FreeKit docs).