chore: require 100% JSDoc coverage with docov

README.md

@@ -21,7 +21,7 @@ nodevu is composed of a set of modules:
 ## Development
 
 - `npm test` and `npm run coverage` run every module's tests.
-- `npm run lint` checks the whole repo with oxlint and oxfmt.
+- `npm run lint` checks the whole repo with oxlint and oxfmt, and checks with [docov](https://github.com/cutenode/docov) that everything the modules export has JSDoc. `docov.jsonc` sets what it scans.
 - `npm run types` type-checks the JSDoc and writes each module's TypeScript declarations to its `types/` folder. Commit them: CI fails when they're out of date.
 - `npm run docs:dev` builds the docs from `docs/pages/` with [doc-kit](https://doc-kit.nodejs.org/) and serves them locally. `npm run docs` only builds them, into `out/`.
 

core/util/dev/beforeEachTemplate.js

@@ -8,6 +8,11 @@ const {
 const staticIndex = require('../../test/data/static/index.json');
 const staticSchedule = require('../../test/data/static/schedule.json');
 
+/**
+ * Mocks the network for a test: the default and `https://bnb.im` index.json
+ * and schedule.json URLs serve core's static snapshots, and any other request
+ * fails.
+ */
 function beforeEachTemplate() {
 	// this fixes a bug in Node.js - it should be fixed _eventually_ and can be removed: https://github.com/nodejs/undici/issues/1248
 	dns.setDefaultResultOrder('ipv4first');

core/util/dev/fixtures.js

@@ -1,10 +1,12 @@
 const index = require('../../test/data/static/index.json');
 const schedule = require('../../test/data/static/schedule.json');
 
-// returns options for @nodevu/core (and the packages built on it) that serve
-// `data` (core's index.json and schedule.json snapshots by default) instead of
-// fetching them, only including releases that were out by `now`, like the
-// real index.json. any other URL throws, so tests never touch the network.
+/**
+ * Returns options for @nodevu/core (and the packages built on it) that serve
+ * `data` (core's index.json and schedule.json snapshots by default) instead of
+ * fetching them, only including releases that were out by `now`, like the
+ * real index.json. Any other URL throws, so tests never touch the network.
+ */
 function at(now, data = { index, schedule }) {
 	return {
 		now,

core/util/dev/write.js

@@ -1,6 +1,9 @@
 const { writeFile } = require('node:fs/promises');
 const { resolve } = require('node:path');
 
+/**
+ * Writes `data` to `path` as tab-indented JSON.
+ */
 async function write(path, data) {
 	const outputJSON = JSON.stringify(data, null, '\t');
 	const filepath = resolve(path);

docov.jsonc

@@ -0,0 +1,12 @@
+{
+	"$schema": "https://raw.githubusercontent.com/cutenode/docov/v0.1.1/docov.schema.json",
+	"exclude": [
+		"**/test/**",
+		// generated from the JSDoc by `npm run types`, and TypeScript 7 leaves
+		// @typedef descriptions out of them
+		"*/types/**",
+		// vendored oxlint plugin
+		"tools/oxlint/anti-slop/**",
+	],
+	"threshold": 100,
+}

docs/theme/Navigation.jsx

@@ -9,9 +9,11 @@ import Logo from '#theme/Logo';
 
 import styles from '@node-core/ui-components/Containers/NavBar/index.module.css';
 
-// doc-kit's navigation bar, except the logo links to the site's index
-// relative to the page. the NavBar links it to `/`, which leaves the site
-// when it's served from a subpath, like GitHub Pages' /nodevu/
+/**
+ * doc-kit's navigation bar, except the logo links to the site's index
+ * relative to the page. The NavBar links it to `/`, which leaves the site
+ * when it's served from a subpath, like GitHub Pages' /nodevu/.
+ */
 export default ({ metadata }) => {
 	const home = `${relativeOrAbsolute('/index', metadata.path)}.html`;
 

package.json

@@ -4,7 +4,7 @@
 	"description": "comprehensive node.js version tooling",
 	"main": "index.js",
 	"scripts": {
-		"lint": "oxlint && oxfmt --check",
+		"lint": "oxlint && oxfmt --check && docov",
 		"lint:write": "oxlint --fix && oxfmt",
 		"coverage": "npm run coverage --ws --if-present",
 		"test": "npm run test --ws",
@@ -42,6 +42,7 @@
 	"devDependencies": {
 		"@doc-kit/cli": "1.0.5",
 		"@doc-kit/generator-react": "0.5.0",
+		"@docov/cli": "0.1.1",
 		"@node-core/ui-components": "1.8.1",
 		"@oxlint/plugins": "1.89.0",
 		"@types/luxon": "3.7.6",

static/util/dev/write.js

@@ -1,6 +1,9 @@
 const { writeFile } = require('node:fs/promises');
 const { resolve } = require('node:path');
 
+/**
+ * Writes `data` to `path` as JSON indented with two spaces.
+ */
 async function write(path, data) {
 	const outputJSON = JSON.stringify(data, null, 2);
 	let filepath = resolve(path);