npm package: @neabyte/figra
Description: Parses import/export statements, generates dependency trees, and tracks filename references with alias resolution to map file relationships.
Author: NeaByteLab
Latest version: 0.2.0

# Figra

![npm version](https://img.shields.io/npm/v/@neabyte/figra)
![node version](https://img.shields.io/node/v/@neabyte/figra)
![typescript version](https://img.shields.io/badge/typeScript-5.9.2-blue.svg)
![license](https://img.shields.io/npm/l/@neabyte/figra.svg)
![status](https://img.shields.io/badge/status-development-orange.svg)

A powerful file analysis tool that parses import/export statements, generates dependency trees, and tracks filename references with alias resolution. Features automatic ripgrep binary download and multi-platform support.

<div align="center">
  <img src="./preview/example1.svg" alt="Figra Dependency Tree Example" width="100%"/>
</div>

<p align="center">
  📊 <b><a href="./BENCHMARK.md">[View Performance Benchmarks]</a></b> - Detailed performance analysis across 78 TypeScript files
</p>

> **⚠️ Development Notice**: This project is currently in active development. We're working on improving regex patterns for file structure parsing, which may occasionally result in "No correlation found" or "No exports found" errors. The CLI is fully functional, but analysis accuracy may vary. We welcome bug reports and feedback to help improve the tool.

## ✨ Features

- **Auto Download** - Automatically downloads ripgrep binary for your platform
- **Dependency Trees** - Generates hierarchical file structures
- **File Correlation** - Maps relationships between files
- **Filename Tracking** - Finds filename mentions in code
- **Import/Export Analysis** - Parses all import/export relationships
- **Multi-Platform** - Supports Windows, macOS, and Linux
- **Smart Extraction** - Automatically extracts and sets up ripgrep

---

## 📦 Installation

```bash
npm install -g @neabyte/figra
```

## 🚀 Usage

### CLI Usage

```bash
# Download and setup ripgrep binary (required first time)
figra --download
# or using short alias
figra -d

# Analyze a file with full dependency tree and SVG export
figra --files="/path/to/your/file.ts"
# or using short alias
figra -f "/path/to/your/file.ts"

# Get only related files list (skip correlation analysis)
figra --files="/path/to/your/file.ts" --only-files

# Generate JSON output only (skip SVG generation)
figra --files="/path/to/your/file.ts" --no-export

# Use custom export directory
figra --files="/path/to/your/file.ts" --export-path="./my-output"
# or using short alias
figra -f "/path/to/your/file.ts" -e "./my-output"

# Show help
figra --help
# or using short alias
figra -h
```

### Backend API Usage

```javascript
import figra from '@neabyte/figra'

// Basic file analysis
const result = await figra({
  values: {
    'files': 'src/index.ts'
  }
})

// With options
const result = await figra({
  values: {
    'files': 'src/core/Parser.ts',
    'only-files': true,
    'no-export': false,
    'export-path': './custom-output'
  }
})

console.log(result)
// Output:
// {
//   relatedFiles: ['/path/to/file1.ts', '/path/to/file2.ts'],
//   correlations: { filePath: '...', connections: [...], exports: [...] },
//   svgPath: '/path/to/output.svg',
//   svgBuffer: Buffer
// }
```

#### API Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `values.files` | `string` | File path to analyze (required) | - |
| `values.only-files` | `boolean` | Return only related files list | `false` |
| `values.no-export` | `boolean` | Skip SVG generation | `false` |
| `values.export-path` | `string` | Custom export directory | `./output` |

#### TypeScript Support

```typescript
import figra, { 
  AnalyzeFileResult, 
  ParsedArgs, 
  DependencyTree, 
  DependencyConnection 
} from '@neabyte/figra'

const result: AnalyzeFileResult = await figra({
  values: {
    'files': 'src/index.ts'
  }
})
```

### 📋 Available Options

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--help` | `-h` | Show help message | - |
| `--download` | `-d` | Download and setup ripgrep binary | `false` |
| `--files` | `-f` | File path to analyze (required) | - |
| `--export-path` | `-e` | Custom export directory for SVG output | `./output` |
| `--no-export` | - | Skip SVG generation, return JSON only | `false` |
| `--only-files` | - | Return only related files list (skip correlation analysis) | `false` |

## 📁 Supported Files

- `.js`, `.mjs`, `.cjs` - JavaScript files
- `.jsx` - React JavaScript
- `.ts` - TypeScript
- `.tsx` - React TypeScript

---

## 🔧 How Figra Works?

```mermaid
graph TD
    A[📁 Target File] --> B[🔧 Stage 1: Parser]
    B --> C[🔍 Extract Exports]
    C --> D[🔧 Stage 2: Finder]
    D --> E[⚡ Ripgrep Search]
    E --> F[🎯 Find Consumers]
    F --> G[🔧 Stage 3: Resolver]
    G --> H[🛣️ Resolve Paths]
    H --> I[🔧 Stage 4: Correlation]
    I --> J[🔗 Map Relationships]
    J --> K[📊 Dependency Tree]
    
    B --> B1[Functions]
    B --> B2[Classes]
    B --> B3[Interfaces]
    B --> B4[Types]
    B --> B5[Enums]
    
    D --> D1[Named Imports]
    D --> D2[Default Imports]
    D --> D3[Type Imports]
    D --> D4[CommonJS]
    
    G --> G1[Relative Paths]
    G --> G2[Alias Resolution]
    G --> G3[Absolute Paths]
    
    I --> I1[Direct Connections]
    I --> I2[Re-export Chains]
    
    classDef important fill:#e1f5fe,stroke:#01579b,stroke-width:3px,color:#000
    classDef stage fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000
    classDef result fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px,color:#000
    
    class B,D,G,I stage
    class C,E,F,H,J important
    class K result
```

### 🔍 **Stage 1: File Structure Parsing**
- **Parser Module** (`Parser.ts`) extracts all export declarations from the target file
- Detects **functions**, **classes**, **interfaces**, **enums**, **types**, **variables**, and **default exports**
- Supports **ES6**, **CommonJS**, **named exports**, **re-exports**, and **default exports**
- Uses regex patterns to identify different export patterns accurately

### 🔎 **Stage 2: Pattern-Based Search**
- **Finder Module** (`Finder.ts`) uses **ripgrep** to search across your entire project
- Generates detailed search patterns for different import styles:
  - `import { name } from 'path'` (named imports)
  - `import name from 'path'` (default imports)
  - `import type { name } from 'path'` (type imports)
  - `const { name } = require('path')` (CommonJS destructuring)
  - `const name = require('path')` (CommonJS default)
- Filters results by file extensions and ignores common directories (node_modules, dist, etc.)

### 🛣️ **Stage 3: Path Resolution**
- **Resolver Module** (`Resolver.ts`) resolves import paths to actual file locations
- Handles multiple path types:
  - **Relative paths** (`./`, `../`) with proper directory traversal
  - **Alias resolution** from `tsconfig.json` path mapping
  - **Absolute paths** and **cross-platform compatibility**
- Supports complex nested structures and wildcard aliases (`@utils/*`)

### 🔗 **Stage 4: Dependency Correlation**
- **Correlation Module** (`Correlation.ts`) maps relationships between files
- Identifies two types of connections:
  - **Direct**: Files that directly import from the analyzed file
  - **Re-export**: Files that re-export exports from the analyzed file
- Detects **re-export chains** and **alias-based re-exports**
- Returns structured **dependency trees** with connection details

---

## 🖼️ Other Preview

<div align="center">
  <img src="./preview/example2.svg" alt="Figra Analysis Example 2" width="100%"/>
</div>

<div align="center">
  <img src="./preview/example3.svg" alt="Figra Analysis Example 3" width="100%"/>
</div>

---

## 🚧 TODO Checklist

### Known Bugs
- **Regex Parsing Issues**: Occasional "No correlation found" or "No exports found" errors due to ongoing improvements in regex patterns for file structure parsing
- **Boolean Parameter Validation**: Backend API accepts any truthy value for boolean options (e.g., `'only-files': 'false'` is treated as `true`). Use actual boolean values for expected behavior
- **SVG Export Path**: Custom export paths may not create directories automatically - ensure target directories exist before analysis

#### Core Analysis Engine
- [x] **File Structure Parsing** - Extracts export declarations (functions, classes, interfaces, types, enums)
- [x] **Export Type Detection** - Supports ES6, CommonJS, default, named, and re-exports
- [x] **File Reference Tracking** - Uses ripgrep to find cross-file references
- [x] **Pattern-based Search** - Multiple search patterns for different import styles
- [x] **Project Root Detection** - Automatically finds project root directory

#### Cross-Platform Support
- [x] **Platform Detection** - macOS (x64/ARM64), Windows (x64/ARM64/i686), Linux (multiple architectures)
- [x] **Binary Management** - Downloads and manages ripgrep v14.1.1 automatically
- [x] **Archive Extraction** - Handles tar.gz (Unix) and zip (Windows) formats
- [x] **Progress Tracking** - Visual download progress with user feedback

#### File Support & Validation
- [x] **Multi-format Support** - `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.tsx`
- [x] **File Validation** - Checks existence and extension validity
- [x] **Error Handling** - Detailed error messages and validation

#### CLI Interface
- [x] **Command Line Interface** - Full CLI with `--files`, `--download`, `--help` commands
- [x] **Short Aliases** - `-f`, `-d`, `-h`, `-e` for common options
- [x] **Export Options** - `--no-export` and `--only-files` flags
- [x] **Custom Output** - `--export-path` for custom SVG export directory
- [x] **Search Filtering** - Ignores common directories (node_modules, dist, .git, etc.)
- [x] **JSON Output** - Structured file analysis results with SVG buffer
- [x] **Duplicate Filtering** - Removes duplicate search results

### Enhance Core Features
- [x] Add configurable search patterns for better filtering
- [x] Add real-time file watching with live updates
- [x] Create API exports for programmatic usage
- [x] Generate visual dependency tree diagrams
- [ ] Improve CLI progress indicators and user feedback

### Support Alias Resolution from Config Files
- [ ] Parse `astro.config.js/ts` for Astro aliases
- [ ] Parse `bun.config.js` for Bun aliases
- [ ] Parse `esbuild.config.js` for esbuild aliases
- [ ] Parse `jest.config.js` for Jest testing aliases
- [ ] Parse `jsconfig.json` for JavaScript path aliases
- [ ] Parse `metro.config.js` for React Native aliases
- [ ] Parse `next.config.js` for Next.js aliases
- [ ] Parse `nuxt.config.js/ts` for Nuxt.js aliases
- [ ] Parse `package.json` for npm/yarn/pnpm aliases
- [ ] Parse `parcel.config.js` for Parcel aliases
- [ ] Parse `rollup.config.js` for Rollup aliases
- [ ] Parse `svelte.config.js` for SvelteKit aliases
- [x] Parse `tsconfig.json` for TypeScript path aliases
- [ ] Parse `vite.config.js/ts` for Vite bundler aliases
- [ ] Parse `vitest.config.js/ts` for Vitest testing aliases
- [ ] Parse `webpack.config.js` for Webpack aliases

---

## 📄 License

This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.