@sahm-org/ai-context-generator

v1.0.0

Published

7 months ago

Enterprise-grade codebase context generator for AI assistants

Downloads

0High
0Medium
0Low

sahm-org

ai context codebase documentation generator llm gpt claude

🤖 AI Context Generator - Enterprise Edition

📋 Table of Contents

🎯 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

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

Install from source

# 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



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)



{
  "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):

# 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

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



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.

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

Configuration Options

See Configuration section for all options.

Methods

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



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



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



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

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

💡 Examples Example 1: React Project



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



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

Output file too large



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

Missing files in output



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

Slow performance



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

Debug Mode



# 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



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