w3c-html-validator 1.9.1 → 2.0.1

package/README.md

@@ -52,17 +52,17 @@ Command-line flags:
 | Flag              | Description                                                         | Value      |
 | ----------------- | ------------------------------------------------------------------- | ---------- |
 | `--continue`      | Report messages but do not throw an error if validation failed.     | N/A        |
+| `--default-rules` | Apply additional built-in opinionated ignore list.                  | N/A        |
 | `--delay`         | Debounce pause in milliseconds between each file validation.        | **number** |
 | `--dry-run`       | Bypass validation (for usage while building your CI).               | N/A        |
 | `--exclude`       | Comma separated list of strings to match in paths to skip.          | **string** |
-| `--ignore`        | Skip validation messages containing a string or matching a regex.   | **string** |
 | `--ignore-config` | File containing strings and regexes of validation messages to skip. | **string** |
+| `--ignore`        | Skip validation messages containing a string or matching a regex.   | **string** |
 | `--note`          | Place to add a comment only for humans.                             | **string** |
 | `--quiet`         | Suppress messages for successful validations.                       | N/A        |
 | `--trim`          | Truncate validation messages to not exceed a maximum length.        | **number** |
 
-### 4. Example CLI usage
-Examples:
+### 4. Examples
    - `html-validator`<br>
    Validates all HTML files in the project.
 
@@ -81,8 +81,8 @@ Examples:
    - `html-validator docs --ignore-config=spec/ignore-config.txt`<br>
    Similar to the pervious command but strings and regexes are stored in a configuration file (see the _Configuration File for Ignore Patterns_ section below).
 
-   - `html-validator --quiet`<br>
-   Suppresses all the "pass" status messages.
+   - `html-validator --default-rules --quiet`<br>
+   Skip all HTML validation messages in the built-in opinionated ignore list and also suppresses all the "pass" status messages.
 
    - `html-validator docs --delay=200`<br>
    Validates all HTML files in the "docs" folder at a rate of 1 file per 200 ms (default is 500 ms).
@@ -108,6 +108,16 @@ Example configuration file with 3 regexes:
 The caret (`^`) regex operator says to match from the beginning of the validation message.&nbsp;
 The dot (`.`) regex operator says to match any one character, which is a handy way to avoid typing the special curly quote characters in some of the validation messages.
 
+### 6. Default Ignore List
+The optional `--default-rules` flag causes HTML validation messages to be skipped if they are on the opinionated pre-defined list of unhelpful messages.&nbsp;
+
+Default ignore list:
+| Pattern                  | Level       | Explanation |
+| ------------------------ | ----------- | ----------- |
+| `Section lacks heading.` | **warning** | Rule is sensible for traditional print publishing but absurd for modern UI components not burning in nested `<div>` hell. |
+
+If there is an additional W3C validation message you think is ridiculous, open an issue with a note explaining why the message should be ignored.&nbsp;
+
 ## 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.
 
@@ -137,6 +147,7 @@ $ node examples.js
 | Name (key)       | Type                    | Default                          | Description                                             |
 | :--------------- | :---------------------- | :------------------------------- | :------------------------------------------------------ |
 | `checkUrl`       | **string**              | `'https://validator.w3.org/nu/'` | W3C validation API endpoint.                            |
+| `defaultRules`   | **boolean**             | `false`                          | Apply additional built-in opinionated ignore list.      |
 | `dryRun`         | **boolean**             | `false`                          | Bypass validation (for usage while building your CI).   |
 | `filename`       | **string**              | `null`                           | HTML file to validate.                                  |
 | `html`           | **string**              | `null`                           | HTML string to validate.                                |

package/bin/cli.js

@@ -21,62 +21,6 @@
 //    $ npm test
 //    $ node bin/cli.js spec --continue
 
-// Imports
-import { cliArgvUtil } from 'cli-argv-util';
-import { globSync } from 'glob';
 import { w3cHtmlValidator } from '../dist/w3c-html-validator.js';
-import fs from 'fs';
-import slash from 'slash';
 
-// Parameters and flags
-const validFlags =
-   ['continue', 'delay', 'dry-run', 'exclude', 'ignore', 'ignore-config', 'note', 'quiet', 'trim'];
-const cli =          cliArgvUtil.parse(validFlags);
-const files =        cli.params.length ? cli.params.map(cliArgvUtil.cleanPath) : ['.'];
-const excludeList =  cli.flagMap.exclude ? cli.flagMap.exclude.split(',') : [];
-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 dryRunMode =   cli.flagOn.dryRun || process.env.w3cHtmlValidator === 'dry-run';  //bash: export w3cHtmlValidator=dry-run
-
-const getFilenames = () => {
-   const readFilenames = (file) => globSync(file, { ignore: '**/node_modules/**/*' }).map(slash);
-   const readHtmlFiles = (folder) => readFilenames(folder + '/**/*.html');
-   const addHtml =       (file) => fs.lstatSync(file).isDirectory() ? readHtmlFiles(file) : file;
-   const keep =          (file) => excludeList.every(exclude => !file.includes(exclude));
-   return files.map(readFilenames).flat().map(addHtml).flat().filter(keep).sort();
-   };
-const filenames = getFilenames();
-const error =
-   cli.invalidFlag ?          cli.invalidFlagMsg :
-   !filenames.length ?        'No files to validate.' :
-   cli.flagOn.trim && !trim ? 'Value of "trim" must be a positive whole number.' :
-   null;
-if (error)
-   throw new Error('[w3c-html-validator] ' + error);
-if (dryRunMode)
-   w3cHtmlValidator.dryRunNotice();
-if (filenames.length > 1 && !cli.flagOn.quiet)
-   w3cHtmlValidator.summary(filenames.length);
-const reporterOptions = {
-   continueOnFail: cli.flagOn.continue,
-   quiet:          cli.flagOn.quiet,
-   maxMessageLen:  trim,
-   };
-const getIgnoreMessages = () => {
-   const toArray =    (text) => text.replace(/\r/g, '').split('\n').map(line => line.trim());
-   const notComment = (line) => line.length > 1 && !line.startsWith('#');
-   const readLines =  (file) => toArray(fs.readFileSync(file).toString()).filter(notComment);
-   const rawLines =   ignoreConfig ? readLines(ignoreConfig) : [];
-   if (ignore)
-      rawLines.push(ignore);
-   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 baseOptions =   { ignoreMessages: getIgnoreMessages(), dryRun: dryRunMode };
-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);
+w3cHtmlValidator.cli();

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

@@ -1,15 +1,17 @@
-//! w3c-html-validator v1.9.1 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
+//! w3c-html-validator v2.0.1 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
 
 export type ValidatorSettings = {
-    html: string;
-    filename: string;
-    website: string;
-    checkUrl: string;
-    ignoreLevel: 'info' | 'warning';
-    ignoreMessages: (string | RegExp)[];
-    output: ValidatorResultsOutput;
+    html: string | null;
+    filename: string | null;
+    website: string | null;
+    checkUrl: string | null;
+    ignoreLevel: 'info' | 'warning' | null;
+    ignoreMessages: ValidatorIgnorePattern[];
+    defaultRules: boolean;
+    output: 'json' | 'html' | null;
     dryRun: boolean;
 };
+export type ValidatorIgnorePattern = string | RegExp;
 export type ValidatorResultsMessage = {
     type: 'info' | 'error' | 'non-document-error' | 'network-error';
     subType?: 'warning' | 'fatal' | 'io' | 'schema' | 'internal';
@@ -36,7 +38,6 @@ export type ValidatorResults = {
     display: string | null;
     dryRun: boolean;
 };
-export type ValidatorResultsOutput = ValidatorResults['output'];
 export type ReporterSettings = {
     continueOnFail: boolean;
     maxMessageLen: number | null;
@@ -45,6 +46,9 @@ export type ReporterSettings = {
 };
 declare const w3cHtmlValidator: {
     version: string;
+    defaultIgnoreList: string[];
+    assert(ok: unknown, message: string | null): void;
+    cli(): void;
     validate(options: Partial<ValidatorSettings>): Promise<ValidatorResults>;
     dryRunNotice(): void;
     summary(numFiles: number): void;

package/dist/w3c-html-validator.js

@@ -1,30 +1,98 @@
-//! w3c-html-validator v1.9.1 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
+//! w3c-html-validator v2.0.1 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
 
+import { cliArgvUtil } from 'cli-argv-util';
+import { globSync } from 'glob';
 import chalk from 'chalk';
 import fs from 'fs';
 import log from 'fancy-log';
 import request from 'superagent';
 import slash from 'slash';
 const w3cHtmlValidator = {
-    version: '1.9.1',
+    version: '2.0.1',
+    defaultIgnoreList: [
+        'Section lacks heading.'
+    ],
+    assert(ok, message) {
+        if (!ok)
+            throw new Error(`[w3c-html-validator] ${message}`);
+    },
+    cli() {
+        const validFlags = ['continue', 'default-rules', 'delay', 'dry-run', 'exclude',
+            'ignore', 'ignore-config', 'note', 'quiet', 'trim'];
+        const cli = cliArgvUtil.parse(validFlags);
+        const files = cli.params.length ? cli.params.map(cliArgvUtil.cleanPath) : ['.'];
+        const excludeList = cli.flagMap.exclude?.split(',') ?? [];
+        const ignore = cli.flagMap.ignore ?? null;
+        const ignoreConfig = cli.flagMap.ignoreConfig ?? null;
+        const defaultRules = cli.flagOn.defaultRules;
+        const delay = Number(cli.flagMap.delay) || 500;
+        const trim = Number(cli.flagMap.trim) || null;
+        const dryRun = cli.flagOn.dryRun || process.env.w3cHtmlValidator === 'dry-run';
+        const getFilenames = () => {
+            const readFilenames = (file) => globSync(file, { ignore: '**/node_modules/**/*' }).map(slash);
+            const readHtmlFiles = (folder) => readFilenames(folder + '/**/*.html');
+            const addHtml = (file) => fs.lstatSync(file).isDirectory() ? readHtmlFiles(file) : file;
+            const keep = (file) => excludeList.every(exclude => !file.includes(exclude));
+            return files.map(readFilenames).flat().map(addHtml).flat().filter(keep).sort();
+        };
+        const filenames = getFilenames();
+        const error = cli.invalidFlag ? cli.invalidFlagMsg :
+            !filenames.length ? 'No files to validate.' :
+                cli.flagOn.trim && !trim ? 'Value of "trim" must be a positive whole number.' :
+                    null;
+        w3cHtmlValidator.assert(!error, error);
+        if (dryRun)
+            w3cHtmlValidator.dryRunNotice();
+        if (filenames.length > 1 && !cli.flagOn.quiet)
+            w3cHtmlValidator.summary(filenames.length);
+        const reporterOptions = {
+            continueOnFail: cli.flagOn.continue,
+            maxMessageLen: trim,
+            quiet: cli.flagOn.quiet,
+            title: null,
+        };
+        const getIgnoreMessages = () => {
+            const toArray = (text) => text.replace(/\r/g, '').split('\n').map(line => line.trim());
+            const notComment = (line) => line.length > 1 && !line.startsWith('#');
+            const readLines = (file) => toArray(fs.readFileSync(file).toString()).filter(notComment);
+            const rawLines = ignoreConfig ? readLines(ignoreConfig) : [];
+            if (ignore)
+                rawLines.push(ignore);
+            const isRegex = /^\/.*\/$/;
+            return rawLines.map(line => isRegex.test(line) ? new RegExp(line.slice(1, -1)) : line);
+        };
+        const ignoreMessages = getIgnoreMessages();
+        const options = (filename) => ({ filename, ignoreMessages, defaultRules, dryRun });
+        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);
+    },
     validate(options) {
         const defaults = {
             checkUrl: 'https://validator.w3.org/nu/',
+            defaultRules: false,
             dryRun: false,
+            filename: null,
+            html: null,
             ignoreLevel: null,
             ignoreMessages: [],
             output: 'json',
+            website: null,
         };
         const settings = { ...defaults, ...options };
-        if (!settings.html && !settings.filename && !settings.website)
-            throw new Error('[w3c-html-validator] Must specify the "html", "filename", or "website" option.');
-        if (![null, 'info', 'warning'].includes(settings.ignoreLevel))
-            throw new Error(`[w3c-html-validator] Invalid ignoreLevel option: ${settings.ignoreLevel}`);
-        if (settings.output !== 'json' && settings.output !== 'html')
-            throw new Error('[w3c-html-validator] Option "output" must be "json" or "html".');
+        const missingInput = !settings.html && !settings.filename && !settings.website;
+        const badLevel = ![null, 'info', 'warning'].includes(settings.ignoreLevel);
+        const invalidOutput = settings.output !== 'json' && settings.output !== 'html';
+        const error = missingInput ? 'Must specify the "html", "filename", or "website" option.' :
+            badLevel ? `Invalid ignoreLevel option: ${settings.ignoreLevel}` :
+                invalidOutput ? 'Option "output" must be "json" or "html".' :
+                    null;
+        w3cHtmlValidator.assert(!error, error);
         const filename = settings.filename ? slash(settings.filename) : null;
         const mode = settings.html ? 'html' : filename ? 'filename' : 'website';
-        const readFile = (filename) => fs.readFileSync(filename, 'utf-8').replace(/\r/g, '');
+        const unixify = (text) => text.replace(/\r/g, '');
+        const readFile = (filename) => unixify(fs.readFileSync(filename, 'utf-8'));
         const inputHtml = settings.html ?? (filename ? readFile(filename) : null);
         const makePostRequest = () => request.post(settings.checkUrl)
             .set('Content-Type', 'text/html; encoding=utf-8')
@@ -32,7 +100,8 @@ const w3cHtmlValidator = {
         const makeGetRequest = () => request.get(settings.checkUrl)
             .query({ doc: settings.website });
         const w3cRequest = inputHtml ? makePostRequest() : makeGetRequest();
-        w3cRequest.set('User-Agent', 'W3C HTML Validator ~ github.com/center-key/w3c-html-validator');
+        const userAgent = 'W3C HTML Validator ~ github.com/center-key/w3c-html-validator';
+        w3cRequest.set('User-Agent', userAgent);
         w3cRequest.query({ out: settings.output });
         const json = settings.output === 'json';
         const success = '<p class="success">';
@@ -44,8 +113,11 @@ const w3cHtmlValidator = {
         const filterMessages = (response) => {
             const aboveInfo = (subType) => settings.ignoreLevel === 'info' && !!subType;
             const aboveIgnoreLevel = (message) => !settings.ignoreLevel || message.type !== 'info' || aboveInfo(message.subType);
-            const matchesSkipPattern = (title) => settings.ignoreMessages.some(pattern => typeof pattern === 'string' ? title.includes(pattern) : pattern.test(title));
-            const isImportant = (message) => aboveIgnoreLevel(message) && !matchesSkipPattern(message.message);
+            const defaultList = settings.defaultRules ? w3cHtmlValidator.defaultIgnoreList : [];
+            const ignoreList = [...settings.ignoreMessages, ...defaultList];
+            const tester = (title) => (pattern) => typeof pattern === 'string' ? title.includes(pattern) : pattern.test(title);
+            const skipMatchFound = (title) => ignoreList.some(tester(title));
+            const isImportant = (message) => aboveIgnoreLevel(message) && !skipMatchFound(message.message);
             if (json)
                 response.body.messages = response.body.messages?.filter(isImportant) ?? [];
             return response;
@@ -93,8 +165,8 @@ const w3cHtmlValidator = {
             title: null,
         };
         const settings = { ...defaults, ...options };
-        if (typeof results?.validates !== 'boolean')
-            throw new Error(`[w3c-html-validator] Invalid results for reporter(): ${results}`);
+        const hasResults = 'validates' in results && typeof results.validates === 'boolean';
+        w3cHtmlValidator.assert(hasResults, `Invalid results for reporter(): ${results}`);
         const messages = results.messages ?? [];
         const title = settings.title ?? results.title;
         const status = results.validates ? chalk.green.bold('✔ pass') : chalk.red.bold('✘ fail');
@@ -122,8 +194,8 @@ const w3cHtmlValidator = {
             const fileDetails = () => `${results.filename} -- ${results.messages.map(toString).join(', ')}`;
             return !results.filename ? results.messages[0].message : fileDetails();
         };
-        if (!settings.continueOnFail && !results.validates)
-            throw new Error(`[w3c-html-validator] Failed: ${failDetails()}`);
+        const failed = !settings.continueOnFail && !results.validates;
+        w3cHtmlValidator.assert(!failed, `Failed: ${failDetails()}`);
         return results;
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "w3c-html-validator",
-   "version": "1.9.1",
+   "version": "2.0.1",
    "description": "Check the markup validity of HTML files using the W3C validator",
    "license": "MIT",
    "type": "module",
@@ -53,11 +53,11 @@
    },
    "scripts": {
       "pretest": "run-scripts clean lint build",
-      "test": "mocha spec/*.spec.js --timeout 7000",
+      "test": "mocha spec --timeout 7000",
       "examples": "node examples.js"
    },
    "dependencies": {
-      "chalk": "~5.5",
+      "chalk": "~5.6",
       "cli-argv-util": "~1.3",
       "fancy-log": "~2.0",
       "glob": "~11.0",
@@ -65,21 +65,20 @@
       "superagent": "~10.2"
    },
    "devDependencies": {
-      "@eslint/js": "~9.33",
+      "@eslint/js": "~9.39",
       "@types/fancy-log": "~2.0",
-      "@types/node": "~24.2",
+      "@types/node": "~24.10",
       "@types/superagent": "~8.1",
-      "add-dist-header": "~1.5",
+      "add-dist-header": "~1.6",
       "assert-deep-strict-equal": "~1.2",
       "copy-file-util": "~1.3",
       "copy-folder-util": "~1.1",
-      "eslint": "~9.33",
+      "eslint": "~9.39",
       "jshint": "~2.13",
-      "merge-stream": "~2.0",
       "mocha": "~11.7",
-      "rimraf": "~6.0",
+      "rimraf": "~6.1",
       "run-scripts-util": "~1.3",
       "typescript": "~5.9",
-      "typescript-eslint": "~8.39"
+      "typescript-eslint": "~8.46"
    }
 }