eslint-plugin-traceability 1.8.0 → 1.8.2

package/docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md

@@ -1,236 +0,0 @@
-# 010.3-DEV-MIGRATE-TO-IMPLEMENTS: Recommend @implements and Auto-fix Migration
-
-## Release Goal
-
-_Release 0.1 Enhancement: Provide optional migration tooling and recommendations to convert from @story/@req annotations to the new @implements format_
-
-This story provides optional warnings and ESLint auto-fix capabilities to help teams migrate from `@story` + `@req` annotations to the new `@implements` format. It encourages adoption of the clearer, more explicit `@implements` syntax while maintaining full support for both formats, with configurable enforcement levels for teams that want to standardize on `@implements`.
-
-## How This Story Contributes
-
-This story enhances the "Fix Issues" journey phase by providing automated tools to migrate from legacy annotations to the new format. It reduces manual migration effort and ensures codebases can adopt the improved `@implements` syntax with minimal friction, while deprecation warnings guide teams toward best practices.
-
-## User Story
-
-**Format**: So that I can easily migrate from `@story`/`@req` annotations to the new `@implements` format, as a Developer or Team Lead, I want optional warnings with auto-fix capabilities that automatically convert my annotations.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed after `@implements` support is implemented (depends on 010.2)
-- **Negotiable**: Recommendation enforcement level and warning severity can be adjusted
-- **Valuable**: Reduces migration friction and guides teams toward best practices
-- **Estimable**: Scope is clear - add optional warnings and auto-fix transformation
-- **Small**: Can be completed within a single iteration/sprint
-- **Testable**: Auto-fix transformation can be thoroughly tested with various annotation patterns
-
-## Acceptance Criteria
-
-Use checkbox format for clear completion tracking:
-
-- [x] **Optional Warning**: Emit configurable warning/recommendation when `@story` + `@req` annotations are detected (default: off)
-- [x] **Auto-fix Support**: Provide ESLint auto-fix that converts `@story` + `@req` to `@implements`
-- [x] **Single Story Conversion**: Auto-fix converts single `@story` with multiple `@req` to one `@implements` line
-- [x] **Multi-story Detection**: Detect when function has `@req` that don't match `@story` and warn (cannot auto-fix)
-- [x] **Preserve Order**: Auto-fix maintains relative position of annotations (after description, before params)
-- [x] **Configurable Enforcement**: Allow configuration of recommendation level (off, warn, error) - default off to maintain backward compatibility
-- [x] **Both Formats Valid**: Ensure `@story`/`@req` continues to pass all validation when recommendation is disabled
-- [x] **Quality Standards**: Auto-fix produces valid `@implements` annotations that pass validation
-- [x] **Documentation**: Migration guide with auto-fix examples and opt-in configuration
-
-## Requirements (Current Implementation or To Be Implemented)
-
-Document specific technical requirements using the format:
-
-- **REQ-OPTIONAL-WARNING**: Emit configurable recommendation warning for `@story` + `@req` usage (default: disabled)
-- **REQ-AUTO-FIX**: Implement auto-fix to transform `@story` + `@req` to `@implements`
-- **REQ-SINGLE-STORY-FIX**: Auto-fix single-story annotations (one `@story`, multiple `@req`)
-- **REQ-MULTI-STORY-DETECT**: Detect and warn about multi-story patterns that cannot be auto-fixed
-- **REQ-PRESERVE-FORMAT**: Maintain JSDoc structure and annotation order during conversion
-- **REQ-CONFIG-SEVERITY**: Support configurable recommendation severity (off/warn/error), default off
-- **REQ-BACKWARD-COMPAT-VALIDATION**: Ensure `@story`/`@req` continues to validate correctly regardless of recommendation setting
-- **REQ-VALID-OUTPUT**: Auto-fix output passes all `@implements` validation rules
-
-## Dependencies
-
-List other stories this story depends on, using numbered story references:
-
-- 001.0-DEV-PLUGIN-SETUP (requires plugin structure foundation)
-- 002.0-DEV-ESLINT-CONFIG (requires configuration system)
-- 003.0-DEV-FUNCTION-ANNOTATIONS (deprecates function annotation pattern)
-- 008.0-DEV-AUTO-FIX (uses auto-fix infrastructure)
-- 010.2-DEV-MULTI-STORY-SUPPORT (requires `@implements` annotation support)
-
-**Dependency Rules**:
-
-- Story numbers MUST be greater than all dependency story numbers
-- Dependencies should be from in-scope stories when possible
-- Cross-release dependencies should be clearly justified
-- No circular dependencies allowed
-
-## Implementation Notes (Optional)
-
-Additional context for developers:
-
-**Development Resources**:
-
-- See [Auto-fix Guide](../custom-rules-development-guide.md#auto-fix) for ESLint auto-fix patterns
-- Review story 008.0-DEV-AUTO-FIX for auto-fix infrastructure
-- See [Testing Guide](../jest-testing-guide.md) for auto-fix testing patterns
-
-**Implementation Details**:
-
-- Add new rule `prefer-implements-annotation` (or similar name indicating preference, not requirement)
-- Rule is **disabled by default** to maintain backward compatibility
-- When enabled, detect `@story` + `@req` pattern and emit configurable recommendation
-- Implement auto-fix that:
-  1. Extracts `@story` path
-  2. Collects all `@req` IDs
-  3. Removes `@story` and `@req` lines
-  4. Inserts `@implements <story-path> <REQ-1> <REQ-2> ...` line
-  5. Maintains position after description, before `@param`
-- Handle edge cases:
-  - Multiple `@story` annotations (warn, cannot auto-fix)
-  - `@req` without matching `@story` (warn, cannot auto-fix)
-  - Mixed `@story`/`@req` and `@implements` (warn, manual migration needed)
-- Support configuration option to control recommendation severity (default: "off")
-- Ensure `@story`/`@req` validation continues to work correctly when rule is disabled
-- Ensure auto-fixed code passes all validation rules
-
-**Auto-fix Transformation Examples**:
-
-Before (legacy format):
-
-```javascript
-/**
- * Calculate age in days since publish date.
- * @param {string} publishDate - ISO date string
- * @returns {number} Days since publish
- * @story prompts/002.0-DEV-FETCH-AVAILABLE-VERSIONS.md
- * @req REQ-AGE-CALC
- */
-export function calculateAgeInDays(publishDate) {
-```
-
-After (auto-fixed to @implements):
-
-```javascript
-/**
- * Calculate age in days since publish date.
- * @implements prompts/002.0-DEV-FETCH-AVAILABLE-VERSIONS.md REQ-AGE-CALC
- * @param {string} publishDate - ISO date string
- * @returns {number} Days since publish
- */
-export function calculateAgeInDays(publishDate) {
-```
-
-Before (multiple requirements):
-
-```javascript
-/**
- * Filter packages by age threshold.
- * @story prompts/005.0-DEV-CONFIGURABLE-AGE-THRESHOLD.md
- * @req REQ-CLI-FLAG
- * @req REQ-CONFIG-FILE
- * @req REQ-VALIDATION
- * @param {Array} rows - Package rows
- * @returns {Array} Filtered rows
- */
-export function filterByAge(rows) {
-```
-
-After (auto-fixed):
-
-```javascript
-/**
- * Filter packages by age threshold.
- * @implements prompts/005.0-DEV-CONFIGURABLE-AGE-THRESHOLD.md REQ-CLI-FLAG REQ-CONFIG-FILE REQ-VALIDATION
- * @param {Array} rows - Package rows
- * @returns {Array} Filtered rows
- */
-export function filterByAge(rows) {
-```
-
-Cannot auto-fix (manual migration needed):
-
-```javascript
-/**
- * Integration function with multiple stories.
- * @story prompts/003.0-DEV-IDENTIFY-OUTDATED.md
- * @req REQ-AGE-THRESHOLD
- * @req REQ-AUDIT-CHECK  // From different story!
- * @param {Array} rows
- */
-export function applyFilters(rows) {
-```
-
-Warning emitted:
-
-```
-Multiple stories detected. Cannot auto-fix. Manually migrate to @implements format:
-  @implements prompts/003.0-DEV-IDENTIFY-OUTDATED.md REQ-AGE-THRESHOLD
-  @implements prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-AUDIT-CHECK
-```
-
-**Configuration Options**:
-
-```javascript
-// eslint.config.js - Default (both formats accepted)
-{
-  "traceability/prefer-implements-annotation": "off" // Default - no warnings
-}
-
-// eslint.config.js - Recommend migration (warnings only)
-{
-  "traceability/prefer-implements-annotation": "warn" // Suggest using @implements
-}
-
-// eslint.config.js - Enforce new format (errors)
-{
-  "traceability/prefer-implements-annotation": "error" // Require @implements
-}
-```
-
-**Recommendation Warning Messages**:
-
-```typescript
-messages: {
-  preferImplements: "Consider using @implements instead of @story + @req for clearer traceability. Run ESLint with --fix to auto-convert.",
-  cannotAutoFix: "Cannot auto-fix: {{reason}}. Manual migration to @implements required.",
-  multiStoryDetected: "Multiple @story annotations detected. Manually convert to separate @implements lines."
-}
-```
-
-**Testing Strategy**:
-
-- Unit tests for auto-fix transformation with various annotation patterns
-- Tests for single-story, multi-requirement scenarios
-- Tests for edge cases that cannot be auto-fixed
-- Integration tests verifying auto-fixed code passes validation
-- Tests for preserving JSDoc structure and formatting
-- Configuration tests for recommendation severity levels (off/warn/error)
-- Tests verifying `@story`/`@req` validation works correctly when rule is disabled (default)
-- Tests verifying both formats coexist without conflicts
-
-**Migration Timeline** (Planned):
-
-1. **Phase 1 (Release 0.1)**: Add optional recommendation rule (default: off) with auto-fix support
-2. **Phase 2 (Release 0.2+)**: Enable recommendation by default (warn level) to guide new adoption
-3. **Phase 3 (Future Release)**: Consider deprecation warnings (teams can opt-in to error level)
-4. **Phase 4 (Future Major Release)**: Evaluate removing `@story`/`@req` support based on ecosystem adoption
-
-Note: Both formats remain fully supported indefinitely. Teams control their own migration timeline via configuration.
-
-## Definition of Done
-
-- [x] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [x] Tests written and passing (auto-fix transformations, edge cases, configuration)
-- [x] Documentation updated (migration guide, auto-fix examples, opt-in configuration)
-- [ ] Auto-fix verified with dry-aged-deps codebase
-- [x] Rule disabled by default (backward compatibility confirmed)
-- [x] Recommendation warnings tested at different severity levels (off/warn/error)
-- [x] Both annotation formats validated correctly regardless of rule setting
-- [x] Cannot-auto-fix scenarios properly detected and reported
-- [x] Integration tested with 010.2-DEV-MULTI-STORY-SUPPORT
-
----

package/docs/stories/developer-story.map.md

@@ -1,120 +0,0 @@
-# Developer User Story Map - ESLint Plugin Traceability
-
-## Journey Steps (Columns)
-
-| **Setup Plugin**                                                                           | **Write Code**                                                              | **Validate Annotations**                                    | **Fix Issues**                                            | **Maintain Quality**                          |
-| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------- |
-| _Install and configure the ESLint plugin in their project to start enforcing traceability_ | _Write functions and code branches with proper @story and @req annotations_ | _Run linting to check that annotations exist and are valid_ | _Address any traceability violations found by the linter_ | _Keep annotations up-to-date as code evolves_ |
-| **Installation**                                                                           | **Function Annotations**                                                    | **Annotation Validation**                                   | **Error Resolution**                                      | **Ongoing Maintenance**                       |
-| **Configuration**                                                                          | **Branch Annotations**                                                      | **File Reference Validation**                               | **Quick Fixes**                                           | **Ongoing Maintenance**                       |
-
-## Personas
-
-- 🎯 **PRIMARY**: Developer - _A software developer who needs to maintain bidirectional traceability between code and requirements to ensure code quality and enable requirement validation through test execution_
-- 👥 **Team Lead** - _A technical lead who needs to ensure team compliance with traceability standards across the codebase_
-- 🔧 **QA Engineer** - _A quality assurance engineer who needs to validate that requirements are properly implemented and traceable through code_
-
----
-
-# User Story Map with Releases
-
-| **Release 0.1 (Core Validation)** (Planned) | **Setup Plugin**                | **Write Code**                 | **Validate Annotations**        | **Fix Issues**                  | **Maintain Quality**        |
-| ------------------------------------------- | ------------------------------- | ------------------------------ | ------------------------------- | ------------------------------- | --------------------------- |
-| **Plugin Foundation**                       | 001.0-DEV-PLUGIN-SETUP          | 003.0-DEV-FUNCTION-ANNOTATIONS | 005.0-DEV-ANNOTATION-VALIDATION | 007.0-DEV-ERROR-REPORTING       | 009.0-DEV-MAINTENANCE-TOOLS |
-| **Basic Rules**                             | 002.0-DEV-ESLINT-CONFIG         | 004.0-DEV-BRANCH-ANNOTATIONS   | 006.0-DEV-FILE-VALIDATION       | 008.0-DEV-AUTO-FIX              | 010.0-DEV-DEEP-VALIDATION   |
-| **Enhanced Configuration**                  | 010.1-DEV-CONFIGURABLE-PATTERNS | 010.2-DEV-MULTI-STORY-SUPPORT  | -                               | 010.3-DEV-MIGRATE-TO-IMPLEMENTS | -                           |
-
-| **Release 0.2 (Enhanced Features)** (Future) | **Setup Plugin**            | **Write Code**               | **Validate Annotations**     | **Fix Issues**              | **Maintain Quality**      |
-| -------------------------------------------- | --------------------------- | ---------------------------- | ---------------------------- | --------------------------- | ------------------------- |
-| **Advanced Validation**                      | 011.0-DEV-IDE-INTEGRATION   | 013.0-DEV-SMART-SUGGESTIONS  | 015.0-DEV-REAL-TIME-FEEDBACK | 016.0-DEV-BULK-FIXES        | 018.0-DEV-QUALITY-METRICS |
-| **Developer Experience**                     | 012.0-DEV-PROJECT-TEMPLATES | 014.0-DEV-ANNOTATION-HELPERS | -                            | 017.0-DEV-GUIDED-RESOLUTION | 019.0-DEV-DASHBOARD       |
-|                                              | -                           | -                            | -                            | -                           | -                         |
-
----
-
-## Release Details
-
-### Release 0.1: Core Validation (Planned)
-
-**Goal**: Provide essential ESLint rules that enforce @story and @req annotations on functions and code branches, with validation that referenced files exist and contain the referenced requirements.
-**Success Metric**: Developers can run ESLint and receive clear feedback when traceability annotations are missing, incorrect, or point to non-existent files/requirements.
-**Scope**: Basic plugin setup, core validation rules, error reporting, and simple auto-fix capabilities for common issues.
-
-**Stories by Category:**
-
-- **Plugin Foundation**: 001.0-DEV-PLUGIN-SETUP (ESLint plugin structure), 002.0-DEV-ESLINT-CONFIG (configuration setup)
-- **Core Annotations**: 003.0-DEV-FUNCTION-ANNOTATIONS (validate @story/@req on functions), 004.0-DEV-BRANCH-ANNOTATIONS (validate annotations on branches)
-- **Validation Logic**: 005.0-DEV-ANNOTATION-VALIDATION (check annotation format), 006.0-DEV-FILE-VALIDATION (verify story files exist)
-- **Developer Support**: 007.0-DEV-ERROR-REPORTING (clear error messages), 008.0-DEV-AUTO-FIX (simple auto-fixes)
-- **Ongoing Maintenance**: 009.0-DEV-MAINTENANCE-TOOLS (update helpers)
-- **Deep Validation**: 010.0-DEV-DEEP-VALIDATION (requirement content validation)
-- **Enhanced Configuration**: 010.1-DEV-CONFIGURABLE-PATTERNS (custom format patterns), 010.2-DEV-MULTI-STORY-SUPPORT (@implements annotation for multi-story requirements), 010.3-DEV-MIGRATE-TO-IMPLEMENTS (deprecate legacy format with auto-fix migration)
-
-**Total**: 13 stories covering complete basic traceability enforcement workflow with configuration flexibility and migration tooling
-
-### Release 0.2: Enhanced Features (Future)
-
-**Goal**: Enhance developer experience with IDE integration, intelligent suggestions, advanced validation, and quality metrics to make traceability maintenance effortless and valuable.
-**Success Metric**: Developers proactively maintain traceability annotations with minimal friction, and teams can track and improve their traceability coverage over time.
-**Scope**: IDE extensions, smart auto-completion, deep requirement validation, bulk fixing tools, and traceability quality dashboards.
-
-**Stories by Category:**
-
-- **Developer Integration**: 011.0-DEV-IDE-INTEGRATION (VS Code extension), 012.0-DEV-PROJECT-TEMPLATES (starter templates)
-- **Smart Features**: 013.0-DEV-SMART-SUGGESTIONS (intelligent annotation suggestions), 014.0-DEV-ANNOTATION-HELPERS (auto-completion)
-- **Advanced Validation**: 015.0-DEV-REAL-TIME-FEEDBACK (live validation)
-- **Productivity Tools**: 016.0-DEV-BULK-FIXES (mass update tools), 017.0-DEV-GUIDED-RESOLUTION (fix wizards)
-- **Quality Management**: 018.0-DEV-QUALITY-METRICS (coverage tracking), 019.0-DEV-DASHBOARD (team dashboard)
-
-**Total**: 9 stories covering advanced developer experience and team quality management
-
----
-
-## Key Questions for Developer
-
-### **Release 0.1 Questions:**
-
-**Plugin Foundation:**
-
-- How easy is it to add the ESLint plugin to an existing project without disrupting current workflow?
-- What configuration options are needed to accommodate different project structures and story file locations?
-- How should the plugin handle different story file naming conventions (.story.md vs other formats)?
-
-**Core Annotations:**
-
-- What types of functions should require @story annotations (all functions, only exported functions, only functions above certain complexity)?
-- Which code branches need traceability annotations (if/else, try/catch, switch cases, loops)?
-- How should the plugin handle generated code or third-party code that can't have annotations?
-- How should integration functions reference requirements from multiple stories while maintaining clear traceability?
-
-**Validation Logic:**
-
-- How strict should annotation format validation be (exact format vs flexible parsing)?
-- Should the plugin validate that @req annotations point to actual requirements within the referenced story file?
-- How should the plugin handle story files that exist but are empty or malformed?
-
-**Developer Support:**
-
-- What information should be included in error messages to help developers fix annotation issues quickly?
-- Which annotation errors can be auto-fixed safely (missing @story template, broken file paths)?
-- How should the plugin integrate with existing ESLint configurations and other rules?
-
-### **Release 0.2 Questions:**
-
-**Developer Integration:**
-
-- What IDE features would make maintaining traceability annotations feel natural and effortless?
-- How can the plugin provide intelligent suggestions for @story references based on file context?
-- What project templates would help new teams adopt traceability practices from the start?
-
-**Advanced Validation:**
-
-- Should the plugin parse story files to validate that referenced requirements actually exist in the content?
-- How can the plugin detect when story files are updated but code annotations become stale?
-- What real-time feedback mechanisms would help developers maintain traceability as they code?
-
-**Quality Management:**
-
-- What metrics help teams understand and improve their traceability coverage?
-- How can teams track traceability quality trends over time?
-- What visualization tools would help identify areas of the codebase with poor traceability?