fileflows/README.md

CLI tool for deploying data workflow analysis documentation

# FileFlows CLI

A CLI tool for generating `FILE_FLOWS.md` - analyzes project files and creates comprehensive documentation showing data flow relationships.

[![npm version](https://badge.fury.io/js/fileflows.svg)](https://badge.fury.io/js/fileflows)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

## Features

- **Smart File Grouping**: Groups files by actual data flow relationships (imports/exports) as the primary method
- **Fallback Naming**: Uses filename similarity for files without clear data flow connections  
- **Comprehensive Analysis**: Supports JavaScript, TypeScript, JSON, Markdown, YAML, HTML, CSS, and more
- **AST Parsing**: Deep analysis of JavaScript/TypeScript files to extract imports, exports, functions, and components
- **Clean Output**: Generates well-formatted Markdown documentation

## Installation

### Global Installation (Recommended)
```bash
npm install -g fileflows
```

### Local Installation
```bash
npm install fileflows
```

### Development/Direct Use
```bash
npm install @babel/parser globby
```

## Usage

### Global Installation
```bash
# Analyze current directory (generates FILE_FLOWS.md)
fileflows

# Analyze specific directory  
fileflows --dir ./src

# Custom output file
fileflows --output my-flows.md

# Show help
fileflows --help
```

### Local Installation
```bash
# Using npx
npx fileflows

# Using npm scripts (if added to package.json)
npm run generate

# Direct node execution
node node_modules/fileflows/cli.js
```

### Development/Direct Use
```bash
# Clone or download the repository, then:
node cli.js                    # Analyze current directory
node cli.js --dir ./src        # Analyze src directory  
node cli.js --output flows.md  # Custom output file
node cli.js --help            # Show help
```

## How It Works

1. **File Discovery**: Scans project for all relevant file types, excluding common build/cache directories
2. **Dependency Analysis**: Parses JavaScript/TypeScript files to extract import/export relationships
3. **Flow Clustering**: Groups files that share data flow relationships using graph analysis
4. **Naming Fallback**: Groups remaining files by filename similarity patterns
5. **Documentation Generation**: Creates comprehensive Markdown with file metadata

## File Types Supported

- **Code**: `.js`, `.ts`, `.jsx`, `.tsx`
- **Config**: `.json`, `.yml`, `.yaml`, `.env`
- **Documentation**: `.md`
- **Web**: `.html`, `.css`, `.scss`
- **Other**: `.sh`, `.graphql`

## Output Format

The generated `FILE_FLOWS.md` includes:

- Flow groups based on actual relationships
- File type classification
- Extracted metadata (imports, exports, functions, etc.)
- Clear structure for understanding project architecture

## Example Output

```markdown
# FILE_FLOWS
> Auto-generated. Do not edit directly.
> Files grouped by PRIMARY: actual data flow relationships, SECONDARY: filename similarity.

### 🧩 Flow Group: `auth-flow`

## [1] `src/auth/login.js`
**Type:** Feature Logic/UI
**Imports:** ./auth-api, ./validators
**Exports:** LoginComponent, validateLogin
**Functions:** LoginComponent, validateLogin, handleSubmit

---
```

## Command Line Options

```
Usage: node cli.js [options]

Options:
  --dir <path>     Directory to analyze (default: current directory)
  --output <file>  Output file path (default: FILE_FLOWS.md)
  --help, -h       Show this help message

Examples:
  node cli.js                    # Analyze current directory
  node cli.js --dir ./src        # Analyze src directory
  node cli.js --output flows.md  # Custom output file
```

This tool preserves all the sophisticated analysis capabilities of the original system while providing a clean, focused CLI interface.