rev-dep 1.0.0-alpha.4 → 1.0.0-alpha.5

package/README.md

@@ -1,16 +1,51 @@
 <h3 align="center">
-  <code>rev🠄dep</code>
+  <code>rev⭠dep</code>
 </h3>
 
 <p align="center">
-  A small tool for JavaScript project discovery
+  Dependency debugging tool for JavaScript and TypeScript projects
 </p>
 
 ---
 
 <img alt="rev-dep version" src="https://img.shields.io/npm/v/rev-dep"> <img alt="rev-dep license" src="https://img.shields.io/npm/l/rev-dep"> <img alt="rev-dep PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square">
 
-## Installation
+## About
+
+The tool was created help with daily dev struggles by answering these questions:
+
+- What entry points my codebase have
+- Which entry points uses a given file
+- Which dependencies a given file has
+
+This helps to debug project dependencies, plan refactoring, optimize bundles or plan code splitting.
+
+It's especially useful in JS world without TypeScript or tests coverage.
+
+It also helps to identify and eliminate dead files, understand the complexity of the file dependencies
+
+[Jump to CLI reference](#CLI-reference)
+
+[`export * from` problem](#Export-from-problem)
+
+### Use cases
+
+- You plan to refactor some file and you wonder which entry points are affected
+- You are wondering wether a given source file is used
+- You wonder if there are any dead files in your project
+- You want to identify all dead files at once
+- You want to verify if a given entry point imports only the required files
+- You want to optimize the amount of files imported by an entry point
+
+### How about dependency or bundle graphs?
+
+There are tool that can output nice, visual representation of project dependencies like [webpack-bundle-analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer) or [dependency-cruiser](https://www.npmjs.com/package/dependency-cruiser) (_which btw rev-dep uses for non-TS codebases_)
+
+While graphs can be useful to identify major problems like too big bundle size or to visualize mess in your deps, it's hard to take any action based on them (_at least it was hard for me_ 🤷‍♂️)
+
+`rev-dep` visualize dependencies as lists, so it's really easy to see where to cut the line to solve the problem.
+
+## Getting Started
 
 ### Install globally to use as CLI tool
 
@@ -28,59 +63,31 @@ or
 
 `npm install rev-dep`
 
-## Example
+## Recipes
 
-For this repo
+### How to identify where a file is used in the project?
 
-```sh
-rev-dep resolve getDepsSet.js cli.js
-```
+### How to check if a file is used in the project?
 
-will output
+### How to identify dead files in the project?
 
-```
-Results:
-
- ➞ cli.js
-  ➞ find.js
-   ➞ getDepsSet.js
-```
-
-Which says that `getDepsSet.js` file is used in `cli.js` entry point and is required through `find.js`
-
-## About
-
-The tool was created to determine places in the project where a particular file is used, to test wether the refactoring do not break functionalities.
-
-It's especially useful in JS world without TypeScript or tests coverage.
+### How to check which files are imported by a given file?
 
-Except the reverse dependency resolution path, it can print statistics about how many times a particular module is required in the project, which might be helpful for code-splitting planning.
+### How to reduce amount of files imported by entry point?
 
 ## Usage
 
-Project can be used as a CLI tool or as a regular JS module
+Project can be used as a CLI tool or as a module
 
 ### CLI Tool
 
-Avaliable commands:
-
-#### `resolve`
-
-```sh
-rev-dep resolve <filePath> <entryPoints...>
-```
-
-Available options are
-
-- `-cs or --compactSummary` - instead of file paths print a compact summary of reverse resolution with a count of found paths
-- `--verbose` - log currently performed operation
-- `-wc, --webpackConfig <path>` - path to webpack config to enable webpack aliases support
+For CLI usage see [CLI reference](#CLI-reference)
 
 ### Module
 
 #### `find` Function
 
-```js
+```ts
 import { find } from "rev-dep";
 
 const path = find({
@@ -91,25 +98,18 @@ const path = find({
 console.log(path);
 ```
 
-#### `find` Options
-
-- `entryPoints (Array)` - Array of entry points to build a tree for search. Usually it will be one entry point, but project can have many of them, eg. next.js application. **Required**
-- `filePath (String)` - A file that we want to find path for. **Required**
-- `skipRegex (String | RegExp)` - If a file path matches the pattern, we stop to traverse it's dependencies and do not include that file in the search tree. _Optional_, default: `'(node_modules|/__tests__|/__test__|/__mockContent__|.scss)'`
-- `verbose (Boolean)` - when set to true, will print current operation performed by find function. _Optional_, default: `false`
-- `cwd` - root for resolved files, must be an absolute path. _Optional_, default: `process.cwd()`
-- `webpackConfig (String)` - path to webpack config to enable webpack aliases support
-
-### Additional setup may be required
-
-#### Resolving implicit file extensions
+#### `find` Function
 
-A vast amount of JS/TS projects are configured in a way that allows (or even forces) to skip file extensions in import statements. Rev-dep is strongly based on [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) which by default support implicit file extensions for `*.js, *.cjs, *.mjs, *.jsx` files (check [source](https://github.com/sverweij/dependency-cruiser/blob/96e34d0cf158034f2b7c8cafe9cec72dd74d8c45/src/extract/transpile/meta.js)).
-In order to resolve implicit extensions for other JS based languages it look for available corresponding compiler in `package.json`. If compiler is available, then extension is supported.
+```ts
+import { find } from "rev-dep";
 
-If you installed `rev-dep` **globally**, you will have appropriate compiler installed **globally** as well. If you use it as a module, your project has to have compiler in it's package.json.
+const path = find({
+  entryPoints: ["index.js"],
+  filePath: "utils.js",
+});
 
-For example, to support `*.ts` and `*.tsx` implicit extensions in globally installed `rev-dep`, you have to also install globally `typescript` package (see [source](https://github.com/sverweij/dependency-cruiser/blob/96e34d0cf158034f2b7c8cafe9cec72dd74d8c45/src/extract/transpile/typescript-wrap.js))
+console.log(path);
+```
 
 ## CLI reference
 
@@ -196,6 +196,59 @@ rev-dep docs <outputPath> [options]
 - `-hl, --headerLevel <value>` - Initial header level (_optional_)
 <!-- cli-docs-end -->
 
+## Export from problem
+
+`rev-dep` attempts to also solve `export * from` by a babel plugin that can be used as follows
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    'rev-dep/babel'
+  ]
+};
+```
+
+The plugins is currently **experimental** and might not work for all codebases!
+
+It helps by rewiring paths to re-exported modules
+
+```ts
+// file.ts
+import { add } from "./utils";
+
+// utils/index.ts
+
+export * from "./math";
+export * from "./otherModule";
+export * from "./anotherModule";
+
+// utils/math.ts
+
+export const add = () => {};
+```
+
+And for `file.ts` it would rewire the import like this
+
+```ts
+// file.ts
+import { add } from "./utils/math";
+```
+
+So as a result, we don't implicitly require `./otherModule` and `./anotherModule` which we will not use anyway
+
+### Benefits
+
+I don't have solid evidence for this, but I think it reduced RAM usage of the dev server I worked with (_blitz.js_). It crashed less often due to reaching heap size limit.
+
+But for sure it reduced bundle size, _slightly_, but still 😀
+
+It all depends on the the project dependencies structure.
+
+By using the babel plugin you will reduce a risk of problems like implicitly importing `front-end` modules on the `server` or similar while still being able to benefit from short import paths.
+
+Once I got an incident that, after a rebase with main branch, my project stopped compiling due to the problem caused by `export * from`. I spend a few hours debugging that, very frustrating.
+
 ## Contributing
 
 Project is open to contributions, just rise an issue if you have some ideas about features or you noticed a bug. After discussion we can approach implementation :)
@@ -204,16 +257,20 @@ Project is open to contributions, just rise an issue if you have some ideas abou
 
 1. Clone repo
 2. Install deps using `yarn`
-3. Run tests using `yarn test --watch`
+3. Run `yarn build:watch`
 4. Code!
 
-For testing purpose you can install CLI tool from the file system using
+For testing purpose use
+
+`yarn dev [command] --cwd path/to/some/codebase`
+
+or you can install CLI tool from the file system using
 
-`yarn global add file:ABSOLUTE_PATH_TO_REPO`
+`yarn global add $PWD`
 
-or just
+and then just run
 
-`yarn global add file:$(echo $PWD)`
+`rev-dep`
 
 ## Made with 🧠 by [@jayu](https://github.com/jayu)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rev-dep",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.5",
   "description": "Reverse dependency resolution tool built with dependency-cruiser",
   "main": "lib/find.js",
   "bin": "bin.js",