Add "rules" made of arbitrary selectors to choose source lines to be reported
npm install eslint-plugin-query








Add "rules" made of arbitrary selectors to choose source lines to be reported.
If using as a plugin, you can install locally:
``sh`
$ npm i eslint-plugin-query --save-dev
However, if you only wish to use this tool to make one-off searches of code,
the global installation is recommended as it is more convenient for CLI usage
and does not require each project to have its own installation.
You can install globally as follows using the -g flag:
`sh`
$ npm i -g eslint-plugin-query
Add query to the plugins section of your eslint.config.js configuration file:
`js
import query from 'eslint-plugin-query';
export default {
plugins: {
query
}
};
`
Then configure the rules you want to use under the rules section.
`js${result}
export default {
// ...
rules: {
'query/query': [2, {
queries: {
'FunctionDeclaration[params.length>4]': {
// All optional
// Defaults to just ${result}
template: 'Oops, too long: .',`
// Default: 0 (also accepts negative)
start: 0,
// Default Infinity (also accepts negative)
end: 100
}
}
}],
'query/no-missing-syntax': [
'error',
{
queries: {
'FunctionDeclaration[params.length<2]': {
message: 'Must have at least two short function signatures!',
minimum: 2
}
}
}
]
}
};
* query/no-missing-syntax
* query/query
It is simpler to use the CLI to get at results (though you'll want to
install eslint-plugin-query in such a case):
Note that the CLI uses the ESLint formatter, in this case showing them as
errors, but as this does no fixing, you can use the esq CLI command simply
to see the code (as in the above screenshot).
Note also that in the CLI (and also programmatic) usage, we auto-detect your
parser and parser options. However, since we allow you to supply file globs,
and since ESLint allows overrides such that you may have different parsersnotGlob
set up in your config, we don't know by default which file to check for the
parser config. To ensure the proper parser is used, you can either use the setting (and use a regular file) or rely on setting an override foreslint-plugin-query-dummy.js
the default file (you don't need to have thisoverrides
file in your project, but it allows you to specify an file
targeting it and giving a parser or parser options for it).
You might use the likes of eslint-formatter-badger
to build a badge counting the use of certain JavaScript features out of
your results, e.g., if you wanted to show the number of
FunctionDeclaration's in your project.
Unless you wish to count the aggregate of total of multiple selectors, you'd
probably need to create separate badges for each type (since the
eslint-formatter-badger determines type by the whole rule (e.g., from themeta.type
rule's ) rather than by the rule options (in this case queries)
that are in use). Such an approach would allow you to get the individual
count for each query type.
You could then display these badges adjacently, optionally with different
colors, and with human-readable text (e.g., "Function declarations")),
possibly with a plain intro badge before them (e.g., "Language Feature
Counts").
Though it is probably just easier to use the CLI, it may be of interest
to know that you can use the ESLint binary to make one-off searches,
e.g., if you have installed eslint and this plugin globally:
`shell`
eslint --plugin query --rule 'query/query: [2, {queries: {"FunctionDeclaration[params.length>4]": {end:100}}}]' .
Or if you only have eslint and this plugin as local installs:
`shell`
$(npm bin)/eslint --plugin query --rule 'query/query: [2, {queries: {"FunctionDeclaration[params.length>4]": {end:100}}}]' .
Here are the results:
Note that you can add the --no-save flag (for local or global use) if
you only want to use this plugin for querying in this manner, and not as
the basis of permanent rules.
Another use case is ensuring a file or set of files (e.g., within overrides):not()
(or targeted via glob if on the command line) only has one type or a set of
types (by using the esquery selector):
`shell`
$(npm bin)/eslint --plugin query --rule 'query/query: [2, {queries: {":not(FunctionDeclaration,FunctionExpression)": {end:100}}}]' .
1. Could give fixable option (to remove all identified nodes)@todo
1. Add an option to match (additionally) by regex.
1. Add an option to highlight certain esqueries out of the results, e.g.,
to show the list of parameter names of all functions
1. Get an AST parser for jsdoc comment blocks, e.g., to search for comments,@public
or all functions with a given (jsdoc-described) signature (e.g., all params
accepting a given type, all typedefs extending a type, all functions,parent
etc. If selectors don't support , would be ideal to add support,meta.type
e.g., to query for parent comment of a given function signature.
1. Add separate rule for to-do specific querying (date, etc.)
see
and
1. Would ideally allow sorting (see
1. Note: Could implement with new formatter, and the formatter
could be used for other purposes as well (e.g., showing rule
errors by or in this case, by query)jsdoc/match-description
1. Also lint to ensure even unexpired to-dos have an actual date
format (see Unicorn to-do rule). Could use
if Unicorn isn't supporting (and optionjsdoc/no-undefined-types
to it to show text of description so can be used in queries, also
for other rules like ?)./* @type {Date} /
1. Might add separate rule using jsdoc blocks in place of selectors, e.g., to
find all Date objects, use . Likewise with:matches('jsdoc', '@param {string}\n@param {Date}')
TypeScript expressions (again, not as much for validation, which TS
already does, but for querying documents using TS).
1. Could make selector which allows such matching, e.g.,
or:matches('typescript', '(...args: string[]) => void')
comment-parser
1. In supporting this, could make utility for compiling jsdoc (or (a
subset of) TS) into selectors (and vice versa). Use
. Could also convert jsdoc to TS by strippingeslint-plugin-jsdoc
out types and putting inline (as an rule)ReturnStatement
or in reverse.
1. Make combining selectors, e.g., "string" to find string literals or
string literals joined in a binary expression, etc. Then can search
for a with string to get the return type.docs/** IfStatement
1. Allow dir/file glob at beginning of selector, e.g., es-file-traverse
1. Could use @since
to limit queries to those that are visited by imports (including with
"Other interesting use cases" below).
1. Add separate rules (all supporting range queries) for semver-aware
or @version, integer-aware @variation, (and date-aware@date
abilities for tags indicated in options (e.g., if one defined ).@license
Also useful for and @copyright searchingFunctionDeclaration {color: green;}`)
1. Other interesting use cases for selectors (independent of this plugin):
1. A selector syntax for defining JS syntax highlighters (e.g.,
1. Potentially less brittle monkey-patching
1. Dynamically evaluating snippets, even private, from within other
trusted files (e.g., user templates).
1. Making links within jsdoc documentation to specific parts of code
1. Embedding code snippets within Markdown documentation without
duplication (e.g., querying for all public method names to
generate documentation headings or embed example code).
1. Using a JS XSLT equivalent to reshape an entire JS file into HTML
1. Searching for code within an IDE (within or across files)
1. Create badges showing summary of number of functions, classes, et.
along with number of lines of code