Get method examples from test suites #20

New issue

Open

opened 2026-01-05 21:15:41 +00:00 by mprihoda · 0 comments

mprihoda commented

2026-01-05 21:15:41 +00:00

(Migrated from github.com)

Problem

Agent sees a method signature but doesn't know how to use it in practice:

"What do I pass to Ref.make?"
"How is flatMap typically chained?"
"What does realistic usage of this method look like?"

Proposed Solution

New Tool: `get_method_examples`

{
  "name": "get_method_examples",
  "description": "Find usage examples for a method",
  "input": {
    "coordinates": "Maven/Coursier coordinates",
    "className": "Fully qualified class name",
    "methodName": "Method to find examples for",
    "scalaVersion": "optional"
  }
}

Example:

get_method_examples("org.typelevel::cats-effect:3.5.4", "cats.effect.kernel.Ref", "make")

Returns:

## Examples: Ref.make

### From cats-effect test suite:

\`\`\`scala
// Basic usage
test("Ref.make creates a mutable reference") {
  for {
    ref   <- Ref.make[IO, Int](0)
    _     <- ref.set(42)
    value <- ref.get
  } yield assertEquals(value, 42)
}
\`\`\`

\`\`\`scala
// With concurrent access
test("Ref provides atomic updates") {
  for {
    ref <- Ref.make[IO, Int](0)
    _   <- (1 to 100).toList.parTraverse_(_ => ref.update(_ + 1))
    v   <- ref.get
  } yield assertEquals(v, 100)
}
\`\`\`

### Signature:
\`\`\`scala
def make[F[_]: Sync, A](a: A): F[Ref[F, A]]
\`\`\`

### Notes:
- Requires `Sync` constraint (cats-effect)
- Returns `F[Ref[...]]` - effect that creates the ref
- Initial value is provided, not a thunk

Implementation

Fetch sources JAR (already have this capability)
Find test directory - src/test/scala/**
Search for method usage - AST parsing or grep
Extract relevant snippets - with context

Technical Challenges

Test suites may be in separate artifact (-tests.jar)
Need to identify "good" examples (not internal test helpers)
May need to fetch from GitHub if tests not in sources JAR

Value for Agent

Sees real-world usage, not contrived examples
Understands typical arguments and patterns
Tests often show edge cases and error handling

Acceptance Criteria

Find method usages in test sources
Extract code snippets with surrounding context
Include method signature for reference
Handle case where no examples found gracefully

## Problem Agent sees a method signature but doesn't know how to use it in practice: - "What do I pass to `Ref.make`?" - "How is `flatMap` typically chained?" - "What does realistic usage of this method look like?" ## Proposed Solution ### New Tool: `get_method_examples` ```json { "name": "get_method_examples", "description": "Find usage examples for a method", "input": { "coordinates": "Maven/Coursier coordinates", "className": "Fully qualified class name", "methodName": "Method to find examples for", "scalaVersion": "optional" } } ``` **Example:** ``` get_method_examples("org.typelevel::cats-effect:3.5.4", "cats.effect.kernel.Ref", "make") ``` **Returns:** ```markdown ## Examples: Ref.make ### From cats-effect test suite: \`\`\`scala // Basic usage test("Ref.make creates a mutable reference") { for { ref <- Ref.make[IO, Int](0) _ <- ref.set(42) value <- ref.get } yield assertEquals(value, 42) } \`\`\` \`\`\`scala // With concurrent access test("Ref provides atomic updates") { for { ref <- Ref.make[IO, Int](0) _ <- (1 to 100).toList.parTraverse_(_ => ref.update(_ + 1)) v <- ref.get } yield assertEquals(v, 100) } \`\`\` ### Signature: \`\`\`scala def make[F[_]: Sync, A](a: A): F[Ref[F, A]] \`\`\` ### Notes: - Requires `Sync` constraint (cats-effect) - Returns `F[Ref[...]]` - effect that creates the ref - Initial value is provided, not a thunk ``` ## Implementation 1. **Fetch sources JAR** (already have this capability) 2. **Find test directory** - `src/test/scala/**` 3. **Search for method usage** - AST parsing or grep 4. **Extract relevant snippets** - with context ## Technical Challenges - Test suites may be in separate artifact (`-tests.jar`) - Need to identify "good" examples (not internal test helpers) - May need to fetch from GitHub if tests not in sources JAR ## Value for Agent - Sees real-world usage, not contrived examples - Understands typical arguments and patterns - Tests often show edge cases and error handling ## Acceptance Criteria - [ ] Find method usages in test sources - [ ] Extract code snippets with surrounding context - [ ] Include method signature for reference - [ ] Handle case where no examples found gracefully