feat: Refactor AST generation routes workflow
- Introduced a comprehensive data model for route definitions, parameters, and validation rules. - Established component interfaces for route parsing, comment parsing, import resolution, route building, validation, and rendering. - Developed a detailed implementation plan outlining execution flow, user requirements, and compliance with design principles. - Created a quickstart guide to assist users in utilizing the refactored system effectively. - Conducted thorough research on existing architecture, identifying key improvements and establishing a refactoring strategy. - Specified functional requirements and user scenarios to ensure clarity and testability. - Generated a task list for implementation, emphasizing test-driven development and parallel execution where applicable.
This commit is contained in:
Rogee
122
specs/002-refactor-ast-gen/spec.md
Normal file
122
specs/002-refactor-ast-gen/spec.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# Feature Specification: Refactor AST Generation Routes Workflow
|
||||
|
||||
**Feature Branch**: `002-refactor-ast-gen`
|
||||
**Created**: 2025-09-22
|
||||
**Status**: Draft
|
||||
**Input**: User description: "refactor ast gen routes workflow"
|
||||
|
||||
## Execution Flow (main)
|
||||
```
|
||||
1. Parse user description from Input
|
||||
<20> If empty: ERROR "No feature description provided"
|
||||
2. Extract key concepts from description
|
||||
<20> Identify: actors, actions, data, constraints
|
||||
3. For each unclear aspect:
|
||||
<20> Mark with [NEEDS CLARIFICATION: specific question]
|
||||
4. Fill User Scenarios & Testing section
|
||||
<20> If no clear user flow: ERROR "Cannot determine user scenarios"
|
||||
5. Generate Functional Requirements
|
||||
<20> Each requirement must be testable
|
||||
<20> Mark ambiguous requirements
|
||||
6. Identify Key Entities (if data involved)
|
||||
7. Run Review Checklist
|
||||
<20> If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
|
||||
<20> If implementation details found: ERROR "Remove tech details"
|
||||
8. Return: SUCCESS (spec ready for planning)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## <20> Quick Guidelines
|
||||
- Focus on WHAT users need and WHY
|
||||
- L Avoid HOW to implement (no tech stack, APIs, code structure)
|
||||
- =e 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
|
||||
As a developer using the atomctl code generation system, I need the AST-based route generation workflow to be refactored so that it is more maintainable, extensible, and follows consistent patterns with other generation workflows in the system.
|
||||
|
||||
### Acceptance Scenarios
|
||||
1. **Given** a developer wants to generate route handlers from AST annotations, **When** they run the generation command, **Then** the system should correctly parse route definitions and generate appropriate handler code
|
||||
2. **Given** existing route generation code has inconsistent patterns, **When** the refactoring is complete, **Then** all route generation should follow the same architectural patterns as other providers
|
||||
3. **Given** the current system has duplicate logic, **When** the refactoring is complete, **Then** common functionality should be shared and DRY principles should be applied
|
||||
|
||||
### Edge Cases
|
||||
- What happens when the system encounters unsupported route annotations?
|
||||
- How does the system handle conflicting route definitions?
|
||||
- What occurs when there are circular dependencies between route handlers?
|
||||
|
||||
## Requirements *(mandatory)*
|
||||
|
||||
### Functional Requirements
|
||||
- **FR-001**: System MUST parse route-related annotations from AST structures
|
||||
- **FR-002**: System MUST generate route handler code based on parsed annotations
|
||||
- **FR-003**: Users MUST be able to define route patterns and HTTP methods through annotations
|
||||
- **FR-004**: System MUST integrate route generation with existing provider generation workflow
|
||||
- **FR-005**: System MUST eliminate duplicate code between route generation and other generation workflows
|
||||
- **FR-006**: System MUST follow consistent error handling patterns across all generation workflows
|
||||
- **FR-007**: System MUST provide clear feedback when route generation fails or encounters issues
|
||||
|
||||
*Example of marking unclear requirements:*
|
||||
- **FR-008**: System MUST support [NEEDS CLARIFICATION: which HTTP methods? GET, POST, PUT, DELETE, or all?]
|
||||
- **FR-009**: Route generation MUST handle [NEEDS CLARIFICATION: what level of route complexity? simple paths, parameters, wildcards?]
|
||||
|
||||
### Key Entities *(include if feature involves data)*
|
||||
- **Route Definition**: Represents a route annotation containing path, HTTP method, and handler information
|
||||
- **Route Generator**: Component responsible for transforming route annotations into executable code
|
||||
- **Route Parser**: Component that extracts route information from AST structures
|
||||
- **Route Template**: Code generation template that produces the final route handler code
|
||||
|
||||
---
|
||||
|
||||
## 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*
|
||||
|
||||
- [x] User description parsed
|
||||
- [x] Key concepts extracted
|
||||
- [x] Ambiguities marked
|
||||
- [x] User scenarios defined
|
||||
- [x] Requirements generated
|
||||
- [x] Entities identified
|
||||
- [ ] Review checklist passed
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user