eslint-plugin-traceability 1.8.0 → 1.8.2

package/docs/stories/010.0-DEV-DEEP-VALIDATION.story.md

@@ -1,124 +0,0 @@
-# 010.0-DEV-DEEP-VALIDATION: Requirement Content Validation
-
-## Release Goal
-
-**Release 0.1: Core Validation** - 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.
-
-This story completes the validation framework by ensuring that @req annotations not only point to existing story files, but that the referenced requirements actually exist within those files. This provides complete end-to-end traceability validation from code annotations to actual requirement content.
-
-## How This Story Contributes
-
-While basic file validation (006.0) ensures story files exist, deep validation goes further to verify that the specific requirements referenced in @req annotations are actually present in the story files. This prevents broken traceability links where annotations point to valid files but non-existent requirements, ensuring the traceability system maintains integrity as requirements evolve.
-
-This story completes the "Maintain Quality" journey phase and Release 0.1 by providing the most comprehensive validation possible, ensuring annotations remain meaningful and accurate.
-
-## User Story
-
-**Format**: So that I can trust that @req annotations point to actual requirements and not just valid files, as a Developer, I want the ESLint plugin to validate that referenced requirements exist within the target story files.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed using existing file validation and annotation parsing logic
-- **Negotiable**: The specific requirement matching strategies and formats can be refined during implementation
-- **Valuable**: Delivers clear value by ensuring annotation accuracy and preventing broken traceability
-- **Estimable**: Scope is well-defined - parse story files to validate requirement existence
-- **Small**: Focused on requirement content validation rather than broader file analysis
-- **Testable**: Requirement validation can be verified through story file parsing and matching tests
-
-## Acceptance Criteria
-
-- [x] **Core Functionality**: Plugin validates that @req annotations reference requirements that actually exist in the target story files
-- [ ] **Quality Standards**: Validation handles various requirement formats and story file structures
-- [ ] **Integration**: Works with existing file validation and annotation parsing logic
-- [x] **User Experience**: Provides clear error messages when requirements are not found in story files
-- [ ] **Error Handling**: Gracefully handles malformed story files, missing sections, or parsing errors
-- [ ] **Documentation**: Requirement validation behavior is documented with examples of supported formats
-
-## Requirements (Current Implementation or To Be Implemented)
-
-- **REQ-DEEP-PARSE**: Parse story file content to identify available requirements
-- **REQ-DEEP-MATCH**: Match @req annotation references against actual requirements in story files
-- **REQ-DEEP-FORMAT**: Support multiple requirement formats (REQ-XXX-YYY, bullet points, numbered lists)
-- **REQ-DEEP-SECTION**: Handle requirements in different story file sections (Requirements, Acceptance Criteria, etc.)
-- **REQ-DEEP-CACHE**: Cache parsed story file content to avoid re-parsing on every validation
-- **REQ-DEEP-ERROR**: Provide specific error messages when requirements are not found in story files
-
-## Dependencies
-
-- 005.0-DEV-ANNOTATION-VALIDATION (deep validation needs annotation format parsing)
-- 006.0-DEV-FILE-VALIDATION (deep validation builds on file existence validation)
-- 007.0-DEV-ERROR-REPORTING (deep validation needs clear error reporting for requirement mismatches)
-
-**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)
-
-**Development Resources**:
-
-- See [Custom ESLint Rules Development Guide](../custom-rules-development-guide.md) for implementation patterns
-- Review [The Context Object](../custom-rules-development-guide.md#the-context-object) for accessing file information
-- See [Best Practices](../custom-rules-development-guide.md#best-practices) for performance optimization
-
-**Technical Considerations**:
-
-- Implement robust markdown parsing to extract requirements from story files
-- Support multiple requirement identification patterns (REQ-XXX-YYY, numbered bullets, etc.)
-- Consider performance implications of parsing story files during linting
-- Provide caching mechanisms to avoid repeated file parsing (cache at plugin level, not per rule execution)
-- Use lazy loading - only parse story files when their requirements are referenced
-- Store parsed requirement data with file modification timestamps for cache invalidation
-
-**Key Guide Sections**:
-
-- [The Context Object](../custom-rules-development-guide.md#the-context-object) - Using context.cwd and context.filename
-- [Best Practices](../custom-rules-development-guide.md#best-practices) - Performance and caching strategies
-- [Reporting Problems](../custom-rules-development-guide.md#reporting-problems) - Clear error messages for missing requirements
-
-**Integration Points**:
-
-- Extend existing file validation logic to include content parsing
-- Integrate with annotation parsing to extract requirement references
-- Work with error reporting system to provide detailed mismatch information
-- Support various story file formats and structures
-
-**Requirement Identification Strategies**:
-
-- **Explicit Requirements**: Lines starting with "REQ-" or "\*\*REQ-"
-- **Acceptance Criteria**: Checkbox items in acceptance criteria sections
-- **Numbered Requirements**: Numbered list items in requirements sections
-- **Custom Patterns**: Configurable regex patterns for project-specific formats
-
-**Content Parsing Approach**:
-
-- Parse markdown structure to identify sections
-- Extract requirement identifiers using multiple strategies
-- Build searchable index of requirements per story file
-- Cache parsing results with file modification time tracking
-
-**Performance Considerations**:
-
-- Parse story files only when @req annotations reference them
-- Cache parsed content with file modification timestamps
-- Use incremental parsing for large story files
-- Provide configuration options to disable deep validation for performance
-
-**Testing Strategy**:
-
-- Unit tests for markdown parsing with various story file formats
-- Integration tests with real story files and annotation patterns
-- Performance tests with large story files and many annotations
-- Edge case testing with malformed markdown and unusual requirement formats
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing
-- [ ] Documentation updated
-- [ ] Deployed to appropriate environment
-- [ ] Stakeholder acceptance confirmed

package/docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md

@@ -1,149 +0,0 @@
-# 010.1-DEV-CONFIGURABLE-PATTERNS: Configurable Annotation Format Patterns
-
-## Release Goal
-
-_Release 0.1 Enhancement: Enable plugin adoption for projects with established documentation structures and naming conventions_
-
-This story extends the annotation format validation to support configurable patterns for story paths and requirement identifiers. It removes adoption barriers by allowing projects to customize validation patterns while maintaining format validation integrity.
-
-## How This Story Contributes
-
-This story enhances the "Setup Plugin" journey phase by enabling teams to integrate the plugin without restructuring their existing documentation. It provides configuration flexibility that respects diverse project conventions while maintaining the validation benefits of format checking.
-
-## User Story
-
-**Format**: So that I can use the traceability plugin without restructuring my existing documentation, as a Developer or Team Lead, I want to configure custom patterns for @story paths and @req identifiers that match my project's established conventions.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed after core format validation (depends on 005.0)
-- **Negotiable**: Pattern configuration approach and validation strictness can be refined
-- **Valuable**: Removes adoption barriers for projects with established conventions
-- **Estimable**: Scope is clear - add configuration options to existing validation rule
-- **Small**: Can be completed within a single iteration/sprint
-- **Testable**: Configuration and pattern validation can be thoroughly tested
-
-## Acceptance Criteria
-
-Use checkbox format for clear completion tracking:
-
-- [x] **Core Functionality**: Add `storyPathPattern` and `requirementIdPattern` options to `valid-annotation-format` rule
-- [x] **Backward Compatibility**: Default to current hardcoded patterns when `storyPathPattern` and `requirementIdPattern` options are not configured
-- [x] **Pattern Validation**: Validate that custom `storyPathPattern` and `requirementIdPattern` values are valid regular expressions
-- [x] **Error Messages**: Support optional `storyPathExample` and `requirementIdExample` strings for better error messages with custom patterns
-- [x] **Quality Standards**: Follows ESLint rule schema and configuration best practices for `storyPathPattern`, `requirementIdPattern`, `storyPathExample`, and `requirementIdExample`
-- [x] **Integration**: Works seamlessly with existing `valid-story-reference` rule configuration (including `storyDirectories`)
-- [x] **Documentation**: Clear examples of custom pattern configuration for different use cases using `storyPathPattern`, `requirementIdPattern`, `storyPathExample`, and `requirementIdExample`
-
-## Requirements (Current Implementation or To Be Implemented)
-
-Document specific technical requirements using the format:
-
-- **REQ-PATTERN-CONFIG**: Support configuration of custom story path and requirement ID patterns
-- **REQ-REGEX-VALIDATION**: Validate that configured patterns are valid regular expressions
-- **REQ-BACKWARD-COMPAT**: Maintain current behavior when no custom patterns configured
-- **REQ-EXAMPLE-MESSAGES**: Support optional example strings in error messages
-- **REQ-SCHEMA-VALIDATION**: Use JSON Schema to validate configuration options
-- **REQ-CONSISTENCY**: Align with `storyDirectories` configuration in `valid-story-reference` rule
-- **REQ-PATTERN-TESTING**: Provide test utilities for validating custom patterns
-
-## 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)
-- 005.0-DEV-ANNOTATION-VALIDATION (extends format validation patterns)
-
-**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 [Rule Options and Schema](../custom-rules-development-guide.md#rule-options-and-schema) for configuration patterns
-- Review existing `valid-story-reference` rule for `storyDirectories` configuration approach
-- See [Testing Guide](../jest-testing-guide.md) for configuration testing patterns
-
-**Implementation Details**:
-
-- Add schema properties to `valid-annotation-format` rule meta
-- Extract hardcoded patterns to configurable options with defaults
-- Validate regex patterns at configuration time with clear error messages
-- Support both string patterns (converted to regex) and regex patterns
-- Coordinate with `storyDirectories` configuration for consistency
-- Update error message templates to use configured examples when provided
-- Ensure auto-fix behavior respects custom patterns
-
-**Configuration Schema**:
-
-```typescript
-interface RuleOptions {
-  storyPathPattern?: string; // Regex pattern for story paths
-  requirementIdPattern?: string; // Regex pattern for requirement IDs
-  storyPathExample?: string; // Example for error messages
-  requirementIdExample?: string; // Example for error messages
-}
-```
-
-**Use Case Examples**:
-
-Different directory structure:
-
-```javascript
-{
-  "traceability/valid-annotation-format": ["warn", {
-    "storyPathPattern": "^prompts/[0-9]+\\.[0-9]+-DEV-[\\w-]+\\.md$",
-    "storyPathExample": "prompts/005.0-DEV-EXAMPLE.md"
-  }]
-}
-```
-
-Different requirement prefix:
-
-```javascript
-{
-  "traceability/valid-annotation-format": ["warn", {
-    "requirementIdPattern": "^(REQ|SPEC|FR)-[A-Z0-9-]+$",
-    "requirementIdExample": "SPEC-EXAMPLE or REQ-EXAMPLE"
-  }]
-}
-```
-
-Custom story file format:
-
-```javascript
-{
-  "traceability/valid-annotation-format": ["warn", {
-    "storyPathPattern": "^specifications/[A-Z]+-[0-9]+\\.markdown$",
-    "storyPathExample": "specifications/FEAT-123.markdown"
-  }]
-}
-```
-
-**Edge Cases to Handle**:
-
-- Invalid regex patterns in configuration
-- Empty or whitespace-only patterns
-- Patterns that would never match valid annotations
-- Interaction with auto-fix behavior
-- Error message clarity when using custom examples
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [x] Tests written and passing (custom pattern configuration, validation, error messages)
-- [x] Documentation updated (configuration examples, migration guide for custom patterns)
-- [ ] Schema validation tested with invalid configurations
-- [ ] Integration tested with `valid-story-reference` configuration
-- [ ] GitHub issue #1 resolved and closed
-
----

package/docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md

@@ -1,216 +0,0 @@
-# 010.2-DEV-MULTI-STORY-SUPPORT: Multi-Story Requirements with @implements
-
-## Release Goal
-
-_Release 0.1 Enhancement: Enable traceability validation for integration functions that implement requirements from multiple stories_
-
-This story introduces the `@implements` annotation to support functions that combine functionality from multiple stories, addressing the limitation where integration code cannot properly reference requirements from different source stories. This removes false-positive linting errors and enables complete traceability for real-world codebases.
-
-## How This Story Contributes
-
-This story enhances the "Write Code" journey phase by enabling proper annotation of integration functions that naturally combine multiple stories. It removes the forced choice between suppressing linting errors or losing traceability information, ensuring validation works correctly for both simple single-story functions and complex multi-story integration code.
-
-## User Story
-
-**Format**: So that I can properly trace integration functions that combine multiple stories without linting errors, as a Developer, I want to use `@implements` annotations that explicitly map requirements to their source stories.
-
-**INVEST Criteria Compliance**:
-
-- **Independent**: Can be developed after requirement validation (depends on 010.0)
-- **Negotiable**: Annotation format and validation behavior can be refined during implementation
-- **Valuable**: Enables traceability validation for integration code (currently blocked by false positives)
-- **Estimable**: Scope is clear - add new annotation parser and extend validation logic
-- **Small**: Can be completed within a single iteration/sprint
-- **Testable**: Multi-story validation can be thoroughly tested with various annotation patterns
-
-## Acceptance Criteria
-
-Use checkbox format for clear completion tracking:
-
-- [x] **Core Functionality**: Support `@implements story-path REQ-ID1 REQ-ID2 ...` annotation format
-- [x] **Validation**: Validate each requirement exists in its specified story file
-- [x] **Backward Compatibility**: Existing `@story` + `@req` annotations continue working unchanged
-- [x] **Mixed Usage**: Support both annotation styles in same codebase and even same file
-- [x] **Error Messages**: Clearly indicate which story was checked when requirement validation fails
-- [x] **Requirement Scoping**: Requirement IDs only need to be unique within their story file
-- [x] **Quality Standards**: Follows ESLint rule development best practices
-- [x] **Documentation**: Clear examples of both annotation styles and migration guidance
-
-## Requirements (Current Implementation or To Be Implemented)
-
-Document specific technical requirements using the format:
-
-- **REQ-IMPLEMENTS-PARSE**: Parse `@implements` annotation format extracting story path and requirement IDs
-- **REQ-IMPLEMENTS-VALIDATE**: Validate each requirement against its specified story file
-- **REQ-REQUIRE-ACCEPTS-IMPLEMENTS**: Update `require-story-annotation` and `require-req-annotation` rules to accept `@implements` as satisfying story and requirement annotations
-- **REQ-BACKWARD-COMPAT**: Maintain full compatibility with existing `@story` + `@req` annotations
-- **REQ-MIXED-SUPPORT**: Support both annotation styles in same function/file
-- **REQ-ERROR-CONTEXT**: Include story path in error messages for requirement validation failures
-- **REQ-SCOPED-IDS**: Enable requirement ID reuse across different story files
-- **REQ-FORMAT-VALIDATION**: Validate `@implements` line format (story path followed by requirement IDs)
-
-## 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 (extends function annotation validation)
-- 005.0-DEV-ANNOTATION-VALIDATION (extends annotation format validation)
-- 006.0-DEV-FILE-VALIDATION (uses story file validation)
-- 010.0-DEV-DEEP-VALIDATION (uses requirement existence validation)
-
-**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 [Custom ESLint Rules Development Guide](../custom-rules-development-guide.md) for implementation patterns
-- Review `valid-req-reference` rule for requirement validation logic
-- See [Testing Guide](../jest-testing-guide.md) for multi-scenario testing patterns
-
-**Implementation Details**:
-
-- Extend `valid-annotation-format` rule to recognize `@implements` annotations
-- Update `require-story-annotation` rule to accept `@implements` as satisfying the story annotation requirement (REQ-REQUIRE-ACCEPTS-IMPLEMENTS)
-- Update `require-req-annotation` rule to accept `@implements` as satisfying the requirement annotation (REQ-REQUIRE-ACCEPTS-IMPLEMENTS)
-- Extend `valid-req-reference` rule to validate `@implements` requirements
-- Parse `@implements` lines: first token is story path, remaining tokens are requirement IDs
-- For backward compatibility, existing `@story` + `@req` parsing remains unchanged
-- Support mixed usage: function can have both `@story`/`@req` and `@implements` annotations
-- Each requirement in `@implements` is validated against its specified story file
-- Update error messages to include which story was checked
-- Requirement ID format validation applies to both annotation styles
-
-**Annotation Format**:
-
-New `@implements` format:
-
-```javascript
-/**
- * Apply age and security filters to rows.
- * @implements prompts/003.0-DEV-IDENTIFY-OUTDATED.md REQ-AGE-THRESHOLD REQ-OUTPUT
- * @implements prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-AUDIT-CHECK REQ-SAFE-ONLY
- * @param {Array} rows - Array of package data
- * @returns {Promise<Object>} Filtered results
- */
-export async function applyFilters(rows, options) {
-```
-
-Legacy `@story` + `@req` format (still supported):
-
-```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) {
-```
-
-Mixed usage (both styles in same function):
-
-```javascript
-/**
- * Complex integration function.
- * @story prompts/001.0-DEV-PRIMARY-STORY.md
- * @req REQ-PRIMARY-FUNCTION
- * @implements prompts/002.0-DEV-SECONDARY-STORY.md REQ-INTEGRATION-LOGIC
- */
-export function complexFunction() {
-```
-
-**Parsing Logic**:
-
-```typescript
-// Detect annotation type
-function parseImplementsLine(line: string): {
-  storyPath: string;
-  reqIds: string[];
-} | null {
-  const trimmed = line.trim();
-  if (!trimmed.startsWith("@implements")) return null;
-
-  const tokens = trimmed.split(/\s+/).slice(1); // Remove '@implements'
-  if (tokens.length < 2) return null; // Need story path + at least one requirement
-
-  return {
-    storyPath: tokens[0],
-    reqIds: tokens.slice(1),
-  };
-}
-
-// Validation logic
-function validateImplementsAnnotation(opts: {
-  storyPath: string;
-  reqIds: string[];
-  context: any;
-  reqCache: Map<string, Set<string>>;
-}): void {
-  const { storyPath, reqIds, context, reqCache } = opts;
-
-  // Resolve and load story file requirements
-  const requirements = loadAndCacheRequirements(storyPath, reqCache);
-
-  // Validate each requirement exists
-  for (const reqId of reqIds) {
-    if (!requirements.has(reqId)) {
-      context.report({
-        messageId: "reqMissing",
-        data: { reqId, storyPath },
-      });
-    }
-  }
-}
-```
-
-**Error Message Updates**:
-
-```typescript
-// Enhanced error messages showing which story was checked
-messages: {
-  reqMissing: "Requirement '{{reqId}}' not found in '{{storyPath}}'",
-  invalidImplementsFormat: "Invalid @implements format. Expected: @implements <story-path> <REQ-ID> [<REQ-ID>...]",
-  noRequirementsSpecified: "@implements annotation requires at least one requirement ID after story path"
-}
-```
-
-**Benefits of @implements**:
-
-1. **Explicit Story Mapping**: Each requirement clearly states its source story
-2. **Scoped Requirement IDs**: REQ-PARSE can exist in multiple stories without conflict
-3. **Grouped by Story**: All requirements from one story listed together
-4. **Reduced Duplication**: Story path appears once per story, not per requirement
-5. **Migration Friendly**: Can adopt gradually without breaking existing code
-6. **Natural Semantics**: "implements requirements from story" is intuitive
-
-**Migration Strategy**:
-
-1. Both annotation styles work simultaneously (no forced migration)
-2. Single-story code can continue using `@story` + `@req`
-3. Multi-story code should migrate to `@implements` to fix validation
-4. Teams can choose one style for consistency or use both as needed
-5. Auto-fix could offer conversion from `@story`/`@req` to `@implements`
-
-## Definition of Done
-
-- [x] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Tests written and passing (single-story, multi-story, mixed usage)
-- [x] Documentation updated (`@implements` format, examples, migration guide)
-- [ ] Backward compatibility verified with existing test suite
-- [ ] Error messages tested for both annotation styles
-- [ ] Integration tested with dry-aged-deps codebase
-- [ ] ADR 010 referenced and decision documented
-
----