---
applyTo: "src/ExcelMcp.Core/Commands/**/*.cs,src/ExcelMcp.McpServer/**/*.cs"
---

# Core Commands Coverage - Mandatory Workflow

> **⚠️ CRITICAL**: When adding Core Commands methods, you MUST expose them in MCP Server

## Quick Reference

| Task | Command | Time |
|------|---------|------|
| Check coverage before commit | `.\scripts\audit-core-coverage.ps1` | 30s |
| Add new Core method | Follow 8-step workflow below | 5-10 min |
| Fix pre-commit hook failure | Add missing enum values + mappings | 2-3 min |
| Verify build | `dotnet build -c Release` | 1-2 min |

---

## Mandatory Workflow: Adding New Core Method

**ALWAYS follow these 8 steps in order:**

```markdown
1. ✅ Add method to Core Commands interface
   File: src/ExcelMcp.Core/Commands/[Feature]/I[Feature]Commands.cs
   Example: Task<OperationResult> NewMethodAsync(IExcelBatch batch);

2. ✅ Implement in Core Commands class  
   File: src/ExcelMcp.Core/Commands/[Feature]/[Feature]Commands.cs

3. ✅ Add enum value to ToolActions.cs
   File: src/ExcelMcp.McpServer/Models/ToolActions.cs
   Example: PowerQueryAction.NewMethod
   ⚠️ Build will show CS8524 error until steps 4-6 complete

4. ✅ Add ToActionString mapping
   File: src/ExcelMcp.McpServer/Models/ActionExtensions.cs
   Example: PowerQueryAction.NewMethod => "new-method",
   ⚠️ CS8524 error persists

5. ✅ Add switch case in MCP Tool
   File: src/ExcelMcp.McpServer/Tools/Excel[Feature]Tool.cs
   Example: PowerQueryAction.NewMethod => await NewMethodAsync(...),
   ⚠️ CS8524 error persists

6. ✅ Implement MCP method
   File: src/ExcelMcp.McpServer/Tools/Excel[Feature]Tool.cs
   Example: private static async Task<string> NewMethodAsync(...)
   ✅ CS8524 errors resolved

7. ✅ Build and verify
   Command: dotnet build -c Release
   Expected: 0 warnings, 0 errors

8. ✅ Update documentation
   Files: skill references (`skills/shared/`), tool descriptions, README (if needed)
```

**Why This Order**: Compiler (CS8524) enforces steps 3-6, preventing you from shipping unexposed Core methods.

---

## Compiler Enforcement (CS8524)

**The compiler FORCES you to expose Core methods** through enum-based switches:

```csharp
// Step 3: Add enum value (compiler checks this)
public enum PowerQueryAction
{
    List,
    View,
    NewMethod  // ⚠️ Forget this → CS8524 error in ActionExtensions.cs
}

// Step 4: Add ToActionString mapping (compiler checks this)
public static string ToActionString(this PowerQueryAction action) => action switch
{
    PowerQueryAction.List => "list",
    PowerQueryAction.View => "view",
    PowerQueryAction.NewMethod => "new-method",  // ⚠️ Forget this → CS8524 error
};

// Step 5: Add switch case in Tool (compiler checks this)
return action switch
{
    PowerQueryAction.List => await ListAsync(...),
    PowerQueryAction.View => await ViewAsync(...),
    PowerQueryAction.NewMethod => await NewMethodAsync(...),  // ⚠️ Forget this → CS8524 error
};
```

**Result**: **Impossible to compile** until all 3 enum mappings are added!

---

## Pre-Commit Hook (Automatic Check)

**Before every commit**, the pre-commit hook runs `audit-core-coverage.ps1` to verify Core methods match enum values.

**Setup** (one-time):
```powershell
.\scripts\pre-commit.ps1
```

**On failure, you see**:
```
❌ Coverage gaps detected! All Core methods must be exposed via MCP Server.

The following interfaces have fewer enum values than Core methods:
  - IRangeCommands: Core has 42 methods, RangeAction has 40 values (missing 2)

Action Required:
  1. Review Core interface for new methods
  2. Add missing enum values to ToolActions.cs
  3. Add ToActionString mappings to ActionExtensions.cs
  4. Add switch cases to appropriate MCP Tools
```

**Fix**: Follow 8-step workflow above.

**Emergency bypass** (use only for non-Core changes):
```bash
git commit --no-verify -m "Message"
```

⚠️ **Never use `--no-verify`** for Core Commands changes - fix the gaps instead!

---

## Manual Coverage Check

**Run anytime** to verify coverage:

```powershell
# Check coverage (shows gaps if any)
.\scripts\audit-core-coverage.ps1

# Check coverage and fail if gaps found (useful in CI/CD)
.\scripts\audit-core-coverage.ps1 -FailOnGaps

# Verbose output with detailed counts
.\scripts\audit-core-coverage.ps1 -Verbose
```

**Expected output when 100% coverage**:
```
Interface           CoreMethods EnumValues Gap Status
---------           ----------- ---------- --- ------
IPowerQueryCommands          18         18   0 ✅
ISheetCommands               13         13   0 ✅
IRangeCommands               42         42   0 ✅
ITableCommands               23         23   0 ✅

Summary: 100% coverage ✅ (156 Core methods, 156 enum values)
```

**When gaps detected**:
```
Interface           CoreMethods EnumValues Gap Status
---------           ----------- ---------- --- ------
IRangeCommands               42         40   2 ❌

Summary: 98.7% coverage (156 Core methods, 154 enum values, 2 gaps)
```

**Fix**: Follow 8-step workflow.

---

## Troubleshooting

### CS8524 Error: "Switch expression does not handle all possible values"

**Cause**: Added enum value but forgot to add it to switch expression.

**Fix**: Add the missing case to the switch expression in the file mentioned in error.

### Pre-Commit Hook Fails with "Coverage gaps detected"

**Cause**: Core interface has more methods than corresponding enum has values.

**Fix**: Follow 8-step workflow (steps 3-6).

### Build Succeeds but Pre-Commit Hook Still Fails

**Cause**: Added Core method but forgot to add enum value.

**Fix**: Add to ToolActions.cs, then mappings in ActionExtensions.cs, then Tool switch case.

---

## Key Takeaways

✅ **Compiler enforces coverage** - CS8524 prevents incomplete implementations  
✅ **Pre-commit hook verifies** - Catches gaps before commit  
✅ **8-step workflow is mandatory** - No shortcuts  
✅ **100% coverage is required** - No exceptions

