CI: docgen demo-function smoke (issue #9); ensure Mike Farah yq in regression

.github/workflows/docgen-demo-function.yml

@@ -0,0 +1,46 @@
+# Smoke-test upstream `docgen demo-function` (issue #9): install from git pin, no docgen-shim / python -m demo_function.
+name: docgen demo-function
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    env:
+      # Pinned to jmjava/documentation-generator@main — bump when adopting new docgen features (see courseforge/infrastructure docs/tekton-dag-reuse.md).
+      DOCGEN_GIT_REF: b880ba7a96c35fa32672f217e68c3e3592fb2be1
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install docgen from upstream
+        run: |
+          python -m pip install --upgrade pip
+          pip install "docgen @ git+https://github.com/jmjava/documentation-generator.git@${DOCGEN_GIT_REF}"
+
+      - name: docgen demo-function (neutral skip => success)
+        run: |
+          set +e
+          docgen demo-function \
+            --manifest ci/docgen-demo-function-smoke.docgen.yaml \
+            --output "${RUNNER_TEMP}/docgen-demo-out" \
+            --no-narration
+          code=$?
+          set -e
+          if [ "${code}" -eq 78 ]; then
+            echo "docgen demo-function exited 78 (neutral skip) — treating as success per Tekton/GitHub Actions convention."
+            exit 0
+          fi
+          exit "${code}"

.gitignore

@@ -1,3 +1,6 @@
+# Auto-downloaded Mike Farah yq (see scripts/common.sh ensure_mikefarah_yq)
+.tools/
+
 # Local overrides / env (never commit secrets)
 .env
 .env.*.local

ci/docgen-demo-function-smoke.docgen.yaml

@@ -0,0 +1,10 @@
+# Placeholder manifest for CI: `docgen demo-function` exits 78 (neutral skip)
+# when kind=playwright has no URL/spec — see documentation-generator demo_function.
+identifier: ci/tekton-dag:docgen-demo-function-smoke
+intent: Verify the upstream docgen demo-function CLI is wired; neutral skip is success.
+demonstration:
+  kind: playwright
+  actions: []
+output_budget:
+  duration_seconds: 10
+  resolution: 1280x720

scripts/common.sh

@@ -105,3 +105,48 @@ load_env() {
     set +a
   fi
 }
+
+# ── YAML processor (Mike Farah yq) ────────────────────────────────────
+# Some images ship the unrelated PyPI `yq` package on PATH (wrapper around jq).
+# Stack scripts require https://github.com/mikefarah/yq (`yq -o=json`, etc.).
+_mikefarah_yq_ok() {
+  local ver
+  command -v yq >/dev/null 2>&1 || return 1
+  ver=$(yq --version 2>&1 || true)
+  [[ "$ver" == *"mikefarah"* ]] || [[ "$ver" == *"github.com/mikefarah/yq"* ]]
+}
+
+# Install a static Mike Farah yq binary under REPO_ROOT/.tools and prepend to PATH.
+# Override version with MIKEFARAH_YQ_VERSION (default v4.45.4).
+ensure_mikefarah_yq() {
+  if _mikefarah_yq_ok; then
+    return 0
+  fi
+  local install_dir="${REPO_ROOT}/.tools"
+  local bin="${install_dir}/yq"
+  local want="${MIKEFARAH_YQ_VERSION:-v4.45.4}"
+  mkdir -p "$install_dir"
+  if [[ -x "$bin" ]]; then
+    local cached
+    cached=$("$bin" --version 2>&1 || true)
+    if [[ "$cached" == *"mikefarah"* ]] || [[ "$cached" == *"github.com/mikefarah/yq"* ]]; then
+      export PATH="${install_dir}:$PATH"
+      return 0
+    fi
+  fi
+  need curl
+  local arch
+  arch=$(uname -m)
+  case "$arch" in
+    x86_64) arch=amd64 ;;
+    aarch64 | arm64) arch=arm64 ;;
+    *) die "ensure_mikefarah_yq: unsupported uname -m: $arch (install yq manually)" ;;
+  esac
+  local url="https://github.com/mikefarah/yq/releases/download/${want}/yq_linux_${arch}"
+  info "Installing Mike Farah yq ${want} -> ${bin} (first on PATH for this process)"
+  curl -fsSL -o "$bin.tmp" "$url"
+  mv -f "$bin.tmp" "$bin"
+  chmod +x "$bin"
+  export PATH="${install_dir}:$PATH"
+  _mikefarah_yq_ok || die "ensure_mikefarah_yq: installed binary failed self-check"
+}

scripts/run-regression.sh

@@ -115,6 +115,7 @@ fi
 
 echo ""
 echo ">>> Phase 1: DAG verification (no cluster) — scripts/verify-dag-phase1.sh"
+ensure_mikefarah_yq
 need yq
 bash "$SCRIPT_DIR/verify-dag-phase1.sh"