moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-tool-ast-grep/reference.md

@@ -0,0 +1,288 @@
+# AST-Grep Tool - Reference Documentation
+
+## Official Resources
+
+### Core Documentation
+- **AST-Grep Official Site**: https://ast-grep.github.io/
+  - Main documentation hub
+  - Getting started guide
+  - Feature overview
+
+- **GitHub Repository**: https://github.com/ast-grep/ast-grep
+  - Source code
+  - Issue tracker
+  - Contributing guide
+  - Release notes
+
+- **Playground**: https://ast-grep.github.io/playground.html
+  - Interactive pattern testing
+  - Live rule validation
+  - Multi-language support
+
+### Installation
+
+#### Package Managers
+- **Homebrew (macOS/Linux)**: https://ast-grep.github.io/guide/install.html#homebrew
+  ```bash
+  brew install ast-grep
+  ```
+
+- **npm (Cross-platform)**: https://www.npmjs.com/package/@ast-grep/cli
+  ```bash
+  npm install -g @ast-grep/cli
+  ```
+
+- **Cargo (Rust)**: https://crates.io/crates/ast-grep
+  ```bash
+  cargo install ast-grep
+  ```
+
+- **Pre-built Binaries**: https://github.com/ast-grep/ast-grep/releases
+  - Linux, macOS, Windows
+  - No installation required
+
+### Core Documentation
+
+#### Getting Started
+- **Quick Start**: https://ast-grep.github.io/guide/quick-start.html
+  - Basic pattern search
+  - First rule creation
+  - Common use cases
+
+- **Pattern Syntax**: https://ast-grep.github.io/reference/pattern.html
+  - Meta-variables ($VAR)
+  - Variadic variables ($$$ARGS)
+  - Anonymous variables ($$_)
+  - Wildcards and quantifiers
+
+#### Rule Configuration
+- **YAML Rule Reference**: https://ast-grep.github.io/reference/yaml.html
+  - Rule structure
+  - Composite rules (all/any/not)
+  - Relational rules (inside/has/follows)
+  - Fix patterns
+  - Severity levels
+
+- **Configuration Files**: https://ast-grep.github.io/reference/config.html
+  - sgconfig.yml structure
+  - Rule directory organization
+  - Test configuration
+  - Language glob patterns
+
+### Advanced Features
+
+#### Pattern Matching
+- **Advanced Patterns**: https://ast-grep.github.io/guide/pattern-syntax.html
+  - String matching
+  - Regular expressions in patterns
+  - Node type matching
+  - Field constraints
+
+#### Relational Rules
+- **Inside Rule**: https://ast-grep.github.io/reference/rule.html#inside
+  - Scoped search within parent nodes
+  - Nested context matching
+
+- **Has Rule**: https://ast-grep.github.io/reference/rule.html#has
+  - Contains check
+  - Descendant node matching
+
+- **Follows/Precedes Rules**: https://ast-grep.github.io/reference/rule.html#follows-precedes
+  - Sequential pattern matching
+  - Order-based validation
+
+#### Composite Rules
+- **All/Any/Not**: https://ast-grep.github.io/reference/rule.html#all-any-not
+  - Logical combinations
+  - Complex conditionals
+  - Negation patterns
+
+### Language Support
+
+#### Supported Languages
+- **Full Language List**: https://ast-grep.github.io/languages.html
+  - Python, JavaScript, TypeScript
+  - Go, Rust, Java, Kotlin
+  - C, C++, C#, Swift
+  - Ruby, PHP, Scala, Elixir
+  - HTML, CSS, Vue, Svelte
+  - And 30+ more
+
+#### Language-Specific Guides
+- **Python Patterns**: https://ast-grep.github.io/languages/python.html
+- **JavaScript Patterns**: https://ast-grep.github.io/languages/javascript.html
+- **TypeScript Patterns**: https://ast-grep.github.io/languages/typescript.html
+- **Go Patterns**: https://ast-grep.github.io/languages/go.html
+
+### Security Scanning
+
+#### Security Rules
+- **Security Templates**: https://ast-grep.github.io/guide/security.html
+  - SQL injection detection
+  - XSS vulnerability scanning
+  - Hardcoded credential detection
+  - Insecure dependency checks
+
+#### OWASP Integration
+- **OWASP Top 10**: https://ast-grep.github.io/guide/security.html#owasp-top-10
+  - Injection attacks
+  - Broken authentication
+  - Sensitive data exposure
+  - Security misconfigurations
+
+### Refactoring & Transformation
+
+#### Code Transformation
+- **Rewrite Rules**: https://ast-grep.github.io/reference/rule.html#fix
+  - Pattern-to-pattern mapping
+  - Variable substitution
+  - Multi-file transformations
+
+#### Refactoring Patterns
+- **Common Refactorings**: https://ast-grep.github.io/guide/refactoring.html
+  - API migration
+  - Function renaming
+  - Code modernization
+  - Design pattern application
+
+### Testing & Validation
+
+#### Rule Testing
+- **Test Framework**: https://ast-grep.github.io/guide/test.html
+  - Snapshot testing
+  - Inline test cases
+  - Test organization
+
+#### CI/CD Integration
+- **GitHub Actions**: https://ast-grep.github.io/guide/ci.html#github-actions
+  - Workflow examples
+  - Automated scanning
+  - PR integration
+
+- **Pre-commit Hooks**: https://ast-grep.github.io/guide/ci.html#pre-commit
+  - Local validation
+  - Fast feedback
+  - Configuration examples
+
+### Context7 Integration
+
+- **Library Resolution**: Use `mcp__context7__resolve-library-id` with query "ast-grep"
+- **Documentation Fetch**: Use `mcp__context7__get-library-docs` for latest docs
+
+### Module Organization
+
+This skill contains 4 modules:
+
+- **modules/pattern-syntax.md** - Complete pattern syntax reference
+  - Meta-variable types
+  - Wildcard patterns
+  - String and regex matching
+  - Language-specific syntax
+
+- **modules/security-rules.md** - Security scanning rule templates
+  - SQL injection detection
+  - XSS vulnerability patterns
+  - Hardcoded secret detection
+  - Insecure dependency checks
+  - OWASP Top 10 coverage
+
+- **modules/refactoring-patterns.md** - Common refactoring patterns
+  - API migration patterns
+  - Function/method renaming
+  - Code modernization
+  - Design pattern applications
+  - Multi-file transformations
+
+- **modules/language-specific.md** - Language-specific patterns
+  - Python patterns (decorators, context managers, etc.)
+  - JavaScript/TypeScript patterns (React hooks, async/await, etc.)
+  - Go patterns (error handling, interfaces, etc.)
+  - Rust patterns (macros, traits, etc.)
+
+### MoAI-ADK Integration
+
+#### Tool Registry
+- **Registration**: `tool_registry.py` as AST_ANALYZER type
+- **Permissions**: Auto-allowed for `Bash(sg:*)` and `Bash(ast-grep:*)`
+- **Hooks**: PostToolUse hook for automatic security scanning
+
+#### Running Scans
+```bash
+# Scan with MoAI-ADK rules
+sg scan --config .claude/skills/moai-tool-ast-grep/rules/sgconfig.yml
+
+# Scan specific directory
+sg scan --config sgconfig.yml src/
+
+# JSON output for CI/CD
+sg scan --config sgconfig.yml --json > results.json
+```
+
+### Community & Support
+
+- **GitHub Discussions**: https://github.com/ast-grep/ast-grep/discussions
+  - Q&A threads
+  - Pattern sharing
+  - Community rules
+
+- **Discord Server**: https://discord.gg/HuWxGYW6Pc
+  - Real-time chat
+  - Pattern help
+  - Feature discussions
+
+- **Twitter**: https://twitter.com/ast_grep
+  - Updates and tips
+  - Pattern examples
+  - Community highlights
+
+### Related Tools
+
+#### Complementary Tools
+- **ripgrep (rg)**: https://github.com/BurntSushi/ripgrep
+  - Fast text search
+  - Regex-based filtering
+
+- **grep.app**: https://grep.app
+  - Code search across GitHub
+  - Pattern discovery
+
+- **GitHub Code Search**: https://cs.github.com
+  - Large-scale code search
+  - Cross-repository patterns
+
+### Related Skills
+
+- **moai-workflow-testing** - TDD integration, test pattern detection
+- **moai-foundation-quality** - TRUST 5 compliance, code quality gates
+- **moai-domain-backend** - API pattern detection, security scanning
+- **moai-domain-frontend** - React/Vue pattern optimization
+- **moai-lang-python** - Python-specific security and style rules
+- **moai-lang-typescript** - TypeScript type safety patterns
+
+### Related Agents
+
+- **expert-refactoring** - AST-based large-scale refactoring
+- **expert-security** - Security vulnerability scanning
+- **manager-quality** - Code complexity analysis
+- **expert-debug** - Pattern-based debugging
+
+### Books & Resources
+
+- **Refactoring**: Martin Fowler
+  - Classic refactoring patterns
+  - Code smells identification
+
+- **Clean Code**: Robert C. Martin
+  - Code quality principles
+  - Best practices
+
+- **Design Patterns**: Gang of Four
+  - Pattern implementations
+  - Structural improvements
+
+---
+
+**Last Updated**: 2026-01-06
+**Skill Version**: 1.0.0
+**Total Modules**: 4
+**Supported Languages**: 40+

moai_adk/templates/.claude/skills/moai-tool-ast-grep/rules/languages/go.yml

@@ -0,0 +1,90 @@
+# Go-specific Quality Rules
+
+id: unchecked-error
+language: go
+severity: error
+message: "Error is being ignored. Handle or explicitly ignore with comment."
+rule:
+  pattern: $RESULT, _ := $FUNC($$$ARGS)
+
+---
+id: error-without-wrap
+language: go
+severity: warning
+message: "Consider wrapping error with context using fmt.Errorf or errors.Wrap"
+rule:
+  pattern: return $ERR
+  inside:
+    pattern: |
+      if $ERR != nil {
+          $$$BODY
+      }
+
+---
+id: defer-in-loop
+language: go
+severity: warning
+message: "defer inside loop may cause resource leak. Consider moving outside."
+rule:
+  pattern: defer $FUNC($$$ARGS)
+  inside:
+    any:
+      - pattern: for $$$INIT; $$$COND; $$$POST { $$$BODY }
+      - pattern: for $$$RANGE { $$$BODY }
+
+---
+id: context-first-param
+language: go
+severity: warning
+message: "Context should be the first parameter by convention"
+rule:
+  pattern: func $NAME($$$BEFORE, ctx context.Context, $$$AFTER)
+
+---
+id: mutex-not-deferred
+language: go
+severity: warning
+message: "Consider using defer for Unlock() to prevent deadlocks"
+rule:
+  pattern: $MU.Lock()
+  not:
+    follows:
+      pattern: defer $MU.Unlock()
+
+---
+id: empty-interface
+language: go
+severity: info
+message: "Consider using 'any' instead of 'interface{}' (Go 1.18+)"
+rule:
+  pattern: interface{}
+
+---
+id: time-now-sub
+language: go
+severity: info
+message: "Use time.Since() instead of time.Now().Sub()"
+rule:
+  pattern: time.Now().Sub($TIME)
+fix: time.Since($TIME)
+
+---
+id: bytes-compare
+language: go
+severity: info
+message: "Use bytes.Equal() for comparing byte slices"
+rule:
+  any:
+    - pattern: bytes.Compare($A, $B) == 0
+    - pattern: bytes.Compare($A, $B) != 0
+fix: bytes.Equal($A, $B)
+
+---
+id: string-bytes-conversion
+language: go
+severity: info
+message: "Unnecessary string/[]byte conversion may impact performance"
+rule:
+  any:
+    - pattern: string([]byte($STR))
+    - pattern: "[]byte(string($BYTES))"

moai_adk/templates/.claude/skills/moai-tool-ast-grep/rules/languages/python.yml

@@ -0,0 +1,101 @@
+# Python-specific Quality Rules
+
+id: use-fstring
+language: python
+severity: info
+message: "Consider using f-strings for string formatting"
+rule:
+  any:
+    - pattern: "$$$STR".format($$$ARGS)
+    - pattern: "$$$STR" % $ARGS
+
+---
+id: use-pathlib
+language: python
+severity: info
+message: "Consider using pathlib for file path operations"
+rule:
+  any:
+    - pattern: os.path.join($$$ARGS)
+    - pattern: os.path.exists($PATH)
+    - pattern: os.path.isfile($PATH)
+    - pattern: os.path.isdir($PATH)
+
+---
+id: use-context-manager
+language: python
+severity: warning
+message: "Use context manager (with statement) for file operations"
+rule:
+  pattern: |
+    $FILE = open($PATH)
+    $$$BODY
+    $FILE.close()
+fix: |
+  with open($PATH) as $FILE:
+      $$$BODY
+
+---
+id: bare-except
+language: python
+severity: warning
+message: "Avoid bare except clauses. Catch specific exceptions."
+rule:
+  pattern: |
+    except:
+        $$$BODY
+
+---
+id: mutable-default-argument
+language: python
+severity: warning
+message: "Mutable default argument. Use None and initialize inside function."
+rule:
+  any:
+    - pattern: def $FUNC($$$ARGS, $PARAM=[], $$$REST):
+    - pattern: def $FUNC($$$ARGS, $PARAM={}, $$$REST):
+
+---
+id: type-comparison
+language: python
+severity: warning
+message: "Use isinstance() instead of type comparison"
+rule:
+  pattern: type($OBJ) == $TYPE
+fix: isinstance($OBJ, $TYPE)
+
+---
+id: dict-get-default
+language: python
+severity: info
+message: "Use dict.get() with default instead of conditional"
+rule:
+  pattern: |
+    if $KEY in $DICT:
+        $VAR = $DICT[$KEY]
+    else:
+        $VAR = $DEFAULT
+fix: $VAR = $DICT.get($KEY, $DEFAULT)
+
+---
+id: list-comprehension-opportunity
+language: python
+severity: info
+message: "Consider using list comprehension"
+rule:
+  pattern: |
+    $RESULT = []
+    for $ITEM in $ITER:
+        $RESULT.append($EXPR)
+
+---
+id: use-enumerate
+language: python
+severity: info
+message: "Use enumerate() instead of manual index tracking"
+rule:
+  pattern: |
+    $IDX = 0
+    for $ITEM in $ITER:
+        $$$BODY
+        $IDX += 1

moai_adk/templates/.claude/skills/moai-tool-ast-grep/rules/languages/typescript.yml

@@ -0,0 +1,83 @@
+# TypeScript-specific Quality Rules
+
+id: avoid-any-type
+language: typescript
+severity: warning
+message: "Avoid using 'any' type. Be more specific."
+rule:
+  any:
+    - pattern: "const $NAME: any = $VALUE"
+    - pattern: "let $NAME: any = $VALUE"
+    - pattern: "function $FUNC($$$ARGS): any"
+    - pattern: "$PARAM: any"
+
+---
+id: prefer-as-over-angle-bracket
+language: typescript
+severity: info
+message: "Prefer 'as' syntax for type assertions"
+rule:
+  pattern: <$TYPE>$EXPR
+fix: $EXPR as $TYPE
+
+---
+id: use-optional-chaining
+language: typescript
+severity: info
+message: "Use optional chaining instead of && chain"
+rule:
+  pattern: $OBJ && $OBJ.$PROP
+fix: $OBJ?.$PROP
+
+---
+id: use-nullish-coalescing
+language: typescript
+severity: info
+message: "Use nullish coalescing operator"
+rule:
+  any:
+    - pattern: $VAR !== null && $VAR !== undefined ? $VAR : $DEFAULT
+    - pattern: $VAR != null ? $VAR : $DEFAULT
+fix: $VAR ?? $DEFAULT
+
+---
+id: prefer-const
+language: typescript
+severity: info
+message: "Prefer const over let for variables that are not reassigned"
+rule:
+  pattern: let $NAME = $VALUE
+
+---
+id: no-non-null-assertion
+language: typescript
+severity: warning
+message: "Avoid non-null assertion. Handle null cases explicitly."
+rule:
+  pattern: $EXPR!
+
+---
+id: prefer-interface-over-type
+language: typescript
+severity: info
+message: "Prefer interface over type alias for object types"
+rule:
+  pattern: type $NAME = { $$$PROPS }
+
+---
+id: explicit-return-type
+language: typescript
+severity: info
+message: "Consider adding explicit return type annotation"
+rule:
+  pattern: "function $NAME($$$ARGS) { $$$BODY }"
+  not:
+    pattern: "function $NAME($$$ARGS): $TYPE { $$$BODY }"
+
+---
+id: prefer-readonly
+language: typescript
+severity: info
+message: "Consider using readonly for properties that are not modified"
+rule:
+  pattern: "interface $NAME { $PROP: $TYPE; }"

moai_adk/templates/.claude/skills/moai-tool-ast-grep/rules/quality/complexity-check.yml

@@ -0,0 +1,94 @@
+# Code Complexity and Quality Rules
+
+id: deeply-nested-code
+language: javascript
+severity: warning
+message: "Deeply nested code is hard to read. Consider refactoring."
+rule:
+  pattern: |
+    if ($COND1) {
+      if ($COND2) {
+        if ($COND3) {
+          $$$BODY
+        }
+      }
+    }
+
+---
+id: deeply-nested-code-python
+language: python
+severity: warning
+message: "Deeply nested code is hard to read. Consider refactoring."
+rule:
+  pattern: |
+    if $COND1:
+        if $COND2:
+            if $COND3:
+                $$$BODY
+
+---
+id: long-function-params-js
+language: javascript
+severity: warning
+message: "Function has too many parameters. Consider using an options object."
+rule:
+  pattern: function $NAME($P1, $P2, $P3, $P4, $P5, $$$REST) { $$$BODY }
+
+---
+id: long-function-params-python
+language: python
+severity: warning
+message: "Function has too many parameters. Consider using **kwargs or a config object."
+rule:
+  pattern: def $NAME($P1, $P2, $P3, $P4, $P5, $P6, $$$REST):
+
+---
+id: callback-hell
+language: javascript
+severity: warning
+message: "Callback hell detected. Consider using async/await or Promises."
+rule:
+  pattern: |
+    $FUNC1($$$ARGS1, function($$$P1) {
+      $FUNC2($$$ARGS2, function($$$P2) {
+        $FUNC3($$$ARGS3, function($$$P3) {
+          $$$BODY
+        })
+      })
+    })
+
+---
+id: empty-catch-block
+language: javascript
+severity: warning
+message: "Empty catch block. Handle or log the error."
+rule:
+  pattern: |
+    catch ($ERR) {
+    }
+
+---
+id: empty-catch-block-python
+language: python
+severity: warning
+message: "Empty except block. Handle or log the exception."
+rule:
+  pattern: |
+    except $EXC:
+        pass
+
+---
+id: console-log-in-production
+language: javascript
+severity: info
+message: "console.log should be removed in production code"
+rule:
+  pattern: console.log($$$ARGS)
+
+---
+id: print-statement-python
+language: python
+severity: info
+message: "print() should be replaced with proper logging in production"
+rule:
+  pattern: print($$$ARGS)