eslint-plugin-traceability 1.9.0 → 1.10.1

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

@@ -1,247 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const valid_annotation_options_1 = require("./helpers/valid-annotation-options");
-const valid_annotation_utils_1 = require("./helpers/valid-annotation-utils");
-const valid_implements_utils_1 = require("./helpers/valid-implements-utils");
 const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-format-internal");
-/**
- * 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
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- */
-function reportInvalidStoryFormat(context, comment, collapsed, options) {
-    context.report({
-        node: comment,
-        messageId: "invalidStoryFormat",
-        data: { details: (0, valid_annotation_utils_1.buildStoryErrorMessage)("invalid", collapsed, options) },
-    });
-}
-/**
- * Compute the text replacement for an invalid @story annotation within a comment.
- *
- * This helper:
- *   - finds the @story tag in the raw comment text,
- *   - computes the character range of its value,
- *   - and returns an ESLint fix that replaces only that range.
- *
- * Returns null when the tag or value cannot be safely located.
- *
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @req REQ-AUTOFIX-SAFE
- * @req REQ-AUTOFIX-PRESERVE
- */
-function createStoryFix(context, comment, fixed) {
-    const sourceCode = context.getSourceCode();
-    const commentText = sourceCode.getText(comment);
-    const search = "@story";
-    const tagIndex = commentText.indexOf(search);
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-    // @req REQ-AUTOFIX-SAFE - Skip auto-fix when @story tag cannot be reliably located
-    if (tagIndex === valid_annotation_utils_1.TAG_NOT_FOUND_INDEX) {
-        return null;
-    }
-    const afterTagIndex = tagIndex + search.length;
-    const rest = commentText.slice(afterTagIndex);
-    const valueMatch = rest.match(/[^\S\r\n]*([^\r\n*]+)/);
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-    // @req REQ-AUTOFIX-SAFE - Abort auto-fix when story value range cannot be safely determined
-    if (!valueMatch || valueMatch.index === undefined) {
-        return null;
-    }
-    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,
-    ];
-    return () => (fixer) => fixer.replaceTextRange(fixRange, fixed);
-}
-/**
- * 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
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.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 fixFactory = createStoryFix(context, comment, fixed);
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-    // @req REQ-AUTOFIX-SAFE - Fall back to reporting without fix when safe fix cannot be created
-    if (!fixFactory) {
-        reportInvalidStoryFormat(context, comment, collapsed, (0, valid_annotation_options_1.getResolvedDefaults)());
-        return;
-    }
-    context.report({
-        node: comment,
-        messageId: "invalidStoryFormat",
-        data: {
-            details: (0, valid_annotation_utils_1.buildStoryErrorMessage)("invalid", collapsed, (0, valid_annotation_options_1.getResolvedDefaults)()),
-        },
-        fix: fixFactory(),
-    });
-}
-/**
- * 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
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.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
- * @req REQ-REGEX-VALIDATION - Validate configurable story regex patterns and fall back safely
- * @req REQ-BACKWARD-COMP - Preserve behavior when invalid regex config is supplied
- * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
- */
-function validateStoryAnnotation(context, comment, rawValue, options) {
-    const trimmed = rawValue.trim();
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-PATH-FORMAT - Treat missing @story value as a specific validation error
-    if (!trimmed) {
-        context.report({
-            node: comment,
-            messageId: "invalidStoryFormat",
-            data: { details: (0, valid_annotation_utils_1.buildStoryErrorMessage)("missing", null, options) },
-        });
-        return;
-    }
-    const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
-    const pathPattern = options.storyPattern;
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-PATH-FORMAT - Accept @story value when it matches configured storyPattern
-    if (pathPattern.test(collapsed)) {
-        return;
-    }
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-PATH-FORMAT - Reject @story values containing internal whitespace as invalid
-    if (/\s/.test(trimmed)) {
-        reportInvalidStoryFormat(context, comment, collapsed, options);
-        return;
-    }
-    const fixed = (0, valid_annotation_utils_1.getFixedStoryPath)(collapsed);
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-    // @req REQ-AUTOFIX-FORMAT - Apply suffix-only auto-fix when it yields a pattern-compliant path
-    if (fixed && pathPattern.test(fixed)) {
-        reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed);
-        return;
-    }
-    reportInvalidStoryFormat(context, comment, collapsed, options);
-}
-/**
- * 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
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
- * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
- * @req REQ-REGEX-VALIDATION - Validate configurable requirement regex patterns and fall back safely
- * @req REQ-BACKWARD-COMP - Preserve behavior when invalid regex config is supplied
- * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
- */
-function validateReqAnnotation(context, comment, rawValue, options) {
-    const trimmed = rawValue.trim();
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-REQ-FORMAT - Treat missing @req value as a specific validation error
-    if (!trimmed) {
-        context.report({
-            node: comment,
-            messageId: "invalidReqFormat",
-            data: { details: (0, valid_annotation_utils_1.buildReqErrorMessage)("missing", null, options) },
-        });
-        return;
-    }
-    const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
-    const reqPattern = options.reqPattern;
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-REQ-FORMAT - Flag @req identifiers that do not match the configured pattern
-    if (!reqPattern.test(collapsed)) {
-        context.report({
-            node: comment,
-            messageId: "invalidReqFormat",
-            data: { details: (0, valid_annotation_utils_1.buildReqErrorMessage)("invalid", collapsed, options) },
-        });
-    }
-}
-/**
- * Validate an @supports annotation value and report detailed errors when needed.
- *
- * Expected format:
- *   @supports <storyPath> <REQ-ID> [<REQ-ID> ...]
- *
- * Validation rules:
- *   - Value must include at least a story path and one requirement ID.
- *   - Story path must match the same storyPattern used for @story (no auto-fix).
- *   - Each subsequent token must match reqPattern and is validated individually.
- *
- * Story path issues are reported with "invalidImplementsFormat" and
- * requirement ID issues reuse the existing "invalidReqFormat" message.
- *
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-SUPPORTS-PARSE - Parse @supports annotations without affecting @story/@req
- * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
- * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
- */
-function validateImplementsAnnotation(context, comment, rawValue, options) {
-    const deps = {
-        MIN_IMPLEMENTS_TOKENS: valid_implements_utils_1.MIN_IMPLEMENTS_TOKENS,
-        reportMissingImplementsReqIds: valid_implements_utils_1.reportMissingImplementsReqIds,
-        reportMissingImplementsValue: valid_implements_utils_1.reportMissingImplementsValue,
-        reportInvalidImplementsReqId: valid_implements_utils_1.reportInvalidImplementsReqId,
-        reportInvalidImplementsStoryPath: valid_implements_utils_1.reportInvalidImplementsStoryPath,
-    };
-    (0, valid_implements_utils_1.validateImplementsAnnotationHelper)(deps, context, comment, {
-        rawValue,
-        options,
-    });
-}
-/**
- * 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
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
- * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
- */
-function finalizePendingAnnotation(context, comment, options, pending) {
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-MULTILINE-SUPPORT - Do nothing when there is no pending multi-line annotation to finalize
-    if (!pending) {
-        return null;
-    }
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-SYNTAX-VALIDATION - Dispatch to @story or @req validator based on pending annotation type
-    // @req REQ-AUTOFIX-FORMAT - Route to story validator which may apply safe auto-fixes
-    // @req REQ-MIXED-SUPPORT - Ensure @story and @req annotations are handled independently
-    if (pending.type === "story") {
-        validateStoryAnnotation(context, comment, pending.value, options);
-    }
-    else {
-        validateReqAnnotation(context, comment, pending.value, options);
-    }
-    return null;
-}
+const valid_annotation_format_validators_1 = require("./helpers/valid-annotation-format-validators");
 /**
  * Process a single normalized comment line and update the pending annotation state.
  *
@@ -269,7 +30,7 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     // @req REQ-IMPLEMENTS-PARSE - Immediately validate @supports without starting multi-line state
     if (isImplements) {
         const implementsValue = normalized.replace(/^@supports\b/, "").trim();
-        validateImplementsAnnotation(context, comment, implementsValue, options);
+        (0, valid_annotation_format_validators_1.validateImplementsAnnotation)(context, comment, implementsValue, options);
         return pending;
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
@@ -279,7 +40,7 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
     // @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
     if (isStory || isReq) {
-        finalizePendingAnnotation(context, comment, options, pending);
+        (0, valid_annotation_format_validators_1.finalizePendingAnnotation)(context, comment, options, pending);
         const value = normalized.replace(/^@story\b|^@req\b/, "").trim();
         return {
             type: isStory ? "story" : "req",
@@ -287,6 +48,12 @@ function processCommentLine({ normalized, pending, context, comment, options, })
             hasValue: value.trim().length > 0,
         };
     }
+    // Implement JSDoc tag coexistence behavior: terminate @story/@req values when a new non-traceability JSDoc tag line (e.g., @param, @returns) is encountered.
+    // @supports docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md REQ-ANNOTATION-TERMINATION REQ-CONTINUATION-LOGIC
+    if ((0, valid_annotation_format_internal_1.isNonTraceabilityJSDocTagLine)(normalized)) {
+        (0, valid_annotation_format_validators_1.finalizePendingAnnotation)(context, comment, options, pending);
+        return null;
+    }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
     // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
@@ -344,7 +111,7 @@ function processComment(context, comment, options) {
             options,
         });
     });
-    finalizePendingAnnotation(context, comment, options, pending);
+    (0, valid_annotation_format_validators_1.finalizePendingAnnotation)(context, comment, options, pending);
 }
 exports.default = {
     meta: {

package/lib/tests/rules/require-test-traceability.test.js

@@ -4,8 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * Tests for: docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
+ * Tests for:
+ * - docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
+ * - docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md
  * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX REQ-TEST-FRAMEWORK-COMPAT REQ-TEST-PATTERN-DETECT
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-PLACEHOLDER REQ-TEST-FIX-NO-INFERENCE
  */
 const eslint_1 = require("eslint");
 const require_test_traceability_1 = __importDefault(require("../../src/rules/require-test-traceability"));
@@ -14,7 +17,7 @@ const ruleTester = new eslint_1.RuleTester({
         parserOptions: { ecmaVersion: 2020, sourceType: "module" },
     },
 });
-describe("require-test-traceability rule (Story 020.0-DEV-TEST-ANNOTATION-VALIDATION)", () => {
+describe("require-test-traceability rule (Stories 020.0 and 021.0)", () => {
     ruleTester.run("require-test-traceability", require_test_traceability_1.default, {
         valid: [
             {
@@ -32,24 +35,58 @@ describe("require-test-traceability rule (Story 020.0-DEV-TEST-ANNOTATION-VALIDA
                 code: `/**\n * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT\n */\ndescribe('Story 020.0-DEV-TEST-ANNOTATION-VALIDATION', () => {});`,
                 filename: "src/not-a-test-file.ts",
             },
+            {
+                // [REQ-TEST-FIX-PREFIX-FORMAT] already-correct [REQ-XXX] prefix is left unchanged by auto-fix
+                code: `/**\n * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT\n */\ndescribe('Story 021.0-DEV-TEST-ANNOTATION-AUTO-FIX', () => { it('[REQ-TRACE-123] behaves correctly', () => {}); });`,
+                filename: "tests/rules/correct-prefix-autofix.test.ts",
+            },
         ],
         invalid: [
             {
-                // [REQ-TEST-FILE-SUPPORTS] missing @supports in test file
+                // [REQ-TEST-FIX-TEMPLATE] missing @supports in test file -> insert default placeholder template
                 code: `describe('Story 020.0-DEV-TEST-ANNOTATION-VALIDATION', () => { it('[REQ-ONE] works', () => {}); });`,
+                output: `/**\n * @supports docs/stories/XXX.X-STORY-NAME.story.md REQ-XXX-YYY REQ-XXX-ZZZ\n * TODO: Replace the placeholder story path and REQ-IDs with real values for this test file.\n */\ndescribe('Story 020.0-DEV-TEST-ANNOTATION-VALIDATION', () => { it('[REQ-ONE] works', () => {}); });`,
                 filename: "tests/rules/missing-supports.test.ts",
                 errors: [{ messageId: "missingFileSupports" }],
             },
             {
-                // [REQ-TEST-DESCRIBE-STORY] describe without story phrase
+                // [REQ-TEST-DESCRIBE-STORY] describe without story phrase still reported (no auto-fix)
                 code: `/**\n * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-DESCRIBE-STORY\n */\ndescribe('no story reference here', () => {});`,
                 filename: "tests/rules/bad-describe.test.ts",
                 errors: [{ messageId: "missingDescribeStory" }],
             },
             {
-                // [REQ-TEST-IT-REQ-PREFIX] test name without [REQ-XXX] prefix
+                // [REQ-TEST-IT-REQ-PREFIX][REQ-TEST-FIX-NO-INFERENCE] test name without any REQ prefix -> error but no auto-fix
                 code: `/**\n * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-IT-REQ-PREFIX\n */\nit('missing prefix', () => {});`,
-                filename: "tests/rules/bad-test-name.test.ts",
+                filename: "tests/rules/bad-test-name-no-prefix.test.ts",
+                errors: [{ messageId: "missingReqPrefix" }],
+            },
+            {
+                // [REQ-TEST-FIX-PREFIX-FORMAT] malformed prefix with extra spaces in brackets
+                code: `/**\n * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT\n */\nit('[ REQ-TEST-FIX ] does something', () => {});`,
+                output: `/**\n * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT\n */\nit('[REQ-TEST-FIX] does something', () => {});`,
+                filename: "tests/rules/malformed-prefix-spacing.test.ts",
+                errors: [{ messageId: "missingReqPrefix" }],
+            },
+            {
+                // [REQ-TEST-FIX-PREFIX-FORMAT] malformed prefix with underscore delimiter
+                code: `/**\n * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT\n */\nit('[REQ_TEST_FIX] does something', () => {});`,
+                output: `/**\n * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT\n */\nit('[REQ-TEST-FIX] does something', () => {});`,
+                filename: "tests/rules/malformed-prefix-underscore.test.ts",
+                errors: [{ messageId: "missingReqPrefix" }],
+            },
+            {
+                // [REQ-TEST-FIX-PREFIX-FORMAT] malformed prefix with lowercase req
+                code: `/**\n * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT\n */\nit('[req-lowercase] bad casing', () => {});`,
+                output: `/**\n * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT\n */\nit('[REQ-LOWERCASE] bad casing', () => {});`,
+                filename: "tests/rules/malformed-prefix-lowercase.test.ts",
+                errors: [{ messageId: "missingReqPrefix" }],
+            },
+            {
+                // [REQ-TEST-FIX-PREFIX-FORMAT] malformed prefix using parentheses
+                code: `/**\n * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT\n */\nit('(REQ-PAREN) with parens', () => {});`,
+                output: `/**\n * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT\n */\nit('[REQ-PAREN] with parens', () => {});`,
+                filename: "tests/rules/malformed-prefix-parens.test.ts",
                 errors: [{ messageId: "missingReqPrefix" }],
             },
         ],

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

@@ -23,6 +23,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-SUPPORTS-PARSE - Rule parses @supports annotations with story and requirement references
  * @req REQ-FORMAT-VALIDATION - Rule validates story and requirement formats inside @supports annotations
  * @req REQ-MIXED-SUPPORT - Rule supports mixed @story/@req/@supports usage in the same comment
+ * Tests for: docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
+ * @story docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
+ * @req REQ-JSDOC-TAG-COEXISTENCE - Rule allows traceability annotations to coexist with other JSDoc tags
+ * @req REQ-ANNOTATION-TERMINATION - Rule correctly terminates traceability annotation values at JSDoc tag boundaries
+ * @req REQ-JSDOC-BOUNDARY-DETECTION - Rule detects @param/@returns and similar tags as boundaries
+ * @req REQ-CONTINUATION-LOGIC - Rule correctly decides when to continue or stop multi-line traceability values
+ * @req REQ-NO-FALSE-POSITIVES - Rule does not report false positives when JSDoc tags follow traceability tags
+ * @req REQ-PRESERVE-MULTILINE - Rule preserves multi-line story/req values without including following JSDoc tags
  */
 const eslint_1 = require("eslint");
 const valid_annotation_format_1 = __importDefault(require("../../src/rules/valid-annotation-format"));
@@ -194,6 +202,69 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
  * @supports docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-IMPLEMENTS-PARSE REQ-FORMAT-VALIDATION REQ-MIXED-SUPPORT
  */`,
             },
+            {
+                name: "[REQ-JSDOC-TAG-COEXISTENCE] traceability before other JSDoc tags",
+                code: `/**
+ * @story docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
+ * @req REQ-JSDOC-TAG-COEXISTENCE
+ * @param {string} id - Identifier for the lookup.
+ * @returns {Promise<void>} - Completes when finished.
+ */
+function fetchById(id) {
+  return Promise.resolve();
+}`,
+            },
+            {
+                name: "[REQ-JSDOC-TAG-COEXISTENCE] traceability after other JSDoc tags",
+                code: `/**
+ * Fetch a user by id.
+ *
+ * @param {string} id - Identifier for the lookup.
+ * @returns {Promise<void>} - Completes when finished.
+ * @story docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
+ * @req REQ-ANNOTATION-TERMINATION
+ */
+function fetchUser(id) {
+  return Promise.resolve();
+}`,
+            },
+            {
+                name: "[REQ-JSDOC-TAG-COEXISTENCE] mixed positions of traceability and other JSDoc tags",
+                code: `/**
+ * Update a record with new data.
+ *
+ * @story docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
+ * @param {string} id - Identifier.
+ * @req REQ-JSDOC-BOUNDARY-DETECTION
+ * @param {object} payload - Updated fields.
+ * @returns {boolean} - True if updated.
+ * @req REQ-CONTINUATION-LOGIC
+ */
+function updateRecord(id, payload) {
+  return true;
+}`,
+            },
+            {
+                name: "[REQ-PRESERVE-MULTILINE] multi-line @story annotation before other JSDoc tags",
+                code: `/**
+ * @story docs/stories/022.0-DEV-
+ * JSDOC-COEXISTENCE.story.md
+ * @param {string} id - Identifier for the lookup.
+ * @returns {Promise<void>} - Completes when finished.
+ */
+function loadForStory(id) {
+  return Promise.resolve();
+}`,
+            },
+            {
+                name: "[REQ-NO-FALSE-POSITIVES] JSDoc tags do not pollute requirement ID when following @req",
+                code: `/**
+ * @req REQ-OPTIMIZATION
+ * @param {object} data - Input payload.
+ * @returns {void}
+ */
+function optimize(data) {}`,
+            },
         ],
         invalid: [
             makeInvalidStory({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "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",

package/user-docs/api-reference.md

@@ -197,7 +197,7 @@ Description: Enforces traceability conventions in test files by requiring:
 - Story references in top-level `describe` blocks.
 - Requirement identifiers in `it`/`test` names using a `[REQ-XXX]` prefix.
 
-The rule is designed to complement the function-level rules (such as `require-story-annotation` and `require-req-annotation`) by ensuring that tests explicitly declare which requirements and stories they validate. It is enabled in both the `recommended` and `strict` presets alongside the other core rules.
+The rule is designed to complement the function-level rules (such as `require-story-annotation` and `require-req-annotation`) by ensuring that tests explicitly declare which requirements and stories they validate. It is enabled in both the `recommended` and `strict` presets alongside the other core rules. For Story 021.0, this rule also provides targeted auto-fix capabilities: when run with `--fix`, it can (1) insert a safe, non-semantic file-level `@supports` placeholder template at the top of matching test files when the annotation is missing, including clear TODO guidance for humans to replace the template with a real story and requirement reference, and (2) normalize malformed `[REQ-XXX]` prefixes that already contain an identifiable requirement ID, correcting spacing, bracket/parenthesis usage, underscores, and casing while preserving the original ID text and never inventing new requirement identifiers.
 
 Options:
 
@@ -207,6 +207,9 @@ The rule accepts an optional configuration object:
 - `requireDescribeStory` (boolean, optional) – When `true` (default), requires that each top-level `describe` block include a story reference somewhere in its description text (for example, a path such as `docs/stories/010.0-PAYMENTS.story.md` or a shorter project-specific alias that your team uses consistently).
 - `requireTestReqPrefix` (boolean, optional) – When `true` (default), requires each `it`/`test` block name to begin with a requirement identifier in square brackets, such as `[REQ-PAYMENTS-REFUND]`. The exact `REQ-` pattern is shared with the `valid-annotation-format` rule’s requirement ID checks.
 - `describePattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that the `describe` description text must match when `requireDescribeStory` is enabled. This lets you enforce a project-specific format such as requiring a canonical story path or a `STORY-` style identifier in the `describe` string. If omitted, a built-in default that loosely matches a typical story path (similar to `docs/stories/<name>.story.md`) is used.
+- `autoFixTestTemplate` (boolean, optional) – When `true` (default), allows the rule’s `--fix` mode to insert a file-level `@supports` placeholder template at the top of test files that are missing it. The template is intentionally non-semantic and includes TODO-style guidance so humans can later replace it with a real story path and requirement IDs; disabling this option prevents the rule from inserting the template automatically.
+- `autoFixTestPrefixFormat` (boolean, optional) – When `true` (default), enables safe normalization of malformed `[REQ-XXX]` prefixes in `it`/`test` names during `--fix`. The rule only rewrites prefixes that already contain a recognizable requirement identifier and limits changes to formatting concerns (spacing, square brackets vs. parentheses, underscore and dash usage, and letter casing) without fabricating new IDs or guessing requirement names.
+- `testSupportsTemplate` (string, optional) – Overrides the default file-level `@supports` placeholder template used when `autoFixTestTemplate` is enabled. This string should be a complete JSDoc-style block (for example, including `/**`, `*`, and `*/`) that encodes your project’s preferred TODO guidance or placeholder story path; it is inserted verbatim at the top of matching test files that lack a `@supports` annotation, and is never interpreted or expanded by the rule.
 
 Behavior notes:
 
@@ -567,4 +570,5 @@ If `--from` or `--to` is missing, the CLI prints an error, shows the help text,
 In CI:
 
 ```bash
-npm run traceability:verify
+npm run traceability:verify
+```