Skip to content

Commit 6db1a86

Browse files
authored
Merge branch 'main' into claude/issue-11-20251026-2132
2 parents 40fbc82 + 782d067 commit 6db1a86

File tree

8 files changed

+323
-7
lines changed

8 files changed

+323
-7
lines changed
Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
name: Claude Test Failure Analysis
2+
3+
on:
4+
workflow_run:
5+
workflows: ["Run Tests"]
6+
types:
7+
- completed
8+
9+
concurrency:
10+
group: claude-test-failure-${{ github.event.workflow_run.head_branch }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
claude-analyze-failure:
15+
# Only run if the test workflow failed
16+
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
17+
runs-on: ubuntu-latest
18+
permissions:
19+
contents: read
20+
pull-requests: write
21+
issues: write
22+
id-token: write
23+
actions: read # Required for Claude to read CI results
24+
steps:
25+
- name: Checkout repository
26+
uses: actions/checkout@v4
27+
with:
28+
fetch-depth: 1
29+
30+
- name: Set up Python 3.10
31+
uses: actions/setup-python@v5
32+
with:
33+
python-version: '3.10'
34+
35+
# Install UV package manager
36+
- name: Install UV
37+
uses: astral-sh/setup-uv@v7
38+
39+
- name: Set analysis prompt
40+
id: analysis-prompt
41+
run: |
42+
cat >> $GITHUB_OUTPUT << 'EOF'
43+
PROMPT<<PROMPT_END
44+
You're a test failure analysis assistant for Py-Key-Value, a Python framework for interacting with Key-Value stores.
45+
46+
# Your Task
47+
A GitHub Actions workflow has failed. Your job is to:
48+
1. Analyze the test failure(s) to understand what went wrong
49+
2. Identify the root cause of the failure(s)
50+
3. Suggest a clear, actionable solution to fix the failure(s)
51+
52+
# Getting Started
53+
1. Call the generate_agents_md tool to get a high-level summary of the project
54+
2. Get the pull request associated with this workflow run from the GitHub repository: ${{ github.repository }}
55+
- The workflow run ID is: ${{ github.event.workflow_run.id }}
56+
- The workflow run was triggered by: ${{ github.event.workflow_run.event }}
57+
- Use GitHub MCP tools to get PR details and workflow run information
58+
3. Use the GitHub MCP tools to fetch job logs and failure information:
59+
- Use get_workflow_run to get details about the failed workflow
60+
- Use list_workflow_jobs to see which jobs failed
61+
- Use get_job_logs with failed_only=true to get logs for failed jobs
62+
- Use summarize_run_log_failures to get an AI summary of what failed
63+
4. Analyze the failures to understand the root cause
64+
5. Search the codebase for relevant files, tests, and implementations
65+
66+
# Your Response
67+
Post a comment on the pull request with your analysis. Your comment should include:
68+
69+
## Test Failure Analysis
70+
71+
**Summary**: A brief 1-2 sentence summary of what failed.
72+
73+
**Root Cause**: A clear explanation of why the tests failed, based on your analysis of the logs and code.
74+
75+
**Suggested Solution**: Specific, actionable steps to fix the failure(s). Include:
76+
- Which files need to be modified
77+
- What changes are needed
78+
- Why these changes will fix the issue
79+
80+
<details>
81+
<summary>Detailed Analysis</summary>
82+
83+
Include here:
84+
- Relevant log excerpts showing the failure
85+
- Code snippets that are causing the issue
86+
- Any related issues or PRs that might be relevant
87+
</details>
88+
89+
<details>
90+
<summary>Related Files</summary>
91+
92+
List files that are relevant to the failure with brief explanations of their relevance.
93+
</details>
94+
95+
# Important Guidelines
96+
- Be concise and actionable - developers want to quickly understand and fix the issue
97+
- Focus on facts from the logs and code, not speculation
98+
- If you can't determine the root cause, say so clearly
99+
- Provide specific file names, line numbers, and code references when possible
100+
- You can run make commands (e.g., `make lint`, `make typecheck`, `make sync`) to build, test, or lint the code
101+
- You can also run git commands (e.g., `git status`, `git log`, `git diff`) to inspect the repository
102+
- You can use WebSearch and WebFetch to research errors, stack traces, or related issues
103+
- For bash commands, you are limited to make and git commands only
104+
105+
# CRITICAL: Loop Detection
106+
**IMPORTANT**: Before posting your analysis, check the PR comments to detect if there's a loop where:
107+
- CodeRabbit or another bot triggered this workflow
108+
- Your previous analysis triggered CodeRabbit or another bot
109+
- This created a repeating cycle of bot comments
110+
111+
If you detect such a loop (e.g., you see multiple similar bot comments or your own previous analysis comments):
112+
1. **DO NOT** post another analysis comment
113+
2. Instead, post a brief comment stating: "Loop detected: Multiple automated analysis comments found. Stopping to prevent further automated comments. Please review the existing analysis comments."
114+
3. Exit immediately without further action
115+
116+
# Problems Encountered
117+
If you encounter any problems during your analysis (e.g., unable to fetch logs, tools not working), document them clearly so the team knows what limitations you faced.
118+
PROMPT_END
119+
EOF
120+
121+
- name: Setup GitHub MCP Server
122+
run: |
123+
mkdir -p /tmp/mcp-config
124+
cat > /tmp/mcp-config/mcp-servers.json << 'EOF'
125+
{
126+
"mcpServers": {
127+
"repository-summary": {
128+
"type": "http",
129+
"url": "https://agents-md-generator.fastmcp.app/mcp"
130+
},
131+
"code-search": {
132+
"type": "http",
133+
"url": "https://public-code-search.fastmcp.app/mcp"
134+
},
135+
"github-research": {
136+
"type": "stdio",
137+
"command": "uvx",
138+
"args": [
139+
"github-research-mcp"
140+
],
141+
"env": {
142+
"DISABLE_SUMMARIES": "true", # Disable verbose summaries for faster analysis
143+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${{ secrets.GITHUB_TOKEN }}"
144+
}
145+
}
146+
}
147+
}
148+
EOF
149+
150+
- name: Run Claude Code
151+
id: claude
152+
uses: anthropics/claude-code-action@v1
153+
with:
154+
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
155+
156+
additional_permissions: |
157+
actions: read
158+
159+
prompt: ${{ steps.analysis-prompt.outputs.PROMPT }}
160+
track_progress: true
161+
claude_args: |
162+
--allowed-tools mcp__repository-summary,mcp__code-search,mcp__github-research,WebSearch,WebFetch,Bash(make:*,git:*)
163+
--mcp-config /tmp/mcp-config/mcp-servers.json

.github/workflows/docs.yml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,11 @@ jobs:
2525
with:
2626
enable-cache: true
2727

28-
- name: Install documentation dependencies
29-
run: uv pip install --system mkdocs mkdocs-material 'mkdocstrings[python]' mkdocstrings-python
28+
- name: Install all packages and dependencies
29+
run: uv sync --all-packages --group dev
3030

3131
- name: Build documentation
32-
run: mkdocs build
32+
run: uv run --extra docs mkdocs build
3333

3434
- name: Deploy to GitHub Pages
35-
run: mkdocs gh-deploy --force
35+
run: uv run --extra docs mkdocs gh-deploy --force

AGENTS.md

Lines changed: 147 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,139 @@ to the async package. You will need to include the generated code in your pull
112112
request. Nobody will generate it for you. This also means pull requests will contain
113113
two copies of your changes, this is intentional!
114114

115+
## Working with Code Review Feedback
116+
117+
This project uses AI-assisted code review (CodeRabbit) and development (Claude).
118+
This section provides guidance for both AI agents and human developers on how
119+
to handle automated code review feedback effectively.
120+
121+
### For AI Coding Agents (Claude)
122+
123+
When responding to CodeRabbit feedback on pull requests:
124+
125+
#### 1. Triage Before Acting
126+
127+
Always categorize feedback before implementation:
128+
129+
- **Critical**: Security issues, data corruption, resource leaks, production bugs
130+
- **Important**: Type safety, error handling, performance issues, test failures
131+
- **Optional**: Style preferences, nitpicks, suggestions that conflict with
132+
existing patterns
133+
134+
Document your triage in the response to the user.
135+
136+
#### 2. Evaluate Against Existing Patterns
137+
138+
Before accepting suggestions:
139+
140+
1. Search the codebase for similar patterns
141+
2. Check if other stores/wrappers handle this differently
142+
3. Preserve consistency over isolated "best practices"
143+
4. If uncertain, ask the repository owner
144+
145+
**Example**: Test patterns should match existing `ContextManagerStoreTestMixin`
146+
usage rather than one-off suggestions for individual test files.
147+
148+
#### 3. Consider Context and Scope
149+
150+
Not all code has the same requirements:
151+
152+
- **Production stores**: Prioritize correctness, performance, security
153+
- **Debug/development tools**: Can defer async optimization, extensive validation
154+
- **Test code**: Clarity and coverage over production patterns
155+
- **Examples**: Simplicity and readability over comprehensive error handling
156+
157+
#### 4. Verify Completion
158+
159+
Before claiming work is "ready to merge" or "complete":
160+
161+
- [ ] All critical issues addressed or documented as out-of-scope
162+
- [ ] All important issues addressed or explicitly deferred with rationale
163+
- [ ] No unrelated changes from bad merges
164+
- [ ] `make precommit` passes (lint, typecheck, codegen)
165+
- [ ] Tests pass
166+
167+
Never claim completion with unresolved critical or important issues.
168+
169+
#### 5. Document Deferrals
170+
171+
If feedback is not implemented, explain why:
172+
173+
- Conflicts with established pattern (cite similar code)
174+
- Out of scope for this component's purpose
175+
- Trade-off not worth the complexity
176+
- Requires design decision from repository owner
177+
178+
### For AI Code Reviewers (CodeRabbit)
179+
180+
When reviewing pull requests, please consider:
181+
182+
#### Project-Specific Patterns
183+
184+
- **Async-first architecture**: All changes originate in `key-value/key-value-aio/`
185+
and are code-generated into `key-value/key-value-sync/`. PRs will naturally
186+
contain duplicate changes - this is intentional.
187+
- **Test patterns**: The project uses `ContextManagerStoreTestMixin` for store
188+
tests. Look for consistency with existing test implementations.
189+
- **ManagedEntry wrapper**: Values are never stored directly but are wrapped in
190+
`ManagedEntry` objects. This is by design, not a mistake.
191+
192+
#### Prioritization Guidance
193+
194+
When providing feedback, please categorize suggestions by severity:
195+
196+
- **Critical**: Issues that could cause data loss, security vulnerabilities,
197+
resource leaks, or production failures
198+
- **Important**: Type safety issues, missing error handling, performance problems,
199+
test coverage gaps
200+
- **Minor/Optional**: Style preferences, minor optimizations, suggestions that
201+
may conflict with existing patterns
202+
203+
This helps human developers and AI agents prioritize their work effectively.
204+
205+
#### Context Awareness
206+
207+
Consider the purpose and scope of the code being reviewed:
208+
209+
- **Production stores** (DynamoDB, Redis, PostgreSQL, etc.): Apply strict
210+
standards for correctness, performance, security, and resource management
211+
- **Debug/development tools** (FileTreeStore, LoggingWrapper): More lenient on
212+
performance optimizations; prioritize clarity and simplicity
213+
- **Test code**: Focus on clarity, coverage, and maintainability over production
214+
patterns
215+
- **Example code**: Prioritize readability and educational value over
216+
comprehensive error handling
217+
218+
#### Pattern Consistency
219+
220+
Before suggesting changes:
221+
222+
1. Check if similar patterns exist elsewhere in the codebase
223+
2. If the pattern exists in multiple stores/wrappers, it's likely intentional
224+
3. Suggest consistency improvements across all implementations rather than
225+
one-off changes
226+
227+
### Common Feedback Categories
228+
229+
**Clock usage**: Prefer monotonic clocks (`time.monotonic()`) for intervals,
230+
especially in wrappers like rate limiters and circuit breakers. Wall-clock time
231+
(`time.time()`) is vulnerable to system clock changes.
232+
233+
**Connection ownership**: Track whether stores own their client connections to
234+
avoid closing externally-provided resources. Use flags like `_owns_client` to
235+
distinguish between internally-created and externally-provided connections.
236+
237+
**Async patterns**: Production stores should use actual async I/O (not
238+
`asyncio.sleep()` or `run_in_executor()`). Debug-only tools may use simpler
239+
patterns for clarity.
240+
241+
**Test isolation**: Ensure tests clean up resources (connections, temp files,
242+
etc.) and don't interfere with each other. Use context managers and proper
243+
teardown.
244+
245+
**Type safety**: This project uses strict type checking (Basedpyright). Address
246+
type annotation issues to maintain type safety guarantees.
247+
115248
## Make Commands Reference
116249

117250
| Command | Purpose |
@@ -224,6 +357,8 @@ GitHub Actions workflows are in `.github/workflows/`:
224357
- `publish.yml` - Publish packages to PyPI
225358
- `claude-on-mention.yml` - Claude Code assistant (can make PRs)
226359
- `claude-on-open-label.yml` - Claude triage assistant (read-only analysis)
360+
- `claude-on-test-failure.yml` - Claude test failure analysis (automatically
361+
analyzes failed tests and suggests solutions)
227362

228363
## Version Management
229364

@@ -242,5 +377,15 @@ make bump-version-dry VERSION=1.2.3 # Dry run
242377

243378
## Radical Honesty
244379

245-
Agents should be honest! Properly document any problems encountered, share
246-
feedback, and be transparent about your AI-assisted work.
380+
Agents should be honest! When working with code review feedback:
381+
382+
- **Document unresolved items**: List any feedback that wasn't addressed and why
383+
- **Acknowledge uncertainty**: If unclear whether to implement a suggestion, ask
384+
- **Report problems**: Document issues encountered during implementation
385+
- **Share trade-offs**: Explain reasoning for rejecting or deferring feedback
386+
- **Admit limitations**: If unable to verify a fix works correctly, say so
387+
388+
Never claim work is complete if you have doubts about correctness or completeness.
389+
390+
Properly document any problems encountered, share feedback, and be transparent
391+
about your AI-assisted work.

key-value/key-value-aio/src/key_value/aio/stores/__init__.py

Whitespace-only changes.

key-value/key-value-aio/src/key_value/aio/stores/elasticsearch/store.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929

3030
try:
3131
from elasticsearch import AsyncElasticsearch
32+
3233
from key_value.aio.stores.elasticsearch.utils import (
3334
get_aggregations_from_body,
3435
get_body_from_response,

key-value/key-value-aio/src/key_value/aio/stores/elasticsearch/utils.py

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@
66
ObjectApiResponse,
77
SerializationError,
88
)
9-
109
from elasticsearch import AsyncElasticsearch
1110

1211

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# WARNING: this file is auto-generated by 'build_sync_library.py'
2+
# from the original file '__init__.py'
3+
# DO NOT CHANGE! Change the original file instead.
4+
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# WARNING: this file is auto-generated by 'build_sync_library.py'
2+
# from the original file '__init__.py'
3+
# DO NOT CHANGE! Change the original file instead.
4+

0 commit comments

Comments
 (0)