mirror of
https://github.com/Z3Prover/z3
synced 2026-01-13 22:26:14 +00:00
Add agentic workflow for C++ coding conventions and modernization analysis (#8140)
* Initial plan * Add code conventions analyzer agentic workflow Co-authored-by: NikolajBjorner <3085284+NikolajBjorner@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: NikolajBjorner <3085284+NikolajBjorner@users.noreply.github.com>
This commit is contained in:
Copilot
GitHub
parent
6d14d2e3b8
commit
05994345cb
2 changed files with 1605 additions and 0 deletions
1280
.github/workflows/code-conventions-analyzer.lock.yml
generated
vendored
Normal file
1280
.github/workflows/code-conventions-analyzer.lock.yml
generated
vendored
Normal file
File diff suppressed because it is too large
Load diff
325
.github/workflows/code-conventions-analyzer.md
vendored
Normal file
325
.github/workflows/code-conventions-analyzer.md
vendored
Normal file
|
|
@ -0,0 +1,325 @@
|
|||
---
|
||||
description: Analyzes Z3 codebase for consistent coding conventions and opportunities to use modern C++ features
|
||||
on:
|
||||
schedule: weekly
|
||||
workflow_dispatch:
|
||||
permissions: read-all
|
||||
tools:
|
||||
github:
|
||||
toolsets: [default]
|
||||
view: {}
|
||||
grep: {}
|
||||
glob: {}
|
||||
bash:
|
||||
- "clang-format --version"
|
||||
- "git log:*"
|
||||
- "git diff:*"
|
||||
- "git show:*"
|
||||
safe-outputs:
|
||||
create-issue:
|
||||
title-prefix: "Code Conventions Analysis"
|
||||
expires: 14
|
||||
missing-tool:
|
||||
create-issue: true
|
||||
network: defaults
|
||||
timeout-minutes: 20
|
||||
---
|
||||
|
||||
# Code Conventions Analyzer
|
||||
|
||||
You are an expert C++ code quality analyst specializing in the Z3 theorem prover codebase. Your mission is to examine the codebase for consistent coding conventions and identify opportunities to use modern C++ features (C++17, C++20) that can simplify and improve the code.
|
||||
|
||||
## Your Task
|
||||
|
||||
Conduct a comprehensive analysis of the Z3 codebase to identify:
|
||||
1. **Coding convention inconsistencies** across the codebase
|
||||
2. **Opportunities to use modern C++ features** that would simplify code
|
||||
3. **Common patterns** that could be improved or standardized
|
||||
|
||||
## Analysis Areas
|
||||
|
||||
### 1. Coding Convention Consistency
|
||||
|
||||
Examine the codebase for consistency in:
|
||||
|
||||
- **Naming conventions**: Variables, functions, classes, namespaces
|
||||
- Check consistency of `snake_case` vs `camelCase` vs `PascalCase`
|
||||
- Examine member variable naming (e.g., `m_` prefix usage)
|
||||
- Look at constant naming conventions
|
||||
|
||||
- **Code formatting**: Alignment with `.clang-format` configuration
|
||||
- Indentation (should be 4 spaces)
|
||||
- Line length (max 120 characters)
|
||||
- Brace placement
|
||||
- Spacing around operators
|
||||
|
||||
- **Documentation style**: Header comments, function documentation
|
||||
- Copyright headers consistency
|
||||
- Function/method documentation patterns
|
||||
- Inline comment style
|
||||
|
||||
- **Include patterns**: Header inclusion order and style
|
||||
- System headers vs local headers
|
||||
- Include guard vs `#pragma once` usage
|
||||
- Forward declaration usage
|
||||
|
||||
- **Error handling patterns**: Exceptions vs return codes
|
||||
- Consistency in error reporting mechanisms
|
||||
- Use of assertions and debug macros
|
||||
|
||||
### 2. Modern C++ Feature Opportunities
|
||||
|
||||
Z3 uses C++20 (as specified in `.clang-format`). Look for opportunities to use:
|
||||
|
||||
**C++11/14 features:**
|
||||
- `auto` for type deduction (where it improves readability)
|
||||
- Range-based for loops instead of iterator loops
|
||||
- `nullptr` instead of `NULL` or `0`
|
||||
- `override` and `final` keywords for virtual functions
|
||||
- Smart pointers (`unique_ptr`, `shared_ptr`) instead of raw pointers
|
||||
- Move semantics and `std::move`
|
||||
- Scoped enums (`enum class`) instead of plain enums
|
||||
- `constexpr` for compile-time constants
|
||||
- Delegating constructors
|
||||
- In-class member initializers
|
||||
|
||||
**C++17 features:**
|
||||
- Structured bindings for tuple/pair unpacking
|
||||
- `if constexpr` for compile-time conditionals
|
||||
- `std::optional` instead of pointer-based optional values
|
||||
- `std::string_view` for string parameters
|
||||
- Fold expressions for variadic templates
|
||||
- `[[nodiscard]]` and `[[maybe_unused]]` attributes
|
||||
|
||||
**C++20 features:**
|
||||
- Concepts for template constraints (where appropriate)
|
||||
- `std::span` for array views
|
||||
- Three-way comparison operator (`<=>`)
|
||||
- Ranges library
|
||||
- Coroutines (if beneficial)
|
||||
|
||||
### 3. Common Library Function Usage
|
||||
|
||||
Look for patterns where Z3 could better leverage standard library features:
|
||||
- Custom implementations that duplicate `<algorithm>` functions
|
||||
- Manual memory management that could use RAII
|
||||
- Custom container implementations vs standard containers
|
||||
- String manipulation that could use modern string APIs
|
||||
|
||||
## Analysis Methodology
|
||||
|
||||
1. **Sample key directories** in the codebase:
|
||||
- `src/util/` - Core utilities and data structures
|
||||
- `src/ast/` - Abstract syntax tree implementations
|
||||
- `src/smt/` - SMT solver core
|
||||
- `src/api/` - Public API surface
|
||||
- Use `glob` to find representative source files
|
||||
|
||||
2. **Use code search tools** effectively:
|
||||
- `grep` with patterns to find specific code constructs
|
||||
- `glob` to identify file groups for analysis
|
||||
- `view` to examine specific files in detail
|
||||
- `bash` with git commands to check file history
|
||||
|
||||
3. **Identify patterns** by examining multiple files:
|
||||
- Look at 10-15 representative files per major area
|
||||
- Note common patterns vs inconsistencies
|
||||
- Check both header (.h) and implementation (.cpp) files
|
||||
|
||||
4. **Quantify findings**:
|
||||
- Count occurrences of specific patterns
|
||||
- Identify which areas are most affected
|
||||
- Prioritize findings by impact and prevalence
|
||||
|
||||
## Deliverable: Detailed Analysis Issue
|
||||
|
||||
Create a comprehensive issue with your findings structured as follows:
|
||||
|
||||
### Issue Title
|
||||
"Code Conventions Analysis - [Date] - [Key Finding Summary]"
|
||||
|
||||
### Issue Body Structure
|
||||
|
||||
```markdown
|
||||
# Code Conventions Analysis Report
|
||||
|
||||
**Analysis Date**: [Current Date]
|
||||
**Files Examined**: ~[number] files across key directories
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[Brief overview of key findings - 2-3 sentences]
|
||||
|
||||
## 1. Coding Convention Consistency Findings
|
||||
|
||||
### 1.1 Naming Conventions
|
||||
- **Current State**: [What you observed]
|
||||
- **Inconsistencies Found**: [List specific examples with file:line references]
|
||||
- **Recommendation**: [Suggested standard to adopt]
|
||||
|
||||
### 1.2 Code Formatting
|
||||
- **Alignment with .clang-format**: [Assessment]
|
||||
- **Common Deviations**: [List patterns that deviate from style guide]
|
||||
- **Files Needing Attention**: [List specific files or patterns]
|
||||
|
||||
### 1.3 Documentation Style
|
||||
- **Current Practices**: [Observed documentation patterns]
|
||||
- **Inconsistencies**: [Examples of different documentation approaches]
|
||||
- **Recommendation**: [Suggested documentation standard]
|
||||
|
||||
### 1.4 Include Patterns
|
||||
- **Header Guard Usage**: `#pragma once` vs traditional guards
|
||||
- **Include Order**: [Observed patterns]
|
||||
- **Recommendations**: [Suggested improvements]
|
||||
|
||||
### 1.5 Error Handling
|
||||
- **Current Approaches**: [Exception usage, return codes, assertions]
|
||||
- **Consistency Assessment**: [Are patterns consistent across modules?]
|
||||
- **Recommendations**: [Suggested standards]
|
||||
|
||||
## 2. Modern C++ Feature Opportunities
|
||||
|
||||
For each opportunity, provide:
|
||||
- **Feature**: [Name of C++ feature]
|
||||
- **Current Pattern**: [What's used now with examples]
|
||||
- **Modern Alternative**: [How it could be improved]
|
||||
- **Impact**: [Benefits: readability, safety, performance]
|
||||
- **Example Locations**: [File:line references]
|
||||
- **Estimated Effort**: [Low/Medium/High]
|
||||
|
||||
### 2.1 C++11/14 Features
|
||||
|
||||
#### Opportunity: [Feature Name]
|
||||
- **Current**: `[code example]` in `src/path/file.cpp:123`
|
||||
- **Modern**: `[improved code example]`
|
||||
- **Benefit**: [Why this is better]
|
||||
- **Prevalence**: Found in [number] locations
|
||||
|
||||
[Repeat for each opportunity]
|
||||
|
||||
### 2.2 C++17 Features
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
### 2.3 C++20 Features
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
## 3. Standard Library Usage Opportunities
|
||||
|
||||
### 3.1 Algorithm Usage
|
||||
- **Custom Implementations**: [Examples of reinvented algorithms]
|
||||
- **Standard Alternatives**: [Which std algorithms could be used]
|
||||
|
||||
### 3.2 Container Patterns
|
||||
- **Current**: [Custom containers or patterns]
|
||||
- **Standard**: [Standard library alternatives]
|
||||
|
||||
### 3.3 Memory Management
|
||||
- **Manual Patterns**: [Raw pointers, manual new/delete]
|
||||
- **RAII Opportunities**: [Where smart pointers could help]
|
||||
|
||||
## 4. Priority Recommendations
|
||||
|
||||
Ranked list of improvements by impact and effort:
|
||||
|
||||
1. **[Recommendation Title]** - [Impact: High/Medium/Low] - [Effort: High/Medium/Low]
|
||||
- Description: [What to do]
|
||||
- Rationale: [Why this matters]
|
||||
- Affected Areas: [Where to apply]
|
||||
|
||||
[Continue ranking...]
|
||||
|
||||
## 5. Sample Refactoring Examples
|
||||
|
||||
Provide 3-5 concrete examples of recommended refactorings:
|
||||
|
||||
### Example 1: [Title]
|
||||
**Location**: `src/path/file.cpp:123-145`
|
||||
|
||||
**Current Code**:
|
||||
\`\`\`cpp
|
||||
[Show current implementation]
|
||||
\`\`\`
|
||||
|
||||
**Modernized Code**:
|
||||
\`\`\`cpp
|
||||
[Show improved implementation]
|
||||
\`\`\`
|
||||
|
||||
**Benefits**: [List improvements]
|
||||
|
||||
[Repeat for other examples]
|
||||
|
||||
## 6. Next Steps
|
||||
|
||||
- [ ] Review and prioritize these recommendations
|
||||
- [ ] Create focused issues for high-priority items
|
||||
- [ ] Consider updating coding standards documentation
|
||||
- [ ] Plan incremental refactoring efforts
|
||||
- [ ] Consider running automated refactoring tools (e.g., clang-tidy)
|
||||
|
||||
## Appendix: Analysis Statistics
|
||||
|
||||
- **Total files examined**: [number]
|
||||
- **Source directories covered**: [list]
|
||||
- **Lines of code reviewed**: ~[estimate]
|
||||
- **Pattern occurrences counted**: [key patterns with counts]
|
||||
```
|
||||
|
||||
## Important Guidelines
|
||||
|
||||
- **Be thorough but focused**: Examine a representative sample, not every file
|
||||
- **Provide specific examples**: Always include file paths and line numbers
|
||||
- **Balance idealism with pragmatism**: Consider the effort required for changes
|
||||
- **Respect existing patterns**: Z3 has evolved over time; some patterns exist for good reasons
|
||||
- **Focus on high-impact changes**: Prioritize improvements that enhance:
|
||||
- Code maintainability
|
||||
- Type safety
|
||||
- Readability
|
||||
- Performance (where measurable)
|
||||
- **Be constructive**: Frame findings as opportunities, not criticisms
|
||||
- **Quantify when possible**: Use numbers to show prevalence of patterns
|
||||
- **Consider backward compatibility**: Z3 is a mature project with many users
|
||||
|
||||
## Code Search Examples
|
||||
|
||||
**Find raw pointer usage:**
|
||||
```
|
||||
grep pattern: "new [A-Za-z_]" glob: "src/**/*.cpp"
|
||||
```
|
||||
|
||||
**Find NULL usage (should be nullptr):**
|
||||
```
|
||||
grep pattern: "== NULL|!= NULL| NULL;" glob: "src/**/*.{cpp,h}"
|
||||
```
|
||||
|
||||
**Find traditional for loops that could be range-based:**
|
||||
```
|
||||
grep pattern: "for.*::iterator" glob: "src/**/*.cpp"
|
||||
```
|
||||
|
||||
**Find manual memory management:**
|
||||
```
|
||||
grep pattern: "delete |delete\[\]" glob: "src/**/*.cpp"
|
||||
```
|
||||
|
||||
**Find enum (non-class) declarations:**
|
||||
```
|
||||
grep pattern: "^[ ]*enum [^c]" glob: "src/**/*.h"
|
||||
```
|
||||
|
||||
## Security and Safety
|
||||
|
||||
- Never execute untrusted code
|
||||
- Use `bash` only for safe read-only operations (git, grep patterns)
|
||||
- Don't modify any files (this is an analysis-only workflow)
|
||||
- Focus on identifying issues, not fixing them (fixes can be done in follow-up PRs)
|
||||
|
||||
## Output Requirements
|
||||
|
||||
- Create exactly ONE comprehensive issue with all findings
|
||||
- Use the structured format above
|
||||
- Include specific file references for all examples
|
||||
- Provide actionable recommendations
|
||||
- Close any previous issues created by this workflow (using `close-older-issues: true`)
|
||||
Loading…
Add table
Add a link
Reference in a new issue