Add Augment Code Review guidelines

[phodal]

Overview

This PR adds Augment Code Review guidelines to the Coca project following the Augment Code Review Admin Guide.

Changes

• Added .augment/code_review_guidelines.yaml configuration file
• Defined custom code review rules tailored for the Coca codebase
• Enhanced with real-world review insights from successful Augment Code Review examples

Guidelines Included

1. Error Handling

• Proper error handling and nil safety
• Error wrapping for better context
• Nil pointer checks

2. Concurrency Safety

• Goroutine leak prevention
• Race condition detection
• Proper synchronization

3. Code Analysis Accuracy ⭐ Enhanced

• AST parsing correctness with grammar alternatives consideration
• Analysis result validation with no data loss emphasis
• Language support consistency
• NEW: Scope tracking correctness - Prevents misattribution in nested scopes (inspired by chapi#37)
• NEW: Complete syntax coverage - Ensures all syntax variants are handled (inspired by chapi#38)

4. Domain Model Integrity

• Immutable domain objects
• Domain validation at creation

5. Performance

• Memory allocation optimization
• Resource cleanup (file handles, etc.)
• Large file handling efficiency

6. Testing ⭐ Enhanced

• Test isolation
• Proper use of test fixtures
• Table-driven tests
• NEW: Edge case coverage - Comprehensive testing of corner scenarios
• NEW: Test completeness - Verify complete behavior, not just happy path

7. API Compatibility

• Backward compatibility for CLI
• Consistent output formats

8. Code Quality ⭐ Enhanced

• Avoid magic numbers
• Function complexity management
• Package organization
• Documentation for exported symbols
• NEW: Data structure choice - Use appropriate data structures (e.g., stacks for nested scopes)
• NEW: State management - Proper scoping of mutable state in hierarchical structures

9. Dependency Management

• Avoid circular dependencies
• Minimize external dependencies

Real-World Inspiration

These guidelines have been enhanced based on actual Augment Code Review comments from the Chapi project:

1. chapi#37 - Identified nested scope tracking issue:

   "Using a single shared classFields list here will misattribute fields when classes are nested: fields collected in the outer class before entering an inner class will be assigned to the inner class and then cleared, causing them to be missing from the outer class upon its exit."

   → Led to scope_tracking_correctness and state_management rules

2. chapi#38 - Identified incomplete syntax handling:

   "For arguments of the form test comp_for (e.g., generator expressions f(x for x in a)), using only test(0).text will drop the comprehension and record just x; consider handling the comp_for case so the full argument is captured."

   → Led to complete_syntax_coverage and enhanced ast_parsing_correctness rules

Benefits

• Automated Code Review: Augment will automatically review PRs based on these guidelines
• Consistency: Ensures consistent code quality across the project
• Focus on Go Best Practices: Rules are tailored for Go language and this project's architecture
• Domain-Specific Rules: Includes rules specific to code analysis tools (AST parsing, analysis accuracy, etc.)
• Battle-Tested: Enhanced with insights from real code review scenarios
• Prevents Common Pitfalls: Addresses actual issues found in similar projects

Testing

The YAML file has been validated and follows the format specified in the Augment documentation.

Statistics

• Total Rules: 27 (6 new rules added based on real reviews)
• High Severity: 11 rules
• Medium Severity: 13 rules
• Low Severity: 3 rules
• Coverage: 9 key areas

References

• Augment Code Review Admin Guide
• Augment Code Review Guidelines Format
• Example Review: chapi#37 - Nested scope tracking
• Example Review: chapi#38 - Complete syntax coverage

[phodal]

@coderabbitai review

[phodal]

augment review

[augmentcode]

Review completed. No suggestions at this time.

Comment augment review to trigger a new review at any time.