Refactor to more specific function types

lib/utils/checkAgainstRule.js

@@ -14,10 +14,10 @@ const rules = require('../rules');
 		ruleSettings: import('stylelint').StylelintConfigRuleSettings<T, O>,
 		root: import('postcss').Root,
 	}} options
- * @param {Function} callback
+ * @param {(warning: import('postcss').Warning) => void} callback
  * @returns {void}
  */
-module.exports = function (options, callback) {
+module.exports = function checkAgainstRule(options, callback) {
 	if (!options)
 		throw new Error(
 			"checkAgainstRule requires an options object with 'ruleName', 'ruleSettings', and 'root' properties",

lib/utils/eachDeclarationBlock.js

@@ -6,6 +6,8 @@ const { isRoot, isAtRule, isRule } = require('./typeGuards');
 /** @typedef {import('postcss').Root} Document */
 /** @typedef {import('postcss').Node} PostcssNode */
 /** @typedef {import('postcss').Container} PostcssContainerNode */
+/** @typedef {import('postcss').Declaration} Declaration */
+/** @typedef {(callbackFn: (decl: Declaration, index: number, decls: Declaration[]) => void) => void} EachDeclaration */
 
 /**
  * @param {PostcssNode} node
@@ -24,11 +26,11 @@ function isContainerNode(node) {
  * executes a provided function once for each declaration block.
  *
  * @param {Root | Document} root - root element of file.
- * @param {function} cb - Function to execute for each declaration block
+ * @param {(eachDecl: EachDeclaration) => void} callback - Function to execute for each declaration block
  *
  * @returns {void}
  */
-module.exports = function (root, cb) {
+module.exports = function eachDeclarationBlock(root, callback) {
 	/**
 	 * @param {PostcssNode} statement
 	 *
@@ -38,7 +40,7 @@ module.exports = function (root, cb) {
 		if (!isContainerNode(statement)) return;
 
 		if (statement.nodes && statement.nodes.length) {
-			/** @type {PostcssNode[]} */
+			/** @type {Declaration[]} */
 			const decls = [];
 
 			statement.nodes.forEach((node) => {
@@ -50,7 +52,7 @@ module.exports = function (root, cb) {
 			});
 
 			if (decls.length) {
-				cb(decls.forEach.bind(decls));
+				callback(decls.forEach.bind(decls));
 			}
 		}
 	}

lib/utils/functionArgumentsSearch.js

@@ -15,9 +15,9 @@ const styleSearch = require('style-search');
  *
  * @param {string} source
  * @param {string} functionName
- * @param {Function} callback
+ * @param {(expression: string, expressionIndex: number) => void} callback
  */
-module.exports = function (source, functionName, callback) {
+module.exports = function functionArgumentsSearch(source, functionName, callback) {
 	styleSearch(
 		{
 			source,

lib/utils/parseSelector.js

@@ -6,12 +6,11 @@ const selectorParser = require('postcss-selector-parser');
  * @param {string} selector
  * @param {import('stylelint').PostcssResult} result
  * @param {import('postcss').Node} node
- * @param {Function} cb
+ * @param {(root: import('postcss-selector-parser').Root) => void} callback
  */
-module.exports = function parseSelector(selector, result, node, cb) {
+module.exports = function parseSelector(selector, result, node, callback) {
 	try {
-		// @ts-ignore TODO TYPES wrong postcss-selector-parser types
-		return selectorParser(cb).processSync(selector);
+		return selectorParser(callback).processSync(selector);
 	} catch {
 		result.warn('Cannot parse selector', { node, stylelintType: 'parseError' });
 	}

lib/utils/ruleMessages.js

@@ -1,35 +1,28 @@
 'use strict';
 
+/** @typedef {(...args: any[]) => string} MessageGenerator */
+/** @typedef {Record<string, string | MessageGenerator>} Messages */
+
 /**
  * Given an object of violation messages, return another
  * that provides the same messages postfixed with the rule
  * that has been violated.
  *
  * @param {string} ruleName
- * @param {{[k: string]: string|Function}} messages - Object whose keys are message identifiers
+ * @param {Messages} messages - Object whose keys are message identifiers
  *   and values are either message strings or functions that return message strings
- * @return {{[k: string]: string|Function}} New message object, whose messages will be marked with the rule name
+ * @returns {Messages} New message object, whose messages will be marked with the rule name
  */
-module.exports = function (ruleName, messages) {
-	return Object.keys(messages).reduce(
-		/**
-		 * @param {{[k: string]: string|Function}} newMessages
-		 * @param {string} messageId
-		 * @return {{[k: string]: string|Function}}
-		 */
-		(newMessages, messageId) => {
-			const messageText = messages[messageId];
+module.exports = function ruleMessages(ruleName, messages) {
+	return Object.keys(messages).reduce((/** @type {Messages} */ newMessages, messageId) => {
+		const messageText = messages[messageId];
 
-			if (typeof messageText === 'string') {
-				newMessages[messageId] = `${messageText} (${ruleName})`;
-			} else {
-				newMessages[messageId] = (/** @type {any[]} */ ...args) => {
-					return `${messageText(...args)} (${ruleName})`;
-				};
-			}
+		if (typeof messageText === 'string') {
+			newMessages[messageId] = `${messageText} (${ruleName})`;
+		} else {
+			newMessages[messageId] = (...args) => `${messageText(...args)} (${ruleName})`;
+		}
 
-			return newMessages;
-		},
-		{},
-	);
+		return newMessages;
+	}, {});
 };

lib/utils/transformSelector.js

@@ -4,13 +4,12 @@ const selectorParser = require('postcss-selector-parser');
 
 /**
  * @param {import('stylelint').PostcssResult} result
- * @param {import('postcss').Node} node
- * @param {Function} cb
+ * @param {import('postcss').Rule} node
+ * @param {(root: import('postcss-selector-parser').Root) => void} callback
  */
-module.exports = function (result, node, cb) {
+module.exports = function transformSelector(result, node, callback) {
 	try {
-		// @ts-ignore TODO TYPES wrong postcss-selector-parser definitions
-		return selectorParser(cb).processSync(node, { updateSelector: true });
+		return selectorParser(callback).processSync(node, { updateSelector: true });
 	} catch {
 		result.warn('Cannot parse selector', { node, stylelintType: 'parseError' });
 	}