npm package: @sahm-org/ai-context-generator
Description: Enterprise-grade codebase context generator for AI assistants
Author: SAHM-ORG
Latest version: 1.0.0

# 🤖 AI Context Generator - Enterprise Edition

<p align="center">
  <strong>Professional codebase context generation for AI assistants</strong>
</p>

<p align="center">
  Generate comprehensive, AI-optimized documentation of your entire codebase with a single command.
</p>

---

## 📋 Table of Contents

- [Overview](#-overview)
- [Features](#-features)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Usage](#-usage)
- [Configuration](#-configuration)
- [Output Format](#-output-format)
- [Advanced Usage](#-advanced-usage)
- [API Reference](#-api-reference)
- [Examples](#-examples)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [License](#-license)

---

## 🎯 Overview

**AI Context Generator** is an enterprise-grade tool that scans your codebase and generates comprehensive documentation optimized for consumption by AI assistants like ChatGPT, Claude, and GitHub Copilot. It creates a single, well-structured markdown (or JSON) file containing your entire project's structure and code.

### Why Use This Tool?

When working with AI coding assistants, providing full codebase context dramatically improves the quality of suggestions and responses. This tool automates the process of creating that context.

**Perfect for:**

- 🤖 Working with AI coding assistants (ChatGPT, Claude, etc.)
- 📚 Onboarding new team members
- 📖 Generating project documentation
- 🔍 Code review preparation
- 💾 Creating project snapshots

---

## ✨ Features

### Core Features

- **🌳 Directory Tree Visualization** - Beautiful ASCII tree structure with emoji icons
- **📄 File Content Extraction** - Complete source code with syntax highlighting hints
- **📊 Comprehensive Statistics** - File counts, sizes, processing metrics
- **🎯 Smart Filtering** - Respects `.gitignore` and custom ignore patterns
- **🔒 Binary Detection** - Automatically skips binary and media files
- **⚡ Performance** - Fast scanning with configurable depth limits
- **📝 Multiple Formats** - Markdown (default) and JSON output
- **🎨 Syntax Highlighting** - Language detection for 30+ file types

### Advanced Features

- **.contextignore Support** - Custom ignore patterns beyond `.gitignore`
- **File Size Limits** - Skip files exceeding size threshold
- **Error Resilience** - Gracefully handles permission errors and unreadable files
- **Metadata Extraction** - File sizes, modification dates, line counts
- **Token Estimation** - Approximate token count for AI models
- **Dry Run Mode** - Preview what will be generated
- **Verbose Logging** - Detailed debug information
- **Configuration Files** - Multiple config file formats supported
- **Environment Variables** - Override settings via env vars
- **Programmatic API** - Use as a library in your Node.js apps

---

## 📦 Installation

### Prerequisites

- Node.js >= 14.0.0
- npm or yarn

### Install via npm

```bash
npm install -g @SAHM-ORG/ai-context-generator
```

### Install from source

````bash
# Clone repository
git clone https://github.com/SAHM-ORG/ai-context-generator.git
cd ai-context-generator

# Install dependencies
npm install

# Link globally
npm link
### Quick Start
Basic Usage
```bash

# Generate context for current directory
gen-context

# Scan specific directory
gen-context --path ./src

# Custom output file
gen-context --output my-project-context.md
````

The output file will contain:

- Project metadata
- Directory tree structure
- Statistics
- Complete file contents with syntax highlighting

## Usage

Command Line Interface

````bash


gen-context [options]
Options
Option
Description
Default


-p, --path <path>	Root directory to scan	Current directory
-o, --output <file>	Output file path	ai-context.md
-c, --config <file>	Configuration file	context.config.js
-m, --max-size <kb>	Max file size in KB	1024 (1MB)
-d, --max-depth <n>	Max directory depth	10
--no-tree	Skip tree generation	-
--no-content	Skip file contents	-
--no-stats	Skip statistics	-
-i, --include <patterns>	Additional file patterns	-
-e, --exclude <patterns>	Additional exclude patterns	-
--format <type>	Output format (markdown/json)	markdown
--verbose	Enable debug logging	-
--silent	Suppress output	-
--dry-run	Preview without writing	-
-v, --version	Show version	-
-h, --help	Show help	-
Examples
```bash


# Full project scan with verbose output
gen-context --verbose

# Scan only JavaScript/TypeScript files
gen-context --include ".js,.ts,.jsx,.tsx"

# Exclude test files
gen-context --exclude "*.test.js,*.spec.js"

# Generate tree only (no file contents)
gen-context --no-content

# JSON output format
gen-context --format json --output project.json

# Dry run to preview
gen-context --dry-run --verbose

# Limit file size and depth
gen-context --max-size 500 --max-depth 5
## Configuration
### Configuration Files
Create a context.config.js in your project root:

```javascript


module.exports = {
  // Output settings
  outputFile: 'ai-context.md',
  format: 'markdown',

  // Scanning settings
  maxFileSize: 1024 * 1024, // 1MB
  maxDepth: 10,

  // Ignore patterns (gitignore-style)
  ignorePatterns: [
    'node_modules/**',
    'dist/**',
    '**/*.test.js'
  ],

  // File extensions to include
  fileExtensions: [
    '.js', '.ts', '.jsx', '.tsx',
    '.json', '.md', '.css'
  ],

  // Feature toggles
  includeTree: true,
  includeContent: true,
  includeStats: true,
  includeMetadata: true,
  includeToc: true,
  showFileSizes: false,

  // Behavior
  useGitignore: true,
  verbose: false,
  silent: false,
  dryRun: false
};
````

## Alternative Config Formats

### JSON (.contextrc.json)

````json


{
  "outputFile": "ai-context.md",
  "maxFileSize": 1048576,
  "ignorePatterns": ["node_modules/**", "dist/**"]
}
### JavaScript (.contextrc.js)
```javascript


module.exports = {
  outputFile: 'context.md',
  ignorePatterns: ['node_modules/**']
};
````

## .contextignore File

Create a .contextignore file (same syntax as .gitignore):

````gitignore
# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/
out/

# IDE
.vscode/
.idea/

# Logs
*.log
logs/

# Environment
.env
.env.*

# Test coverage
coverage/
## Environment Variables
Override configuration with environment variables:

```bash


export CONTEXT_MAX_SIZE=512      # Max file size in KB
export CONTEXT_MAX_DEPTH=8       # Max directory depth
export CONTEXT_OUTPUT=output.md  # Output file
export CONTEXT_FORMAT=json       # Output format

gen-context
````

## Output Format

### Markdown Structure

````markdown
# 📚 AI Codebase Context

## 📋 Document Metadata

[Project info, generation time, file counts, token estimates]

## 📖 Table of Contents

[Auto-generated TOC]

## 🌳 Directory Structure

[ASCII tree visualization]

## 📊 Statistics

[Detailed metrics and error reports]

## 📄 File Contents

[Individual file contents with metadata and syntax highlighting]

## 📌 Notes

[Usage tips and warnings]

### JSON Structure

```json
{
  "metadata": {
    "projectName": "my-project",
    "generated": "2025-01-25T18:19:00.000Z",
    "version": "1.0.0"
  },
  "statistics": { ... },
  "tree": "...",
  "content": "...",
  "config": { ... }
}
```
````

## Advanced Usage

### Programmatic API

````javascript


const ContextGenerator = require('@SAHM-ORG/ai-context-generator');

const generator = new ContextGenerator({
  rootPath: './my-project',
  outputFile: 'context.md',
  maxFileSize: 512 * 1024,
  ignorePatterns: ['node_modules/**'],
  fileExtensions: ['.js', '.ts'],
  verbose: true
});

// Generate context
generator.generate()
  .then(results => {
    console.log('Success!', results);
  })
  .catch(error => {
    console.error('Failed:', error);
  });
### Custom Processing
```javascript


const { Scanner, TreeGenerator, ContentExtractor } = require('@SAHM-ORG/ai-context-generator');

// Use individual components
const scanner = new Scanner(config, logger);
const fileTree = await scanner.scan('./src');
const stats = scanner.getStatistics();

console.log(`Found ${stats.totalFiles} files`);
### Integration with Build Tools
#### package.json script
```json


{
  "scripts": {
    "gen-context": "gen-context --path ./src --output docs/ai-context.md",
    "pre-commit": "npm run gen-context"
  }
}
### GitHub Actions
```yaml


name: Generate Context

on: [push]

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
      - run: npm install -g @SAHM-ORG/ai-context-generator
      - run: gen-context --output context.md
      - uses: actions/upload-artifact@v2
        with:
          name: context
          path: context.md

````

## API Reference

### ContextGenerator

Main class for generating context.

```javascript
const generator = new ContextGenerator(config);
await generator.generate();
```

### Configuration Options

See Configuration section for all options.

### Methods

generate() - Execute generation process
Returns: Promise<Object> with results
Scanner
File system scanner.

```javascript


const scanner = new Scanner(config, logger);
const fileTree = await scanner.scan(rootPath);
const stats = scanner.getStatistics();
TreeGenerator
Generates ASCII tree visualization.
```

```javascript


const treeGen = new TreeGenerator(config, logger);
const tree = treeGen.generate(fileTree);
ContentExtractor
Extracts file contents.
```

```javascript


const extractor = new ContentExtractor(config, logger);
const content = await extractor.extract(fileTree);
OutputFormatter
Formats final output.
```

```javascript
const formatter = new OutputFormatter(config, logger);
const output = formatter.format({ tree, content, statistics, config });
```

💡 Examples
Example 1: React Project

```bash


gen-context \
  --path ./my-react-app \
  --include ".js,.jsx,.ts,.tsx,.json,.css" \
  --exclude "*.test.js,*.spec.js" \
  --output react-context.md
```

Example 2: Python Project

````bash


gen-context \
  --path ./my-python-app \
  --include ".py,.yaml,.yml,.toml" \
  --max-depth 8 \
  --output python-context.md
Example 3: Large Monorepo
```bash


gen-context \
  --path ./monorepo/packages/core \
  --max-size 500 \
  --max-depth 6 \
  --no-metadata \
  --output core-context.md
🐛 Troubleshooting
Common Issues
1. "Permission denied" errors
```bash


# Run with sudo (not recommended) or fix permissions
chmod -R +r ./your-project
gen-context
````

2. Output file too large

```bash


# Reduce file size limit or exclude more patterns
gen-context --max-size 256 --exclude "*.json,*.lock"
```

3. Missing files in output

```bash


# Check ignore patterns and file extensions
gen-context --verbose --dry-run
```

4. Slow performance

```bash


# Reduce depth or exclude large directories
gen-context --max-depth 5 --exclude "node_modules/**,dist/**"
```

Debug Mode

````bash


# Enable verbose logging to see what's happening
gen-context --verbose --dry-run
Getting Help
📖 Documentation
🐛 Issue Tracker
💬 Discussions
🤝 Contributing
We welcome contributions! Please see CONTRIBUTING.md [blocked] for details.

Development Setup
```bash


git clone https://github.com/SAHM-ORG/ai-context-generator.git
cd ai-context-generator
npm install
npm link
````

Run Tests

```bash


npm test
```

📝 License
MIT License - see LICENSE [blocked] for details.

🙏 Acknowledgments
Built with ❤️ by SAHM-ORG

Dependencies:

- Commander.js - CLI framework
- Chalk - Terminal styling
- Ora - Spinners
- ignore - Gitignore parser
- Made with ❤️ for the AI development community