Update documentation for v0.2.0 with split/merge features

Author: alexanderv-sifi

README.md

@@ -1,62 +1,71 @@
-# JSON to CSV Converter (Multi-File)
+# FileShift
 
-A powerful native macOS application for converting JSON files to CSV format with advanced schema analysis and field merging capabilities.
+A powerful native macOS application for converting, splitting, and merging JSON, JSONL, and CSV files.
 
-![Build Status](https://github.com/simplifi/json-converter/workflows/Build%20JSON%20to%20CSV%20Converter/badge.svg)
+**Version 0.2.0**
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
 
-**Download for your Mac:**
-- [📥 Intel Mac](https://github.com/simplifi/json-converter/releases/latest/download/JSON-to-CSV-Converter-intel.dmg) • [📥 Apple Silicon](https://github.com/simplifi/json-converter/releases/latest/download/JSON-to-CSV-Converter-apple-silicon.dmg)
+**Download:** [FileShift for Apple Silicon](https://github.com/simplifi/FileShift/releases/latest/download/FileShift-apple-silicon.dmg) (M1/M2/M3/M4)
 
-**⚠️ First Launch:** Right-click the app and select "Open" to bypass the security warning (see [Installation](#installation) for details)
+**First Launch:** Right-click the app and select "Open" to bypass the security warning (see [Installation](#installation) for details)
 
 ---
 
 ## Features
 
-- 🚀 **Batch Processing**: Convert multiple JSON files at once
-- 🧠 **Smart Schema Analysis**: Automatically analyzes and compares schemas across files
-- 🔀 **Multiple Merge Strategies**:
+### Convert Tab
+- **Batch Processing**: Convert multiple JSON files to CSV at once
+- **Smart Schema Analysis**: Automatically analyzes and compares schemas across files
+- **Multiple Merge Strategies**:
   - Smart Auto: Fields present in 70%+ of files
   - All Available: Union of all fields across files
   - Common Only: Fields present in ALL files
   - Most Complete File: Use the file with most fields as template
   - Keep Separate: Individual CSV files with their own schemas
-- 📊 **Nested Field Support**: Handles complex nested JSON structures
-- 🖥️ **Native macOS Interface**: Built with PyQt6 for a smooth, native experience
-- 📝 **Real-time Status Logging**: Track conversion progress with detailed logs
-
-## 📥 Download
-
-### Quick Download (Latest Release)
+- **Nested Field Support**: Handles complex nested JSON structures
+
+### Split Tab
+- **Split by Number of Files**: Divide a file into N equal parts
+- **Split by Rows**: Create files with a specific number of records each
+- **Split by Size**: Create files of approximately N kilobytes each
+- **Format Flexibility**: Input can be JSON, JSONL, or CSV; output format is selectable
+
+### Merge Tab
+- **Combine Multiple Files**: Merge any number of files into one
+- **Mixed Format Support**: Merge JSON, JSONL, and CSV files together
+- **Schema Strategies**:
+  - Union: Include all fields from all files
+  - Intersection: Only include fields common to all files
+  - First File: Use the schema from the first file
+- **Output Format Selection**: Choose JSON, JSONL, or CSV output
+
+### General
+- **Native macOS Interface**: Built with PyQt6 for a smooth, native experience
+- **Real-time Progress**: Track operations with progress bars and status logs
+- **Memory Efficient**: Streaming processing for large files
+
+## Download
 
 | Mac Type | Download Link |
 |----------|--------------|
-| **Intel Macs** | [📥 Download Intel DMG](https://github.com/simplifi/json-converter/releases/latest/download/JSON-to-CSV-Converter-intel.dmg) |
-| **Apple Silicon** (M1/M2/M3) | [📥 Download Apple Silicon DMG](https://github.com/simplifi/json-converter/releases/latest/download/JSON-to-CSV-Converter-apple-silicon.dmg) |
-
-> **📋 All Releases**: View all versions on the [Releases page](https://github.com/simplifi/json-converter/releases)
+| **Apple Silicon** (M1/M2/M3/M4) | [Download DMG](https://github.com/simplifi/FileShift/releases/latest/download/FileShift-apple-silicon.dmg) |
 
-### How to check your Mac type
-1. Click the Apple menu  > About This Mac
-2. Look for "Chip" or "Processor"
-   - Intel processor = Download Intel version
-   - Apple M1/M2/M3 = Download Apple Silicon version
+> **All Releases**: View all versions on the [Releases page](https://github.com/simplifi/FileShift/releases)
 
 ## Installation
 
-1. Download the appropriate DMG file for your Mac
+1. Download the DMG file
 2. Double-click the DMG to mount it
-3. Drag "JSON to CSV Converter" to your Applications folder
+3. Drag "FileShift" to your Applications folder
 4. **First time running**: The app will show a security warning because it's not signed with an Apple Developer certificate
 
-### 🔒 Security Warning Fix
+### Security Warning Fix
 
 When you first run the app, you'll see this warning:
-> "JSON to CSV Converter.app" cannot be opened because Apple cannot verify that it is free from malware.
+> "FileShift.app" cannot be opened because Apple cannot verify that it is free from malware.
 
 **To safely run the app:**
 
@@ -66,94 +75,106 @@ When you first run the app, you'll see this warning:
 4. The app will now run normally
 
 **Alternative method:**
-1. Go to **System Preferences** > **Security & Privacy** > **General**
-2. Click **"Open Anyway"** next to the blocked app message
+1. Go to **System Settings** > **Privacy & Security**
+2. Scroll down and click **"Open Anyway"** next to the blocked app message
 3. Enter your password when prompted
 
-**Why this happens:**
-- The app is unsigned (requires a paid Apple Developer account)
-- This is normal for open-source software distributed outside the Mac App Store
-- The warning is Apple's way of ensuring you intentionally want to run the app
-
 **Note:** After the first time, the app will open normally without any warnings.
 
 ## Usage
 
-1. **Select JSON Files**: Click "Browse for JSON Files" to select one or more JSON files
-2. **Schema Analysis**: The app automatically analyzes the structure of your files
-3. **Choose Strategy**: Select how you want to handle different schemas across files
-4. **Convert**: Click "Convert All Files" and choose an output directory
+### Converting Files
+
+1. Go to the **Convert** tab
+2. Click "Browse for JSON Files" to select one or more JSON files
+3. The app automatically analyzes the structure of your files
+4. Select a merge strategy for handling different schemas
+5. Click "Convert All Files" and choose an output directory
 
-### Field Selection Strategies
+### Splitting Files
 
-- **Smart Auto**: Includes fields that appear in at least 70% of your files
-- **All Available**: Includes every field found across all files (union)
-- **Common Only**: Only includes fields that exist in every single file
-- **Most Complete File**: Uses the schema from the file with the most fields
-- **Keep Files Separate**: Creates individual CSV files, each with its own schema
+1. Go to the **Split** tab
+2. Select a single input file (JSON, JSONL, or CSV)
+3. Choose a split mode:
+   - **By number of files**: Split into N equal parts
+   - **By rows per file**: Each output file has N records
+   - **By file size**: Each output file is approximately N KB
+4. Select output format and directory
+5. Click "Split File"
+
+### Merging Files
+
+1. Go to the **Merge** tab
+2. Select multiple input files (can be mixed formats)
+3. Choose a schema strategy:
+   - **Union**: All fields from all files
+   - **Intersection**: Only common fields
+   - **First file**: Use first file's schema
+4. Select output format and file path
+5. Click "Merge Files"
 
 ## Building from Source
 
 ### Requirements
 
-- macOS 10.13 or later
-- Python 3.8 or later
+- macOS 11 or later
+- Python 3.9 or later
 - PyQt6
 
 ### Quick Build
 
 ```bash
 # Clone the repository
-git clone https://github.com/simplifi/json-converter.git
-cd json-converter
+git clone https://github.com/simplifi/FileShift.git
+cd FileShift
 
-# Run the build script
-./build_app.sh
-```
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate
 
-The built application will be in `dist/JSON to CSV Converter.app`
+# Install dependencies
+pip install PyQt6 pyinstaller
 
-### Building for Different Architectures
+# Build the app
+pyinstaller --clean fileshift.spec
+```
 
-See [README_BUILD.md](README_BUILD.md) for detailed instructions on building for both Intel and Apple Silicon Macs.
+The built application will be in `dist/FileShift.app`
 
 ## Development
 
 ### Setting up the development environment
 
 ```bash
 # Create virtual environment
-python3 -m venv .venv
+uv venv
 source .venv/bin/activate
 
 # Install dependencies
-pip install -r requirements.txt
+uv pip install -e ".[dev]"
 
 # Run the application
 python json_to_csv_multifile_pyqt.py
+
+# Run tests
+pytest
 ```
 
 ### Project Structure
 
 ```
-json-converter/
-├── json_to_csv_multifile_pyqt.py  # Main application
-├── generate_sample_data.py         # Generate test data
-├── build_app.sh                    # Build script
-├── requirements.txt                # Python dependencies
-└── samples/                        # Sample JSON files
+FileShift/
+├── json_to_csv_multifile_pyqt.py  # Main GUI application
+├── src/
+│   └── converters/                 # Core conversion library
+│       ├── base.py                 # Base classes and types
+│       ├── handlers.py             # Format handlers (JSON, JSONL, CSV)
+│       └── operations.py           # Split and merge operations
+├── tests/                          # Test suite
+├── fileshift.spec                  # PyInstaller build spec
+└── pyproject.toml                  # Project configuration
 ```
 
-## Sample Data
-
-Generate sample data for testing:
-
-```bash
-python generate_sample_data.py
-```
-
-This creates various JSON files with different schemas and sizes in the `samples/` directory.
-
 ## Contributing
 
 1. Fork the repository
@@ -173,4 +194,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Support
 
-For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/simplifi/json-converter).
+For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/simplifi/FileShift).