Add RTL/LTR Markdown linter for mixed-direction text consistency and PR annotation

Introduce a Python-based linter (scripts/rtl_ltr_linter.py) to automatically detect and annotate issues related to mixed Right-To-Left (RTL) and Left-To-Right (LTR) text in Markdown files. The linter analyzes list items, book entries, and metadata for potential bidirectional text rendering problems, such as missing Unicode directionality markers (RLM/LRM) and improper handling of LTR keywords or symbols in RTL contexts.

Key features:
- Scans all Markdown files in the repository, with full logs saved as workflow artifacts.
- Annotates only changed or added lines in pull requests, providing targeted feedback in the GitHub Actions Job Summary.
- Detects common RTL/LTR issues, including:
  - Missing directionality markers after LTR keywords (e.g., "HTML") or symbols (e.g., "C#") in RTL text.
  - BIDI (bidirectional) mismatches that may affect text display.
  - Incorrect ordering of author names and metadata in RTL contexts.
- Configurable via rtl_linter_config.yml for keywords, symbols, and severity levels.
- Includes a GitHub Actions workflow (rtl-ltr-linter.yml) for automated checks on PRs.

Author: gabriele-ciccotelli

.github/workflows/rtl-ltr-linter.yml

@@ -0,0 +1,78 @@
+name: RTL/LTR Markdown Linter
+
+on: [pull_request]
+
+permissions:
+  contents: read # Required to checkout the repository content
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+    # Checkout the repository code
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    # Fetch the full history of 'main' for accurate git diff in PRs
+    - name: Fetch all history for main
+      run: git fetch --no-tags --prune --depth=50 origin main
+
+    # Set up the required Python version for the linter
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11' # Use a recent Python version for compatibility
+
+    # Install only the Python dependencies needed for the linter script
+    - name: Install Python dependencies
+      run: |
+        pip install python-bidi PyYAML
+
+    # (Optional) List files for debugging purposes
+    - name: List files in scripts directory and current path
+      run: |
+        echo "Current working directory:"
+        pwd
+        echo "Listing contents of scripts directory (if it exists at root):"
+        ls -la scripts/ || echo "scripts/ directory not found at root or ls failed"
+
+    # Identify all changed Markdown files in the PR using tj-actions/changed-files
+    - name: Get changed Markdown files
+      id: changed_md_files
+      uses: tj-actions/changed-files@v44
+      with:
+        files: |
+          **/*.md
+
+    # Run the RTL/LTR Markdown linter:
+    # - Scans all Markdown files for issues and writes a full log
+    # - Prints GitHub Actions annotations only for issues on changed lines in changed files
+    # - Fails the job if any error or warning is found on changed lines
+    - name: Run RTL/LTR Markdown linter
+      id: run_linter
+      run: |
+        echo "Scanning all specified paths for full log..."
+        echo "Changed Markdown files for PR annotations: ${{ steps.changed_md_files.outputs.all_changed_files }}"
+        
+        CHANGED_FILES_ARGS=""
+        if [ "${{ steps.changed_md_files.outputs.all_changed_files_count }}" -gt 0 ]; then
+          # Pass changed files to the script for PR annotation generation
+          # The paths from tj-actions/changed-files are space-separated
+          CHANGED_FILES_ARGS="--changed-files ${{ steps.changed_md_files.outputs.all_changed_files }}"
+        fi
+        
+        # Execute the linter.
+        # Annotations for changed files will be printed to stdout by the script.
+        # The script will also write a full log to 'rtl-linter-output.log'.
+        # If the script exits with a non-zero code (issues found), this step will fail.
+        python3 scripts/rtl_ltr_linter.py books casts courses more ${CHANGED_FILES_ARGS} --log-file rtl-linter-output.log
+
+    # Upload the linter output log as a workflow artifact for further inspection
+    - name: Upload linter output artifact
+      uses: actions/upload-artifact@v4
+      if: always() # Upload artifact even if the linter step failed
+      with:
+        name: rtl-linter-output # Name of the artifact
+        path: rtl-linter-output.log # Path to the output file
+        retention-days: 7 # How long to keep the artifact