feat(check-property-names): add rule to check for duplicated and improperly nested properties

BREAKING CHANGE:

Adds new rule to `recommended`

Author: brettz9

.README/README.md

@@ -332,6 +332,7 @@ only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`).
 {"gitdown": "include", "file": "./rules/check-examples.md"}
 {"gitdown": "include", "file": "./rules/check-indentation.md"}
 {"gitdown": "include", "file": "./rules/check-param-names.md"}
+{"gitdown": "include", "file": "./rules/check-property-names.md"}
 {"gitdown": "include", "file": "./rules/check-syntax.md"}
 {"gitdown": "include", "file": "./rules/check-tag-names.md"}
 {"gitdown": "include", "file": "./rules/check-types.md"}

.README/rules/check-property-names.md

@@ -0,0 +1,13 @@
+### `check-property-names`
+
+Ensures that property names in JSDoc are not duplicated on the same block
+and that nested properties have defined roots.
+
+#### Options
+
+|||
+|---|---|
+|Context|Everywhere|
+|Tags|`property`|
+
+<!-- assertions checkPropertyNames -->

README.md

@@ -24,6 +24,7 @@ JSDoc linting rules for ESLint.
         * [`check-examples`](#eslint-plugin-jsdoc-rules-check-examples)
         * [`check-indentation`](#eslint-plugin-jsdoc-rules-check-indentation)
         * [`check-param-names`](#eslint-plugin-jsdoc-rules-check-param-names)
+        * [`check-property-names`](#eslint-plugin-jsdoc-rules-check-property-names)
         * [`check-syntax`](#eslint-plugin-jsdoc-rules-check-syntax)
         * [`check-tag-names`](#eslint-plugin-jsdoc-rules-check-tag-names)
         * [`check-types`](#eslint-plugin-jsdoc-rules-check-types)
@@ -1728,6 +1729,121 @@ function quux ({
 
 Likewise for the pattern `[a, b]` which is an [`ArrayPattern`](https://github.com/estree/estree/blob/master/es2015.md#arraypattern).
 
+<a name="eslint-plugin-jsdoc-rules-check-property-names"></a>
+### <code>check-property-names</code>
+
+Ensures that property names in JSDoc are not duplicated on the same block
+and that nested properties have defined roots.
+
+<a name="eslint-plugin-jsdoc-rules-check-property-names-options-4"></a>
+#### Options
+
+|||
+|---|---|
+|Context|Everywhere|
+|Tags|`property`|
+
+The following patterns are considered problems:
+
+````js
+/**
+ * @typedef (SomeType) SomeTypedef
+ * @property Foo.Bar
+ */
+// Message: @property path declaration ("Foo.Bar") appears before any real property.
+
+/**
+ * @typedef (SomeType) SomeTypedef
+ * @property foo
+ * @property Foo.Bar
+ */
+// Message: @property path declaration ("Foo.Bar") root node name ("Foo") does not match previous real property name ("foo").
+
+/**
+ * @typedef (SomeType) SomeTypedef
+ * @property foo
+ * @property foo
+ */
+// Message: Duplicate @property "foo"
+
+/**
+ * @typedef (SomeType) SomeTypedef
+ * @prop foo
+ * @prop foo
+ */
+// Settings: {"jsdoc":{"tagNamePreference":{"property":"prop"}}}
+// Message: Duplicate @prop "foo"
+
+/**
+ * @typedef (SomeType) SomeTypedef
+ * @property foo
+ */
+// Settings: {"jsdoc":{"tagNamePreference":{"property":false}}}
+// Message: Unexpected tag `@property`
+````
+
+The following patterns are not considered problems:
+
+````js
+/**
+ *
+ */
+
+/**
+ * @typedef (SomeType) SomeTypedef
+ * @property foo
+ */
+
+/**
+ * @typedef (SomeType) SomeTypedef
+ * @prop foo
+ */
+
+/**
+ * @typedef (SomeType) SomeTypedef
+ * @property foo
+ * @property bar
+ */
+
+/**
+ * @typedef (SomeType) SomeTypedef
+ * @property foo
+ * @property foo.foo
+ * @property bar
+ */
+
+/**
+ * Assign the project to a list of employees.
+ * @typedef (SomeType) SomeTypedef
+ * @property {object[]} employees - The employees who are responsible for the project.
+ * @property {string} employees[].name - The name of an employee.
+ * @property {string} employees[].department - The employee's department.
+ */
+
+/**
+ * @typedef (SomeType) SomeTypedef
+ * @property {Error} error Exit code
+ * @property {number} [code = 1] Exit code
+ */
+
+/**
+ * @namespace (SomeType) SomeNamespace
+ * @property {Error} error Exit code
+ * @property {number} [code = 1] Exit code
+ */
+
+/**
+ * @class
+ * @property {Error} error Exit code
+ * @property {number} [code = 1] Exit code
+ */
+function quux (code = 1) {
+  this.error = new Error('oops');
+  this.code = code;
+}
+````
+
+
 <a name="eslint-plugin-jsdoc-rules-check-syntax"></a>
 ### <code>check-syntax</code>
 
@@ -1926,10 +2042,10 @@ wizaction
 
 Note that the tags indicated as replacements in `settings.jsdoc.tagNamePreference` will automatically be considered as valid.
 
-<a name="eslint-plugin-jsdoc-rules-check-tag-names-options-4"></a>
+<a name="eslint-plugin-jsdoc-rules-check-tag-names-options-5"></a>
 #### Options
 
-<a name="eslint-plugin-jsdoc-rules-check-tag-names-options-4-definedtags"></a>
+<a name="eslint-plugin-jsdoc-rules-check-tag-names-options-5-definedtags"></a>
 ##### <code>definedTags</code>
 
 Use an array of `definedTags` strings to configure additional, allowed tags.
@@ -2529,7 +2645,7 @@ Date
 RegExp
 ```
 
-<a name="eslint-plugin-jsdoc-rules-check-types-options-5"></a>
+<a name="eslint-plugin-jsdoc-rules-check-types-options-6"></a>
 #### Options
 
 `check-types` allows one option:
@@ -3416,22 +3532,22 @@ This rule checks the values for a handful of tags:
     `allowedAuthors` is present, ensure that the author value is one
     of these array items.
 
-<a name="eslint-plugin-jsdoc-rules-check-values-options-6"></a>
+<a name="eslint-plugin-jsdoc-rules-check-values-options-7"></a>
 #### Options
 
-<a name="eslint-plugin-jsdoc-rules-check-values-options-6-allowedauthors"></a>
+<a name="eslint-plugin-jsdoc-rules-check-values-options-7-allowedauthors"></a>
 ##### <code>allowedAuthors</code>
 
 An array of allowable author values. If absent, only non-whitespace will
 be checked for.
 
-<a name="eslint-plugin-jsdoc-rules-check-values-options-6-allowedlicenses"></a>
+<a name="eslint-plugin-jsdoc-rules-check-values-options-7-allowedlicenses"></a>
 ##### <code>allowedLicenses</code>
 
 An array of allowable license values or `true` to allow any license text.
 If present as an array, will be used in place of SPDX identifiers.
 
-<a name="eslint-plugin-jsdoc-rules-check-values-options-6-licensepattern"></a>
+<a name="eslint-plugin-jsdoc-rules-check-values-options-7-licensepattern"></a>
 ##### <code>licensePattern</code>
 
 A string to be converted into a `RegExp` (with `u` flag) and whose first
@@ -3664,10 +3780,10 @@ Note that `@private` will still be checked for content by this rule even with
 `settings.jsdoc.ignorePrivate` set to `true` (a setting which normally
 causes rules not to take effect).
 
-<a name="eslint-plugin-jsdoc-rules-empty-tags-options-7"></a>
+<a name="eslint-plugin-jsdoc-rules-empty-tags-options-8"></a>
 #### Options
 
-<a name="eslint-plugin-jsdoc-rules-empty-tags-options-7-tags"></a>
+<a name="eslint-plugin-jsdoc-rules-empty-tags-options-8-tags"></a>
 ##### <code>tags</code>
 
 If you want additional tags to be checked for their descriptions, you may
@@ -3895,10 +4011,10 @@ by our supported Node versions):
 Applies to the jsdoc block description and `@description` (or `@desc`)
 by default but the `tags` option (see below) may be used to match other tags.
 
-<a name="eslint-plugin-jsdoc-rules-match-description-options-8"></a>
+<a name="eslint-plugin-jsdoc-rules-match-description-options-9"></a>
 #### Options
 
-<a name="eslint-plugin-jsdoc-rules-match-description-options-8-matchdescription"></a>
+<a name="eslint-plugin-jsdoc-rules-match-description-options-9-matchdescription"></a>
 ##### <code>matchDescription</code>
 
 You can supply your own expression to override the default, passing a
@@ -3913,7 +4029,7 @@ You can supply your own expression to override the default, passing a
 As with the default, the supplied regular expression will be applied with the
 Unicode (`"u"`) flag and is *not* case-insensitive.
 
-<a name="eslint-plugin-jsdoc-rules-match-description-options-8-tags-1"></a>
+<a name="eslint-plugin-jsdoc-rules-match-description-options-9-tags-1"></a>
 ##### <code>tags</code>
 
 If you want different regular expressions to apply to tags, you may use
@@ -3950,7 +4066,7 @@ its "description" (e.g., for `@returns {someType} some description`, the
 description is `some description` while for `@some-tag xyz`, the description
 is `xyz`).
 
-<a name="eslint-plugin-jsdoc-rules-match-description-options-8-maindescription"></a>
+<a name="eslint-plugin-jsdoc-rules-match-description-options-9-maindescription"></a>
 ##### <code>mainDescription</code>
 
 If you wish to override the main function description without changing the
@@ -3972,7 +4088,7 @@ There is no need to add `mainDescription: true`, as by default, the main
 function (and only the main function) is linted, though you may disable checking
 it by setting it to `false`.
 
-<a name="eslint-plugin-jsdoc-rules-match-description-options-8-contexts"></a>
+<a name="eslint-plugin-jsdoc-rules-match-description-options-9-contexts"></a>
 ##### <code>contexts</code>
 
 Set this to an array of strings representing the AST context
@@ -4616,7 +4732,7 @@ function quux () {
 
 Enforces a consistent padding of the block description.
 
-<a name="eslint-plugin-jsdoc-rules-newline-after-description-options-9"></a>
+<a name="eslint-plugin-jsdoc-rules-newline-after-description-options-10"></a>
 #### Options
 
 This rule allows one optional string argument. If it is `"always"` then a problem is raised when there is no newline after the description. If it is `"never"` then a problem is raised when there is a newline after the description. The default value is `"always"`.
@@ -4887,7 +5003,7 @@ The following types are always considered defined.
 Note that preferred types indicated within `settings.jsdoc.preferredTypes` will
 also be assumed to be defined.
 
-<a name="eslint-plugin-jsdoc-rules-no-undefined-types-options-10"></a>
+<a name="eslint-plugin-jsdoc-rules-no-undefined-types-options-11"></a>
 #### Options
 
 An option object may have the following key:
@@ -5316,10 +5432,10 @@ tag descriptions are written in complete sentences, i.e.,
 * Periods after items within the `abbreviations` option array are not treated
   as sentence endings.
 
-<a name="eslint-plugin-jsdoc-rules-require-description-complete-sentence-options-11"></a>
+<a name="eslint-plugin-jsdoc-rules-require-description-complete-sentence-options-12"></a>
 #### Options
 
-<a name="eslint-plugin-jsdoc-rules-require-description-complete-sentence-options-11-tags-2"></a>
+<a name="eslint-plugin-jsdoc-rules-require-description-complete-sentence-options-12-tags-2"></a>
 ##### <code>tags</code>
 
 If you want additional tags to be checked for their descriptions, you may
@@ -5341,7 +5457,7 @@ its "description" (e.g., for `@returns {someType} some description`, the
 description is `some description` while for `@some-tag xyz`, the description
 is `xyz`).
 
-<a name="eslint-plugin-jsdoc-rules-require-description-complete-sentence-options-11-abbreviations"></a>
+<a name="eslint-plugin-jsdoc-rules-require-description-complete-sentence-options-12-abbreviations"></a>
 ##### <code>abbreviations</code>
 
 You can provide an `abbreviations` options array to avoid such strings of text
@@ -5973,7 +6089,7 @@ Requires that all functions have a description.
   `"tag"`) must have a non-empty description that explains the purpose of the
   method.
 
-<a name="eslint-plugin-jsdoc-rules-require-description-options-12"></a>
+<a name="eslint-plugin-jsdoc-rules-require-description-options-13"></a>
 #### Options
 
 An options object may have any of the following properties:
@@ -6269,25 +6385,25 @@ Requires that all functions have examples.
 * All functions must have one or more `@example` tags.
 * Every example tag must have a non-empty description that explains the method's usage.
 
-<a name="eslint-plugin-jsdoc-rules-require-example-options-13"></a>
+<a name="eslint-plugin-jsdoc-rules-require-example-options-14"></a>
 #### Options
 
 This rule has an object option.
 
-<a name="eslint-plugin-jsdoc-rules-require-example-options-13-exemptedby"></a>
+<a name="eslint-plugin-jsdoc-rules-require-example-options-14-exemptedby"></a>
 ##### <code>exemptedBy</code>
 
 Array of tags (e.g., `['type']`) whose presence on the document
 block avoids the need for an `@example`. Defaults to an empty array.
 
-<a name="eslint-plugin-jsdoc-rules-require-example-options-13-avoidexampleonconstructors"></a>
+<a name="eslint-plugin-jsdoc-rules-require-example-options-14-avoidexampleonconstructors"></a>
 ##### <code>avoidExampleOnConstructors</code>
 
 Set to `true` to avoid the need for an example on a constructor (whether
 indicated as such by a jsdoc tag or by being within an ES6 `class`).
 Defaults to `false`.
 
-<a name="eslint-plugin-jsdoc-rules-require-example-options-13-contexts-1"></a>
+<a name="eslint-plugin-jsdoc-rules-require-example-options-14-contexts-1"></a>
 ##### <code>contexts</code>
 
 Set this to an array of strings representing the AST context
@@ -6612,7 +6728,7 @@ function quux () {
 
 Requires a hyphen before the `@param` description.
 
-<a name="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description-options-14"></a>
+<a name="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description-options-15"></a>
 #### Options
 
 This rule takes one optional string argument. If it is `"always"` then a problem is raised when there is no hyphen before the description. If it is `"never"` then a problem is raised when there is a hyphen before the description. The default value is `"always"`.
@@ -6718,7 +6834,7 @@ function quux () {
 Checks for presence of jsdoc comments, on class declarations as well as
 functions.
 
-<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-15"></a>
+<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-16"></a>
 #### Options
 
 Accepts one optional options object with the following optional keys.
@@ -7919,7 +8035,7 @@ function quux (foo) {
 
 Requires that all function parameters are documented.
 
-<a name="eslint-plugin-jsdoc-rules-require-param-options-16"></a>
+<a name="eslint-plugin-jsdoc-rules-require-param-options-17"></a>
 #### Options
 
 An options object accepts one optional property:
@@ -9308,7 +9424,7 @@ Requires returns are documented.
 
 Will also report if multiple `@returns` tags are present.
 
-<a name="eslint-plugin-jsdoc-rules-require-returns-options-17"></a>
+<a name="eslint-plugin-jsdoc-rules-require-returns-options-18"></a>
 #### Options
 
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
@@ -9810,7 +9926,7 @@ Also impacts behaviors on namepath (or event)-defining and pointing tags:
    allow `#`, `.`, or `~` at the end (which is not allowed at the end of
    normal paths).
 
-<a name="eslint-plugin-jsdoc-rules-valid-types-options-18"></a>
+<a name="eslint-plugin-jsdoc-rules-valid-types-options-19"></a>
 #### Options
 
 - `allowEmptyNamepaths` (default: true) - Set to `false` to disallow