Skip to content

[WIP] Update JavaScript front matter hash consistency algorithm #13087

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Copilot wants to merge 2 commits into from
+58 −145
Closed

[WIP] Update JavaScript front matter hash consistency algorithm #13087

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
33b2cdf
Initial plan
Copilot Feb 1, 2026
088c5d3
Initial analysis of frontmatter hash inconsistency
Copilot Feb 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 58 additions & 145 deletions .github/aw/serena-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,173 +1,86 @@
# Serena Language Server Tool

Serena is a **language service protocol (LSP) MCP server** for semantic code analysis. Use it ONLY when you need deep code understanding beyond text manipulation.
Serena is an **advanced static analysis tool** that provides deep code understanding through language server capabilities. It is designed for **advanced coding tasks** that require sophisticated code analysis.

## Quick Decision: Should I Use Serena?
## When to Use Serena

**✅ YES - Use Serena when you need:**
- Symbol navigation (find all usages of a function/type)
- Call graph analysis across files
- Semantic duplicate detection (not just text matching)
- Refactoring analysis (functions in wrong files, extraction opportunities)
- Type relationships and interface implementations
⚠️ **Important**: Serena should only be suggested when the user **explicitly requests advanced static analysis** for specific programming languages.

**❌ NO - Use simpler tools when:**
- Searching text patterns → Use `grep`
- Editing files → Use `edit` tool
- Running commands → Use `bash`
- Working with YAML/JSON/Markdown → Use `edit` tool
- Simple file operations → Use `bash` or `create`
**Appropriate use cases:**
- Deep code refactoring requiring semantic understanding
- Complex code transformations across multiple files
- Advanced type checking and inference
- Cross-file dependency analysis
- Language-specific semantic analysis

**Rule of thumb**: If `grep` or `bash` can solve it in 1-2 commands, don't use Serena.
**NOT recommended for:**
- Simple file editing or text manipulation
- Basic code generation
- General workflow automation
- Tasks that don't require deep code understanding

## Configuration

Add to workflow frontmatter:
When a user explicitly asks for advanced static analysis capabilities:

```yaml
tools:
serena: ["go"] # Specify language(s): go, typescript, python, ruby, rust, java, cpp, csharp
serena: ["<language>"] # Specify the programming language(s)
```

Multi-language repositories:
```yaml
tools:
serena: ["go", "typescript"] # First language is default fallback
```

## Available Serena Tools

### Navigation & Analysis
- `find_symbol` - Search for symbols by name
- `get_symbols_overview` - List all symbols in a file
- `find_referencing_symbols` - Find where a symbol is used
- `find_referencing_code_snippets` - Find code snippets using a symbol
- `search_for_pattern` - Search for code patterns (regex)

### Code Editing
- `read_file` - Read file with semantic context
- `create_text_file` - Create/overwrite files
- `insert_at_line` - Insert content at line number
- `insert_before_symbol` / `insert_after_symbol` - Insert near symbols
- `replace_lines` - Replace line range
- `replace_symbol_body` - Replace symbol definition
- `delete_lines` - Delete line range

### Project Management
- `activate_project` - **REQUIRED** - Activate Serena for workspace
- `onboarding` - Analyze project structure
- `restart_language_server` - Restart LSP if needed
- `get_current_config` - View Serena configuration
- `list_dir` - List directory contents

## Usage Workflow

### 1. Activate Serena First

**Always call activate_project before other Serena tools:**

```javascript
// activate_project tool
{
"path": "/home/runner/work/gh-aw/gh-aw"
}
```

### 2. Combine with Other Tools

**Best practice**: Use bash for discovery, Serena for analysis
**Supported languages:**
- `go`
- `typescript`
- `python`
- `ruby`
- `rust`
- `java`
- `cpp`
- `csharp`
- And many more (see `.serena/project.yml` for full list)

## Detection and Usage

**To detect the repository's primary language:**
1. Check file extensions in the repository
2. Look for language-specific files:
- `go.mod` → Go
- `package.json` → TypeScript/JavaScript
- `requirements.txt` or `pyproject.toml` → Python
- `Cargo.toml` → Rust
- `pom.xml` or `build.gradle` → Java
- etc.

## Example Configuration

```yaml
tools:
serena: ["go"]
bash:
- "find pkg -name '*.go' ! -name '*_test.go'"
- "cat go.mod"
github:
toolsets: [default]
```

**Pattern**:
1. Use `bash` to list files
2. Use Serena to analyze semantic structure
3. Use `edit` to make changes

### 3. Use Cache for Recurring Analysis

Track analysis state across runs:

```yaml
tools:
serena: ["go"]
cache-memory: true # Store analysis history
```

Load cache → Analyze new/changed files → Save results → Avoid redundant work

## Common Patterns

### Pattern 1: Find All Function Usages

```
1. Use find_symbol to locate function definition
2. Use find_referencing_code_snippets to find call sites
3. Analyze patterns
serena: ["go"] # For Go repositories requiring advanced static analysis
```

### Pattern 2: Code Quality Analysis
## User Interaction Pattern

```
1. Use get_symbols_overview on multiple files
2. Use find_symbol for similar function names
3. Use search_for_pattern for duplicate logic
4. Identify consolidation opportunities
```
When a user describes a task:

### Pattern 3: Daily Code Analysis
1. **Analyze the request**: Does it require advanced static analysis?
2. **If NO**: Use standard tools (bash, edit, etc.)
3. **If YES**: Ask the user if they want to use Serena for advanced static analysis
4. **Only add Serena** if the user explicitly confirms

```
1. Load previous state from cache-memory
2. Select files using round-robin or priority
3. Use Serena for semantic analysis
4. Save findings to cache
5. Generate improvement tasks
```

## Production Examples

Workflows successfully using Serena:

- **go-fan** (97.6% success) - Go module usage analysis with round-robin
- **sergo** (94.4% success) - Daily code quality with 50/50 cached/new strategies
- **semantic-function-refactor** - Function clustering and outlier detection
- **daily-compiler-quality** - Rotating file analysis with cache tracking
**Example conversation:**

## Common Pitfalls
User: "I need to refactor the authentication logic across multiple files with proper type safety"

❌ **Using Serena for non-code files** - Use `edit` for YAML/JSON/Markdown
❌ **Forgetting activate_project** - Always call first
❌ **Not combining with bash** - Use bash for file discovery
❌ **Missing language configuration** - Must specify language(s)
Agent: "This task involves complex cross-file refactoring. Would you like me to use the Serena language server for advanced static analysis? This will provide deeper code understanding but adds complexity to the workflow."

## Supported Languages
User: "Yes, use Serena"

Primary languages with full LSP features:
- `go` (gopls)
- `typescript` (TypeScript/JavaScript)
- `python` (jedi/pyright)
- `ruby` (solargraph)
- `rust` (rust-analyzer)
- `java`, `cpp`, `csharp`
Agent: *Adds `serena: ["go"]` to the workflow configuration*

See `.serena/project.yml` for complete list (25+ languages).
## Best Practices

## Decision Tree

```
Task requires code semantics/structure?
├─ NO → Use bash/edit/view
└─ YES
├─ Simple text search/replace? → Use grep/bash
├─ Config/data files? → Use edit
└─ Symbol/structure/semantic patterns? → Use Serena ✅
```
- **Default to simpler tools** when possible
- **Only suggest Serena** for genuinely complex analysis tasks
- **Ask before adding** Serena to a workflow
- **Explain the benefits** when suggesting Serena
- **Consider the trade-offs** (added complexity vs. better analysis)