Integrate sync-ai-rules into pre-commit-hooks (#52)

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

Author: kush-duolingo

.dockerignore

@@ -6,3 +6,4 @@
 !ruff.toml
 !stylesheet.xml
 !svgo.config.js
+!sync_ai_rules

.pre-commit-hooks.yaml

@@ -3,14 +3,30 @@
   entry: duolingo/pre-commit-hooks:1.10.0 /entry
   language: docker_image
   types: [text]
+  exclude: &sync_ai_rules_output (AGENTS|CLAUDE|copilot-instructions)\.md$
 
-# Nobody should ever use this hook in production. It's just for testing PRs in
+- id: sync-ai-rules
+  name: Sync AI Rules
+  entry: &sync_ai_rules_entry sh -c "PYTHONPATH=/ python3 -m sync_ai_rules"
+  language: docker
+  files: ^\.cursor/rules/.*\.mdc$
+  pass_filenames: false
+
+# Nobody should ever use these hooks in production. They're just for testing PRs in
 # the duolingo/pre-commit-hooks repo more easily without having to tag and push
-# temporary images to Docker Hub. Usage: edit a consumer repo's `id: duolingo`
-# hook config to instead declare `id: duolingo-dev` and `rev: <PR branch SHA>`,
-# then run `pre-commit run duolingo-dev --all-files`
+# temporary images to Docker Hub. Usage: edit a consumer repo's hook config to
+# instead declare `id: duolingo-dev` or `id: sync-ai-rules-dev` and `rev: <PR branch SHA>`,
+# then run `pre-commit run <hook-id> --all-files`
 - id: duolingo-dev
   name: Duolingo (dev)
   entry: /entry
   language: docker
   types: [text]
+  exclude: *sync_ai_rules_output
+
+- id: sync-ai-rules-dev
+  name: Sync AI Rules (dev)
+  entry: *sync_ai_rules_entry
+  language: docker
+  files: ^\.cursor/rules/.*\.mdc$
+  pass_filenames: false

Dockerfile

@@ -46,7 +46,8 @@ apk add --no-cache \
 pip3 install --break-system-packages \
   autoflake==1.7.8 \
   isort==5.13.2 \
-  ruff==0.7.3
+  ruff==0.7.3 \
+  PyYAML>=6.0
 
 # Install Python dependencies
 python3 -m venv /black21-venv

README.md

@@ -1,6 +1,10 @@
 # pre-commit hooks
 
-This repo currently contains a single [pre-commit](https://pre-commit.com/) hook that internally runs several code formatters in parallel:
+This repo contains [pre-commit](https://pre-commit.com/) hooks for Duolingo development:
+
+## Code Formatting Hook (`duolingo`)
+
+The main hook that runs several code formatters in parallel:
 
 - [Prettier](https://github.com/prettier/prettier) v3.5.3 for CSS, HTML, JS, JSX, Markdown, Sass, TypeScript, XML, YAML
 - [ESLint](https://eslint.org/) v9.23.0 for JS, TypeScript
@@ -29,18 +33,25 @@ To minimize developer friction, we enable only rules whose violations can be fix
 
 We run this hook on developer workstations and enforce it in CI for all production repos at Duolingo.
 
+## Sync AI Rules Hook (`sync-ai-rules`)
+
+This hook synchronizes AI coding rules from .cursor/rules/\*.mdc files to other AI assistant configuration files (CLAUDE.md, AGENTS.md, etc.). This ensures all AI coding assistants in your project stay aware of the same rules and conventions, eliminating the need to manually copy rules between different AI config files.
+
 ## Usage
 
-Repo maintainers can declare this hook in `.pre-commit-config.yaml`:
+Repo maintainers can declare these hooks in `.pre-commit-config.yaml`:
 
 ```yaml
 - repo: https://github.com/duolingo/pre-commit-hooks.git
   rev: 1.10.0
   hooks:
+    # Code formatting hook
     - id: duolingo
       args: # Optional
         - --python-version=2 # Defaults to Python 3
         - --scala-version=3 # Defaults to Scala 2.12
+    # Sync AI rules hook (for repos with Cursor AI rules)
+    - id: sync-ai-rules
 ```
 
 Directories named `build` and `node_modules` are excluded by default - no need to declare them in the hook's `exclude` key.

sync_ai_rules/.gitignore

@@ -0,0 +1,7 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Ruff cache
+.ruff_cache/

sync_ai_rules/README.md

@@ -0,0 +1,52 @@
+# sync-ai-rules
+
+- Synchronize AI coding rules from .cursor/rules/\*.mdc files to other AI assistant configuration files (CLAUDE.md, AGENTS.md, etc.)
+- Built with a plugin architecture that can easily support new input/output formats as the ecosystem evolves
+
+## Extending to new formats
+
+### Adding New Input Parsers
+
+Create a parser class implementing `InputParser` in `sync_ai_rules/parsers/`:
+
+```python
+from sync_ai_rules.core.interfaces import InputParser, RuleMetadata
+
+class YourParser(InputParser):
+    @property
+    def name(self) -> str:
+        return "your-format"
+
+    # Implement required methods...
+```
+
+### Adding New Output Generators
+
+Create a generator class implementing `OutputGenerator` in `sync_ai_rules/generators/`:
+
+```python
+from sync_ai_rules.core.interfaces import OutputGenerator
+
+class YourGenerator(OutputGenerator):
+    @property
+    def name(self) -> str:
+        return "your-output"
+
+    # Implement required methods...
+```
+
+### Register Your Extensions
+
+Add them to `sync_ai_rules/plugins.yaml`:
+
+```yaml
+parsers:
+  - name: your-format
+    module: your_parser
+    class: YourParser
+
+generators:
+  - name: your-output
+    module: your_generator
+    class: YourGenerator
+```

sync_ai_rules/__init__.py

@@ -0,0 +1,3 @@
+"""Sync AI Rules - Automates generation of AI rule configurations."""
+
+__version__ = "1.0.0"

sync_ai_rules/__main__.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""
+This script uses a plugin architecture to parse rules and generate documentation.
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+from sync_ai_rules.core.interfaces import RuleMetadata
+from sync_ai_rules.core.plugin_manager import PluginManager
+from sync_ai_rules.file_updater import update_documentation_file
+
+
+def find_project_root() -> str:
+    """Find the project root by looking for key indicators."""
+    current = Path.cwd()
+
+    # Look for .cursor/rules directory
+    for path in [current] + list(current.parents):
+        if (path / ".cursor" / "rules").exists():
+            return str(path)
+
+    # Fallback to current directory
+    return str(current)
+
+
+def get_category(file_path: str, rules_dir: str) -> str:
+    """Get category name from file path."""
+    rel_path = os.path.relpath(file_path, rules_dir)
+    folder = os.path.dirname(rel_path)
+
+    if not folder or folder == ".":
+        return "root"
+
+    return folder
+
+
+def group_rules_by_category(rules: List[RuleMetadata]) -> Dict[str, List[RuleMetadata]]:
+    """Group rules by their category."""
+    groups = {}
+
+    for rule in rules:
+        category = rule.category
+        if category not in groups:
+            groups[category] = []
+        groups[category].append(rule)
+
+    return groups
+
+
+def main():
+    """Main entry point."""
+    # Find project root
+    project_root = find_project_root()
+    rules_dir = os.path.join(project_root, ".cursor", "rules")
+
+    if not os.path.exists(rules_dir):
+        print(f"Error: Rules directory not found: {rules_dir}")
+        sys.exit(1)
+
+    print(f"Syncing rules from: {rules_dir}")
+
+    # Initialize plugin manager
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    plugin_manager = PluginManager()
+    plugin_manager.load_plugins(script_dir)
+
+    # Scan for rules using available parsers
+    rules = []
+    for root, dirs, files in os.walk(rules_dir):
+        # Skip generated and personal directories
+        if "generated" in Path(root).parts or "personal" in Path(root).parts:
+            continue
+
+        for file in files:
+            file_path = os.path.join(root, file)
+
+            # Find appropriate parser
+            parser = plugin_manager.get_parser_for_file(file_path)
+            if not parser:
+                continue
+
+            # Create parsing context
+            context = {
+                "relative_path": os.path.relpath(file_path, project_root),
+                "category": get_category(file_path, rules_dir),
+            }
+
+            # Parse the rule
+            rule = parser.parse(file_path, context)
+            if rule:
+                rules.append(rule)
+
+    if not rules:
+        print("No rules found to sync")
+        return
+
+    # Group rules by category
+    grouped_rules = group_rules_by_category(rules)
+
+    # Get markdown generator
+    generator = plugin_manager.get_generator("markdown")
+    if not generator:
+        print("Error: Markdown generator not found")
+        sys.exit(1)
+
+    # Generate content
+    content = generator.generate(grouped_rules, {})
+
+    # Print summary
+    total_rules = sum(len(rules) for rules in grouped_rules.values())
+    print(f"\nFound {total_rules} rules in {len(grouped_rules)} categories")
+
+    # Update output files using generator's default filenames
+    output_files = [
+        os.path.join(project_root, filename) for filename in generator.default_filenames
+    ]
+
+    for file_path in output_files:
+        success, message = update_documentation_file(
+            file_path, content, generator.get_section_markers()
+        )
+
+        if success:
+            print(f"✓ {message}")
+        else:
+            print(f"✗ {message}")
+
+    print("\n✓ Rules synchronization completed!")
+
+
+if __name__ == "__main__":
+    main()

sync_ai_rules/core/__init__.py

@@ -0,0 +1 @@
+"""Core plugin system for sync-ai-rules."""

sync_ai_rules/core/interfaces.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+Core interfaces for sync_ai_rules plugin system.
+Defines abstract base classes for parsers and generators.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class RuleMetadata:
+    """Universal rule representation, format-agnostic."""
+
+    file_path: str
+    relative_path: str
+    title: str
+    description: str
+    scope_patterns: List[str]
+    always_apply: bool
+    category: str
+    raw_content: str
+    metadata: Dict[str, Any] = None
+
+    def __post_init__(self):
+        if self.metadata is None:
+            self.metadata = {}
+
+
+class InputParser(ABC):
+    """Abstract base class for all input parsers."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique name for this parser."""
+
+    @property
+    @abstractmethod
+    def supported_extensions(self) -> List[str]:
+        """File extensions this parser can handle."""
+
+    @abstractmethod
+    def can_parse(self, file_path: str) -> bool:
+        """Check if this parser can handle the given file."""
+
+    @abstractmethod
+    def parse(self, file_path: str, context: Dict[str, Any]) -> Optional[RuleMetadata]:
+        """Parse a file and return standardized metadata."""
+
+
+class OutputGenerator(ABC):
+    """Abstract base class for all output generators."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique name for this generator."""
+
+    @property
+    @abstractmethod
+    def default_filenames(self) -> List[str]:
+        """Default output filenames."""
+
+    @abstractmethod
+    def generate(self, rules: Dict[str, List[RuleMetadata]], config: Dict[str, Any]) -> str:
+        """Generate output content from grouped rules."""
+
+    @abstractmethod
+    def get_section_markers(self) -> tuple[str, str]:
+        """Return start and end markers for auto-generated section."""