Merge pull request #32986 from backstage/freben/valer

run vale directly instead of through the action

.github/workflows/verify_docs-quality.yml

@@ -7,7 +7,10 @@ on:
       - '**.md'
 
 jobs:
-  check-all-files:
+  check-docs:
+    permissions:
+      contents: read
+      pull-requests: read
     runs-on: ubuntu-latest
 
     steps:
@@ -18,18 +21,34 @@ jobs:
 
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      # Vale does not support file excludes, so we use the script to generate a list of files instead
-      # The action also does not allow args or a local config file to be passed in, so the files array
-      # also contains an "--config=.github/vale/config.ini" option
-      - name: generate vale args
-        id: generate
-        run: echo "args=$(node scripts/check-docs-quality.js --ci-args)" >> $GITHUB_OUTPUT
+      - name: Install vale
+        run: |
+          VALE_VERSION="3.7.1"
+          VALE_CHECKSUM="ba4924bf2c5884499f09b02a6eb3318b29df40a3e81701c0804b9b1aefcd9483"
+          VALE_DIST_DIR="/tmp/vale-dist"
+          VALE_ARCHIVE="vale_${VALE_VERSION}_Linux_64-bit.tar.gz"
 
-      - name: documentation quality check
-        uses: errata-ai/vale-action@d89dee975228ae261d22c15adcd03578634d429c # v2.1.1
-        with:
-          # This also contains --config=.github/vale/config.ini ... :/
-          files: '${{ steps.generate.outputs.args }}'
-          version: latest
+          mkdir -p "$VALE_DIST_DIR"
+
+          # Download pinned Vale binary
+          curl -fsSL -H "Authorization: token $GH_TOKEN" "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/${VALE_ARCHIVE}" -o "$VALE_DIST_DIR/$VALE_ARCHIVE"
+
+          # Verify the integrity of the downloaded archive
+          echo "$VALE_CHECKSUM  $VALE_DIST_DIR/$VALE_ARCHIVE" | sha256sum --check
+
+          mkdir -p "$HOME/.local/bin"
+          tar -xzf "$VALE_DIST_DIR/$VALE_ARCHIVE" -C "$HOME/.local/bin" vale
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          vale --version
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Get changed files
+        run: |
+          gh api "repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files" \
+            --paginate -q '.[] | select(.status != "removed") | .filename' > /tmp/pr-files.txt
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Documentation quality check
+        run: node scripts/check-docs-quality.js --ci /tmp/pr-files.txt

scripts/check-docs-quality.js

@@ -36,6 +36,7 @@ const IGNORED_WHEN_LISTING = [
 const IGNORED_WHEN_EXPLICIT = [
   /^ADOPTERS\.md$/,
   /^OWNERS\.md$/,
+  /^.*[/\\]CHANGELOG\.md$/, // generated from changesets anyway - THOSE should have been checked earlier
   /^.*[/\\]knip-report\.md$/,
 ];
 
@@ -71,7 +72,7 @@ async function exitIfMissingVale() {
   try {
     // eslint-disable-next-line @backstage/no-undeclared-imports
     await require('command-exists')('vale');
-  } catch (e) {
+  } catch {
     console.log(
       `Language linter (vale) was not found. Please install vale linter (https://vale.sh/docs/vale-cli/installation/).\n`,
     );
@@ -101,7 +102,92 @@ async function runVale(files) {
   return true;
 }
 
+async function ciCheck(prFilesPath) {
+  const content = await fs.readFile(prFilesPath, 'utf8');
+  const prFiles = content.split('\n').filter(f => f.trim());
+
+  const mdFiles = prFiles
+    .filter(f => f.endsWith('.md'))
+    .filter(f => !IGNORED_WHEN_LISTING.some(p => p.test(f)));
+
+  if (mdFiles.length === 0) {
+    console.log('No documentation files to check.');
+    return;
+  }
+
+  console.log(`Checking ${mdFiles.length} changed documentation file(s)...`);
+
+  const result = spawnSync(
+    'vale',
+    [
+      '--config',
+      resolvePath(rootDir, '.vale.ini'),
+      '--output=JSON',
+      ...mdFiles,
+    ],
+    { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024 },
+  );
+
+  if (result.error) {
+    console.error('Failed to run vale:', result.error.message);
+    process.exit(1);
+  }
+
+  let issueCount = 0;
+
+  if (result.stdout && result.stdout.trim()) {
+    try {
+      const data = JSON.parse(result.stdout);
+      for (const [file, alerts] of Object.entries(data)) {
+        for (const alert of alerts) {
+          const severityLevels = {
+            error: 'error',
+            warning: 'warning',
+            suggestion: 'notice',
+          };
+          const level = severityLevels[alert.Severity] ?? 'notice';
+          const col = alert.Span ? alert.Span[0] : 1;
+          const endCol = alert.Span ? `,endColumn=${alert.Span[1] + 1}` : '';
+          console.log(
+            `::${level} file=${file},line=${alert.Line},col=${col}${endCol},title=${alert.Check}::${alert.Message}`,
+          );
+          issueCount++;
+        }
+      }
+    } catch {
+      console.error('Failed to parse vale output:');
+      console.error(result.stdout);
+      process.exit(1);
+    }
+  }
+
+  if (result.stderr && result.stderr.trim()) {
+    console.error(result.stderr);
+  }
+
+  if (issueCount > 0) {
+    console.log(
+      `\nFound ${issueCount} documentation quality issue(s). Please review the annotations above.`,
+    );
+  }
+
+  if (result.status !== 0) {
+    process.exit(1);
+  }
+}
+
 async function main() {
+  if (process.argv.includes('--ci')) {
+    const idx = process.argv.indexOf('--ci');
+    const prFilesPath = process.argv[idx + 1];
+    if (!prFilesPath) {
+      console.error('Usage: check-docs-quality.js --ci <pr-files-list.txt>');
+      process.exit(1);
+    }
+    await ciCheck(prFilesPath);
+    return;
+  }
+
   if (process.argv.includes('--ci-args')) {
     const files = await listFiles();