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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy