v3 docs: bump & cleanup node modules (#4052)

The node modules for the v3 docs are outdated which includes potential security issues.
This change bumps all node modules and removes unused ones. Additionally the 'check-pages' module was replaced with 'linkinator' due to regular updates.

Author: johha

docs/v3/README.md

@@ -6,7 +6,7 @@ Built with [Slate](https://github.com/lord/slate).
 Getting Started
 ---------------
 
-- Ensure you have Ruby 2.4.x installed
+- Ensure you have Ruby 3.2.x installed
 - Ensure you have Bundler installed and have run `bundle install` in this directory
 - Ensure you have the latest version of NodeJS installed
 - Get the npm dependencies: `npm install`

docs/v3/gulpfile.js

@@ -1,10 +1,11 @@
-const fs = require('fs');
-const gulp = require('gulp');
-const {exec} = require('child_process');
-const express = require('express');
-const checkPages = require('check-pages');
-const { glob } = require('glob');
-const cheerio = require('cheerio');
+import { exec } from 'child_process';
+import { readFileSync } from 'fs';
+import gulp from 'gulp';
+import express from 'express';
+import { glob } from 'glob';
+import { LinkChecker } from 'linkinator';
+
+const cheerio = await import('cheerio');
 
 function displayErrors(err, stdout, stderr) {
   if (err) {
@@ -19,7 +20,7 @@ function checkInternalLinksAndExit(htmlPath) {
   const duplicateHeadingIds = [];
   const seenHeadingIds = new Set();
   const badLinks = [];
-  const $ = cheerio.load(fs.readFileSync(htmlPath, 'utf8'));
+  const $ = cheerio.load(readFileSync(htmlPath, 'utf8'));
 
   $('a').each((index, anchor) => {
     const href = $(anchor).attr('href') || '';
@@ -32,13 +33,12 @@ function checkInternalLinksAndExit(htmlPath) {
       if (foundElementByName) return;
 
       const text = $(anchor).text();
-      badLinks.push({text, href});
+      badLinks.push({ text, href });
     }
   });
 
   $('h1,h2,h3').each((index, element) => {
     const id = $(element).attr('id');
-
     if (id) {
       if (seenHeadingIds.has(id)) duplicateHeadingIds.push(id);
       else seenHeadingIds.add(id);
@@ -48,7 +48,7 @@ function checkInternalLinksAndExit(htmlPath) {
   if (badLinks.length) {
     console.error('v3 docs error: Found invalid internal links');
     console.error('Make sure these `href`s correspond to the `id`s of real headings in the HTML:');
-    console.error(badLinks.map(({text, href}) => `  - [${text}](${href})`).join('\n'));
+    console.error(badLinks.map(({ text, href }) => `  - [${text}](${href})`).join('\n'));
   }
 
   if (duplicateHeadingIds.length) {
@@ -63,8 +63,9 @@ function checkInternalLinksAndExit(htmlPath) {
 }
 
 function checkSyntaxErrorsAndExit(htmlPath) {
-  const $ = cheerio.load(fs.readFileSync(htmlPath, 'utf8'));
+  const $ = cheerio.load(readFileSync(htmlPath, 'utf8'));
   const syntaxErrors = $('code .err');
+
   if (syntaxErrors.length) {
     syntaxErrors.each((_index, errorElement) => {
       console.error('⚠️ v3 docs error: Found syntax error');
@@ -73,25 +74,66 @@ function checkSyntaxErrorsAndExit(htmlPath) {
       console.error('👆👆👆👆👆👆👆👆👆👆👆👆👆👆👆👆👆\n')
     });
 
-    process.exit(1)
+    process.exit(1);
   }
 }
 
-function checkPathAndExit(path, options, done) {
+async function checkPathAndExit(path, options, done) {
   const app = express();
   app.use(express.static(path));
-  const server = app.listen({port: 8001});
+  const server = app.listen({ port: 8001 });
+
+  const url = 'http://localhost:8001/';
+
+  const config = {
+    path: url,
+    linksToSkip: options.linksToSkip || [],
+    recurse: options.recurse,
+    silent: options.silent,
+    markdown: options.markdown,
+  };
+
+  try {
+    const checker = new LinkChecker();
+
+    if (path === '../v2') {
+      const htmlFiles = await glob(path + '/**/*.html');
+      let allResults = { links: [] };
+      for (let file of htmlFiles) {
+        const fileUrl = url + file.substr(path.length);
+        const fileConfig = { ...config, path: fileUrl };
+        const results = await checker.check(fileConfig);
+        allResults.links = allResults.links.concat(results.links);
+      }
+      displayResults(allResults);
+    } else {
+      const results = await checker.check(config);
+      displayResults(results);
+    }
 
-  return checkPages(console, options, (err, stdout, stderr) => {
     server.close();
     done();
 
-    if (err) {
-      return displayErrors(err, stdout, stderr);
-    }
+  } catch (err) {
+    server.close();
+    done(err);
+    process.exit(1);
+  }
+}
 
-    return true;
-  });
+function displayResults(results) {
+  const totalLinks = results.links.length;
+  const brokenLinks = results.links.filter(link => link.state === 'BROKEN');
+
+  console.log(`Total Links Checked: ${totalLinks}`);
+  console.log(`Broken Links Found: ${brokenLinks.length}`);
+  if (brokenLinks.length > 0) {
+    console.log('Broken Links:');
+    brokenLinks.forEach(link => {
+      console.log(`  - ${link.url} (status: ${link.status})`);
+    });
+    process.exitCode = 1;
+  }
 }
 
 gulp.task('build', cb => {
@@ -110,7 +152,7 @@ gulp.task('webserver', cb => {
     }
     cb();
   });
-  console.log('Your docs are waiting for you at http://localhost:8000')
+  console.log('Your docs are waiting for you at http://localhost:8000');
 });
 
 gulp.task('default', gulp.series('webserver'));
@@ -119,29 +161,29 @@ gulp.task('checkV3docs', gulp.series('build', done => {
   checkInternalLinksAndExit('build/index.html');
   checkSyntaxErrorsAndExit('build/index.html');
 
-  checkPathAndExit('build', {
-    checkLinks: true,
-    summary: true,
-    terse: true,
-    onlySameDomain: true,
-    pageUrls: ['http://localhost:8001/'],
-    linksToIgnore: ['http://localhost:8001/version/release-candidate']
-  }, done);
+  try {
+    checkPathAndExit('build', {
+      linksToSkip: ['http://localhost:8001/version/release-candidate'],
+      recurse: true,
+      silent: true,
+      markdown: true,
+    }, done);
+  } catch (err) {
+    done(err);
+  }
 }));
 
-gulp.task('checkV2docs', async(done) => {
-  const htmlFiles = await glob('../v2/**/*.html')
-  const fixedFiles = htmlFiles.map(fname => {
-    return 'http://localhost:8001' + fname.substr('../v2'.length);
-  });
-
-  checkPathAndExit('../v2', {
-    checkLinks: true,
-    summary: true,
-    terse: true,
-    onlySameDomain: true,
-    pageUrls: ['http://localhost:8001/'].concat(fixedFiles)
-  }, done);
+gulp.task('checkV2docs', done => {
+  try {
+    checkPathAndExit('../v2', {
+      linksToSkip: [],
+      recurse: true,
+      silent: true,
+      markdown: true,
+    }, done);
+  } catch (err) {
+    done(err);
+  }
 });
 
-gulp.task('checkdocs', gulp.parallel('checkV2docs', 'checkV3docs'));
+gulp.task('checkdocs', gulp.series('checkV2docs', 'checkV3docs'));