--- /dev/null
+/**
+ * @fileoverview enforce or disallow capitalization of the first letter of a comment
+ * @author Kevin Partington
+ */
+"use strict";
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+const LETTER_PATTERN = require("./utils/patterns/letters");
+const astUtils = require("./utils/ast-utils");
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+const DEFAULT_IGNORE_PATTERN = astUtils.COMMENTS_IGNORE_PATTERN,
+ WHITESPACE = /\s/gu,
+ MAYBE_URL = /^\s*[^:/?#\s]+:\/\/[^?#]/u; // TODO: Combine w/ max-len pattern?
+
+/*
+ * Base schema body for defining the basic capitalization rule, ignorePattern,
+ * and ignoreInlineComments values.
+ * This can be used in a few different ways in the actual schema.
+ */
+const SCHEMA_BODY = {
+ type: "object",
+ properties: {
+ ignorePattern: {
+ type: "string"
+ },
+ ignoreInlineComments: {
+ type: "boolean"
+ },
+ ignoreConsecutiveComments: {
+ type: "boolean"
+ }
+ },
+ additionalProperties: false
+};
+const DEFAULTS = {
+ ignorePattern: "",
+ ignoreInlineComments: false,
+ ignoreConsecutiveComments: false
+};
+
+/**
+ * Get normalized options for either block or line comments from the given
+ * user-provided options.
+ * - If the user-provided options is just a string, returns a normalized
+ * set of options using default values for all other options.
+ * - If the user-provided options is an object, then a normalized option
+ * set is returned. Options specified in overrides will take priority
+ * over options specified in the main options object, which will in
+ * turn take priority over the rule's defaults.
+ * @param {Object|string} rawOptions The user-provided options.
+ * @param {string} which Either "line" or "block".
+ * @returns {Object} The normalized options.
+ */
+function getNormalizedOptions(rawOptions, which) {
+ return Object.assign({}, DEFAULTS, rawOptions[which] || rawOptions);
+}
+
+/**
+ * Get normalized options for block and line comments.
+ * @param {Object|string} rawOptions The user-provided options.
+ * @returns {Object} An object with "Line" and "Block" keys and corresponding
+ * normalized options objects.
+ */
+function getAllNormalizedOptions(rawOptions = {}) {
+ return {
+ Line: getNormalizedOptions(rawOptions, "line"),
+ Block: getNormalizedOptions(rawOptions, "block")
+ };
+}
+
+/**
+ * Creates a regular expression for each ignorePattern defined in the rule
+ * options.
+ *
+ * This is done in order to avoid invoking the RegExp constructor repeatedly.
+ * @param {Object} normalizedOptions The normalized rule options.
+ * @returns {void}
+ */
+function createRegExpForIgnorePatterns(normalizedOptions) {
+ Object.keys(normalizedOptions).forEach(key => {
+ const ignorePatternStr = normalizedOptions[key].ignorePattern;
+
+ if (ignorePatternStr) {
+ const regExp = RegExp(`^\\s*(?:${ignorePatternStr})`, "u");
+
+ normalizedOptions[key].ignorePatternRegExp = regExp;
+ }
+ });
+}
+
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+
+module.exports = {
+ meta: {
+ type: "suggestion",
+
+ docs: {
+ description: "enforce or disallow capitalization of the first letter of a comment",
+ category: "Stylistic Issues",
+ recommended: false,
+ url: "https://eslint.org/docs/rules/capitalized-comments"
+ },
+
+ fixable: "code",
+
+ schema: [
+ { enum: ["always", "never"] },
+ {
+ oneOf: [
+ SCHEMA_BODY,
+ {
+ type: "object",
+ properties: {
+ line: SCHEMA_BODY,
+ block: SCHEMA_BODY
+ },
+ additionalProperties: false
+ }
+ ]
+ }
+ ],
+
+ messages: {
+ unexpectedLowercaseComment: "Comments should not begin with a lowercase character.",
+ unexpectedUppercaseComment: "Comments should not begin with an uppercase character."
+ }
+ },
+
+ create(context) {
+
+ const capitalize = context.options[0] || "always",
+ normalizedOptions = getAllNormalizedOptions(context.options[1]),
+ sourceCode = context.getSourceCode();
+
+ createRegExpForIgnorePatterns(normalizedOptions);
+
+ //----------------------------------------------------------------------
+ // Helpers
+ //----------------------------------------------------------------------
+
+ /**
+ * Checks whether a comment is an inline comment.
+ *
+ * For the purpose of this rule, a comment is inline if:
+ * 1. The comment is preceded by a token on the same line; and
+ * 2. The command is followed by a token on the same line.
+ *
+ * Note that the comment itself need not be single-line!
+ *
+ * Also, it follows from this definition that only block comments can
+ * be considered as possibly inline. This is because line comments
+ * would consume any following tokens on the same line as the comment.
+ * @param {ASTNode} comment The comment node to check.
+ * @returns {boolean} True if the comment is an inline comment, false
+ * otherwise.
+ */
+ function isInlineComment(comment) {
+ const previousToken = sourceCode.getTokenBefore(comment, { includeComments: true }),
+ nextToken = sourceCode.getTokenAfter(comment, { includeComments: true });
+
+ return Boolean(
+ previousToken &&
+ nextToken &&
+ comment.loc.start.line === previousToken.loc.end.line &&
+ comment.loc.end.line === nextToken.loc.start.line
+ );
+ }
+
+ /**
+ * Determine if a comment follows another comment.
+ * @param {ASTNode} comment The comment to check.
+ * @returns {boolean} True if the comment follows a valid comment.
+ */
+ function isConsecutiveComment(comment) {
+ const previousTokenOrComment = sourceCode.getTokenBefore(comment, { includeComments: true });
+
+ return Boolean(
+ previousTokenOrComment &&
+ ["Block", "Line"].indexOf(previousTokenOrComment.type) !== -1
+ );
+ }
+
+ /**
+ * Check a comment to determine if it is valid for this rule.
+ * @param {ASTNode} comment The comment node to process.
+ * @param {Object} options The options for checking this comment.
+ * @returns {boolean} True if the comment is valid, false otherwise.
+ */
+ function isCommentValid(comment, options) {
+
+ // 1. Check for default ignore pattern.
+ if (DEFAULT_IGNORE_PATTERN.test(comment.value)) {
+ return true;
+ }
+
+ // 2. Check for custom ignore pattern.
+ const commentWithoutAsterisks = comment.value
+ .replace(/\*/gu, "");
+
+ if (options.ignorePatternRegExp && options.ignorePatternRegExp.test(commentWithoutAsterisks)) {
+ return true;
+ }
+
+ // 3. Check for inline comments.
+ if (options.ignoreInlineComments && isInlineComment(comment)) {
+ return true;
+ }
+
+ // 4. Is this a consecutive comment (and are we tolerating those)?
+ if (options.ignoreConsecutiveComments && isConsecutiveComment(comment)) {
+ return true;
+ }
+
+ // 5. Does the comment start with a possible URL?
+ if (MAYBE_URL.test(commentWithoutAsterisks)) {
+ return true;
+ }
+
+ // 6. Is the initial word character a letter?
+ const commentWordCharsOnly = commentWithoutAsterisks
+ .replace(WHITESPACE, "");
+
+ if (commentWordCharsOnly.length === 0) {
+ return true;
+ }
+
+ const firstWordChar = commentWordCharsOnly[0];
+
+ if (!LETTER_PATTERN.test(firstWordChar)) {
+ return true;
+ }
+
+ // 7. Check the case of the initial word character.
+ const isUppercase = firstWordChar !== firstWordChar.toLocaleLowerCase(),
+ isLowercase = firstWordChar !== firstWordChar.toLocaleUpperCase();
+
+ if (capitalize === "always" && isLowercase) {
+ return false;
+ }
+ if (capitalize === "never" && isUppercase) {
+ return false;
+ }
+
+ return true;
+ }
+
+ /**
+ * Process a comment to determine if it needs to be reported.
+ * @param {ASTNode} comment The comment node to process.
+ * @returns {void}
+ */
+ function processComment(comment) {
+ const options = normalizedOptions[comment.type],
+ commentValid = isCommentValid(comment, options);
+
+ if (!commentValid) {
+ const messageId = capitalize === "always"
+ ? "unexpectedLowercaseComment"
+ : "unexpectedUppercaseComment";
+
+ context.report({
+ node: null, // Intentionally using loc instead
+ loc: comment.loc,
+ messageId,
+ fix(fixer) {
+ const match = comment.value.match(LETTER_PATTERN);
+
+ return fixer.replaceTextRange(
+
+ // Offset match.index by 2 to account for the first 2 characters that start the comment (// or /*)
+ [comment.range[0] + match.index + 2, comment.range[0] + match.index + 3],
+ capitalize === "always" ? match[0].toLocaleUpperCase() : match[0].toLocaleLowerCase()
+ );
+ }
+ });
+ }
+ }
+
+ //----------------------------------------------------------------------
+ // Public
+ //----------------------------------------------------------------------
+
+ return {
+ Program() {
+ const comments = sourceCode.getAllComments();
+
+ comments.filter(token => token.type !== "Shebang").forEach(processComment);
+ }
+ };
+ }
+};
projects / dotfiles / .git / blobdiff