code-pluck v1.0.35

Code Pluck

A command line utility to perform SQL-like queries on JavaScript codebases.

pluck allows you to search for pieces of code in your project by syntactic type, treating your code like an AST database.

To install

> yarn global add code-pluck

Then, to see all the arrow functions you've written in the project at your current working directory:

> pluck 'select * from $downstream.arrowfunctionexpressions' 

To see them and then cut them all with one command:

> pluck 'select * from $downstream.arrowfunctionexpressions' --post cut

To comment out all of the console.whatever() calls in your project:

pluck 'select * from $downstream.memberexpressions where "callee.object.name" like "console%"' --post commentOutLine

Note the " " around the property lookup in the where expression.

To comment out all of the console.whatever() calls in your project only in files where the path matches test:

pluck 'select * from "/test/.memberexpressions" where "callee.object.name" like "console%"' --post commentOutLine

Note, also, the " " around the target in the from expression.

API

The general form of the api looks like this:

> pluck 'select [propertyName | *] from ["$downstream" | /pattern/].[ast-type-name] where [propertyName[.member, ...]]] like "some value"' --post [post-function-name]

ast-type-name can be any valid babel type, lowercased: see here, or a valid pluck-defined alias.

Types are either plural or singular: plural type names with return all matches for a type per file, singular with stop at the first match.

Pluralisation is simplified to adding "s" to the end of the type, regardless of whether doing so is correct in terms of English grammar.

> pluck 'select * from $downstream.identifier' # -> maximum of one result per file 
> pluck 'select * from $downstream.identifiers' # -> many results per file

There are a number of aliases (WIP) for type names, currently these can be learned by inspecting src/ast-aliases.js.

For example:

> pluck 'select * from $downstream.fatarrows' 
> # same as 
> pluck 'select * from $downstream.arrowfunctionexpressions' 

The * (asterix) token when used with select will return the entire piece of code that is matched as a string.

> pluck 'select * from $downstream.fatarrows'

// ... more results above 
	---
	11: (line 36)
	async (someArg) => {
	  return await fetch(...someArgs)
	}
// ... more results below

Alternatively, select can be used with a property name:

> pluck 'select params from $downstream.fatarrows'

// ... more results above 
########

path:  /my-project/myfile.js
[
  Node {
    type: 'Identifier',
    start: 132,
    end: 141,
    loc: SourceLocation {
      start: [Position],
      end: [Position],
      filename: undefined,
      identifierName: 'props'
    },
    name: 'someArg'
  }
]
// ... more results below

The where expression can look up nested object properties. So were I to refine the last query to have a good chance of only returning the highlighted result, I could try:

> pluck 'select params from $downstream.fatarrows where "params.0.name" like "someArg"' 

Supported SQL Functionality

• select
  • *
  • propertyName
• from
  • $downstream.{ast-type-name} (searches all files below cwd)
  • "/{some-pattern}/.{ast-type-name} (searches all paths that match {some pattern})

• where

  • LIKE function
    • "%STR" | "STR%" | "STR"

Post Operations and Mods

Code Pluck accepts a --post flag which allows a user to apply a function to the query results.

Currently the two supported functions are:

cut

pluck 'select * from $downstream.stringliterals where value like "a%"' --post cut

Will cut all string literal expressions which start with "a".

commentOutLine

pluck 'select * from $downstream.identifiers where value like "console%"' --post commentOutLine

Will comment out any lines that contain the variable name "console".