Add comprehensive ruff configuration and fix code quality issues

- Add modern Python linting rules to pyproject.toml covering style, performance, and best practices
- Fix pre-commit config to use ruff-check instead of deprecated ruff alias
- Increase line length to 120 for better readability
- Fix nested if statements for better code clarity
- Break long system prompt into readable multi-line format
- Add missing docstrings to metrics methods
- Fix import sorting and organization
- Maintain API field camelCase compatibility with targeted ignores

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: mattgodbolt

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.11.10
     hooks:
-      - id: ruff
+      - id: ruff-check
         args: [ --fix ]
       - id: ruff-format
   - repo: https://github.com/jumanjihouse/pre-commit-hooks

CLAUDE.md

@@ -89,3 +89,7 @@ Uses AWS Embedded Metrics for CloudWatch integration when deployed, with a no-op
 ## Code Style Guidelines
 
 - Prefer using modern Python 3.9+ type syntax. Good: `a: list[str] | None`. Bad: `a: Optional[List[str]]`
+
+## Development Workflow Notes
+
+- The pre commit hooks may modify the code and so: always run them before `git add`, and if a commit hook fails then it's probably you'll need to `git add` again if it indicated if fixed issues (e.g. `ruff`)

app/config.py

@@ -2,6 +2,8 @@
 
 
 class Settings(BaseSettings):
+    """Application-level settings."""
+
     anthropic_api_key: str
     root_path: str = ""
     model_config = SettingsConfigDict(env_file=".env")

app/explain.py

@@ -2,9 +2,9 @@
 import logging
 
 from anthropic import Anthropic
-from app.explain_api import ExplainRequest, ExplainResponse, TokenUsage, CostBreakdown
-from app.metrics import MetricsProvider
 
+from app.explain_api import CostBreakdown, ExplainRequest, ExplainResponse, TokenUsage
+from app.metrics import MetricsProvider
 
 # Configure logging
 LOGGER = logging.getLogger("explain")
@@ -53,12 +53,13 @@ def select_important_assembly(
             continue
 
         # Source mapping makes this important
-        if asm_item.get("source") and asm_item["source"] is not None:
-            if (
-                isinstance(asm_item["source"], dict)
-                and asm_item["source"].get("line") is not None
-            ):
-                important_indices.add(idx)
+        if (
+            asm_item.get("source")
+            and asm_item["source"] is not None
+            and isinstance(asm_item["source"], dict)
+            and asm_item["source"].get("line") is not None
+        ):
+            important_indices.add(idx)
 
         # Function returns and epilogues are important
         text = asm_item.get("text", "").strip()
@@ -80,7 +81,7 @@ def select_important_assembly(
     # If we still have too many lines, prioritize
     if len(all_indices) > max_lines:
         # Prioritize function boundaries and source mappings over context
-        important_indices_list = sorted(list(important_indices))
+        important_indices_list = sorted(important_indices)
         all_indices = set(important_indices_list[:max_lines])
 
     # Collect selected assembly items
@@ -137,9 +138,7 @@ def prepare_structured_data(body: ExplainRequest) -> dict:
 
     if len(asm_dicts) > MAX_ASSEMBLY_LINES:
         # If assembly is too large, we need smart truncation
-        structured_data["assembly"] = select_important_assembly(
-            asm_dicts, body.labelDefinitions or {}
-        )
+        structured_data["assembly"] = select_important_assembly(asm_dicts, body.labelDefinitions or {})
         structured_data["truncated"] = True
         structured_data["originalLength"] = len(asm_dicts)
     else:
@@ -180,15 +179,20 @@ def process_request(
 
     structured_data = prepare_structured_data(body)
 
-    # TODO: consider not baking the language and arch here for system prompt caching later on. We'll need to hit minimum token lengths.
-    system_prompt = f"""You are an expert in {arch} assembly code and {language}, helping users of the Compiler Explorer website understand how their code compiles to assembly.
-The request will be in the form of a JSON document, which explains a source program and how it was compiled, and the resulting assembly code that was generated.
+    # TODO: consider not baking the language and arch here for system prompt caching later on.
+    #  We'll need to hit minimum token lengths.
+    system_prompt = f"""You are an expert in {arch} assembly code and {language}, helping users of the
+Compiler Explorer website understand how their code compiles to assembly.
+The request will be in the form of a JSON document, which explains a source program and how it was compiled,
+and the resulting assembly code that was generated.
 Provide clear, concise explanations. Focus on key transformations, optimizations, and important assembly patterns.
 Explanations should be educational and highlight why certain code constructs generate specific assembly instructions.
-Give no commentary on the original source: it is expected the user already understands their input, and is only looking for guidance on the assembly output.
+Give no commentary on the original source: it is expected the user already understands their input, and is only
+looking for guidance on the assembly output.
 If it makes it easiest to explain, note the corresponding parts of the source code, but do not focus on this.
 Do not give an overall conclusion.
-Be precise and accurate about CPU features and optimizations - avoid making incorrect claims about branch prediction or other hardware details."""
+Be precise and accurate about CPU features and optimizations - avoid making incorrect claims about branch
+prediction or other hardware details."""
 
     # Call Claude API with JSON structure
     LOGGER.info(f"Using Anthropic client with model: {MODEL}")

app/explain_api.py

@@ -1,5 +1,4 @@
-"""
-Pydantic models for the Claude Explain API.
+"""Pydantic models for the Claude Explain API.
 
 Defines request and response types based on the API specification
 in claude_explain.md.
@@ -42,20 +41,12 @@ class ExplainRequest(BaseModel):
     """Request body for the /explain endpoint."""
 
     language: str = Field(..., description="Programming language (e.g., 'c++', 'rust')")
-    compiler: str = Field(
-        ..., description="Compiler identifier (e.g., 'g112', 'clang1500')"
-    )
+    compiler: str = Field(..., description="Compiler identifier (e.g., 'g112', 'clang1500')")
     code: str = Field(..., description="Original source code")
-    compilationOptions: list[str] = Field(
-        default_factory=list, description="Array of compiler flags/options"
-    )
-    instructionSet: str | None = Field(
-        None, description="Target architecture (e.g., 'amd64', 'arm64')"
-    )
+    compilationOptions: list[str] = Field(default_factory=list, description="Array of compiler flags/options")
+    instructionSet: str | None = Field(None, description="Target architecture (e.g., 'amd64', 'arm64')")
     asm: list[AssemblyItem] = Field(..., description="Array of assembly objects")
-    labelDefinitions: dict[str, int] | None = Field(
-        None, description="Optional map of label names to line numbers"
-    )
+    labelDefinitions: dict[str, int] | None = Field(None, description="Optional map of label names to line numbers")
 
 
 class TokenUsage(BaseModel):
@@ -79,9 +70,7 @@ class ExplainResponse(BaseModel):
 
     explanation: str | None = Field(None, description="The generated explanation")
     status: str = Field(..., description="'success' or 'error'")
-    message: str | None = Field(
-        None, description="Error message (only present on error)"
-    )
+    message: str | None = Field(None, description="Error message (only present on error)")
     model: str | None = Field(None, description="The Claude model used")
     usage: TokenUsage | None = Field(None, description="Token usage information")
     cost: CostBreakdown | None = Field(None, description="Cost breakdown")
@@ -97,9 +86,7 @@ class ExplainErrorResponse(BaseModel):
 class ExplainSuccessResponse(BaseModel):
     """Success response from the /explain endpoint."""
 
-    status: str = Field(
-        "success", description="Always 'success' for successful responses"
-    )
+    status: str = Field("success", description="Always 'success' for successful responses")
     explanation: str = Field(..., description="The generated explanation")
     model: str = Field(..., description="The Claude model used")
     usage: TokenUsage = Field(..., description="Token usage information")

app/explain_test.py

@@ -1,18 +1,19 @@
 import json
 from unittest.mock import MagicMock
+
 import pytest
 
 from app.explain import (
-    process_request,
-    select_important_assembly,
-    prepare_structured_data,
     MAX_ASSEMBLY_LINES,
-    MODEL,
     MAX_TOKENS,
+    MODEL,
+    prepare_structured_data,
+    process_request,
+    select_important_assembly,
 )
 from app.explain_api import (
-    ExplainRequest,
     AssemblyItem,
+    ExplainRequest,
     SourceMapping,
 )
 from app.metrics import NoopMetricsProvider
@@ -82,18 +83,13 @@ def noop_metrics():
 class TestProcessRequest:
     """Test the main process_request function."""
 
-    def test_process_request_success(
-        self, sample_request, mock_anthropic_client, noop_metrics
-    ):
+    def test_process_request_success(self, sample_request, mock_anthropic_client, noop_metrics):
         """Test successful processing of a request."""
         response = process_request(sample_request, mock_anthropic_client, noop_metrics)
 
         # Verify response structure
         assert response.status == "success"
-        assert (
-            response.explanation
-            == "This assembly code implements a simple square function..."
-        )
+        assert response.explanation == "This assembly code implements a simple square function..."
         assert response.model == MODEL
 
         # Check usage information
@@ -145,9 +141,7 @@ def test_process_request_success(
         structured_data = json.loads(messages[0]["content"][1]["text"])
         assert structured_data["language"] == "c++"
         assert structured_data["compiler"] == "g++"
-        assert (
-            structured_data["sourceCode"] == "int square(int x) {\n  return x * x;\n}"
-        )
+        assert structured_data["sourceCode"] == "int square(int x) {\n  return x * x;\n}"
 
 
 class TestSelectImportantAssembly:
@@ -206,13 +200,14 @@ def test_select_important_assembly_over_limit(self):
         # Check that important lines (with sources) are included
         has_source_lines = False
         for line in result:
-            if "isOmissionMarker" not in line and line.get("source") is not None:
-                if (
-                    isinstance(line["source"], dict)
-                    and line["source"].get("line") is not None
-                ):
-                    has_source_lines = True
-                    break
+            if (
+                "isOmissionMarker" not in line
+                and line.get("source") is not None
+                and isinstance(line["source"], dict)
+                and line["source"].get("line") is not None
+            ):
+                has_source_lines = True
+                break
         assert has_source_lines
 
     def test_select_important_assembly_preserves_function_boundaries(self):

app/main.py

@@ -1,14 +1,16 @@
 import logging
 
-from anthropic import Anthropic, __version__ as AnthropicVersion
+import aws_embedded_metrics
+from anthropic import Anthropic
+from anthropic import __version__ as anthropic_version
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from mangum import Mangum
+
 from app.config import settings
 from app.explain import process_request
 from app.explain_api import ExplainRequest, ExplainResponse
 from app.metrics import NoopMetricsProvider
-from fastapi import FastAPI
-from fastapi.middleware.cors import CORSMiddleware
-from mangum import Mangum
-import aws_embedded_metrics
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger()
@@ -28,7 +30,7 @@
 handler = Mangum(app)
 
 anthropic_client = Anthropic(api_key=settings.anthropic_api_key)
-logger.info(f"Anthropic SDK version: {AnthropicVersion}")
+logger.info(f"Anthropic SDK version: {anthropic_version}")
 
 metrics_provider = NoopMetricsProvider()
 #    if metrics:
@@ -39,10 +41,12 @@
 
 @app.get("/")
 async def root() -> str:
+    """Temporary placeholder for a better API."""
     return "Hello, world!"
 
 
 @aws_embedded_metrics.metric_scope
 @app.post("/")
 async def explain(request: ExplainRequest) -> ExplainResponse:
+    """Explain a Compiler Explorer compilation from its source and output assembly."""
     return process_request(request, anthropic_client, metrics_provider)

app/metrics.py

@@ -9,12 +9,10 @@ class MetricsProvider(ABC):
     @abstractmethod
     def put_metric(self, name: str, value: int | float) -> None:
         """Record a metric with the given name and value."""
-        pass
 
     @abstractmethod
     def set_property(self, name: str, value: str) -> None:
         """Set a property/dimension for metrics."""
-        pass
 
 
 class CloudWatchMetricsProvider(MetricsProvider):
@@ -24,17 +22,19 @@ def __init__(self, metrics_logger: MetricsLogger):
         self.metrics = metrics_logger
 
     def put_metric(self, name: str, value: int | float) -> None:
+        """Record a metric with the given name and value in CloudWatch."""
         self.metrics.put_metric(name, value)
 
     def set_property(self, name: str, value: str) -> None:
+        """Set a property/dimension for metrics."""
         self.metrics.set_property(name, value)
 
 
 class NoopMetricsProvider(MetricsProvider):
     """Metrics provider that does nothing - for testing."""
 
     def put_metric(self, name: str, value: int | float) -> None:
-        pass
+        """Does nothing."""
 
     def set_property(self, name: str, value: str) -> None:
-        pass
+        """Does nothing."""

pyproject.toml

@@ -20,3 +20,63 @@ dev = [
     "pre-commit>=4.2.0",
     "pytest>=8.3.5",
 ]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    # Pyflakes
+    "F",
+    # pycodestyle
+    "E",
+    "W",
+    # isort
+    "I",
+    # pep8-naming
+    "N",
+    # pydocstyle
+    "D",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # flake8-comprehensions
+    "C4",
+    # flake8-pie
+    "PIE",
+    # flake8-return
+    "RET",
+    # flake8-unused-arguments
+    "ARG",
+    # flake8-use-pathlib
+    "PTH",
+    # Ruff-specific rules
+    "RUF",
+]
+
+ignore = [
+    # Allow non-lowercase variable names (e.g., for API field names)
+    "N806",
+    # Allow missing docstrings for some cases
+    "D100", # Missing docstring in public module
+    "D104", # Missing docstring in public package
+    "D107", # Missing docstring in __init__
+    # Allow imperative mood in docstrings (e.g., "Create a new user")
+    "D401",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"test*.py" = [
+    "D", # Don't require docstrings in tests
+    "ARG", # Allow unused arguments in tests (fixtures)
+]
+"app/explain_api.py" = [
+    "N815", # Allow camelCase field names for API compatibility
+]