w3c-html-validator 1.1.2 → 1.2.0

package/README.md

@@ -8,41 +8,90 @@ _Check the markup validity of HTML files using the W3C validator_
 [![Vulnerabilities](https://snyk.io/test/github/center-key/w3c-html-validator/badge.svg)](https://snyk.io/test/github/center-key/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)
 
-## 1) Setup
+**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.
 
-### Install
+<img src=https://raw.githubusercontent.com/center-key/w3c-html-validator/main/examples.png
+width=800 alt=screenshot>
+
+## A) Setup
 Install package for node:
 ```shell
 $ npm install --save-dev w3c-html-validator
 ```
 
-### Import
-Import into your application:
-```javascript
-import { w3cHtmlValidator } from 'w3c-html-validator';
+## B) Usage
+### 1. npm scripts
+Run `html-validator` from the `"scripts"` section of your **package.json** file.
+
+The parameters are files to be validated.
+
+Example **package.json** scripts:
+```json
+   "scripts": {
+      "validate":   "html-validator docs/*.html flyer.html",
+      "one-folder": "html-validator docs",
+      "all":        "html-validator --quiet"
+   },
 ```
-or invoke directly [from the command line or from a **package.json** script](#6-command-line).
 
-## 2) Usage
-Call the `validate()` function:
-```javascript
+Passing no parameters defaults to validating all HTML files in the project (skipping the
+**node_modules** folder).
+
+### 2. Global
+You can install **w3c-html-validator** globally and then run it anywhere directly from the terminal.
+
+Example terminal commands:
+```shell
+$ npm install --global w3c-html-validator
+$ html-validator docs/*.html flyer.html
+```
+
+### 3. CLI Flags
+Command-line flags:
+| Flag        | Description                                                  | Value      |
+| ----------- | ------------------------------------------------------------ | ---------- |
+| `--exclude` | Comma separated list of strings to match in paths to skip.   | **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:
+   - `html-validator`<br>
+   Validate all HTML files in the project.
+   - `html-validator --exclude=build,tmp`<br>
+   Slip all files which have "build" or "tmp" anywhere in their pathname or filename.
+   - `html-validator --quiet`<br>
+   Suppress "pass" messages.
+   - `html-validator docs`<br>
+   Validate HTML files in a folder.
+   - `html-validator docs --trim=30`<br>
+   Truncate messages to 30 characters.
+
+## 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.
+
+### 1. Import
+Example call to the `validate()` function:
+```typescript
+import { w3cHtmlValidator } from 'w3c-html-validator';
+
 const options = { filename: 'docs/index.html' };
 w3cHtmlValidator.validate(options).then(console.log);
 ```
 To display formatted output, replace `console.log` with `w3cHtmlValidator.reporter`:
-```javascript
+```typescript
 w3cHtmlValidator.validate(options).then(w3cHtmlValidator.reporter);
 ```
+
 To see some example validation results, run the commands:
 ```shell
 $ cd w3c-html-validator
 $ node examples.js
 ```
-<img src=https://raw.githubusercontent.com/center-key/w3c-html-validator/main/examples.png
-width=800 alt=screenshot>
 
-## 3) Options
-### w3cHtmlValidator.validate(options)
+### 2. Options
+#### w3cHtmlValidator.validate(options)
 | Name (key)       | Type                    | Default                          | Description                                                          |
 | :--------------- | :---------------------- | :------------------------------- | :------------------------------------------------------------------- |
 | `html`           | **string**              | `null`                           | HTML string to validate.                                             |
@@ -56,14 +105,14 @@ width=800 alt=screenshot>
 *The `ignoreMessages` and `ignoreLevel` options only work for `'json'` output.&nbsp;
 Option value `'warning'` also skips `'info'`.
 
-### w3cHtmlValidator.reporter(options)
+#### w3cHtmlValidator.reporter(options)
 | Name (key)      | Type        | Default | Description                                                    |
 | :-------------- | :---------- | :------ | :------------------------------------------------------------- |
 | `maxMessageLen` | **number**  | `null`  | Trim validation messages to not exceed a maximum length.       |
 | `quiet`         | **boolean** | `false` | Suppress messages for successful validations.                  |
 | `title`         | **string**  | `null`  | Override display title (useful for naming HTML string inputs). |
 
-## 4) TypeScript Declarations
+### 3. TypeScript Declarations
 The **TypeScript Declaration File** file is [w3c-html-validator.d.ts](dist/w3c-html-validator.d.ts)
 in the **dist** folder.
 
@@ -83,12 +132,13 @@ type ValidatorResults = {
    };
 ```
 
-## 5) Mocha Example
+### 4. Mocha Example
 ```javascript
 import assert from 'assert';
 import { w3cHtmlValidator } from 'w3c-html-validator';
 
 describe('Home page', () => {
+
    it('validates', (done) => {
       const handleResults = (results) => {
          assert(results.status === 200, 'Request succeeded');
@@ -98,37 +148,19 @@ describe('Home page', () => {
       const options = { filename: 'docs/index.html' };
       w3cHtmlValidator.validate(options).then(handleResults);
       });
-   });
-```
 
-## 6) Command Line
-You can install **w3c-html-validator** globally and then run it anywhere directly from the terminal.
-
-Example terminal commands:
-```shell
-$ npm install --global w3c-html-validator
-$ html-validator docs/*.html flyer.html
-$ html-validator docs  #validate html files in a folder
-$ html-validator       #validate all html files in project
-```
-or as an npm script in **package.json**:
-```json
-   "scripts": {
-      "validate":   "html-validator docs/*.html flyer.html",
-      "one-folder": "html-validator docs",
-      "all":        "html-validator"
-   },
+   });
 ```
-Passing no parameters defaults to validating all HTML files in the project (skipping the
-**node_modules** folder).
 
 <br>
 
 ---
-**Build Tools**
-   - 🎋 [add-dist-header](https://github.com/center-key/add-dist-header):&nbsp; _Prepend a one-line header comment (with license notice) to distribution files_
-   - 📄 [copy-file-util](https://github.com/center-key/copy-file-util):&nbsp; _Copy or rename a file (CLI tool designed for use in npm scripts)_
-   - 📂 [copy-folder-cli](https://github.com/center-key/copy-folder-cli):&nbsp; _Recursively copy a folder (CLI tool designed for use in npm scripts)_
+**CLI Build Tools**
+   - 🎋 [add-dist-header](https://github.com/center-key/add-dist-header):&nbsp; _Prepend a one-line banner comment (with license notice) to distribution files_
+   - 📄 [copy-file-util](https://github.com/center-key/copy-file-util):&nbsp; _Copy or rename a file with optional package version number_
+   - 📂 [copy-folder-util](https://github.com/center-key/copy-folder-util):&nbsp; _Recursively copy files from one folder to another folder_
+   - 🔍 [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_
    - 🚦 [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

@@ -21,38 +21,44 @@
 
 // Imports
 import { w3cHtmlValidator } from '../dist/w3c-html-validator.js';
-import { lstatSync }        from 'fs';
-import chalk                from 'chalk';
-import glob                 from 'glob';
-import log                  from 'fancy-log';
+import chalk from 'chalk';
+import fs    from 'fs';
+import glob  from 'glob';
+import log   from 'fancy-log';
 
 // Parameters
-const validFlags =  ['quiet'];
+const validFlags =  ['exclude', 'quiet', 'trim'];
 const args =        process.argv.slice(2);
 const flags =       args.filter(arg => /^--/.test(arg));
 const flagMap =     Object.fromEntries(flags.map(flag => flag.replace(/^--/, '').split('=')));
+const flagOn =      Object.fromEntries(validFlags.map(flag => [flag, flag in flagMap]));
 const invalidFlag = Object.keys(flagMap).find(key => !validFlags.includes(key));
 const params =      args.filter(arg => !/^--/.test(arg));
 
 // Data
 const files = params;
-const mode =  { quiet: 'quiet' in flagMap };
+const trim =  parseInt(flagMap.trim) || null;
 
 // Validator
 const keep =         (filename) => !filename.includes('node_modules/');
 const readFolder =   (folder) => glob.sync(folder + '**/*.html', { ignore: '**/node_modules/**/*' });
-const expandFolder = (file) => lstatSync(file).isDirectory() ? readFolder(file + '/') : file;
+const expandFolder = (file) => fs.lstatSync(file).isDirectory() ? readFolder(file + '/') : file;
 const getFilenames = () => [...new Set(files.map(expandFolder).flat().filter(keep))].sort();
-const filenames =    files.length ? getFilenames() : readFolder('');
+const list =         files.length ? getFilenames() : readFolder('');
+const excludes =     flagMap.exclude?.split(',') ?? [];
+const filenames =    list.filter(name => !excludes.find(exclude => name.includes(exclude)));
 const error =
-   invalidFlag ?       'Invalid flag: ' + invalidFlag :
-   !files.length ?     'Missing file parameter.' :
-   !filenames.length ? 'No files to validate.' :
+   invalidFlag ?          'Invalid flag: ' + invalidFlag :
+   !filenames.length ?    'No files to validate.' :
+   flagOn.trim && !trim ? 'Value of "trim" must be a positive whole number.' :
    null;
 if (error)
    throw Error('[w3c-html-validator] ' + error);
-if (filenames.length > 1 && !mode.quiet)
+if (filenames.length > 1 && !flagOn.quiet)
    log(chalk.gray('w3c-html-validator'), chalk.magenta('files: ' + filenames.length));
-const reporterOptions = { quiet: mode.quiet };
+const reporterOptions = {
+   quiet:         flagOn.quiet,
+   maxMessageLen: trim,
+   };
 const handleReport = (report) => w3cHtmlValidator.reporter(report, reporterOptions);
 filenames.forEach(file => w3cHtmlValidator.validate({ filename: file }).then(handleReport));

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

@@ -1,14 +1,15 @@
-//! w3c-html-validator v1.1.2 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
+//! w3c-html-validator v1.2.0 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
 
-export declare type ValidatorOptions = {
-    html?: string;
-    filename?: string;
-    website?: string;
-    checkUrl?: string;
-    ignoreLevel?: 'info' | 'warning';
-    ignoreMessages?: string | RegExp;
-    output?: ValidatorResultsOutput;
+export declare type ValidatorSettings = {
+    html: string;
+    filename: string;
+    website: string;
+    checkUrl: string;
+    ignoreLevel: 'info' | 'warning';
+    ignoreMessages: string | RegExp;
+    output: ValidatorResultsOutput;
 };
+export declare type ValidatorOptions = Partial<ValidatorSettings>;
 export declare type ValidatorResultsMessage = {
     type: 'info' | 'error' | 'non-document-error' | 'network-error';
     subType?: 'warning' | 'fatal' | 'io' | 'schema' | 'internal';
@@ -35,11 +36,12 @@ export declare type ValidatorResults = {
     display: string | null;
 };
 export declare type ValidatorResultsOutput = ValidatorResults['output'];
-export declare type ReporterOptions = {
-    maxMessageLen?: number | null;
-    quiet?: boolean;
-    title?: string | null;
+export declare type ReporterSettings = {
+    maxMessageLen: number | null;
+    quiet: boolean;
+    title: string | null;
 };
+export declare type ReporterOptions = Partial<ReporterSettings>;
 declare const w3cHtmlValidator: {
     version: string;
     validate(options: ValidatorOptions): Promise<ValidatorResults>;

package/dist/w3c-html-validator.js

@@ -1,11 +1,11 @@
-//! w3c-html-validator v1.1.2 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
+//! w3c-html-validator v1.2.0 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
 
-import { readFileSync } from 'fs';
 import chalk from 'chalk';
+import fs from 'fs';
 import log from 'fancy-log';
 import request from 'superagent';
 const w3cHtmlValidator = {
-    version: '1.1.2',
+    version: '1.2.0',
     validate(options) {
         var _a;
         const defaults = {
@@ -22,7 +22,7 @@ const w3cHtmlValidator = {
         if (settings.output !== 'json' && settings.output !== 'html')
             throw Error('[w3c-html-validator] Option "output" must be "json" or "html".');
         const mode = settings.html ? 'html' : settings.filename ? 'filename' : 'website';
-        const readFile = (filename) => readFileSync(filename, 'utf8').replace(/\r/g, '');
+        const readFile = (filename) => fs.readFileSync(filename, 'utf-8').replace(/\r/g, '');
         const inputHtml = (_a = settings.html) !== null && _a !== void 0 ? _a : (settings.filename ? readFile(settings.filename) : null);
         const makePostRequest = () => request.post(settings.checkUrl)
             .set('Content-Type', 'text/html; encoding=utf-8')

package/dist/w3c-html-validator.umd.cjs

@@ -1,4 +1,4 @@
-//! w3c-html-validator v1.1.2 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
+//! w3c-html-validator v1.2.0 ~~ https://github.com/center-key/w3c-html-validator ~~ MIT License
 
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -9,18 +9,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
         if (v !== undefined) module.exports = v;
     }
     else if (typeof define === "function" && define.amd) {
-        define(["require", "exports", "fs", "chalk", "fancy-log", "superagent"], factory);
+        define(["require", "exports", "chalk", "fs", "fancy-log", "superagent"], factory);
     }
 })(function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.w3cHtmlValidator = void 0;
-    const fs_1 = require("fs");
     const chalk_1 = __importDefault(require("chalk"));
+    const fs_1 = __importDefault(require("fs"));
     const fancy_log_1 = __importDefault(require("fancy-log"));
     const superagent_1 = __importDefault(require("superagent"));
     const w3cHtmlValidator = {
-        version: '1.1.2',
+        version: '1.2.0',
         validate(options) {
             var _a;
             const defaults = {
@@ -37,7 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
             if (settings.output !== 'json' && settings.output !== 'html')
                 throw Error('[w3c-html-validator] Option "output" must be "json" or "html".');
             const mode = settings.html ? 'html' : settings.filename ? 'filename' : 'website';
-            const readFile = (filename) => (0, fs_1.readFileSync)(filename, 'utf8').replace(/\r/g, '');
+            const readFile = (filename) => fs_1.default.readFileSync(filename, 'utf-8').replace(/\r/g, '');
             const inputHtml = (_a = settings.html) !== null && _a !== void 0 ? _a : (settings.filename ? readFile(settings.filename) : null);
             const makePostRequest = () => superagent_1.default.post(settings.checkUrl)
                 .set('Content-Type', 'text/html; encoding=utf-8')

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "w3c-html-validator",
-   "version": "1.1.2",
+   "version": "1.2.0",
    "description": "Check the markup validity of HTML files using the W3C validator",
    "license": "MIT",
    "type": "module",
@@ -33,7 +33,7 @@
       "w3c"
    ],
    "jshintConfig": {
-      "esversion": 9,
+      "esversion": 11,
       "strict": "implied",
       "eqeqeq": true,
       "undef": true,
@@ -65,16 +65,16 @@
       "step:01": "rimraf build dist **/.DS_Store",
       "step:02": "jshint . --exclude-path .gitignore",
       "step:03": "eslint --max-warnings 0 . --ext .ts",
-      "step:04": "tsc",
-      "step:05": "tsc --module UMD --outDir build/umd",
-      "step:06": "copy-file build/umd/w3c-html-validator.js build/w3c-html-validator.umd.cjs",
-      "step:07": "add-dist-header build dist",
+      "step:10": "tsc",
+      "step:11": "tsc --module UMD --outDir build/umd",
+      "step:12": "copy-file build/umd/w3c-html-validator.js build/w3c-html-validator.umd.cjs",
+      "step:20": "add-dist-header build dist",
       "pretest": "npm-run-all step:*",
       "test": "mocha spec/*.spec.js --timeout 5000",
       "examples": "node examples.js"
    },
    "dependencies": {
-      "chalk": "~5.0",
+      "chalk": "~5.1",
       "fancy-log": "~2.0",
       "glob": "~8.0",
       "superagent": "~8.0"
@@ -82,15 +82,15 @@
    "devDependencies": {
       "@types/fancy-log": "~2.0",
       "@types/glob": "~8.0",
-      "@types/node": "~18.7",
+      "@types/node": "~18.8",
       "@types/superagent": "~4.1",
-      "@typescript-eslint/eslint-plugin": "~5.38",
-      "@typescript-eslint/parser": "~5.38",
-      "add-dist-header": "~0.2",
+      "@typescript-eslint/eslint-plugin": "~5.40",
+      "@typescript-eslint/parser": "~5.40",
+      "add-dist-header": "~0.3",
       "assert-deep-strict-equal": "~1.0",
       "copy-file-util": "~0.1",
-      "copy-folder-cli": "~0.1",
-      "eslint": "~8.23",
+      "copy-folder-util": "~0.2",
+      "eslint": "~8.25",
       "jshint": "~2.13",
       "merge-stream": "~2.0",
       "mocha": "~10.0",