Skip to content

Commit ad0a727

Browse files
EdwardAngertclaude
EdwardAngert
and
claude
committed
refactor: improve documentation workflow consistency
- Replace manual Vale installation with errata-ai/vale-action GitHub Action - Correct the weekly preset description (issue creation not implemented) - Add clear warnings and TODOs for unimplemented issue creation - Update test script to reflect the new Vale action approach - Improve error handling for Vale integration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 44a38fd commit ad0a727

File tree

3 files changed

+92
-164
lines changed

3 files changed

+92
-164
lines changed

‎.github/docs/actions/docs-core/action.yaml

Lines changed: 45 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -217,7 +217,7 @@ runs:
217217
LINT_VALE="false" # Skip Vale style checking in weekly checks
218218
GEN_PREVIEW="false"
219219
POST_COMMENT="false"
220-
CREATE_ISSUES="true" # Create issues for persistent problems
220+
CREATE_ISSUES="false" # Issue creation not implemented yet (changed to false for accuracy)
221221
FAIL_ON_ERROR="true"
222222
echo "::notice::Applied weekly check preset configuration"
223223
;;
@@ -330,21 +330,18 @@ runs:
330330
# Check which tools we'll need based on enabled validations
331331
NEEDS_PNPM="false"
332332
NEEDS_NODE="false"
333-
NEEDS_VALE="false"
333+
# Note: Vale is now handled via GitHub Action, not manual installation
334334
335335
if [ "${{ env.lint_markdown }}" == "true" ] || [ "${{ env.check_format }}" == "true" ]; then
336336
NEEDS_PNPM="true"
337337
NEEDS_NODE="true"
338338
fi
339339
340-
if [ "${{ env.lint_vale }}" == "true" ]; then
341-
NEEDS_VALE="true"
342-
fi
343-
344340
# Output for workflow to use
345341
echo "needs_pnpm=$NEEDS_PNPM" >> $GITHUB_OUTPUT
346342
echo "needs_node=$NEEDS_NODE" >> $GITHUB_OUTPUT
347-
echo "needs_vale=$NEEDS_VALE" >> $GITHUB_OUTPUT
343+
# Vale is now handled by an action, no longer need this output
344+
echo "needs_vale=false" >> $GITHUB_OUTPUT
348345
349346
# === PHASE 1D: CONTEXT EXTRACTION ===
350347
# Centralized PR and branch information extraction
@@ -701,144 +698,65 @@ runs:
701698
echo "message=Link checking is enabled" >> $GITHUB_OUTPUT
702699
echo "::endgroup::"
703700
704-
# Vale style checking - rely on the Vale installed in the parent workflow
701+
# Use the official Vale GitHub Action for style checking
705702
- name: Run Vale style checks
706703
id: lint-vale
707704
if: env.lint_vale == 'true' && steps.file-detection.outputs.has_changes == 'true'
705+
uses: errata-ai/vale-action@reviewdog
706+
with:
707+
files: ${{ steps.file-detection.outputs.changed_files_csv }}
708+
fail_on_error: false
709+
reporter: github-check
710+
token: ${{ inputs.github-token }}
711+
vale_flags: "--config=.github/docs/vale/.vale.ini"
712+
713+
# Process Vale results for consistent output format
714+
- name: Process Vale results
715+
id: process-vale-results
716+
if: env.lint_vale == 'true' && steps.file-detection.outputs.has_changes == 'true'
708717
shell: bash
709718
run: |
710-
echo "::group::Vale style checking"
719+
echo "::group::Vale results processing"
711720
712721
# Get the files to check from the detection step
713722
CHANGED_FILES_JSON='${{ steps.file-detection.outputs.changed_files_json }}'
714723
715724
# Skip if no files to check
716725
if [ "$CHANGED_FILES_JSON" == "[]" ] || [ -z "$CHANGED_FILES_JSON" ]; then
717-
echo "No files to check with Vale"
726+
echo "No files were checked with Vale"
718727
echo "status=success" >> $GITHUB_OUTPUT
719728
echo "message=No files to check" >> $GITHUB_OUTPUT
720729
echo "::endgroup::"
721730
exit 0
722731
fi
723732
724-
# Extract markdown files to check
725-
FILES_TO_CHECK=$(echo "$CHANGED_FILES_JSON" | jq -r '.[] | select(endswith(".md"))' | tr '\n' ' ')
733+
# Extract markdown files that were checked
734+
FILES_COUNT=$(echo "$CHANGED_FILES_JSON" | jq -r '.[] | select(endswith(".md"))' | wc -l | tr -d ' ')
726735
727-
if [ -z "$FILES_TO_CHECK" ]; then
728-
echo "No markdown files to check"
736+
if [ $FILES_COUNT -eq 0 ]; then
737+
echo "No markdown files were checked"
729738
echo "status=success" >> $GITHUB_OUTPUT
730739
echo "message=No markdown files to check" >> $GITHUB_OUTPUT
731740
echo "::endgroup::"
732741
exit 0
733742
fi
734743
735-
echo "Found markdown files to check with Vale"
736-
FILE_COUNT=$(echo "$FILES_TO_CHECK" | wc -w | tr -d ' ')
737-
echo "Found $FILE_COUNT markdown files to check"
738-
739-
# Verify Vale is available (should be installed by the parent workflow)
740-
if ! command -v vale &> /dev/null; then
741-
echo "Vale command not found, it should be installed by the parent workflow"
742-
echo "status=skipped" >> $GITHUB_OUTPUT
743-
echo "message=Vale not installed" >> $GITHUB_OUTPUT
744-
echo "::endgroup::"
745-
exit 0
746-
fi
747-
748-
# Show Vale version
749-
echo "Using Vale version:"
750-
vale --version
751-
752-
echo "Running Vale checks on $FILE_COUNT files..."
753-
754-
# Create a temporary directory for results
755-
TEMP_DIR=$(mktemp -d)
756-
trap 'rm -rf "$TEMP_DIR"' EXIT
757-
758-
# Run Vale on files in chunks (to avoid command line length limits)
759-
# Create chunks of files (maximum 10 files per chunk)
760-
CHUNK_SIZE=10
761-
CHUNKS=()
762-
CHUNK=""
763-
COUNT=0
764-
765-
for FILE in $FILES_TO_CHECK; do
766-
if [ $COUNT -eq $CHUNK_SIZE ]; then
767-
CHUNKS+=("$CHUNK")
768-
CHUNK="$FILE"
769-
COUNT=1
770-
else
771-
CHUNK="$CHUNK $FILE"
772-
COUNT=$((COUNT + 1))
773-
fi
774-
done
775-
776-
# Add the last chunk if not empty
777-
if [ -n "$CHUNK" ]; then
778-
CHUNKS+=("$CHUNK")
779-
fi
780-
781-
# Process each chunk and combine results
782-
echo "[" > "$TEMP_DIR/combined_results.json"
783-
FIRST_CHUNK=true
744+
# Vale action doesn't provide a specific output we can use directly
745+
# So we'll record that it ran successfully and was integrated
784746
785-
for ((i=0; i<${#CHUNKS[@]}; i++)); do
786-
CHUNK_FILES="${CHUNKS[$i]}"
787-
CHUNK_OUTPUT="$TEMP_DIR/chunk_$i.json"
788-
789-
echo "Processing chunk $((i+1))/${#CHUNKS[@]} ($(echo "$CHUNK_FILES" | wc -w | tr -d ' ') files)"
790-
791-
# Run Vale on this chunk of files
792-
vale --no-exit --output=JSON --config=.github/docs/vale/.vale.ini $CHUNK_FILES > "$CHUNK_OUTPUT" 2>/dev/null || true
793-
794-
# Verify JSON output and append to combined results
795-
if [ -s "$CHUNK_OUTPUT" ] && jq empty "$CHUNK_OUTPUT" 2>/dev/null; then
796-
# Add separator between chunks if not first chunk
797-
if [ "$FIRST_CHUNK" = true ]; then
798-
FIRST_CHUNK=false
799-
elif [ -s "$CHUNK_OUTPUT" ]; then
800-
echo "," >> "$TEMP_DIR/combined_results.json"
801-
fi
802-
803-
# Add content without brackets
804-
jq -c '.[]' "$CHUNK_OUTPUT" >> "$TEMP_DIR/combined_results.json" || echo "Error processing chunk $i"
805-
else
806-
echo "No valid results from chunk $i"
807-
fi
808-
done
809-
810-
# Close the combined JSON array
811-
echo "]" >> "$TEMP_DIR/combined_results.json"
812-
813-
# Fix JSON if needed
814-
if ! jq empty "$TEMP_DIR/combined_results.json" 2>/dev/null; then
815-
echo "Warning: Invalid combined JSON output, creating empty array"
816-
echo "[]" > "$TEMP_DIR/combined_results.json"
817-
fi
818-
819-
# Extract and analyze results
820-
VALE_OUTPUT=$(cat "$TEMP_DIR/combined_results.json")
821-
822-
# Store results
823-
if [ "$VALE_OUTPUT" = "[]" ] || [ "$(echo "$VALE_OUTPUT" | jq 'length')" -eq 0 ]; then
824-
echo "Vale check passed: No style issues found"
747+
# Determine status based on Vale action
748+
if [ "${{ steps.lint-vale.outcome }}" == "success" ]; then
749+
echo "Vale check completed successfully"
825750
echo "status=success" >> $GITHUB_OUTPUT
826-
echo "message=No style issues found in $FILE_COUNT files" >> $GITHUB_OUTPUT
827-
else
828-
# Count issues
829-
ISSUE_COUNT=$(echo "$VALE_OUTPUT" | jq 'length')
830-
echo "Vale found $ISSUE_COUNT style issues in $FILE_COUNT files"
831-
832-
# Group issues by file for better readability
833-
echo "$VALE_OUTPUT" | jq -r 'group_by(.Path) | .[] | .[0].Path + ":" + (. | length | tostring) + " issues"'
834-
835-
# Show details of first 10 issues
836-
echo "First 10 issues (detail):"
837-
echo "$VALE_OUTPUT" | jq -r '.[] | "\(.Path):\(.Line):\(.Column) - \(.Message) (\(.Check))"' | head -10
838-
751+
echo "message=Style checking completed on $FILES_COUNT files" >> $GITHUB_OUTPUT
752+
elif [ "${{ steps.lint-vale.outcome }}" == "failure" ]; then
753+
echo "Vale found style issues"
839754
echo "status=warning" >> $GITHUB_OUTPUT
840-
echo "message=Found $ISSUE_COUNT style issues in $FILE_COUNT files" >> $GITHUB_OUTPUT
841-
echo "issues=$VALE_OUTPUT" >> $GITHUB_OUTPUT
755+
echo "message=Style issues found in documentation" >> $GITHUB_OUTPUT
756+
else
757+
echo "Vale check was skipped or had issues"
758+
echo "status=skipped" >> $GITHUB_OUTPUT
759+
echo "message=Vale check was skipped or had issues" >> $GITHUB_OUTPUT
842760
fi
843761
844762
echo "::endgroup::"
@@ -1049,7 +967,7 @@ runs:
1049967
{
1050968
"enabled": "${{ env.lint_vale }}",
1051969
"name": "Vale Style",
1052-
"step_id": "lint-vale",
970+
"step_id": "process-vale-results",
1053971
"guidance": "Follow style guidelines or use inline comments to suppress rules",
1054972
"fix_command": "vale --no-exit --config=.github/docs/vale/.vale.ini <filename>"
1055973
},
@@ -1399,9 +1317,14 @@ runs:
13991317
case "$CHANNEL" in
14001318
"github-issue")
14011319
if [ "${{ env.create_issues }}" == "true" ] && [ "${{ steps.format-results.outputs.has_issues }}" == "true" ]; then
1402-
echo "Would create GitHub issue here with appropriate API calls"
1403-
echo "Issue would include formatted information about failures"
1404-
echo "This is a placeholder for the actual implementation"
1320+
echo "::warning::GitHub issue creation functionality is not implemented yet - this is a placeholder"
1321+
echo "::notice::To implement issue creation, this would use the GitHub API to create issues for validation failures"
1322+
echo "::notice::See: https://docs.github.com/en/rest/issues/issues?apiVersion=2022-11-28#create-an-issue"
1323+
# TODO: Implementation would look like:
1324+
# curl -X POST -H "Authorization: token ${{ inputs.github-token }}" \
1325+
# -H "Accept: application/vnd.github+json" \
1326+
# https://api.github.com/repos/${{ github.repository }}/issues \
1327+
# -d '{"title":"Documentation validation issues","body":"...","labels":["documentation","bug"]}'
14051328
fi
14061329
;;
14071330
"slack")

‎.github/docs/testing/test-vale.sh

Lines changed: 44 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -59,29 +59,41 @@ raw:
5959
- \b(am|are|were|being|is|been|was|be)\b\s*(\w+ed|\w+ing|\w+en)
6060
EOF
6161

62-
echo "=== PHASE 1: Testing Vale installation ==="
63-
echo "-----------------------------------------"
64-
65-
# Install Vale using the same method as the workflow
66-
os=$(uname -s | tr '[:upper:]' '[:lower:]')
67-
arch=$(uname -m)
68-
if [ "$arch" = "x86_64" ]; then
69-
arch="64-bit"
70-
elif [[ "$arch" =~ ^(arm|aarch).* ]]; then
71-
arch="arm64"
72-
fi
62+
echo "=== PHASE 1: Testing GitHub Actions setup ==="
63+
echo "--------------------------------------------"
7364

74-
echo "Downloading Vale for $os-$arch to $HOME_BIN"
75-
curl -sfL "https://github.com/errata-ai/vale/releases/download/v2.30.0/vale_2.30.0_${os}_${arch}.tar.gz" | tar xz -C "$HOME_BIN" vale
76-
chmod +x "$HOME_BIN/vale"
65+
echo "With the updated workflow, Vale is now run using the errata-ai/vale-action GitHub Action"
66+
echo "This means we no longer need to install Vale manually in the workflow"
67+
echo "This test script now simulates what would happen in a GitHub Actions environment"
7768

78-
# Verify Vale installation
69+
# For local testing, we still need Vale installed
7970
if command -v vale &> /dev/null; then
80-
echo "✅ Vale installed successfully"
71+
echo "✅ Vale available locally for testing"
8172
vale --version
8273
else
83-
echo "❌ Vale installation failed"
84-
exit 1
74+
echo "⚠️ Vale not found locally - installing for testing purposes"
75+
76+
# Install Vale using the same method, but only for local testing
77+
os=$(uname -s | tr '[:upper:]' '[:lower:]')
78+
arch=$(uname -m)
79+
if [ "$arch" = "x86_64" ]; then
80+
arch="64-bit"
81+
elif [[ "$arch" =~ ^(arm|aarch).* ]]; then
82+
arch="arm64"
83+
fi
84+
85+
echo "Downloading Vale for $os-$arch to $HOME_BIN"
86+
curl -sfL "https://github.com/errata-ai/vale/releases/download/v2.30.0/vale_2.30.0_${os}_${arch}.tar.gz" | tar xz -C "$HOME_BIN" vale
87+
chmod +x "$HOME_BIN/vale"
88+
89+
# Verify Vale installation
90+
if command -v vale &> /dev/null; then
91+
echo "✅ Vale installed successfully for local testing"
92+
vale --version
93+
else
94+
echo "❌ Vale installation failed"
95+
exit 1
96+
fi
8597
fi
8698

8799
echo
@@ -213,4 +225,17 @@ fi
213225
echo
214226
echo "=== TEST SUMMARY ==="
215227
echo "All Vale tests completed successfully! 🎉"
216-
echo "The implementation should work in GitHub Actions workflows"
228+
echo "Vale is now integrated via errata-ai/vale-action in GitHub Actions workflows"
229+
echo
230+
echo "=== Vale GitHub Action Simulation ==="
231+
echo "In the actual workflow, Vale would be run like this:"
232+
echo "- Uses: errata-ai/vale-action@reviewdog"
233+
echo "- With:"
234+
echo " files: list of markdown files"
235+
echo " fail_on_error: false"
236+
echo " reporter: github-check"
237+
echo " token: \${{ github-token }}"
238+
echo " vale_flags: --config=.github/docs/vale/.vale.ini"
239+
echo
240+
echo "This approach is more reliable and follows GitHub Actions best practices"
241+
echo "by using dedicated actions for specialized tools like Vale."

‎.github/workflows/docs-unified.yaml

Lines changed: 3 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -153,29 +153,9 @@ jobs:
153153
./scripts/pnpm_install.sh --prefer-offline || ./scripts/pnpm_install.sh --no-frozen-lockfile
154154
echo "Node.js dependencies installed successfully"
155155
156-
# Install Vale if needed
157-
- name: Install Vale
158-
if: steps.docs-core-setup.outputs.needs_vale == 'true' && steps.docs-core-setup.outputs.has_changes == 'true'
159-
shell: bash
160-
run: |
161-
echo "Installing Vale for style checking..."
162-
mkdir -p $HOME/bin
163-
echo "$HOME/bin" >> $GITHUB_PATH
164-
165-
os=$(uname -s | tr '[:upper:]' '[:lower:]')
166-
arch=$(uname -m)
167-
if [ "$arch" = "x86_64" ]; then
168-
arch="64-bit"
169-
elif [[ "$arch" =~ ^(arm|aarch).* ]]; then
170-
arch="arm64"
171-
fi
172-
173-
# Download Vale binary
174-
curl -sfL https://github.com/errata-ai/vale/releases/download/v2.30.0/vale_2.30.0_${os}_${arch}.tar.gz | tar xz -C $HOME/bin vale
175-
chmod +x $HOME/bin/vale
176-
177-
echo "Vale installed successfully"
178-
vale --version
156+
# Note: Vale is now handled via the errata-ai/vale-action GitHub Action
157+
# when required and is used directly within the docs-core action
158+
# No separate Vale installation step is needed
179159

180160
# Vale style checking is now fully integrated into the docs-core action
181161
# No need to run Vale separately in this file

0 commit comments

Comments
 (0)