FileFlows CLI

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

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)

npm install -g fileflows

Local Installation

npm install fileflows

Development/Direct Use

npm install @babel/parser globby

Usage

Global Installation

# 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

# 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

# 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

# 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.