@nuxdie/inctree v1.1.1

IncTree

Build a tree of files based on a search string. It's a shallow wrapper on top of grep (actually ripgrep) which recursively searches the dir structure in this manner:

<search_term> -> filename.ext -> file2.ext

Meaning that if pattern <search_term> was found in filename.ext, it would search for files that include (or at least mention) this filename.ext repeating the process recursively until the end of the chain (or Stop Pattern) would be reached.

Install

To install simply run:

npm i -g @nuxdie/inctree

Usage

In general this is the command you'll use:

inctree [--threads=2] [--search=]<search_term>

For full list of keys see Config section below.

Output

Please note that it outputs graphviz dot file format. In order to consume it you'll use something like this:

inctree <search_term> | dot -Tpng graph.png

The raw output looks like this:

digraph g{
  rankdir=RL;
  "search_term" -> "ROOT";
  "file/path/filename.inc" -> "search_term";
  "parent/dir/path/filename2.inc" -> "file/path/filename.inc";
}

Live Server

Optionally you can start the builtin web server to check the resulting graph (in SVG) in realtime. Just pipe the output to the inctree-server (optionally saving also to a file using tee):

inctree <search_term> | tee graph.gv | inctree-server

This would open (using [xdg-]open command) default browser on `localhost:<random_port> page which would serve the graph as SVG image. You should refresh the page while the command is running to get a fresh depiction of the tree.

Config

Create a .inctreerc.json file in the dir you are going to search in (or $HOME dir) that looks like this:

````json
{
    "only": [
        ".inc",
        ".tmpl",
        ".js"
    ],
    "stopList": [
        ".tmpl",
        "inc/footer.inc",
    ],
    "mask": [
        "html_templates/general/"
    ]
}
````

This are the options available:

- mask {Array{String}} list of prefixes to remove for each node
- threads {Number} number of threads to perform search
- only {Array{String}} list of filetypes to process
- stopList {Array{String}} list of patterns to stop at (see below)

Stop Pattern List

In some cases it makes sense to stop the search based on a file ext or path. For this there's a stopList config var that allows you to define a list of such patterns in config file:

````json
{
    ...
    "stopList": [
        ".tmpl",
        "inc/footer.inc",
        "common",
    ],
    ...
}
````

When one of these patterns would match a filepath the tool would stop digging that branch of a tree.

Deps

This depends on these software packages:

- ripgrep

The (manual) processing would require:

- graphviz (to visualize the resulting graph)
- tee (to monitor output while saving to file on disk)

Speed

How slow is it? Given that it's just a shallow wrapper around grep, and all it does is calling it recursively until there're results from grep returned. There's no cache or index so the average speed is 100 nodes/minute, meaning, it takes around 20 min to get through 2k source files.