@cleartrip/frontguard 0.2.5 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleartrip/frontguard",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Org-wide frontend PR guardrails: linting, hygiene, any-delta, cycles, dead code, bundle/CWV hints, custom rules, optional LLM brief",
   "type": "module",
   "bin": {
@@ -26,6 +26,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "test": "npm run build && tsx --test src/lib/bitbucket-checks-image-md.test.ts src/runner/checks-snapshot-png.integration.test.ts",
     "format": "prettier --write .",
     "prepack": "npm run build"
   },
@@ -38,6 +39,7 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@resvg/resvg-js": "^2.6.2",
     "fast-glob": "^3.3.3",
     "typescript": "^5.8.2"
   },
@@ -48,6 +50,7 @@
     "picocolors": "^1.1.1",
     "prettier": "^3.5.3",
     "tinyexec": "^1.0.1",
-    "tsup": "^8.4.0"
+    "tsup": "^8.4.0",
+    "tsx": "^4.21.0"
   }
 }

package/templates/bitbucket-pipelines.yml

@@ -1,67 +1,54 @@
-# FrontGuard + Bitbucket PR comment: Checks table screenshot + FreeKit full HTML link
+# FrontGuard — PR comment: checks screenshot (inline) + FreeKit full report
 #
-# 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.
+# • The checks-table PNG is generated with @resvg/resvg-js (SVG → raster; no Playwright/Chromium).
+# • The PNG is embedded in the PR comment as a small base64 image (no Bitbucket Downloads / extra tokens).
+# • Full HTML report is uploaded to FreeKit; the comment links to that URL for details.
 #
-# Repo variable (secured): BITBUCKET_ACCESS_TOKEN — pullrequest:write + repository:write (for Downloads).
+# Secured variable: BITBUCKET_ACCESS_TOKEN — must be allowed to post pull request comments.
 #
-# FreeKit: POST https://freekit.dev/api/v1/sites — see templates/freekit-ci-setup.md
-# Optional: FREEKIT_BASE_URL — override API host.
+# Optional: FREEKIT_BASE_URL — override FreeKit API host (default https://freekit.dev).
 #
-# If Chromium fails on your runner image, switch the screenshot step to Playwright (see comments below).
+# Deeper clone avoids shallow-git errors (e.g. merge-base / parent rev) for diff-based checks.
 
 image: node:20
 
+clone:
+  depth: 50
+
 pipelines:
   pull-requests:
     '**':
       - step:
-          name: FrontGuard – checks image + FreeKit + PR comment
+          name: FrontGuard — report + PR comment
           caches:
             - node
           artifacts:
             - frontguard-report.html
             - frontguard-report.md
             - frontguard-checks.html
-            - frontguard-checks*.png
+            - frontguard-checks.png
           script:
-            - apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends chromium
             - corepack enable
+            - apt-get update && apt-get install -y --no-install-recommends fonts-dejavu-core
             - 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 \
+                --checksPngOut frontguard-checks.png \
                 > 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 base64
               import json
               import os
-              import subprocess
-              import sys
               from urllib.error import HTTPError
-              from urllib.parse import quote
               from urllib.request import Request, urlopen
 
               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()
+              # Keep in sync with src/lib/bitbucket-checks-image-md.ts (markdown line length cap).
+              MAX_IMAGE_LINE = 300_000
+              PNG_SIG = bytes([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A])
 
               base = os.environ.get("FREEKIT_BASE_URL", "https://freekit.dev").rstrip("/")
               with open("frontguard-report.html", encoding="utf-8") as f:
@@ -89,56 +76,20 @@ pipelines:
               if not report_url:
                   raise SystemExit(f"FreeKit: missing data.url in {json.dumps(parsed)[:2000]}")
 
-              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`._"
+              with open("frontguard-checks.png", "rb") as f:
+                  raw = f.read()
+              if len(raw) < 8 or raw[:8] != PNG_SIG:
+                  raise SystemExit("frontguard-checks.png is missing or not a valid PNG file.")
+              b64 = base64.standard_b64encode(raw).decode("ascii")
+              # ASCII alt text; standard Base64 — matches FrontGuard pngBufferToBitbucketImageMarkdownLine.
+              img_line = f"![FrontGuard checks summary](data:image/png;base64,{b64})"
+              if len(img_line) > MAX_IMAGE_LINE:
+                  raise SystemExit(
+                      f"Checks PNG too large for inline comment ({len(raw)} bytes, line {len(img_line)} chars). "
+                      "Shrink the table or host the PNG and link it; see bitbucket-checks-image-md.ts limits."
                   )
 
-              body = "\n".join(lines) + "\n"
+              body = f"{img_line}\n\n{DETAILED}\n{report_url}\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:

package/templates/checks-snapshot-bitbucket-snippet.yml

@@ -1,30 +1 @@
-# 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"
+# Deprecated: use `templates/bitbucket-pipelines.yml` — it now uses `--checksPngOut` + inline PNG.

package/templates/freekit-ci-setup.md

@@ -1,8 +1,8 @@
 # FreeKit.dev + FrontGuard (Bitbucket Pipelines)
 
-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.
+The Bitbucket template (`templates/bitbucket-pipelines.yml`) runs FrontGuard with **`--checksPngOut`** (SVG → PNG via **`@resvg/resvg-js`**, no headless browser), uploads the full HTML to **FreeKit**, and posts a PR comment that **inlines** the checks PNG as `data:image/png;base64,...` plus the FreeKit URL. You only need **`BITBUCKET_ACCESS_TOKEN`** with permission to **comment on pull requests** — no Repository Downloads or `repository:write`.
 
-It also uploads `frontguard-report.html` with **no signup or API key** to FreeKit’s public API:
+The same step uploads `frontguard-report.html` 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>"}`
@@ -26,24 +26,7 @@ On **Bitbucket Pipelines** pull-request builds, FrontGuard reads **`BITBUCKET_PR
 
 ## 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.
+The default pipeline uses **`--checksPngOut`** so FrontGuard writes **`frontguard-checks.png`** (raster from the checks table). A short Python step base64-embeds that image in the PR comment (no extra hosting). If the PNG is too large for Bitbucket, raise the limit in the pipeline script cautiously or host the image and set **`FRONTGUARD_CHECKS_IMAGE_URL`** with **`--prCommentOut`** instead.
 
 ## Compared to Surge