eslint-plugin-traceability 1.5.1 → 1.6.0

package/README.md

@@ -55,6 +55,8 @@ module.exports = [
 - `traceability/valid-story-reference` Validates that `@story` references point to existing story files. ([Documentation](docs/rules/valid-story-reference.md))
 - `traceability/valid-req-reference` Validates that `@req` references point to existing requirement IDs. ([Documentation](docs/rules/valid-req-reference.md))
 
+Configuration options: For detailed per-rule options (such as scopes, branch types, and story directory settings), see the individual rule docs in `docs/rules/` and the consolidated [API Reference](user-docs/api-reference.md).
+
 For development and contribution guidelines, see docs/eslint-plugin-development-guide.md.
 
 ## Quick Start

package/lib/src/rules/helpers/require-story-helpers.d.ts

@@ -100,7 +100,9 @@ declare function shouldProcessNode(node: any, scope: string[], exportPriority?:
  * Report a missing @story annotation for a function-like node
  * Provides a suggestion to add the annotation.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing annotations with suggestion
+ * @req REQ-AUTOFIX-MISSING - Provide autofix for missing annotations while preserving suggestions
  * @param {Rule.RuleContext} context - ESLint rule context used to report
  * @param {any} sourceCode - ESLint sourceCode object
  * @param {any} node - AST node that is missing the annotation
@@ -111,7 +113,9 @@ declare function reportMissing(context: Rule.RuleContext, sourceCode: any, node:
  * Report a missing @story annotation for a method-like node
  * Provides a suggestion to update the method/interface with the annotation.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing method/interface annotations with suggestion
+ * @req REQ-AUTOFIX-MISSING - Provide autofix for missing method/interface annotations while preserving suggestions
  * @param {Rule.RuleContext} context - ESLint rule context to report
  * @param {any} sourceCode - ESLint sourceCode object
  * @param {any} node - AST node that is missing the annotation

package/lib/src/rules/helpers/require-story-helpers.js

@@ -238,7 +238,9 @@ function shouldProcessNode(node, scope, exportPriority = "all") {
  * Report a missing @story annotation for a function-like node
  * Provides a suggestion to add the annotation.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing annotations with suggestion
+ * @req REQ-AUTOFIX-MISSING - Provide autofix for missing annotations while preserving suggestions
  * @param {Rule.RuleContext} context - ESLint rule context used to report
  * @param {any} sourceCode - ESLint sourceCode object
  * @param {any} node - AST node that is missing the annotation
@@ -259,6 +261,7 @@ function reportMissing(context, sourceCode, node, passedTarget) {
             node: nameNode,
             messageId: "missingStory",
             data: { name },
+            fix: (0, require_story_core_1.createAddStoryFix)(resolvedTarget),
             suggest: [
                 {
                     desc: `Add JSDoc @story annotation for function '${name}', e.g., ${ANNOTATION}`,
@@ -275,7 +278,9 @@ function reportMissing(context, sourceCode, node, passedTarget) {
  * Report a missing @story annotation for a method-like node
  * Provides a suggestion to update the method/interface with the annotation.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing method/interface annotations with suggestion
+ * @req REQ-AUTOFIX-MISSING - Provide autofix for missing method/interface annotations while preserving suggestions
  * @param {Rule.RuleContext} context - ESLint rule context to report
  * @param {any} sourceCode - ESLint sourceCode object
  * @param {any} node - AST node that is missing the annotation
@@ -293,6 +298,7 @@ function reportMethod(context, sourceCode, node, passedTarget) {
             node: nameNode,
             messageId: "missingStory",
             data: { name },
+            fix: (0, require_story_core_1.createMethodFix)(resolvedTarget),
             suggest: [
                 {
                     desc: `Add JSDoc @story annotation for function '${name}', e.g., ${ANNOTATION}`,

package/lib/src/rules/require-branch-annotation.d.ts

@@ -1,9 +1,16 @@
-/****
- * Rule to enforce @story and @req annotations on significant code branches
+/**
+ * Rule to enforce @story and @req annotations on significant code branches.
+ *
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
- * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+ * @req REQ-BRANCH-DETECTION
+ * @req REQ-CONFIGURABLE-SCOPE
  */
 import type { Rule } from "eslint";
+/**
+ * ESLint rule definition for require-branch-annotation.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-BRANCH-DETECTION - Enforce @story/@req presence on configured branch types
+ * @req REQ-CONFIGURABLE-SCOPE - Respect configurable branchTypes option
+ */
 declare const rule: Rule.RuleModule;
 export default rule;

package/lib/src/rules/require-branch-annotation.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const branch_annotation_helpers_1 = require("../utils/branch-annotation-helpers");
+/**
+ * ESLint rule definition for require-branch-annotation.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-BRANCH-DETECTION - Enforce @story/@req presence on configured branch types
+ * @req REQ-CONFIGURABLE-SCOPE - Respect configurable branchTypes option
+ */
 const rule = {
     meta: {
         type: "problem",
@@ -28,12 +34,20 @@ const rule = {
     },
     /**
      * Create visitor for require-branch-annotation rule.
+     *
      * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-     * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
-     * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+     * @req REQ-BRANCH-DETECTION
+     * @req REQ-CONFIGURABLE-SCOPE
      */
     create(context) {
         const branchTypesOrListener = (0, branch_annotation_helpers_1.validateBranchTypes)(context);
+        /**
+         * Branch configuration guard: if validation returns a listener, use it directly
+         * instead of branch-type iteration.
+         *
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-CONFIGURABLE-SCOPE
+         */
         if (!Array.isArray(branchTypesOrListener)) {
             return branchTypesOrListener;
         }
@@ -44,8 +58,8 @@ const rule = {
             /**
              * Handler for a specific branch node type.
              * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-             * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
-             * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+             * @req REQ-BRANCH-DETECTION
+             * @req REQ-CONFIGURABLE-SCOPE
              */
             handlers[type] = function branchHandler(node) {
                 if (type === "SwitchCase" && node.test == null) {

package/lib/src/rules/require-story-annotation.d.ts

@@ -5,6 +5,7 @@
  * on functions and methods according to configured scope and export priority.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED
  */
 import type { Rule } from "eslint";
@@ -12,6 +13,7 @@ import type { Rule } from "eslint";
  * ESLint rule to require @story annotations on functions/methods.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED
  */
 declare const rule: Rule.RuleModule;

package/lib/src/rules/require-story-annotation.js

@@ -6,6 +6,7 @@ const require_story_helpers_1 = require("./helpers/require-story-helpers");
  * ESLint rule to require @story annotations on functions/methods.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED
  */
 const rule = {
@@ -16,6 +17,7 @@ const rule = {
             recommended: "error",
         },
         hasSuggestions: true,
+        fixable: "code",
         messages: {
             missingStory: "Missing @story annotation for function '{{name}}' (REQ-ANNOTATION-REQUIRED)",
         },
@@ -38,6 +40,7 @@ const rule = {
      * Create the rule visitor functions.
      *
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
      * @req REQ-CREATE-HOOK
      */
     create(context) {

package/lib/src/rules/valid-annotation-format.js

@@ -1,6 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const STORY_EXAMPLE_PATH = "docs/stories/005.0-DEV-EXAMPLE.story.md";
+/**
+ * Constant to represent the "tag not found" index when searching
+ * for @story or @req within a comment.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+const TAG_NOT_FOUND_INDEX = -1;
 /**
  * Normalize a raw comment line to make annotation parsing more robust.
  *
@@ -8,7 +17,9 @@ const STORY_EXAMPLE_PATH = "docs/stories/005.0-DEV-EXAMPLE.story.md";
  * later in the line, and supports common JSDoc styles such as leading "*".
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 function normalizeCommentLine(rawLine) {
     const trimmed = rawLine.trim();
@@ -31,7 +42,9 @@ function normalizeCommentLine(rawLine) {
  *   multiple lines will be collapsed before validation.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 function collapseAnnotationValue(value) {
     return value.replace(/\s+/g, "");
@@ -40,7 +53,9 @@ function collapseAnnotationValue(value) {
  * Build a detailed error message for invalid @story annotations.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 function buildStoryErrorMessage(kind, value) {
     if (kind === "missing") {
@@ -52,7 +67,9 @@ function buildStoryErrorMessage(kind, value) {
  * Build a detailed error message for invalid @req annotations.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 function buildReqErrorMessage(kind, value) {
     if (kind === "missing") {
@@ -60,12 +77,101 @@ function buildReqErrorMessage(kind, value) {
     }
     return `Invalid requirement ID "${value ?? ""}" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).`;
 }
+/**
+ * Attempt a minimal, safe auto-fix for common @story path suffix issues.
+ *
+ * Only handles:
+ *   - missing ".md"
+ *   - missing ".story.md"
+ * and skips any paths with traversal segments (e.g. "..").
+ *
+ * Returns the fixed path when safe, or null if no fix should be applied.
+ *
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+function getFixedStoryPath(original) {
+    if (original.includes("..")) {
+        return null;
+    }
+    if (/\.story\.md$/.test(original)) {
+        return null;
+    }
+    if (/\.story$/.test(original)) {
+        return `${original}.md`;
+    }
+    if (/\.md$/.test(original)) {
+        return original.replace(/\.md$/, ".story.md");
+    }
+    return `${original}.story.md`;
+}
+/**
+ * Report an invalid @story annotation without applying a fix.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+function reportInvalidStoryFormat(context, comment, collapsed) {
+    context.report({
+        node: comment,
+        messageId: "invalidStoryFormat",
+        data: { details: buildStoryErrorMessage("invalid", collapsed) },
+    });
+}
+/**
+ * Report an invalid @story annotation and attempt a minimal, safe auto-fix
+ * for common path suffix issues by locating and replacing the path text
+ * within the original comment.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
+    const sourceCode = context.getSourceCode();
+    const commentText = sourceCode.getText(comment);
+    const search = "@story";
+    const tagIndex = commentText.indexOf(search);
+    if (tagIndex === TAG_NOT_FOUND_INDEX) {
+        reportInvalidStoryFormat(context, comment, collapsed);
+        return;
+    }
+    const afterTagIndex = tagIndex + search.length;
+    const rest = commentText.slice(afterTagIndex);
+    const valueMatch = rest.match(/[^\S\r\n]*([^\r\n*]+)/);
+    if (!valueMatch || valueMatch.index === undefined) {
+        reportInvalidStoryFormat(context, comment, collapsed);
+        return;
+    }
+    const valueStartInComment = afterTagIndex +
+        valueMatch.index +
+        (valueMatch[0].length - valueMatch[1].length);
+    const valueEndInComment = valueStartInComment + valueMatch[1].length;
+    const start = comment.range[0];
+    const fixRange = [
+        start + valueStartInComment,
+        start + valueEndInComment,
+    ];
+    context.report({
+        node: comment,
+        messageId: "invalidStoryFormat",
+        data: { details: buildStoryErrorMessage("invalid", collapsed) },
+        fix(fixer) {
+            return fixer.replaceTextRange(fixRange, fixed);
+        },
+    });
+}
 /**
  * Validate a @story annotation value and report detailed errors when needed.
+ * Where safe and unambiguous, apply an automatic fix for missing suffixes.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 function validateStoryAnnotation(context, comment, rawValue) {
     const trimmed = rawValue.trim();
@@ -79,18 +185,25 @@ function validateStoryAnnotation(context, comment, rawValue) {
     }
     const collapsed = collapseAnnotationValue(trimmed);
     const pathPattern = /^docs\/stories\/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$/;
-    if (!pathPattern.test(collapsed)) {
-        context.report({
-            node: comment,
-            messageId: "invalidStoryFormat",
-            data: { details: buildStoryErrorMessage("invalid", collapsed) },
-        });
+    if (pathPattern.test(collapsed)) {
+        return;
+    }
+    if (/\s/.test(trimmed)) {
+        reportInvalidStoryFormat(context, comment, collapsed);
+        return;
+    }
+    const fixed = getFixedStoryPath(collapsed);
+    if (fixed && pathPattern.test(fixed)) {
+        reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed);
+        return;
     }
+    reportInvalidStoryFormat(context, comment, collapsed);
 }
 /**
  * Validate a @req annotation value and report detailed errors when needed.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  */
@@ -122,8 +235,10 @@ function validateReqAnnotation(context, comment, rawValue) {
  * validated against the configured patterns.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
  * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 function processComment(context, comment) {
     const rawLines = (comment.value || "").split(/\r?\n/);
@@ -132,14 +247,18 @@ function processComment(context, comment) {
      * Finalize and validate the currently pending annotation, if any.
      *
      * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+     * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
      * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
+     * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
      */
     function finalizePending() {
         if (!pending) {
             return;
         }
         // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+        // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
         // @req REQ-SYNTAX-VALIDATION - Dispatch validation based on annotation type
+        // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
         if (pending.type === "story") {
             validateStoryAnnotation(context, comment, pending.value);
         }
@@ -156,7 +275,9 @@ function processComment(context, comment) {
         const isStory = /@story\b/.test(normalized);
         const isReq = /@req\b/.test(normalized);
         // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+        // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
         // @req REQ-SYNTAX-VALIDATION - Start new pending annotation when a tag is found
+        // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
         if (isStory || isReq) {
             finalizePending();
             const value = normalized.replace(/^@story\b|^@req\b/, "").trim();
@@ -168,7 +289,9 @@ function processComment(context, comment) {
             return;
         }
         // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+        // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
         // @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
+        // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
         if (pending) {
             const continuation = normalized.trim();
             if (!continuation) {
@@ -194,11 +317,14 @@ exports.default = {
             invalidReqFormat: "{{details}}",
         },
         schema: [],
+        fixable: "code",
     },
     /**
      * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+     * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
      * @req REQ-SYNTAX-VALIDATION - Ensure rule create function validates annotations syntax
      * @req REQ-FORMAT-SPECIFICATION - Implement formatting checks per specification
+     * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
      */
     create(context) {
         const sourceCode = context.getSourceCode();
@@ -207,8 +333,10 @@ exports.default = {
              * Program-level handler that inspects all comments for @story and @req tags
              *
              * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+             * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
              * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
              * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
+             * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
              */
             Program() {
                 const comments = sourceCode.getAllComments() || [];

package/lib/src/rules/valid-req-reference.js

@@ -7,21 +7,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Rule to validate @req annotation references refer to existing requirements in story files
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Parse story files to extract requirement identifiers
- * @req REQ-DEEP-MATCH - Validate @req references against story file content
- * @req REQ-DEEP-CACHE - Cache parsed story content for performance
- * @req REQ-DEEP-PATH - Protect against path traversal in story paths
+ * @req REQ-DEEP-PARSE - Parse comments and extract story/requirement metadata
+ * @req REQ-DEEP-MATCH - Match @req annotations to story file requirements
+ * @req REQ-DEEP-CACHE - Cache requirement IDs per story file for efficient validation
+ * @req REQ-DEEP-PATH - Validate and resolve story file paths safely
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 /**
  * Extract the story path from a JSDoc comment.
- * Parses comment.value lines for @story annotation.
- * @param comment any JSDoc comment node
- * @returns story path or null if not found
- *
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Extracts @story annotation from comment content
+ * @req REQ-DEEP-PARSE - Parse JSDoc comment lines to locate @story annotations
  */
 function extractStoryPath(comment) {
     const rawLines = comment.value.split(/\r?\n/);
@@ -37,14 +33,11 @@ function extractStoryPath(comment) {
 /**
  * Validate a @req annotation line against the extracted story content.
  * Performs path validation, file reading, caching, and requirement existence checks.
- *
- * @param opts options bag
- *
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PATH - Validates and protects against path traversal and absolute paths
- * @req REQ-DEEP-CACHE - Caches parsed story files to avoid repeated IO
- * @req REQ-DEEP-MATCH - Ensures referenced requirement IDs exist in the story file
- * @req REQ-DEEP-PARSE - Parses story file content to find REQ- identifiers
+ * @req REQ-DEEP-PATH - Validate and resolve referenced story file paths
+ * @req REQ-DEEP-CACHE - Cache requirement IDs discovered in story files
+ * @req REQ-DEEP-MATCH - Verify that a referenced requirement ID exists in the story
+ * @req REQ-DEEP-PARSE - Parse story file contents to extract requirement identifiers
  */
 function validateReqLine(opts) {
     const { comment, context, line, storyPath, cwd, reqCache } = opts;
@@ -96,15 +89,10 @@ function validateReqLine(opts) {
     }
 }
 /**
- * Handle a single annotation line.
- * @story Updates the current story path when encountering an @story annotation
- * @req Validates the requirement reference against the current story content
- *
- * @param opts handler options
- *
+ * Handle a single annotation line for story or requirement metadata.
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Recognizes @story and @req annotation lines
- * @req REQ-DEEP-MATCH - Delegates @req validation to validateReqLine
+ * @req REQ-DEEP-PARSE - Parse annotation lines for @story and @req tags
+ * @req REQ-DEEP-MATCH - Dispatch @req lines for validation against story requirements
  */
 function handleAnnotationLine(opts) {
     const { line, comment, context, cwd, reqCache, storyPath } = opts;
@@ -119,14 +107,11 @@ function handleAnnotationLine(opts) {
     return storyPath;
 }
 /**
- * Handle JSDoc story and req annotations.
- *
- * @param opts options for comment handling
- *
+ * Handle JSDoc story and req annotations for a single comment block.
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Parses comment blocks to extract annotation lines
- * @req REQ-DEEP-MATCH - Uses handleAnnotationLine to validate @req entries
- * @req REQ-DEEP-CACHE - Passes shared cache for parsed story files
+ * @req REQ-DEEP-PARSE - Iterate comment lines to process @story/@req annotations
+ * @req REQ-DEEP-MATCH - Coordinate annotation handling across a comment block
+ * @req REQ-DEEP-CACHE - Maintain and reuse discovered story path across comments
  */
 function handleComment(opts) {
     const { comment, context, cwd, reqCache, rawStoryPath } = opts;
@@ -147,30 +132,25 @@ function handleComment(opts) {
 }
 /**
  * Create a Program listener that iterates comments and validates annotations.
- *
- * @param context ESLint rule context
- * @returns Program visitor function
- *
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-CACHE - Maintains a cache across comment processing
- * @req REQ-DEEP-PATH - Resolves and protects story paths against traversal
+ * @req REQ-DEEP-CACHE - Initialize and share a requirement cache for the program
+ * @req REQ-DEEP-PATH - Derive the working directory context for path resolution
  */
 function programListener(context) {
     const sourceCode = context.getSourceCode();
     const cwd = process.cwd();
     const reqCache = new Map();
     let rawStoryPath = null;
+    /**
+     * Program visitor that walks all comments to validate story/requirement references.
+     * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+     * @req REQ-DEEP-PARSE - Collect all comments from the source code
+     * @req REQ-DEEP-MATCH - Drive comment-level handling for traceability checks
+     * @req REQ-DEEP-CACHE - Reuse story path and requirement cache across comments
+     * @req REQ-DEEP-PATH - Ensure validation respects project-relative paths
+     */
     return function Program() {
         const comments = sourceCode.getAllComments() || [];
-        /**
-         * Process each comment to handle story and requirement annotations.
-         *
-         * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
-         * @req REQ-DEEP-PARSE - Parse annotations from comment blocks
-         * @req REQ-DEEP-MATCH - Validate @req references found in comments
-         * @req REQ-DEEP-CACHE - Use cache for parsed story files to avoid repeated IO
-         * @req REQ-DEEP-PATH - Enforce path validation when resolving story files
-         */
         comments.forEach((comment) => {
             rawStoryPath = handleComment({
                 comment,
@@ -197,12 +177,11 @@ exports.default = {
     },
     /**
      * Rule create entrypoint that returns the Program visitor.
-     *
      * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
-     * @req REQ-DEEP-MATCH - Entrypoint orchestrates validation of @req annotations
-     * @req REQ-DEEP-PARSE - Uses parsing helpers to extract annotations and story paths
-     * @req REQ-DEEP-CACHE - Establishes cache used during validation
-     * @req REQ-DEEP-PATH - Ensures path validation is applied during checks
+     * @req REQ-DEEP-MATCH - Register the Program visitor with ESLint
+     * @req REQ-DEEP-PARSE - Integrate comment parsing into the ESLint rule lifecycle
+     * @req REQ-DEEP-CACHE - Ensure cache and context are wired into the listener
+     * @req REQ-DEEP-PATH - Propagate path context into the program listener
      */
     create(context) {
         return { Program: programListener(context) };

package/lib/tests/rules/auto-fix-behavior-008.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tests/rules/auto-fix-behavior-008.test.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-AUTOFIX-MISSING - Verify ESLint --fix automatically adds missing @story annotations to functions
+ * @req REQ-AUTOFIX-FORMAT - Verify ESLint --fix corrects simple annotation format issues for @story annotations
+ */
+const eslint_1 = require("eslint");
+const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
+const valid_annotation_format_1 = __importDefault(require("../../src/rules/valid-annotation-format"));
+const functionRuleTester = new eslint_1.RuleTester({
+    languageOptions: {
+        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+    },
+});
+const formatRuleTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
+    describe("[REQ-AUTOFIX-MISSING] require-story-annotation auto-fix", () => {
+        functionRuleTester.run("require-story-annotation --fix", require_story_annotation_1.default, {
+            valid: [
+                {
+                    name: "[REQ-AUTOFIX-MISSING] already annotated function is unchanged",
+                    code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction alreadyAnnotated() {}`,
+                },
+            ],
+            invalid: [
+                {
+                    name: "[REQ-AUTOFIX-MISSING] adds @story before function declaration when missing",
+                    code: `function autoFixMe() {}`,
+                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction autoFixMe() {}`,
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'autoFixMe', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction autoFixMe() {}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+    describe("[REQ-AUTOFIX-FORMAT] valid-annotation-format auto-fix", () => {
+        formatRuleTester.run("valid-annotation-format --fix simple @story extension issues", valid_annotation_format_1.default, {
+            valid: [
+                {
+                    name: "[REQ-AUTOFIX-FORMAT] already-correct story path is unchanged",
+                    code: `// @story docs/stories/005.0-DEV-EXAMPLE.story.md`,
+                },
+            ],
+            invalid: [
+                {
+                    name: "[REQ-AUTOFIX-FORMAT] adds .md extension for .story path",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
+                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                    errors: [
+                        {
+                            messageId: "invalidStoryFormat",
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-FORMAT] adds .story.md extension when missing entirely",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION`,
+                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                    errors: [
+                        {
+                            messageId: "invalidStoryFormat",
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+});

package/lib/tests/rules/error-reporting.test.js

@@ -29,6 +29,7 @@ describe("Error Reporting Enhancements for require-story-annotation (Story 007.0
             {
                 name: "[REQ-ERROR-SPECIFIC] missing @story annotation should report specific details and suggestion",
                 code: `function bar() {}`,
+                output: "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}",
                 errors: [
                     {
                         messageId: "missingStory",

package/lib/tests/rules/require-story-annotation.test.js

@@ -69,6 +69,7 @@ declare function tsDecl(): void;`,
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story annotation on function",
                 code: `function bar() {}`,
+                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}`,
                 errors: [
                     {
                         messageId: "missingStory",
@@ -84,6 +85,7 @@ declare function tsDecl(): void;`,
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on function expression",
                 code: `const fnExpr = function() {};`,
+                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
                 errors: [
                     {
                         messageId: "missingStory",
@@ -99,6 +101,7 @@ declare function tsDecl(): void;`,
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on class method",
                 code: `class C {\n  method() {}\n}`,
+                output: `class C {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
                 errors: [
                     {
                         messageId: "missingStory",
@@ -114,6 +117,7 @@ declare function tsDecl(): void;`,
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on TS declare function",
                 code: `declare function tsDecl(): void;`,
+                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2020, sourceType: "module" },
@@ -133,6 +137,7 @@ declare function tsDecl(): void;`,
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on TS method signature",
                 code: `interface D {\n  method(): void;\n}`,
+                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ninterface D {\n  method(): void;\n}`,
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2020, sourceType: "module" },
@@ -173,6 +178,7 @@ declare function tsDecl(): void;`,
             {
                 name: "[exportPriority] exported function missing @story annotation",
                 code: `export function exportedMissing() {}`,
+                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nexport function exportedMissing() {}`,
                 options: [{ exportPriority: "exported" }],
                 errors: [
                     {
@@ -200,6 +206,7 @@ declare function tsDecl(): void;`,
             {
                 name: "[scope] function declaration missing annotation when scope is FunctionDeclaration",
                 code: `function onlyDecl() {}`,
+                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction onlyDecl() {}`,
                 options: [{ scope: ["FunctionDeclaration"] }],
                 errors: [
                     {

package/lib/tests/rules/valid-annotation-format.test.js

@@ -69,6 +69,7 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
             {
                 name: "[REQ-PATH-FORMAT] invalid story file extension",
                 code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
+                output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
                 errors: [
                     {
                         messageId: "invalidStoryFormat",
@@ -81,6 +82,7 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
             {
                 name: "[REQ-PATH-FORMAT] missing extension in story path",
                 code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION`,
+                output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
                 errors: [
                     {
                         messageId: "invalidStoryFormat",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",
@@ -22,7 +22,7 @@
     "lint": "eslint --config eslint.config.js \"src/**/*.{js,ts}\" \"tests/**/*.{js,ts}\" --max-warnings=0",
     "test": "jest --ci --bail",
     "ci-verify": "npm run type-check && npm run lint && npm run format:check && npm run duplication && npm run check:traceability && npm test && npm run audit:ci && npm run safety:deps",
-    "ci-verify:full": "npm run check:traceability && npm run safety:deps && npm run audit:ci && npm run build && npm run type-check && npm run lint-plugin-check && npm run lint -- --max-warnings=0 && npm run duplication && npm run test -- --coverage && npm run format:check && npm audit --production --audit-level=high && npm run audit:dev-high",
+    "ci-verify:full": "npm run check:traceability && npm run safety:deps && npm run audit:ci && npm run build && npm run type-check && npm run lint-plugin-check && npm run lint -- --max-warnings=0 && npm run duplication && npm run test -- --coverage && npm run format:check && npm audit --omit=dev --audit-level=high && npm run audit:dev-high",
     "ci-verify:fast": "npm run type-check && npm run check:traceability && npm run duplication && jest --ci --bail --passWithNoTests --testPathPatterns 'tests/(unit|fast)'",
     "format": "prettier --write .",
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
@@ -30,8 +30,7 @@
     "audit:dev-high": "node scripts/generate-dev-deps-audit.js",
     "safety:deps": "node scripts/ci-safety-deps.js",
     "audit:ci": "node scripts/ci-audit.js",
-    "smoke-test": "./scripts/smoke-test.sh",
-    "prepare": "husky install"
+    "smoke-test": "./scripts/smoke-test.sh"
   },
   "lint-staged": {
     "src/**/*.{js,jsx,ts,tsx,json,md}": [