XGo Project AI Assistant Guide

Workflow

Adding New Syntax Features

When implementing new language syntax, follow this three-phase approach:

IMPORTANT: Each phase must be implemented in a separate pull request. Do NOT mix phases in a single PR. This separation ensures:

• Clear review focus (grammar vs semantics vs documentation)
• Easier rollback if issues are found
• Better git history and maintainability
• Allows grammar to be reviewed independently from implementation details

Phase 1: Grammar Definition (First Pull Request)

Scope: AST, parser, printer, and required AST consumer modifications ONLY

• AST: Define new node types in ast/ directory (if needed - often existing nodes can be reused)
• Parser: Implement parsing rules in parser/ directory to recognize the new syntax
• Printer: Add formatting support for new syntax (inverse of parsing) in printer/ directory
• AST Consumers: Audit manually maintained consumers such as ast.Walk, ast/filter.go, parser expression validation, and x/format
• Testing: Add test cases in parser/_testdata/ for new syntax and focused unit tests for affected AST consumers
  • Note: Printer reuses parser test cases and also has printer-specific cases in printer/_testdata/
• What NOT to include: Do NOT add any code generation or semantic logic in cl/ package - that belongs in Phase 2

Phase 2: Semantic Implementation (Second Pull Request)

Scope: Code generation via cl package and gogen module ONLY

• Code Generation: Implement semantics using github.com/goplus/gogen package
• Type Safety: Leverage gogen's type information maintenance for semantic correctness
• Testing: Add comprehensive test cases in cl/_testxgo/ covering various usage scenarios
• Prerequisite: Phase 1 PR must be merged before starting Phase 2

When submitting a new PR to the gogen repository for a change, also submit a PR to the xgo repository that updates the gogen module to the latest code from the corresponding gogen branch. The xgo PR's go.mod/go.sum must pin the gogen dependency to the feature branch's commit (not to a released version), so the two PRs represent a coherent, reviewable change set.

Phase 3: Documentation (Third Pull Request)

Scope: User-facing documentation updates ONLY

• Quick Start Guide: Add feature documentation to doc/docs.md with practical examples
• Table of Contents: Update TOC in quick start to include new feature section
• Language Specification: Update specification documents (see Language Specification Structure below)
• Examples: Provide clear, runnable code examples demonstrating the feature
• Prerequisite: Phase 2 PR must be merged before starting Phase 3

Communication Protocol

• When I request syntax additions, first confirm the exact grammar specification
• Always consider backward compatibility with existing Go code
• For ambiguous requirements, ask clarifying questions about:
  • Precedence and associativity rules
  • Error handling expectations
  • Integration with existing type system

Technical Specifications

Compiler Architecture

• Target: XGo compiles to Go code, not machine code
• Foundation: Built on github.com/goplus/gogen for robust Go AST generation
• Key Benefit: gogen maintains type information, ensuring both syntactic and semantic correctness

Quality Standards

Code Requirements

• Maintain full compatibility with existing Go ecosystem
• Ensure new syntax doesn't break existing XGo/Go code
• Follow Go idioms in generated code
• Provide comprehensive error messages
• Code Formatting: Run go fmt on any changed source files before committing

Documentation Expectations

• Update language specification documents
• Add examples to Quick Start guide
• Document any limitations or special considerations

Testing Requirements

• Phase 1: 100% test coverage for new syntax parsing in parser/_testdata/ and focused tests for affected AST consumers
• Phase 2: Comprehensive test coverage for semantic implementation in cl/_testxgo/ covering:
  • Common usage scenarios
  • Edge cases and error conditions
  • Integration with existing type system
• Phase 3: Documentation validation
  • Ensure all code examples in documentation are runnable and correct
  • Verify documentation accurately reflects implemented behavior
  • Check that TOC links work correctly
• Coverage rule: Unit test coverage must not decrease across any PR. Run go test ./... -cover before and after your changes and compare. If coverage drops for any package, add tests to compensate before submitting.