analyze-project-structure/readme.md

CLI tool for analyzing and printing the folder structure of a project, extracting details about files (such as functions, variables, routes, and imports/exports), and summarizing the project's code organization.

# Analyze Project Structure

A command-line tool to analyze and print the folder structure of JavaScript/TypeScript projects, extracting detailed insights about files, including functions, variables, routes, imports, and exports. It helps summarize the organization of your project’s codebase.

## Features

- Recursively prints the folder structure starting from the current directory (or specified folder).
- Extracts detailed info from source files, including:
  - Functions (regular and arrow functions)
  - Variables (including constants)
  - Routes (GET, POST, etc. with handler details)
  - Imports and exports
- Supports popular frameworks with enhanced parsing:
  - Angular (components, services, imports, functions)
  - Express (routes, imports, classes, functions, variables)
  - React (components, hooks, imports, functions)
- Outputs a clean, tree-like formatted text file or JSON file for easy reading.
- Default output file is `folder-structure-output.txt` in text format, customizable via command line.
- Supports output in **JSON format** by specifying the format argument.

## Installation

### Global Installation

Install the tool globally to run from anywhere:

```bash
npm install -g analyze-project-structure
```

### Local Installation

Install as a development dependency in your project:

```bash
npm install analyze-project-structure --save-dev
```

## Usage

Run the tool from your project root directory (where `package.json` and source folders like `src` exist):

```bash
analyze-project-structure [outputFile] [outputFormat]
```

or using the alias:

```bash
aps [outputFile] [outputFormat]
```

- `outputFile` (optional): Specify a custom output file name. Defaults to `folder-structure-output.txt`.
- `outputFormat` (optional): Specify the output format, either `text` (default) or `json`.

### Examples

Generate the default output file in text format:

```bash
analyze-project-structure
```

or

```bash
aps
```

Generate output with a custom file name in text format:

```bash
analyze-project-structure my-output.txt
```

or

```bash
aps my-output.txt
```

Generate output in JSON format with default file name:

```bash
analyze-project-structure folder-structure-output.json json
```

or

```bash
aps folder-structure-output.json json
```

Generate output in JSON format with custom file name:

```bash
analyze-project-structure my-output.json json
```

or

```bash
aps my-output.json json
```

## Example Output (Text)

The generated text file will show a detailed, nested folder and file structure with extracted code details. For example:

```
├── routes
│   ├── appointment.ts
│   │   ├── Routes
│   │   │   ├── /
│   │   │   │   ├── GET
│   │   │   │   │   ├── Handler Variables
│   │   │   │   │   │   └── user
│   │   │   │   │   └── Functions in Handler
│   │   │   │   │       └── Anonymous Arrow Function
│   │   │   │   └── POST
│   │   │   │       ├── Handler Variables
│   │   │   │       │   └── appointment
│   │   │   │       └── Functions in Handler
│   │   │   │           └── Anonymous Arrow Function
│   │   ├── Imports
│   │   │   ├── express
│   │   │   └── ../../db
│   │   ├── Exports
│   │   │   └── appointmentRouter
│
│   └── auth.ts
│       ├── Routes
│       │   └── /register
│       │       └── POST
│       ├── Imports
│       │   ├── express
│       │   ├── bcryptjs
│       │   ├── jsonwebtoken
│       │   ├── express-validator
│       │   └── ../../db
│       ├── Exports
│       │   └── authRoutes
│
├── server.ts
│   ├── Imports
│   │   ├── express
│   │   ├── helmet
│   │   ├── ./routes/auth
│   │   └── ./routes/appointment
```

## Example Output (JSON)

The generated JSON file will contain the same structure in a JSON object format, suitable for programmatic consumption.

```json
{
  "routes": {
    "appointment.ts": {
      "routes": [
        {
          "path": "/",
          "methods": [
            {
              "type": "GET",
              "handlerVariables": ["user"],
              "functions": ["Anonymous Arrow Function"]
            },
            {
              "type": "POST",
              "handlerVariables": ["appointment"],
              "functions": ["Anonymous Arrow Function"]
            }
          ],
          "imports": ["express", "../../db"],
          "exports": ["appointmentRouter"]
        }
      ]
    },
    "auth.ts": {
      "routes": [
        {
          "path": "/register",
          "methods": [
            {
              "type": "POST"
            }
          ],
          "imports": [
            "express",
            "bcryptjs",
            "jsonwebtoken",
            "express-validator",
            "../../db"
          ],
          "exports": ["authRoutes"]
        }
      ]
    }
  },
  "server.ts": {
    "imports": [
      "express",
      "helmet",
      "./routes/auth",
      "./routes/appointment"
    ]
  }
}
```

## Supported Frameworks

* **Angular**: Detects components, services, imports, and functions by parsing decorators.
* **Express**: Detects routes, imports, classes, functions, and variables.
* **React**: Detects components, hooks, imports, and functions.

The tool automatically detects the project type from your `package.json` dependencies and adjusts parsing accordingly.

## License

This project is licensed under the ISC License - see the LICENSE file for details.

## Author

Prasad Dhule

---