codesummary 1.0.0

package/README.md

@@ -0,0 +1,370 @@
+# CodeSummary
+
+[![npm version](https://badge.fury.io/js/codesummary.svg)](https://badge.fury.io/js/codesummary)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Cross-Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)](#)
+
+A **cross-platform CLI tool** that automatically scans project source code and generates **clean, professional PDF documentation** containing file structures and complete formatted code content. Perfect for code reviews, audits, project documentation, and archival snapshots.
+
+## 🚀 Key Features
+
+- **🔍 Intelligent Scanning**: Recursively scans project directories with configurable file type filtering
+- **📄 Clean PDF Output**: Generates well-structured A4 PDFs with optimized formatting and complete content flow
+- **📝 Complete Content**: Includes ALL file content without truncation - no size limits
+- **⚙️ Global Configuration**: One-time setup with persistent cross-platform user preferences
+- **🎯 Interactive Selection**: Choose which file types to include via intuitive checkbox prompts
+- **🛡️ Safe & Smart**: Whitelist-driven approach prevents binary files, with intelligent fallbacks
+- **🌍 Cross-Platform**: Works identically on Windows, macOS, and Linux with terminal compatibility
+- **📊 Smart Filtering**: Automatically excludes build directories, dependencies, and temporary files
+- **⚡ Performance Optimized**: Efficient memory usage and streaming for large projects
+- **🔄 File Conflict Handling**: Automatic timestamped filenames when original files are in use
+
+## 📦 Installation
+
+```bash
+npm install -g codesummary
+```
+
+**Requirements**: Node.js ≥ 18.0.0
+
+## 🎯 Quick Start
+
+1. **First-time setup** (interactive wizard):
+   ```bash
+   codesummary
+   ```
+
+2. **Generate PDF for current project**:
+   ```bash
+   cd /path/to/your/project
+   codesummary
+   ```
+
+3. **Override output location**:
+   ```bash
+   codesummary --output ./documentation
+   ```
+
+## 📖 Usage
+
+### Interactive Workflow
+
+#### 1. First Run Setup
+
+```bash
+$ codesummary
+Welcome to CodeSummary!
+No configuration found. Starting setup...
+
+Where should the PDF be generated by default?
+> [ ] Current working directory (relative mode)
+> [x] Fixed folder (absolute mode)
+
+Enter absolute path for fixed folder:
+> ~/Desktop/CodeSummaries
+```
+
+#### 2. Extension Selection
+
+```bash
+Scanning directory: /path/to/project
+
+Scan Summary:
+   Extensions found: .js, .ts, .md, .json
+   Total files: 127
+   Total size: 2.4 MB
+
+Select file extensions to include:
+[x] .js → JavaScript (42 files)
+[x] .ts → TypeScript (28 files)
+[x] .md → Markdown (5 files)
+[ ] .json → JSON (52 files)
+```
+
+#### 3. Generation Complete
+
+```bash
+SUCCESS: PDF generation completed successfully!
+
+Summary:
+   Output: ~/Desktop/CodeSummaries/MYPROJECT_code.pdf
+   Extensions: .js, .ts, .md
+   Total files: 75
+   PDF size: 2.3 MB
+```
+
+### Command Reference
+
+| Command                      | Description                             |
+| ---------------------------- | --------------------------------------- |
+| `codesummary`                | Scan current directory and generate PDF |
+| `codesummary config`         | Edit configuration settings             |
+| `codesummary --show-config`  | Display current configuration           |
+| `codesummary --reset-config` | Reset configuration to defaults         |
+| `codesummary --help`         | Show help information                   |
+
+### Command Line Options
+
+| Option                | Description                              |
+| --------------------- | ---------------------------------------- |
+| `-o, --output <path>` | Override output directory for this run   |
+| `--show-config`       | Display current configuration            |
+| `--reset-config`      | Reset configuration and run setup wizard |
+| `-h, --help`          | Show help message                        |
+
+### Examples
+
+```bash
+# Generate PDF with default settings
+codesummary
+
+# Save PDF to specific directory
+codesummary --output ~/Documents/CodeReviews
+
+# Edit configuration
+codesummary config
+
+# View current settings
+codesummary --show-config
+```
+
+## ⚙️ Configuration
+
+CodeSummary stores global configuration in:
+
+- **Linux/macOS**: `~/.codesummary/config.json`
+- **Windows**: `%APPDATA%\\CodeSummary\\config.json`
+
+### Default Configuration
+
+```json
+{
+  \"output\": {
+    \"mode\": \"fixed\",
+    \"fixedPath\": \"~/Desktop/CodeSummaries\"
+  },
+  \"allowedExtensions\": [
+    \".json\", \".ts\", \".js\", \".jsx\", \".tsx\", \".xml\", \".html\",
+    \".css\", \".scss\", \".md\", \".txt\", \".py\", \".java\", \".cs\",
+    \".cpp\", \".c\", \".h\", \".yaml\", \".yml\", \".sh\", \".bat\",
+    \".ps1\", \".php\", \".rb\", \".go\", \".rs\", \".swift\", \".kt\",
+    \".scala\", \".vue\", \".svelte\", \".dockerfile\", \".sql\", \".graphql\"
+  ],
+  \"excludeDirs\": [
+    \"node_modules\", \".git\", \".vscode\", \"dist\", \"build\",
+    \"coverage\", \"out\", \"__pycache__\", \".next\", \".nuxt\"
+  ],
+  \"styles\": {
+    \"colors\": {
+      \"title\": \"#333353\",
+      \"section\": \"#00FFB9\",
+      \"text\": \"#333333\",
+      \"error\": \"#FF4D4D\",
+      \"footer\": \"#666666\"
+    },
+    \"layout\": {
+      \"marginLeft\": 40,
+      \"marginTop\": 40,
+      \"marginRight\": 40,
+      \"footerHeight\": 20
+    }
+  },
+  \"settings\": {
+    \"documentTitle\": \"Project Code Summary\",
+    \"maxFilesBeforePrompt\": 500
+  }
+}
+```
+
+## 📋 PDF Structure
+
+Generated PDFs use **A4 format** with optimized margins and contain three main sections:
+
+### 1. Project Overview
+- Document title and project name
+- Generation timestamp
+- List of included file types with descriptions
+
+### 2. File Structure
+- Complete hierarchical listing of all included files
+- Organized by relative paths from project root
+- Sorted alphabetically for easy navigation
+
+### 3. File Content
+- **Complete source code** for each file (no truncation)
+- Proper formatting with monospace fonts for code
+- Intelligent text wrapping without overlap
+- Natural page breaks when needed
+- Error handling for unreadable files
+
+## 🔧 Advanced Features
+
+### Smart File Conflict Handling
+
+When the target PDF file is in use (e.g., open in a PDF viewer), CodeSummary automatically creates a timestamped version:
+
+```bash
+# Original filename
+MYPROJECT_code.pdf
+
+# If file is in use, creates:
+MYPROJECT_code_20250729_141602.pdf
+```
+
+### Large File Processing
+
+- **No file size limits**: Processes files of any size completely
+- **Progress indicators**: Shows processing status for large files
+- **Memory efficient**: Uses streaming for optimal performance
+- **Smart warnings**: Informs about large files being processed
+
+### Terminal Compatibility
+
+- **Universal compatibility**: Works with all terminal types and operating systems
+- **No special characters**: Uses standard ASCII text for maximum compatibility
+- **Clear output**: Color-coded messages with fallback text indicators
+
+## 🎨 Supported File Types
+
+CodeSummary supports an extensive range of text-based file formats:
+
+| Extension | Language/Type  | Extension    | Language/Type     |
+| --------- | -------------- | ------------ | ----------------- |
+| `.js`     | JavaScript     | `.py`        | Python            |
+| `.ts`     | TypeScript     | `.java`      | Java              |
+| `.jsx`    | React JSX      | `.cs`        | C#                |
+| `.tsx`    | TypeScript JSX | `.cpp`       | C++               |
+| `.json`   | JSON           | `.c`         | C                 |
+| `.xml`    | XML            | `.h`         | Header            |
+| `.html`   | HTML           | `.yaml/.yml` | YAML              |
+| `.css`    | CSS            | `.sh`        | Shell Script      |
+| `.scss`   | SCSS           | `.bat`       | Batch File        |
+| `.md`     | Markdown       | `.ps1`       | PowerShell        |
+| `.txt`    | Plain Text     | `.php`       | PHP               |
+| `.go`     | Go             | `.rb`        | Ruby              |
+| `.rs`     | Rust           | `.swift`     | Swift             |
+| `.kt`     | Kotlin         | `.scala`     | Scala             |
+| `.vue`    | Vue.js         | `.svelte`    | Svelte            |
+| `.sql`    | SQL            | `.graphql`   | GraphQL           |
+
+## 🛠️ Development
+
+### Project Structure
+
+```
+codesummary/
+├── bin/
+│   └── codesummary.js      # Global executable entry point
+├── src/
+│   ├── cli.js              # Command line interface
+│   ├── configManager.js    # Global configuration management
+│   ├── scanner.js          # File system scanning and filtering
+│   ├── pdfGenerator.js     # PDF creation and formatting
+│   └── errorHandler.js     # Comprehensive error handling
+├── package.json
+├── README.md
+└── features.md
+```
+
+### Building from Source
+
+```bash
+# Clone repository
+git clone https://github.com/skamoll/CodeSummary.git
+cd CodeSummary
+
+# Install dependencies
+npm install
+
+# Test the CLI
+node bin/codesummary.js --help
+
+# Run locally without global install
+node bin/codesummary.js
+```
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+**Configuration not found**
+- Run `codesummary` to trigger first-time setup
+- Check file permissions in config directory
+
+**PDF generation fails**
+- Verify output directory permissions
+- Ensure Node.js version ≥18.0.0
+- Close any open PDF viewers on the target file
+
+**Files not showing up**
+- Check that file extensions are in `allowedExtensions`
+- Verify directories aren't in `excludeDirs` list
+- Ensure files are text-based (not binary)
+
+**Large project performance**
+- Adjust `maxFilesBeforePrompt` in configuration
+- Use extension filtering to reduce file count
+- CodeSummary handles large files efficiently with streaming
+
+### Getting Help
+
+1. Run `codesummary --help` for usage information
+2. Check configuration with `codesummary --show-config`
+3. Reset configuration with `codesummary --reset-config`
+4. Open an issue on [GitHub](https://github.com/skamoll/CodeSummary/issues)
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/yourusername/CodeSummary.git`
+3. Install dependencies: `npm install`
+4. Create a feature branch: `git checkout -b feature-name`
+5. Make your changes and test thoroughly
+6. Submit a pull request
+
+## 📄 License
+
+This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
+
+### License Summary
+
+- ✅ Commercial use permitted
+- ✅ Modification allowed
+- ✅ Distribution allowed
+- ✅ Private use allowed
+- ❗ Copyleft: derivative works must use GPL-3.0
+- ❗ Must include license and copyright notice
+
+## 🙏 Acknowledgments
+
+- Built with [PDFKit](https://pdfkit.org/) for PDF generation
+- Uses [Inquirer.js](https://github.com/SBoudrias/Inquirer.js) for interactive prompts
+- Styled with [Chalk](https://github.com/chalk/chalk) for colorful console output
+- Uses [Ora](https://github.com/sindresorhus/ora) for progress indicators
+
+## 📊 Roadmap
+
+### Future Enhancements
+
+- [ ] Syntax highlighting in PDF output
+- [ ] Clickable table of contents with bookmarks
+- [ ] Multiple output formats (HTML, JSON, Markdown)
+- [ ] Project metrics and code statistics
+- [ ] CI/CD integration mode for automated documentation
+- [ ] Custom PDF themes and styling options
+- [ ] Plugin system for custom processors
+
+## 📞 Support
+
+- 📧 Report bugs: [GitHub Issues](https://github.com/skamoll/CodeSummary/issues)
+- 💬 Ask questions: [GitHub Discussions](https://github.com/skamoll/CodeSummary/discussions)
+- 📖 Documentation: [Wiki](https://github.com/skamoll/CodeSummary/wiki)
+
+---
+
+**Made with ❤️ for developers worldwide**