lintro-verify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Verify Lintro Tool Implementation

验证Lintro工具实现

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

使用此技能来验证lintro工具的实现是否完整且符合所有项目标准。

Usage

使用方法

When asked to verify a tool (e.g.,

/lintro-verify tsc

), run through all checklist items below.

当被要求验证某个工具（例如

/lintro-verify tsc

）时，逐一检查以下所有清单项。

1. Core Implementation

1. 核心实现

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

```
lintro/tools/definitions/<tool>.py
```
文件存在
使用了
```
lintro.plugins.registry
```
中的
```
@register_tool
```
装饰器
继承自
```
BaseToolPlugin
```
```
ToolDefinition
```
包含以下内容：
- ```
name
```
  - 工具标识符（小写）
- ```
description
```
  - 工具功能的清晰描述
- ```
file_patterns
```
  - 通配符模式列表（例如
```
["*.ts", "*.tsx"]
```
  ）
- ```
tool_type
```
  - 合适的
```
ToolType
```
  枚举值
- ```
can_fix
```
  - 布尔值，指示工具是否支持自动修复
- ```
native_configs
```
  - 工具使用的配置文件列表（例如
```
["tsconfig.json"]
```
  ）
- ```
version_command
```
  - 检查版本的命令（例如
```
["tsc", "--version"]
```
  ）
- ```
priority
```
  - 执行优先级（默认值50）
实现了
```
check()
```
方法
实现了
```
fix()
```
方法（如果
```
can_fix=False
```
，则抛出
```
NotImplementedError
```
）
使用正确的类型和默认值定义了选项

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)

```
lintro/parsers/<tool>/
```
目录存在，包含：
- ```
__init__.py
```
  - 导出解析器和问题类
- ```
<tool>_parser.py
```
  - 将工具输出解析为问题
- ```
<tool>_issue.py
```
  - 带有
```
to_display_row()
```
  方法的问题数据类
解析器能处理工具生成的所有输出格式
解析器能处理边缘情况（空输出、错误、警告）

Enums (if needed)

枚举（如有需要）

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

如果工具拥有
```
ToolName
```
枚举，已将其添加到
```
lintro/enums/tool_name.py
```

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>
```
)

版本已添加到
```
lintro/_tool_versions.py
```
（针对外部工具）

安装提示已添加到

lintro/tools/core/version_checking.py

的

get_install_hints()

模板中

版本为合理的当前版本（检查最新版本：
```
npm view <tool> version
```
或
```
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

所有版本源保持一致：
- ```
lintro/_tool_versions.py
```
  中的版本
- ```
package.json
```
  中的版本（针对npm工具）
- 工具定义中的插件
```
min_version
```
- ```
lintro/tools/manifest.json
```
  中的版本
```
renovate.json
```
中存在针对
```
_tool_versions.py
```
的Renovate自定义管理器
```
package.json
```
使用脱字符(^)前缀匹配
```
_tool_versions.py
```
中的版本（例如 ^0.27.0）
插件
```
min_version
```
等于或小于
```
_tool_versions.py
```
中的版本

Doctor Health Check

Doctor健康检查

Tool added to

TOOL_COMMANDS

lintro/cli_utils/commands/doctor.py

```
lintro doctor
```
shows tool with correct version (no "No cmd defined")

工具已添加到

lintro/cli_utils/commands/doctor.py

的

TOOL_COMMANDS

中

```
lintro doctor
```
显示工具的正确版本（无"No cmd defined"提示）

Command Builder (if needed)

命令构建器（如有需要）

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

如果工具需要特殊的命令构建逻辑，已添加到
```
lintro/tools/core/command_builders.py
```

CLI Option Verification

CLI选项验证

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

运行
```
<tool> --help
```
并与已实现的
```
set_options()
```
参数进行对比
验证每个选项都是真实的CLI标志（而非仅支持配置文件）

测试

--tool-options

实际可用：

lintro check . --tools <tool> --tool-options "<tool>:option=value"

在文档中记录哪些设置支持CLI配置、哪些仅支持配置文件

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

运行
```
<tool> --init
```
（如果可用）查看默认配置结构
如果工具的配置文件包含有用设置，检查是否需要在
```
lintro/utils/native_parsers.py
```
中解析它
验证
```
ToolDefinition
```
中的
```
native_configs
```
列出了所有支持的配置文件

2. Documentation

2. 文档

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

添加了完整的配置章节，包括：
- 工具描述
- 安装说明（所有方式：brew、npm/bun、pip等）
- 原生配置文件示例
- 可用的
```
--tool-options
```
  表格
- 使用示例

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)

已按照标准格式创建工具分析文档：
- 工具功能概述
- 核心工具能力（原生功能）
- Lintro实现分析：
  - 保留的功能（lintro暴露的功能）
  - 受限/缺失的功能（无法通过lintro使用的功能）
  - 增强功能（lintro添加的功能：超时、标准化等）
- 使用对比（原生命令vs lintro命令）
- 配置策略
- 优先级与冲突
- 使用建议（何时使用lintro vs 原生工具）

3. Tests

3. 测试

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

```
tests/unit/tools/<tool>/
```
目录包含：
- ```
test_options.py
```
  - 定义属性、默认选项、set_options验证
- ```
test_execution.py
```
  - 模拟子进程的check/fix测试
```
tests/unit/parsers/test_<tool>_parser.py
```
- 解析器测试覆盖：
- 单个错误/警告解析
- 多个问题解析
- 空输出处理
- 边缘情况（不同文件扩展名、路径等）
- ```
to_display_row()
```
  输出

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

```
tests/integration/tools/test_<tool>_integration.py
```
包含：
- 工具未安装时的
```
pytest.mark.skipif
```
  标记
- 测试文件的夹具（包含问题和无问题的文件）
- ```
test_definition_attributes
```
  - 名称、can_fix验证
- ```
test_definition_file_patterns
```
  - 正确的模式验证
- ```
test_check_file_with_issues
```
  - 检测问题的验证
- ```
test_check_clean_file
```
  - 无假阳性的验证
- ```
test_check_empty_directory
```
  - 优雅处理空目录的验证
- ```
test_set_options
```
  - 选项功能正常的验证

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>
```

```
test_samples/tools/<language>/<tool>/
```
目录包含：
- ```
<tool>_violations.<ext>
```
  - 包含故意问题的文件（验证工具能检测到）
- ```
<tool>_clean.<ext>
```
  - 无问题的有效文件（验证无假阳性）
直接运行工具时，违规文件会触发实际错误：
```
<tool> <violations_file>
```

4. CI/CD & Docker

Dockerfile.tools

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

添加了工具版本验证（例如
```
tsc --version && \
```
）

Dockerfile (runtime)

Dockerfile（运行时）

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

工具二进制文件/包装器已从构建阶段复制过来
针对Node.js工具：已在
```
/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

工具已添加到帮助文本描述中
添加了安装块，使用
```
_tool_versions.py
```
中的版本
工具已添加到“已安装工具”回显列表
工具已添加到
```
tools_to_verify
```
数组

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)

验证触发路径包含相关文件（通常通过Dockerfile.tools自动实现）

5. User Experience

5. 用户体验

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

已记录所有常见安装方式（brew、npm/bun、pip、cargo等）
提示中的版本占位符能正常工作

6. Verification Commands

6. 验证命令

Run these to verify implementation:

bash

undefined

运行以下命令验证实现：

bash

undefined

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

完整的lint检查

uv run lintro chk

Full test suite

完整测试套件

uv run pytest tests/ -v

undefined

uv run pytest tests/ -v

undefined

Version Consistency Verification

版本一致性验证

bash

undefined

bash

undefined

Check all version sources are aligned (replace <tool> with actual name)

检查所有版本源是否一致（将<tool>替换为实际名称）

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

undefined

undefined

CLI Option Verification Commands

CLI选项验证命令

bash

undefined

bash

undefined

Compare native CLI options against lintro implementation

对比原生CLI选项与lintro实现

<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

npm view <tool> version # 针对npm包 brew info <tool> # 针对Homebrew包 pip index versions <tool> # 针对Python包

Test that tool-options actually work (should not error)

测试tool-options实际可用（不应报错）

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

---

<tool> --init # 如果可用

---

7. Common Issues to Check

7. 需要检查的常见问题

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

运行lintro时无“Missing install hints for tools”警告
工具遵守通过CLI传递的
```
--tool-options
```
工具存在原生配置文件时会使用它
解析器正确映射严重级别
问题中的文件路径正确（相对路径vs绝对路径）
行/列号为1索引（而非0索引）
工具超时可配置且具有合理默认值
CLI选项确实存在 - 使用
```
<tool> --help
```
验证（部分工具仅支持通过配置文件设置选项）
版本为当前版本 - 检查固定版本是否已显著过时
仅支持配置文件的选项未作为
```
--tool-options
```
暴露（会导致运行时错误）

版本一致性 -

_tool_versions.py

、

package.json

和插件

min_version

保持一致

Renovate管理器 - 针对外部工具的自定义正则管理器已存在于
```
renovate.json
```

Review Output Format

评审输出格式

After reviewing, provide a summary:

text

undefined

评审完成后，提供摘要：

text

undefined

Tool Review: <tool_name>

工具评审: <tool_name>

Status: PASS / FAIL / PARTIAL

状态: 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

核心实现: X/Y项
文档: X/Y项
测试: X/Y项
CI/Docker: X/Y项
用户体验: X/Y项

Missing Items

缺失项

[item description]
[item description]

[项描述]
[项描述]

Recommendations

建议

[recommendation]
[recommendation]

undefined

[建议内容]
[建议内容]

undefined