Merge pull request #50 from happyprime/lint-cleanup

Clean up lint and adopt project JSDoc style

Author: jeremyfelt

README.md

@@ -53,17 +53,16 @@ self-ignored `.reglance/` directory — nothing to add to `.gitignore`.
 | `output`            | no       | Output directory. Defaults to `.reglance`.                                         |
 | `pixelmatchOptions` | no       | [pixelmatch](https://github.com/mapbox/pixelmatch) options, e.g. `{ "threshold": 0.1 }`. |
 | `timeouts`          | no       | `{ goto, settle }` in ms. `goto` bounds navigation; `settle` bounds each post-scroll wait (network idle, then image load/decode). Defaults `{ goto: 15000, settle: 8000 }`. Raise `settle` for slow, lazy-loading pages. |
-| `blockHosts`        | no       | Hostnames to block requests to during capture, e.g. `["challenges.cloudflare.com"]`. Each entry also blocks its subdomains. |
+| `blockHosts`        | no       | Hostnames to block requests to during capture, e.g. `["captcha.example.com"]`. Each entry also blocks its subdomains. |
 
 `domain` is only needed by `capture`; `control` and `compare` work on the files
 already captured. See [`reglance.example.json`](reglance.example.json) for a full
 example.
 
 `blockHosts` aborts every request to the listed hosts (and their subdomains)
 before it leaves the browser. Use it for third-party embeds that keep the
-network busy and stall capture — CAPTCHA widgets like Cloudflare Turnstile,
-ad tech, analytics — or that render differently on every load and pollute
-diffs. Captures wait for the network to go idle, so a widget that polls or
+network busy and stall capture — CAPTCHA widgets, ad tech, analytics — or
+that render differently on every load and pollute diffs. Captures wait for the network to go idle, so a widget that polls or
 retries indefinitely will otherwise time out every viewport on pages that
 embed it. Entries are bare hostnames; `"example.org"` blocks `example.org` and
 `sub.example.org` alike.

eslint.config.mjs

@@ -1,3 +1,28 @@
 import config from '@happyprime/eslint-config';
 
-export default [...config];
+export default [
+	...config,
+	{
+		// reglance is a CLI: console.log/warn ARE its user-facing output, so
+		// only the noisier debugging methods (debug, info, table, …) stay
+		// flagged. Templates ship to the browser and keep the shared rule.
+		files: ['bin/**/*.mjs', 'src/**/*.mjs'],
+		rules: {
+			'no-console': ['warn', { allow: ['log', 'warn', 'error'] }],
+		},
+	},
+	{
+		// Project style: no hyphen between a JSDoc param name and its
+		// description, with types, names, and descriptions aligned in columns.
+		rules: {
+			'jsdoc/require-hyphen-before-param-description': ['warn', 'never'],
+			// Align params with each other only — a long @returns type would
+			// otherwise drag every description far to the right.
+			'jsdoc/check-line-alignment': [
+				'warn',
+				'always',
+				{ tags: ['param', 'property'] },
+			],
+		},
+	},
+];

reglance.example.json

@@ -21,5 +21,5 @@
 		"goto": 15000,
 		"settle": 8000
 	},
-	"blockHosts": ["challenges.cloudflare.com"]
+	"blockHosts": ["captcha.example.com"]
 }

src/args.mjs

@@ -5,10 +5,10 @@
  * instead of silently truncated, and enforces a minimum so a value like
  * `--concurrency=0` cannot reach the capture loop and hang it.
  *
- * @param {string} value     - The raw flag value.
- * @param {string} name      - The flag name, for error messages.
- * @param {object} [options] - Parse options.
- * @param {number} [options.min] - The smallest allowed value (default 1).
+ * @param {string} value         The raw flag value.
+ * @param {string} name          The flag name, for error messages.
+ * @param {object} [options]     Parse options.
+ * @param {number} [options.min] The smallest allowed value (default 1).
  * @returns {number} The parsed integer.
  */
 export function toInt(value, name, { min = 1 } = {}) {

src/capture.mjs

@@ -7,7 +7,7 @@ import { filterTargets, DEFAULT_TIMEOUTS } from './config.mjs';
  * Whether a host is a local development host, for which self-signed/invalid
  * TLS certificates are expected and certificate errors are ignored by default.
  *
- * @param {string|null} host - The hostname (no port).
+ * @param {string|null} host The hostname (no port).
  * @returns {boolean} True for localhost/loopback and .test/.local(.localhost) hosts.
  */
 export function isLocalHost(host) {
@@ -34,8 +34,8 @@ export function isLocalHost(host) {
  * surfacing it makes off-domain (and potentially internal-network) capture a
  * conscious choice rather than a silent one.
  *
- * @param {Array}       targets - The targets to inspect.
- * @param {string|null} domain  - The configured domain origin.
+ * @param {Array}       targets The targets to inspect.
+ * @param {string|null} domain  The configured domain origin.
  * @returns {Array} Targets pointing at a different host.
  */
 export function offDomainTargets(targets, domain) {
@@ -66,8 +66,8 @@ export function offDomainTargets(targets, domain) {
  * "example.org" blocks both "example.org" and "sub.example.org". Non-network
  * URLs (blob:, data:, chrome-extension:) have no hostname and never match.
  *
- * @param {string}   url        - The request URL.
- * @param {string[]} blockHosts - Normalized (lowercase) hostnames.
+ * @param {string}   url        The request URL.
+ * @param {string[]} blockHosts Normalized (lowercase) hostnames.
  * @returns {boolean} True when the request should be blocked.
  */
 export function isBlockedHost(url, blockHosts) {
@@ -102,7 +102,7 @@ export function isBlockedHost(url, blockHosts) {
  * timing race. The height is re-read every step so content that loads and
  * grows the page extends the walk.
  *
- * @param {import('playwright').Page} page - The page to scroll.
+ * @param {import('playwright').Page} page The page to scroll.
  */
 async function autoScroll(page) {
 	await page.evaluate(async () => {
@@ -137,8 +137,8 @@ async function autoScroll(page) {
  * a broken image rejects, which counts as settled — a missing image is the
  * page's actual state, not something to keep waiting on.
  *
- * @param {import('playwright').Page} page    - The page to wait on.
- * @param {number}                    timeout - Max wait in ms.
+ * @param {import('playwright').Page} page    The page to wait on.
+ * @param {number}                    timeout Max wait in ms.
  * @returns {Promise<number>} How many images were still loading at timeout.
  */
 async function waitForImages(page, timeout) {
@@ -171,7 +171,7 @@ async function waitForImages(page, timeout) {
  * per viewport while still letting setViewportSize switch sizes within a group.
  * A viewport without an explicit deviceScaleFactor defaults to 1.
  *
- * @param {Array} viewports - Viewport definitions.
+ * @param {Array} viewports Viewport definitions.
  * @returns {Array<{ deviceScaleFactor: number, viewports: Array }>} Groups in
  *   first-seen DPR order.
  */
@@ -378,13 +378,13 @@ export function shouldFailRun(failures, failOnDegraded = false) {
 /**
  * Capture screenshots for every configured target.
  *
- * @param {object} config                   The normalized config.
- * @param {object} [options]                Capture options.
- * @param {number} [options.concurrency]    Parallel browser contexts.
- * @param {number} [options.staggerDelay]   Delay (ms) between context starts.
- * @param {boolean}[options.skipReload]     Reuse the page between viewports.
- * @param {boolean}[options.failOnDegraded] Exit non-zero if any capture is degraded.
- * @param {Array}  [options.only]           Limit to these target keys.
+ * @param {object}  config                   The normalized config.
+ * @param {object}  [options]                Capture options.
+ * @param {number}  [options.concurrency]    Parallel browser contexts.
+ * @param {number}  [options.staggerDelay]   Delay (ms) between context starts.
+ * @param {boolean} [options.skipReload]     Reuse the page between viewports.
+ * @param {boolean} [options.failOnDegraded] Exit non-zero if any capture is degraded.
+ * @param {Array}   [options.only]           Limit to these target keys.
  * @returns {Promise<{ failures: Array }>} The degraded-slug records.
  */
 export async function capture(config, options = {}) {

src/compare.mjs

@@ -24,8 +24,8 @@ const HTML_DIFF_MAX_BYTES = 2 * 1024 * 1024;
  * Write a comparison artifact, surfacing the path and error code on failure
  * (e.g. a full disk or a read-only output dir) instead of an opaque stack.
  *
- * @param {string}        file - The destination path.
- * @param {string|Buffer} data - The contents to write.
+ * @param {string}        file The destination path.
+ * @param {string|Buffer} data The contents to write.
  */
 function writeArtifact(file, data) {
 	try {
@@ -43,9 +43,9 @@ function writeArtifact(file, data) {
  * Returns the image unchanged when it already matches the target dimensions,
  * avoiding a needless full-buffer copy.
  *
- * @param {PNG}    img         - The image to pad.
- * @param {number} targetWidth  - The desired width.
- * @param {number} targetHeight - The desired height.
+ * @param {PNG}    img          The image to pad.
+ * @param {number} targetWidth  The desired width.
+ * @param {number} targetHeight The desired height.
  * @returns {PNG} The padded image (or the original when no padding is needed).
  */
 export function padImage(img, targetWidth, targetHeight) {
@@ -61,9 +61,9 @@ export function padImage(img, targetWidth, targetHeight) {
 /**
  * Compare a single control/capture pair for one target and viewport.
  *
- * @param {object} config   - The normalized config.
- * @param {object} target   - The target ({ key, url }).
- * @param {object} viewport - The viewport definition.
+ * @param {object} config   The normalized config.
+ * @param {object} target   The target ({ key, url }).
+ * @param {object} viewport The viewport definition.
  * @returns {object|null} The comparison result, or null when it can't run.
  */
 export function compareSlug(config, target, viewport) {
@@ -172,8 +172,8 @@ export function compareSlug(config, target, viewport) {
  * Warn when the controls being compared were promoted across more than one
  * `control` run, which means the baseline mixes captures from different times.
  *
- * @param {object} config  - The normalized config.
- * @param {Array}  targets - The targets being compared.
+ * @param {object} config  The normalized config.
+ * @param {Array}  targets The targets being compared.
  */
 function warnOnStaleControls(config, targets) {
 	const slugs = targets.flatMap((target) =>
@@ -202,9 +202,9 @@ function warnOnStaleControls(config, targets) {
  * size (each in-flight comparison holds large RGBA buffers), which is why the
  * concurrency is capped and configurable.
  *
- * @param {object} config      - The normalized config.
- * @param {Array}  jobs        - `{ target, viewport }` work items.
- * @param {number} concurrency - Maximum workers to run at once.
+ * @param {object} config      The normalized config.
+ * @param {Array}  jobs        `{ target, viewport }` work items.
+ * @param {number} concurrency Maximum workers to run at once.
  * @returns {Promise<Array>} The comparison reports (in completion order).
  */
 async function runComparisons(config, jobs, concurrency) {
@@ -265,11 +265,11 @@ async function runComparisons(config, jobs, concurrency) {
 /**
  * Compare every captured target against its control and build the report.
  *
- * @param {object}  config                  - The normalized config.
- * @param {object}  [options]               - Compare options.
- * @param {Array}   [options.only]          - Limit to these target keys.
- * @param {boolean} [options.open]          - Open the report when finished.
- * @param {number}  [options.concurrency]   - Parallel diff workers.
+ * @param {object}  config                The normalized config.
+ * @param {object}  [options]             Compare options.
+ * @param {Array}   [options.only]        Limit to these target keys.
+ * @param {boolean} [options.open]        Open the report when finished.
+ * @param {number}  [options.concurrency] Parallel diff workers.
  */
 export async function compare(config, options = {}) {
 	const { dirs } = config;

src/config.mjs

@@ -36,7 +36,7 @@ export const DEFAULT_TIMEOUTS = { goto: 15000, settle: 8000 };
  * ("https://site.test"), and trailing slashes, returning a consistent
  * origin like "https://site.test".
  *
- * @param {string} domain - The domain to normalize.
+ * @param {string} domain The domain to normalize.
  * @returns {string} The normalized origin.
  */
 export function normalizeDomain(domain) {
@@ -77,8 +77,8 @@ const SAFE_SLUG_PART = /^[a-z0-9][a-z0-9._-]*$/i;
 /**
  * Assert a value is safe to use as part of an output filename.
  *
- * @param {string} value - The value to check.
- * @param {string} kind  - A label for the error message (e.g. "path key").
+ * @param {string} value The value to check.
+ * @param {string} kind  A label for the error message (e.g. "path key").
  */
 function assertSafeSlugPart(value, kind) {
 	if (
@@ -101,8 +101,8 @@ function assertSafeSlugPart(value, kind) {
  * a `.join` TypeError at the very end of a compare run, and a crafted array
  * would be interpolated into the report's CSS.
  *
- * @param {*}      color - The configured color value.
- * @param {string} name  - The option name, for the error message.
+ * @param {*}      color The configured color value.
+ * @param {string} name  The option name, for the error message.
  */
 function validateColor(color, name) {
 	const valid =
@@ -125,7 +125,7 @@ function validateColor(color, name) {
  * setViewportSize() and fails mid-capture with an opaque error, so it is
  * cheaper to catch it up front with an actionable message.
  *
- * @param {Array} viewports - The viewport definitions to validate.
+ * @param {Array} viewports The viewport definitions to validate.
  */
 export function validateViewports(viewports) {
 	if (!Array.isArray(viewports) || viewports.length === 0) {
@@ -192,7 +192,7 @@ export function validateViewports(viewports) {
  * Anything with a scheme, path, or port is rejected up front — silently
  * matching nothing would read as "the block isn't working".
  *
- * @param {*} blockHosts - The raw config value.
+ * @param {*} blockHosts The raw config value.
  * @returns {string[]} Lowercased hostnames with any `*.` prefix removed.
  */
 export function normalizeBlockHosts(blockHosts) {
@@ -203,15 +203,15 @@ export function normalizeBlockHosts(blockHosts) {
 	if (!Array.isArray(blockHosts)) {
 		throw new Error(
 			'❌ Invalid "blockHosts": expected an array of hostnames.\n' +
-				'💡 Use entries like ["challenges.cloudflare.com"].'
+				'💡 Use entries like ["captcha.example.com"].'
 		);
 	}
 
 	return blockHosts.map((entry) => {
 		if (typeof entry !== 'string' || !entry.trim()) {
 			throw new Error(
 				`❌ Invalid "blockHosts" entry ${JSON.stringify(entry)}: expected a non-empty string.\n` +
-					'💡 Use a bare hostname like "challenges.cloudflare.com".'
+					'💡 Use a bare hostname like "captcha.example.com".'
 			);
 		}
 
@@ -220,7 +220,7 @@ export function normalizeBlockHosts(blockHosts) {
 		if (/[/:\s]/.test(host)) {
 			throw new Error(
 				`❌ Invalid "blockHosts" entry ${JSON.stringify(entry)}: expected a bare hostname (no scheme, port, or path).\n` +
-					'💡 Use "challenges.cloudflare.com", not "https://challenges.cloudflare.com/".'
+					'💡 Use "captcha.example.com", not "https://captcha.example.com/".'
 			);
 		}
 
@@ -234,8 +234,8 @@ export function normalizeBlockHosts(blockHosts) {
  * A path that is already an absolute URL is returned untouched so that a
  * config can point individual entries at a different domain.
  *
- * @param {string} domain - The normalized domain origin.
- * @param {string} pathname - The path or absolute URL.
+ * @param {string} domain   The normalized domain origin.
+ * @param {string} pathname The path or absolute URL.
  * @returns {string} The full URL.
  */
 export function buildUrl(domain, pathname) {
@@ -253,8 +253,8 @@ export function buildUrl(domain, pathname) {
  * `control`/`compare` surfaces an actionable error instead of silently
  * doing nothing and printing a success-looking summary.
  *
- * @param {Array}    targets - The configured targets.
- * @param {string[]} [only]  - Path keys to keep. Falsy/empty keeps all.
+ * @param {Array}    targets The configured targets.
+ * @param {string[]} [only]  Path keys to keep. Falsy/empty keeps all.
  * @returns {Array} The filtered targets.
  */
 export function filterTargets(targets, only) {
@@ -277,9 +277,9 @@ export function filterTargets(targets, only) {
 /**
  * Load and normalize a reglance config file.
  *
- * @param {object}  [options]            - Loader options.
- * @param {string}  [options.configPath] - Path to the config file.
- * @param {string}  [options.domain]     - Domain override (e.g. from a flag).
+ * @param {object} [options]            Loader options.
+ * @param {string} [options.configPath] Path to the config file.
+ * @param {string} [options.domain]     Domain override (e.g. from a flag).
  * @returns {object} The normalized config.
  */
 export function loadConfig({ configPath = 'reglance.json', domain } = {}) {
@@ -363,7 +363,7 @@ export function loadConfig({ configPath = 'reglance.json', domain } = {}) {
  * Writes a self-contained .gitignore inside the output directory so that
  * captures, diffs, and reports never get committed to the host project.
  *
- * @param {object} config - The normalized config.
+ * @param {object} config The normalized config.
  */
 export function ensureOutputDir(config) {
 	fs.mkdirSync(config.outputDir, { recursive: true });

src/control.mjs

@@ -13,10 +13,10 @@ import { readManifest, writeManifest } from './manifest.mjs';
  * when a run promotes fewer captures than expected (leaving older controls in
  * place for the rest).
  *
- * @param {object} config         - The normalized config.
- * @param {object} [options]      - Control options.
- * @param {Array}  [options.only] - Limit to these target keys.
- * @param {string} [options.now]  - ISO timestamp override (for tests).
+ * @param {object} config         The normalized config.
+ * @param {object} [options]      Control options.
+ * @param {Array}  [options.only] Limit to these target keys.
+ * @param {string} [options.now]  ISO timestamp override (for tests).
  * @returns {{ moved: number, expected: number }} Promotion counts.
  */
 export function control(config, options = {}) {