Reposcope

A TypeScript CLI tool for generating comprehensive codebase documentation with tree view and file contents.

Features

• Tree View Generation: Creates a visual directory structure
• File Content Extraction: Includes actual file contents with syntax highlighting
• Smart Filtering: Configurable ignore patterns using glob syntax
• Path Tracking: Optional included/excluded paths reporting
• Fast & Efficient: Built with TypeScript and optimized for large codebases
• Configuration Files: Support for JSON and JS config files
• File Size Limits: Control maximum file size with exceptions for specific extensions
• Custom Templates: Customizable file section templates

Installation

Global Installation (Recommended)

npm install -g reposcope

Local Installation

npm install reposcope

Usage

Command Line Interface

# Scan current directory (requires config file or -dir argument)
reposcope -dir=.

# Scan specific directory
reposcope -dir=./src -output=documentation.md

# With custom ignore patterns
reposcope -ignore="**/*.log,**/node_modules/**,**/.git/**"

# Save path reports
reposcope -included-paths-file=included.txt -excluded-paths-file=excluded.txt

Options

| Option | Description | Default | |--------|-------------|---------| | -dir=<path> | Directory to scan | . (current directory) | | -output=<file> | Output markdown file | codebase.md | | -ignore=<patterns> | Comma-separated glob patterns to ignore | \\.git.* | | -included-paths-file=<file> | File to save included paths | - | | -excluded-paths-file=<file> | File to save excluded paths | - | | -config=<file> | Path to config file | Auto-detected | | -max-file-size=<bytes> | Maximum file size to include | No limit | | -sort=<method> | Sort method: name, size, modified, type | name | | -version | Show version | - | | -help | Show help message | - |

Configuration Files

Reposcope supports configuration files for easier management of complex setups. The tool will automatically look for config files in this order:

1. .reposcope.json
2. .reposcoperc
3. .reposcoperc.json
4. reposcope.config.json
5. reposcope.config.js
6. package.json (reposcope section)

JSON Configuration Example

{
  "dir": "./src",
  "output": "project-docs.md",
  "ignore": [
    "**/node_modules/**",
    "**/.git/**",
    "**/*.log",
    "**/*.test.{js,ts}"
  ],
  "maxFileSize": 1048576,
  "alwaysIncludeExtensions": ["md", "json"],
  "header": "# My Project Documentation\n\n",
  "fileTemplate": "### 📄 {{path}}\n\n```{{extension}}\n{{content}}\n```\n\n",
  "sort": "name"
}

JavaScript Configuration Example

// reposcope.config.js
export default {
  dir: './src',
  output: 'docs.md',
  ignore: [
    '**/node_modules/**',
    '**/*.test.{js,ts}',
    // Dynamic patterns based on environment
    ...(process.env.NODE_ENV === 'production' ? ['**/dev-**'] : [])
  ],
  header: `# Documentation\n\nGenerated: ${new Date().toISOString()}\n\n`,
  maxFileSize: 512 * 1024, // 512KB
  alwaysIncludeExtensions: ['md', 'json'],
  sort: 'type'
};

Package.json Configuration

{
  "name": "my-project",
  "reposcope": {
    "dir": "./src",
    "ignore": ["**/*.test.js"],
    "output": "api-docs.md"
  }
}

Programmatic Usage

import { walkDir, writeFileContent } from 'reposcope';

// Custom file processing
await walkDir(
  './src',
  './src',
  ['**/*.test.ts', '**/node_modules/**'],
  async (filePath, relPath, depth, isLast, depthOpen) => {
    console.log(`File: ${relPath}`);
  },
  async (dirPath, relPath, depth, isLast, depthOpen) => {
    console.log(`Directory: ${relPath}`);
  }
);

Examples

Basic Documentation Generation

reposcope -dir=./my-project -output=project-docs.md

Using Configuration File

# Uses auto-detected config file
reposcope

# Use specific config file
reposcope -config=./my-config.json

Advanced CLI Usage

# Limit file size and sort by type
reposcope -dir=./src -max-file-size=1048576 -sort=type

# Complex ignore patterns
reposcope -dir=. -ignore="**/node_modules/**,**/.git/**,**/*.log,**/*.ico,**/*.png"

TypeScript Project Documentation

reposcope -dir=./src -output=api-docs.md -ignore="**/*.test.ts,**/*.spec.ts,**/__mocks__/**"

Configuration Options

| Option | Type | Description | |--------|------|-------------| | dir | string | Directory to scan | | output | string | Output file name | | ignore | string[] | Array of glob patterns to ignore | | includedPathsFile | string | File to save included paths | | excludedPathsFile | string | File to save excluded paths | | header | string | Custom header for documentation | | maxFileSize | number | Maximum file size in bytes | | alwaysIncludeExtensions | string[] | Extensions to always include | | fileTemplate | string | Custom template for file sections | | sort | string | Sort method: name, size, modified, type | | sortDirection | string | Sort direction: asc, desc |

Template Variables

When using fileTemplate, you can use these variables:

• {{path}} - Relative file path
• {{extension}} - File extension
• {{content}} - File content

Output Format

The generated markdown file includes:

1. Custom Header (if configured)
2. Tree View: Visual directory structure

├─src/
│  ├─components/
│  │  └─Button.tsx
│  ├─utils/
│  │  └─helpers.ts
│  └─main.ts

3. File Contents: Syntax-highlighted code blocks

// Content of each file with proper syntax highlighting
export function helper() {
  return "Hello World";
}

Ignore Patterns

Reposcope uses minimatch for pattern matching. Common patterns:

• **/*.log - All .log files
• **/node_modules/** - Node modules directory
• **/.git/** - Git directory
• *.{png,jpg,ico} - Image files
• test/** - Test directories

Requirements

• Node.js >= 18.0.0
• TypeScript support (for development)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

v1.0.0

• Initial release
• Tree view generation
• File content extraction
• Configurable ignore patterns
• Path tracking features