Repository files navigation

Add "rules" made of arbitraryselectors to choose source lines to be reported.

If using as a plugin, you can install locally:

$ 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 usageand does not require each project to have its own installation.

You can install globally as follows using the-g flag:

$ npm i -g eslint-plugin-query

Addquery to the plugins section of youreslint.config.js configuration file:

importqueryfrom'eslint-plugin-query';exportdefault{plugins:{    query}};

Then configure the rules you want to use under the rules section.

exportdefault{// ...rules:{'query/query':[2,{queries:{'FunctionDeclaration[params.length>4]':{// All optional// Defaults to just `${result}`template:'Oops, too long: `${result}`.',// 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 toinstalleslint-plugin-query in such a case):

Note that the CLI uses the ESLint formatter, in this case showing them aserrors, but as this does no fixing, you can use theesq CLI command simplyto see the code (as in the above screenshot).

Note also that in the CLI (and also programmatic) usage, we auto-detect yourparser and parser options. However, since we allow you to supply file globs,and since ESLint allowsoverrides such that you may have different parsersset up in your config, we don't know by default which file to check for theparser config. To ensure the proper parser is used, you can either use thenotGlob setting (and use a regular file) or rely on setting an override forthe defaulteslint-plugin-query-dummy.js file (you don't need to have thisfile in your project, but it allows you to specify anoverridesfiletargeting it and giving a parser or parser options for it).

You might use the likes ofeslint-formatter-badgerto build a badge counting the use of certain JavaScript features out ofyour results, e.g., if you wanted to show the number ofFunctionDeclaration's in your project.

Unless you wish to count the aggregate of total of multiple selectors, you'dprobably need to create separate badges for each type (since theeslint-formatter-badger determines type by the whole rule (e.g., from therule'smeta.type) rather than by the rule options (in this casequeries)that are in use). Such an approach would allow you to get the individualcount for each query type.

You could then display these badges adjacently, optionally with differentcolors, and with human-readable text (e.g., "Function declarations")),possibly with a plain intro badge before them (e.g., "Language FeatureCounts").

Though it is probably just easier to use the CLI, it may be of interestto know that you can use the ESLint binary to make one-off searches,e.g., if you have installedeslint and this plugin globally:

eslint --plugin query --rule'query/query: [2, {queries: {"FunctionDeclaration[params.length>4]": {end:100}}}]'.

Or if you only haveeslint and this plugin as local installs:

$(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) ifyou only want to use this plugin for querying in this manner, and not asthe basis of permanent rules.

Another use case is ensuring a file or set of files (e.g., withinoverrides)(or targeted via glob if on the command line) only has one type or a set oftypes (by using the:not() esquery selector):

$(npm bin)/eslint --plugin query --rule'query/query: [2, {queries: {":not(FunctionDeclaration,FunctionExpression)": {end:100}}}]'.

1. Could givefixable option (to remove all identified nodes)
2. Add an option to match (additionally) by regex.
3. Add an option to highlight certain esqueries out of the results, e.g.,to show the list of parameter names of all functions
4. Get an AST parser for jsdoc comment blocks, e.g., to search for@todo comments,or all functions with a given (jsdoc-described) signature (e.g., all paramsaccepting a given type, all typedefs extending a type, all@public functions,etc. If selectors don't supportparent, would be ideal to add support,e.g., to query for parent comment of a given function signature.
5. Add separate rule for to-do specific querying (date, etc.)seegajus/eslint-plugin-jsdoc#299,sindresorhus/eslint-plugin-unicorn#238,andeslint/eslint#11747.
   1. Would ideally allow sorting (seehttps://eslint.org/docs/developer-guide/working-with-custom-formatters#using-rule-metadata?)
      1. Note: Could implement with new formatter, and the formattercould be used for other purposes as well (e.g., showing ruleerrors bymeta.type or in this case, by query)
   2. Also lint to ensure even unexpired to-dos have an actual dateformat (see Unicorn to-do rule). Could usejsdoc/match-description if Unicorn isn't supporting (and optionto it to show text of description so can be used in queries, alsofor other rules likejsdoc/no-undefined-types?).
6. Might add separate rule using jsdoc blocks in place of selectors, e.g., tofind all Date objects, use/** @type {Date} */. Likewise withTypeScript expressions (again, not as much for validation, which TSalready does, but for querying documents using TS).
   1. Could make selector which allows such matching, e.g.,:matches('jsdoc', '@param {string}\n@param {Date}') or:matches('typescript', '(...args: string[]) => void')
   2. In supporting this, could make utility for compiling jsdoc (or (asubset of) TS) into selectors (and vice versa). Usecomment-parser. Could also convert jsdoc to TS by strippingout types and putting inline (as aneslint-plugin-jsdoc rule)or in reverse.
7. Make combining selectors, e.g., "string" to find string literals orstring literals joined in a binary expression, etc. Then can searchfor aReturnStatement withstring to get the return type.
8. Allow dir/file glob at beginning of selector, e.g.,docs/** IfStatement
9. Could usees-file-traverseto limit queries to those that are visited by imports (including with"Other interesting use cases" below).
10. Add separate rules (all supporting range queries) for semver-aware@since or@version, integer-aware@variation, (and date-awareabilities for tags indicated in options (e.g., if one defined@date).Also useful for@license and@copyright searching
11. Other interesting use cases for selectors (independent of this plugin):
    1. A selector syntax for defining JS syntax highlighters (e.g.,FunctionDeclaration {color: green;})
    2. Potentially less brittle monkey-patching
    3. Dynamically evaluating snippets, even private, from within othertrusted files (e.g., user templates).
    4. Making links within jsdoc documentation to specific parts of code
    5. Embedding code snippets within Markdown documentation withoutduplication (e.g., querying for all public method names togenerate documentation headings or embed example code).
    6. Using a JS XSLT equivalent to reshape an entire JS file into HTML
    7. Searching for code within an IDE (within or across files)
    8. Create badges showing summary of number of functions, classes, et.along with number of lines of code