feat: JSONC config support, stateless revert impl, and .gitignore integration

Author: assignment-sets

.gitignore

@@ -10,6 +10,3 @@ build/
 
 # Virtual environments
 .venv
-
-
-buffer.md

README.md

@@ -1,4 +1,4 @@
-# Annotator
+# Annotator CLI
 
 **Annotator** is a simple CLI utility that prepends relative file paths as comments to your project files as the first line.  
 It’s designed to make AI debugging easier by automatically marking file paths for better context and easier copy-pasting.
@@ -7,80 +7,224 @@ It’s designed to make AI debugging easier by automatically marking file paths
 
 ## ✨ Features
 
-- 🚀 **Automatically annotates** files with their relative paths.
-- 🛠️ **Supports many programming languages and file types** out of the box.
-- ⚙️ **Fully customizable** via a `.annotator.json` configuration file.
-- 🚫 **Exclude** specific directories, files, or extensions.
-- ⚡ **Lightweight and fast** — no external dependencies.
+- 🚀 **Automatically annotates** files with their relative paths
+- 🔄 **Reversible** — clean annotations with `--revert`
+- 🎯 **Template system** — framework-specific presets (Next.js, Spring Boot, Python, React, Prisma)
+- ⚙️ **Fully customizable** via `.annotator.jsonc` configuration
+- 🚫 **Smart filtering** — respects `.gitignore`, excludes binaries, and skips nested paths
+- 🔍 **Stateless revert** — removes annotations using unique signature (`~annotator~`)
+- ⚡ **Lightweight and fast** — minimal dependencies
 
 ---
 
-## 📝 Example `.annotator.json`
+## 📦 Installation
 
-```json
+### Via [pipx](https://pipx.pypa.io/) (recommended):
+
+```sh
+pipx install annotator-cli
+```
+
+### Via pip:
+
+```sh
+pip install annotator-cli
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Initialize configuration
+
+```sh
+cd /path/to/your/project
+annotator --init
+```
+
+This creates `.annotator.jsonc` with sensible defaults and helpful comments.
+
+### 2. Annotate your project
+
+```sh
+annotator
+```
+
+### 3. Revert annotations (if needed)
+
+```sh
+annotator --revert
+```
+
+---
+
+## 📝 Configuration
+
+Annotator uses a layered configuration system:
+
+**Priority Chain:**  
+`.gitignore` → `.annotator.jsonc` → `templates` (cumulative)
+
+### Example `.annotator.jsonc`
+
+```jsonc
 {
-  "comment_styles": {
-    ".md": "<!--",
-    "Dockerfile": "#"
+  // List of templates to apply (keeping default is recommended)
+  // pick additional: nextjs, react, springboot, python3, prisma ...
+  "templates": ["default", "nextjs"],
+
+  // Behavior settings
+  "settings": {
+    "max_recursive_depth": 10, // How deep to recurse into folders
+    "max_num_of_files": 1000, // Maximum files to process
+    "max_file_size_kb": 512, // Skip files larger than this
   },
-  "exclude_extensions": ["*.test.js", "*.spec.ts"],
-  "exclude_dirs": ["test", "dist"],
-  "exclude_files": [".env"]
+
+  // Override comment styles for specific extensions
+  // Example: ".kt": "//", ".scala": "//"
+  "comment_styles": {},
+
+  // Additional file extensions to exclude
+  "exclude_extensions": [".log", ".cache"],
+
+  // Additional directories to exclude (supports nested paths)
+  // Example: ["temp", "src/generated/proto"]
+  "exclude_dirs": ["node_modules", ".venv", "__pycache__"],
+
+  // Additional specific file names to exclude
+  "exclude_files": [".env", ".annotator.jsonc"],
 }
 ```
 
 <details>
-<summary><strong>Configuration Notes</strong></summary>
+<summary><strong>📋 Configuration Details</strong></summary>
+
+### Templates
+
+Annotator includes built-in templates for common frameworks:
 
-- **comment_styles**: Maps file extensions (from the first `.` to the end) or exact filenames to their comment syntax.  
-  _Example:_ `.js` → `//`, `.md` → `<!--`. You can add any extension to annotate non-default types.
+- **`default`** - General-purpose config with 40+ languages, common excludes
+- **`nextjs`** - Next.js specific exclusions (`.next`, config files, etc.)
+- **`react`** - React/Vite/CRA exclusions
+- **`springboot`** - Spring Boot/Maven/Gradle exclusions
+- **`python3`** - Python virtual envs, caches, Jupyter notebooks
+- **`prisma`** - Prisma schema and migration exclusions
+
+Templates are applied cumulatively in order. See all templates at:  
+[github.com/assignment-sets/annotator-cli/tree/main/annotator/templates](https://github.com/assignment-sets/annotator-cli)
+
+### Comment Styles
+
+Maps file extensions or exact filenames to comment syntax:
+
+```jsonc
+".js": "//",
+".py": "#",
+".html": "<!--",
+".css": "/*"
+```
 
-- **exclude_extensions**: Skips all files with these full extensions (from the first `.`).  
-  _Note:_ Even if an extension is mapped in `comment_styles`, files matching an excluded extension will not be annotated.
+### Exclusion Rules
 
-- **exclude_dirs**: Skips these directories entirely.  
-  _Note:_ Any file inside an excluded directory is never annotated, even if its extension is mapped in `comment_styles`.
+- **`exclude_extensions`**: Skip files by extension (e.g., `[".log", ".bin"]`)
+- **`exclude_dirs`**: Skip directories by name or nested path (e.g., `["node_modules", "src/generated"]`)
+- **`exclude_files`**: Skip specific filenames (e.g., `[".env", "package-lock.json"]`)
 
-- **exclude_files**: Skips specific full filenames (with extensions) entirely.  
-  _Note:_ These take precedence over both `comment_styles` and `exclude_extensions`.
+**Note:** `.gitignore` patterns are always respected and have highest priority.
 
-- **Extension parsing**: Extensions are always taken from the first `.` to the end of the filename.  
-  _Example:_ For a file named `file.a.b.c.js`, the full extension is `.a.b.c.js`.
+### Extension Parsing
+
+Extensions are parsed from the last `.` to the end:
+
+- `file.js` → `.js`
+- `component.test.tsx` → `.tsx`
+- `archive.tar.gz` → `.gz`
 
 </details>
 
 ---
 
-## Installation
+## 🎯 CLI Commands
 
-### 1. Install pipx
+```sh
+# Annotate current directory
+annotator
 
-Follow the official guide: [pipx Installation Guide](https://pipxproject.github.io/pipx/installation/)
+# Annotate specific path
+annotator /path/to/project
 
-### 2. Install annotator-cli via [pipx](https://pipx.pypa.io/) (recommended):
+# Initialize configuration
+annotator --init
 
-```sh
-pipx install annotator-cli
+# Remove all annotations
+annotator --revert
+
+# Show help
+annotator --help
 ```
 
 ---
 
-## 🚀 Usage
+## 🔧 How It Works
 
-### 1. Run the CLI
+1. **Loads configuration** from `.annotator.jsonc` and merges with selected templates
+2. **Respects `.gitignore`** patterns (highest priority)
+3. **Applies filters** based on extensions, directories, files, and size limits
+4. **Prepends comments** with relative path and unique signature:
 
-```sh
-annotator /path/to/project
+```python
+   # src/utils/helper.py ~annotator~
 ```
 
-Annotator will process and annotate all eligible files based on your configuration.
+5. **Skips already annotated** files (idempotent)
+6. **Revert support** removes only lines containing `~annotator~` signature
 
-### 2. Uninstall (if needed)
+---
 
-```sh
-pipx uninstall annotator-cli
+## 📚 Common Use Cases
+
+### Next.js Project
+
+```jsonc
+{
+  "templates": ["default", "nextjs"],
+}
+```
+
+### Python Data Science Project
+
+```jsonc
+{
+  "templates": ["default", "python3"],
+  // customize more as you need for example
+  "exclude_extensions": [".parquet"],
+}
 ```
 
+### Spring Boot Microservice
+
+```jsonc
+{
+  "templates": ["default", "springboot"],
+}
+```
+
+### Full-Stack React + Prisma
+
+```jsonc
+{
+  "templates": ["default", "react", "prisma"],
+}
+```
+
+---
+
+## 🤝 Contributing
+
+Want to add a template for your favorite framework? PRs welcome!
+
+Repository: [github.com/assignment-sets/annotator-cli](https://github.com/assignment-sets/annotator-cli)
+
 ---
 
 ## ⚠️ Disclaimer
@@ -89,3 +233,13 @@ pipx uninstall annotator-cli
 > Use at your own risk — the author is not responsible for data loss, crashes, or security issues.
 
 ---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+Built to make AI-assisted debugging easier by providing better file context.