sdras / project-explorer Goto Github PK

🎋A CLI tool to create an annotated tree visualization of any project

Home Page: https://sdras.github.io/project-explorer-site/

License: MIT License

JavaScript 100.00%

directory-tree tree project-explorer tree-visualization cli-tool cli cli-documentation cli-directory-tree automated-documentation docs

project-explorer's Introduction

🎋 Project Explorer

Check out the site: https://sdras.github.io/project-explorer-site/

Create a tree visualization of any project with this CLI tool. When ramping people up on an existing codebase, there's often a lot of state they have to understand about the project- where everything is, where everything starts, exceptional files. With this tool, you can generate a visualization of any project, as well modify certain directories to be open, or have notes that people can read through easily.

Installation

npm i -g project-explorer

Here's an example of what we'll be generating:

A working example of this exists here. I created this for Vue core off of notes taken at a core meeting as Evan You walked us through some of the file structure.

Prerequisites:

You need to be running Node 8 or higher
You have to have Yarn installed.

Usage:

To create the visualization in the same folder as your project:

Go into the directory of a project you'd like to document, and run the first command, pexx nameofyourproject.
When prompted for your path, write . or ./
Magic happens! ✨ (but it takes a minute ⏰)

To create the visualization in a separate folder:

Go into the directory of a project you'd like to document, and run pwd in your terminal to get the path
Create a new folder to run this CLI in.
Run the first command, pexx nameofyourproject.
Then paste in the output of pwd as your path when the CLI prompts you for it.
Magic happens! ✨ (but it takes a minute ⏰)

$ pexx nameofyourproject
> path: ./ (or whatever your pwd output is)
‣ Name of Project: nameofyourproject
‣ Path: ./

Replace nameofyourproject with the name you'd like to give your project
Files in .gitignore will be ignored in the build. We've also removed .gitignore, .git, and the base-directory-tree that this project will generate.
Path can either be the current directory or you can use pwd in another local directory of choice. I recommend this option as you might want these files and this documentation in another folder.

This will kick off the processes that will build the directory trees, the UI for traversing, and give you a little example to start with too :) It will even kick off the server for you.

Open directories

You can specify what directories you would like to be open when a user first visits by adding them to the opened array in base-directory-tree/src/store.

Comments

You can add comments for the different files by adding them to the comments object in base-directory-tree/src/store. You will specify it using the path as the key and the comment as the value, like this:

`READMEexample`: `This is an example of how a note is made! You can write the pathname of any file and the note will appear ☺️. You can delete this now.`

Github link

You can point the github logo link to your own repo by updating the github string in base-directory-tree/src/store.

(Basically all the state you need is probably in the Vuex store. 😉)

Contributing

Contributions are welcome! 🤘 Please head over to CONTRIBUTING.md for more information.

🥂 Thanks for using this project! I hope it's helpful. If you see ways to improve it, PRs are welcome.

Twitter: sarah_edo

project-explorer's People

Contributors

Stargazers

Watchers

project-explorer's Issues

`tree` is already a Unix command, so `tree nameofmyproject` fails.

Hi! This CLI looks amazing for onboarding new developers on a project with a large codebase 😊

However I ran into a problem while trying it out: I already have a tree command on my $PATH, so running tree nameofmyproject tries to run the “Unix” tree. As this command is fairly popular, I wouldn’t be surprised if other people have the same problem.

A solution for now is to type the full path for the project-explorer’s tree binary, e.g. /Users/nico/.nvm/versions/node/v8.11.3/bin/tree.

Do you think it would be possible to change the name of the executable, e.g. to project-explorer or some other fancier name? I’m willing to do a PR on the matter.

Thanks!

Update tree without rebuilding and losing comments

I'd be great if you could update the tree to reflect the latest project structure without rebuilding the entire thing which overwrites all of my comments.

Missing script and broken on Node 8

All that being said, the default template of project appears to be lacking of dev script. Here is a couple of screenshots.

And I also run into the failure in installing Project Explorer on Node 8.

How to add comments to subdirectories

For example, If have e structure like:
-common
--models

how do I add an info to a models directory?

Adding something like "common.models": "Info text" to comments section of store.js

Sorry if I missed some documentation, nice work!

Fix the arrow placement for small directories

The arrow is too low for single file directories

Comments not appearing for any files other than READMEexample

Can't supply my store.js as that'd be revealing confidential information, but I'm wanting to use this internally for a presentation. I'll probably miss my chance today but oh well.

The issue is that I can't add comments to any files other than READMEexample. I can change the contents of that comment, but supplying any path, whether that's any of:

project-name/app/models/model.rb
project-name/app/models/model
app/models/model.rb
app/models/model
model
model.rb

will not result in a comment being added for that file in the view.

I've also tried renaming the project to projectname rather than project-name.

Feel free to drop this if it can't be replicated.

Run a check for if the directory is too large

If someone mistakenly points to root or some gigantic directory they didn't mean to, it will just get clogged for a while. This needs a check for how large the file is- and maybe a loader too? I'm interested to hear people's opinions on this before I implement it for what the expected behavior should be.

Allow path to be passed as a flag

I think it would be nice if the user could pass the pass the path in directly. For example, pexx my project --path .. In this case, the tool can then skip the "Path" question. I'm willing to work on this.

1. Cannot read property 'push' of undefined 2. using project-explorer locally

I've installed it locally (npm i --save-dev project-explorer)

Then I ran:

node_modules/.bin/pexx abc

But error appeared (UnhandledPromiseRejectionWarning)

path: .
‣ Name of Project: abc
‣ Path: .
(node:5535) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'push' of undefined
    at /Users/lukasz/sandbox/resmix/node_modules/project-explorer/index.js:70:21
    at Generator.next (<anonymous>)
    at onFulfilled (/Users/lukasz/sandbox/resmix/node_modules/co/index.js:65:19)
    at process._tickCallback (internal/process/next_tick.js:68:7)
(node:5535) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:5535) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

Then I manually edited index.js in node_modules/project-eplorer/ and changed:

const gitignoredArr = gitignoreRegex(pathDir)

into

 const gitignoredArr = gitignoreRegex(pathDir) || [];

and then it worked... almost. It generated base-directory-tree but it wasn't able to run it

Your files were saved, now let's build it out! ✨
Hang tight, this might take a minute.
yarn install v0.15.1
info No lockfile found.
[1/4] Resolving packages...
warning @vue/cli-service > webpack-bundle-analyzer > [email protected]: Switch to the `bfj` package for fixes and new features!
[2/4] Fetching packages...
[3/4] Linking dependencies...
warning Unmet peer dependency "webpack@^2.0.0 || ^3.0.0 || ^4.0.0".
warning Incorrect peer dependency "@babel/core@^7.0.0".
warning Unmet peer dependency "webpack@>=2".
[4/4] Building fresh packages...
success Saved lockfile.
Done in 42.98s.
🎸 Done! Built with success! Now let's get you a server.
yarn serve v0.15.1
$ "vue-cli-service serve --open" 
sh: vue-cli-service serve --open: command not found
error Command failed with exit code 127.
info Visit http://yarnpkg.com/en/docs/cli/serve for documentation about this command.
exec: sh: vue-cli-service serve --open: command not found
error Command failed with exit code 127.

Then I've run cd base-directory-tree and npm start but it also didn't run

> [email protected] start /Users/lukasz/sandbox/resmix/base-directory-tree
> npm run dev

npm ERR! missing script: dev

UPDATE: I ran node_modules/.bin/vue-cli-service serve --open from base-directory-tree and a file tree was appeared on http://localhost:8080/ but anyway...

It seems like I stumbled upon two different issues:

push problem (which I resolved by manually adding || [] )
this projects seems to assume global installing. Is this special reason for that? I prefer to install things locally and it would be nice if it worked out of the box when installing locally.

Good defaults for if the project name or path is not defined

Right now if you don't use the tool properly and forget to pass in the name of the project, it fails silently.

Ignore files and folders from '.gitignore'

Wouldn't be nice if we ignore files which are included in the .gitignore?

Create ability to add a file back in after excluded from .gitignore

From the discussion on this issue: #8, we need to have a way to add files back in that are excluded in gitignore.

/bin/sh: yarn: command not found

Tnx a lot for this awesome project. I don't have yarn installed on my PC and I get this error /bin/sh: yarn: command not found Can you handle this situation gracefully? (by using npm if yarn is not presented)

Proposal: eliminating ./base-directory-tree

First, thank you for making this: it has so much potential to help people get a better understanding of how projects & libraries work. It's also beautifully designed and executed.

My question: since we're installing pexx globally, could the global lib not also contain the necessary infrastructure for rendering the UI?

Current: running pexx my-project saves an entire instance of Project Explorer per directory
Proposed:
1. Running pexx my-project saves what is now saved as ./my-project/base-directory-tree/src/store.js as a single JSON file named ./my-project/.pexxrc;
2. Running pexx my-project (or simply pexx within it) detects the existence of .pexxrc and serves a production build of a Vue app that reads .pexxrc and renders the same interface as now.

It's quite possible I'm missing context: feel free to dismiss if so!

Don't right path in the `dist` folder

Hello. I try explaine a problem.

Cloning Flask project.

> $ git clone [email protected]:pallets/flask.git

pexx flask_structure
> $ cd base-directory-tree
> $ yarn build
It creates the dist directory, right?
But if I open the index.html in a browser I don't see the project structure.
Because don't the right path to js, CSS and favicon files.
For example:

<!DOCTYPE html>
<html>

<head>
    <meta charset=utf-8>
    <meta http-equiv=X-UA-Compatible content="IE=edge">
    <meta name=viewport content="width=device-width,initial-scale=1">
    <link rel="shortcut icon" href=/favicon.ico> <title>Vue directory tree with notes</title>
    <link href=/css/app.76b10bfb.css rel=preload as=style>
    <link href=/css/chunk-vendors.391ed6f9.css rel=preload as=style>
    <link href=/js/app.a8693738.js rel=preload as=script>
    <link href=/js/chunk-vendors.fded67b1.js rel=preload as=script>
    <link href=/css/chunk-vendors.391ed6f9.css rel=stylesheet>
    <link href=/css/app.76b10bfb.css rel=stylesheet>
</head>

<body><noscript><strong>We're sorry but drawtree doesn't work properly without JavaScript enabled. Please enable it to
            continue.</strong></noscript>
    <div id=app></div>
    <script src=/js/chunk-vendors.fded67b1.js> </script> <script src=/js/app.a8693738.js> </script> </body> </html>

This index.html
If I add . - all work.

<!DOCTYPE html>
<html>

<head>
    <meta charset=utf-8>
    <meta http-equiv=X-UA-Compatible content="IE=edge">
    <meta name=viewport content="width=device-width,initial-scale=1">
    <link rel="shortcut icon" href=/favicon.ico> <title>Vue directory tree with notes</title>
    <link href=./css/app.76b10bfb.css rel=preload as=style>
    <link href=./css/chunk-vendors.391ed6f9.css rel=preload as=style>
    <link href=./js/app.a8693738.js rel=preload as=script>
    <link href=./js/chunk-vendors.fded67b1.js rel=preload as=script>
    <link href=./css/chunk-vendors.391ed6f9.css rel=stylesheet>
    <link href=./css/app.76b10bfb.css rel=stylesheet>
</head>

<body><noscript><strong>We're sorry but drawtree doesn't work properly without JavaScript enabled. Please enable it to
            continue.</strong></noscript>
    <div id=app></div>
    <script src=./js/chunk-vendors.fded67b1.js> </script> <script src=./js/app.a8693738.js> </script> </body> </html>

What do you think about that?
Thank you very much.

Add ability to specify different labels

Adding ignore labels to certain directories / files would be useful for teams that bring in outside consultants. That way they could specify the info label only to certain sections of the project that are relevant to them and label any configs / irrelevant directories with ignore.

I'm happy to add more use cases here and implement if it's of value.

comment disappearing

currently if the cursor is out of focus from the 'info' button, the comments goes away. It would be nice to select the texts from the comment dialog as well. :) One solution can be to give the info button a click handler to persist state for comments.

Remove .DS_Store

Remove unneeded files like .DS_Store. Possibly node_modules as well.