Common issues and solutions.

Linter Not Found

Symptom

{
  "status": "not_found",
  "error": "'ruff' is not installed. Install it with: pip install ruff"
}

Cause

The linter binary isn't in your PATH.

Solution

Install the linter:

pip install ruff
# or
brew install ruff

pip install pyright
# or
npm install -g pyright

npm install -D eslint
# or globally
npm install -g eslint

npm install -D typescript

Verify installation:

which ruff
ruff --version

No Linters Detected

Symptom

{
  "error": true,
  "code": "NO_LINTERS",
  "message": "No linters detected..."
}

Cause

lintent couldn't find linter configuration files.

Solution

Ensure config files exist:

Config Validation Error

Symptom

{
  "valid": false,
  "errors": [
    { "message": "Rule 'ruff/E501' must have 'legal' string" }
  ]
}

Cause

Your lintent.yaml has missing or invalid fields.

Solution

Each rule needs all three fields:

rules:
  ruff:
    E501:
      illegal: "Lines too long"     # Required
      legal: "Break into lines"     # Required
      why: "Readability"            # Required

Validate your config:

lintent validate --pretty

Violations Without Semantic Context

Symptom

{
  "code": "E999",
  "message": "Some error",
  "semantic": null
}

Cause

The rule code isn't defined in lintent.yaml.

Solution

Add the rule to your config:

rules:
  ruff:
    E999:
      illegal: "Description of what's wrong"
      legal: "How to fix it"
      why: "Why it matters"

Check semantic coverage in summary:

{
  "summary": {
    "with_semantic": 10,
    "without_semantic": 2  // ← These need rules added
  }
}

Empty Violations Array

Symptom

{
  "violations": [],
  "summary": { "total": 0 }
}

Possible Causes

1. Linter ran but found no issues - Your code is clean!

2. Linter failed silently - Check linters.results:

   {
     "linters": {
       "results": [
         { "name": "ruff", "status": "error", "error": "..." }
       ]
     }
   }

3. Wrong paths - Linter ran on wrong directory:

   linters:
     ruff:
       paths: ["./src"]  # Make sure this is correct

lintent Command Not Found

Symptom

lintent: command not found

Solution

Install globally:

npm install -g lintent

Or use npx:

npx lintent run

Check installation:

npm list -g lintent

JSON Parse Errors

Symptom

Garbled output or parse errors.

Cause

Linter output wasn't valid JSON.

Solution

Run the linter directly to check its output:

ruff check . --output-format json

If the linter has issues, fix them first.

Slow Performance

Symptom

lintent takes too long.

Causes & Solutions

1. Large codebase - Use paths to limit scope:

   linters:
     ruff:
       paths: ["./src"]  # Not entire repo

2. Many linters - Run specific ones:

   lintent run --tool ruff

3. Linter itself is slow - Check individual linter performance:

   time ruff check .

Getting Help

If you're still stuck:

1. Check the GitHub Issues
2. Run with --pretty to see full output
3. Verify linters work independently first
4. Create an issue with:
5. lintent version (lintent --version)
6. OS and Node version
7. Your lintent.yaml
8. Full error output