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

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:

bash

# 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

bash

# 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

bash

# 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:

text

## 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]

lintro-verify

NPX Install

Tags

SKILL.md Content

Verify Lintro Tool Implementation

Usage

1. Core Implementation

Plugin Definition

Parser

Enums (if needed)

Version Management

Version Consistency (CRITICAL)

Doctor Health Check

Command Builder (if needed)

CLI Option Verification

Native Config Integration

2. Documentation

README.md

docs/getting-started.md

docs/configuration.md

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

3. Tests

Unit Tests

Integration Tests

Test Samples

4. CI/CD & Docker

Dockerfile.tools

Dockerfile (runtime)

scripts/utils/install-tools.sh

scripts/ci/tools-image-verify.sh

.github/workflows/tools-image.yml

5. User Experience

lintro list-tools

Error Handling

Install Hints

6. Verification Commands

Version Consistency Verification

CLI Option Verification Commands

7. Common Issues to Check

Review Output Format