From 10b2e56e167de810da42c601327afad7d89c4280 Mon Sep 17 00:00:00 2001 From: botandbang <337765928+botandbang@users.noreply.github.com> Date: Thu, 29 Oct 2026 17:00:26 -0400 Subject: [PATCH] chore: require 100% JSDoc coverage with docov --- README.md | 2 +- core/util/dev/beforeEachTemplate.js | 5 +++++ core/util/dev/fixtures.js | 10 ++++++---- core/util/dev/write.js | 3 +++ docov.jsonc | 12 ++++++++++++ docs/theme/Navigation.jsx | 8 +++++--- package.json | 3 ++- static/util/dev/write.js | 3 +++ 8 files changed, 37 insertions(+), 9 deletions(-) create mode 100644 docov.jsonc diff --git a/README.md b/README.md index 0866d02e..f4bb872e 100644 --- a/README.md +++ b/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/`. diff --git a/core/util/dev/beforeEachTemplate.js b/core/util/dev/beforeEachTemplate.js index 49e0b4a0..9ebabf22 100644 --- a/core/util/dev/beforeEachTemplate.js +++ b/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'); diff --git a/core/util/dev/fixtures.js b/core/util/dev/fixtures.js index c9aa4e3f..562bc5bf 100644 --- a/core/util/dev/fixtures.js +++ b/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, diff --git a/core/util/dev/write.js b/core/util/dev/write.js index d98dd763..4cf7d22c 100644 --- a/core/util/dev/write.js +++ b/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); diff --git a/docov.jsonc b/docov.jsonc new file mode 100644 index 00000000..136c7ad3 --- /dev/null +++ b/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, +} diff --git a/docs/theme/Navigation.jsx b/docs/theme/Navigation.jsx index 3110dca9..2d1222d2 100644 --- a/docs/theme/Navigation.jsx +++ b/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`; diff --git a/package.json b/package.json index 2250f298..aa500f5f 100644 --- a/package.json +++ b/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", diff --git a/static/util/dev/write.js b/static/util/dev/write.js index d11cc93f..bd6d72b1 100644 --- a/static/util/dev/write.js +++ b/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);