fix: correct arun() return type annotation (#1898)

[hafezparast]

Summary

arun() was annotated as returning RunManyReturn (which is Union[CrawlResultContainer, AsyncGenerator]), but it always returns CrawlResultContainer. This caused Pylance/Pyright to flag result.markdown as an error because AsyncGenerator doesn't have that attribute.

Fixes #1898

The Bug

result = await crawler.arun(url="https://example.com")
result.markdown  # IDE shows error: "markdown" doesn't exist on AsyncGenerator

Code works fine at runtime — Python ignores type hints. But the IDE red squiggly confuses users.

The Fix

# Before
async def arun(self, url, config=None, **kwargs) -> RunManyReturn:  # includes AsyncGenerator

# After
async def arun(self, url, config=None, **kwargs) -> CrawlResultContainer:  # what it actually returns

arun_many() keeps RunManyReturn — it does return AsyncGenerator when stream=True.

Regression guard

Adds tests/test_type_annotations.py — 11 tests that catch annotation mismatches using static introspection (no pyright/mypy needed in CI):

• Return type includes types the method never returns
• Missing return annotations on public methods
• Missing parameter annotations
• Return annotation doesn't include the actual return type
• Config init params match stored attributes
• Public types are importable

A pyright scan found 46 return type mismatches across the codebase. This PR fixes the user-facing one (#1898) and adds the test guard to prevent future regressions.

Test plan

• 11 annotation tests passing
• Existing pipeline tests pass (16/16)
• All CrawlResultContainer usage patterns verified (attribute access, iteration, indexing)

🤖 Generated with Claude Code