eslint-plugin-traceability 1.11.2 → 1.11.3

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.11.2](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.11.1...v1.11.2) (2025-12-06)
+## [1.11.3](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.11.2...v1.11.3) (2025-12-06)
 
 
 ### Bug Fixes
 
-* ignore inline-code annotation references in comment normalization ([118d743](https://github.com/voder-ai/eslint-plugin-traceability/commit/118d743ff8c8bf1dcb0854b898480c641cc727c8))
+* ensure catch clause annotations remain valid after prettier formatting ([ca38772](https://github.com/voder-ai/eslint-plugin-traceability/commit/ca3877248d344d7b94ed0059eca9b80b14a04772))
 
 # Changelog
 

package/README.md

@@ -8,7 +8,7 @@ Created autonomously by [voder.ai](https://voder.ai).
 
 ## Installation
 
-Prerequisites: Node.js >=18.18.0 and ESLint v9+.
+Prerequisites: Node.js 18.18.x, 20.x, 22.14.x, or 24.x and ESLint v9+.
 
 1. Using npm  
    npm install --save-dev eslint-plugin-traceability
@@ -55,7 +55,7 @@ export default [
 - `traceability/valid-story-reference` Validates that `@story` references point to existing story files. (See the rule documentation in the plugin's user guide.)
 - `traceability/valid-req-reference` Validates that `@req` references point to existing requirement IDs. (See the rule documentation in the plugin's user guide.)
 - `traceability/require-test-traceability` Enforces traceability conventions in test files by requiring file-level `@supports` annotations, story references in `describe` blocks, and `[REQ-...]` prefixes in `it`/`test` names. (See the rule documentation in the plugin's user guide.)
-- `traceability/prefer-implements-annotation` Recommends migration from legacy `@story`/`@req` annotations to `@supports` (opt-in; disabled by default in the presets and must be explicitly enabled). (See the rule documentation in the plugin's user guide.)
+- `traceability/prefer-supports-annotation` Recommends migration from legacy `@story`/`@req` annotations to `@supports` (opt-in; disabled by default in the presets and must be explicitly enabled). The legacy rule name `traceability/prefer-implements-annotation` remains available as a deprecated alias. (See the rule documentation in the plugin's user guide.)
 
 Configuration options: For detailed per-rule options (such as scopes, branch types, and story directory settings), see the individual rule docs in the plugin's user guide and the consolidated [API Reference](user-docs/api-reference.md).
 

package/lib/src/index.d.ts

@@ -10,13 +10,7 @@ import type { Rule } from "eslint";
  * @req REQ-MAINTENANCE-API-EXPORT - Expose maintenance utilities alongside core plugin exports
  */
 import { detectStaleAnnotations, updateAnnotationReferences, batchUpdateAnnotations, verifyAnnotations, generateMaintenanceReport } from "./maintenance";
-/**
- * @story docs/stories/002.0-DEV-ESLINT-CONFIG.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", "require-test-traceability"];
-type RuleName = (typeof RULE_NAMES)[number];
-declare const rules: Record<RuleName, Rule.RuleModule>;
+declare const rules: Record<string, Rule.RuleModule>;
 /**
  * Plugin metadata used by ESLint for debugging and caching.
  *

package/lib/src/index.js

@@ -74,6 +74,34 @@ RULE_NAMES.forEach(
         };
     }
 });
+/**
+ * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-RULE-NAME
+ * Wire up traceability/prefer-supports-annotation as the primary rule name and
+ * traceability/prefer-implements-annotation as its deprecated alias.
+ */
+{
+    const implementsRule = rules["prefer-implements-annotation"];
+    if (implementsRule) {
+        const originalMeta = implementsRule.meta ?? {};
+        const preferSupportsRule = {
+            ...implementsRule,
+            meta: {
+                ...originalMeta,
+                deprecated: false,
+            },
+        };
+        rules["prefer-supports-annotation"] = preferSupportsRule;
+        const implementsMeta = (implementsRule.meta =
+            implementsRule.meta ?? {});
+        implementsMeta.deprecated = true;
+        implementsMeta.replacedBy = ["prefer-supports-annotation"];
+        if (implementsMeta.docs &&
+            typeof implementsMeta.docs.description === "string") {
+            implementsMeta.docs.description +=
+                " (deprecated alias: use traceability/prefer-supports-annotation instead)";
+        }
+    }
+}
 /**
  * Plugin metadata used by ESLint for debugging and caching.
  *

package/lib/src/utils/branch-annotation-helpers.js

@@ -78,6 +78,61 @@ function validateBranchTypes(context) {
         ? options.branchTypes
         : Array.from(exports.DEFAULT_BRANCH_TYPES);
 }
+/**
+ * Extract the raw value from a comment node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
+ */
+function extractCommentValue(_c) {
+    return _c.value;
+}
+/**
+ * Gather annotation text for CatchClause nodes, supporting both before-catch and inside-catch positions.
+ * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+ * @req REQ-DUAL-POSITION-DETECTION
+ * @req REQ-FALLBACK-LOGIC
+ */
+function gatherCatchClauseCommentText(sourceCode, node, beforeText) {
+    if (/@story\b/.test(beforeText) || /@req\b/.test(beforeText)) {
+        return beforeText;
+    }
+    const getCommentsInside = sourceCode.getCommentsInside;
+    if (node.body && typeof getCommentsInside === "function") {
+        try {
+            const insideComments = getCommentsInside(node.body) || [];
+            const insideText = insideComments.map(extractCommentValue).join(" ");
+            if (insideText) {
+                return insideText;
+            }
+        }
+        catch {
+            // fall through to line-based fallback
+        }
+    }
+    if (node.body && node.body.loc && node.body.loc.start && node.body.loc.end) {
+        const lines = sourceCode.lines;
+        const startIndex = node.body.loc.start.line - 1;
+        const endIndex = node.body.loc.end.line - 1;
+        const comments = [];
+        let i = startIndex + 1;
+        while (i <= endIndex) {
+            const line = lines[i];
+            if (!line || !line.trim()) {
+                break;
+            }
+            if (!/^\s*(\/\/|\/\*)/.test(line)) {
+                break;
+            }
+            comments.push(line.trim());
+            i++;
+        }
+        const insideText = comments.join(" ");
+        if (insideText) {
+            return insideText;
+        }
+    }
+    return beforeText;
+}
 /**
  * Gather leading comment text for a branch node.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -102,16 +157,12 @@ function gatherBranchCommentText(sourceCode, node) {
         }
         return comments.join(" ");
     }
-    const comments = sourceCode.getCommentsBefore(node) || [];
-    /**
-     * Mapper to extract the text value from a comment node.
-     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-     * @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
-     */
-    function commentToValue(c) {
-        return c.value;
+    const beforeComments = sourceCode.getCommentsBefore(node) || [];
+    const beforeText = beforeComments.map(extractCommentValue).join(" ");
+    if (node.type === "CatchClause") {
+        return gatherCatchClauseCommentText(sourceCode, node, beforeText);
     }
-    return comments.map(commentToValue).join(" ");
+    return beforeText;
 }
 /**
  * Report missing @story annotation tag on a branch node when that branch lacks a corresponding @story reference in its comments.
@@ -168,8 +219,8 @@ function reportMissingReq(context, node, options) {
          * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
          * @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer function used to insert missing @req
          */
-        function insertReqFixer(fixer) {
-            return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`);
+        function insertReqFixer(fxer) {
+            return fxer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`);
         }
         context.report({
             node,
@@ -195,11 +246,39 @@ function getBranchAnnotationInfo(sourceCode, node) {
     const text = gatherBranchCommentText(sourceCode, node);
     const missingStory = !/@story\b/.test(text);
     const missingReq = !/@req\b/.test(text);
-    const indent = sourceCode.lines[node.loc.start.line - 1].match(/^(\s*)/)?.[1] || "";
-    const insertPos = sourceCode.getIndexFromLoc({
+    let indent = sourceCode.lines[node.loc.start.line - 1].match(/^(\s*)/)?.[1] || "";
+    let insertPos = sourceCode.getIndexFromLoc({
         line: node.loc.start.line,
         column: 0,
     });
+    if (node.type === "CatchClause" && node.body) {
+        const bodyNode = node.body;
+        const bodyStatements = Array.isArray(bodyNode.body)
+            ? bodyNode.body
+            : undefined;
+        const firstStatement = bodyStatements && bodyStatements.length > 0
+            ? bodyStatements[0]
+            : undefined;
+        if (firstStatement && firstStatement.loc && firstStatement.loc.start) {
+            const firstLine = firstStatement.loc.start.line;
+            const innerIndent = sourceCode.lines[firstLine - 1].match(/^(\s*)/)?.[1] || "";
+            indent = innerIndent;
+            insertPos = sourceCode.getIndexFromLoc({
+                line: firstLine,
+                column: 0,
+            });
+        }
+        else if (bodyNode.loc && bodyNode.loc.start) {
+            const blockLine = bodyNode.loc.start.line;
+            const blockIndent = sourceCode.lines[blockLine - 1].match(/^(\s*)/)?.[1] || "";
+            const innerIndent = `${blockIndent}  `;
+            indent = innerIndent;
+            insertPos = sourceCode.getIndexFromLoc({
+                line: blockLine,
+                column: 0,
+            });
+        }
+    }
     return { missingStory, missingReq, indent, insertPos };
 }
 /**

package/lib/tests/integration/catch-annotation-prettier.integration.test.d.ts

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

package/lib/tests/integration/catch-annotation-prettier.integration.test.js

@@ -0,0 +1,131 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Prettier integration tests for CatchClause annotation positions.
+ * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-PRETTIER-COMPATIBILITY
+ */
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+describe("CatchClause annotations with Prettier (Story 025.0-DEV-CATCH-ANNOTATION-POSITION)", () => {
+    const eslintPkgDir = path_1.default.dirname(require.resolve("eslint/package.json"));
+    const eslintCliPath = path_1.default.join(eslintPkgDir, "bin", "eslint.js");
+    const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");
+    const prettierPackageJson = require.resolve("prettier/package.json");
+    const prettierCliPath = path_1.default.join(path_1.default.dirname(prettierPackageJson), "bin", "prettier.cjs");
+    function runEslintWithRequireBranchAnnotation(code) {
+        const args = [
+            "--no-config-lookup",
+            "--config",
+            configPath,
+            "--stdin",
+            "--stdin-filename",
+            "catch.js",
+            "--rule",
+            "no-unused-vars:off",
+            "--rule",
+            "no-magic-numbers:off",
+            "--rule",
+            "no-undef:off",
+            "--rule",
+            "no-console:off",
+            "--rule",
+            "traceability/require-branch-annotation:error",
+        ];
+        return (0, child_process_1.spawnSync)(process.execPath, [eslintCliPath, ...args], {
+            encoding: "utf-8",
+            input: code,
+        });
+    }
+    function formatWithPrettier(source) {
+        const result = (0, child_process_1.spawnSync)(process.execPath, [prettierCliPath, "--parser", "typescript"], {
+            encoding: "utf-8",
+            input: source,
+        });
+        if (result.status !== 0) {
+            throw new Error(`Prettier formatting failed: ${result.stderr || result.stdout}`);
+        }
+        return result.stdout;
+    }
+    it("[REQ-PRETTIER-COMPATIBILITY-BEFORE] accepts code where annotations start before catch but are moved inside by Prettier", () => {
+        const original = `
+function doSomething() {
+  return 42;
+}
+
+function handleError(error) {
+  console.error(error);
+}
+
+// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-TRY
+try {
+  doSomething();
+}
+// @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+// @req REQ-CATCH-PATH
+catch (error) {
+  handleError(error);
+}
+`;
+        const formatted = formatWithPrettier(original);
+        // Sanity check: Prettier should move the branch annotations inside the catch body.
+        expect(formatted).toContain("catch (error) {");
+        const catchIndex = formatted.indexOf("catch (error) {");
+        const storyIndex = formatted.indexOf("@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md");
+        expect(storyIndex).toBeGreaterThan(catchIndex);
+        const result = runEslintWithRequireBranchAnnotation(formatted);
+        expect(result.status).toBe(0);
+    });
+    it("[REQ-PRETTIER-COMPATIBILITY-INSIDE] accepts code where annotations start inside the catch body and are preserved by Prettier", () => {
+        const original = `
+function doSomething() {
+  return 42;
+}
+
+function handleError(error) {
+  console.error(error);
+}
+
+// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-TRY
+try {
+  doSomething();
+} catch (error) {
+  // @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+  // @req REQ-CATCH-INSIDE
+  handleError(error);
+}
+`;
+        const formatted = formatWithPrettier(original);
+        // Sanity: annotations should still be associated with the catch body after formatting.
+        expect(formatted).toContain("catch (error) {");
+        const catchIndex = formatted.indexOf("catch (error) {");
+        const storyIndex = formatted.indexOf("@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md");
+        expect(storyIndex).toBeGreaterThan(catchIndex);
+        const result = runEslintWithRequireBranchAnnotation(formatted);
+        expect(result.status).toBe(0);
+    });
+    it("[REQ-PRETTIER-COMPATIBILITY-EMPTY] accepts empty catch blocks with inside-catch annotations after Prettier formatting", () => {
+        const original = `
+function doSomething() {
+  return 42;
+}
+
+// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-TRY
+try {
+  doSomething();
+} catch (error) {
+  // @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+  // @req REQ-CATCH-EMPTY
+}
+`;
+        const formatted = formatWithPrettier(original);
+        const result = runEslintWithRequireBranchAnnotation(formatted);
+        expect(result.status).toBe(0);
+    });
+});

package/lib/tests/perf/valid-annotation-format-large-file.test.d.ts

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

package/lib/tests/perf/valid-annotation-format-large-file.test.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Performance tests for valid-annotation-format on large annotated files.
+ *
+ * @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-MULTILINE-SUPPORT REQ-FLEXIBLE-PARSING REQ-SYNTAX-VALIDATION
+ */
+const eslint_1 = require("eslint");
+const perf_hooks_1 = require("perf_hooks");
+const valid_annotation_format_1 = __importDefault(require("../../src/rules/valid-annotation-format"));
+/**
+ * Build a large source file containing many functions with traceability
+ * annotations in both line and block comments.
+ *
+ * The generated code mixes valid and invalid annotation formats to exercise
+ * parsing, multi-line handling, and error-reporting paths at scale without
+ * relying on auto-fix.
+ */
+function buildLargeAnnotatedSource(functionCount, annotationsPerFunction) {
+    const lines = [];
+    for (let i = 0; i < functionCount; i += 1) {
+        // JSDoc-style block comment with multi-line @story/@req values.
+        lines.push("/**");
+        lines.push(" * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md");
+        lines.push(" * @req REQ-FORMAT-SPECIFICATION");
+        lines.push(" */");
+        // Additional line comments with a mix of valid and intentionally
+        // invalid formats (missing extensions, traversal, malformed IDs).
+        for (let j = 0; j < annotationsPerFunction; j += 1) {
+            const selector = (i + j) % 4;
+            if (selector === 0) {
+                lines.push("// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story");
+            }
+            else if (selector === 1) {
+                lines.push("// @req REQ-EXAMPLE-" + i.toString(10));
+            }
+            else if (selector === 2) {
+                lines.push("// @story ../outside-project.story.md");
+            }
+            else {
+                lines.push("// @req invalid-format-id");
+            }
+        }
+        lines.push(`function annotated_fn_${i}() {`);
+        lines.push('  return "ok";\n}');
+    }
+    return lines.join("\n");
+}
+describe("valid-annotation-format performance on large annotated files (Story 005.0-DEV-ANNOTATION-VALIDATION)", () => {
+    const ruleName = "traceability/valid-annotation-format";
+    it("[REQ-MULTILINE-SUPPORT][REQ-FLEXIBLE-PARSING] analyzes a large annotated file within a generous time budget", () => {
+        const linter = new eslint_1.Linter({ configType: "eslintrc" });
+        linter.defineRule(ruleName, valid_annotation_format_1.default);
+        // 150 functions each with several annotations provides a substantial
+        // volume of comments and annotation patterns without being extreme.
+        const source = buildLargeAnnotatedSource(150, 3);
+        const start = perf_hooks_1.performance.now();
+        const messages = linter.verify(source, {
+            parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+            rules: {
+                [ruleName]: "error",
+            },
+        });
+        const durationMs = perf_hooks_1.performance.now() - start;
+        // Sanity check: we expect diagnostics for some invalid annotations so the
+        // rule is definitely executing its validation logic.
+        expect(messages.length).toBeGreaterThan(0);
+        // Guardrail: keep analysis comfortably under ~5 seconds on CI hardware.
+        expect(durationMs).toBeLessThan(5000);
+    });
+});

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

@@ -59,6 +59,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
             "valid-req-reference",
             "prefer-implements-annotation",
             "require-test-traceability",
+            "prefer-supports-annotation",
         ];
         // Act: get actual rule names from plugin
         const actual = Object.keys(index_1.rules);

package/lib/tests/rules/prefer-implements-annotation.test.js

@@ -18,80 +18,87 @@ const ruleTester = new eslint_1.RuleTester({
         parserOptions: { ecmaVersion: 2020, sourceType: "module" },
     },
 });
-describe("prefer-implements-annotation rule (Story 010.3-DEV-MIGRATE-TO-SUPPORTS)", () => {
-    ruleTester.run("prefer-implements-annotation", prefer_implements_annotation_1.default, {
-        valid: [
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @story is ignored",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction onlyStory() {}`,
-            },
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @req is ignored",
-                code: `/**\n * @req REQ-ONLY\n */\nfunction onlyReq() {}`,
-            },
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @supports only is ignored",
-                code: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction alreadyImplements() {}`,
-            },
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @story and @supports but no @req is ignored",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction storyAndSupportsNoReq() {}`,
-            },
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @req and @supports but no @story is ignored",
-                code: `/**\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction reqAndSupportsNoStory() {}`,
-            },
-        ],
-        invalid: [
-            {
-                name: "[REQ-OPTIONAL-WARNING] single-story @story + @req block triggers preferImplements message",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
-                output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-MULTI-STORY-DETECT] mixed @story/@req and @supports triggers cannotAutoFix",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction mixed() {}`,
-                errors: [
-                    {
-                        messageId: "cannotAutoFix",
-                        data: {
-                            reason: "comment mixes @story/@req with existing @supports annotations",
-                        },
+describe("prefer-supports-annotation / prefer-implements-annotation aliasing (Story 010.3-DEV-MIGRATE-TO-SUPPORTS)", () => {
+    const valid = [
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @story is ignored",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction onlyStory() {}`,
+        },
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @req is ignored",
+            code: `/**\n * @req REQ-ONLY\n */\nfunction onlyReq() {}`,
+        },
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @supports only is ignored",
+            code: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction alreadyImplements() {}`,
+        },
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @story and @supports but no @req is ignored",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction storyAndSupportsNoReq() {}`,
+        },
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @req and @supports but no @story is ignored",
+            code: `/**\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction reqAndSupportsNoStory() {}`,
+        },
+    ];
+    const invalid = [
+        {
+            name: "[REQ-OPTIONAL-WARNING] single-story @story + @req block triggers preferImplements message",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
+            output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-MULTI-STORY-DETECT] mixed @story/@req and @supports triggers cannotAutoFix",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction mixed() {}`,
+            errors: [
+                {
+                    messageId: "cannotAutoFix",
+                    data: {
+                        reason: "comment mixes @story/@req with existing @supports annotations",
                     },
-                ],
-            },
-            {
-                name: "[REQ-MULTI-STORY-DETECT] multiple @story paths in same block trigger multiStoryDetected",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n * @req REQ-BRANCH-DETECTION\n */\nfunction multiStory() {}`,
-                errors: [{ messageId: "multiStoryDetected" }],
-            },
-            {
-                name: "[REQ-AUTO-FIX] single @story + single @req auto-fixes to single @supports line",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
-                output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-SINGLE-STORY-FIX] single @story with multiple @req lines auto-fixes to single @supports line containing all REQ IDs",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ONE\n * @req REQ-TWO\n * @req REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
-                output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ONE REQ-TWO REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-AUTO-FIX] complex @req content (extra description) does not auto-fix but still warns",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED must handle extra description\n */\nfunction complexReqNoAutoFix() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-AUTO-FIX] complex @story content (extra description) does not auto-fix but still warns",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md additional descriptive text\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction complexStoryNoAutoFix() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-        ],
+                },
+            ],
+        },
+        {
+            name: "[REQ-MULTI-STORY-DETECT] multiple @story paths in same block trigger multiStoryDetected",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n * @req REQ-BRANCH-DETECTION\n */\nfunction multiStory() {}`,
+            errors: [{ messageId: "multiStoryDetected" }],
+        },
+        {
+            name: "[REQ-AUTO-FIX] single @story + single @req auto-fixes to single @supports line",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
+            output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-SINGLE-STORY-FIX] single @story with multiple @req lines auto-fixes to single @supports line containing all REQ IDs",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ONE\n * @req REQ-TWO\n * @req REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
+            output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ONE REQ-TWO REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-AUTO-FIX] complex @req content (extra description) does not auto-fix but still warns",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED must handle extra description\n */\nfunction complexReqNoAutoFix() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-AUTO-FIX] complex @story content (extra description) does not auto-fix but still warns",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md additional descriptive text\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction complexStoryNoAutoFix() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+    ];
+    ruleTester.run("prefer-implements-annotation", prefer_implements_annotation_1.default, {
+        valid,
+        invalid,
+    });
+    ruleTester.run("prefer-supports-annotation", prefer_implements_annotation_1.default, {
+        valid,
+        invalid,
     });
 });
 describe("prefer-implements-annotation configuration severity (REQ-CONFIG-SEVERITY)", () => {
+    // Story 010.3 / REQ-RULE-NAME: verify aliasing semantics for new primary rule name and deprecated alias
     test("rule is disabled by default in recommended and strict presets (not present in preset rule maps)", () => {
         const recommended = src_1.configs.recommended;
         expect(Array.isArray(recommended)).toBe(true);
@@ -99,27 +106,34 @@ describe("prefer-implements-annotation configuration severity (REQ-CONFIG-SEVERI
         expect(firstConfig).toBeDefined();
         const rules = firstConfig.rules || {};
         expect(rules["traceability/prefer-implements-annotation"]).toBeUndefined();
+        expect(rules["traceability/prefer-supports-annotation"]).toBeUndefined();
         const strict = src_1.configs.strict;
         expect(Array.isArray(strict)).toBe(true);
         const strictFirstConfig = strict[0];
         expect(strictFirstConfig).toBeDefined();
         const strictRules = strictFirstConfig.rules || {};
         expect(strictRules["traceability/prefer-implements-annotation"]).toBeUndefined();
+        expect(strictRules["traceability/prefer-supports-annotation"]).toBeUndefined();
     });
     test("rule can be configured with severity 'warn' or 'error' in flat config", () => {
+        // Story 010.3 / REQ-RULE-NAME: both primary and alias rule keys must be accepted in flat config
         const flatWarnConfig = {
             files: ["**/*.ts"],
             rules: {
                 "traceability/prefer-implements-annotation": "warn",
+                "traceability/prefer-supports-annotation": "warn",
             },
         };
         expect(flatWarnConfig.rules["traceability/prefer-implements-annotation"]).toBe("warn");
+        expect(flatWarnConfig.rules["traceability/prefer-supports-annotation"]).toBe("warn");
         const flatErrorConfig = {
             files: ["**/*.ts"],
             rules: {
                 "traceability/prefer-implements-annotation": "error",
+                "traceability/prefer-supports-annotation": "error",
             },
         };
         expect(flatErrorConfig.rules["traceability/prefer-implements-annotation"]).toBe("error");
+        expect(flatErrorConfig.rules["traceability/prefer-supports-annotation"]).toBe("error");
     });
 });

package/lib/tests/utils/branch-annotation-catch-insert-position.test.d.ts

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

package/lib/tests/utils/branch-annotation-catch-insert-position.test.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Unit tests for CatchClause insert position calculation.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-PRETTIER-AUTOFIX
+ */
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+describe("CatchClause insert position (Story 025.0-DEV-CATCH-ANNOTATION-POSITION)", () => {
+    it("[REQ-PRETTIER-AUTOFIX] inserts annotations at the first statement inside the catch body", () => {
+        const lines = [
+            "try {",
+            "  doSomething();",
+            "}",
+            "catch (error) {",
+            "  handleError(error);",
+            "}",
+        ];
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const context = {
+            getSourceCode() {
+                return {
+                    lines,
+                    getCommentsBefore() {
+                        return [];
+                    },
+                    getIndexFromLoc({ line, column }) {
+                        // simple line/column to index mapping for the test: assume each line ends with "\n"
+                        const prefix = lines.slice(0, line - 1).join("\n");
+                        return prefix.length + (line > 1 ? 1 : 0) + column;
+                    },
+                };
+            },
+            report({ fix }) {
+                // immediately invoke the fixer to exercise the insert position
+                if (typeof fix === "function") {
+                    fix(fixer);
+                }
+            },
+        };
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 4 } },
+            body: {
+                type: "BlockStatement",
+                loc: { start: { line: 4 } },
+                body: [
+                    {
+                        type: "ExpressionStatement",
+                        loc: { start: { line: 5 } },
+                    },
+                ],
+            },
+        };
+        const storyFixCountRef = { count: 0 };
+        (0, branch_annotation_helpers_1.reportMissingAnnotations)(context, node, storyFixCountRef);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
+        const [range, text] = fixer.insertTextBeforeRange.mock.calls[0];
+        // ensure we are inserting before the first statement in the catch body (line 5)
+        const expectedIndex = context.getSourceCode().getIndexFromLoc({ line: 5, column: 0 });
+        expect(range).toEqual([expectedIndex, expectedIndex]);
+        // and that the inserted text is prefixed with the inner indentation from line 5
+        expect(text.startsWith("  ")).toBe(true);
+    });
+});

package/lib/tests/utils/branch-annotation-catch-position.test.d.ts

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

package/lib/tests/utils/branch-annotation-catch-position.test.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+function createMockSourceCode(options) {
+    const { lines = [], commentsBefore = [], commentsInside = [] } = options;
+    return {
+        lines,
+        getCommentsBefore() {
+            return commentsBefore;
+        },
+        getCommentsInside(node) {
+            // exercise the code path that passes node.body into getCommentsInside
+            if (node && node.type === "BlockStatement") {
+                return commentsInside;
+            }
+            return [];
+        },
+    };
+}
+describe("gatherBranchCommentText CatchClause behavior (Story 025.0-DEV-CATCH-ANNOTATION-POSITION)", () => {
+    it("[REQ-DUAL-POSITION-DETECTION] prefers before-catch annotations when present", () => {
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [
+                { value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md" },
+                { value: "@req REQ-BRANCH-DETECTION" },
+            ],
+            commentsInside: [
+                { value: "@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md" },
+            ],
+        });
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 5 } },
+            body: { type: "BlockStatement" },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(text).toContain("@req REQ-BRANCH-DETECTION");
+    });
+    it("[REQ-FALLBACK-LOGIC] falls back to inside-catch annotations when before-catch is missing", () => {
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [],
+            commentsInside: [
+                { value: "@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md" },
+                { value: "@req REQ-CATCH-PATH" },
+            ],
+        });
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 10 } },
+            body: { type: "BlockStatement" },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-CATCH-PATH");
+    });
+    it("[REQ-FALLBACK-LOGIC] returns before-catch text when getCommentsInside is not available", () => {
+        const lines = [
+            "try {",
+            "  doSomething();",
+            "}",
+            "catch (error) {",
+            "  // body",
+            "}",
+        ];
+        const sourceCode = {
+            lines,
+            getCommentsBefore() {
+                return [
+                    { value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md" },
+                    { value: "@req REQ-BRANCH-DETECTION" },
+                ];
+            },
+            // intentionally omit getCommentsInside so that the CatchClause path
+            // falls back to the before-catch comments.
+        };
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 4 } },
+            body: { type: "BlockStatement" },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(text).toContain("@req REQ-BRANCH-DETECTION");
+    });
+    it("[REQ-FALLBACK-LOGIC] collects inside-catch comments using line-based fallback when getCommentsInside is unavailable", () => {
+        const lines = [
+            "try {",
+            "  doSomething();",
+            "} catch (error) {",
+            "  // @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md",
+            "  // @req REQ-CATCH-LINE-FALLBACK",
+            "  handleError(error);",
+            "}",
+        ];
+        const sourceCode = {
+            lines,
+            getCommentsBefore() {
+                return [];
+            },
+        };
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 3 } },
+            body: {
+                type: "BlockStatement",
+                loc: { start: { line: 3 }, end: { line: 7 } },
+                body: [],
+            },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-CATCH-LINE-FALLBACK");
+    });
+});

package/lib/tests/utils/req-annotation-detection.test.d.ts

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

package/lib/tests/utils/req-annotation-detection.test.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const reqAnnotationDetection_1 = require("../../src/utils/reqAnnotationDetection");
+// Small helper to construct a minimal SourceCode-like object for the detection helpers.
+function createMockSourceCode(options = {}) {
+    const { lines = null, text = "", commentsBefore = [] } = options;
+    return {
+        lines: lines ?? undefined,
+        getText() {
+            return text;
+        },
+        getCommentsBefore() {
+            return commentsBefore;
+        },
+    };
+}
+describe("reqAnnotationDetection advanced heuristics (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
+    it("[REQ-ANNOTATION-REQ-DETECTION] returns false when sourceCode is missing", () => {
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], undefined, {
+            loc: null,
+        });
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] returns false when node is missing", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({ lines: ["/** @req REQ-TEST */"] });
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, undefined);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] inspects jsdoc and comments when advanced heuristics throw", () => {
+        const context = {
+            getSourceCode() {
+                // This object intentionally causes hasReqInAdvancedHeuristics to throw by
+                // providing a getCommentsBefore implementation that throws on access.
+                return {
+                    getCommentsBefore() {
+                        throw new Error("boom");
+                    },
+                };
+            },
+        };
+        const jsdoc = { value: "/** @req REQ-FROM-JSDOC */" };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, {
+            // Minimal shape – the helper will call into the mock sourceCode and trigger the throw
+            parent: {},
+        });
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] treats @supports in comments as satisfying requirement", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode();
+            },
+        };
+        const comments = [{ value: "// @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-X" }];
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, comments, context, {
+            parent: {},
+        });
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] linesBeforeHasReq returns false when lines is not an array", () => {
+        const context = {
+            getSourceCode() {
+                // lines is null here, causing the helper to see a non-array and return false
+                return createMockSourceCode({ lines: null });
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, {
+            // Provide a minimal location so advanced heuristics try to use line info
+            loc: { start: { line: 5 } },
+            parent: {},
+        });
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] linesBeforeHasReq returns false when startLine is not a number", () => {
+        const sourceCode = createMockSourceCode({ lines: ["// @req REQ-SHOULD-NOT-BE-SEEN"] });
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], { getSourceCode: () => sourceCode }, {
+            // loc is missing/undefined; startLine will not be a valid number
+            loc: undefined,
+            parent: {},
+        });
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] parentChainHasReq returns false when getCommentsBefore is not a function and no leadingComments/parents have req", () => {
+        const context = {
+            getSourceCode() {
+                return {
+                    // getCommentsBefore is not a function here
+                    getCommentsBefore: 123,
+                };
+            },
+        };
+        const node = {
+            parent: {
+                leadingComments: [{ value: "no req here" }],
+                parent: {
+                    leadingComments: [{ value: "still nothing" }],
+                },
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] parentChainHasReq returns true when getCommentsBefore returns comments containing @req", () => {
+        const sourceCode = {
+            getCommentsBefore(n) {
+                if (n && n.isTargetParent) {
+                    return [{ value: "/* @req REQ-FROM-PARENT */" }];
+                }
+                return [];
+            },
+        };
+        const context = {
+            getSourceCode() {
+                return sourceCode;
+            },
+        };
+        const node = {
+            parent: {
+                isTargetParent: true,
+                parent: {},
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when getText is not a function", () => {
+        const context = {
+            getSourceCode() {
+                return {
+                    // getText is not a function
+                    getText: "not-a-function",
+                };
+            },
+        };
+        const node = {
+            range: [0, 10],
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when node.range is not an array", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({ text: "/* @req REQ-IN-TEXT */" });
+            },
+        };
+        const node = {
+            // range is missing; helper should see non-array range and return false
+            range: null,
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns true when text window contains @req", () => {
+        const fullText = `
+      // some header
+      /** @req REQ-IN-TEXT-WINDOW */
+      function foo() {}
+    `;
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({ text: fullText });
+            },
+        };
+        // Choose a range that starts after the @req comment so the "text before"
+        // window that the helper inspects includes the annotation.
+        const startIndex = fullText.indexOf("function foo");
+        const node = {
+            range: [startIndex, startIndex + 5],
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when getText throws", () => {
+        const context = {
+            getSourceCode() {
+                return {
+                    getText() {
+                        throw new Error("boom from getText");
+                    },
+                };
+            },
+        };
+        const node = {
+            range: [0, 10],
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqInAdvancedHeuristics short-circuits and returns false when sourceCode is missing", () => {
+        const context = {
+        // No getSourceCode method at all – internal advanced heuristics
+        // should immediately return false and not throw.
+        };
+        const node = {
+            loc: { start: { line: 3 } },
+            range: [0, 10],
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqInAdvancedHeuristics short-circuits and returns false when node is missing", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({ text: "@req REQ-SHOULD-NOT-BE-SEEN" });
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, undefined);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqAnnotation returns true when jsdoc contains @supports and advanced heuristics are false", () => {
+        const context = {
+            getSourceCode() {
+                // Returning a sourceCode that will not satisfy any advanced heuristic
+                // (no lines, no comments, empty text).
+                return createMockSourceCode({ lines: [], text: "" });
+            },
+        };
+        const jsdoc = {
+            value: "/** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-JSDOC-SUPPORTS */",
+        };
+        const node = {
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] falls back to jsdoc/comments when context.getSourceCode throws", () => {
+        const context = {
+            getSourceCode() {
+                throw new Error("boom from getSourceCode");
+            },
+        };
+        const jsdoc = { value: "/** @req REQ-FROM-GETSOURCECODE */" };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, { parent: {} });
+        expect(has).toBe(true);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.11.2",
+  "version": "1.11.3",
   "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",
@@ -41,7 +41,7 @@
     "safety:deps": "node scripts/ci-safety-deps.js",
     "audit:ci": "node scripts/ci-audit.js",
     "check:ci-artifacts": "node scripts/check-no-tracked-ci-artifacts.js",
-    "security:secrets": "secretlint \"**/*\" --no-color",
+    "security:secrets": "secretlint \"**/*\"",
     "smoke-test": "./scripts/smoke-test.sh",
     "debug:cli": "node scripts/cli-debug.js",
     "debug:require-story": "node scripts/debug-require-story.js",
@@ -99,7 +99,7 @@
     "eslint": "^9.0.0"
   },
   "engines": {
-    "node": ">=18.18.0"
+    "node": "^18.18.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
   },
   "overrides": {
     "glob": "12.0.0",

package/user-docs/api-reference.md

@@ -15,7 +15,7 @@ In addition to the core `@story` and `@req` annotations, the plugin also underst
 `@supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND`
 to indicate that a given function supports a particular requirement from a payments story document within that project’s own `docs/stories` tree. For a detailed explanation of `@supports` behavior and validation, see [Migration Guide](migration-guide.md) (section **3.1 Multi-story @supports annotations**). Additional background on multi-story semantics is available in the project’s internal rule documentation, which is intended for maintainers rather than end users.
 
-The `prefer-implements-annotation` rule is an **opt-in migration helper** that is disabled by default and **not** part of any built-in preset. It can be enabled and given a severity like `"warn"` or `"error"` using normal ESLint rule configuration when you want to gradually encourage multi-story `@supports` usage. Detailed behavior and migration guidance are documented in the project’s internal rule documentation, which is targeted at maintainers; typical end users can rely on the high-level guidance in this API reference and the [Migration Guide](migration-guide.md).
+The `prefer-supports-annotation` rule is an **opt-in migration helper** that is disabled by default and **not** part of any built-in preset. It can be enabled and given a severity like `"warn"` or `"error"` using normal ESLint rule configuration when you want to gradually encourage multi-story `@supports` usage. The legacy rule key `traceability/prefer-implements-annotation` remains available as a **deprecated alias** for backward compatibility, but new configurations should prefer `traceability/prefer-supports-annotation`. Detailed behavior and migration guidance are documented in the project’s internal rule documentation, which is targeted at maintainers; typical end users can rely on the high-level guidance in this API reference and the [Migration Guide](migration-guide.md).
 
 ### traceability/require-story-annotation
 
@@ -68,11 +68,17 @@ function initAuth() {
 
 ### traceability/require-branch-annotation
 
-Description: Ensures significant code branches (if/else, loops, switch cases, try/catch) have both `@story` and `@req` annotations in preceding comments.
+Description: Ensures significant code branches (if/else, loops, switch cases, try/catch) have both `@story` and `@req` annotations in preceding comments. For `catch` clauses specifically, the rule accepts annotations either immediately before the `catch` keyword or as the first comment-only lines inside the catch block. This dual-position handling is designed to stay compatible with common formatters such as Prettier, which often move comments from before `catch` into the catch body.
+
 Options:
 
 - `branchTypes` (string[], optional) – AST node types that are treated as significant branches for annotation enforcement. Allowed values: "IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement". Default: ["IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement"]. If an invalid branch type is provided, the rule reports a configuration error for each invalid value.
 
+Behavior notes:
+
+- When both before-`catch` and inside-block annotations are present for the same catch clause, the comments immediately before `catch` take precedence for validation and reporting.
+- When auto-fixing missing annotations on a catch clause, the rule inserts placeholder comments inside the catch body so that formatters like Prettier preserve them and do not move them to unexpected locations.
+
 Default Severity: `error`
 Example:
 
@@ -246,9 +252,9 @@ describe("Refunds flow docs/stories/010.0-PAYMENTS.story.md", () => {
 });
 ```
 
-### traceability/prefer-implements-annotation
+### traceability/prefer-supports-annotation
 
-Description: An optional, opt-in migration helper that encourages converting legacy single‑story `@story` + `@req` JSDoc blocks into the newer multi‑story `@supports` format. The rule is **disabled by default** and is **not included in any built‑in preset**; you enable it explicitly and control its behavior entirely via ESLint severity (`"off" | "warn" | "error"`). It does not change what the core rules consider valid—it only adds migration recommendations and safe auto‑fixes on top of existing validation.
+Description: An optional, opt-in migration helper that encourages converting legacy single‑story `@story` + `@req` JSDoc blocks into the newer multi‑story `@supports` format. The rule is **disabled by default** and is **not included in any built‑in preset**; you enable it explicitly and control its behavior entirely via ESLint severity (`"off" | "warn" | "error"`). It does not change what the core rules consider valid—it only adds migration recommendations and safe auto‑fixes on top of existing validation. The legacy rule key `traceability/prefer-implements-annotation` is still recognized as a **deprecated alias** for `traceability/prefer-supports-annotation` so that existing configurations continue to work unchanged.
 
 Options: None – this rule does not accept a configuration object. All tuning is done via the ESLint rule level (`"off"`, `"warn"`, `"error"`).
 
@@ -318,7 +324,7 @@ function issueRefund() {
 }
 ```
 
-With `traceability/prefer-implements-annotation` enabled and ESLint run with `--fix`, the rule rewrites it to:
+With `traceability/prefer-supports-annotation` enabled (or its deprecated alias `traceability/prefer-implements-annotation`) and ESLint run with `--fix`, the rule rewrites it to:
 
 ```js
 /**
@@ -343,7 +349,9 @@ export default [
   traceability.configs.recommended,
   {
     rules: {
-      "traceability/prefer-implements-annotation": "warn",
+      "traceability/prefer-supports-annotation": "warn",
+      // The deprecated alias is still honored if you prefer:
+      // "traceability/prefer-implements-annotation": "warn",
     },
   },
 ];
@@ -358,7 +366,7 @@ The plugin provides two built-in presets for easy configuration:
 Enables the **six core traceability rules** with severities tuned for common usage (most at `error`, with
 `traceability/valid-annotation-format` at `warn` to reduce noise). This `warn` level for `traceability/valid-annotation-format` is intentional to keep early adoption noise low, but you can safely raise it to `error` in projects that want strict enforcement of annotation formatting.
 
-The `prefer-implements-annotation` migration rule is **not included** in this (or any) preset and remains disabled by default. If you want to encourage or enforce multi-story `@supports` annotations, you must enable `traceability/prefer-implements-annotation` explicitly in your ESLint configuration and choose an appropriate severity (for example, `"warn"` during migration or `"error"` once fully adopted).
+The `prefer-supports-annotation` migration rule (and its deprecated alias key `traceability/prefer-implements-annotation`) is **not included** in this (or any) preset and remains disabled by default. If you want to encourage or enforce multi-story `@supports` annotations, you must enable `traceability/prefer-supports-annotation` explicitly in your ESLint configuration and choose an appropriate severity (for example, `"warn"` during migration or `"error"` once fully adopted).
 
 Core rules enabled by the `recommended` preset:
 
@@ -381,7 +389,7 @@ export default [js.configs.recommended, traceability.configs.recommended];
 
 ### strict
 
-Currently mirrors the **recommended** preset, reserved for future stricter policies. As with the `recommended` preset, the `traceability/prefer-implements-annotation` rule is **not** enabled here by default and must be configured manually if desired.
+Currently mirrors the **recommended** preset, reserved for future stricter policies. As with the `recommended` preset, the `traceability/prefer-supports-annotation` rule is **not** enabled here by default, and the deprecated alias key `traceability/prefer-implements-annotation` continues to be honored only when you opt into it manually in your own configuration.
 
 Usage:
 

package/user-docs/migration-guide.md

@@ -57,18 +57,22 @@ function integrate() {}
 
 You **do not** need to change existing, single-story annotations that already use `@story` and `@req`. Migration to `@supports` is only recommended when a function or module genuinely implements requirements from more than one story file.
 
-#### Optional `prefer-implements-annotation` migration rule
+#### Optional `prefer-supports-annotation` migration rule
 
-For teams that want to gradually migrate from `@story` + `@req` to `@supports`, the plugin provides an optional rule: `traceability/prefer-implements-annotation`.
+For teams that want to gradually migrate from `@story` + `@req` to `@supports`, the plugin provides an optional rule: `traceability/prefer-supports-annotation`.
 
-- This rule is **disabled by default** and is **not** included in any built-in presets.
+- This is the canonical rule name starting in v1.x.
+- The legacy key `traceability/prefer-implements-annotation` remains supported as a **deprecated alias** for backward compatibility, but should not be used in new configurations.
+
+- This rule is **disabled by default** and is **not** included in any built-in presets (the deprecated alias is also not enabled by any presets).
 - You can enable it with any standard ESLint severity (`"off"`, `"warn"`, or `"error"`) in your config, for example:
 
   ```js
   // excerpt from eslint.config.js
   {
     rules: {
-      "traceability/prefer-implements-annotation": "warn",
+      "traceability/prefer-supports-annotation": "warn",
+      // "traceability/prefer-implements-annotation": "warn", // deprecated alias
     },
   }
   ```
@@ -101,7 +105,7 @@ Aligned with the internal rule behavior, the key cases are:
   - Comments that contain only `@supports` lines, and
   - Line comments such as `// @story ...`.
 
-  These forms are still supported by the plugin and are not modified by `traceability/prefer-implements-annotation`.
+  These forms are still supported by the plugin and are not modified by `traceability/prefer-supports-annotation`.
 
 A typical migration path is: