eslint-plugin-traceability 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.9.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.8.3...v1.9.0) (2025-12-04)
+# [1.10.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.9.0...v1.10.0) (2025-12-05)
 
 
 ### Features
 
-* add require-test-traceability rule for test files ([1eca595](https://github.com/voder-ai/eslint-plugin-traceability/commit/1eca595d7c1b12b224c3b7a647405c0bff7e7346))
+* add safe auto-fix support for test traceability rule ([b511e40](https://github.com/voder-ai/eslint-plugin-traceability/commit/b511e40593791ac4b25af9c71d3f377b3245ea74))
 
 # Changelog
 

package/lib/src/rules/helpers/require-test-traceability-helpers.d.ts

@@ -0,0 +1,34 @@
+export type TestTraceabilityAutoFixOptions = {
+    autoFixTestTemplate: boolean;
+    testSupportsTemplate?: string;
+};
+export type CallExpressionOptions = {
+    sourceCode: any;
+    describeRegex: RegExp;
+    requireDescribeStory: boolean;
+    requireTestReqPrefix: boolean;
+    autoFixTestPrefixFormat: boolean;
+};
+/**
+ * Determine if a file should be treated as a test file based on patterns.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT
+ */
+export declare function determineIsTestFile(filename: string, rawPatterns?: string[]): boolean;
+/**
+ * Ensure the file has a @supports annotation listing tested requirements.
+ *
+ * When auto-fix is enabled, a placeholder @supports JSDoc is inserted at the
+ * top of the file (after any shebang) using a safe, non-semantic template.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS REQ-TEST-SUPPORTS-VALID
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PLACEHOLDER REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+export declare function ensureFileSupportsAnnotation(context: any, sourceCode: any, autoFixOptions: TestTraceabilityAutoFixOptions): void;
+/**
+ * Build a CallExpression visitor for the main rule create() function.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX REQ-TEST-NESTED-DESCRIBE REQ-TEST-ERROR-CONTEXT
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+export declare function handleCallExpression(context: any, options: CallExpressionOptions): (node: any) => void;

package/lib/src/rules/helpers/require-test-traceability-helpers.js

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.determineIsTestFile = determineIsTestFile;
+exports.ensureFileSupportsAnnotation = ensureFileSupportsAnnotation;
+exports.handleCallExpression = handleCallExpression;
+/**
+ * Helper utilities for the require-test-traceability rule.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT REQ-TEST-FRAMEWORK-COMPAT
+ * @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 NOT_FOUND = -1;
+const REQ_PREFIX_LENGTH = 3;
+const QUOTES = ["'", '"', "`"];
+/**
+ * Determine if a file should be treated as a test file based on patterns.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT
+ */
+function determineIsTestFile(filename, rawPatterns = [
+    "/tests/",
+    "/test/",
+    "/__tests__",
+    ".test.",
+    ".spec.",
+]) {
+    return rawPatterns.some((pattern) => filename.includes(pattern.replace("**", "")));
+}
+/**
+ * Build the placeholder @supports template comment for a test file.
+ *
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PLACEHOLDER
+ */
+function buildSupportsTemplateComment(customTemplate) {
+    const baseTemplate = (customTemplate && customTemplate.trim()) ||
+        "@supports docs/stories/XXX.X-STORY-NAME.story.md REQ-XXX-YYY REQ-XXX-ZZZ";
+    const lines = [
+        "/**",
+        ` * ${baseTemplate}`,
+        " * TODO: Replace the placeholder story path and REQ-IDs with real values for this test file.",
+        " */",
+        "",
+    ];
+    return lines.join("\n");
+}
+/**
+ * Insert the file-level @supports template comment at a safe location.
+ *
+ * The template is inserted after a shebang line if present, otherwise at the
+ * very start of the file. This preserves executable semantics while adding
+ * only comment text.
+ *
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+function insertSupportsTemplate(fixer, sourceCode, customTemplate) {
+    const text = sourceCode.text || "";
+    let insertIndex = 0;
+    // Preserve shebang: it must remain the very first characters in the file.
+    if (text.startsWith("#!")) {
+        const firstNewline = text.indexOf("\n");
+        insertIndex = firstNewline === NOT_FOUND ? text.length : firstNewline + 1;
+    }
+    const templateComment = buildSupportsTemplateComment(customTemplate);
+    return fixer.insertTextBeforeRange([insertIndex, insertIndex], templateComment);
+}
+/**
+ * Ensure the file has a @supports annotation listing tested requirements.
+ *
+ * When auto-fix is enabled, a placeholder @supports JSDoc is inserted at the
+ * top of the file (after any shebang) using a safe, non-semantic template.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS REQ-TEST-SUPPORTS-VALID
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PLACEHOLDER REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+function ensureFileSupportsAnnotation(context, sourceCode, autoFixOptions) {
+    const fileComments = sourceCode.getAllComments() || [];
+    const fileHasSupports = fileComments.some((comment) => /@supports\b/.test(comment.value || ""));
+    if (!fileHasSupports) {
+        const node = fileComments[0] || (sourceCode.ast && sourceCode.ast);
+        context.report({
+            node: node,
+            messageId: "missingFileSupports",
+            fix: autoFixOptions.autoFixTestTemplate === false
+                ? undefined
+                : (fixer) => insertSupportsTemplate(fixer, sourceCode, autoFixOptions.testSupportsTemplate),
+        });
+    }
+}
+/**
+ * Check if a callee name corresponds to a test framework function.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FRAMEWORK-COMPAT
+ */
+function isTestCallName(name) {
+    return ["describe", "it", "test", "context"].includes(name);
+}
+function getCalleeName(node) {
+    if (node.callee.type === "Identifier") {
+        return node.callee.name;
+    }
+    if (node.callee.type === "MemberExpression" &&
+        node.callee.object.type === "Identifier") {
+        return node.callee.object.name;
+    }
+    return null;
+}
+function getFirstArgumentLiteral(node) {
+    const arg = node.arguments && node.arguments[0];
+    if (!arg)
+        return null;
+    if (arg.type === "Literal" && typeof arg.value === "string") {
+        return arg.value;
+    }
+    return null;
+}
+/**
+ * Normalize a raw REQ identifier string to canonical REQ-XXX format.
+ *
+ * This helper performs only local, format-level normalization without
+ * inferring new requirement IDs.
+ *
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-NO-INFERENCE
+ */
+function normalizeReqId(raw) {
+    let id = raw.trim().toUpperCase();
+    if (!id.startsWith("REQ")) {
+        return id;
+    }
+    let rest = id.slice(REQ_PREFIX_LENGTH);
+    // Drop leading separators after "REQ"
+    rest = rest.replace(/^[-_\s:]+/, "");
+    // Convert internal whitespace/underscores to hyphens
+    rest = rest.replace(/[\s_]+/g, "-");
+    // Collapse multiple hyphens
+    rest = rest.replace(/-+/g, "-");
+    return rest ? `REQ-${rest}` : "REQ-";
+}
+/**
+ * Normalize malformed [REQ-XXX] prefixes in test names.
+ *
+ * Handles cases such as:
+ * - "[ REQ-XXX ] ..."  -> "[REQ-XXX] ..."
+ * - "[REQ_XXX] ..."    -> "[REQ-XXX] ..."
+ * - "(REQ-XXX) ..."    -> "[REQ-XXX] ..."
+ * - "[req-xxx] ..."    -> "[REQ-XXX] ..."
+ *
+ * Only operates when a REQ identifier is already present at the start of the
+ * string; it never invents new IDs.
+ *
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+function normalizeReqPrefixInDescription(description) {
+    const canonicalPattern = /^\[REQ-[^\]]+]/;
+    if (canonicalPattern.test(description)) {
+        return null;
+    }
+    // Leading square brackets with optional spacing.
+    const squareMatch = description.match(/^\[\s*(REQ[^\]]*?)\s*](.*)$/i);
+    if (squareMatch) {
+        const normalizedId = normalizeReqId(squareMatch[1]);
+        return `[${normalizedId}]${squareMatch[2] ?? ""}`;
+    }
+    // Leading parentheses with optional spacing.
+    const parenMatch = description.match(/^\(\s*(REQ[^)]*?)\s*\)(.*)$/i);
+    if (parenMatch) {
+        const normalizedId = normalizeReqId(parenMatch[1]);
+        return `[${normalizedId}]${parenMatch[2] ?? ""}`;
+    }
+    return null;
+}
+/**
+ * Create a string literal with the same quote style as the original node.
+ *
+ * This helper rewrites only the literal value while preserving the original
+ * quoting character (`'`, `"`, or `` ` ``) and escaping rules.
+ *
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PRESERVE
+ */
+function createUpdatedStringLiteralRaw(originalNode, newValue, sourceCode) {
+    const raw = sourceCode.getText(originalNode);
+    const firstChar = raw[0];
+    if (QUOTES.includes(firstChar)) {
+        const quote = firstChar;
+        const escaped = newValue
+            .replace(/\\/g, "\\\\")
+            .replace(new RegExp(`\\${quote}`, "g"), `\\${quote}`);
+        return `${quote}${escaped}${quote}`;
+    }
+    // Fallback: let JSON.stringify choose a safe representation.
+    return JSON.stringify(newValue);
+}
+function handleDescribeCall(context, node, description, options) {
+    const { describeRegex, requireDescribeStory } = options;
+    if (!requireDescribeStory)
+        return;
+    if (!describeRegex.test(description)) {
+        context.report({
+            node: node,
+            messageId: "missingDescribeStory",
+        });
+    }
+}
+function handleItOrTestCall(context, node, description, options) {
+    const { sourceCode, requireTestReqPrefix, autoFixTestPrefixFormat } = options;
+    if (!requireTestReqPrefix)
+        return;
+    if (!/^\[REQ-[^\]]+]/.test(description)) {
+        const normalizedDescription = autoFixTestPrefixFormat !== false
+            ? normalizeReqPrefixInDescription(description)
+            : null;
+        context.report({
+            node: node,
+            messageId: "missingReqPrefix",
+            ...(autoFixTestPrefixFormat !== false &&
+                normalizedDescription !== null &&
+                node.arguments &&
+                node.arguments[0] &&
+                node.arguments[0].type === "Literal" &&
+                typeof node.arguments[0].value === "string"
+                ? {
+                    fix(fixer) {
+                        const literalNode = node.arguments[0];
+                        const newRaw = createUpdatedStringLiteralRaw(literalNode, normalizedDescription, sourceCode);
+                        return fixer.replaceText(literalNode, newRaw);
+                    },
+                }
+                : {}),
+        });
+    }
+}
+/**
+ * Build a CallExpression visitor for the main rule create() function.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX REQ-TEST-NESTED-DESCRIBE REQ-TEST-ERROR-CONTEXT
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+ */
+function handleCallExpression(context, options) {
+    const { describeRegex, requireDescribeStory } = options;
+    return (node) => {
+        const calleeName = getCalleeName(node);
+        if (!calleeName || !isTestCallName(calleeName)) {
+            return;
+        }
+        const description = getFirstArgumentLiteral(node);
+        if (!description)
+            return;
+        if (calleeName === "describe") {
+            handleDescribeCall(context, node, description, {
+                describeRegex,
+                requireDescribeStory,
+            });
+            return;
+        }
+        if (calleeName === "it" || calleeName === "test") {
+            handleItOrTestCall(context, node, description, options);
+        }
+    };
+}

package/lib/src/rules/require-test-traceability.d.ts

@@ -6,6 +6,8 @@ import type { Rule } from "eslint";
  * - Test files have a file-level @supports annotation listing tested requirements.
  * - describe()/it()/test()/context() blocks include story and requirement references
  *   following project conventions.
+ * - When ESLint runs with --fix, safe, non-semantic auto-fixes are applied for
+ *   missing file-level @supports and malformed [REQ-XXX] prefixes in test names.
  *
  * @story docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
  * @req REQ-TEST-FILE-SUPPORTS
@@ -16,6 +18,7 @@ import type { Rule } from "eslint";
  * @req REQ-TEST-FRAMEWORK-COMPAT
  * @req REQ-TEST-NESTED-DESCRIBE
  * @req REQ-TEST-ERROR-CONTEXT
+ * @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
  */
 declare const rule: Rule.RuleModule;
 export default rule;

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

@@ -1,62 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-/**
- * Determine if a file should be treated as a test file based on patterns.
- *
- * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT
- */
-function determineIsTestFile(filename, rawPatterns = [
-    "/tests/",
-    "/test/",
-    "/__tests__/",
-    ".test.",
-    ".spec.",
-]) {
-    return rawPatterns.some((pattern) => filename.includes(pattern.replace("**", "")));
-}
-/**
- * Ensure the file has a @supports annotation listing tested requirements.
- *
- * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS REQ-TEST-SUPPORTS-VALID
- */
-function ensureFileSupportsAnnotation(context, sourceCode) {
-    const fileComments = sourceCode.getAllComments() || [];
-    const fileHasSupports = fileComments.some((comment) => /@supports\b/.test(comment.value || ""));
-    if (!fileHasSupports) {
-        const node = fileComments[0] || (sourceCode.ast && sourceCode.ast);
-        context.report({
-            node: node,
-            messageId: "missingFileSupports",
-        });
-    }
-}
-/**
- * Check if a callee name corresponds to a test framework function.
- *
- * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FRAMEWORK-COMPAT
- */
-function isTestCallName(name) {
-    return ["describe", "it", "test", "context"].includes(name);
-}
-function getCalleeName(node) {
-    if (node.callee.type === "Identifier") {
-        return node.callee.name;
-    }
-    if (node.callee.type === "MemberExpression" &&
-        node.callee.object.type === "Identifier") {
-        return node.callee.object.name;
-    }
-    return null;
-}
-function getFirstArgumentLiteral(node) {
-    const arg = node.arguments && node.arguments[0];
-    if (!arg)
-        return null;
-    if (arg.type === "Literal" && typeof arg.value === "string") {
-        return arg.value;
-    }
-    return null;
-}
+const require_test_traceability_helpers_1 = require("./helpers/require-test-traceability-helpers");
 /**
  * Enforce traceability conventions in test files.
  *
@@ -64,6 +8,8 @@ function getFirstArgumentLiteral(node) {
  * - Test files have a file-level @supports annotation listing tested requirements.
  * - describe()/it()/test()/context() blocks include story and requirement references
  *   following project conventions.
+ * - When ESLint runs with --fix, safe, non-semantic auto-fixes are applied for
+ *   missing file-level @supports and malformed [REQ-XXX] prefixes in test names.
  *
  * @story docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
  * @req REQ-TEST-FILE-SUPPORTS
@@ -74,6 +20,7 @@ function getFirstArgumentLiteral(node) {
  * @req REQ-TEST-FRAMEWORK-COMPAT
  * @req REQ-TEST-NESTED-DESCRIBE
  * @req REQ-TEST-ERROR-CONTEXT
+ * @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 rule = {
     meta: {
@@ -82,6 +29,7 @@ const rule = {
             description: "Enforce traceability annotations and naming conventions in test files",
             recommended: "error",
         },
+        fixable: "code",
         schema: [
             {
                 type: "object",
@@ -108,6 +56,17 @@ const rule = {
                         type: "string",
                         default: "Story [0-9]+\\.[0-9]+-",
                     },
+                    autoFixTestTemplate: {
+                        type: "boolean",
+                        default: true,
+                    },
+                    autoFixTestPrefixFormat: {
+                        type: "boolean",
+                        default: true,
+                    },
+                    testSupportsTemplate: {
+                        type: "string",
+                    },
                 },
                 additionalProperties: false,
             },
@@ -120,49 +79,33 @@ const rule = {
     },
     create(context) {
         const filename = context.getFilename();
-        const options = (context.options && context.options[0]) || {};
+        const rawOptions = (context.options && context.options[0]) || {};
         const { testFilePatterns = [
             "/tests/",
             "/test/",
-            "/__tests__/",
+            "/__tests__",
             ".test.",
             ".spec.",
-        ], requireDescribeStory = true, requireTestReqPrefix = true, describePattern = "Story [0-9]+\\.[0-9]+-", } = options;
-        const isTestFile = determineIsTestFile(filename, testFilePatterns);
-        if (!isTestFile) {
+        ], requireDescribeStory = true, requireTestReqPrefix = true, describePattern = "Story [0-9]+\\.[0-9]+-", autoFixTestTemplate = true, autoFixTestPrefixFormat = true, testSupportsTemplate, } = rawOptions;
+        const isTestFile = (0, require_test_traceability_helpers_1.determineIsTestFile)(filename, testFilePatterns);
+        if (!isTestFile)
             return {};
-        }
         const sourceCode = context.getSourceCode();
-        ensureFileSupportsAnnotation(context, sourceCode);
+        (0, require_test_traceability_helpers_1.ensureFileSupportsAnnotation)(context, sourceCode, {
+            autoFixTestTemplate,
+            testSupportsTemplate,
+        });
         const describeRegex = new RegExp(describePattern);
         return {
             // @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX REQ-TEST-NESTED-DESCRIBE REQ-TEST-ERROR-CONTEXT
-            CallExpression(node) {
-                const calleeName = getCalleeName(node);
-                if (!calleeName || !isTestCallName(calleeName)) {
-                    return;
-                }
-                const description = getFirstArgumentLiteral(node);
-                if (!description)
-                    return;
-                if (requireDescribeStory && calleeName === "describe") {
-                    if (!describeRegex.test(description)) {
-                        context.report({
-                            node: node,
-                            messageId: "missingDescribeStory",
-                        });
-                    }
-                }
-                if (requireTestReqPrefix &&
-                    (calleeName === "it" || calleeName === "test")) {
-                    if (!/^\[REQ-[^\]]+]/.test(description)) {
-                        context.report({
-                            node: node,
-                            messageId: "missingReqPrefix",
-                        });
-                    }
-                }
-            },
+            // @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+            CallExpression: (0, require_test_traceability_helpers_1.handleCallExpression)(context, {
+                sourceCode,
+                describeRegex,
+                requireDescribeStory,
+                requireTestReqPrefix,
+                autoFixTestPrefixFormat,
+            }),
         };
     },
 };

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/package.json

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

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
+```