Lintro verify

Verify Lintro Tool Implementation

Use this skill to verify that a lintro tool implementation is complete and follows all project standards.

Usage

When asked to verify a tool (e.g., /lintro-verify tsc), run through all checklist items below.

---

1. Core Implementation

Plugin Definition

• lintro/tools/definitions/<tool>.py exists
• Uses @register_tool decorator from lintro.plugins.registry
• Inherits from BaseToolPlugin
• ToolDefinition includes:
  • name - tool identifier (lowercase)
  • description - clear description of what the tool does
  • file_patterns - list of glob patterns (e.g., ["*.ts", "*.tsx"])
  • tool_type - appropriate ToolType enum value
  • can_fix - boolean indicating if tool supports auto-fix
  • native_configs - list of config files the tool uses (e.g., ["tsconfig.json"])
  • version_command - command to check version (e.g., ["tsc", "--version"])
  • priority - execution priority (default 50)
• check() method implemented
• fix() method implemented (or raises NotImplementedError if can_fix=False)
• Options defined with proper types and defaults

Parser

• lintro/parsers/<tool>/ directory exists with:
  • __init__.py - exports parser and issue classes
  • <tool>_parser.py - parses tool output into issues
  • <tool>_issue.py - issue dataclass with to_display_row() method
• Parser handles all output formats the tool produces
• Parser handles edge cases (empty output, errors, warnings)

Enums (if needed)

• Tool added to lintro/enums/tool_name.py if it has a ToolName enum

Version Management

• Version added to lintro/_tool_versions.py (for external tools)
• Install hint added to lintro/tools/core/version_checking.py get_install_hints() templates
• Version is reasonably current (check latest: npm view <tool> version or brew info <tool>)

Version Consistency (CRITICAL)

• All version sources are aligned:
  • lintro/_tool_versions.py version
  • package.json version (for npm tools)
  • Plugin min_version in tool definition
  • lintro/tools/manifest.json version
• Renovate custom manager exists in renovate.json for _tool_versions.py
• package.json uses caret (^) prefix matching _tool_versions.py (e.g., ^0.27.0)
• Plugin min_version equals or is less than _tool_versions.py version

Doctor Health Check

• Tool added to TOOL_COMMANDS in lintro/cli_utils/commands/doctor.py
• lintro doctor shows tool with correct version (no "No cmd defined")

Command Builder (if needed)

• If tool needs special command building, added to lintro/tools/core/command_builders.py

CLI Option Verification

• Run <tool> --help and compare against implemented set_options() parameters
• Verify each option is a real CLI flag (not config-file-only)
• Test --tool-options actually work: lintro check . --tools <tool> --tool-options "<tool>:option=value"
• Document which settings are CLI-available vs config-file-only in docs

Native Config Integration

• Run <tool> --init (if available) to see default config structure
• If tool has config file with useful settings, check if lintro/utils/native_parsers.py should parse it
• Verify native_configs in ToolDefinition lists all supported config files

---

2. Documentation

README.md

• Tool added to Supported Tools table with badge, language, and fix support
• Tool added to Optional External Tools list (for external tools) with install commands

docs/getting-started.md

• Tool added to Optional External Tools section with install instructions
• Usage example section added (if tool has unique features)

docs/configuration.md

• Full configuration section added including:
  • Tool description
  • Installation instructions (all methods: brew, npm/bun, pip, etc.)
  • Native config file example
  • Available --tool-options table
  • Usage examples

docs/tool-analysis/{tool}-analysis.md

• Tool analysis document created following the standard format:
  • Overview of what the tool does
  • Core Tool Capabilities (native features)
  • Lintro Implementation Analysis:
    • Preserved Features (what lintro exposes)
    • Limited / Missing (what's NOT available via lintro)
    • Enhancements (what lintro adds: timeout, normalization, etc.)
  • Usage Comparison (native vs lintro commands)
  • Configuration Strategy
  • Priority and Conflicts
  • Recommendations (when to use lintro vs native tool)

---

3. Tests

Unit Tests

• tests/unit/tools/<tool>/ directory with:
  • test_options.py - definition attributes, default options, set_options validation
  • test_execution.py - check/fix with mocked subprocess
• tests/unit/parsers/test_<tool>_parser.py - parser tests covering:
  • Single error/warning parsing
  • Multiple issues parsing
  • Empty output handling
  • Edge cases (different file extensions, paths, etc.)
  • to_display_row() output

Integration Tests

• tests/integration/tools/test_<tool>_integration.py with:
  • pytest.mark.skipif for when tool not installed
  • Fixtures for test files (with issues and clean)
  • test_definition_attributes - name, can_fix
  • test_definition_file_patterns - correct patterns
  • test_check_file_with_issues - detects problems
  • test_check_clean_file - no false positives
  • test_check_empty_directory - handles gracefully
  • test_set_options - options work correctly

Test Samples

• test_samples/tools/<language>/<tool>/ directory with:
  • <tool>_violations.<ext> - file with deliberate issues (verify tool detects them)
  • <tool>_clean.<ext> - valid file without issues (verify no false positives)
• Violations file triggers actual tool errors when run directly: <tool> <violations_file>

---

4. CI/CD & Docker

Dockerfile.tools

• Tool version verification added (e.g., tsc --version && \)

Dockerfile (runtime)

• Tool binary/wrapper copied from builder stage
• For Node.js tools: wrapper script created in /usr/local/bin/

scripts/utils/install-tools.sh

• Tool added to help text description
• Installation block added with version from _tool_versions.py
• Tool added to "Installed tools" echo list
• Tool added to tools_to_verify array

scripts/ci/tools-image-verify.sh

• Tool version check added

.github/workflows/tools-image.yml

• Verify trigger paths include relevant files (usually automatic via Dockerfile.tools)

---

5. User Experience

lintro list-tools

• Tool appears with correct name, language, actions, priority, config type

Error Handling

• Graceful handling when tool not installed
• Clear error messages with install hints
• No crashes on malformed tool output

Install Hints

• All common installation methods documented (brew, npm/bun, pip, cargo, etc.)
• Version placeholders work correctly in hints

---

6. Verification Commands

Run these to verify implementation:

# Unit tests
uv run pytest tests/unit/tools/<tool>/ tests/unit/parsers/test_<tool>_parser.py -v

# Integration tests (requires tool installed)
uv run pytest tests/integration/tools/test_<tool>_integration.py -v

# Test on sample files
uv run lintro check test_samples/tools/<language>/<tool>/ --tools <tool>

# Verify tool appears in list
uv run lintro list-tools | grep <tool>

# Full lint check
uv run lintro chk

# Full test suite
uv run pytest tests/ -v

Version Consistency Verification

# Check all version sources are aligned (replace <tool> with actual name)
echo "=== _tool_versions.py ===" && grep "<tool>" lintro/_tool_versions.py
echo "=== manifest.json ===" && grep -A3 '"<tool>"' lintro/tools/manifest.json
echo "=== package.json ===" && grep "<tool>" package.json
echo "=== Plugin min_version ===" && grep "min_version" lintro/tools/definitions/<tool>.py
echo "=== Renovate manager ===" && grep -A5 '"<tool>"' renovate.json | head -10
echo "=== Doctor TOOL_COMMANDS ===" && grep "<tool>" lintro/cli_utils/commands/doctor.py

CLI Option Verification Commands

# Compare native CLI options against lintro implementation
<tool> --help

# Check version currency
npm view <tool> version        # for npm packages
brew info <tool>               # for Homebrew packages
pip index versions <tool>      # for Python packages

# Test that tool-options actually work (should not error)
uv run lintro check test_samples/ --tools <tool> --tool-options "<tool>:timeout=60"

# Test each documented option (replace with actual options)
uv run lintro check . --tools <tool> --tool-options "<tool>:option_name=value"

# Generate default config to understand structure
<tool> --init  # if available

---

7. Common Issues to Check

• No "Missing install hints for tools" warning when running lintro
• Tool respects --tool-options passed via CLI
• Tool uses native config file when present
• Parser correctly maps severity levels
• File paths in issues are correct (relative vs absolute)
• Line/column numbers are 1-indexed (not 0-indexed)
• Tool timeout is configurable and has reasonable default
• CLI options actually exist - verify with <tool> --help (some tools only support options via config file)
• Version is current - check if pinned version is significantly outdated
• Config-file-only options are not exposed as --tool-options (will cause runtime errors)
• Version consistency - _tool_versions.py, package.json, and plugin min_version are aligned
• Renovate manager - custom regex manager exists in renovate.json for external tools

---

Review Output Format

After reviewing, provide a summary:

## Tool Review: <tool_name>

### Status: PASS / FAIL / PARTIAL

### Checklist Summary
- Core Implementation: X/Y items
- Documentation: X/Y items
- Tests: X/Y items
- CI/Docker: X/Y items
- User Experience: X/Y items

### Missing Items
1. [item description]
2. [item description]

### Recommendations
1. [recommendation]
2. [recommendation]