w3c-html-validator 1.6.4 → 1.8.0

package/README.md

@@ -5,10 +5,10 @@ _Check the markup validity of HTML files using the W3C validator_
 
 [![License:MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/center-key/w3c-html-validator/blob/main/LICENSE.txt)
 [![npm](https://img.shields.io/npm/v/w3c-html-validator.svg)](https://www.npmjs.com/package/w3c-html-validator)
-[![Build](https://github.com/center-key/w3c-html-validator/workflows/build/badge.svg)](https://github.com/center-key/w3c-html-validator/actions/workflows/run-spec-on-push.yaml)
+[![Build](https://github.com/center-key/w3c-html-validator/actions/workflows/run-spec-on-push.yaml/badge.svg)](https://github.com/center-key/w3c-html-validator/actions/workflows/run-spec-on-push.yaml)
 
 **w3c-html-validator** takes HTML files and returns detailed validation results. 
-The reporter produces formatted output indended for use in build scripts and test suites.
+The reporter produces formatted output indented for use in build scripts and test suites.
 
 <img src=https://raw.githubusercontent.com/center-key/w3c-html-validator/main/examples.png
 width=800 alt=screenshot>
@@ -20,7 +20,7 @@ $ npm install --save-dev w3c-html-validator
 ```
 
 ## B) Usage
-### 1. npm scripts
+### 1. npm package.json scripts
 Run `html-validator` from the `"scripts"` section of your **package.json** file.
 
 The parameters are folders and files to be validated.
@@ -110,6 +110,8 @@ The dot (`.`) regex operator says to match any one character, which is a handy w
 ## D) Application Code and Testing Frameworks
 In addition to the CLI interface, the **w3c-html-validator** package can also be imported and called directly in ESM and TypeScript projects.
 
+Note that if your application calls `w3cHtmlValidator.validate()` multiple times, you must throttle (debounce) the calls or risk getting rejected by the W3C server.
+
 ### 1. Import
 Example call to the `validate()` function:
 ```typescript
@@ -139,12 +141,13 @@ $ node examples.js
 | `ignoreLevel`    | `'info'` or `'warning'` | `null`                           | Skip unwanted messages.*                                |
 | `ignoreMessages` | **array**               | `[]`                             | Skip messages containing a string or matching a regex.* |
 | `output`         | `'json'` or `'html'`    | `'json'`                         | Get results as an array or as a web page.               |
+| `skip`           | **boolean**             | `false`                          | bypass validation (for usage while building your CI).   |
 | `website`        | **string**              | `null`                           | URL of website to validate.                             |
 
 *The `ignoreMessages` and `ignoreLevel` options only work for `'json'` output.&nbsp;
 Setting `ignoreLevel` to `'warning'` skips both `'warning'` level and `'info'` level validation messages.
 
-#### w3cHtmlValidator.reporter(options)
+#### w3cHtmlValidator.reporter(results, options)
 | Name (key)       | Type        | Default | Description                                                     |
 | :--------------- | :---------- | :------ | :-------------------------------------------------------------- |
 | `continueOnFail` | **boolean** | `false` | Report messages but do not throw an error if validation failed. |
@@ -169,6 +172,7 @@ type ValidatorResults = {
    status:    number,
    messages:  ValidatorResultsMessage[] | null,  //for 'json' output
    display:   string | null,                     //for 'html' output
+   skip:      boolean,
    };
 ```
 
@@ -202,7 +206,7 @@ describe('Home page', () => {
    - 🪺 [recursive-exec](https://github.com/center-key/recursive-exec):&nbsp; _Run a command on each file in a folder and its subfolders_
    - 🔍 [replacer-util](https://github.com/center-key/replacer-util):&nbsp; _Find and replace strings or template outputs in text files_
    - 🔢 [rev-web-assets](https://github.com/center-key/rev-web-assets):&nbsp; _Revision web asset filenames with cache busting content hash fingerprints_
-   - 🚆 [run-scripts-util](https://github.com/center-key/run-scripts-util):&nbsp; _Organize npm scripts into named groups of easy to manage commands_
+   - 🚆 [run-scripts-util](https://github.com/center-key/run-scripts-util):&nbsp; _Organize npm package.json scripts into named groups of easy to manage commands_
    - 🚦 [w3c-html-validator](https://github.com/center-key/w3c-html-validator):&nbsp; _Check the markup validity of HTML files using the W3C validator_
 
 Feel free to submit questions at:<br>

package/bin/cli.js

@@ -36,6 +36,7 @@ const ignore =       cli.flagMap.ignore ?? null;
 const ignoreConfig = cli.flagMap.ignoreConfig ?? null;
 const delay =        Number(cli.flagMap.delay) || 500;  //default half second debounce pause
 const trim =         Number(cli.flagMap.trim) || null;
+const skip =         process.env.w3cHtmlValidator === 'skip';  //bash: export w3cHtmlValidator=skip
 
 // Validator
 const globOptions =  { ignore: '**/node_modules/**/*' };
@@ -54,6 +55,8 @@ const error =
    null;
 if (error)
    throw Error('[w3c-html-validator] ' + error);
+if (skip)
+   w3cHtmlValidator.skipNotice();
 if (filenames.length > 1 && !cli.flagOn.quiet)
    w3cHtmlValidator.summary(filenames.length);
 const reporterOptions = {
@@ -71,8 +74,9 @@ const getIgnoreMessages = () => {
    const isRegex = /^\/.*\/$/;  //starts and ends with a slash indicating it's a regex
    return rawLines.map(line => isRegex.test(line) ? new RegExp(line.slice(1, -1)) : line);
    };
-const handleReport = (report) => w3cHtmlValidator.reporter(report, reporterOptions);
-const options =      (filename) => ({ filename: filename, ignoreMessages: getIgnoreMessages() });
-const getReport =    (filename) => w3cHtmlValidator.validate(options(filename)).then(handleReport);
-const processFile =  (filename, i) => globalThis.setTimeout(() => getReport(filename), i * delay);
+const baseOptions =   { ignoreMessages: getIgnoreMessages(), skip: skip };
+const options =       (filename) => ({ filename: filename, ...baseOptions });
+const handleResults = (results) => w3cHtmlValidator.reporter(results, reporterOptions);
+const getReport =     (filename) => w3cHtmlValidator.validate(options(filename)).then(handleResults);
+const processFile =   (filename, i) => globalThis.setTimeout(() => getReport(filename), i * delay);
 filenames.forEach(processFile);

package/dist/w3c-html-validator.d.ts

@@ -1,4 +1,4 @@
-//! w3c-html-validator v1.6.4 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
+//! w3c-html-validator v1.8.0 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
 
 export type ValidatorSettings = {
     html: string;
@@ -8,6 +8,7 @@ export type ValidatorSettings = {
     ignoreLevel: 'info' | 'warning';
     ignoreMessages: (string | RegExp)[];
     output: ValidatorResultsOutput;
+    skip: boolean;
 };
 export type ValidatorResultsMessage = {
     type: 'info' | 'error' | 'non-document-error' | 'network-error';
@@ -33,6 +34,7 @@ export type ValidatorResults = {
     status: number;
     messages: ValidatorResultsMessage[] | null;
     display: string | null;
+    skip: boolean;
 };
 export type ValidatorResultsOutput = ValidatorResults['output'];
 export type ReporterSettings = {
@@ -44,6 +46,7 @@ export type ReporterSettings = {
 declare const w3cHtmlValidator: {
     version: string;
     validate(options: Partial<ValidatorSettings>): Promise<ValidatorResults>;
+    skipNotice(): void;
     summary(numFiles: number): void;
     reporter(results: ValidatorResults, options?: Partial<ReporterSettings>): ValidatorResults;
 };

package/dist/w3c-html-validator.js

@@ -1,4 +1,4 @@
-//! w3c-html-validator v1.6.4 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
+//! w3c-html-validator v1.8.0 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
 
 import chalk from 'chalk';
 import fs from 'fs';
@@ -6,13 +6,14 @@ import log from 'fancy-log';
 import request from 'superagent';
 import slash from 'slash';
 const w3cHtmlValidator = {
-    version: '1.6.4',
+    version: '1.8.0',
     validate(options) {
         const defaults = {
             checkUrl: 'https://validator.w3.org/nu/',
             ignoreLevel: null,
             ignoreMessages: [],
             output: 'json',
+            skip: false,
         };
         const settings = { ...defaults, ...options };
         if (!settings.html && !settings.filename && !settings.website)
@@ -60,16 +61,26 @@ const w3cHtmlValidator = {
             status: response.statusCode || -1,
             messages: json ? response.body.messages : null,
             display: json ? null : response.text,
+            skip: settings.skip,
         });
         const handleError = (reason) => {
-            const response = reason.response;
-            const getMsg = () => [response.status, response.res.statusMessage, response.request.url];
-            const message = response ? getMsg() : [reason.errno, reason.message];
-            const errRes = response ?? {};
+            const errRes = reason.response ?? {};
+            const getMsg = () => [errRes.status, errRes.res.statusMessage, errRes.request.url];
+            const message = reason.response ? getMsg() : [reason.errno, reason.message];
             errRes.body = { messages: [{ type: 'network-error', message: message.join(' ') }] };
             return toValidatorResults(errRes);
         };
-        return w3cRequest.then(filterMessages).then(toValidatorResults).catch(handleError);
+        const pseudoResponse = {
+            statusCode: 200,
+            body: { messages: [] },
+            text: 'Validation skipped.',
+        };
+        const pseudoRequest = () => new Promise(resolve => resolve(pseudoResponse));
+        const validation = settings.skip ? pseudoRequest() : w3cRequest;
+        return validation.then(filterMessages).then(toValidatorResults).catch(handleError);
+    },
+    skipNotice() {
+        log(chalk.gray('w3c-html-validator'), chalk.yellowBright('skip mode:'), chalk.whiteBright('validation being bypassed'));
     },
     summary(numFiles) {
         log(chalk.gray('w3c-html-validator'), chalk.magenta('files: ' + numFiles));

package/package.json

@@ -1,21 +1,15 @@
 {
    "name": "w3c-html-validator",
-   "version": "1.6.4",
+   "version": "1.8.0",
    "description": "Check the markup validity of HTML files using the W3C validator",
    "license": "MIT",
    "type": "module",
    "module": "dist/w3c-html-validator.js",
-   "main": "dist/w3c-html-validator.js",
    "types": "dist/w3c-html-validator.d.ts",
+   "exports": "./dist/w3c-html-validator.js",
    "files": [
       "dist"
    ],
-   "exports": {
-      ".": {
-         "import": "./dist/w3c-html-validator.js"
-      },
-      "./": "./dist/"
-   },
    "bin": {
       "html-validator": "bin/cli.js",
       "w3c-html-validator": "bin/cli.js"
@@ -87,24 +81,24 @@
       "fancy-log": "~2.0",
       "glob": "~10.3",
       "slash": "~5.1",
-      "superagent": "~8.1"
+      "superagent": "~9.0"
    },
    "devDependencies": {
       "@types/fancy-log": "~2.0",
-      "@types/node": "~20.10",
+      "@types/node": "~20.12",
       "@types/superagent": "~8.1",
-      "@typescript-eslint/eslint-plugin": "~6.17",
-      "@typescript-eslint/parser": "~6.17",
-      "add-dist-header": "~1.3",
-      "assert-deep-strict-equal": "~1.1",
-      "copy-file-util": "~1.1",
+      "@typescript-eslint/eslint-plugin": "~7.7",
+      "@typescript-eslint/parser": "~7.7",
+      "add-dist-header": "~1.4",
+      "assert-deep-strict-equal": "~1.2",
+      "copy-file-util": "~1.2",
       "copy-folder-util": "~1.1",
-      "eslint": "~8.56",
+      "eslint": "8.57.0",
       "jshint": "~2.13",
       "merge-stream": "~2.0",
-      "mocha": "~10.2",
+      "mocha": "~10.4",
       "rimraf": "~5.0",
       "run-scripts-util": "~1.2",
-      "typescript": "~5.3"
+      "typescript": "~5.4"
    }
 }