1.4.0

Author: [Interfaced] Кирилл Дронкин

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change log
 
+## 1.4.0 (release date: 9.10.2018)
+
+* Preserve the head and the tail of a JSDoc
+* `jsdoc-type-spacing`: don't crash on an one-symbol token
+* New rule: `jsdoc-type-indent`
+
 ## 1.3.0 (release date: 28.09.2018)
 
 * `jsdoc-type-spacing`: tolerate multiline types

README.md

@@ -41,6 +41,7 @@ npm i eslint-plugin-interfaced --save-dev
 * [interfaced/interface-name-prefix](docs/rules/interface-name-prefix.md)
 * [interfaced/jsdoc-tags-order](docs/rules/jsdoc-tags-order.md)
 * [interfaced/jsdoc-type-application-dot](docs/rules/jsdoc-type-application-dot.md)
+* [interfaced/jsdoc-type-indent](docs/rules/jsdoc-type-indent.md)
 * [interfaced/jsdoc-type-spacing](docs/rules/jsdoc-type-spacing.md)
 * [interfaced/lines-around-class](docs/rules/lines-around-class.md)
 * [interfaced/lines-between-methods](docs/rules/lines-between-methods.md)

docs/rules/jsdoc-type-indent.md

@@ -0,0 +1,14 @@
+# interfaced/jsdoc-type-indent
+
+Enforce consistent indentation in JSDocs.
+
+**Fixable:** this rule is automatically fixable by `--fix`.
+
+## Options
+
+The rule accepts either `'tab'` for tabbed indentation or an integer for spaced indentation. The default value is `2` (2-space indentation).
+
+## Resources
+
+* [Source](../../lib/rules/jsdoc-type-indent.js)
+* [Tests](../../test/eslint/rules/jsdoc-type-indent.js)

index.js

@@ -14,6 +14,7 @@ module.exports.rules = {
 	'interface-name-prefix': require('./lib/rules/interface-name-prefix'),
 	'jsdoc-tags-order': require('./lib/rules/jsdoc-tags-order'),
 	'jsdoc-type-application-dot': require('./lib/rules/jsdoc-type-application-dot'),
+	'jsdoc-type-indent': require('./lib/rules/jsdoc-type-indent'),
 	'jsdoc-type-spacing': require('./lib/rules/jsdoc-type-spacing'),
 	'lines-around-class': require('./lib/rules/lines-around-class'),
 	'lines-between-methods': require('./lib/rules/lines-between-methods'),

lib/ast-utils.js

@@ -1,10 +1,15 @@
 const doctrine = require('doctrine');
 const JSDocTokenizer = require('./jsdoc-tokenizer');
 
-const JSDocTypeTokenizer = new JSDocTokenizer({
-	type: true,
-	range: true
-});
+const JSDocTokenizers = {
+	default: new JSDocTokenizer({
+		range: true
+	}),
+	type: new JSDocTokenizer({
+		type: true,
+		range: true
+	})
+};
 
 /**
  * @param {ASTNode} node
@@ -282,7 +287,8 @@ function parseJSDoc(comment) {
 		return null;
 	}
 
-	const content = doctrine.unwrapComment(comment.value);
+	const content = doctrine.unwrapComment(comment.value)
+		.replace(/^\s*/, ''); // Remove heading whitespace
 
 	let JSDoc = null;
 	try {
@@ -373,7 +379,7 @@ function getJSDocTypeContent(JSDoc, type) {
  * @return {Array<JSDocTokenWithRange>}
  */
 function getJSDocTagTokens(JSDoc, tag) {
-	return JSDocTypeTokenizer.tokenize(JSDoc.content.slice(...tag.range))
+	return JSDocTokenizers.default.tokenize(JSDoc.content.slice(...tag.range))
 		.map((token) => {
 			token.range[0] += tag.range[0];
 			token.range[1] += tag.range[0];
@@ -388,7 +394,7 @@ function getJSDocTagTokens(JSDoc, tag) {
  * @return {Array<JSDocTokenWithRange>}
  */
 function getJSDocTypeTokens(JSDoc, type) {
-	return JSDocTypeTokenizer.tokenize(JSDoc.content.slice(...type.range))
+	return JSDocTokenizers.type.tokenize(JSDoc.content.slice(...type.range))
 		.map((token) => {
 			token.range[0] += type.range[0];
 			token.range[1] += type.range[0];
@@ -427,6 +433,53 @@ function getJSDocTokenAfter(tokens, targetToken) {
 	return tokens.find((token) => token.range[0] === targetToken.range[1]) || null;
 }
 
+/**
+ * @param {Array<JSDocTokenWithRange>} tokens
+ * @param {JSDocTokenWithRange} tokenA
+ * @param {JSDocTokenWithRange} tokenB
+ * @return {Array<JSDocTokenWithRange>}
+ */
+function getJSDocTokensBetween(tokens, tokenA, tokenB) {
+	const tokensBetween = [];
+
+	let cursor = tokenA;
+	while (cursor) {
+		cursor = getJSDocTokenAfter(tokens, cursor);
+
+		if (!cursor || cursor.range[0] === tokenB.range[0]) {
+			break;
+		}
+
+		tokensBetween.push(cursor);
+	}
+
+	return tokensBetween;
+}
+
+/**
+ * @param {Array<JSDocTokenWithRange>} tokens
+ * @param {{
+ *     type: (string|undefined),
+ *     value: (string|undefined)
+ * }=} options
+ * @return {?JSDocTokenWithRange}
+ */
+function findFirstJSDocToken(tokens, {type, value}) {
+	return tokens.find((token) => (!type || token.type === type) && (!value || token.value === value)) || null;
+}
+
+/**
+ * @param {Array<JSDocTokenWithRange>} tokens
+ * @param {{
+ *     type: (string|undefined),
+ *     value: (string|undefined)
+ * }=} options
+ * @return {?JSDocTokenWithRange}
+ */
+function findLastJSDocToken(tokens, {type, value}) {
+	return findFirstJSDocToken(tokens.slice().reverse(), {type, value});
+}
+
 /**
  * @param {Array<JSDocTokenWithRange>} tokens
  * @param {JSDocTokenWithRange} token
@@ -438,26 +491,22 @@ function getJSDocTokenAfter(tokens, targetToken) {
  * @return {?JSDocTokenWithRange}
  */
 function findNonWhitespaceSiblingJSDocToken(tokens, token, {type, value, moveForward = true} = {}) {
-	let currentToken = token;
-
-	while (currentToken) {
-		currentToken = moveForward ?
-			getJSDocTokenAfter(tokens, currentToken) :
-			getJSDocTokenBefore(tokens, currentToken);
+	let cursor = token;
+	while (cursor) {
+		cursor = moveForward ?
+			getJSDocTokenAfter(tokens, cursor) :
+			getJSDocTokenBefore(tokens, cursor);
 
-		if (!currentToken) {
+		if (!cursor) {
 			return null;
 		}
 
-		if (currentToken.type === 'Whitespace') {
+		if (cursor.type === 'Whitespace') {
 			continue;
 		}
 
-		if (
-			(!type || currentToken.type === type) &&
-			(!value || currentToken.value === value)
-		) {
-			return currentToken;
+		if ((!type || cursor.type === type) && (!value || cursor.value === value)) {
+			return cursor;
 		}
 
 		return null;
@@ -589,8 +638,11 @@ module.exports = {
 	getJSDocSubtypeTokens,
 	getJSDocTokenBefore,
 	getJSDocTokenAfter,
+	getJSDocTokensBetween,
 	getScopeFromJSDoc,
 	getStaticTypeFromJSDoc,
+	findFirstJSDocToken,
+	findLastJSDocToken,
 	findNonWhitespaceSiblingJSDocToken,
 	traverseJSDocType
 };

lib/rules/event-const-desc.js

@@ -1,5 +1,6 @@
 const {visitConstantExpressions} = require('../visitors');
 const {getJSDocDescription, resolveConstantName} = require('../ast-utils');
+const {LINE_BREAK_MATCHER} = require('../utils');
 
 module.exports = {
 	meta: {
@@ -19,7 +20,7 @@ module.exports = {
 			if (constantName.startsWith('EVENT_')) {
 				const description = getJSDocDescription(constantExpression, sourceCode);
 
-				if (!description.split('\n').some((line) => line.startsWith('Fired with:'))) {
+				if (!description.split(LINE_BREAK_MATCHER).some((line) => line.startsWith('Fired with:'))) {
 					context.report({
 						node: constantExpression,
 						message: `Event constant "${constantName}" has no "Fired with: ..." description.`