feat: implement MVP of gomongo library (#1)

* chore: claude.md and readme.md

* feat: implement MVP of gomongo library

Implement the initial version of gomongo - a Go library that parses
MongoDB shell syntax and executes commands using the native Go MongoDB
driver.

MVP scope (matching bytebase/bytebase#18883):
- db.collection.find() - returns all documents (filter parsed but ignored)
- Collection access via dot notation, bracket notation, and getCollection()
- Extended JSON (Relaxed) output format
- Parse errors with line/column information
- Unsupported operation errors with hints

Not yet supported:
- Filter support for find()
- findOne()
- Cursor modifiers (sort, limit, skip, projection)
- Helper functions (ObjectId, ISODate, UUID, etc.)
- Shell commands (show dbs, show collections)

Also includes:
- GitHub Actions workflows for tests and linting
- Integration tests using testcontainers
- ANTLR replace directive for Bytebase's optimized fork

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: h3n4l

.github/workflows/lint.yml

@@ -0,0 +1,28 @@
+name: Lint
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  golangci-lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v6
+        with:
+          version: v1.64.8
+          args: --verbose --timeout 5m --allow-parallel-runners

.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+      - name: Verify go.mod is tidy
+        run: |
+          go mod tidy
+          git diff --exit-code
+      - name: Run tests
+        run: go test -v -race -timeout 10m ./...

CLAUDE.md

@@ -0,0 +1,131 @@
+This file provides guidance to AI coding assistants when working with code in this repository.
+
+## Project Overview
+
+gomongo is a Go library that parses MongoDB shell syntax and executes commands using the native Go MongoDB driver. It uses the ANTLR-based parser from `github.com/bytebase/parser/mongodb`.
+
+## Project Structure
+
+```
+gomongo/
+├── client.go              # Public API: Client, NewClient, Execute
+├── executor.go            # Parse → Translate → Execute pipeline
+├── translator.go          # Walk ANTLR parse tree, build driver operations
+├── helper_functions.go    # Convert ObjectId(), ISODate(), etc. to BSON
+├── errors.go              # Error types (ParseError, UnsupportedOperationError)
+├── executor_test.go       # Integration tests with testcontainers
+└── go.mod
+```
+
+## Development Workflow
+
+**ALWAYS follow these steps after making code changes:**
+
+1. **Format** — Run `gofmt -w` on modified files
+2. **Lint** — Run `golangci-lint run --allow-parallel-runners` to catch issues
+   - Run repeatedly until there are no issues (linter has max-issues limit)
+3. **Auto-fix** — Use `golangci-lint run --fix --allow-parallel-runners` to fix issues automatically
+4. **Test** — Run `go test -v ./...` before committing
+5. **Build** — Run `go build ./...` to verify compilation
+
+## Build/Test Commands
+
+```bash
+# Build
+go build ./...
+
+# Run all tests
+go test -v ./...
+
+# Run single test
+go test -v -count=1 -run ^TestFunctionName$
+
+# Run tests with race detection
+go test -race -v ./...
+
+# Lint
+golangci-lint run --allow-parallel-runners
+
+# Format
+gofmt -w .
+```
+
+## Code Style
+
+### General
+
+- Follow [Google Go Style Guide](https://google.github.io/styleguide/go/)
+- Write clean, minimal code; fewer lines is better
+- Prioritize simplicity for effective and maintainable software
+- Only include comments that are essential to understanding functionality
+
+### Go
+
+- Use standard Go error handling with detailed error messages
+- Always use `defer` for resource cleanup like `cursor.Close()`
+- Avoid using `defer` inside loops — use IIFE or scope properly
+- Use `any` instead of `interface{}` (Go 1.18+)
+
+### Naming
+
+- Use American English
+- Avoid plurals like "xxxList"
+
+### Imports
+
+- Use organized imports (sorted by import path)
+- Group: stdlib, external, internal
+
+### Error Handling
+
+- Be explicit but concise about error cases
+- Wrap errors with context using `errors.Wrap()` or `fmt.Errorf("...: %w", err)`
+
+## Common Go Lint Rules
+
+- **Unused Parameters** — Prefix unused parameters with underscore (e.g., `func foo(_ *Bar)`)
+- **Modern Go Conventions** — Use `any` instead of `interface{}`
+- **Confusing Naming** — Avoid similar names that differ only by capitalization
+- **Identical Branches** — Don't use if-else branches that contain identical code
+- **Function Receivers** — Don't create unnecessary function receivers
+- **Export Rules** — Only export functions and types that need to be used outside the package
+
+## Testing
+
+### Unit Tests
+
+- Test translator logic with mock parse trees
+- Test helper function conversions (ObjectId, ISODate, etc.)
+- Test error message formatting
+
+### Integration Tests
+
+Use testcontainers for MongoDB:
+
+```go
+func TestFind(t *testing.T) {
+    // Start MongoDB container
+    // Insert test documents
+    // Execute query via gomongo
+    // Verify results
+}
+```
+
+## Dependencies
+
+- `go.mongodb.org/mongo-driver/v2` — Official MongoDB Go driver
+- `github.com/bytebase/parser` — ANTLR-based MongoDB shell parser
+- `github.com/antlr4-go/antlr/v4` — ANTLR runtime for Go
+
+## Output Format
+
+All query results are returned as Extended JSON (Relaxed) format using `bson.MarshalExtJSONIndent()`. This ensures:
+- Valid JSON that can be parsed by `JSON.parse()`
+- Type information preserved for BSON types
+- Consistent output format
+
+## Pull Request Guidelines
+
+- **Description** — Clearly describe what the PR changes and why
+- **Testing** — Include information about how the changes were tested
+- **Breaking Changes** — Clearly mark any breaking API changes

README.md

@@ -0,0 +1,101 @@
+# gomongo
+
+Go library for parsing and executing MongoDB shell syntax using the native MongoDB driver.
+
+## Overview
+
+gomongo parses MongoDB shell commands (e.g., `db.users.find()`) and executes them using the Go MongoDB driver, eliminating the need for external mongosh CLI.
+
+## Status
+
+**MVP v0.1.0** - Basic functionality implemented:
+
+| Feature | Status |
+|---------|--------|
+| `find()` without filter | Supported |
+| `find()` with filter | Parsed but filter ignored (returns all documents) |
+| `findOne()` | Not yet supported |
+| Cursor modifiers (sort, limit, skip, projection) | Parsed but ignored |
+| Helper functions (ObjectId, ISODate, etc.) | Not yet supported |
+| Shell commands (show dbs, show collections) | Not yet supported |
+| Collection access (dot, bracket, getCollection) | Supported |
+
+## Installation
+
+```bash
+go get github.com/bytebase/gomongo
+```
+
+## Usage
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+
+    "github.com/bytebase/gomongo"
+    "go.mongodb.org/mongo-driver/v2/mongo"
+    "go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func main() {
+    // Connect to MongoDB
+    client, err := mongo.Connect(options.Client().ApplyURI("mongodb://localhost:27017"))
+    if err != nil {
+        panic(err)
+    }
+    defer client.Disconnect(context.Background())
+
+    // Create gomongo client
+    gc := gomongo.NewClient(client)
+
+    // Execute MongoDB shell command
+    ctx := context.Background()
+    result, err := gc.Execute(ctx, "mydb", `db.users.find()`)
+    if err != nil {
+        panic(err)
+    }
+
+    // Print results (Extended JSON format)
+    for _, row := range result.Rows {
+        fmt.Println(row)
+    }
+}
+```
+
+## Supported Operations (MVP)
+
+| Category | Operation | Status |
+|----------|-----------|--------|
+| **Read** | `find()` | Supported (no filter) |
+| | `findOne()` | Not yet supported |
+| **Collection Access** | dot notation | Supported (`db.users`) |
+| | bracket notation | Supported (`db["user-logs"]`) |
+| | getCollection | Supported (`db.getCollection("users")`) |
+
+## Output Format
+
+Results are returned in Extended JSON (Relaxed) format:
+
+```json
+{
+  "_id": {"$oid": "507f1f77bcf86cd799439011"},
+  "name": "Alice",
+  "age": 30,
+  "createdAt": {"$date": "2024-01-01T00:00:00Z"}
+}
+```
+
+## Roadmap
+
+Future versions will add:
+- Filter support for `find()` and `findOne()`
+- Cursor modifiers (sort, limit, skip, projection)
+- Helper functions (ObjectId, ISODate, UUID, NumberLong, etc.)
+- Shell commands (show dbs, show collections)
+
+## License
+
+Apache License 2.0

client.go

@@ -0,0 +1,30 @@
+package gomongo
+
+import (
+	"context"
+
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+// Client wraps a MongoDB client and provides query execution.
+type Client struct {
+	client *mongo.Client
+}
+
+// NewClient creates a new gomongo client from an existing MongoDB client.
+func NewClient(client *mongo.Client) *Client {
+	return &Client{client: client}
+}
+
+// Result represents query execution results.
+type Result struct {
+	Rows      []string
+	RowCount  int
+	Statement string
+}
+
+// Execute parses and executes a MongoDB shell statement.
+// Returns results as Extended JSON (Relaxed) strings.
+func (c *Client) Execute(ctx context.Context, database, statement string) (*Result, error) {
+	return execute(ctx, c.client, database, statement)
+}

errors.go

@@ -0,0 +1,32 @@
+package gomongo
+
+import "fmt"
+
+// ParseError represents a syntax error during parsing.
+type ParseError struct {
+	Line     int
+	Column   int
+	Message  string
+	Found    string
+	Expected string
+}
+
+func (e *ParseError) Error() string {
+	if e.Found != "" && e.Expected != "" {
+		return fmt.Sprintf("parse error at line %d, column %d: found %q, expected %s", e.Line, e.Column, e.Found, e.Expected)
+	}
+	return fmt.Sprintf("parse error at line %d, column %d: %s", e.Line, e.Column, e.Message)
+}
+
+// UnsupportedOperationError represents an unsupported operation.
+type UnsupportedOperationError struct {
+	Operation string
+	Hint      string
+}
+
+func (e *UnsupportedOperationError) Error() string {
+	if e.Hint != "" {
+		return fmt.Sprintf("unsupported operation %q: %s", e.Operation, e.Hint)
+	}
+	return fmt.Sprintf("unsupported operation %q", e.Operation)
+}