Add types for assignDisabledRanges.js (#4354)

* add types to assignDisabledRanges * add @types/lodash and types for stylelint
stylelint · Oct 15, 2019 · 94c7a28 · 94c7a28
1 parent 97809b3
commit 94c7a28
Show file tree

Hide file tree

Showing 4 changed files with 144 additions and 20 deletions.
diff --git a/lib/assignDisabledRanges.js b/lib/assignDisabledRanges.js
@@ -22,6 +22,19 @@ const ALL_RULES = 'all';
   [ruleName: string]: Array<disableRange>
 }*/
 
+/** @typedef {import('postcss').Comment} PostcssComment */
+/** @typedef {import('postcss').Root} PostcssRoot */
+/** @typedef {import('stylelint').PostcssResult} PostcssResult */
+/** @typedef {import('stylelint').DisabledRangeObject} DisabledRangeObject */
+/** @typedef {import('stylelint').DisabledRange} DisabledRange */
+
+/**
+ * @param {number} start
+ * @param {boolean} strictStart
+ * @param {number} [end]
+ * @param {boolean} [strictEnd]
+ * @returns {DisabledRange}
+ */
 function createDisableRange(
 	start /*: number*/,
 	strictStart /*: boolean*/,
@@ -36,12 +49,23 @@ function createDisableRange(
 	};
 }
 
-// Run it like a plugin ...
+/**
+ * Run it like a plugin ...
+ * @param {PostcssRoot} root
+ * @param {PostcssResult} result
+ * @returns {PostcssResult}
+ */
 module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$result*/ {
-	result.stylelint = result.stylelint || {};
+	result.stylelint = result.stylelint || {
+		disabledRanges: {},
+		ruleSeverities: {},
+		customMessages: {},
+	};
 
-	// Most of the functions below work via side effects mutating
-	// this object
+	/**
+	 * Most of the functions below work via side effects mutating this object
+	 * @type {DisabledRangeObject}
+	 */
 	const disabledRanges /*: disabledRangeObject*/ = {
 		all: [],
 	};
@@ -51,18 +75,37 @@ module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$re
 
 	return result;
 
+	/**
+	 * @param {PostcssComment} comment
+	 */
 	function processDisableLineCommand(comment /*: postcss$comment*/) {
-		getCommandRules(disableLineCommand, comment.text).forEach((ruleName) => {
-			disableLine(comment.source.start.line, ruleName, comment);
-		});
+		if (comment.source && comment.source.start) {
+			const line = comment.source.start.line;
+
+			getCommandRules(disableLineCommand, comment.text).forEach((ruleName) => {
+				disableLine(line, ruleName, comment);
+			});
+		}
 	}
 
+	/**
+	 * @param {PostcssComment} comment
+	 */
 	function processDisableNextLineCommand(comment /*: postcss$comment*/) {
-		getCommandRules(disableNextLineCommand, comment.text).forEach((ruleName) => {
-			disableLine(comment.source.start.line + 1, ruleName, comment);
-		});
+		if (comment.source && comment.source.start) {
+			const line = comment.source.start.line;
+
+			getCommandRules(disableNextLineCommand, comment.text).forEach((ruleName) => {
+				disableLine(line + 1, ruleName, comment);
+			});
+		}
 	}
 
+	/**
+	 * @param {number} line
+	 * @param {string} ruleName
+	 * @param {PostcssComment} comment
+	 */
 	function disableLine(line /*: number*/, ruleName /*: string*/, comment /*: postcss$comment*/) {
 		if (ruleIsDisabled(ALL_RULES)) {
 			throw comment.error('All rules have already been disabled', {
@@ -89,6 +132,9 @@ module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$re
 		}
 	}
 
+	/**
+	 * @param {PostcssComment} comment
+	 */
 	function processDisableCommand(comment /*: postcss$comment*/) {
 		getCommandRules(disableCommand, comment.text).forEach((ruleToDisable) => {
 			const isAllRules = ruleToDisable === ALL_RULES;
@@ -104,19 +150,32 @@ module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$re
 				);
 			}
 
-			if (isAllRules) {
-				Object.keys(disabledRanges).forEach((ruleName) => {
-					startDisabledRange(comment.source.start.line, ruleName, ruleName === ALL_RULES);
-				});
-			} else {
-				startDisabledRange(comment.source.start.line, ruleToDisable, true);
+			if (comment.source && comment.source.start) {
+				const line = comment.source.start.line;
+
+				if (isAllRules) {
+					Object.keys(disabledRanges).forEach((ruleName) => {
+						startDisabledRange(line, ruleName, ruleName === ALL_RULES);
+					});
+				} else {
+					startDisabledRange(line, ruleToDisable, true);
+				}
 			}
 		});
 	}
 
+	/**
+	 * @param {PostcssComment} comment
+	 */
 	function processEnableCommand(comment /*: postcss$comment*/) {
 		getCommandRules(enableCommand, comment.text).forEach((ruleToEnable) => {
+			// TODO TYPES
+			// need fallback if endLine will be undefined
+			const endLine =
+				/** @type {number} */ (comment.source && comment.source.end && comment.source.end.line);
+
 			if (ruleToEnable === ALL_RULES) {
+				// @ts-ignore https://github.com/stylelint/stylelint/issues/4328
 				if (_.values(disabledRanges).every((ranges) => _.isEmpty(ranges) || !!_.last(ranges.end))) {
 					throw comment.error('No rules have been disabled', {
 						plugin: 'stylelint',
@@ -125,7 +184,7 @@ module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$re
 
 				Object.keys(disabledRanges).forEach((ruleName) => {
 					if (!_.get(_.last(disabledRanges[ruleName]), 'end')) {
-						endDisabledRange(comment.source.end.line, ruleName, ruleName === ALL_RULES);
+						endDisabledRange(endLine, ruleName, ruleName === ALL_RULES);
 					}
 				});
 
@@ -139,16 +198,20 @@ module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$re
 						createDisableRange(start, false, end, false),
 					);
 				} else {
-					disabledRanges[ruleToEnable].push(_.clone(_.last(disabledRanges[ALL_RULES])));
+					const range = _.clone(_.last(disabledRanges[ALL_RULES]));
+
+					if (range) {
+						disabledRanges[ruleToEnable].push(range);
+					}
 				}
 
-				endDisabledRange(comment.source.end.line, ruleToEnable, true);
+				endDisabledRange(endLine, ruleToEnable, true);
 
 				return;
 			}
 
 			if (ruleIsDisabled(ruleToEnable)) {
-				endDisabledRange(comment.source.end.line, ruleToEnable, true);
+				endDisabledRange(endLine, ruleToEnable, true);
 
 				return;
 			}
@@ -159,6 +222,9 @@ module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$re
 		});
 	}
 
+	/**
+	 * @param {PostcssComment} comment
+	 */
 	function checkComment(comment /*: postcss$comment*/) {
 		const text = comment.text;
 
@@ -179,6 +245,11 @@ module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$re
 		}
 	}
 
+	/**
+	 * @param {string} command
+	 * @param {string} fullText
+	 * @returns {string[]}
+	 */
 	function getCommandRules(command /*: string*/, fullText /*: string*/) /*: Array<string>*/ {
 		const rules = _.compact(fullText.slice(command.length).split(',')).map((r) => r.trim());
 
@@ -189,13 +260,23 @@ module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$re
 		return rules;
 	}
 
+	/**
+	 * @param {number} line
+	 * @param {string} ruleName
+	 * @param {boolean} strict
+	 */
 	function startDisabledRange(line /*: number*/, ruleName /*: string*/, strict /*: boolean*/) {
 		const rangeObj = createDisableRange(line, strict);
 
 		ensureRuleRanges(ruleName);
 		disabledRanges[ruleName].push(rangeObj);
 	}
 
+	/**
+	 * @param {number} line
+	 * @param {string} ruleName
+	 * @param {boolean} strict
+	 */
 	function endDisabledRange(line /*: number*/, ruleName /*: string*/, strict /*: boolean*/) {
 		const lastRangeForRule = _.last(disabledRanges[ruleName]);
 
@@ -208,6 +289,9 @@ module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$re
 		lastRangeForRule.strictEnd = strict;
 	}
 
+	/**
+	 * @param {string} ruleName
+	 */
 	function ensureRuleRanges(ruleName /*: string*/) {
 		if (!disabledRanges[ruleName]) {
 			disabledRanges[ruleName] = disabledRanges.all.map(({ start, end }) =>
@@ -216,6 +300,10 @@ module.exports = function(root /*: Object*/, result /*: Object*/) /*: postcss$re
 		}
 	}
 
+	/**
+	 * @param {string} ruleName
+	 * @returns {boolean}
+	 */
 	function ruleIsDisabled(ruleName /*: string*/) /*: boolean*/ {
 		if (disabledRanges[ruleName] === undefined) return false;
 

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -90,6 +90,7 @@
     "v8-compile-cache": "^2.1.0"
   },
   "devDependencies": {
+    "@types/lodash": "^4.14.144",
     "benchmark": "^2.1.4",
     "common-tags": "^1.8.0",
     "coveralls": "^3.0.7",

diff --git a/types/stylelint/index.d.ts b/types/stylelint/index.d.ts
@@ -0,0 +1,29 @@
+declare module 'stylelint' {
+	import { Result, WarningOptions } from 'postcss';
+
+	export type DisabledRange = {
+		start: number,
+		strictStart: boolean,
+		end?: number,
+		strictEnd?: boolean
+	};
+
+	export type DisabledRangeObject = {
+		[ruleName: string]: Array<DisabledRange>
+	};
+
+	export type StylelintPostcssResult = {
+		ruleSeverities: {[k: string]: any},
+		customMessages: {[k: string]: any},
+		quiet?: boolean,
+		disabledRanges: DisabledRangeObject,
+		ignored?: boolean,
+		ignoreDisables?: boolean,
+		stylelintError?: boolean
+	};
+
+	export type PostcssResult = Result & {
+		stylelint: StylelintPostcssResult,
+		warn(message: string, options?: WarningOptions & {stylelintType?: string}): void;
+	};
+}