fileflows 1.0.0

package/README.md

@@ -0,0 +1,105 @@
+# File Flows 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/file-flows-cli.svg)](https://badge.fury.io/js/file-flows-cli)
+[![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 file-flows-cli
+```
+
+### Local Installation
+```bash
+npm install file-flows-cli
+```
+
+### Development/Direct Use
+```bash
+npm install @babel/parser globby
+```
+
+## Usage
+
+### Global Installation
+```bash
+# Analyze current directory (generates FILE_FLOWS.md)
+file-flows
+
+# Analyze specific directory  
+file-flows --dir ./src
+
+# Custom output file
+file-flows --output my-flows.md
+
+# Show help
+file-flows --help
+```
+
+### Local Installation
+```bash
+# Using npx
+npx file-flows
+
+# Using npm scripts
+npm run file-flows
+
+# Direct node execution
+node node_modules/file-flows-cli/cli-file-flows.js
+```
+
+## 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
+
+---
+```
+
+This tool preserves all the sophisticated analysis capabilities of the original system while providing a clean, focused CLI interface.

package/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * CLI tool for generating FILE_FLOWS.md
+ * Analyzes project files and creates documentation showing data flow relationships
+ * Following NPM architecture guidelines with modular structure
+ */
+
+const generateFileFlows = require(`./lib/fileFlowsGenerator`);
+const localVars = require(`./config/localVars`);
+
+/**
+ * CLI usage display functionality
+ * Shows help information for the CLI tool
+ */
+function showUsage() {
+  console.log(`Usage: node cli.js [options]`);
+  console.log(``);
+  console.log(`Options:`);
+  console.log(`  --dir <path>     Directory to analyze (default: current directory)`);
+  console.log(`  --output <file>  Output file path (default: FILE_FLOWS.md)`);
+  console.log(`  --help, -h       Show this help message`);
+  console.log(``);
+  console.log(`Examples:`);
+  console.log(`  node cli.js                    # Analyze current directory`);
+  console.log(`  node cli.js --dir ./src        # Analyze src directory`);
+  console.log(`  node cli.js --output flows.md  # Custom output file`);
+}
+
+/**
+ * Main CLI logic
+ * Parses arguments and executes file flows generation
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  let rootDir = localVars.DEFAULT_ROOT_DIR;
+  let outputFile = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg === `--help` || arg === `-h`) {
+      showUsage();
+      process.exit(0);
+    } else if (arg === `--dir`) {
+      if (i + 1 < args.length) {
+        rootDir = args[++i];
+      } else {
+        console.error(`Error: --dir requires a directory path`);
+        process.exit(1);
+      }
+    } else if (arg === `--output`) {
+      if (i + 1 < args.length) {
+        outputFile = args[++i];
+      } else {
+        console.error(`Error: --output requires a file path`);
+        process.exit(1);
+      }
+    } else {
+      console.error(`Error: Unknown argument '${arg}'`);
+      showUsage();
+      process.exit(1);
+    }
+  }
+
+  try {
+    console.log(`🚀 Generating FILE_FLOWS.md...`);
+    await generateFileFlows(rootDir, outputFile);
+    console.log(`🎉 Generation complete!`);
+  } catch (error) {
+    console.error(`❌ Error:`, error.message);
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+module.exports = { showUsage, main };

package/config/localVars.js

@@ -0,0 +1,48 @@
+/**
+ * Configuration constants and environment variables
+ * Single source of truth for all hardcoded values in the application
+ * Following NPM architecture guidelines - DO NOT modify existing values
+ */
+// 🚩AI: MUST_UPDATE_IF_FILE_EXTENSIONS_CHANGE
+
+// === FILE ANALYSIS CONSTANTS ===
+const CODE_EXTENSIONS = [`js`, `ts`, `jsx`, `tsx`];
+const ALL_EXTENSIONS = [...CODE_EXTENSIONS, `json`, `md`, `yml`, `yaml`, `env`, `html`, `css`, `scss`, `sh`, `graphql`];
+
+// === DEFAULT PATHS ===
+const DEFAULT_ROOT_DIR = `.`;
+const DEFAULT_OUTPUT_FILE = `FILE_FLOWS.md`;
+
+// === GITIGNORE PATTERNS ===
+const IGNORE_PATTERNS = [
+  `**/node_modules/**`,
+  `**/.config/**`,
+  `**/logs/**`,
+  `**/.git/**`,
+  `**/tmp/**`,
+  `**/temp/**`,
+  `**/.npm/**`,
+  `**/.cache/**`,
+  `**/dist/**`,
+  `**/build/**`,
+  `**/.next/**`,
+  `**/.nuxt/**`
+];
+
+// === PARSING LIMITS ===
+const MAX_JSON_KEYS = 10;
+const MAX_YAML_KEYS = 5;
+const MAX_SHELL_COMMANDS = 5;
+const MAX_HTML_TAGS = 5;
+
+module.exports = {
+  CODE_EXTENSIONS,
+  ALL_EXTENSIONS,
+  DEFAULT_ROOT_DIR,
+  DEFAULT_OUTPUT_FILE,
+  IGNORE_PATTERNS,
+  MAX_JSON_KEYS,
+  MAX_YAML_KEYS,
+  MAX_SHELL_COMMANDS,
+  MAX_HTML_TAGS
+};

package/config/localVars.test.js

@@ -0,0 +1,37 @@
+// Auto-generated unit test for localVars.js - optimized for speed
+const mod = require('./localVars.js');
+
+describe('localVars.js', () => {
+  test('CODE_EXTENSIONS works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.CODE_EXTENSIONS).toBeDefined();
+  });
+  test('ALL_EXTENSIONS works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.ALL_EXTENSIONS).toBeDefined();
+  });
+  test('DEFAULT_ROOT_DIR works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.DEFAULT_ROOT_DIR).toBeDefined();
+  });
+  test('DEFAULT_OUTPUT_FILE works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.DEFAULT_OUTPUT_FILE).toBeDefined();
+  });
+  test('IGNORE_PATTERNS works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.IGNORE_PATTERNS).toBeDefined();
+  });
+  test('MAX_JSON_KEYS works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.MAX_JSON_KEYS).toBeDefined();
+  });
+  test('MAX_YAML_KEYS works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.MAX_YAML_KEYS).toBeDefined();
+  });
+  test('MAX_SHELL_COMMANDS works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.MAX_SHELL_COMMANDS).toBeDefined();
+  });
+});

package/index.js

@@ -0,0 +1,8 @@
+/**
+ * Main entry point for the file-flows-cli NPM module
+ * Exports public functionality following NPM architecture guidelines
+ */
+
+const { generateFileFlows } = require(`./lib/index`);
+
+module.exports = generateFileFlows;

package/lib/SUMMARY.md

@@ -0,0 +1,53 @@
+# lib/ Directory Summary
+
+## Overview
+Core library modules for FILE_FLOWS.md generation, following Single Responsibility Principle with one function per file.
+
+## File Roles & Data Flow
+
+### Entry Points
+- **index.js** - Main module aggregator, exports all lib functions for external use
+- **fileFlowsGenerator.js** - Primary orchestrator, coordinates analysis and output generation
+
+### Analysis Pipeline
+1. **fileClassifier.js** - Classifies files by type (Code, Configuration, Documentation, etc.)
+2. **jsParser.js** - AST parsing for JavaScript/TypeScript files, extracts functions and imports
+3. **otherFileParser.js** - Simple parsing for non-JS files (JSON, MD, etc.)
+4. **dependencyExtractor.js** - Extracts import/require dependencies from file content
+
+### Grouping & Output
+5. **dataFlowGrouper.js** - Groups files by actual data flow relationships and naming patterns
+
+## Request/Response Flows
+
+### Main Generation Flow
+```
+generateFileFlows(rootDir, outputFile)
+├── globby scan for files
+├── groupByDataFlow(files, rootDir)
+│   ├── classifyFile(filePath, ext) for each file
+│   ├── parseJSFile(filePath, content) OR parseOtherFile(filePath, content)
+│   ├── extractDependencies(content) for dependency mapping
+│   └── clustering algorithms for flow grouping
+└── markdown output generation
+```
+
+### Data Dependencies
+- **config/localVars.js** - Centralized constants (file extensions, ignore patterns, etc.)
+- **External**: globby (file discovery), @babel/parser & @babel/traverse (AST parsing)
+
+## Known Side Effects
+- **File System**: Reads all project files matching configured extensions
+- **Output**: Overwrites FILE_FLOWS.md without backup
+- **Memory**: Processes entire project file tree in memory
+- **Performance**: AST parsing scales with codebase size
+
+## Edge Cases & Caveats
+- **Large Projects**: Memory usage grows with file count and complexity
+- **Binary Files**: Ignored via gitignore patterns but may cause issues if included
+- **Circular Dependencies**: Detected but may create complex flow groups
+- **ES Modules vs CommonJS**: Mixed module systems handled via dynamic imports
+- **Parse Errors**: Individual file failures don't stop overall generation
+
+## AI Agent Task Anchors
+See individual files for specific `// 🚩AI:` markers indicating critical update points.

package/lib/dataFlowGrouper.js

@@ -0,0 +1,150 @@
+/**
+ * Data flow grouping functionality
+ * Groups files by actual data flow relationships (imports/exports)
+ * @param {Array} fileList - List of files to analyze
+ * @param {string} rootDir - Root directory path
+ * @returns {Promise<Map>} Map of grouped files by data flow relationships
+ */
+// 🚩AI: CORE_DATA_FLOW_ANALYSIS_ALGORITHM
+async function groupByDataFlow(fileList, rootDir) {
+  const fs = require(`fs`);
+  const path = require(`path`);
+  const localVars = require(`../config/localVars`);
+  const parseJSFile = require(`./jsParser`);
+  const parseOtherFile = require(`./otherFileParser`);
+  const classifyFile = require(`./fileClassifier`);
+  const extractDependencies = require(`./dependencyExtractor`);
+  
+  const dependencyGraph = new Map();
+  const fileMetadata = new Map();
+  
+  // Build dependency graph by analyzing imports/exports
+  for (const filePath of fileList) {
+    const fullPath = path.join(rootDir, filePath);
+    const ext = path.extname(filePath).slice(1);
+    
+    try {
+      const content = fs.readFileSync(fullPath, `utf8`);
+      let metadata = {};
+      
+      if (localVars.CODE_EXTENSIONS.includes(ext)) {
+        metadata = parseJSFile(content, filePath);
+      } else {
+        metadata = parseOtherFile(content, filePath, ext);
+      }
+      
+      fileMetadata.set(filePath, {
+        ...metadata,
+        type: classifyFile(filePath, ext),
+        dependencies: extractDependencies(metadata.Imports || [], filePath, fileList)
+      });
+      
+      dependencyGraph.set(filePath, metadata.Imports || []);
+    } catch (error) {
+      // File read error - skip this file
+      dependencyGraph.set(filePath, []);
+    }
+  }
+  
+  // Group files by connected components in dependency graph
+  const visited = new Set();
+  const groups = new Map();
+  let groupCounter = 1;
+  
+  function dfs(file, groupName, group) {
+    if (visited.has(file)) return;
+    visited.add(file);
+    group.push(file);
+    
+    // Visit all files that this file imports
+    const deps = fileMetadata.get(file)?.dependencies || [];
+    for (const dep of deps) {
+      if (!visited.has(dep)) {
+        dfs(dep, groupName, group);
+      }
+    }
+    
+    // Visit all files that import this file
+    for (const [otherFile, otherDeps] of fileMetadata) {
+      if (!visited.has(otherFile) && otherDeps.dependencies?.includes(file)) {
+        dfs(otherFile, groupName, group);
+      }
+    }
+  }
+  
+  // Create connected components
+  for (const file of fileList) {
+    if (!visited.has(file)) {
+      const group = [];
+      const groupName = `Group-${groupCounter++}`;
+      dfs(file, groupName, group);
+      
+      if (group.length > 0) {
+        groups.set(groupName, group);
+      }
+    }
+  }
+  
+  // SECONDARY: Use filename similarity for files without clear connections
+  const ungroupedFiles = fileList.filter(f => !visited.has(f));
+  if (ungroupedFiles.length > 0) {
+    const similarityGroups = groupBySimilarity(ungroupedFiles);
+    for (const [name, files] of similarityGroups) {
+      groups.set(`Similarity-${name}`, files);
+    }
+  }
+  
+  // Convert Map to Array format expected by tests
+  const groupArray = [];
+  for (const [groupName, files] of groups) {
+    groupArray.push({
+      name: groupName,
+      files: files,
+      metadata: files.map(f => fileMetadata.get(f)).filter(Boolean)
+    });
+  }
+  
+  return groupArray;
+}
+
+/**
+ * Groups files by filename similarity when no data flow connections exist
+ * @param {Array} files - Array of file paths
+ * @returns {Map} Map of similarity-based groups
+ */
+function groupBySimilarity(files) {
+  const path = require(`path`);
+  const groups = new Map();
+  
+  for (const file of files) {
+    const basename = path.basename(file, path.extname(file));
+    const parts = basename.split(/[-_.]/).filter(p => p.length > 2);
+    
+    let bestGroup = null;
+    let maxSimilarity = 0;
+    
+    for (const [groupName, groupFiles] of groups) {
+      const groupBasename = path.basename(groupFiles[0], path.extname(groupFiles[0]));
+      const groupParts = groupBasename.split(/[-_.]/).filter(p => p.length > 2);
+      
+      const commonParts = parts.filter(p => groupParts.includes(p));
+      const similarity = commonParts.length / Math.max(parts.length, groupParts.length);
+      
+      if (similarity > maxSimilarity && similarity > 0.3) {
+        maxSimilarity = similarity;
+        bestGroup = groupName;
+      }
+    }
+    
+    if (bestGroup) {
+      groups.get(bestGroup).push(file);
+    } else {
+      const key = parts.length > 0 ? parts[0] : basename;
+      groups.set(key, [file]);
+    }
+  }
+  
+  return groups;
+}
+
+module.exports = groupByDataFlow;

package/lib/dataFlowGrouper.test.js

@@ -0,0 +1,17 @@
+// Auto-generated unit test for dataFlowGrouper.js - optimized for speed
+const mod = require('./dataFlowGrouper.js');
+
+describe('dataFlowGrouper.js', () => {
+  test('groupByDataFlow works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.groupByDataFlow).toBeDefined();
+  });
+  test('dfs works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.dfs).toBeDefined();
+  });
+  test('groupBySimilarity works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.groupBySimilarity).toBeDefined();
+  });
+});

package/lib/dependencyExtractor.js

@@ -0,0 +1,70 @@
+/**
+ * Dependency extraction functionality
+ * Extracts and resolves file dependencies from import statements
+ * @param {Array} imports - Array of import statements
+ * @param {string} currentFile - Current file path
+ * @param {Array} fileList - List of all files in the project
+ * @returns {Array} Array of resolved dependencies
+ */
+function extractDependencies(imports, currentFile, fileList) {
+  const path = require(`path`);
+  const dependencies = [];
+  
+  for (const imp of imports) {
+    if (imp.startsWith(`.`)) {
+      // Relative import - try to resolve to actual file  
+      const basePath = path.dirname(currentFile);
+      let resolvedPath = path.normalize(path.join(basePath, imp));
+      
+      // Convert to forward slashes for cross-platform compatibility
+      resolvedPath = resolvedPath.replace(/\\/g, '/');
+      
+      // Handle different resolution scenarios:
+      // If resolvedPath starts with project structure, normalize it
+      // Remove src/ prefix if it exists and the target doesn't include it
+      const pathParts = resolvedPath.split('/');
+      
+      // Try original resolved path first, then variations
+      const possibleBasePaths = [
+        resolvedPath,
+        // Remove 'src/' prefix if present
+        pathParts[0] === 'src' ? pathParts.slice(1).join('/') : null,
+        // Handle cases where path goes up from src/ 
+        resolvedPath.replace(/^src\//, '')
+      ].filter(p => p && p !== resolvedPath); // Remove nulls and duplicates
+      
+      const allPossiblePaths = [resolvedPath, ...possibleBasePaths];
+      
+      // Try to find matching file with common extensions for each base path
+      for (const basePath of allPossiblePaths) {
+        if (!basePath) continue;
+        
+        const possiblePaths = [
+          basePath,
+          basePath + `.js`,
+          basePath + `.ts`, 
+          basePath + `.jsx`,
+          basePath + `.tsx`,
+          basePath + `/index.js`,
+          basePath + `/index.ts`
+        ];
+        
+        for (const possiblePath of possiblePaths) {
+          if (fileList.includes(possiblePath)) {
+            dependencies.push(possiblePath);
+            break;
+          }
+        }
+        
+        // If we found a match, stop looking
+        if (dependencies.some(dep => allPossiblePaths.some(base => dep.startsWith(base)))) {
+          break;
+        }
+      }
+    }
+  }
+  
+  return dependencies;
+}
+
+module.exports = extractDependencies;

package/lib/dependencyExtractor.test.js

@@ -0,0 +1,9 @@
+// Auto-generated unit test for dependencyExtractor.js - optimized for speed
+const mod = require('./dependencyExtractor.js');
+
+describe('dependencyExtractor.js', () => {
+  test('extractDependencies works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.extractDependencies).toBeDefined();
+  });
+});

package/lib/fileClassifier.js

@@ -0,0 +1,38 @@
+/**
+ * File classification functionality
+ * Classifies files based on their path and extension
+ * @param {string} filePath - The file path to classify
+ * @param {string} ext - The file extension
+ * @returns {string} Classification of the file type
+ */
+function classifyFile(filePath, ext) {
+  const localVars = require(`../config/localVars`);
+  
+  if (localVars.CODE_EXTENSIONS.includes(ext)) {
+    // TSX files are specifically React/UI components (check first)
+    if (ext === `tsx`) return `UI Component`;
+    if (filePath.includes(`test`) || filePath.includes(`spec`)) return `Test File`;
+    if (filePath.includes(`component`) || filePath.includes(`Component`)) return `UI Component`;
+    if (filePath.includes(`api`) || filePath.includes(`route`)) return `API/Route`;
+    if (filePath.includes(`util`) || filePath.includes(`helper`)) return `Utility`;
+    if (filePath.includes(`config`) || filePath.includes(`setting`)) return `Configuration`;
+    if (filePath.includes(`model`) || filePath.includes(`schema`)) return `Data Model`;
+    return `Code File`;
+  }
+  
+  switch (ext) {
+    case `json`: return `Configuration/Data`;
+    case `md`: return `Documentation`;
+    case `yml`:
+    case `yaml`: return `Configuration`;
+    case `env`: return `Environment`;
+    case `html`: return `Template/View`;
+    case `css`:
+    case `scss`: return `Stylesheet`;
+    case `sh`: return `Script`;
+    case `graphql`: return `Schema`;
+    default: return `Other`;
+  }
+}
+
+module.exports = classifyFile;

package/lib/fileClassifier.test.js

@@ -0,0 +1,9 @@
+// Auto-generated unit test for fileClassifier.js - optimized for speed
+const mod = require('./fileClassifier.js');
+
+describe('fileClassifier.js', () => {
+  test('classifyFile works', async () => {
+    // Fast assertion - TODO: implement specific test logic
+    expect(typeof mod.classifyFile).toBeDefined();
+  });
+});