@cleartrip/frontguard 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleartrip/frontguard",
-  "version": "0.2.3",
+  "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/checks-snapshot-bitbucket-snippet.yml

@@ -0,0 +1,30 @@
+# Optional fragment: PNG of the Checks table in the PR comment (Bitbucket Cloud)
+#
+# Merge into pull-requests after `frontguard run` produces:
+#   - frontguard-checks.html   (--checksSnapshotOut)
+#   - frontguard-report.html   (--htmlOut)
+#
+# Flow:
+# 1. Screenshot the minimal HTML with Playwright (Chromium).
+# 2. Upload the PNG somewhere HTTPS-public (examples below).
+# 3. export FRONTGUARD_CHECKS_IMAGE_URL='https://.../frontguard-checks.png'
+# 4. Run frontguard again with --prCommentOut (or only export + re-run snippet step) so the comment includes ![...](url).
+#
+# The PR body is Markdown: Bitbucket renders ![](https://...) images when the URL is reachable.
+
+# --- Example: screenshot + upload to Bitbucket Downloads (public file URL for repo viewers) ---
+#   - npx playwright@1.49.0 install chromium
+#   - |
+#     FILE_URL="$(node --input-type=module -e "import { pathToFileURL } from 'node:url'; console.log(pathToFileURL('frontguard-checks.html').href)")"
+#     npx playwright@1.49.0 screenshot "$FILE_URL" frontguard-checks.png --viewport-size=920,2000
+#   - |
+#     curl --silent --show-error --fail --request POST \
+#       --url "https://api.bitbucket.org/2.0/repositories/${BITBUCKET_REPO_FULL_NAME}/downloads" \
+#       --header "Authorization: Bearer ${BITBUCKET_ACCESS_TOKEN}" \
+#       --form "files=@frontguard-checks.png"
+#   # Then set FRONTGUARD_CHECKS_IMAGE_URL to the href Bitbucket returns for that file (see API response),
+#   # or construct the known downloads URL pattern for your workspace.
+#
+# --- Example: same image hosted on your CDN / object storage ---
+#   - aws s3 cp frontguard-checks.png s3://my-bucket/ci/frontguard-checks-${BITBUCKET_BUILD_NUMBER}.png --acl public-read
+#   - export FRONTGUARD_CHECKS_IMAGE_URL="https://my-bucket.s3.amazonaws.com/ci/frontguard-checks-${BITBUCKET_BUILD_NUMBER}.png"

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).
 
@@ -22,6 +24,27 @@ On **Bitbucket Pipelines** pull-request builds, FrontGuard reads **`BITBUCKET_PR
 - **Limits:** Per FreeKit docs — e.g. HTML payload size caps, **rate limits** (creates per minute per IP), possible `429`. Large reports or busy runners may need retries or another host.
 - **No delete token in CI:** Each run creates a **new** site URL. Old FreeKit URLs may still work until you delete them with the `deleteToken` returned in the API response (this template does not store it).
 
+## Checks table image in PR comments
+
+Bitbucket renders **`![](https://.../checks.png)`** in PR comments when the URL is public HTTPS. FrontGuard can emit a **minimal HTML** file that contains only the Checks table (same styling as the full report):
+
+```bash
+yarn frontguard run --markdown \
+  --htmlOut frontguard-report.html \
+  --checksSnapshotOut frontguard-checks.html \
+  > frontguard-report.md
+```
+
+Then:
+
+1. **Screenshot** `frontguard-checks.html` with headless Chromium (e.g. `npx playwright screenshot "<file://...>" frontguard-checks.png`).
+2. **Upload** the PNG to a reachable URL (Bitbucket Downloads API, S3, CDN, etc.).
+3. Set **`FRONTGUARD_CHECKS_IMAGE_URL`** to that URL **before** writing the PR comment (e.g. before `formatBitbucketPrSnippet` / `--prCommentOut`).
+
+The snippet places the image at the **top** of the comment and keeps the **full interactive report** link below (with a short line explaining that details are in the HTML).
+
+See **`templates/checks-snapshot-bitbucket-snippet.yml`** for merge-ready pipeline examples.
+
 ## Compared to Surge
 
 Surge credentials (`SURGE_LOGIN` / `SURGE_TOKEN`) are **not** required for FreeKit’s open POST flow. If you remove Surge, you can delete any old Surge-related secured variables from the repository.