Harper

.github/workflows/docs-quality.yml

@@ -0,0 +1,129 @@
+name: Docs Quality
+on:
+  pull_request:
+  workflow_dispatch:
+jobs:
+  typos:
+    name: Spelling (typos-cli)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - uses: crate-ci/typos@master
+
+  harper:
+    name: Grammar and Style Check
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Cache Harper CLI
+        id: cache-harper
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/harper-cli
+            ~/.cargo/registry
+            ~/.cargo/git
+          key: ${{ runner.os }}-harper-cli
+          restore-keys: |
+            ${{ runner.os }}-harper-cli
+      - name: Report cache status
+        run: |
+          echo "cache-hit output: '${{ steps.cache-harper.outputs.cache-hit }}'"
+          ls -la ~/.cargo/bin/ 2>&1 || echo "~/.cargo/bin does not exist"
+          if [ -x ~/.cargo/bin/harper-cli ]; then
+            echo "RESULT: harper-cli binary present and executable"
+            ~/.cargo/bin/harper-cli --version || true
+          else
+            echo "RESULT: harper-cli binary NOT present -- full reinstall will run"
+          fi
+      - name: Install Harper CLI
+        if: steps.cache-harper.outputs.cache-hit != 'true'
+        run: cargo install --locked --git https://github.com/Automattic/harper.git harper-cli
+      - name: Lint docs with Harper
+        run: |
+          set -uo pipefail
+          ONLY_RULES=(
+            UseTitleCase
+            RepeatedWords
+            MergeWords
+            ItsContraction
+          )
+          ONLY_ARG="--only $(IFS=,; echo "${ONLY_RULES[*]}")"
+          mdxtmp="$(mktemp -d)"
+          out="$(mktemp)"
+          total=0
+          bad=0
+          while IFS= read -r -d '' file; do
+            total=$((total+1))
+            case "$file" in
+              *.mdx)
+                target="$mdxtmp/${file}.md"
+                mkdir -p "$(dirname "$target")"
+                cp "$file" "$target"
+                ;;
+              *)
+                target="$file"
+                ;;
+            esac
+            echo "::group::$file"
+            if harper-cli lint $ONLY_ARG "$target" 2>&1 | tee -a "$out"; then
+              :
+            else
+              bad=$((bad+1))
+            fi
+            echo "::endgroup::"
+          done < <(
+            find docs src/pages \
+              -type f \( -name "*.md" -o -name "*.mdx" \) \
+              -print0 2>/dev/null
+          )
+          titlecase=$(grep -c 'Capitalization::UseTitleCase' "$out" || true)
+          {
+            echo "### Harper summary"
+            echo "- Files scanned: $total"
+            echo "- Files with issues: $bad"
+            echo "- Heading title case violations: $titlecase"
+            echo ""
+            echo "### Violations by rule"
+            echo '```'
+            grep -oE '\[[A-Za-z]+::[A-Za-z]+\]' "$out" | sort | uniq -c | sort -rn || true
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+          echo "== Harper: $bad/$total files with issues; $titlecase UseTitleCase violations =="
+          [ "$bad" -eq 0 ]
+      - name: Annotate PR with Harper warnings
+        if: always()
+        run: |
+          set -uo pipefail
+          ONLY_RULES=(
+            UseTitleCase
+            RepeatedWords
+            MergeWords
+            ItsContraction
+          )
+          ONLY_ARG="--only $(IFS=,; echo "${ONLY_RULES[*]}")"
+          mdxtmp="$(mktemp -d)"
+          while IFS= read -r -d '' file; do
+            case "$file" in
+              *.mdx)
+                target="$mdxtmp/${file}.md"
+                mkdir -p "$(dirname "$target")"
+                cp "$file" "$target"
+                ;;
+              *)
+                target="$file"
+                ;;
+            esac
+            if json_out="$(harper-cli lint $ONLY_ARG --format json "$target" 2>/dev/null)"; then
+              :
+            else
+              printf '%s' "$json_out" | FILE="$file" python3 -c "import json,sys,os;d=json.load(sys.stdin);fp=os.environ['FILE'];esc=lambda s: s.replace('%','%25').replace('\r','%0D').replace('\n','%0A');[print('::warning file='+esc(fp)+',line='+str(l.get('line',1))+',col='+str(l.get('column',1))+',title='+esc(l.get('rule','?'))+'::'+esc(l.get('message',''))) for f in d for l in f.get('lints',[])]" || true
+            fi
+          done < <(
+            find docs src/pages \
+              -type f \( -name "*.md" -o -name "*.mdx" \) \
+              -print0 2>/dev/null
+          )

_typos.toml

@@ -1,3 +1,6 @@
+[files]
+extend-exclude = ["*", "!*/", "!*.md", "!*.mdx"]
+
 [default.extend-words]
 # Scientific Software
 namd = "namd"

docs/hpc/harpertestfile.md

@@ -0,0 +1,2 @@
+## test file
+## `rsync` And `rclone`