feat: support comment-selector-based contexts

feat(`no-restricted-syntax`, `no-missing-syntax`): add new rules

.README/README.md

@@ -469,23 +469,28 @@ properties:
 
 1. For `require-jsdoc`, there is also a `inlineCommentBlock` property. See
     that rule for details.
-2. For other rules, there is a `comment` property which adds to the `context`
+1. For `no-missing-syntax` and `no-restricted-syntax`, there is also a
+    `message` property which allows customization of the message to be shown
+    when the rule is triggered.
+1. For `no-missing-syntax`, there is also a `minimum` property. See that rule.
+1. For other rules, there is a `comment` property which adds to the `context`
     in requiring that the `comment` AST condition is also met, e.g., to
     require that certain tags are present and/or or types and type operators
-    are in use. Note that this AST has not been standardized and should be
-    considered experimental. <!-- Make reference to https://github.com/brettz9/jsdoc-eslint-parser/ when stable: One may also use a full-blown parser which supports
-    comment AST as a first class citizen usable anywhere within a normal AST,
-    but this is also experimental. When using this parser, you need not use
-    `comment` and can just use a plain string context. -->
-    In addition to being generally useful for precision in specifying contexts,
-    it is hoped that the ability to specify required tags on structures can
-    be used for requiring `@type` or other types for a minimalist yet adequate
-    specification of types which can be used to compile JavaScript+JSDoc (JJ)
-    to WebAssembly (e.g., by converting it to TypeSscript and then using
-    AssemblyScript to convert to WebAssembly). (It may be possible that one
-    will need to require types with certain structures beyond function
-    declarations and the like, as well as optionally requiring specification
-    of number types.)
+    are in use. Note that this AST (either for `JSDoc*` or `JSDocType*` AST)
+    has not been standardized and should be considered experimental.
+    Note that this property might also become obsolete if parsers begin to
+    include JSDoc-structured AST. Work has begun on [such a parser](https://github.com/brettz9/jsdoc-eslint-parser/) which is intended to support comment AST as
+    a first class citizen where comment/comment types can be used anywhere
+    within a normal AST selector but this is also experimental. When using
+    such a parser, you need not use `comment` and can just use a plain
+    string context. The determination of the node on which the comment is
+    attached is also subject to change. It may be currently possible for
+    different structures to map to the same comment block. This is because
+    normally when querying to find either the declaration of the function
+    expression for `const quux = function () {}`, the associated comment would,
+    in both cases, generally be expected to be on the line above both, rather
+    than to be immediately preceding the funciton (in the case of the
+    function).
 
 #### Discovering available AST definitions
 
@@ -545,7 +550,7 @@ selector).
 {"gitdown": "include", "file": "./rules/newline-after-description.md"}
 {"gitdown": "include", "file": "./rules/no-bad-blocks.md"}
 {"gitdown": "include", "file": "./rules/no-defaults.md"}
-{"gitdown": "include", "file": "./rules/no-missing-syntax"}
+{"gitdown": "include", "file": "./rules/no-missing-syntax.md"}
 {"gitdown": "include", "file": "./rules/no-restricted-syntax.md"}
 {"gitdown": "include", "file": "./rules/no-types.md"}
 {"gitdown": "include", "file": "./rules/no-undefined-types.md"}

.README/rules/no-missing-syntax.md

@@ -0,0 +1,62 @@
+### `no-missing-syntax`
+
+This rule lets you report when certain comment structures are always expected.
+This rule might be especially useful with [`overrides`](https://eslint.org/docs/user-guide/configuring/configuration-files#how-do-overrides-work)
+where you need only require tags and/or types within specific directories
+(e.g., to enforce that a plugins or locale directory always has a certain form
+of export).
+
+This (along with `no-restricted-syntax`) is a bit similar to Schematron for
+XML or jsontron for JSON--you can validate expectations of there being
+arbitrary structures.
+
+This differs from the rule of the same name in [`eslint-plugin-query`](https://github.com/brettz9/eslint-plugin-query)
+in that this always looks for a comment above a structure (whether or not
+you have a `comment` condition).
+
+In addition to being generally useful for precision in requiring contexts,
+it is hoped that the ability to specify required tags on structures can
+be used for requiring `@type` or other types for a minimalist yet adequate
+specification of types which can be used to compile JavaScript+JSDoc (JJ)
+to WebAssembly (e.g., by converting it to TypeSscript and then using
+AssemblyScript to convert to WebAssembly). (It may be possible that one
+will need to require types with certain structures beyond function
+declarations and the like, as well as optionally requiring specification
+of number types.)
+
+Note that you can use selectors which make use of negators like `:not()`
+including with asterisk, e.g., `*:not(FunctionDeclaration)` to indicate types
+which are not adequate to satisfy a condition, e.g.,
+`FunctionDeclaration:not(FunctionDeclaration[id.name="ignoreMe"])` would
+not report if there were only a function declaration of the name "ignoreMe"
+(though it would report by function declarations of other names).
+
+#### Options
+
+##### `contexts`
+
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
+
+Use the `minimum` property (defaults to 1) to indicate how many are required
+for the rule to be reported.
+
+Use the `message` property to indicate the specific error to be shown when an
+error is reported for that context being found missing.
+
+Set to `"any"` if you want the rule to apply to any jsdoc block throughout
+your files (as is necessary for finding function blocks not attached to a
+function declaration or expression, i.e., `@callback` or `@function` (or its
+aliases `@func` or `@method`) (including those associated with an `@interface`).
+
+See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+section of our README for more on the expected format.
+
+|||
+|---|---|
+|Context|None except those indicated by `contexts`|
+|Tags|Any if indicated by AST|
+|Recommended|false|
+|Options|`contexts`|
+
+<!-- assertions noMissingSyntax -->

.README/rules/no-restricted-syntax.md

@@ -0,0 +1,41 @@
+### `no-restricted-syntax`
+
+Reports when certain comment structures are present.
+
+Note that this rule differs from ESLint's [no-restricted-syntax](https://eslint.org/docs/rules/no-restricted-syntax) rule in expecting values within a single options object's
+`contexts` property, and with the property `context` being used in place of
+`selector` (as well as allowing for `comment`). The format also differs from
+the format expected by [`eslint-plugin-query`](https://github.com/brettz9/eslint-plugin-query).
+
+Unlike those rules, this is specific to finding comments attached to
+structures, (whether or not you add a specific `comment` condition).
+
+Note that if your parser supports comment AST (as [jsdoc-eslint-parser/](https://github.com/brettz9/jsdoc-eslint-parser/) is designed to do), you can just use ESLint's
+rule.
+
+#### Options
+
+##### `contexts`
+
+Set this to an array of strings representing the AST context (or an object with
+`context` and `comment` properties) where you wish the rule to be applied.
+
+Use the `message` property to indicate the specific error to be shown when an
+error is reported for that context being found.
+
+Set to `"any"` if you want the rule to apply to any jsdoc block throughout
+your files (as is necessary for finding function blocks not attached to a
+function declaration or expression, i.e., `@callback` or `@function` (or its
+aliases `@func` or `@method`) (including those associated with an `@interface`).
+
+See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+section of our README for more on the expected format.
+
+|||
+|---|---|
+|Context|None except those indicated by `contexts`|
+|Tags|Any if indicated by AST|
+|Recommended|false|
+|Options|`contexts`|
+
+<!-- assertions noRestrictedSyntax -->