A smart, framework-aware tool for enforcing naming conventions in Python and TypeScript/JavaScript codebases. Unlike traditional linters, Grammar-Ops understands your code's context and respects framework idioms.

# Install grammar-ops cd grammar-ops export PATH="$PWD/bin:$PATH" # Analyze your project grammar-ops analyze /path/to/project # Learn from existing code grammar-ops learn /path/to/project -o my-conventions.json # Migrate code interactively grammar-ops migrate /path/to/project --dry-run

grammar-ops/ ├── bin/ # Executable scripts │ └── grammar-ops # Main CLI entry point │ ├── lib/ # Core library modules │ ├── core/ # Core functionality │ │ └── framework_detector.py │ ├── analyzers/ # Code analyzers │ │ ├── context_analyzer.py │ │ └── constant_detector.py │ └── reporters/ # Output formatters │ └── enhanced_reporter.py │ ├── tools/ # Standalone tools │ ├── learn.py # Learn patterns from code │ └── migrate.py # Migrate code to conventions │ ├── scripts/ # Original audit scripts │ ├── audit-*.sh # Shell-based auditors │ └── *.js/*.py # Language-specific scripts │ ├── config/ # Configuration files │ ├── schema-v2.json # Enhanced config schema │ └── *.json # Other schemas │ ├── examples/ # Example configurations │ ├── sample-configs/ # Config examples │ └── sample-projects/ # Demo projects │ ├── docs/ # Documentation │ ├── ENHANCED_FEATURES.md │ └── *.md # Other docs │ └── templates/ # Code templates 

Automatically detects and respects framework conventions:

• Python: FastAPI, Django, Flask, Typer, Click, Pytest
• JavaScript: React, Vue, Angular, Next.js (coming soon)

Understands function context before applying rules:

• CLI commands can use Rails-style naming (start, stop)
• Test functions already have test_ prefix
• Response factories follow constructor patterns
• Fixtures are nouns, not actions

Distinguishes between:

• True constants (MAX_RETRIES = 3)
• Singleton instances (app = FastAPI())
• TypeVar declarations (T = TypeVar('T'))
• Logger instances (logger = logging.getLogger())

Learn from your existing codebase:

grammar-ops learn . -o learned.json

Safely migrate with preview and rollback:

grammar-ops migrate . --dry-run # Preview grammar-ops migrate . # Apply grammar-ops migrate . --rollback # Undo

grammar-ops analyze [path] [options] Options: -p, --pattern File pattern (default: **/*.py) -v, --verbose Show detailed issues -m, --max-issues Maximum issues to show --no-color Disable colored output

grammar-ops learn [path] [options] Options: -o, --output Output config file -r, --report Show detailed report

grammar-ops migrate [path] [options] Options: -c, --config Config file to use -p, --pattern File pattern -d, --dry-run Preview changes --rollback Undo previous migration

grammar-ops detect [path]

Create .grammarops.config.json in your project:

{ "project": { "type": "fullstack", "language": "python" }, "frameworks": { "auto_detect": true }, "rules": { "python": { "functions": { "require_verb_prefix": { "enabled": true, "exceptions": { "cli_commands": "rails_style" } } } } } }

Let Grammar-Ops learn your patterns:

# Learn patterns grammar-ops learn . -o .grammarops.config.json # Review and adjust cat .grammarops.config.json # Use it grammar-ops analyze .

The scripts/ directory contains the original grammar-ops scripts:

• Metadata Management: add-*.sh scripts
• Auditing: audit-*.sh scripts
• Component Generation: generate-component.js
• Validation: validate-*.js scripts

These scripts work independently and can be used directly:

./scripts/audit-python-naming.sh ./scripts/add-python-metadata.sh

@cli.command() def start(): # ✓ Grammar-Ops understands this """Start the service"""

def test_user_can_login(): # ✓ No "verb prefix" warning assert user.login()

app = FastAPI() # ✓ Not flagged as "should be UPPER_CASE" router = APIRouter() # ✓ Framework pattern recognized

T = TypeVar('T') # ✓ Typing convention understood UserT = TypeVar('UserT', bound=User) # ✓ Also OK

1. Framework patterns not recognized? Add to lib/core/framework_detector.py
2. New context needed? Update lib/analyzers/context_analyzer.py
3. Better error messages? Enhance lib/reporters/enhanced_reporter.py

• Enhanced Features Documentation
• Full Grammar System
• Naming Conventions

1. Analyze Current State

   grammar-ops analyze . --verbose

2. Learn Your Patterns

   grammar-ops learn . -o my-patterns.json

3. Configure Exceptions

   cp my-patterns.json .grammarops.config.json # Edit to adjust rules

4. Gradual Migration

   # Start with new files only # Then expand to existing code grammar-ops migrate . --dry-run

5. Integrate with CI/CD

   - name: Check Grammar run: grammar-ops analyze .

Grammar-Ops believes that:

• Context matters: A CLI command doesn't need execute_ prefix
• Frameworks have idioms: app = FastAPI() is correct, not APP
• Gradual adoption works: Don't break working code
• Developers know best: Learn from existing patterns

Start using Grammar-Ops today for smarter, context-aware code conventions!