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

$3

``bash
npm install -g ansa-fs
`

$3

`shellscript
npm install ansa-fs
`

CLI Usage

$3

`shellscript


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
`

$3

`shellscript


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
`

$3

`shellscript


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

$3

`javascript
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();
`

$3

`javascript
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

$3

| 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




$3

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

$3

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

$3

`javascript
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 `
// 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);