feat: add support for collection information in SQL to MongoDB conversion and enhance documentation

Author: theboringhumane

README.md

@@ -331,4 +331,55 @@ zero-sql/
 └── README.md           # This file
 ```
 
-The converter package is the heart of the application, handling the conversion from SQL Abstract Syntax Trees (AST) to MongoDB aggregation pipelines. 
+The converter package is the heart of the application, handling the conversion from SQL Abstract Syntax Trees (AST) to MongoDB aggregation pipelines. 
+
+## Usage
+
+```bash
+# Basic usage
+zero-sql "SELECT name, age FROM users WHERE age > 18"
+
+# With collection information (helps avoid MongoDB namespace errors)
+zero-sql --include-collection "SELECT name, age FROM users WHERE age > 18 LIMIT 5"
+
+# Pretty print JSON output
+zero-sql --pretty "SELECT * FROM products"
+
+# Verbose mode
+zero-sql --verbose "SELECT name FROM users"
+```
+
+## Troubleshooting
+
+### MongoDB Aggregation Namespace Error
+
+If you encounter an error like `(InvalidNamespace) {aggregate: 1} is not valid for '$limit'; a collection is required`, this means that when executing the generated aggregation pipeline in MongoDB, the collection name is not being specified correctly.
+
+**Solution**: Use the `--include-collection` flag to get both the collection name and the pipeline:
+
+```bash
+# This outputs collection name and pipeline
+zero-sql --include-collection "SELECT name FROM users LIMIT 10"
+```
+
+**Output**:
+```json
+{
+  "collection": "users",
+  "pipeline": [
+    {
+      "$limit": 10
+    }
+  ]
+}
+```
+
+Then, in your MongoDB client/driver, use the collection name when executing the aggregation:
+
+```javascript
+// MongoDB shell
+db.users.aggregate([{"$limit": 10}])
+
+// Node.js with MongoDB driver
+await db.collection("users").aggregate([{"$limit": 10}]).toArray()
+``` 

RELEASE_NOTES_v0.1.3.md

@@ -0,0 +1,115 @@
+# Zero-SQL v0.1.3 Release Notes
+
+## 🎉 New Features
+
+### MongoDB Collection Information Support
+- **Collection Extraction**: New `--include-collection` CLI flag that outputs both collection name and aggregation pipeline
+- **Enhanced API**: Added `ConvertSQLToMongoWithCollection()` method to the public API
+- **Structured Output**: New `ConversionResult` struct containing collection name and pipeline stages
+- **Namespace Error Fix**: Solves MongoDB `(InvalidNamespace) {aggregate: 1} is not valid for '$limit'; a collection is required` errors
+
+### CLI Enhancements
+- **New Flag**: `--include-collection` / `-c` flag for collection-aware output
+- **Better Help**: Updated help documentation with collection information examples
+- **Backward Compatibility**: Existing behavior unchanged when flag is not used
+
+## 🔧 API Changes
+
+### New Public Methods
+```go
+// New method that returns collection name and pipeline
+result, err := conv.ConvertSQLToMongoWithCollection(sqlQuery)
+fmt.Printf("Collection: %s\n", result.Collection)
+fmt.Printf("Pipeline: %v\n", result.Pipeline)
+```
+
+### New Types
+```go
+// ConversionResult holds both collection name and pipeline
+type ConversionResult struct {
+    Collection string                   `json:"collection"`
+    Pipeline   []map[string]interface{} `json:"pipeline"`
+}
+```
+
+## 🚀 Usage Examples
+
+### CLI Usage
+```bash
+# Traditional output (pipeline only)
+zero-sql "SELECT name FROM users LIMIT 10"
+
+# New collection-aware output
+zero-sql --include-collection "SELECT name FROM users LIMIT 10"
+```
+
+### API Usage
+```go
+import "github.com/synehq/zero-sql/pkg/zerosql"
+
+conv := zerosql.New(&zerosql.Options{Verbose: false})
+
+// Get collection and pipeline together
+result, err := conv.ConvertSQLToMongoWithCollection("SELECT * FROM users LIMIT 5")
+if err != nil {
+    return err
+}
+
+// Execute in MongoDB with proper collection
+// db.collection(result.Collection).aggregate(result.Pipeline)
+```
+
+## 🐛 Bug Fixes
+
+### MongoDB Namespace Errors
+- **Issue**: Generated pipelines caused `InvalidNamespace` errors when executed in MongoDB
+- **Root Cause**: MongoDB aggregation requires explicit collection specification
+- **Solution**: Extract collection name from SQL FROM clause and provide it alongside pipeline
+- **Impact**: Eliminates common MongoDB execution errors when using generated pipelines
+
+## 🔄 Troubleshooting
+
+### MongoDB Aggregation Errors
+If you encounter namespace errors like:
+```
+(InvalidNamespace) {aggregate: 1} is not valid for '$limit'; a collection is required
+```
+
+**Solution**: Use the new `--include-collection` flag:
+```bash
+zero-sql --include-collection "SELECT name FROM users LIMIT 10"
+```
+
+This outputs:
+```json
+{
+  "collection": "users",
+  "pipeline": [{"$limit": 10}]
+}
+```
+
+Then execute in MongoDB:
+```javascript
+// MongoDB shell
+db.users.aggregate([{"$limit": 10}])
+
+// Node.js with MongoDB driver
+await db.collection("users").aggregate([{"$limit": 10}]).toArray()
+```
+
+## 📝 Documentation Updates
+
+- **README**: Added troubleshooting section for MongoDB namespace errors
+- **CLI Help**: Updated examples to include new `--include-collection` flag
+- **Usage Guide**: Added collection-aware execution examples
+
+## ⚡ Performance & Compatibility
+
+- **Zero Breaking Changes**: All existing functionality remains unchanged
+- **Backward Compatible**: Existing scripts and integrations continue to work
+- **Optional Feature**: Collection information is opt-in via flag or method choice
+- **Same Performance**: No performance impact on existing workflows
+
+---
+
+**Full Changelog**: https://github.com/synehq/zero-sql/compare/v0.0.2...v0.1.3 

RELEASE_NOTES_v0.0.1.md changelogs/RELEASE_NOTES_v0.0.1.mdRELEASE_NOTES_v0.0.1.md renamed to changelogs/RELEASE_NOTES_v0.0.1.md

@@ -0,0 +1,58 @@
+# Zero-SQL v0.0.2 Release Notes
+
+## 🎉 New Features
+
+### Public API Package
+- **Public Converter Package**: Introduced `pkg/zerosql` package to expose converter functionality publicly
+- **External Integration**: The converter can now be imported and used by external Go modules
+- **Simplified API**: Clean and simple API with `zerosql.New()` and `zerosql.Options{}`
+
+## 🔧 Breaking Changes
+
+### Import Path Changes
+- **Old**: `github.com/synehq/zero-sql/internal/converter` (internal package)
+- **New**: `github.com/synehq/zero-sql/pkg/zerosql` (public package)
+
+### Usage Changes
+```go
+// Before (internal package - not accessible externally)
+conv := converter.New(&converter.Options{
+    Verbose: true,
+})
+
+// After (public package)
+conv := zerosql.New(&zerosql.Options{
+    Verbose: true,
+})
+```
+
+## 🚀 Improvements
+
+- **Better Modularity**: Clear separation between internal implementation and public API
+- **External Usage**: Can now be integrated into other Go projects as a dependency
+- **Maintained Functionality**: All existing converter features remain unchanged
+
+## 📦 Installation
+
+For external projects, you can now import and use zero-sql as a library:
+
+```go
+import "github.com/synehq/zero-sql/pkg/zerosql"
+
+conv := zerosql.New(&zerosql.Options{
+    Verbose: true,
+})
+pipeline, err := conv.ConvertSQLToMongo("SELECT * FROM users WHERE age > 18")
+```
+
+## 🔄 Migration Guide
+
+If you were using the internal package (which wasn't officially supported):
+
+1. Update import: `github.com/synehq/zero-sql/internal/converter` → `github.com/synehq/zero-sql/pkg/zerosql`
+2. Update constructor: `converter.New()` → `zerosql.New()`
+3. Update options: `converter.Options{}` → `zerosql.Options{}`
+
+---
+
+**Full Changelog**: https://github.com/synehq/zero-sql/compare/v0.0.1...v0.0.2 

changelogs/RELEASE_NOTES_v0.0.2.md

@@ -6,15 +6,16 @@ import (
 	"os"
 	"strings"
 
-	"github.com/synehq/zero-sql/internal/converter"
+	"github.com/synehq/zero-sql/pkg/zerosql"
 
 	"github.com/spf13/cobra"
 )
 
 var (
-	outputFormat string
-	prettyPrint  bool
-	verbose      bool
+	outputFormat      string
+	prettyPrint       bool
+	verbose           bool
+	includeCollection bool
 )
 
 // rootCmd represents the base command when called without any subcommands
@@ -39,7 +40,8 @@ Examples:
   zero-sql "SELECT u.name, p.title FROM users u JOIN posts p ON u.id = p.user_id WHERE u.active = true"
   zero-sql "SELECT u.name, p.title, c.name FROM users u JOIN posts p ON u.id = p.user_id JOIN categories c ON p.category_id = c.id"
   zero-sql "SELECT u.name, p.title FROM users u LEFT JOIN posts p ON u.id = p.user_id"
-  zero-sql --format=json --pretty "SELECT COUNT(*) as total FROM orders GROUP BY status"`,
+  zero-sql --format=json --pretty "SELECT COUNT(*) as total FROM orders GROUP BY status"
+  zero-sql --include-collection "SELECT name FROM users LIMIT 10"`,
 	Args: cobra.ExactArgs(1),
 	RunE: runConvert,
 }
@@ -53,6 +55,7 @@ func init() {
 	rootCmd.Flags().StringVarP(&outputFormat, "format", "f", "json", "Output format (json, bson)")
 	rootCmd.Flags().BoolVarP(&prettyPrint, "pretty", "p", true, "Pretty print the output")
 	rootCmd.Flags().BoolVarP(&verbose, "verbose", "v", false, "Verbose output")
+	rootCmd.Flags().BoolVarP(&includeCollection, "include-collection", "c", false, "Include collection information in the output")
 }
 
 // runConvert is the main execution function for the convert command
@@ -68,18 +71,25 @@ func runConvert(cmd *cobra.Command, args []string) error {
 	}
 
 	// Create converter with options
-	conv := converter.New(&converter.Options{
+	conv := zerosql.New(&zerosql.Options{
 		Verbose: verbose,
 	})
 
-	// Convert SQL to MongoDB pipeline
-	pipeline, err := conv.ConvertSQLToMongo(sqlQuery)
-	if err != nil {
-		return fmt.Errorf("conversion failed: %w", err)
+	if includeCollection {
+		// Convert SQL to MongoDB pipeline with collection info
+		result, err := conv.ConvertSQLToMongoWithCollection(sqlQuery)
+		if err != nil {
+			return fmt.Errorf("conversion failed: %w", err)
+		}
+		return outputResultWithCollection(result)
+	} else {
+		// Convert SQL to MongoDB pipeline
+		pipeline, err := conv.ConvertSQLToMongo(sqlQuery)
+		if err != nil {
+			return fmt.Errorf("conversion failed: %w", err)
+		}
+		return outputResult(pipeline)
 	}
-
-	// Output the result
-	return outputResult(pipeline)
 }
 
 // outputResult formats and outputs the MongoDB pipeline
@@ -119,3 +129,34 @@ func outputBSON(pipeline []map[string]interface{}) error {
 	// In a more robust implementation, this could use the official MongoDB Go driver's BSON package
 	return outputJSON(pipeline)
 }
+
+// outputResultWithCollection formats and outputs the MongoDB pipeline with collection information
+func outputResultWithCollection(result *zerosql.ConversionResult) error {
+	switch strings.ToLower(outputFormat) {
+	case "json":
+		return outputJSONWithCollection(result)
+	case "bson":
+		return outputJSONWithCollection(result) // BSON uses same format for now
+	default:
+		return fmt.Errorf("unsupported output format: %s", outputFormat)
+	}
+}
+
+// outputJSONWithCollection outputs the result with collection information as JSON
+func outputJSONWithCollection(result *zerosql.ConversionResult) error {
+	var output []byte
+	var err error
+
+	if prettyPrint {
+		output, err = json.MarshalIndent(result, "", "  ")
+	} else {
+		output, err = json.Marshal(result)
+	}
+
+	if err != nil {
+		return fmt.Errorf("failed to marshal JSON: %w", err)
+	}
+
+	fmt.Println(string(output))
+	return nil
+}

cmd/root.go

@@ -5,6 +5,7 @@ echo
 
 echo "1. Simple SELECT with WHERE clause:"
 ./zero-sql "SELECT name, age FROM users WHERE age > 18"
+
 echo
 
 echo "2. SELECT with LIKE pattern matching:"