@fulldecent/nice-checkers-plugin 1.3.8 → 1.3.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +94 -77
- package/dist/index.cjs +28608 -504
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +4 -9
- package/dist/index.d.cts.map +1 -0
- package/dist/index.d.ts +4 -8
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +28578 -505
- package/dist/index.js.map +1 -1
- package/package.json +24 -31
package/README.md
CHANGED
|
@@ -1,32 +1,36 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Nice Checkers
|
|
2
2
|
|
|
3
|
-
[](https://github.com/fulldecent/html-validate-nice-checkers/actions/workflows/lint.yml)
|
|
4
|
+
[](https://github.com/fulldecent/html-validate-nice-checkers/actions/workflows/test.yml)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
## What this project does
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
Nice Checkers is an [HTML-validate](https://html-validate.org/) plugin with 11 rules for SEO, security, accessibility, and URLs.
|
|
8
9
|
|
|
9
|
-
-
|
|
10
|
-
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
- :white_check_mark: **Comprehensive testing**: high test coverage with realistic fixtures
|
|
10
|
+
The npm package is [@fulldecent/nice-checkers-plugin](https://www.npmjs.com/package/@fulldecent/nice-checkers-plugin). It publishes ESM and CommonJS builds and TypeScript types. It runs in Node.js while a site is built. Some rules call other sites with `curl`. A `fetch()` implementation is blocked by [html-validate issue 317](https://gitlab.com/html-validate/html-validate/-/issues/317).
|
|
11
|
+
|
|
12
|
+
`engines` allows Node.js 22.16 and newer, which is the oldest Node.js supported by html-validate 10. [Tests](.github/workflows/test.yml) run on the Node.js 22, 24, and 26 release lines. [Lint](.github/workflows/lint.yml) checks Prettier and markdownlint. Local development uses the Node.js version in [.node-version](.node-version).
|
|
13
|
+
|
|
14
|
+
[GitHub Pages template](https://github.com/fulldecent/github-pages-template) is a site that uses this plugin, with Actions and Pages deployment.
|
|
15
15
|
|
|
16
16
|
## Installation
|
|
17
17
|
|
|
18
|
-
These instructions assume
|
|
18
|
+
These instructions assume Nice Checkers is part of a web test suite running Node.js 22.16 or newer and [HTML-validate](https://html-validate.org/).
|
|
19
|
+
|
|
20
|
+
### Add the package
|
|
19
21
|
|
|
20
|
-
|
|
22
|
+
Install Nice Checkers as a dev dependency. It is used to test the site.
|
|
21
23
|
|
|
22
|
-
|
|
24
|
+
Yarn:
|
|
23
25
|
|
|
24
26
|
```sh
|
|
25
|
-
|
|
26
|
-
|
|
27
|
+
yarn add -D @fulldecent/nice-checkers-plugin
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
npm:
|
|
27
31
|
|
|
28
|
-
|
|
29
|
-
npm install
|
|
32
|
+
```sh
|
|
33
|
+
npm install -D @fulldecent/nice-checkers-plugin
|
|
30
34
|
```
|
|
31
35
|
|
|
32
36
|
### Update your HTML-validate configuration
|
|
@@ -35,7 +39,7 @@ This example assumes you are using the .htmlvalidate.mjs configuration flavor. H
|
|
|
35
39
|
|
|
36
40
|
```diff
|
|
37
41
|
import { defineConfig } from "html-validate";
|
|
38
|
-
+ import
|
|
42
|
+
+ import NiceCheckersPlugin from "@fulldecent/nice-checkers-plugin"
|
|
39
43
|
|
|
40
44
|
export default defineConfig({
|
|
41
45
|
- "extends": ["htmlvalidate:recommended"]
|
|
@@ -144,7 +148,7 @@ This allows you to validate your HTML before publishing, even when the canonical
|
|
|
144
148
|
"cacheExpiryFoundSeconds": 2592000,
|
|
145
149
|
"cacheExpiryNotFoundSeconds": 259200,
|
|
146
150
|
"timeoutSeconds": 5,
|
|
147
|
-
"cacheDatabasePath": "cache/external-links.
|
|
151
|
+
"cacheDatabasePath": "cache/external-links.csv",
|
|
148
152
|
"userAgent": "Mozilla/5.0 (compatible; html-validate-nice-checkers)"
|
|
149
153
|
}
|
|
150
154
|
]
|
|
@@ -161,7 +165,7 @@ This allows you to validate your HTML before publishing, even when the canonical
|
|
|
161
165
|
| `cacheExpiryFoundSeconds` | `number` | `2592000` | Cache duration for successful checks (default: 30 days) |
|
|
162
166
|
| `cacheExpiryNotFoundSeconds` | `number` | `259200` | Cache duration for failed checks (default: 3 days) |
|
|
163
167
|
| `timeoutSeconds` | `number` | `5` | Request timeout in seconds |
|
|
164
|
-
| `cacheDatabasePath` | `string` | `"cache/external-links.
|
|
168
|
+
| `cacheDatabasePath` | `string` | `"cache/external-links.csv"` | Path to the CSV cache database file |
|
|
165
169
|
| `userAgent` | `string` | `"Mozilla/5.0 (compatible; html-validate-nice-checkers)"` | User agent string for HTTP requests |
|
|
166
170
|
| `manuallyReviewedPath` | `string` | `""` | Path to CSV file with manually reviewed URLs (see below) |
|
|
167
171
|
| `manuallyReviewedExpirySeconds` | `number` | `31536000` | Expiry time for manually reviewed URLs (default: 365 days) |
|
|
@@ -216,7 +220,7 @@ Reports insecure HTTP links that are accessible via HTTPS, encouraging the use o
|
|
|
216
220
|
"cacheExpiryFoundSeconds": 2592000,
|
|
217
221
|
"cacheExpiryNotFoundSeconds": 259200,
|
|
218
222
|
"timeoutSeconds": 10,
|
|
219
|
-
"cacheDatabasePath": "cache/https-availability.
|
|
223
|
+
"cacheDatabasePath": "cache/https-availability.csv"
|
|
220
224
|
}
|
|
221
225
|
]
|
|
222
226
|
}
|
|
@@ -225,12 +229,12 @@ Reports insecure HTTP links that are accessible via HTTPS, encouraging the use o
|
|
|
225
229
|
|
|
226
230
|
#### Configuration options
|
|
227
231
|
|
|
228
|
-
| Option | Type | Default
|
|
229
|
-
| ---------------------------- | -------- |
|
|
230
|
-
| `cacheExpiryFoundSeconds` | `number` | `2592000`
|
|
231
|
-
| `cacheExpiryNotFoundSeconds` | `number` | `259200`
|
|
232
|
-
| `timeoutSeconds` | `number` | `10`
|
|
233
|
-
| `cacheDatabasePath` | `string` | `"cache/https-availability.
|
|
232
|
+
| Option | Type | Default | Description |
|
|
233
|
+
| ---------------------------- | -------- | -------------------------------- | ------------------------------------------------------------- |
|
|
234
|
+
| `cacheExpiryFoundSeconds` | `number` | `2592000` | Cache duration for successful HTTPS checks (default: 30 days) |
|
|
235
|
+
| `cacheExpiryNotFoundSeconds` | `number` | `259200` | Cache duration for failed HTTPS checks (default: 3 days) |
|
|
236
|
+
| `timeoutSeconds` | `number` | `10` | Request timeout in seconds |
|
|
237
|
+
| `cacheDatabasePath` | `string` | `"cache/https-availability.csv"` | Path to the CSV cache database file |
|
|
234
238
|
|
|
235
239
|
### `nice-checkers/internal-links`
|
|
236
240
|
|
|
@@ -297,7 +301,7 @@ Ensures that package assets loaded from CDNs (like jsDelivr) are using the lates
|
|
|
297
301
|
{
|
|
298
302
|
"cacheExpirySeconds": 172800,
|
|
299
303
|
"timeoutSeconds": 10,
|
|
300
|
-
"cacheDatabasePath": "cache/latest-packages.
|
|
304
|
+
"cacheDatabasePath": "cache/latest-packages.csv",
|
|
301
305
|
"skipUrlPatterns": ["googletagmanager.com"]
|
|
302
306
|
}
|
|
303
307
|
]
|
|
@@ -307,12 +311,12 @@ Ensures that package assets loaded from CDNs (like jsDelivr) are using the lates
|
|
|
307
311
|
|
|
308
312
|
#### Configuration options
|
|
309
313
|
|
|
310
|
-
| Option | Type | Default
|
|
311
|
-
| -------------------- | ---------- |
|
|
312
|
-
| `cacheExpirySeconds` | `number` | `172800`
|
|
313
|
-
| `timeoutSeconds` | `number` | `10`
|
|
314
|
-
| `cacheDatabasePath` | `string` | `"cache/latest-packages.
|
|
315
|
-
| `skipUrlPatterns` | `string[]` | `[]`
|
|
314
|
+
| Option | Type | Default | Description |
|
|
315
|
+
| -------------------- | ---------- | ----------------------------- | ----------------------------------------------------------- |
|
|
316
|
+
| `cacheExpirySeconds` | `number` | `172800` | Cache duration for package version checks (default: 2 days) |
|
|
317
|
+
| `timeoutSeconds` | `number` | `10` | Request timeout in seconds |
|
|
318
|
+
| `cacheDatabasePath` | `string` | `"cache/latest-packages.csv"` | Path to the CSV cache database file |
|
|
319
|
+
| `skipUrlPatterns` | `string[]` | `[]` | Array of URL patterns to skip checking |
|
|
316
320
|
|
|
317
321
|
### `nice-checkers/match-regex`
|
|
318
322
|
|
|
@@ -547,36 +551,30 @@ See [issue #23](https://github.com/fulldecent/html-validate-nice-checkers/issues
|
|
|
547
551
|
|
|
548
552
|
## Development
|
|
549
553
|
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
### Install
|
|
554
|
+
Clone the repo:
|
|
553
555
|
|
|
554
556
|
```sh
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
557
|
+
git clone https://github.com/fulldecent/html-validate-nice-checkers.git ~/Developer/html-validate-nice-checkers
|
|
558
|
+
cd ~/Developer/html-validate-nice-checkers
|
|
559
|
+
```
|
|
558
560
|
|
|
559
|
-
|
|
560
|
-
nvm use
|
|
561
|
+
Use Node and yarn. The Node version is pinned in [.node-version](.node-version), and the Yarn version is pinned in [package.json](package.json). Quick start with [fnm](https://github.com/Schniz/fnm):
|
|
561
562
|
|
|
562
|
-
|
|
563
|
+
```sh
|
|
564
|
+
fnm install
|
|
565
|
+
fnm use
|
|
563
566
|
corepack enable
|
|
564
|
-
|
|
565
|
-
# Install dependencies
|
|
566
567
|
yarn install
|
|
568
|
+
yarn test
|
|
567
569
|
```
|
|
568
570
|
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
These notes are [from the Yarn project](https://yarnpkg.com/getting-started/editor-sdks#).
|
|
571
|
+
Format files the lint workflow checks:
|
|
572
572
|
|
|
573
573
|
```sh
|
|
574
|
-
yarn
|
|
574
|
+
yarn format
|
|
575
575
|
```
|
|
576
576
|
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
### [Development scripts](https://github.com/fulldecent/html-validate-nice-checkers/blob/main/package.json)
|
|
577
|
+
[Development scripts](package.json):
|
|
580
578
|
|
|
581
579
|
- `yarn build` builds the package
|
|
582
580
|
- `yarn build:watch` builds the package in watch mode
|
|
@@ -584,34 +582,53 @@ and YES, use workspace TypeScript version.
|
|
|
584
582
|
- `yarn test:watch` runs the tests in watch mode
|
|
585
583
|
- `yarn test:coverage` runs the tests and generates a coverage report
|
|
586
584
|
- `yarn lint` runs TypeScript type checking
|
|
587
|
-
- `yarn
|
|
588
|
-
|
|
589
|
-
### Testing notes
|
|
590
|
-
|
|
591
|
-
When running `yarn test` to test Nice Checkers itself, you may see two warnings about missing "root" paths. These come from the mock HTTP server (`@jaredwray/mockhttp`) which is only used in our test suite. The warnings are harmless and do not affect test results. We consider this an error in the upstream mock HTTP server package. These warnings do not appear for downstream users who install Nice Checkers to validate their own websites.
|
|
585
|
+
- `yarn check:package` checks the built package with publint and arethetypeswrong
|
|
586
|
+
- `yarn format` formats files with Prettier and markdownlint
|
|
592
587
|
|
|
593
|
-
|
|
588
|
+
Changes are ready to push when `yarn format && yarn lint && yarn test` passes.
|
|
594
589
|
|
|
595
|
-
|
|
596
|
-
2. Bump yarn version if appropriate (`yarn set version latest`).
|
|
597
|
-
3. Bump yarn dependencies if appropriate (`yarn upgrade-interactive`).
|
|
598
|
-
4. Bump package.json `peerDependencies` if new `html-validate` is available.
|
|
599
|
-
5. Bump GitHub Actions `uses:` versions if appropriate.
|
|
600
|
-
6. Ensure `yarn && yarn format && yarn lint && yarn build && yarn test && echo ✅` all pass.
|
|
601
|
-
7. Ensure CI passes.
|
|
602
|
-
8. Bump package.json version. (Use a separate commit by itself for this.)
|
|
603
|
-
9. Use GitHub website to create a tag and a release.
|
|
590
|
+
### Editor setup
|
|
604
591
|
|
|
605
|
-
|
|
592
|
+
`yarn format` and the lint workflow both run `npx prettier@latest`. The editor's Prettier extension can be a different version, so `yarn format` is the one that matches CI.
|
|
606
593
|
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
Periodically, load schemaorg-current-https.jsonld file from <https://schema.org/docs/developers.html> and save to src/vendor/schemaorg-current-https.jsonld. Ideally, the sponsors of Schema.org: Google, Inc., Yahoo, Inc., Microsoft Corporation and Yandex should maintain a NPM package for this file that we can depend on. This would allow our package manager to handle updates.
|
|
610
|
-
|
|
611
|
-
## Browser support
|
|
612
|
-
|
|
613
|
-
This is a Node.js library designed for build-time HTML validation. For browser usage, ensure your bundler supports the module format you're using. Some of our rules use `cURL` which will not work in the browser. We would like to switch to `fetch()` but [are limited by](https://gitlab.com/html-validate/html-validate/-/issues/317) HTML-validate.
|
|
594
|
+
### Testing notes
|
|
614
595
|
|
|
615
|
-
|
|
596
|
+
When running `yarn test` to test Nice Checkers itself, you may see two warnings about missing "root" paths. These come from the mock HTTP server (`@jaredwray/mockhttp`) which is only used in our test suite. The warnings are harmless and do not affect test results. We consider this an error in the upstream mock HTTP server package. These warnings do not appear for downstream users who install Nice Checkers to validate their own websites.
|
|
616
597
|
|
|
617
|
-
|
|
598
|
+
## Releasing
|
|
599
|
+
|
|
600
|
+
Package versions use [Semantic Versioning](https://semver.org/).
|
|
601
|
+
|
|
602
|
+
1. Finish the changes that belong in the release.
|
|
603
|
+
1. Bump `peerDependencies` when a newly supported html-validate version requires it.
|
|
604
|
+
1. Run `yarn && yarn format && yarn lint && yarn build && yarn test && yarn check:package`.
|
|
605
|
+
1. Bump `version` in package.json in a commit by itself.
|
|
606
|
+
1. Create a GitHub release for that version. [publish.yml](.github/workflows/publish.yml) publishes the package to npm.
|
|
607
|
+
|
|
608
|
+
## Maintenance and dependency updates
|
|
609
|
+
|
|
610
|
+
Do this every month or so and please send a PR here if you see updates available:
|
|
611
|
+
|
|
612
|
+
1. Identify external Actions in [.github/workflows](./.github/workflows) scripts and look for available new versions. Review and then update to the new version if it is safe. GitHub-supported Actions (i.e. under the actions/ organization) may require only cursory review.
|
|
613
|
+
1. Review the Node.js version in `.node-version`. Update it when a newer version is appropriate. `fnm install` reads that file. This local pin is separate from the versions the package supports.
|
|
614
|
+
1. Review the supported Node.js versions against the [Node.js release schedule](https://nodejs.org/en/about/previous-releases). This package supports the Current, Active LTS, and Maintenance LTS release lines, the same as html-validate. It does not support a Node.js version that the oldest html-validate in `peerDependencies` has dropped from its `engines`. `engines.node` in package.json is the floor, and tsdown compiles to that floor. When a release line reaches end-of-life, or a `peerDependencies` bump raises html-validate's floor, raise `engines.node` and update the Node.js versions in [test.yml](.github/workflows/test.yml) in the same commit.
|
|
615
|
+
1. Review the Yarn version in `package.json` (`packageManager`). Update it with `yarn set version stable && yarn` when a newer stable version is appropriate. [Yarn's install instructions](https://yarnpkg.com/getting-started/install) document that command.
|
|
616
|
+
1. Review direct dependencies with `yarn upgrade-interactive`.
|
|
617
|
+
1. Check whether [TypeScript issue #63769](https://github.com/microsoft/TypeScript/issues/63769) is fixed and whether Vite still warns about Plug'n'Play ([Vite pull request #21906](https://github.com/vitejs/vite/pull/21906)). When neither blocks Plug'n'Play, remove `nodeLinker` from `.yarnrc.yml`.
|
|
618
|
+
1. Download the Schema.org vocabulary from <https://schema.org/docs/developers.html> and save it as `src/vendor/schemaorg-current-https.json`. Schema.org does not publish that file as an npm package, so the update is manual.
|
|
619
|
+
|
|
620
|
+
## References
|
|
621
|
+
|
|
622
|
+
1. We use title case for titles and proper nouns; not for headings and things. This includes our README above as well as our workflow rules and other configuration files. If you have a different policy, then please implement it throughout.
|
|
623
|
+
1. This project uses the MIT license, the same license as [node.js-template](https://github.com/fulldecent/node.js-template).
|
|
624
|
+
1. We would prefer if fnm supported build attestations since it is installed as a binary ([issue #1588](https://github.com/Schniz/fnm/issues/1588)).
|
|
625
|
+
1. Node.js ignore rules are inlined from [Node.gitignore](https://github.com/github/gitignore/blob/main/Node.gitignore). This project also ignores `/cache`, the fixture files that tests rewrite, and `package-lock.json`. `package-lock.json` is ignored because dependencies are locked with `yarn.lock`.
|
|
626
|
+
1. `.yarnrc.yml` sets `enableScripts` to true (Yarn 4.14 defaults to false) and `npmMinimalAgeGate` to 0 (Yarn 4.12 defaults to one day). `approvedGitRepositories` is `"**"`, which approves every git dependency. [Yarn: Security](https://yarnpkg.com/features/security). It also sets `nodeLinker: pnpm` instead of the default, Plug'n'Play, because TypeScript 7 and Vite do not support Plug'n'Play. The comments in that file link to both upstream issues.
|
|
627
|
+
1. Prettier options are in [.prettierrc](.prettierrc). [node.js-template](https://github.com/fulldecent/node.js-template) has no application source and therefore no Prettier config. Formatting still uses `npx prettier@latest`, the same command as that template's lint workflow.
|
|
628
|
+
1. `.prettierignore` ignores `*.md`, the same as the template. It also ignores `tests/fixtures` and `src/vendor`. Fixture HTML is the exact input for `required-reports.json`, which records line, column, and byte offset. `src/vendor/schemaorg-current-https.json` is a file downloaded from Schema.org.
|
|
629
|
+
1. markdownlint disables MD013, the same as the template, and sets MD024 `siblings_only`. Each rule section repeats the headings "Configuration" and "Configuration options". `siblings_only` allows that because each heading sits under a different rule.
|
|
630
|
+
1. [test.yml](.github/workflows/test.yml) runs `yarn lint`, `yarn test`, and `yarn build`. Then it checks the package with publint and arethetypeswrong, packs it, and loads it into html-validate from ESM and from CommonJS. The CommonJS test uses html-validate's `cjsResolver`, which loads plugins with `require()`. The test script in node.js-template is `true`, which is enough for a package with no behavior of its own. This job runs on Node.js 22, 24, and 26, the Maintenance LTS, Active LTS, and Current release lines. `.node-version` stays at 24.
|
|
631
|
+
1. [tsdown.config.ts](tsdown.config.ts) builds `dist/` from `src/index.ts`: `.js` and `.d.ts` for `import`, `.cjs` and `.d.cts` for `require`, matching `exports` in package.json. `tsc --noEmit` type checks and does not publish. The build is not minified so that people can debug the rules. html-validate is a peer dependency and is not bundled. CommonJS is kept for html-validate's `cjsResolver`, so the build turns off tsdown's `legacyCjs` warning.
|
|
632
|
+
1. [publish.yml](.github/workflows/publish.yml) publishes to npm when a GitHub release is published. node.js-template sets `"private": true` and is not an npm package.
|
|
633
|
+
1. This project is built based on [best practices documented in node.js-template](https://github.com/fulldecent/node.js-template).
|
|
634
|
+
1. This project is built based on [best practices documented in project-template](https://github.com/fulldecent/project-template), release 1.0.0.
|