---
name: checking-files-with-lsp
description: Use when you need to check, verify, validate or understand code or structure of a file (often code related files or markdown) - automatically detects file type, finds appropriate LSP/linter in mise, and runs validation
---

# Checking Files With LSP

## Overview

When you need to validate, check, or understand a file's structure or code quality, use language servers and linters to do it systematically. This skill provides a reliable workflow: detect the file type, search mise for available LSP/linter tools, intelligently choose one, and run the check.

**Core principle:** Let the appropriate tool for the language do the validation work, not manual inspection. Automate tool discovery and selection.

## When to Use

**Use this skill when:**

- Checking code files for syntax errors, type issues, or style problems
- Validating configuration files (YAML, TOML, JSON, KDL, etc.)
- Understanding code structure or quality of unfamiliar files
- Verifying Markdown files for formatting/link issues
- Need to quickly understand what problems exist in a file

**Don't use when:**

- Just reading a file to understand its contents (no validation needed)
- Running full test suites (that's testing, not validation)
- Analyzing code behavior (that's debugging, not validation)

## The Workflow

### Step 1: Detect File Type

Determine the language/type from file extension:

```
.lua     → lua
.ts/.tsx → typescript
.py      → python
.go      → go
.rs      → rust
.md      → markdown
.json    → json
.yaml    → yaml
.toml    → toml
.kdl     → kdl
```

If extension is unclear or missing, inspect file shebang or content patterns.

### Step 2: Search Mise for LSP/Linters

Run: `mise search <filetype>`

This returns all available language servers, linters, and formatters for that language.

**Example outputs:**

```
mise search lua
lua-language-server    (most popular)
stylua                 (formatter)

mise search python
pyright
pylance
python-language-server
black
ruff
```

### Step 3: Make Smart Selection

**Prioritize by tool type:** Language Server (LSP) > Linter > Formatter

LSPs provide the most comprehensive validation. Linters catch style/quality issues. Formatters are secondary for validation purposes.

**If ONE obvious choice exists:**

- Auto-select it (e.g., only lua-language-server for Lua)
- Verify installation: `mise list | grep <tool>` (if not listed, install it)
- Install: `mise install lua-language-server`
- Run it on the file

**If MULTIPLE choices exist:**

- Filter by priority: Show LSPs first, linters second, skip formatters
- Rank by popularity: Most-used tools first (measured by GitHub stars, then npm/PyPI downloads as tiebreaker)
- Show ranked list to user (with tool type and brief descriptions)
- Let user pick by number/letter
- Verify and install selected tool
- Run it on the file

**If NO tools found:**

- **Inform user explicitly:** "No LSP/linter available in mise for [filetype]"
- Suggest alternatives in order:
  1. Check online package managers (npm, PyPI, cargo, etc.) if not in mise
  2. Look for generic validators (jq for JSON, yamllint for YAML, etc.)
  3. Basic syntax checking (built-in language checkers)
  4. Manual validation with structured guidance
- Offer: "Would you like me to help install from another source?"

### Step 4: Run Validation

Execute the selected tool against the file and return results: errors, warnings, style issues, and suggestions.

## Quick Reference

| Task | Action |
|------|--------|
| Detect file type | Use file extension as primary signal |
| Find tools | `mise search <filetype>` |
| Install obvious choice | `mise install <tool>` (auto-selected) |
| Show options | Present ranked list for user choice |
| Run validation | Execute tool with file path |

## Common Mistakes

**Mistake: Skip file type detection**

- Wrong: "It's a code file, any language server works"
- Right: File type determines which LSP applies. Wrong LSP = wrong errors

**Mistake: Pick random LSP when multiple exist**

- Wrong: "I'll just try the first one" or "They're all the same"
- Right: Different LSPs check different aspects. Use ranking: most popular > less common. Filter by type: LSP > Linter > Formatter
- **No exceptions:** You must present options to user when multiple exist, not guess

**Mistake: Assume LSP is installed**

- Wrong: "Let me just run lua-language-server..."
- Right: Always verify with `mise search` first. Check `mise list` before installing. Install if needed

**Mistake: Don't check system requirements**

- Wrong: "Install the LSP and it'll work"
- Right: Some LSPs need runtime dependencies (Python, Node, etc.). Test LSP runs before reporting results

**Mistake: When LSP unavailable, give up**

- Wrong: "No tool for this language, can't validate"
- Right: Explore alternatives in order: online package managers → generic validators → syntax checking → manual guidance

**Mistake: Mixing tool categories**

- Wrong: Showing formatters and linters equally for validation
- Right: Prioritize LSP > Linter > Formatter. Use tool type as first filter

## Fallback Validation Options

When LSP/linter not available in mise:

1. Check online package managers (npm, PyPI, cargo, etc.) if not in mise
2. Look for generic validators - JSON validators, YAML checkers work across projects
3. Basic syntax checking - Some languages have built-in syntax checkers
4. Manual validation - Provide structured review guidance
5. Suggest installation - "Would you like me to help install from another source?"

## Implementation Steps

When helping a user check a file:

1. Ask or determine: "What file are we checking?"
2. Detect the file type from extension
3. Run: `mise search <filetype>`
4. Decide: obvious choice or show ranked options?
5. Verify installation: `mise list | grep <tool>` (check if already installed)
6. Install if needed: `mise install <selected-tool>`
7. Test tool runs: Verify LSP/linter executes without errors
8. Run: Execute tool against file with appropriate flags
9. Report: Show user the validation results
10. Offer next steps: "Fix these issues?" or "Run checks again?"

## Troubleshooting

**Tool installs but won't run:**

- Some LSPs need runtime dependencies (Python for some tools, Node for others)
- Check LSP documentation for runtime requirements
- Example: `python-language-server` needs Python installed
- Verify with: `mise exec <tool> -- <tool> --version`

**Mise search returns no results:**

- Language might not be in mise database
- Try alternative package managers: npm (JavaScript), PyPI (Python), cargo (Rust)
- Or use generic validators: jq (JSON), yamllint (YAML)

**LSP finds errors but tool isn't right for the job:**

- Wrong tool selected (formatter instead of LSP)
- Go back to Step 3, filter by type priority (LSP > Linter)
- Ask user to pick a different option from the list

**File has unusual extension:**

- Use file content inspection (shebang, headers) as fallback
- Example: Executable shell scripts often lack `.sh` extension
- Check content to confirm type before searching mise

## Real-World Impact

- Fast validation: No manual code review for common issues
- Consistent checking: Same tool, same criteria, every time
- Discovery: Find issues you'd miss with manual inspection
- Automation: Can be integrated into workflows, CI/CD, pre-commit hooks
- Language agnostic: Same pattern works for any language with an LSP available