.config/coc/extensions/node_modules/coc-prettier/node_modules/tslint/lib/rules/jsdocFormatRule.js

   1 "use strict";
   2 /**
   3  * @license
   4  * Copyright 2013 Palantir Technologies, Inc.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18 Object.defineProperty(exports, "__esModule", { value: true });
  19 var tslib_1 = require("tslib");
  20 var utils = require("tsutils");
  21 var ts = require("typescript");
  22 var Lint = require("../index");
  23 var OPTION_CHECK_MULTILINE_START = "check-multiline-start";
  24 var Rule = /** @class */ (function (_super) {
  25     tslib_1.__extends(Rule, _super);
  26     function Rule() {
  27         return _super !== null && _super.apply(this, arguments) || this;
  28     }
  29     Rule.prototype.apply = function (sourceFile) {
  30         return this.applyWithFunction(sourceFile, walk, {
  31             firstLineOfMultiline: this.ruleArguments.indexOf(OPTION_CHECK_MULTILINE_START) !== -1,
  32         });
  33     };
  34     /* tslint:disable:object-literal-sort-keys */
  35     Rule.metadata = {
  36         ruleName: "jsdoc-format",
  37         description: "Enforces basic format rules for JSDoc comments.",
  38         descriptionDetails: Lint.Utils.dedent(templateObject_1 || (templateObject_1 = tslib_1.__makeTemplateObject(["\n            The following rules are enforced for JSDoc comments (comments starting with `/**`):\n\n            * each line contains an asterisk and asterisks must be aligned\n            * each asterisk must be followed by either a space or a newline (except for the first and the last)\n            * the only characters before the asterisk on each line must be whitespace characters\n            * one line comments must start with `/** ` and end with `*/`\n            * multiline comments don't allow text after `/** ` in the first line (with option `\"", "\"`)\n        "], ["\n            The following rules are enforced for JSDoc comments (comments starting with \\`/**\\`):\n\n            * each line contains an asterisk and asterisks must be aligned\n            * each asterisk must be followed by either a space or a newline (except for the first and the last)\n            * the only characters before the asterisk on each line must be whitespace characters\n            * one line comments must start with \\`/** \\` and end with \\`*/\\`\n            * multiline comments don't allow text after \\`/** \\` in the first line (with option \\`\"", "\"\\`)\n        "])), OPTION_CHECK_MULTILINE_START),
  39         rationale: "Helps maintain a consistent, readable style for JSDoc comments.",
  40         optionsDescription: Lint.Utils.dedent(templateObject_2 || (templateObject_2 = tslib_1.__makeTemplateObject(["\n            You can optionally specify the option `\"", "\"` to enforce the first line of a\n            multiline JSDoc comment to be empty.\n        "], ["\n            You can optionally specify the option \\`\"", "\"\\` to enforce the first line of a\n            multiline JSDoc comment to be empty.\n        "])), OPTION_CHECK_MULTILINE_START),
  41         options: {
  42             type: "array",
  43             minItems: 0,
  44             maxItems: 1,
  45             items: {
  46                 type: "string",
  47                 enum: [OPTION_CHECK_MULTILINE_START],
  48             },
  49         },
  50         optionExamples: [true, [true, OPTION_CHECK_MULTILINE_START]],
  51         type: "formatting",
  52         typescriptOnly: false,
  53     };
  54     /* tslint:enable:object-literal-sort-keys */
  55     Rule.ALIGNMENT_FAILURE_STRING = "asterisks in jsdoc must be aligned";
  56     Rule.FORMAT_FAILURE_STRING = "jsdoc is not formatted correctly on this line";
  57     return Rule;
  58 }(Lint.Rules.AbstractRule));
  59 exports.Rule = Rule;
  60 function walk(ctx) {
  61     return utils.forEachComment(ctx.sourceFile, function (fullText, _a) {
  62         var kind = _a.kind, pos = _a.pos, end = _a.end;
  63         if (kind !== ts.SyntaxKind.MultiLineCommentTrivia ||
  64             fullText[pos + 2] !== "*" ||
  65             fullText[pos + 3] === "*" ||
  66             fullText[pos + 3] === "/") {
  67             return;
  68         }
  69         var lines = fullText.slice(pos + 3, end - 2).split("\n");
  70         var firstLine = lines[0];
  71         if (lines.length === 1) {
  72             if (firstLine[0] !== " " || !firstLine.endsWith(" ")) {
  73                 ctx.addFailure(pos, end, Rule.FORMAT_FAILURE_STRING);
  74             }
  75             return;
  76         }
  77         var alignColumn = getAlignColumn(ctx.sourceFile, pos + 1);
  78         if (ctx.options.firstLineOfMultiline && /\S/.test(firstLine)) {
  79             // first line of multiline JSDoc should be empty, i.e. only contain whitespace
  80             ctx.addFailureAt(pos, firstLine.length + 3, Rule.FORMAT_FAILURE_STRING);
  81         }
  82         var lineStart = pos + firstLine.length + 4; // +3 for the comment start "/**" and +1 for the newline
  83         var endIndex = lines.length - 1;
  84         for (var i = 1; i < endIndex; ++i) {
  85             var line = lines[i].endsWith("\r") ? lines[i].slice(0, -1) : lines[i];
  86             // regex is: start of string, followed by any amount of whitespace, followed by *,
  87             // followed by either a space or the end of the string
  88             if (!/^\s*\*(?: |$)/.test(line)) {
  89                 ctx.addFailureAt(lineStart, line.length, Rule.FORMAT_FAILURE_STRING);
  90             }
  91             if (line.indexOf("*") !== alignColumn) {
  92                 ctx.addFailureAt(lineStart, line.length, Rule.ALIGNMENT_FAILURE_STRING);
  93             }
  94             lineStart += lines[i].length + 1; // + 1 for the splitted-out newline
  95         }
  96         var lastLine = lines[endIndex];
  97         // last line should only consist of whitespace
  98         if (lastLine.search(/\S/) !== -1) {
  99             ctx.addFailure(lineStart, end, Rule.FORMAT_FAILURE_STRING);
 100         }
 101         if (lastLine.length !== alignColumn) {
 102             ctx.addFailure(lineStart, end, Rule.ALIGNMENT_FAILURE_STRING);
 103         }
 104     });
 105 }
 106 function getAlignColumn(sourceFile, pos) {
 107     var result = ts.getLineAndCharacterOfPosition(sourceFile, pos);
 108     // handle files starting with BOM
 109     return result.line === 0 && sourceFile.text[0] === "\uFEFF"
 110         ? result.character - 1
 111         : result.character;
 112 }
 113 var templateObject_1, templateObject_2;