add-feature

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add Feature

添加功能

Guide for adding new functionality to Syncpack.

为Syncpack添加新功能的指南。

Quick Decision

快速决策

What are you adding?

New CLI command (lint, fix, format, etc.) → See adding-command.md
New validation logic (InstanceState variant) → See adding-instance-state.md
Both → Start with instance state, then add command

你要添加的内容是什么？

新CLI命令（lint、fix、format等）→ 查看adding-command.md
新验证逻辑（InstanceState变体）→ 查看adding-instance-state.md
两者都有 → 先从InstanceState开始，再添加命令

Prerequisites

前提条件

Before adding any feature:

Understand the 3-phase pattern: Create Context → Inspect Context → Run Command
Know which phase your feature affects
Check if similar code exists (use
```
ast-grep -p 'PATTERN' src/
```
)

添加任何功能之前：

理解三阶段模式：创建上下文 → 检查上下文 → 运行命令
明确你的功能会影响哪个阶段
检查是否存在类似代码（使用
```
ast-grep -p 'PATTERN' src/
```
）

Feature Types

功能类型

Commands

命令

Commands are user-facing operations (

syncpack lint

syncpack fix

, etc.).

When to create a new command:

New user-facing operation that doesn't fit existing commands
Different output format or behaviour needed

Registration points (all three required):

```
src/cli.rs
```
- Add to
```
Subcommand
```
enum
```
src/main.rs
```
- Add match arm for dispatch

src/commands/*.rs

- Implement

pub fn run(ctx: Context) -> i32

→ Full guide: adding-command.md

命令是面向用户的操作（

syncpack lint

、

syncpack fix

等）。

何时创建新命令：

新的面向用户操作，不适合现有命令
需要不同的输出格式或行为

注册点（三个都需要）：

```
src/cli.rs
```
- 添加到
```
Subcommand
```
枚举
```
src/main.rs
```
- 添加用于分发的匹配分支

src/commands/*.rs

- 实现

pub fn run(ctx: Context) -> i32

→ 完整指南：adding-command.md

Instance States

InstanceState

InstanceState variants describe validation results (valid, fixable, unfixable, suspect).

When to add a new state:

New validation rule needed
New type of error/warning to report
New auto-fix capability

Location:

src/instance_state.rs

src/visit_packages/*.rs

→ Full guide: adding-instance-state.md

InstanceState变体描述验证结果（有效、可修复、不可修复、可疑）。

何时添加新状态：

需要新的验证规则
需要报告新类型的错误/警告
需要新的自动修复能力

位置：

src/instance_state.rs

src/visit_packages/*.rs

→ 完整指南：adding-instance-state.md

Common Workflow

通用工作流

Write failing test using TestBuilder
Implement minimal code to pass
Run
```
cargo clippy
```
and fix warnings
Refactor if needed
Update documentation

使用TestBuilder编写失败的测试
实现最小化代码以通过测试
运行
```
cargo clippy
```
并修复警告
如有需要进行重构
更新文档

Checklist

检查清单

Before submitting:

Tests pass (
```
just test
```
)
Zero clippy warnings
Follows existing patterns
Registered in all required places (for commands)
Uses TDD approach