ansa-fs

A lightweight and flexible Node.js package to extract and visualize file system structures with advanced code analysis.

Features

• Core Functionality

  • Extract file and directory structures from any directory
  • Visualize as a tree, JSON, or list of paths
  • Configurable depth and filtering options
  • Ignore specific files, directories, or extensions

• Analysis Tools

  • Get statistics about your project structure
  • Compare two directory structures and find differences
  • Analyze file content and detect programming languages
  • Calculate file hashes and track modification times
  • Analyze code complexity across multiple languages
  • Generate interactive HTML reports with visualizations

• Advanced Analysis

  • Code Duplication Detection: Find duplicate or similar code blocks
  • Dependency Graph Visualization: Analyze and visualize project dependencies
  • Technical Debt Analysis: Identify TODOs, complex files, and outdated patterns
  • Git History Analysis: Understand file evolution and contributor patterns
  • Documentation Generation: Create comprehensive project documentation
  • Code Quality Analysis: Identify code quality issues and best practices
  • Security Vulnerability Detection: Find potential security vulnerabilities
  • Performance Analysis: Identify performance bottlenecks and issues
  • Accessibility Analysis: Check for accessibility issues in web files
  • Framework Detection: Automatically detect frameworks and libraries used
  • Codebase Evolution Simulator: Predict future maintenance challenges

• Output Options

  • Export structures to Markdown
  • Export to interactive HTML with charts and visualizations
  • Watch directories for changes in real-time
  • Use as a CLI tool or programmatically in your Node.js projects

Installation

Global Installation (for CLI usage)

npm install -g ansa-fs

Local Installation (for programmatic usage)

npm install ansa-fs

CLI Usage

Basic Usage

# Scan current directory
ansa-fs

# Scan specific directory
ansa-fs ./src

# Limit depth to 2 levels
ansa-fs --depth 2 ./my-project

# Ignore specific directories
ansa-fs --ignore node_modules --ignore .git

Output Options

# Output as JSON
ansa-fs --json

# Output as a list of paths
ansa-fs --paths

# Show statistics
ansa-fs --stats

# Export as Markdown
ansa-fs --markdown

# Export as interactive HTML
ansa-fs --html

# Export as interactive HTML with dark mode
ansa-fs --html --dark-mode

# Write output to a file
ansa-fs --output structure.json --json

# Generate HTML report
ansa-fs --html --output report.html

# Detect frameworks and generate HTML report
ansa-fs --detect-frameworks --output frameworks-report.html --html

Advanced Analysis Features

# Analyze code complexity
ansa-fs --analyze-complexity

# Set complexity threshold
ansa-fs --analyze-complexity --complexity-threshold medium

# Include detailed complexity metrics
ansa-fs --analyze-complexity --detailed-complexity

# Detect code duplication
ansa-fs --analyze-duplication --output duplication-report.html --html

# Analyze project dependencies
ansa-fs --analyze-dependencies --output dependency-graph.html --html

# Analyze technical debt
ansa-fs --analyze-tech-debt --output tech-debt-report.html --html

# Analyze git history
ansa-fs --analyze-git --output git-report.html --html

# Generate project documentation
ansa-fs --generate-docs

# Generate documentation in specific format
ansa-fs --generate-docs --docs-format html

# Customize documentation output
ansa-fs --generate-docs --docs-title "My Project Docs" --docs-output-dir "./project-docs"

# Analyze code quality
ansa-fs --analyze-quality --output quality-report.html --html

# Analyze security vulnerabilities
ansa-fs --analyze-security --output security-report.html --html

# Analyze performance issues
ansa-fs --analyze-performance --output performance-report.html --html

# Analyze accessibility issues
ansa-fs --analyze-accessibility --output accessibility-report.html --html

# Detect frameworks and libraries
ansa-fs --detect-frameworks

# Generate HTML report of detected frameworks
ansa-fs --detect-frameworks --output frameworks-report.html --html

# Simulate codebase evolution
ansa-fs --simulate-evolution --output evolution-report.html --html

# Compare evolution scenarios
ansa-fs --simulate-evolution --compare-scenarios --timespan 24 --output evolution-scenarios.html --html

# Compare two directories
ansa-fs --diff ./other-dir

# Watch for changes
ansa-fs --watch

Programmatic Usage

Basic Usage

import { extractStructure, formatAsTree } from 'ansa-fs';

async function example() {
  // Extract the structure of a directory
  const structure = await extractStructure('./my-project');
  
  // Format and print as a tree
  console.log(formatAsTree(structure));
}

example();

Using Advanced Analysis Features

import { 
  extractStructure,
  analyzeDuplication,
  analyzeDependencies,
  analyzeTechDebt,
  analyzeGitHistory,
  analyzeDocumentation,
  analyzeCodeQuality,
  analyzeSecurityVulnerabilities,
  analyzePerformanceIssues,
  analyzeAccessibilityIssues,
  detectFrameworks,
  generateFrameworkReport,
  simulateCodebaseEvolution,
  generateEvolutionVisualization,
  generateEvolutionScenarios,
  generateScenariosComparison
} from 'ansa-fs';
import fs from 'fs';

async function analyzeProject() {
  // Extract structure with content and analysis options
  const structure = await extractStructure('./my-project', {
    includeContent: true,
    detectLanguage: true,
    analyzeComplexity: true,
    analyzeQuality: true,
    analyzeSecurity: true,
    analyzePerformance: true,
    analyzeAccessibility: true,
    includeFrameworkDetection: true,
    includeSize: true
  });
  
  // Simulate codebase evolution
  const evolutionResults = simulateCodebaseEvolution(structure, {
    timespan: 24, // months
    teamSize: 5,
    developmentVelocity: "medium",
    refactoringEffort: "medium"
  });
  
  // Generate evolution visualization
  const evolutionHtml = generateEvolutionVisualization(evolutionResults, {
    title: 'Codebase Evolution Simulation',
    darkMode: false
  });
  fs.writeFileSync('reports/evolution-report.html', evolutionHtml);
  
  // Generate and compare multiple evolution scenarios
  const scenarios = generateEvolutionScenarios(structure, {
    timespan: 24
  });
  
  const scenariosHtml = generateScenariosComparison(scenarios, {
    title: 'Evolution Scenarios Comparison',
    darkMode: false
  });
  fs.writeFileSync('reports/evolution-scenarios.html', scenariosHtml);
  
  console.log('Analysis reports generated successfully!');
}

analyzeProject();

API Reference

Main Functions

| Function | Description |-----|----- | extractStructure(dirPath, options) | Extract the file structure of a directory | formatAsTree(structure, options) | Format the structure as a tree string | toPaths(structure, options) | Convert the structure to an array of paths | filter(structure, predicate) | Filter the structure based on a predicate function | getStats(structure) | Get statistics about the structure | diffStructures(structureA, structureB, options) | Compare two directory structures | exportToMarkdown(structure, options) | Export the structure to Markdown | exportToHtml(structure, options) | Export the structure to interactive HTML | watchStructure(dirPath, callback, options) | Watch a directory for changes | analyzeCodeComplexity(content, language) | Analyze code complexity of a file

Advanced Analysis Functions

| Function | Description |-----|----- | analyzeDuplication(structure, options) | Detect code duplication in the project | generateDuplicationReport(results, options) | Generate HTML report for code duplication | analyzeDependencies(structure, options) | Analyze project dependencies | generateDependencyGraph(results, options) | Generate HTML visualization of dependencies | analyzeTechDebt(structure, options) | Analyze technical debt in the project | generateTechDebtReport(results, options) | Generate HTML report for technical debt | analyzeGitHistory(structure, options) | Analyze git history of the project | generateGitReport(results, options) | Generate HTML report for git history | analyzeDocumentation(structure, options) | Analyze and extract documentation from project | generateMarkdownDocumentation(documentation, options) | Generate Markdown documentation | generateHtmlDocumentation(documentation, options) | Generate HTML documentation with interactive features | analyzeCodeQuality(content, language) | Analyze code quality issues | generateQualityReport(results, options) | Generate HTML report for code quality | analyzeSecurityVulnerabilities(content, language) | Analyze security vulnerabilities | generateSecurityReport(results, options) | Generate HTML report for security vulnerabilities | analyzePerformanceIssues(content, language) | Analyze performance issues | generatePerformanceReport(results, options) | Generate HTML report for performance issues | analyzeAccessibilityIssues(content, language) | Analyze accessibility issues | generateAccessibilityReport(results, options) | Generate HTML report for accessibility issues | detectFrameworks(structure) | Detect frameworks and libraries used in project | generateFrameworkReport(results, options) | Generate HTML report for framework detection | simulateCodebaseEvolution(structure, options) | Simulate codebase evolution over time | generateEvolutionVisualization(results, options) | Generate HTML visualization of evolution simulation | generateEvolutionScenarios(structure, options) | Generate multiple evolution scenarios | generateScenariosComparison(scenarios, options) | Generate HTML comparison of evolution scenarios

Codebase Evolution Simulator

The Codebase Evolution Simulator uses advanced algorithms to predict how your codebase will evolve over time, helping you make informed architectural and process decisions.

Key Features

1. Predictive Complexity Modeling

   • Analyze current code patterns and predict how complexity will grow
   • Identify files likely to become maintenance hotspots
   • Simulate refactoring scenarios and their long-term impact
   • Generate complexity growth curves for different architectural decisions

2. Technical Debt Forecasting

   • Project future technical debt accumulation based on current patterns
   • Visualize debt accumulation timelines under different development scenarios
   • Identify optimal timing for major refactoring efforts
   • Calculate the "interest rate" on technical debt in specific areas

3. Team Collaboration Simulation

   • Model how different team sizes and structures would affect the codebase
   • Simulate knowledge distribution and potential knowledge silos
   • Predict onboarding difficulty for new team members over time
   • Identify areas that would benefit most from documentation improvements

4. Maintenance Cost Prediction

   • Estimate future maintenance costs based on code quality trends
   • Predict bug hotspots before they emerge
   • Calculate the ROI of preventative refactoring
   • Generate maintenance effort forecasts for budget planning

5. Scenario Comparison

   • Compare different development approaches side-by-side
   • Visualize the long-term impact of technical decisions
   • Identify the most sustainable development strategy
   • Optimize team structure and processes based on simulation results

Usage

import { 
  extractStructure, 
  simulateCodebaseEvolution, 
  generateEvolutionVisualization,
  generateEvolutionScenarios,
  generateScenariosComparison
} from 'ansa-fs';
import fs from 'fs';

async function simulateEvolution() {
  // Extract structure with necessary metrics
  const structure = await extractStructure('./my-project', {
    includeContent: true,
    detectLanguage: true,
    analyzeComplexity: true,
    analyzeQuality: true,
    analyzeSecurity: true,
    analyzePerformance: true,
    includeSize: true
  });
  
  // Run basic evolution simulation
  const evolutionResults = simulateCodebaseEvolution(structure, {
    timespan: 24, // months
    teamSize: 5,
    developmentVelocity: "medium",
    refactoringEffort: "medium"
  });
  
  // Generate visualization
  const evolutionHtml = generateEvolutionVisualization(evolutionResults);
  fs.writeFileSync('evolution-report.html', evolutionHtml);
  
  // Generate and compare multiple scenarios
  const scenarios = generateEvolutionScenarios(structure, {
    timespan: 24 // months
  });
  
  const scenariosHtml = generateScenariosComparison(scenarios);
  fs.writeFileSync('evolution-scenarios.html', scenariosHtml);
  
  console.log('Evolution simulation complete!');
  console.log(`Identified ${evolutionResults.hotspots.length} future maintenance hotspots.`);
}

simulateEvolution();

License

MIT

Author

David Ansa <[email protected]> // Detect frameworks and generate report const frameworkResults = detectFrameworks(structure); console.log('Detected frameworks:', frameworkResults.detected);

// Generate HTML report for framework detection const frameworkHtml = generateFrameworkReport(frameworkResults, { title: 'Framework Detection Report', darkMode: false }); fs.writeFileSync('reports/frameworks-report.html', frameworkHtml);