fix + feat: OPE-143 -- Cursor .mdc format complete and working

DevanshuNEU · DevanshuNEU · commit 39af7f69259a · 2026-03-12T14:34:13.000-04:00
Bug fixed:
  cursor_mdc.py referenced fp.data_fetching which does not exist on FrontendPattern.
  The correct field is fp.uses_react_query (bool), introduced back in v0.3.x.
  This caused AttributeError on any repo with TypeScript frontend when generating
  .mdc files, making the entire cursor-mdc format broken.

  Fix: replace fp.data_fetching with fp.uses_react_query and generate the rule
  as a hardcoded best-practice ('use useQuery/useMutation -- never raw fetch')
  rather than interpolating a field that doesn't exist.

What OPE-143 delivers (Cursor .mdc format):
  --format cursor-mdc generates .cursor/rules/*.mdc files instead of flat .cursorrules.
  .mdc is Cursor v2 format: each file has YAML frontmatter with glob patterns so
  rules only load when editing matching files. Better than .cursorrules which
  loads ALL rules for every file.

  Output for fastapi-template:
    .cursor/rules/core.mdc      -- alwaysApply: true, verify workflow, package manager
    .cursor/rules/backend.mdc   -- globs: [**/*.py], auth rules WITH reasoning, ORM, testing
    .cursor/rules/frontend.mdc  -- globs: [**/*.ts, **/*.tsx], React/shadcn/TanStack rules
    .cursor/rules/tests.mdc     -- globs: [**/test_*.py], pytest fixtures, parametrize

  Auto-detection (OPE-141 integration):
    When .cursor/ dir exists, saar prefers cursor-mdc over flat cursorrules.
    'saar extract .' on a Cursor v2 workspace just works.

Tests: 496 passing (was 1 failing, now fixed)
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "saar"
-version = "0.5.6"
+version = "0.5.7"
 description = "Extract the essence of your codebase. Auto-generate AGENTS.md, CLAUDE.md, .cursorrules and more."
 readme = "README.md"
 license = "MIT"
diff --git a/saar/__init__.py b/saar/__init__.py
@@ -1,3 +1,3 @@
 """Saar -- extract the essence of your codebase."""
 
-__version__ = "0.5.6"
+__version__ = "0.5.7"
diff --git a/saar/cli.py b/saar/cli.py
@@ -54,6 +54,7 @@ class OutputFormat(str, Enum):
     markdown = "markdown"
     claude = "claude"
     cursorrules = "cursorrules"
+    cursor_mdc = "cursor-mdc"   # Cursor v2 -- .cursor/rules/*.mdc with glob loading
     copilot = "copilot"
     all = "all"
 
@@ -341,6 +342,7 @@ def extract(
             OutputFormat.agents,
             OutputFormat.claude,
             OutputFormat.cursorrules,
+            OutputFormat.cursor_mdc,
             OutputFormat.copilot,
         ]
     else:
@@ -407,6 +409,11 @@ def extract(
     from saar.formatters import render
 
     for fmt in target_formats:
+        # cursor_mdc is a multi-file format -- special handling
+        if fmt == OutputFormat.cursor_mdc:
+            _write_cursor_mdc(dna, output or repo_path, force=force, console=console)
+            continue
+
         text = render(dna, fmt.value, budget=effective_budget)
         target = _resolve_output_path(fmt, output, repo_path)
 
@@ -568,6 +575,51 @@ def _show_detection_summary(dna, console, no_interview: bool) -> bool:
         return True
 
 
+def _write_cursor_mdc(dna, base_dir: Path, *, force: bool, console: Console) -> None:
+    """Write .cursor/rules/*.mdc files for Cursor v2 format (OPE-143).
+
+    Why separate from _write_with_markers:
+      .mdc files are generated in a directory, not a single file.
+      They don't use SAAR markers -- they're fully regenerated each time
+      because Cursor manages them as a set. Existing .mdc files written
+      by saar are always overwritten; hand-crafted ones are skipped (OPE-181).
+    """
+    from saar.formatters.cursor_mdc import render_cursor_mdc
+
+    rules_dir = base_dir / ".cursor" / "rules"
+    rules_dir.mkdir(parents=True, exist_ok=True)
+
+    mdc_files = render_cursor_mdc(dna)
+    if not mdc_files:
+        return
+
+    written = []
+    skipped = []
+    for filename, content in mdc_files.items():
+        target = rules_dir / filename
+        if target.exists() and not force:
+            # check if it's saar-generated (has our frontmatter signature)
+            existing = target.read_text(encoding="utf-8")
+            is_ours = "alwaysApply:" in existing  # saar always writes this field
+            if not is_ours:
+                skipped.append(filename)
+                continue
+        target.write_text(content, encoding="utf-8")
+        written.append(filename)
+
+    if written:
+        files_str = ", ".join(written)
+        console.print(
+            f"  [green]wrote[/green] .cursor/rules/  "
+            f"[dim]({files_str})[/dim]"
+        )
+    if skipped:
+        console.print(
+            f"  [yellow]skipped[/yellow] .cursor/rules/{skipped[0]}  "
+            f"[dim](hand-crafted — use --force to overwrite)[/dim]"
+        )
+
+
 def _detect_ai_tools(repo_path: Path) -> list[OutputFormat]:
     """Detect which AI tools are present in the repo and return matching formats.
 
@@ -585,9 +637,11 @@ def _detect_ai_tools(repo_path: Path) -> list[OutputFormat]:
     """
     detected: list[OutputFormat] = []
 
-    # Cursor -- check for .cursor/ dir (Cursor v2 workspace) or legacy .cursorrules
-    if (repo_path / ".cursor").is_dir() or (repo_path / ".cursorrules").exists():
-        detected.append(OutputFormat.cursorrules)
+    # Cursor -- prefer .mdc (v2) when .cursor/ dir exists, fall back to flat .cursorrules
+    if (repo_path / ".cursor").is_dir():
+        detected.append(OutputFormat.cursor_mdc)   # .cursor/rules/*.mdc files
+    elif (repo_path / ".cursorrules").exists():
+        detected.append(OutputFormat.cursorrules)   # legacy flat file
 
     # Claude Code -- CLAUDE.md already present means user wants it maintained
     if (repo_path / "CLAUDE.md").exists():
diff --git a/saar/formatters/cursor_mdc.py b/saar/formatters/cursor_mdc.py
@@ -0,0 +1,250 @@
+"""Cursor .mdc rule formatter (OPE-143).
+
+Generates .cursor/rules/*.mdc files with YAML frontmatter and glob-based
+conditional loading. This is the Cursor v2 format, strictly better than
+flat .cursorrules because rules load only when editing matching files.
+
+Why this matters:
+  .cursorrules loads ALL rules for every file.
+  .mdc loads ONLY the rules relevant to the file being edited.
+  A Python backend rule never loads when editing a React component.
+  Shorter context = more precise AI behavior.
+
+.mdc format:
+  ---
+  description: Short summary shown in Cursor UI
+  globs: ["**/*.py"]    # only load for Python files
+  alwaysApply: false    # true = load regardless of file
+  ---
+  # Rule content here (markdown)
+
+Output: dict[filename, content] where filename is relative to .cursor/rules/
+  e.g. {"backend.mdc": "---\\n...", "frontend.mdc": "---\\n..."}
+
+The CLI writes each entry to .cursor/rules/<filename>.
+"""
+from __future__ import annotations
+
+from saar.models import CodebaseDNA
+
+
+def _frontmatter(description: str, globs: list[str], always: bool = False) -> str:
+    """Build YAML frontmatter block for a .mdc file."""
+    lines = ["---", f"description: {description}"]
+    if globs:
+        # Cursor expects a JSON array in the globs field
+        glob_str = ", ".join(f'"{g}"' for g in globs)
+        lines.append(f"globs: [{glob_str}]")
+    lines.append(f"alwaysApply: {'true' if always else 'false'}")
+    lines.append("---")
+    return "\n".join(lines)
+
+
+def render_cursor_mdc(dna: CodebaseDNA) -> dict[str, str]:
+    """Render DNA as a set of .mdc rule files for .cursor/rules/.
+
+    Returns a dict mapping filename -> file content.
+    Each .mdc file targets a specific part of the codebase via globs.
+    """
+    files: dict[str, str] = {}
+
+    fp = dna.frontend_patterns
+    has_python = dna.language_distribution.get("python", 0) > 0
+    has_ts = dna.language_distribution.get("typescript", 0) > 0
+    has_js = dna.language_distribution.get("javascript", 0) > 0
+
+    # ── core.mdc -- always loaded, project-level rules ────────────────────
+    core_lines: list[str] = []
+
+    if dna.detected_framework:
+        core_lines.append(f"This is a **{dna.detected_framework}** project.\n")
+
+    # verify workflow -- always relevant
+    if dna.verify_workflow:
+        core_lines.append("## How to Verify Changes\n")
+        core_lines.append(dna.verify_workflow)
+        core_lines.append("\nRun these before considering any change done.\n")
+
+    # package manager
+    if fp and fp.package_manager:
+        core_lines.append("## Package Manager\n")
+        core_lines.append(
+            f"- Always use `{fp.package_manager}` — never npm or yarn"
+        )
+
+    # deep rules that are always relevant (never_do, auth)
+    deep_rules = getattr(dna, "deep_rules", [])
+    never_do = [r for r in deep_rules if r.get("category") == "never_do"]
+    if never_do:
+        core_lines.append("\n## Never Do\n")
+        for r in never_do[:5]:
+            core_lines.append(f"- {r['text']}")
+
+    # team rules
+    if dna.team_rules:
+        core_lines.append("\n## Project-Specific Rules\n")
+        core_lines.append(dna.team_rules.strip())
+
+    if core_lines:
+        content = _frontmatter(
+            f"{dna.repo_name} project rules",
+            globs=[],
+            always=True,
+        )
+        content += "\n\n" + "\n".join(core_lines).strip() + "\n"
+        files["core.mdc"] = content
+
+    # ── backend.mdc -- Python files only ─────────────────────────────────
+    if has_python:
+        backend_lines: list[str] = []
+        backend_globs = ["**/*.py"]
+
+        # auth deep rules
+        auth_deep = [r for r in deep_rules if r.get("category") == "auth"]
+        if auth_deep:
+            backend_lines.append("## Auth\n")
+            for r in auth_deep[:3]:
+                backend_lines.append(f"- {r['text']}")
+
+        # exception rules
+        exc_deep = [r for r in deep_rules if r.get("category") == "exceptions"]
+        ep = dna.error_patterns
+        if exc_deep or ep.exception_classes:
+            backend_lines.append("\n## Error Handling\n")
+            for r in exc_deep[:2]:
+                backend_lines.append(f"- {r['text']}")
+            if ep.exception_classes and not exc_deep:
+                all_exc = ep.exception_classes
+                if len(all_exc) <= 10:
+                    backend_lines.append(
+                        f"- Use domain exceptions: `{', '.join(all_exc)}`"
+                    )
+                else:
+                    top = all_exc[:8]
+                    backend_lines.append(
+                        f"- Use domain exceptions ({len(all_exc)} total). "
+                        f"Top: `{', '.join(top)}`"
+                    )
+            if ep.http_exception_usage:
+                backend_lines.append("- Raise `HTTPException` for API errors")
+            if ep.logging_on_error:
+                backend_lines.append("- Log before re-raising")
+
+        # database
+        db = dna.database_patterns
+        if db.orm_used:
+            backend_lines.append("\n## Database\n")
+            backend_lines.append(f"- ORM: {db.orm_used}")
+            if db.id_type != "unknown":
+                backend_lines.append(f"- ID type: `{db.id_type}`")
+            if db.has_rls:
+                backend_lines.append("- RLS enabled — always respect row-level policies")
+
+        # naming
+        nc = dna.naming_conventions
+        if nc.function_style != "unknown":
+            backend_lines.append("\n## Naming\n")
+            backend_lines.append(f"- Functions: `{nc.function_style}`")
+            if nc.class_style != "unknown":
+                backend_lines.append(f"- Classes: `{nc.class_style}`")
+
+        # testing deep rules
+        test_deep = [r for r in deep_rules if r.get("category") == "testing"]
+        tp = dna.test_patterns
+        if tp.framework or test_deep:
+            backend_lines.append("\n## Testing\n")
+            if tp.framework:
+                backend_lines.append(f"- Framework: `{tp.framework}` — pattern `{tp.test_file_pattern}`")
+            for r in test_deep[:2]:
+                backend_lines.append(f"- {r['text']}")
+
+        # logging
+        lp = dna.logging_patterns
+        if lp.logger_import:
+            backend_lines.append("\n## Logging\n")
+            backend_lines.append(f"- Use `{lp.logger_import}` — never bare `print()`")
+
+        if backend_lines:
+            content = _frontmatter(
+                "Python backend rules",
+                globs=backend_globs,
+            )
+            content += "\n\n" + "\n".join(backend_lines).strip() + "\n"
+            files["backend.mdc"] = content
+
+    # ── frontend.mdc -- TypeScript/JavaScript files ───────────────────────
+    if (has_ts or has_js) and fp:
+        fe_lines: list[str] = []
+        fe_globs = []
+        if has_ts:
+            fe_globs += ["**/*.ts", "**/*.tsx"]
+        if has_js:
+            fe_globs += ["**/*.js", "**/*.jsx"]
+
+        if fp.framework:
+            fe_lines.append("## Framework\n")
+            fe_lines.append(f"- {fp.framework}")
+            if fp.component_library:
+                fe_lines.append(
+                    f"- Use `{fp.component_library}` components over custom ones"
+                )
+            if fp.state_management:
+                fe_lines.append(f"- State: {fp.state_management}")
+            if fp.uses_react_query:
+                fe_lines.append(
+                    "- Data fetching: use `useQuery`/`useMutation` — never raw `fetch` in useEffect"
+                )
+
+        # naming deep rules for frontend
+        naming_deep = [r for r in deep_rules if r.get("category") == "naming"]
+        if naming_deep:
+            fe_lines.append("\n## Naming\n")
+            for r in naming_deep[:3]:
+                fe_lines.append(f"- {r['text']}")
+
+        # frontend testing
+        if fp.test_framework:
+            fe_lines.append("\n## Testing\n")
+            fe_lines.append(f"- Framework: `{fp.test_framework}`")
+
+        if fe_lines:
+            content = _frontmatter(
+                "Frontend TypeScript/React rules",
+                globs=fe_globs,
+            )
+            content += "\n\n" + "\n".join(fe_lines).strip() + "\n"
+            files["frontend.mdc"] = content
+
+    # ── tests.mdc -- test files only ──────────────────────────────────────
+    test_globs: list[str] = []
+    if has_python:
+        test_globs.append("**/test_*.py")
+        test_globs.append("**/*_test.py")
+    if has_ts or has_js:
+        test_globs.append("**/*.test.ts")
+        test_globs.append("**/*.test.tsx")
+        test_globs.append("**/*.spec.ts")
+
+    test_deep = [r for r in deep_rules if r.get("category") == "testing"]
+    tp = dna.test_patterns
+
+    if test_globs and (test_deep or tp.framework):
+        test_lines: list[str] = ["## Testing Rules\n"]
+        if tp.framework:
+            test_lines.append(f"- Framework: `{tp.framework}`")
+        if tp.has_conftest:
+            test_lines.append("- Shared fixtures in `conftest.py` — use pytest fixtures, not setUp/tearDown")
+        for r in test_deep[:4]:
+            if "conftest" not in r["text"].lower() or not tp.has_conftest:
+                test_lines.append(f"- {r['text']}")
+        if tp.mock_library:
+            test_lines.append(f"- Mocking: `{tp.mock_library}`")
+
+        content = _frontmatter(
+            "Test file rules",
+            globs=test_globs,
+        )
+        content += "\n\n" + "\n".join(test_lines).strip() + "\n"
+        files["tests.mdc"] = content
+
+    return files
diff --git a/tests/test_cli.py b/tests/test_cli.py

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`"""Saar -- extract the essence of your codebase."""`
`2`	`2`
`3`		`-__version__ = "0.5.6"`
	`3`	`+__version__ = "0.5.7"`