eslint-plugin-complete 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright The Complete Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# eslint-plugin-complete
+
+`eslint-plugin-complete` is a collection of miscellaneous [ESLint](https://eslint.org/) rules that can help make your TypeScript code more safe or more strict.
+
+If you already have ESLint set up in your project, then you can try enabling the [`complete/recommend`](#configs) config to get all of the goodness from this plugin in your project at once. Alternatively, if you want more control, feel free to enable the specific rules that you need.
+
+Alternatively, if you want to get off the ground and running with ESLint + TypeScript in a new project, then you should check out the [`complete-lint`](https://github.com/complete-ts/complete/tree/main/packages/complete-lint) meta-package.
+
+## Install / Usage
+
+If you do not want to use the `complete-lint` meta-package, then you can install this plugin manually:
+
+- `npm install --save-dev eslint typescript eslint-plugin-complete` (`eslint` and `typescript` are peer-dependencies)
+- TODO
+- Add `"plugin:complete/recommended"` to the `extends` section of your `.eslintrc.cjs` file. (This will automatically add the plugin and add all of the recommended rules.)
+  - Alternatively, if you want to only enable some specific rules, then add `"complete"` to the `plugins` section of your `.eslintrc.cjs` file, and then add the specific rules that you want in the `rules` section.
+
+## Configs
+
+- `recommended` - Currently, every rule in this plugin is recommended.
+
+## Rules
+
+Each rule has emojis denoting:
+
+- :white_check_mark: - if it belongs to the `recommended` configuration
+- :wrench: - if some problems reported by the rule are automatically fixable by the `--fix` [command line option](https://eslint.org/docs/latest/user-guide/command-line-interface#fixing-problems)
+- :thought_balloon: - if it requires type information
+
+<!-- Do not manually modify the RULES_TABLE section. Instead, run: npm run generate -->
+<!-- RULES_TABLE -->
+
+| Name                                                                                                  | Description                                                                                                 | :white_check_mark: | :wrench: | :thought_balloon: |
+| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------ | -------- | ----------------- |
+| [`complete/complete-sentences-jsdoc`](docs/rules/complete-sentences-jsdoc.md)                         | Requires complete sentences for JSDoc comments                                                              | :white_check_mark: |          |                   |
+| [`complete/complete-sentences-line-comments`](docs/rules/complete-sentences-line-comments.md)         | Requires complete sentences for multi-line leading line comments                                            | :white_check_mark: |          |                   |
+| [`complete/consistent-enum-values`](docs/rules/consistent-enum-values.md)                             | Requires consistent enum values                                                                             | :white_check_mark: |          |                   |
+| [`complete/consistent-named-tuples`](docs/rules/consistent-named-tuples.md)                           | Requires that if one or more tuple elements are named, all of them are named                                | :white_check_mark: |          |                   |
+| [`complete/eqeqeq-fix`](docs/rules/eqeqeq-fix.md)                                                     | Requires the use of `===` and `!==` (and automatically fixes)                                               | :white_check_mark: | :wrench: |                   |
+| [`complete/format-jsdoc-comments`](docs/rules/format-jsdoc-comments.md)                               | Disallows `/**` comments longer than N characters and multi-line comments that can be merged together       | :white_check_mark: | :wrench: |                   |
+| [`complete/format-line-comments`](docs/rules/format-line-comments.md)                                 | Disallows `//` comments longer than N characters and multi-line comments that can be merged together        | :white_check_mark: | :wrench: |                   |
+| [`complete/jsdoc-code-block-language`](docs/rules/jsdoc-code-block-language.md)                       | Requires a language specification for every JSDoc code block                                                | :white_check_mark: |          |                   |
+| [`complete/newline-between-switch-case`](docs/rules/newline-between-switch-case.md)                   | Requires newlines between switch cases                                                                      | :white_check_mark: | :wrench: |                   |
+| [`complete/no-confusing-set-methods`](docs/rules/no-confusing-set-methods.md)                         | Disallows confusing methods for sets                                                                        | :white_check_mark: |          | :thought_balloon: |
+| [`complete/no-empty-jsdoc`](docs/rules/no-empty-jsdoc.md)                                             | Disallows empty JSDoc comments                                                                              | :white_check_mark: | :wrench: |                   |
+| [`complete/no-empty-line-comments`](docs/rules/no-empty-line-comments.md)                             | Disallows empty line comments                                                                               | :white_check_mark: | :wrench: |                   |
+| [`complete/no-explicit-array-loops`](docs/rules/no-explicit-array-loops.md)                           | Disallows explicit iteration for arrays                                                                     | :white_check_mark: | :wrench: | :thought_balloon: |
+| [`complete/no-explicit-map-set-loops`](docs/rules/no-explicit-map-set-loops.md)                       | Disallows explicit iteration for maps and sets                                                              | :white_check_mark: | :wrench: | :thought_balloon: |
+| [`complete/no-for-in`](docs/rules/no-for-in.md)                                                       | Disallows "for x in y" statements                                                                           | :white_check_mark: |          |                   |
+| [`complete/no-let-any`](docs/rules/no-let-any.md)                                                     | Disallows declaring variables with let that do not have a type                                              | :white_check_mark: |          | :thought_balloon: |
+| [`complete/no-mutable-return`](docs/rules/no-mutable-return.md)                                       | Disallows returning mutable arrays, maps, and sets from functions                                           | :white_check_mark: |          | :thought_balloon: |
+| [`complete/no-number-enums`](docs/rules/no-number-enums.md)                                           | Disallows number enums                                                                                      | :white_check_mark: |          |                   |
+| [`complete/no-object-any`](docs/rules/no-object-any.md)                                               | Disallows declaring objects and arrays that do not have a type                                              | :white_check_mark: |          | :thought_balloon: |
+| [`complete/no-object-methods-with-map-set`](docs/rules/no-object-methods-with-map-set.md)             | Disallows using object methods with maps and sets                                                           | :white_check_mark: |          | :thought_balloon: |
+| [`complete/no-string-length-0`](docs/rules/no-string-length-0.md)                                     | Disallows checking for empty strings via the length method in favor of direct comparison to an empty string | :white_check_mark: |          | :thought_balloon: |
+| [`complete/no-template-curly-in-string-fix`](docs/rules/no-template-curly-in-string-fix.md)           | Disallows template literal placeholder syntax in regular strings (and automatically fixes)                  | :white_check_mark: | :wrench: |                   |
+| [`complete/no-undefined-return-type`](docs/rules/no-undefined-return-type.md)                         | Disallows `undefined` return types on functions                                                             | :white_check_mark: |          | :thought_balloon: |
+| [`complete/no-unnecessary-assignment`](docs/rules/no-unnecessary-assignment.md)                       | Disallows useless assignments                                                                               | :white_check_mark: |          | :thought_balloon: |
+| [`complete/no-unsafe-plusplus`](docs/rules/no-unsafe-plusplus.md)                                     | Disallow unsafe and confusing uses of the "++" and "--" operators                                           | :white_check_mark: |          | :thought_balloon: |
+| [`complete/no-useless-return`](docs/rules/no-useless-return.md)                                       | Disallow redundant return statements (with no auto-fixer)                                                   | :white_check_mark: |          |                   |
+| [`complete/no-void-return-type`](docs/rules/no-void-return-type.md)                                   | Disallows `void` return types on non-exported functions                                                     | :white_check_mark: | :wrench: |                   |
+| [`complete/prefer-const`](docs/rules/prefer-const.md)                                                 | Require `const` declarations for variables that are never reassigned after declared (with no auto-fixer)    | :white_check_mark: |          |                   |
+| [`complete/prefer-plusplus`](docs/rules/prefer-plusplus.md)                                           | Require "++" or "--" operators instead of assignment operators where applicable                             | :white_check_mark: | :wrench: |                   |
+| [`complete/prefer-postfix-plusplus`](docs/rules/prefer-postfix-plusplus.md)                           | Require "i++" instead of "++i"                                                                              | :white_check_mark: |          | :thought_balloon: |
+| [`complete/prefer-readonly-parameter-types`](docs/rules/prefer-readonly-parameter-types.md)           | Require function parameters to be typed as `readonly` to prevent accidental mutation of inputs              | :white_check_mark: |          | :thought_balloon: |
+| [`complete/require-break`](docs/rules/require-break.md)                                               | Requires that each case of a switch statement has a `break` statement                                       | :white_check_mark: |          |                   |
+| [`complete/require-capital-const-assertions`](docs/rules/require-capital-const-assertions.md)         | Requires a capital letter for named objects and arrays that have a const assertion                          | :white_check_mark: | :wrench: |                   |
+| [`complete/require-capital-read-only`](docs/rules/require-capital-read-only.md)                       | Requires maps/sets/arrays with a capital letter to be read-only                                             | :white_check_mark: |          | :thought_balloon: |
+| [`complete/require-unannotated-const-assertions`](docs/rules/require-unannotated-const-assertions.md) | Disallows explicit type annotations for variables that have a const assertion                               | :white_check_mark: |          |                   |
+| [`complete/require-variadic-function-argument`](docs/rules/require-variadic-function-argument.md)     | Requires that variadic functions must be supplied with at least one argument                                | :white_check_mark: |          | :thought_balloon: |
+| [`complete/strict-array-methods`](docs/rules/strict-array-methods.md)                                 | Requires boolean return types on array method functions                                                     | :white_check_mark: |          | :thought_balloon: |
+| [`complete/strict-enums`](docs/rules/strict-enums.md)                                                 | Disallows the usage of unsafe enum patterns                                                                 | :white_check_mark: |          | :thought_balloon: |
+| [`complete/strict-undefined-functions`](docs/rules/strict-undefined-functions.md)                     | Disallows empty return statements in functions annotated as returning undefined                             | :white_check_mark: |          | :thought_balloon: |
+| [`complete/strict-void-functions`](docs/rules/strict-void-functions.md)                               | Disallows non-empty return statements in functions annotated as returning void                              | :white_check_mark: |          |                   |
+
+<!-- /RULES_TABLE -->
+
+## Automatic Fixing
+
+You probably already use [Prettier](https://prettier.io/), which is helpful to automatically format files. You probably even have your IDE set up to run Prettier every time your save a file. This kind of thing saves you a tremendous amount of time - you can type out a bunch of code completely unformatted, and then press `Ctrl + s` at the end to automatically fix everything. (Alternatively, you could press `Ctrl + shift + f` to format the file without saving it, but it's simpler to just use one hotkey for everything.)
+
+In a similar way to Prettier, this ESLint plugin contains several rules that are designed to automatically apply whenever you save the file (like the [`format-jsdoc-comments`](docs/rules/format-jsdoc-comments.md) rule). These rules are "fixers", which are applied when ESLint is executed with the "--fix" flag. So, in the same way that you configure Prettier to run on save, you should also configure `eslint --fix` to run on save.
+
+For example, if you use [VSCode](https://code.visualstudio.com/), and you have the [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) and the [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) extensions installed, you can add the following to your repository's `.vscode/settings.json` file:
+
+```jsonc
+{
+  // Automatically run the formatter when certain files are saved.
+  "[javascript][typescript][javascriptreact][typescriptreact]": {
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "explicit",
+    },
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+  },
+}
+```
+
+## Comment Formatting
+
+For a discussion around comments and the motivations for some of the comment rules in the plugin, see [this page](docs/comments.md).
+
+## Contributing
+
+Thanks for helping out with this open-source project!
+
+If you are adding a new rule, start by using the `create-rule` script to automate a few things:
+
+```sh
+npm run create-rule foo "This is a description of the foo rule."
+git status # Show what the script did.
+```
+
+Additionally, You can contact me [on Discord](https://discord.gg/KapmKQ2gUD) if you are doing a PR and have questions.

package/dist/comments.d.ts

@@ -0,0 +1,22 @@
+import type { TSESLint, TSESTree } from "@typescript-eslint/utils";
+/**
+ * Returns false for trailing comments like:
+ *
+ * ```ts
+ * const abc = 123; // Foo
+ * ```
+ */
+export declare function isCommentOnOwnLine(sourceCode: TSESLint.SourceCode, comment: TSESTree.Comment): boolean;
+export declare function isEnumBlockLabel(text: string): boolean;
+/**
+ * A "separator" line is a line with all hyphens like the following:
+ *
+ * ```ts
+ * // ----------------
+ * // Getter functions
+ * // ----------------
+ * ```
+ */
+export declare function isSeparatorLine(text: string): boolean;
+export declare function isSpecialComment(text: string): boolean;
+//# sourceMappingURL=comments.d.ts.map

package/dist/comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../src/comments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,QAAQ,CAAC,UAAU,EAC/B,OAAO,EAAE,QAAQ,CAAC,OAAO,GACxB,OAAO,CAYT;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CA2BtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CActD"}

package/dist/comments.js

@@ -0,0 +1,66 @@
+/**
+ * Returns false for trailing comments like:
+ *
+ * ```ts
+ * const abc = 123; // Foo
+ * ```
+ */
+export function isCommentOnOwnLine(sourceCode, comment) {
+    const startLine = comment.loc.start.line;
+    const endLine = comment.loc.end.line;
+    const previousToken = sourceCode.getTokenBefore(comment);
+    const previousTokenEndLine = previousToken === null ? null : previousToken.loc.end.line;
+    const nextToken = sourceCode.getTokenAfter(comment);
+    const nextTokenStartLine = nextToken === null ? null : nextToken.loc.start.line;
+    return startLine !== previousTokenEndLine && endLine !== nextTokenStartLine;
+}
+export function isEnumBlockLabel(text) {
+    text = text.trim();
+    return (
+    // e.g. CollectibleType.SAD_ONION
+    /^\w+\.\w+$/.test(text) ||
+        // e.g. CollectibleType.SAD_ONION (1)
+        /^\w+\.\w+ \(\d+\)$/.test(text) ||
+        // e.g. CacheFlag.FIRE_DELAY (1 << 1)
+        /^\w+\.\w+ \(\d+ << \d+\)$/.test(text) ||
+        // e.g. 1
+        /^\d+$/.test(text) ||
+        // e.g. 1.0
+        /^\d+\.\d+$/.test(text) ||
+        // e.g. 1 << 1
+        /^\d+ << \d+$/.test(text) ||
+        // e.g. 1, 2, 3, 4, 5
+        /^\d+, \d+$/.test(text) ||
+        /^\d+, \d+, \d+$/.test(text) ||
+        /^(?:\d+, ){3}\d+$/.test(text) ||
+        /^(?:\d+, ){4}\d+$/.test(text) ||
+        // e.g. 1.0, 2.0, 3.0, 4.0, 5.0
+        /^\d+\.\d+, \d+\.\d+$/.test(text) ||
+        /^(?:\d+\.\d+, ){2}\d+\.\d+$/.test(text) ||
+        /^(?:\d+\.\d+, ){3}\d+\.\d+$/.test(text) ||
+        /^(?:\d+\.\d+, ){4}\d+\.\d+$/.test(text));
+}
+/**
+ * A "separator" line is a line with all hyphens like the following:
+ *
+ * ```ts
+ * // ----------------
+ * // Getter functions
+ * // ----------------
+ * ```
+ */
+export function isSeparatorLine(text) {
+    return /^\s*-+\s*$/.test(text);
+}
+export function isSpecialComment(text) {
+    text = text.trim();
+    return (text.startsWith("eslint-") ||
+        text.startsWith("prettier-") ||
+        text.startsWith("cspell:") ||
+        text.startsWith("ts-prune-") || // e.g. ts-prune-ignore-next
+        text.startsWith("@ts-") ||
+        text.startsWith("TODO:") ||
+        text.startsWith("FIXME:") ||
+        text === "TODO" ||
+        text === "FIXME");
+}

package/dist/completeCommon.d.ts

@@ -0,0 +1,25 @@
+export type ReadonlyRecord<K extends string | number | symbol, V> = Readonly<Record<K, V>>;
+/**
+ * Helper function to throw an error if the provided value is equal to `undefined`.
+ *
+ * This is useful to have TypeScript narrow a `T | undefined` value to `T` in a concise way.
+ */
+export declare function assertDefined<T>(value: T, ...[msg]: [undefined] extends [T] ? [string] : [
+    "The assertion is useless because the provided value does not contain undefined."
+]): asserts value is Exclude<T, undefined>;
+export declare function capitalizeFirstLetter(string: string): string;
+/**
+ * From:
+ * https://stackoverflow.com/questions/8334606/check-if-first-letter-of-word-is-a-capital-letter
+ */
+export declare function isFirstLetterCapitalized(string: string): boolean;
+/**
+ * Helper function to trim a prefix from a string, if it exists. Returns the trimmed string.
+ *
+ * @param string The string to trim.
+ * @param prefix The prefix to trim.
+ * @param trimAll Whether to remove multiple instances of the prefix, if they exist. If this is set
+ *                to true, the prefix must only be a single character.
+ */
+export declare function trimPrefix(string: string, prefix: string, trimAll?: boolean): string;
+//# sourceMappingURL=completeCommon.d.ts.map

package/dist/completeCommon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completeCommon.d.ts","sourceRoot":"","sources":["../src/completeCommon.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,QAAQ,CAC1E,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CACb,CAAC;AAIF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,GAC7B,CAAC,MAAM,CAAC,GACR;IACE,iFAAiF;CAClF,GACJ,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,CAIxC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAU5D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,UAAQ,GACd,MAAM,CAWR"}

package/dist/completeCommon.js

@@ -0,0 +1,53 @@
+// We do not want "eslint-plugin-complete" to depend on "complete-common" because it complicates the
+// usage of the plugin inside of the monorepo. Specifically, since we manually copy the compiled
+// output to the monorepo "node_modules" directory, it would cause errors if the "complete-common"
+// directory did not also exist there. To fix this, we could also compile and copy "complete-common"
+// in the build script for this plugin. However, that is undesirable for two reasons:
+// 1) It increases the complexity of the build script.
+// 2) If "complete-common" exists in the monorepo's "node_modules" directory, it can cause bugs due
+//    to tooling preferring the "real" directory over the tsconfig "paths" resolution.
+const FIRST_LETTER_CAPITALIZED_REGEX = /^\p{Lu}/u;
+/**
+ * Helper function to throw an error if the provided value is equal to `undefined`.
+ *
+ * This is useful to have TypeScript narrow a `T | undefined` value to `T` in a concise way.
+ */
+export function assertDefined(value, ...[msg]) {
+    if (value === undefined) {
+        throw new TypeError(msg);
+    }
+}
+export function capitalizeFirstLetter(string) {
+    if (string === "") {
+        return string;
+    }
+    const firstCharacter = string.charAt(0);
+    const capitalizedFirstLetter = firstCharacter.toUpperCase();
+    const restOfString = string.slice(1);
+    return `${capitalizedFirstLetter}${restOfString}`;
+}
+/**
+ * From:
+ * https://stackoverflow.com/questions/8334606/check-if-first-letter-of-word-is-a-capital-letter
+ */
+export function isFirstLetterCapitalized(string) {
+    return FIRST_LETTER_CAPITALIZED_REGEX.test(string);
+}
+/**
+ * Helper function to trim a prefix from a string, if it exists. Returns the trimmed string.
+ *
+ * @param string The string to trim.
+ * @param prefix The prefix to trim.
+ * @param trimAll Whether to remove multiple instances of the prefix, if they exist. If this is set
+ *                to true, the prefix must only be a single character.
+ */
+export function trimPrefix(string, prefix, trimAll = false) {
+    if (trimAll) {
+        const regExp = new RegExp(`^${prefix}+`, "g");
+        return string.replaceAll(regExp, "");
+    }
+    if (!string.startsWith(prefix)) {
+        return string;
+    }
+    return string.slice(prefix.length);
+}

package/dist/completeSentence.d.ts

@@ -0,0 +1,9 @@
+export type CompleteSentenceMessageIds = "missingCapital" | "missingPeriod" | "doublePeriod";
+interface IncompleteSentence {
+    sentence: string;
+    messageId: CompleteSentenceMessageIds;
+}
+export declare function getIncompleteSentences(text: string): readonly IncompleteSentence[];
+export declare function getSentences(text: string): readonly string[];
+export {};
+//# sourceMappingURL=completeSentence.d.ts.map

package/dist/completeSentence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completeSentence.d.ts","sourceRoot":"","sources":["../src/completeSentence.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,0BAA0B,GAClC,gBAAgB,GAChB,eAAe,GACf,cAAc,CAAC;AAEnB,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,0BAA0B,CAAC;CACvC;AAmBD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,GACX,SAAS,kBAAkB,EAAE,CAiC/B;AAwID,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAO5D"}

package/dist/completeSentence.js

@@ -0,0 +1,267 @@
+import { isEnumBlockLabel, isSpecialComment } from "./comments.js";
+import { getAdjustedList, reachedNewList } from "./list.js";
+import { hasURL } from "./utils.js";
+/**
+ * From:
+ * https://stackoverflow.com/questions/23571013/how-to-remove-url-from-a-string-completely-in-javascript
+ */
+const FULL_URL_REGEX = /(?:https?|ftp):\/\/[\S\n]+/g;
+/**
+ * From:
+ * https://stackoverflow.com/questions/11761563/javascript-regexp-for-splitting-text-into-sentences-and-keeping-the-delimiter
+ */
+const SENTENCE_REGEX = /(?=[^])(?:\P{Sentence_Terminal}|\p{Sentence_Terminal}(?!['"`\p{Close_Punctuation}\p{Final_Punctuation}\s]))*(?:\p{Sentence_Terminal}+['"`\p{Close_Punctuation}\p{Final_Punctuation}]*|$)/guy;
+const SENTENCE_SEPARATOR_IDENTIFIER = "___sentence_separator_identifier___";
+const IN_LINE_CODE_IDENTIFIER = "___in_line_code_identifier___";
+const LIST_ELEMENT_IDENTIFIER = "___list_element_identifier___";
+export function getIncompleteSentences(text) {
+    const incompleteSentences = [];
+    const textBlocks = splitOnSpecialText(text);
+    for (const textBlock of textBlocks) {
+        // Handle text that "spills over" to the next line by simply converting all newlines to spaces.
+        const squishedText = textBlock.split("\n").join(" ").trim();
+        // Handling all edge cases for "e.g." or "i.e." is very difficult, since sometimes it is correct
+        // to put a period after them, and sometimes not. Thus, ignore all text that contains them.
+        if (squishedText.includes("e.g.") || squishedText.includes("i.e.")) {
+            continue;
+        }
+        // Whitelist markdown links.
+        if (squishedText.endsWith("](")) {
+            continue;
+        }
+        const sentences = getSentences(squishedText);
+        const loneSentence = sentences.length === 1;
+        for (const sentence of sentences) {
+            const messageId = getIncompleteSentenceKind(sentence, loneSentence);
+            if (messageId !== undefined) {
+                incompleteSentences.push({
+                    sentence,
+                    messageId,
+                });
+            }
+        }
+    }
+    return incompleteSentences;
+}
+/**
+ * Before parsing a multi-line string to get the sentences, we first need to mutate the input to
+ * handle some problematic situations.
+ */
+function splitOnSpecialText(text) {
+    // Below, we avoid replacing certain things to an empty string because that can potentially cause
+    // subsequent text to be considered to be part of the previous sentence.
+    // Remove multi-line code blocks.
+    text = text.replaceAll(/```[\S\s]*```/gm, SENTENCE_SEPARATOR_IDENTIFIER);
+    // Remove example tag blocks. An example tag might be followed by another tag, so first look for
+    // that situation. Then, handle the situation where the example tag is the final tag.
+    text = text.replaceAll(
+    // We use `[\s\S]` instead of `.` because the latter does not match a new line.
+    /@example[\S\s]*?@/gm, `${SENTENCE_SEPARATOR_IDENTIFIER}@`);
+    text = text.replaceAll(/@example[\S\s]*/gm, "");
+    // Remove see tag blocks. A see tag might be followed by another tag, so first look for that
+    // situation. Then, handle the situation where the see tag is the final tag. (This is copy-pasted
+    // from the code that handles example tags above.)
+    text = text.replaceAll(
+    // We use `[\s\S]` instead of `.` because the latter does not match a new line.
+    /@see[\S\s]*?@/gm, `${SENTENCE_SEPARATOR_IDENTIFIER}@`);
+    text = text.replaceAll(/@see[\S\s]*/gm, "");
+    // Replace the link tags with the link text. Note that if we replace them with a sentence
+    // separator instead, then the following sentence would fail: Get the name of a peripheral wrapped
+    // with {@link peripheral.wrap}.
+    // https://regex101.com/r/0u8hQG/1
+    // https://jsdoc.app/tags-inline-link.html
+    text = text.replaceAll(/\[([^\]]*)]{@link [^ |}]+}|{@link ([^ |}]+)[ |]?}|{@link [^ |}]+[ |]([^}]+)}/gm, "$1$2$3");
+    // Remove Markdown headers.
+    text = text.replaceAll(/^\n\s*#.*\n\n/gm, SENTENCE_SEPARATOR_IDENTIFIER);
+    if (text.trimStart().startsWith("#")) {
+        // Also handle if the first line is a Markdown header.
+        text = text.replace(/^\s*#.*\n\n/m, SENTENCE_SEPARATOR_IDENTIFIER);
+    }
+    // Remove pipes (which indicate a Markdown table).
+    text = text.replaceAll("|", SENTENCE_SEPARATOR_IDENTIFIER);
+    // Handle "blocks" indicated by a double newline. We don't want sentences to be parsed/combined
+    // past blocks, so we manually insert a sentence separator.
+    text = text.replaceAll("\n\n", `\n${SENTENCE_SEPARATOR_IDENTIFIER}\n`);
+    // Handle quoted question marks.
+    // e.g. This text contains "???" in the middle.
+    text = text.replaceAll(/'\?+'/g, "");
+    text = text.replaceAll(/"\?+"/g, "");
+    const lines = text.split("\n");
+    const newLines = [];
+    let insideList;
+    for (const [i, originalLine] of lines.entries()) {
+        let line = originalLine;
+        // Ignore "@type" JSDoc tags, since they contain a code type instead of English text.
+        // https://jsdoc.app/tags-type.html
+        line = line.replace(/^\s*@type .+$/, SENTENCE_SEPARATOR_IDENTIFIER);
+        // Remove any JSDoc tags. (But leave the descriptions following the tags, if any.) "@param" tags
+        // are followed by variable names, which will not be part of the sentence.
+        line = line.replace(/^\s*@param \w+ /, SENTENCE_SEPARATOR_IDENTIFIER);
+        // This is "\S+" instead of "\w+" because we need to match things like "@ts-expect-error".
+        line = line.replace(/^\s*@\S+/, SENTENCE_SEPARATOR_IDENTIFIER);
+        // Replace any single-line code snippets with custom text. The custom text begins with an
+        // underscore, which means that it will count towards the sentence starting with a capital
+        // letter. (This is only relevant if the code block is the first word in the sentence.)
+        line = line.replaceAll(/`.+`/g, IN_LINE_CODE_IDENTIFIER);
+        // Remove any URLs present in the string, as the periods will count as sentence terminators.
+        // e.g. "This is my URL: https://stackoverflow."
+        line = line.replaceAll(FULL_URL_REGEX, "");
+        // Remove the periods from some common abbreviations so that they do not mess up the sentence
+        // parsing.
+        line = line.replaceAll(/\bDr\.\s+/g, "Dr");
+        line = line.replaceAll(/\bJr\.\s+/g, "Jr");
+        line = line.replaceAll(/\bMr\.\s+/g, "Mr");
+        line = line.replaceAll(/\bMrs\.\s+/g, "Mrs");
+        line = line.replaceAll(/\bMs\.\s+/g, "Ms");
+        line = line.replaceAll(/\bSr\.\s+/g, "Sr");
+        line = line.replaceAll(/\bSt\.\s+/g, "St");
+        line = line.replaceAll(/\betc\.\s+/g, "etc");
+        // Replace list bullet headers, since they are never part of a sentence. We also need to mark
+        // that this sentence is a list element for the purposes of ignoring any incomplete sentences.
+        // Doing this allows short lists like:
+        // - apple
+        // - banana
+        const previousLine = lines[i - 1];
+        const previousLineWasBlank = previousLine === undefined || previousLine.trim() === "";
+        const previousLineEndedInColon = previousLine !== undefined && previousLine.trimEnd().endsWith(":");
+        const list = getAdjustedList(line, previousLineWasBlank, previousLineEndedInColon, insideList);
+        if (reachedNewList(insideList, list)) {
+            // Keep track that we have begun a list (or a new sub-list).
+            insideList = list;
+        }
+        if (list !== undefined) {
+            line = line.slice(list.markerSize);
+            line = SENTENCE_SEPARATOR_IDENTIFIER + LIST_ELEMENT_IDENTIFIER + line;
+        }
+        // Split enum block labels.
+        if (isEnumBlockLabel(line)) {
+            line += SENTENCE_SEPARATOR_IDENTIFIER;
+        }
+        newLines.push(line);
+    }
+    const textBlocks = newLines.join("\n").split(SENTENCE_SEPARATOR_IDENTIFIER);
+    return textBlocks.filter((textBlock) => !isEnumBlockLabel(textBlock));
+}
+export function getSentences(text) {
+    const match = text.match(SENTENCE_REGEX);
+    if (match === null) {
+        return [];
+    }
+    return match;
+}
+function getIncompleteSentenceKind(sentence, loneSentence) {
+    let text = sentence;
+    // Trim the parenthesis surrounding the sentence, if any.
+    let textBeforeModifications;
+    do {
+        textBeforeModifications = text;
+        text = text.trim().replace(/^\(*/, "").replace(/\)*$/, "").trim();
+    } while (text !== textBeforeModifications);
+    // Ignore / whitelist some specific things.
+    if (
+    // Blank text.
+    text === "" ||
+        // Sentences that do not contain any letters.
+        !/[A-Za-z]/.test(text) ||
+        // Sentences with an arrow, like: "Alice --> Bob"
+        text.includes("-->") ||
+        // Placeholder text.
+        text === "n/a" ||
+        // Special comments.
+        isSpecialComment(text) ||
+        // Dates.
+        isDate(text) ||
+        // URLS.
+        hasURL(text) ||
+        // Single JSDoc tags.
+        /^@\w+$/.test(text) ||
+        // Lists.
+        text.startsWith(LIST_ELEMENT_IDENTIFIER) ||
+        // Code blocks.
+        text.includes("```") ||
+        // Sentences that end with a number in parenthesis (which indicates some kind of expression).
+        // This must check the original text.
+        / \(\d+\)$/.test(sentence.trimEnd())) {
+        return undefined;
+    }
+    // First, check for a double period.
+    if (text.endsWith("..") && text.length >= 3) {
+        const characterBeforePeriods = text.at(-3);
+        if (characterBeforePeriods !== ".") {
+            return "doublePeriod";
+        }
+    }
+    if (loneSentence &&
+        // Single words, double words, and triple words.
+        (/^\S+$/.test(text) || /^\S+ \S+$/.test(text) || /^\S+ \S+ \S+$/.test(text))) {
+        return undefined;
+    }
+    if (/^[a-z]/.test(text) && !isCapitalizedWordException(text)) {
+        return "missingCapital";
+    }
+    if (
+    // Allow normal end-of-line punctuation.
+    !text.endsWith(".") &&
+        !text.endsWith("!") &&
+        !text.endsWith("?") &&
+        // Allow ending with a period inside of a single quote or double quote, since it is implied that
+        // this is a fully quoted sentence.
+        !text.endsWith('."') &&
+        !text.endsWith('!"') &&
+        !text.endsWith('?"') &&
+        !text.endsWith(".'") &&
+        !text.endsWith("!'") &&
+        !text.endsWith("?'") &&
+        // Allow ending with a colon, since it is implied that there is an example of something on the
+        // subsequent block.
+        !text.endsWith(":") &&
+        // Allow ending with anything if there is a colon in the middle of the sentence, since it is
+        // implied that this is an example of something.
+        !text.includes(": ")) {
+        return "missingPeriod";
+    }
+    return undefined;
+}
+const CAPITALIZED_WORD_EXCEPTIONS = ["iPad", "iPhone", "iPod"];
+function isCapitalizedWordException(text) {
+    return CAPITALIZED_WORD_EXCEPTIONS.some((word) => text.startsWith(word));
+}
+const MONTHS_SET = new Set([
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+]);
+const ORDINALS_SET = new Set(["st", "nd", "rd", "th"]);
+function isDate(text) {
+    text = text.trim();
+    const match1 = text.match(/^(?<month>\w+) \d+(?<ordinal>\w+)$/);
+    if (match1 !== null && match1.groups !== undefined) {
+        const { month, ordinal } = match1.groups;
+        if (month !== undefined &&
+            MONTHS_SET.has(month) &&
+            ordinal !== undefined &&
+            ORDINALS_SET.has(ordinal)) {
+            return true;
+        }
+    }
+    const match2 = text.match(/^(?<month>\w+) \d+(?<ordinal>\w+), \d+$/);
+    if (match2 !== null && match2.groups !== undefined) {
+        const { month, ordinal } = match2.groups;
+        if (month !== undefined &&
+            MONTHS_SET.has(month) &&
+            ordinal !== undefined &&
+            ORDINALS_SET.has(ordinal)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/configs/recommended.d.ts

@@ -0,0 +1,3 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+export declare const recommended: TSESLint.FlatConfig.ConfigArray;
+//# sourceMappingURL=recommended.d.ts.map

package/dist/configs/recommended.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommended.d.ts","sourceRoot":"","sources":["../../src/configs/recommended.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,UAAU,CAAC,WA2D7C,CAAC"}