feat: parallel build orchestrator with filtered output and PR failure comments

Replace sequential build-ccutil.sh with a Node.js orchestrator that runs
all ~32 title builds in parallel, filters output to surface errors clearly,
classifies errors against an external YAML catalog with cause/fix suggestions,
and produces a JSON report consumed by the PR workflow.

- build-orchestrator.js: parallel builds, semaphore concurrency, error classification
- error-patterns.yml: 12 error patterns (xref, include, podman, htmltest)
- build-ccutil.sh: thin Bash wrapper for backward compatibility
- pr.yml: continue-on-error + if: always() for rich failure PR comments
- build-asciidoc.yml: add id to build step

Closes: RHDHBUGS-2903

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: themr0c

.github/workflows/build-asciidoc.yml

@@ -46,6 +46,7 @@ jobs:
         echo "GIT_BRANCH=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_ENV
 
     - name: Build guides and indexes
+      id: build
       run: |
         echo "Building branch ${{ env.GIT_BRANCH }}"
         build/scripts/build-ccutil.sh -b ${{ env.GIT_BRANCH }}

.github/workflows/pr.yml

@@ -109,19 +109,25 @@ jobs:
           echo "GIT_BRANCH=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_ENV
 
       - name: Build guides and indexes
+        id: build
+        continue-on-error: true
         run: |
           echo "Building PR ${{ github.event.pull_request.number }}"
           cp trusted-scripts/build/scripts/build-ccutil.sh pr-content/build/scripts/build-ccutil.sh
+          cp trusted-scripts/build/scripts/build-orchestrator.js pr-content/build/scripts/build-orchestrator.js
+          cp trusted-scripts/build/scripts/error-patterns.yml pr-content/build/scripts/error-patterns.yml
           cd pr-content
           build/scripts/build-ccutil.sh -b "pr-${{ github.event.number }}"
 
       - name: Pull from origin before pushing (if possible)
+        if: steps.build.outcome == 'success'
         run: |
           cd pr-content
           /usr/bin/git pull origin gh-pages || true
 
       # repo must be public for this to work
       - name: Deploy
+        if: steps.build.outcome == 'success'
         uses: peaceiris/actions-gh-pages@v4
         # if: github.ref == 'refs/heads/main'
         with:
@@ -131,14 +137,47 @@ jobs:
           publish_dir: ./pr-content/titles-generated
 
       - name: Post or update PR comment with doc preview link
+        if: always() && steps.build.outcome != 'skipped'
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.RHDH_BOT_TOKEN }}
           script: |
+            const fs = require('fs');
             const prNum = context.issue.number;
             const previewUrl = `https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-${prNum}/`;
             const now = new Date().toLocaleString('en-US', { timeZone: 'UTC' });
-            const body = `Updated preview: ${previewUrl} @ ${now}`;
+            const buildOutcome = '${{ steps.build.outcome }}';
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+
+            let body;
+            if (buildOutcome === 'success') {
+              body = `Updated preview: ${previewUrl} @ ${now}`;
+            } else {
+              let report;
+              try {
+                report = JSON.parse(fs.readFileSync('pr-content/build-report.json', 'utf8'));
+              } catch { report = null; }
+
+              if (report) {
+                const failed = report.results.filter(r => r.status === 'failed');
+                const details = failed.map(r => {
+                  const errs = r.errors.map(e =>
+                    `  **Error:** \`${e.line}\`\n  **Cause:** ${e.cause}\n  **Fix:** ${e.fix}`
+                  ).join('\n\n');
+                  return `### ${r.title}\n${errs}`;
+                }).join('\n\n');
+
+                body = `## :x: Build failed\n\n` +
+                  `${report.titles.passed}/${report.titles.total} titles built successfully | ` +
+                  `${report.titles.failed} failed | ${report.duration}s\n\n` +
+                  `${details}\n\n` +
+                  `[View full logs](${runUrl}) | ${now}`;
+              } else {
+                body = `## :x: Build failed\n\n` +
+                  `The documentation build failed before producing a report.\n` +
+                  `[View full logs](${runUrl}) | ${now}`;
+              }
+            }
 
             const { data: comments } = await github.rest.issues.listComments({
               owner: context.repo.owner,
@@ -147,7 +186,8 @@ jobs:
             });
 
             const existing = comments.find(c =>
-              c.body.includes('preview: https://redhat-developer.github.io/')
+              c.body.includes('preview: https://redhat-developer.github.io/') ||
+              c.body.includes('Build failed')
             );
 
             if (existing) {

.gitignore

@@ -12,3 +12,4 @@ linkchecker-out.html
 catalog-info.yaml
 .claude/settings.local.json
 .claude/settings.json.backup
+build-report.json

build/scripts/build-ccutil.sh

@@ -7,69 +7,9 @@
 #
 # SPDX-License-Identifier: EPL-2.0
 #
-# Utility script build html previews with referenced images
-# Requires: Podman - see https://podman.io
-# input: titles/
-# output: titles-generated/ and titles-generated/$BRANCH/
+# Wrapper for backward compatibility — delegates to Node.js build orchestrator.
+# Requires: Node.js, Podman
+# See build-orchestrator.js for the implementation.
 
-# grep regex for title folders to exclude from processing below
-EXCLUDED_TITLES="rhdh-plugins-reference"
-BRANCH="main"
-
-while [[ "$#" -gt 0 ]]; do
-  case $1 in
-    '-b') BRANCH="$2"; shift 1;;
-  esac
-  shift 1
-done
-
-rm -fr titles-generated/;
-mkdir -p titles-generated/"${BRANCH}";
-echo "<html><head><title>Red Hat Developer Hub Documentation Preview - ${BRANCH}</title></head><body><ul>" > titles-generated/"${BRANCH}"/index.html;
-# exclude the rhdh-plugins-reference as it's embedded in the admin guide
-# shellcheck disable=SC2044,SC2013
-set -e
-for t in $(find titles -name master.adoc | sort -uV | grep -E -v "${EXCLUDED_TITLES}"); do
-    d=${t%/*};
-    dest=${d/titles/titles-generated\/${BRANCH}};
-    rm -rf "$d/build" || true
-    CMD="podman run --interactive --rm --tty \
-          --volume $(pwd):/docs:Z \
-          --workdir /docs/$d \
-          quay.io/ivanhorvath/ccutil:amazing ccutil compile --format html-single --lang en-US --doctype article";
-    echo -e -n "\nBuilding $t into $dest ...\n  ";
-    echo "${CMD}" | sed -r -e "s/\  +/ \\\\\n    /g"
-    $CMD
-    rm -rfv "$dest" || true
-    mv -f "$d/build/tmp/en-US/html-single/" "$dest"
-    # shellcheck disable=SC2013
-    for im in $(grep images/ "$dest/index.html" | grep -E -v 'mask-image|background|fa-icons|jupumbra' | sed -r -e "s#.+(images/[^\"]+)\".+#\1#"); do
-        # echo "  Copy $im ...";
-        IMDIR="$dest/${im%/*}/"
-        mkdir -p "${IMDIR}"; rsync -q "$im" "${IMDIR}";
-    done
-    # shellcheck disable=SC2044
-    # for f in $(find "$dest/" -type f); do echo "    $f"; done
-    echo "<li><a href=${dest/titles-generated\/${BRANCH}/.}>${dest/titles-generated\/${BRANCH}\//}</a></li>" >> titles-generated/"${BRANCH}"/index.html;
-done
-echo "</ul></body></html>" >> titles-generated/"${BRANCH}"/index.html
-
-# shellcheck disable=SC2143
-if [[ $BRANCH == "pr-"* ]]; then
-  # fetch the existing https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/index.html to add prs and branches
-  curl -sSL https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pulls.html -o titles-generated/pulls.html
-  if [[ -z $(grep "./${BRANCH}/index.html" titles-generated/pulls.html) ]]; then
-      echo "Building root index for $BRANCH in titles-generated/pulls.html ...";
-      echo "<li><a href=./${BRANCH}/index.html>${BRANCH}</a></li>" >> titles-generated/pulls.html
-  fi
-else
-  # fetch the existing https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/index.html to add prs and branches
-  curl -sSL https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/index.html -o titles-generated/index.html
-  if [[ -z $(grep "./${BRANCH}/index.html" titles-generated/index.html) ]]; then
-      echo "Building root index for $BRANCH in titles-generated/index.html ...";
-      echo "<li><a href=./${BRANCH}/index.html>${BRANCH}</a></li>" >> titles-generated/index.html
-  fi
-fi
-
-# Test the links with htmltest
-podman run --rm --tty --volume "$(pwd)":/test:Z docker.io/wjdp/htmltest:latest -c .htmltest.yml
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec node "${SCRIPT_DIR}/build-orchestrator.js" "$@"