This directory contains utilities for testing the documentation validation workflows locally.

The `test-vale.sh` script is designed to validate that the Vale integration in the unified documentation workflow functions correctly. This script simulates the GitHub Actions environment and tests the full Vale style checking approach, including:

1. Installation of Vale using the same method as the workflow

2. Basic Vale execution and verification

3. JSON output format validation

4. Chunked processing of multiple files (as implemented in the workflow)

To run the Vale integration test:

cd .github/docs/testing

./test-vale.sh

- Validates that Vale can be properly installed and run

- Confirms that Vale produces valid JSON output

- Tests the chunked processing approach used in the workflow

- Verifies the JSON results combination logic

Run this test when:

1. Making changes to the Vale integration in the docs-core action

2. Upgrading the Vale version used in the workflow

3. Modifying the Vale configuration or style rules

4. Troubleshooting Vale-related issues in the GitHub Actions environment

The Vale integration in our workflow has two components:

1. Installation in the parent workflow (`docs-unified.yaml`)

2. Execution in the docs-core composite action

This approach ensures that Vale is properly installed and accessible to the composite action without requiring it to download and install Vale itself, which could be unreliable within the composite action context.

set -e

echo "Testing Vale integration in docs workflow"

echo "----------------------------------------"

cleanup() {

echo "Cleaning up..."

rm -rf "$TEMP_DIR"

}

TEMP_DIR=$(mktemp -d)

trap cleanup EXIT

export HOME_BIN="$TEMP_DIR/home/bin"

mkdir -p "$HOME_BIN"

export PATH="$HOME_BIN:$PATH"

DOCS_DIR="$TEMP_DIR/docs"

mkdir -p "$DOCS_DIR"

VALE_DIR="$TEMP_DIR/.github/docs/vale"

mkdir -p "$VALE_DIR/styles/Vale"

cat > "$DOCS_DIR/sample.md" << EOF

cat > "$VALE_DIR/.vale.ini" << EOF

cat > "$VALE_DIR/styles/Vale/Passive.yml" << EOF

echo "=== PHASE 1: Testing Vale installation ==="

echo "-----------------------------------------"

os=$(uname -s | tr '[:upper:]' '[:lower:]')

arch=$(uname -m)

if [ "$arch" = "x86_64" ]; then

arch="64-bit"

elif [[ "$arch" =~ ^(arm|aarch).* ]]; then

arch="arm64"

echo "Downloading Vale for $os-$arch to $HOME_BIN"

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

chmod +x "$HOME_BIN/vale"

if command -v vale &> /dev/null; then

echo "✅ Vale installed successfully"

vale --version

echo "❌ Vale installation failed"

exit 1

echo "=== PHASE 2: Testing Vale basic execution ==="

echo "--------------------------------------------"

echo "Running Vale check on sample file..."

vale --no-exit --output=line --config="$VALE_DIR/.vale.ini" "$DOCS_DIR/sample.md" || echo "✅ Vale found issues as expected"

echo "=== PHASE 3: Testing Vale JSON output format ==="

echo "----------------------------------------------"

echo "Testing Vale JSON output format..."

VALE_OUTPUT=$(vale --no-exit --output=JSON --config="$VALE_DIR/.vale.ini" "$DOCS_DIR/sample.md")

echo "$VALE_OUTPUT" > "$TEMP_DIR/vale-output.json"

if echo "$VALE_OUTPUT" | jq . > /dev/null 2>&1; then

echo "✅ Vale produces valid JSON output"

echo "Found $(echo "$VALE_OUTPUT" | jq 'length') issues"

echo "❌ Vale JSON output is not valid"

cat "$TEMP_DIR/vale-output.json"

exit 1

echo "=== PHASE 4: Testing the chunked processing approach ==="

echo "-----------------------------------------------------"

for i in {1..15}; do

cp "$DOCS_DIR/sample.md" "$DOCS_DIR/sample_$i.md"

echo "Created 16 test files for chunk processing"

process_files_in_chunks() {

local files="$1"

local chunk_size="$2"

local output_dir="$3"

echo "Processing $(echo "$files" | wc -w | tr -d ' ') files in chunks of $chunk_size"

# Create chunks of files

CHUNKS=()

CHUNK=""

COUNT=0

for FILE in $files; do

if [ $COUNT -eq $chunk_size ]; then

CHUNKS+=("$CHUNK")

CHUNK="$FILE"

COUNT=1

else

CHUNK="$CHUNK $FILE"

COUNT=$((COUNT + 1))

fi

done

# Add the last chunk if not empty

if [ -n "$CHUNK" ]; then

CHUNKS+=("$CHUNK")

fi

echo "Created ${#CHUNKS[@]} chunks"

# Process each chunk

echo "[" > "$output_dir/combined_results.json"

FIRST_CHUNK=true

for ((i=0; i<${#CHUNKS[@]}; i++)); do

CHUNK_FILES="${CHUNKS[$i]}"

CHUNK_OUTPUT="$output_dir/chunk_$i.json"

echo "Processing chunk $((i+1))/${#CHUNKS[@]} ($(echo "$CHUNK_FILES" | wc -w | tr -d ' ') files)"

# Run Vale on this chunk of files

vale --no-exit --output=JSON --config="$VALE_DIR/.vale.ini" $CHUNK_FILES > "$CHUNK_OUTPUT" 2>/dev/null || true

# Verify JSON output and append to combined results

if [ -s "$CHUNK_OUTPUT" ] && jq empty "$CHUNK_OUTPUT" 2>/dev/null; then

# Add separator between chunks if not first chunk

if [ "$FIRST_CHUNK" = true ]; then

FIRST_CHUNK=false

elif [ -s "$CHUNK_OUTPUT" ]; then

echo "," >> "$output_dir/combined_results.json"

fi

# Add content without brackets

jq -c '.[]' "$CHUNK_OUTPUT" >> "$output_dir/combined_results.json" || echo "Error processing chunk $i"

else

echo "No valid results from chunk $i"

fi

done

# Close the combined JSON array

echo "]" >> "$output_dir/combined_results.json"

# Fix JSON if needed

if ! jq empty "$output_dir/combined_results.json" 2>/dev/null; then

echo "Warning: Invalid combined JSON output, creating empty array"

echo "[]" > "$output_dir/combined_results.json"

fi

return 0

}

MD_FILES=$(find "$DOCS_DIR" -name "*.md" | tr '\n' ' ')

process_files_in_chunks "$MD_FILES" 5 "$TEMP_DIR"

COMBINED_OUTPUT="$TEMP_DIR/combined_results.json"

if [ -f "$COMBINED_OUTPUT" ] && jq empty "$COMBINED_OUTPUT" 2>/dev/null; then

ISSUES=$(jq 'length' "$COMBINED_OUTPUT")

echo "✅ Chunked processing successful - found $ISSUES issues total"

echo "❌ Chunked processing failed"

exit 1

echo "=== TEST SUMMARY ==="

echo "All Vale tests completed successfully! 🎉"

echo "The implementation should work in GitHub Actions workflows"