eslint-plugin-traceability 1.5.1 → 1.6.1

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-req-annotation.d.ts

@@ -1,7 +1,12 @@
-/**
+/****
+ * Rule to enforce @req annotation on functions
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-RULE-EXPORT - Export the rule object for ESLint
  * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
+ * @req REQ-FUNCTION-DETECTION - Detect function declarations, function expressions, and method definitions (including TypeScript declarations)
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of which exports are checked
+ * @req REQ-EXPORT-PRIORITY - Allow configuration of export priority behavior
  */
-declare const _default: any;
-export default _default;
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

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

@@ -1,37 +1,59 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-/****
- * Rule to enforce @req annotation on functions
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
- * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
- * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
- */
+const require_story_helpers_1 = require("./helpers/require-story-helpers");
 const annotation_checker_1 = require("../utils/annotation-checker");
-/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-RULE-EXPORT - Export the rule object for ESLint
- * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
- */
-exports.default = {
+const rule = {
     meta: {
         type: "problem",
         fixable: "code",
         docs: {
-            description: "Require @req annotations on functions",
+            description: "Require @req annotations on function-like exports (declarations, expressions, and methods, excluding arrow functions)",
             recommended: "error",
         },
         messages: {
             missingReq: "Missing @req annotation for function '{{name}}' (REQ-ANNOTATION-REQUIRED)",
         },
-        schema: [],
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    scope: {
+                        type: "array",
+                        items: {
+                            enum: require_story_helpers_1.DEFAULT_SCOPE,
+                        },
+                        uniqueItems: true,
+                    },
+                    exportPriority: {
+                        enum: require_story_helpers_1.EXPORT_PRIORITY_VALUES,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
     },
     /**
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
      * @req REQ-CREATE-HOOK - Provide create(context) hook for rule behavior
-     * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
+     * @req REQ-FUNCTION-DETECTION - Detect function declarations, function expressions, and method definitions (including TS-specific nodes)
+     * @req REQ-CONFIGURABLE-SCOPE - Respect configurable scope of which exports are checked
+     * @req REQ-EXPORT-PRIORITY - Respect configurable export priority when determining which nodes to check
      */
     create(context) {
+        const options = context.options?.[0] ?? {};
+        const rawScope = options?.scope;
+        const scope = Array.isArray(rawScope) && rawScope.length > 0 ? rawScope : require_story_helpers_1.DEFAULT_SCOPE;
+        const exportPriority = options?.exportPriority ?? "all";
+        const shouldCheck = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority);
+        /**
+         * Helper to conditionally run the annotation check only when the node
+         * should be processed according to scope/exportPriority.
+         */
+        const runCheck = (node) => {
+            if (!shouldCheck(node))
+                return;
+            (0, annotation_checker_1.checkReqAnnotation)(context, node, { enableFix: false });
+        };
         return {
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -39,18 +61,44 @@ exports.default = {
              * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on function declarations
              */
             FunctionDeclaration(node) {
-                return (0, annotation_checker_1.checkReqAnnotation)(context, node);
+                runCheck(node);
+            },
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-FUNCTION-DETECTION - Detect function expressions
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on function expressions
+             */
+            FunctionExpression(node) {
+                if (node.parent && node.parent.type === "MethodDefinition") {
+                    return;
+                }
+                runCheck(node);
             },
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+             * @req REQ-FUNCTION-DETECTION - Detect method definitions
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on method definitions
              */
-            TSDeclareFunction: (node) => (0, annotation_checker_1.checkReqAnnotation)(context, node),
+            MethodDefinition(node) {
+                runCheck(node);
+            },
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript declare functions
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on TS declare functions
+             */
+            TSDeclareFunction(node) {
+                runCheck(node);
+            },
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript method signatures
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on TS method signatures
              */
-            TSMethodSignature: (node) => (0, annotation_checker_1.checkReqAnnotation)(context, node),
+            TSMethodSignature(node) {
+                runCheck(node);
+            },
         };
     },
 };
+exports.default = rule;

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

@@ -5,14 +5,20 @@
  * 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
+ * @req REQ-AUTOFIX-MISSING - This rule supports auto-fixing missing @story annotations per Story 008.0 auto-fix behavior.
+ * @req REQ-AUTOFIX-SAFE - Auto-fix behavior only inserts @story annotation JSDoc comments and never changes executable or runtime code.
+ * @req REQ-AUTOFIX-PRESERVE - Auto-fix inserts a minimal placeholder JSDoc in a way that preserves existing surrounding formatting and structure.
  */
 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
+ * @req REQ-AUTOFIX-MISSING - This rule participates in auto-fix for missing @story annotations.
  */
 declare const rule: Rule.RuleModule;
 export default rule;

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

@@ -6,16 +6,28 @@ 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
+ * @req REQ-AUTOFIX-MISSING - This rule participates in auto-fix for missing @story annotations.
  */
 const rule = {
     meta: {
         type: "problem",
         docs: {
-            description: "Require @story annotations on functions",
+            description: "Require @story annotations on functions and auto-fix missing annotations where possible",
             recommended: "error",
         },
         hasSuggestions: true,
+        /**
+         * Auto-fix support for inserting @story annotations.
+         *
+         * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+         * @req REQ-ANNOTATION-REQUIRED
+         * @req REQ-AUTOFIX-MISSING - `fixable: \"code\"` is used to implement REQ-AUTOFIX-MISSING for missing @story annotations.
+         * @req REQ-AUTOFIX-SAFE - Auto-fix is conservative and only adds a single-line JSDoc @story annotation without modifying existing runtime expressions.
+         * @req REQ-AUTOFIX-PRESERVE - Auto-fix behavior preserves surrounding code formatting and indentation when inserting the placeholder JSDoc.
+         */
+        fixable: "code",
         messages: {
             missingStory: "Missing @story annotation for function '{{name}}' (REQ-ANNOTATION-REQUIRED)",
         },
@@ -38,7 +50,9 @@ 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
+     * @req REQ-AUTOFIX-MISSING - The create hook wires in visitors that are capable of providing auto-fix suggestions for missing @story annotations.
      */
     create(context) {
         const sourceCode = context.getSourceCode();

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

@@ -1,6 +1,16 @@
 "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
+ * @req REQ-AUTOFIX-PRESERVE - Avoid risky text replacements when the annotation tag cannot be located
+ */
+const TAG_NOT_FOUND_INDEX = -1;
 /**
  * Normalize a raw comment line to make annotation parsing more robust.
  *
@@ -8,7 +18,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 +43,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 +54,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 +68,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 +78,111 @@ 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
+ * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and never broaden the referenced path
+ * @req REQ-AUTOFIX-PRESERVE - Preserve surrounding formatting when normalizing story path suffixes
+ */
+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.
+ *
+ * This helper:
+ *   - only adjusts the story path suffix when a safe, well-understood
+ *     transformation is available, satisfying REQ-AUTOFIX-SAFE.
+ *   - preserves all surrounding comment formatting, spacing, and text
+ *     outside the path substring, satisfying REQ-AUTOFIX-PRESERVE.
+ *
+ * @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
+ * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and avoid changing semantics
+ * @req REQ-AUTOFIX-PRESERVE - Auto-fix must preserve surrounding formatting and comments
+ */
+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 +196,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 +246,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 +258,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 +286,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 +300,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 +328,23 @@ exports.default = {
             invalidReqFormat: "{{details}}",
         },
         schema: [],
+        /**
+         * This rule's fixable support is limited to safe @story path suffix normalization per Story 008.0.
+         * Fixes are limited strictly to adjusting the suffix portion of the @story path (e.g., adding
+         * `.md` or `.story.md`), preserving all other comment text and whitespace exactly as written.
+         *
+         * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+         * @req REQ-AUTOFIX-SAFE
+         * @req REQ-AUTOFIX-PRESERVE
+         */
+        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 +353,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() || [];