atomctl/specs/001-pkg-ast-provider/spec.md

Feature Specification: 优化 pkg/ast/provider 目录的代码组织逻辑与功能实现

Feature Branch: 001-pkg-ast-provider Created: 2025-09-19 Status: Draft Input: User description: "优化 @pkg/ast/provider/ 目录的代码组织逻辑与功能实现，补充完善测试用例"

Execution Flow (main)

1. Parse user description from Input
   → If empty: ERROR "No feature description provided"
2. Extract key concepts from description
   → Identify: actors, actions, data, constraints
3. For each unclear aspect:
   → Mark with [NEEDS CLARIFICATION: specific question]
4. Fill User Scenarios & Testing section
   → If no clear user flow: ERROR "Cannot determine user scenarios"
5. Generate Functional Requirements
   → Each requirement must be testable
   → Mark ambiguous requirements
6. Identify Key Entities (if data involved)
7. Run Review Checklist
   → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
   → If implementation details found: ERROR "Remove tech details"
8. Return: SUCCESS (spec ready for planning)

---

⚡ Quick Guidelines

• ✅ Focus on WHAT users need and WHY
• ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
• 👥 Written for business stakeholders, not developers

Section Requirements

• Mandatory sections: Must be completed for every feature
• Optional sections: Include only when relevant to the feature
• When a section doesn't apply, remove it entirely (don't leave as "N/A")

For AI Generation

When creating this spec from a user prompt:

1. Mark all ambiguities: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
2. Don't guess: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
3. Think like a tester: Every vague requirement should fail the "testable and unambiguous" checklist item
4. Common underspecified areas:
   • User types and permissions
   • Data retention/deletion policies
   • Performance targets and scale
   • Error handling behaviors
   • Integration requirements
   • Security/compliance needs

---

User Scenarios & Testing (mandatory)

Primary User Story

作为开发者，我需要使用 atomctl 工具来解析 Go 源码中的 @provider 注释，并生成相应的依赖注入代码。我希望代码组织逻辑清晰，功能实现可靠，并且有完整的测试用例来保证代码质量。

Acceptance Scenarios

1. Given 一个包含 @provider 注释的 Go 源码文件，When 我运行解析功能，Then 系统能正确提取所有 provider 信息并生成相应的代码
2. Given 一个复杂的 Go 项目结构，When 我解析多个文件中的 provider，Then 系统能正确处理跨文件的依赖关系
3. Given 一个包含错误注释格式的源码文件，When 我运行解析功能，Then 系统能提供清晰的错误信息和建议
4. Given 生成的 provider 代码，When 我运行测试套件，Then 所有测试都能通过，覆盖率达到 90%

Edge Cases

• 当源码文件格式不正确时，系统如何处理？
• 当注释格式不规范时，系统如何提供有用的错误信息？
• 当处理大型项目时，系统性能如何保证？
• 当并发处理多个文件时，如何保证线程安全？

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST 能够解析 @provider 注释的各种格式（基本格式、带模式、带返回类型、带分组等）
• FR-002: System MUST 支持不同的 provider 模式（grpc、event、job、cronjob、model）
• FR-003: System MUST 正确处理依赖注入参数（only/except 模式、包名解析、类型识别）
• FR-004: System MUST 能够生成结构化的 provider 代码，包括必要的导入和函数定义
• FR-005: System MUST 提供完整的错误处理机制，包括语法错误、导入错误等
• FR-006: System MUST 包含全面的测试用例，覆盖所有主要功能和边界情况
• FR-007: System MUST 优化代码组织结构，提高代码的可读性和可维护性
• FR-008: System MUST 处理复杂的包导入和别名解析逻辑

Key Entities (include if feature involves data)

• Provider: 代表一个依赖注入提供者的核心实体，包含结构名、返回类型、模式等属性
• ProviderDescribe: 描述 provider 注释解析结果的实体，包含模式、返回类型、分组等信息
• InjectParam: 描述注入参数的实体，包含类型、包名、别名等信息
• SourceFile: 代表待解析的源码文件，包含文件路径、内容、导入信息等

---

Review & Acceptance Checklist

GATE: Automated checks run during main() execution

Content Quality

• No implementation details (languages, frameworks, APIs)
• Focused on user value and business needs
• Written for non-technical stakeholders
• All mandatory sections completed

Requirement Completeness

• No [NEEDS CLARIFICATION] markers remain
• Requirements are testable and unambiguous
• Success criteria are measurable
• Scope is clearly bounded
• Dependencies and assumptions identified

---

Execution Status

Updated by main() during processing

• User description parsed
• Key concepts extracted
• Ambiguities marked
• User scenarios defined
• Requirements generated
• Entities identified
• Review checklist passed

---