eslint-plugin-traceability 1.8.3 → 1.10.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.8.3](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.8.2...v1.8.3) (2025-12-04)
+# [1.10.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.9.0...v1.10.0) (2025-12-05)
 
 
-### Bug Fixes
+### Features
 
-* avoid running husky in consumers and repair smoke test ([849dbc2](https://github.com/voder-ai/eslint-plugin-traceability/commit/849dbc2d5a8f80890bbee94e1c4f2a6e15068b6d))
+* add safe auto-fix support for test traceability rule ([b511e40](https://github.com/voder-ai/eslint-plugin-traceability/commit/b511e40593791ac4b25af9c71d3f377b3245ea74))
 
 # Changelog
 

package/lib/src/index.d.ts

@@ -14,7 +14,7 @@ import { detectStaleAnnotations, updateAnnotationReferences, batchUpdateAnnotati
  * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
  * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
  */
-declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference", "prefer-implements-annotation"];
+declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference", "prefer-implements-annotation", "require-test-traceability"];
 type RuleName = (typeof RULE_NAMES)[number];
 declare const rules: Record<RuleName, Rule.RuleModule>;
 declare const plugin: {

package/lib/src/index.js

@@ -18,6 +18,7 @@ const RULE_NAMES = [
     "valid-story-reference",
     "valid-req-reference",
     "prefer-implements-annotation",
+    "require-test-traceability",
 ];
 const rules = {};
 exports.rules = rules;
@@ -89,6 +90,7 @@ const TRACEABILITY_RULE_SEVERITIES = {
     "traceability/valid-annotation-format": "warn",
     "traceability/valid-story-reference": "error",
     "traceability/valid-req-reference": "error",
+    "traceability/require-test-traceability": "error",
 };
 /**
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md

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

@@ -0,0 +1,24 @@
+import type { Rule } from "eslint";
+/**
+ * Enforce traceability conventions in test files.
+ *
+ * This rule validates that:
+ * - 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
+ * @req REQ-TEST-DESCRIBE-STORY
+ * @req REQ-TEST-IT-REQ-PREFIX
+ * @req REQ-TEST-SUPPORTS-VALID
+ * @req REQ-TEST-PATTERN-DETECT
+ * @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

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const require_test_traceability_helpers_1 = require("./helpers/require-test-traceability-helpers");
+/**
+ * Enforce traceability conventions in test files.
+ *
+ * This rule validates that:
+ * - 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
+ * @req REQ-TEST-DESCRIBE-STORY
+ * @req REQ-TEST-IT-REQ-PREFIX
+ * @req REQ-TEST-SUPPORTS-VALID
+ * @req REQ-TEST-PATTERN-DETECT
+ * @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: {
+        type: "problem",
+        docs: {
+            description: "Enforce traceability annotations and naming conventions in test files",
+            recommended: "error",
+        },
+        fixable: "code",
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    testFilePatterns: {
+                        type: "array",
+                        items: { type: "string" },
+                        default: [
+                            "**/tests/**/*.test.{js,ts}",
+                            "**/tests/**/*.spec.{js,ts}",
+                            "**/__tests__/**/*.{js,ts}",
+                            "**/*.{test,spec}.{js,ts}",
+                        ],
+                    },
+                    requireDescribeStory: {
+                        type: "boolean",
+                        default: true,
+                    },
+                    requireTestReqPrefix: {
+                        type: "boolean",
+                        default: true,
+                    },
+                    describePattern: {
+                        type: "string",
+                        default: "Story [0-9]+\\.[0-9]+-",
+                    },
+                    autoFixTestTemplate: {
+                        type: "boolean",
+                        default: true,
+                    },
+                    autoFixTestPrefixFormat: {
+                        type: "boolean",
+                        default: true,
+                    },
+                    testSupportsTemplate: {
+                        type: "string",
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            missingFileSupports: "Test file must have @supports annotation listing tested requirements.",
+            missingDescribeStory: "describe() block should reference story (e.g., 'Story 009.0-DEV-...').",
+            missingReqPrefix: "Test name should start with requirement ID (e.g., '[REQ-MAINT-DETECT] ...').",
+        },
+    },
+    create(context) {
+        const filename = context.getFilename();
+        const rawOptions = (context.options && context.options[0]) || {};
+        const { testFilePatterns = [
+            "/tests/",
+            "/test/",
+            "/__tests__",
+            ".test.",
+            ".spec.",
+        ], 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();
+        (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
+            // @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,
+            }),
+        };
+    },
+};
+exports.default = rule;

package/lib/tests/plugin-default-export-and-configs.test.js

@@ -56,6 +56,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
             "valid-story-reference",
             "valid-req-reference",
             "prefer-implements-annotation",
+            "require-test-traceability",
         ];
         // Act: get actual rule names from plugin
         const actual = Object.keys(index_1.rules);
@@ -80,6 +81,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
         expect(recommendedRules).toHaveProperty("traceability/require-branch-annotation", "error");
         expect(recommendedRules).toHaveProperty("traceability/valid-story-reference", "error");
         expect(recommendedRules).toHaveProperty("traceability/valid-req-reference", "error");
+        expect(recommendedRules).toHaveProperty("traceability/require-test-traceability", "error");
     });
     it("[REQ-ERROR-SEVERITY] configs.strict uses same severity mapping as recommended", () => {
         const strictRules = index_1.configs.strict[0].rules;

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

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

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

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for:
+ * - docs/stories/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"));
+const ruleTester = new eslint_1.RuleTester({
+    languageOptions: {
+        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+    },
+});
+describe("require-test-traceability rule (Stories 020.0 and 021.0)", () => {
+    ruleTester.run("require-test-traceability", require_test_traceability_1.default, {
+        valid: [
+            {
+                // [REQ-TEST-FILE-SUPPORTS] file-level @supports present and describe/test satisfied
+                code: `/**\n * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS\n */\ndescribe('Story 020.0-DEV-TEST-ANNOTATION-VALIDATION', () => { it('[REQ-EXAMPLE] does something', () => {}); });`,
+                filename: "tests/rules/require-test-traceability.test.ts",
+            },
+            {
+                // [REQ-TEST-FRAMEWORK-COMPAT] mocha style `context` is treated as a test call but only name checks apply
+                code: `/**\n * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FRAMEWORK-COMPAT\n */\ncontext('Story 020.0-DEV-TEST-ANNOTATION-VALIDATION', () => {});`,
+                filename: "tests/some/context.test.ts",
+            },
+            {
+                // Ensure non-test files are ignored (REQ-TEST-PATTERN-DETECT)
+                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-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 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][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-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.8.3",
+  "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

@@ -189,6 +189,55 @@ function example() {
 }
 ```
 
+### traceability/require-test-traceability
+
+Description: Enforces traceability conventions in test files by requiring:
+
+- A file-level `@supports` annotation indicating which story and requirement(s) the test file exercises.
+- 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. 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:
+
+The rule accepts an optional configuration object:
+
+- `testFilePatterns` (string[], optional) – Glob-style patterns (relative to the project root) used to identify test files. Only files matching at least one pattern are checked by this rule. Defaults to `["**/__tests__/**/*.[jt]s?(x)", "**/?(*.)+(spec|test).[jt]s?(x)"]`.
+- `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:
+
+- The rule only analyzes files whose paths match `testFilePatterns`.
+- File-level `@supports` annotations are typically placed in a JSDoc block at the top of the file; the rule checks that at least one `@supports` tag is present and that it includes a story/requirement reference (for example, `@supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND`).
+- Top-level `describe` calls (such as `describe("payments refunds docs/stories/010.0-PAYMENTS.story.md", ...)`) are inspected when `requireDescribeStory` is `true`. Their first argument must be a string literal that satisfies `describePattern`.
+- Test cases declared via `it(...)` or `test(...)` must use a string literal name beginning with a requirement prefix like `[REQ-PAYMENTS-REFUND]` when `requireTestReqPrefix` is `true`.
+
+Default Severity: `error`
+
+Example:
+
+```javascript
+/**
+ * @supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND
+ */
+
+describe("Refunds flow docs/stories/010.0-PAYMENTS.story.md", () => {
+  it("[REQ-PAYMENTS-REFUND] issues refund on successful request", () => {
+    // ...
+  });
+
+  test("[REQ-PAYMENTS-REFUND-EDGE] handles partial refunds", () => {
+    // ...
+  });
+});
+```
+
 ## Configuration Presets
 
 The plugin provides two built-in presets for easy configuration:
@@ -208,6 +257,7 @@ Core rules enabled by the `recommended` preset:
 - `traceability/valid-annotation-format`: `warn`
 - `traceability/valid-story-reference`: `error`
 - `traceability/valid-req-reference`: `error`
+- `traceability/require-test-traceability`: `error`
 
 Usage: