From de6e4391c618d4598795d1dbbeb31c8218ab7fa6 Mon Sep 17 00:00:00 2001
From: Floze <88098863+floze-the-genius@users.noreply.github.com>
Date: Fri, 14 Aug 2026 15:27:45 +0400
Subject: [PATCH] fix: validate rendered README media

---
 scripts/audit.sh | 66 +++++++++++++++++++++++++++++++++++++++++++++---
 tests/run.sh     | 60 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 123 insertions(+), 3 deletions(-)

diff --git a/scripts/audit.sh b/scripts/audit.sh
index 10f5079..b50a385 100644
--- a/scripts/audit.sh
+++ b/scripts/audit.sh
@@ -67,6 +67,65 @@ check_any() {
   fi
 }
 
+# Print only README content that can render: HTML comments and fenced examples
+# must not satisfy audit checks merely by mentioning image or badge syntax.
+rendered_readme() {
+  if [ ! -f "$REPO/README.md" ]; then
+    return 0
+  fi
+
+  awk '
+    BEGIN { in_comment = 0; fence = "" }
+    {
+      line = $0
+
+      while (1) {
+        if (in_comment) {
+          comment_end = index(line, "-->")
+          if (comment_end == 0) {
+            line = ""
+            break
+          }
+          line = substr(line, comment_end + 3)
+          in_comment = 0
+        }
+
+        comment_start = index(line, "<!--")
+        if (comment_start == 0) break
+
+        before_comment = substr(line, 1, comment_start - 1)
+        after_comment = substr(line, comment_start + 4)
+        comment_end = index(after_comment, "-->")
+        if (comment_end == 0) {
+          line = before_comment
+          in_comment = 1
+          break
+        }
+        line = before_comment substr(after_comment, comment_end + 3)
+      }
+
+      if (fence == "backtick") {
+        if (line ~ /^[[:space:]]*```/) fence = ""
+        next
+      }
+      if (fence == "tilde") {
+        if (line ~ /^[[:space:]]*~~~/) fence = ""
+        next
+      }
+      if (line ~ /^[[:space:]]*```/) {
+        fence = "backtick"
+        next
+      }
+      if (line ~ /^[[:space:]]*~~~/) {
+        fence = "tilde"
+        next
+      }
+
+      print line
+    }
+  ' "$REPO/README.md" 2>/dev/null
+}
+
 echo ""
 bold "OSS Audit: $REPO"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -107,8 +166,9 @@ check_any "CI workflow (test/build/lint)" "Copy a starter from $TPL/.github/work
 
 echo ""
 bold "── README Quality ──"
+README_RENDERED="$(rendered_readme)"
 TOTAL=$((TOTAL + 1))
-if grep -qi "demo\|screenshot\|gif" "$REPO/README.md" 2>/dev/null; then
+if grep -Eqi '!\[[^]]*\]\([^)]+\.(gif|png|jpe?g|webp|svg)([?#][^)]*)?\)|<img[[:space:]][^>]*src[[:space:]]*=' <<<"$README_RENDERED"; then
   green "  $PASS  README references a demo/screenshot"
   SCORE=$((SCORE + 1))
 else
@@ -126,11 +186,11 @@ else
 fi
 
 TOTAL=$((TOTAL + 1))
-if grep -q "img.shields.io\|badge\|actions/workflows" "$REPO/README.md" 2>/dev/null; then
+if grep -Eqi '\[!\[[^]]*\]\([^)]+\)\]\([^)]+\)|!\[[^]]*\]\([^)]*(img\.shields\.io|badge|actions/workflows|contrib\.rocks)[^)]*\)' <<<"$README_RENDERED"; then
   green "  $PASS  README has badges"
   SCORE=$((SCORE + 1))
 else
-  yellow "  $WARN  README missing build/license badges"
+  red "  $FAIL  README missing build/license badges"
   yellow "       Fix: add a badges row at the top (see references/github-metadata.md)"
 fi
 
diff --git a/tests/run.sh b/tests/run.sh
index e7578bf..fc610d7 100644
--- a/tests/run.sh
+++ b/tests/run.sh
@@ -16,6 +16,8 @@ TMP="$(mktemp -d)"
 trap 'rm -rf "$TMP"' EXIT
 
 FAILURES=0
+PASS_SYMBOL="✓"
+FAIL_SYMBOL="✗"
 
 score_of() {  # score_of <dir> -> numeric score out of 16
   bash "$ROOT/scripts/audit.sh" "$1" 2>&1 | sed -n 's/.*Score: \([0-9]\+\)\/16.*/\1/p'
@@ -32,6 +34,17 @@ assert_score() {  # assert_score <label> <dir> <expected>
   fi
 }
 
+assert_audit_line() {  # assert_audit_line <label> <dir> <expected text>
+  local label="$1" dir="$2" expected="$3" output
+  output="$(bash "$ROOT/scripts/audit.sh" "$dir" 2>&1)"
+  if grep -Fq "$expected" <<<"$output"; then
+    echo "  PASS  $label"
+  else
+    echo "  FAIL  $label: missing '$expected'"
+    FAILURES=$((FAILURES + 1))
+  fi
+}
+
 echo "── audit.sh scoring ──"
 
 # --- empty: bare fixture, README only ---
@@ -43,6 +56,53 @@ bash "$ROOT/demo/scaffold.sh" init "$TMP/partial" >/dev/null
 cp "$ROOT/templates/LICENSE-apache.txt" "$TMP/partial/LICENSE"
 assert_score "partial fixture" "$TMP/partial" 2
 
+# --- README media: comments and fenced examples are not rendered content ---
+bash "$ROOT/demo/scaffold.sh" init "$TMP/non-rendered-media" >/dev/null
+cat > "$TMP/non-rendered-media/README.md" <<'EOF'
+# Project
+
+<!-- A demo GIF is still TODO.
+![Demo](docs/media/demo.gif)
+-->
+
+```markdown
+![Screenshot](docs/media/screenshot.png)
+[![CI](https://img.shields.io/badge/build-passing.svg)](https://example.com)
+```
+EOF
+assert_audit_line "HTML comments/fences do not count as media" "$TMP/non-rendered-media" \
+  "$FAIL_SYMBOL  README missing demo GIF or screenshot"
+assert_audit_line "scored badge failure uses the failure marker" "$TMP/non-rendered-media" \
+  "$FAIL_SYMBOL  README missing build/license badges"
+
+# --- README media: rendered image and provider-agnostic linked badge shapes ---
+bash "$ROOT/demo/scaffold.sh" init "$TMP/rendered-image" >/dev/null
+cat > "$TMP/rendered-image/README.md" <<'EOF'
+# Project
+
+![Walkthrough](docs/media/walkthrough.gif)
+EOF
+assert_audit_line "rendered Markdown image counts" "$TMP/rendered-image" \
+  "$PASS_SYMBOL  README references a demo/screenshot"
+
+bash "$ROOT/demo/scaffold.sh" init "$TMP/rendered-html-image" >/dev/null
+cat > "$TMP/rendered-html-image/README.md" <<'EOF'
+# Project
+
+<img src="docs/media/walkthrough.webp" alt="Product walkthrough">
+EOF
+assert_audit_line "rendered HTML image counts" "$TMP/rendered-html-image" \
+  "$PASS_SYMBOL  README references a demo/screenshot"
+
+bash "$ROOT/demo/scaffold.sh" init "$TMP/linked-badge" >/dev/null
+cat > "$TMP/linked-badge/README.md" <<'EOF'
+# Project
+
+[![Contributors](https://contrib.rocks/image?repo=example/project)](https://github.com/example/project/graphs/contributors)
+EOF
+assert_audit_line "provider-agnostic linked image counts as badge" "$TMP/linked-badge" \
+  "$PASS_SYMBOL  README has badges"
+
 # --- full: complete scaffold ---
 bash "$ROOT/demo/scaffold.sh" init "$TMP/full" >/dev/null
 bash "$ROOT/demo/scaffold.sh" apply "$TMP/full" >/dev/null