eslint-plugin-traceability 1.11.4 → 1.12.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.11.4](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.11.3...v1.11.4) (2025-12-06)
+# [1.12.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.11.4...v1.12.0) (2025-12-07)
 
 
-### Bug Fixes
+### Features
 
-* add else-if branch annotation support and tests ([15652db](https://github.com/voder-ai/eslint-plugin-traceability/commit/15652db094d23a261a39acaab76de585f460fda3))
+* accept [@supports](https://github.com/supports) annotations on branches as alternative format ([6773a3a](https://github.com/voder-ai/eslint-plugin-traceability/commit/6773a3ae190e9b9adc605c7d17112f44401e5b24))
 
 # Changelog
 

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

@@ -86,6 +86,25 @@ function validateBranchTypes(context) {
 function extractCommentValue(_c) {
     return _c.value;
 }
+/**
+ * Collect a single contiguous comment line at the given index, appending its
+ * trimmed text to the accumulator. Returns true when a valid comment was
+ * collected and false when scanning should stop (blank or non-comment line).
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
+ */
+function collectCommentLine(lines, index, comments) {
+    const line = lines[index];
+    if (!line || !line.trim()) {
+        return false;
+    }
+    if (!/^\s*(\/\/|\/\*)/.test(line)) {
+        return false;
+    }
+    comments.push(line.trim());
+    return true;
+}
 function isElseIfBranch(node, parent) {
     return (node &&
         node.type === "IfStatement" &&
@@ -123,14 +142,9 @@ function gatherCatchClauseCommentText(sourceCode, node, beforeText) {
         const comments = [];
         let i = startIndex + 1;
         while (i <= endIndex) {
-            const line = lines[i];
-            if (!line || !line.trim()) {
-                break;
-            }
-            if (!/^\s*(\/\/|\/\*)/.test(line)) {
+            if (!collectCommentLine(lines, i, comments)) {
                 break;
             }
-            comments.push(line.trim());
             i++;
         }
         const insideText = comments.join(" ");
@@ -140,9 +154,75 @@ function gatherCatchClauseCommentText(sourceCode, node, beforeText) {
     }
     return beforeText;
 }
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+function scanElseIfPrecedingComments(sourceCode, node) {
+    const lines = sourceCode.lines;
+    if (!node.loc || !node.loc.start || typeof node.loc.start.line !== "number") {
+        return "";
+    }
+    const startLine = node.loc.start.line - 1;
+    const comments = [];
+    let i = startLine - 1;
+    let scanned = 0;
+    while (i >= 0 && scanned < PRE_COMMENT_OFFSET) {
+        const line = lines[i];
+        if (!line || !line.trim()) {
+            break;
+        }
+        if (!/^\s*(\/\/|\/\*)/.test(line)) {
+            break;
+        }
+        comments.unshift(line.trim());
+        i--;
+        scanned++;
+    }
+    return comments.join(" ");
+}
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+function hasValidElseIfBlockLoc(node) {
+    const hasBlockConsequent = node.consequent &&
+        node.consequent.type === "BlockStatement" &&
+        node.consequent.loc &&
+        node.consequent.loc.start;
+    return !!(node.test &&
+        node.test.loc &&
+        node.test.loc.end &&
+        hasBlockConsequent);
+}
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+function scanElseIfBetweenConditionAndBody(sourceCode, node) {
+    const lines = sourceCode.lines;
+    const conditionEndLine = node.test.loc.end.line;
+    const consequentStartLine = node.consequent.loc.start.line;
+    const comments = [];
+    for (let lineIndex = conditionEndLine; lineIndex < consequentStartLine - 1; lineIndex++) {
+        if (!collectCommentLine(lines, lineIndex, comments)) {
+            break;
+        }
+    }
+    return comments.join(" ");
+}
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+function scanElseIfInsideBlockComments(sourceCode, node) {
+    const lines = sourceCode.lines;
+    const consequentStartLine = node.consequent.loc.start.line;
+    const comments = [];
+    // Intentionally start from the block's start line (using the same 1-based line value as provided by the parser)
+    // so that, when indexing into sourceCode.lines, this corresponds to the first logical line inside the block body
+    // for typical formatter layouts.
+    let lineIndex = consequentStartLine;
+    while (lineIndex < lines.length) {
+        if (!collectCommentLine(lines, lineIndex, comments)) {
+            break;
+        }
+        lineIndex++;
+    }
+    return comments.join(" ");
+}
 /**
  * Gather annotation text for IfStatement else-if branches, supporting comments placed
- * between the else-if condition and the consequent statement body.
+ * before the else keyword, between the else-if condition and the consequent body,
+ * and in the first comment-only lines inside the consequent block body.
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
  * @supports REQ-FALLBACK-LOGIC
@@ -154,31 +234,23 @@ function gatherElseIfCommentText(sourceCode, node, parent, beforeText) {
     if (!isElseIfBranch(node, parent)) {
         return beforeText;
     }
-    if (!node.consequent ||
-        node.consequent.type !== "BlockStatement" ||
-        !node.consequent.loc ||
-        !node.consequent.loc.start) {
-        return beforeText;
+    const beforeElseText = scanElseIfPrecedingComments(sourceCode, node);
+    if (beforeElseText &&
+        (/@story\b/.test(beforeElseText) || /@req\b/.test(beforeElseText))) {
+        return beforeElseText;
     }
-    if (!node.test || !node.test.loc || !node.test.loc.end) {
+    if (!hasValidElseIfBlockLoc(node)) {
         return beforeText;
     }
-    const lines = sourceCode.lines;
-    const conditionEndLine = node.test.loc.end.line;
-    const consequentStartLine = node.consequent.loc.start.line;
-    const comments = [];
-    for (let lineIndex = conditionEndLine; lineIndex < consequentStartLine; lineIndex++) {
-        const line = lines[lineIndex];
-        if (!line || !line.trim()) {
-            break;
-        }
-        if (!/^\s*(\/\/|\/\*)/.test(line)) {
-            break;
-        }
-        comments.push(line.trim());
+    const betweenText = scanElseIfBetweenConditionAndBody(sourceCode, node);
+    if (betweenText) {
+        return betweenText;
+    }
+    const insideText = scanElseIfInsideBlockComments(sourceCode, node);
+    if (insideText) {
+        return insideText;
     }
-    const betweenText = comments.join(" ");
-    return betweenText || beforeText;
+    return beforeText;
 }
 /**
  * Gather leading comment text for a branch node.
@@ -345,11 +417,13 @@ function getBaseBranchIndentAndInsertPos(sourceCode, node) {
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
  */
 function getBranchAnnotationInfo(sourceCode, node, parent) {
     const text = gatherBranchCommentText(sourceCode, node, parent);
-    const missingStory = !/@story\b/.test(text);
-    const missingReq = !/@req\b/.test(text);
+    const hasSupports = /@supports\b/.test(text);
+    const missingStory = !/@story\b/.test(text) && !hasSupports;
+    const missingReq = !/@req\b/.test(text) && !hasSupports;
     let { indent, insertPos } = getBaseBranchIndentAndInsertPos(sourceCode, node);
     if (isElseIfBranch(node, parent) &&
         node.consequent &&
@@ -378,13 +452,11 @@ function getBranchAnnotationInfo(sourceCode, node, parent) {
 function reportMissingAnnotations(context, node, storyFixCountRef) {
     const sourceCode = context.getSourceCode();
     /**
-     * Determine the direct parent of the node using the ancestors stack when available.
+     * Determine the direct parent of the node using the parent reference on the node.
      * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
      * @supports REQ-DUAL-POSITION-DETECTION
      */
-    const contextAny = context;
-    const ancestors = contextAny.getAncestors?.() || [];
-    const parent = ancestors.length > 0 ? ancestors[ancestors.length - 1] : undefined;
+    const parent = node.parent;
     const { missingStory, missingReq, indent, insertPos } = getBranchAnnotationInfo(sourceCode, node, parent);
     const actions = [
         {

package/lib/tests/integration/else-if-annotation-prettier.integration.test.js

@@ -73,8 +73,9 @@ else if (anotherVeryLongConditionThatForcesWrapping && someOtherCondition) {
 }
 `;
             const formatted = formatWithPrettier(original);
-            // Sanity check: Prettier should keep both the else-if branch and the associated story annotation.
-            expect(formatted).toContain("else if (");
+            // Sanity checks: Prettier should keep both the else-if branch and the associated story annotation,
+            // but the exact layout and comment movement may vary between versions.
+            expect(formatted).toContain("else if");
             expect(formatted).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
             const result = runEslintWithRequireBranchAnnotation(formatted);
             expect(result.status).toBe(0);
@@ -109,8 +110,62 @@ if (aVeryLongConditionThatForcesPrettierToWrapTheElseIfBranch && anotherConditio
         });
     }
     else {
-        it.skip("Else-if Prettier integration tests are pending full else-if formatter support (set TRACEABILITY_EXPERIMENTAL_ELSE_IF=1 to enable)", () => {
-            // Pending full else-if formatter support.
+        it.skip("[REQ-PRETTIER-COMPATIBILITY-ELSE-IF-BEFORE] accepts code where annotations start before else-if but are moved between condition and body by Prettier", () => {
+            const original = `
+function doA() {
+  return 1;
+}
+
+function doB() {
+  return 2;
+}
+
+// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-DETECTION
+if (aVeryLongConditionThatForcesPrettierToWrapTheElseIfBranch && anotherCondition) {
+  doA();
+}
+// @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+// @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
+else if (anotherVeryLongConditionThatForcesWrapping && someOtherCondition) {
+  doB();
+}
+`;
+            const formatted = formatWithPrettier(original);
+            // Sanity checks: Prettier should keep both the else-if branch and the associated story annotation,
+            // but the exact layout and comment movement may vary between versions.
+            expect(formatted).toContain("else if");
+            expect(formatted).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
+            const result = runEslintWithRequireBranchAnnotation(formatted);
+            expect(result.status).toBe(0);
+        });
+        it.skip("[REQ-PRETTIER-COMPATIBILITY-ELSE-IF-INSIDE] accepts code where annotations start between condition and body and are preserved by Prettier", () => {
+            const original = `
+function doA() {
+  return 1;
+}
+
+function doB() {
+  return 2;
+}
+
+// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-DETECTION
+if (aVeryLongConditionThatForcesPrettierToWrapTheElseIfBranch && anotherCondition) {
+  doA();
+} else if (
+  anotherVeryLongConditionThatForcesWrapping && someOtherCondition
+) {
+  // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+  // @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
+  doB();
+}
+`;
+            const formatted = formatWithPrettier(original);
+            // Note: Prettier's exact layout of the else-if and its comments may differ between versions;
+            // the rule should accept any of the supported annotation positions regardless of formatting.
+            const result = runEslintWithRequireBranchAnnotation(formatted);
+            expect(result.status).toBe(0);
         });
     }
 });

package/lib/tests/rules/require-branch-annotation.test.js

@@ -13,7 +13,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-ERROR-CONSISTENCY - Branch-level missing-annotation error messages follow shared conventions
  * @req REQ-ERROR-SUGGESTION - Branch-level missing-annotation errors include suggestions when applicable
  * @req REQ-NESTED-HANDLING - Nested branch annotations are correctly enforced without duplicative reporting
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION REQ-NESTED-HANDLING
+ * @req REQ-SUPPORTS-ALTERNATIVE - Branches annotated only with @supports are treated as fully annotated
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION REQ-NESTED-HANDLING REQ-SUPPORTS-ALTERNATIVE
  * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SPECIFIC REQ-ERROR-CONSISTENCY REQ-ERROR-SUGGESTION
  * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF REQ-POSITION-PRIORITY-ELSE-IF REQ-PRETTIER-AUTOFIX-ELSE-IF
  */
@@ -158,6 +159,34 @@ if (outer) {
 if (condition) {}`,
                 options: [{ branchTypes: ["IfStatement", "SwitchCase"] }],
             },
+            {
+                name: "[REQ-SUPPORTS-ALTERNATIVE] if-statement with only @supports annotation is treated as fully annotated",
+                code: `// @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+if (shouldHandleAlternative) {
+  handleAlternative();
+}`,
+            },
+            {
+                name: "[REQ-SUPPORTS-ALTERNATIVE] try/catch where both branches are annotated only with @supports",
+                code: `// @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+try {
+  mightThrow();
+}
+// @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+catch (error) {
+  recoverFrom(error);
+}`,
+            },
+            {
+                name: "[REQ-SUPPORTS-ALTERNATIVE] else-if branch with @supports inside the block body",
+                code: `// @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+if (mode === 'primary') {
+  handlePrimary();
+} else if (mode === 'alternative') {
+  // @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+  handleAlternativeMode();
+}`,
+            },
         ],
         invalid: [
             {

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

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

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

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Unit tests for else-if insert position calculation.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-PRETTIER-AUTOFIX-ELSE-IF
+ */
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+describe("Else-if insert position (Story 026.0-DEV-ELSE-IF-ANNOTATION-POSITION)", () => {
+    it("[REQ-PRETTIER-AUTOFIX-ELSE-IF] inserts annotations on a dedicated line inside the else-if block body", () => {
+        const lines = [
+            "if (a) {",
+            "  doA();",
+            "}",
+            "else if (b) {",
+            "  doB();",
+            "}",
+        ];
+        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: "IfStatement",
+            loc: { start: { line: 4 } },
+            test: { loc: { end: { line: 4 } } },
+            consequent: {
+                type: "BlockStatement",
+                loc: { start: { line: 4 } },
+                body: [
+                    {
+                        type: "ExpressionStatement",
+                        loc: { start: { line: 5 } },
+                    },
+                ],
+            },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: node,
+        };
+        node.parent = parent;
+        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 else-if 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-else-if-position.test.d.ts

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

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

@@ -0,0 +1,107 @@
+"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 = [] } = options;
+    return {
+        lines,
+        getCommentsBefore() {
+            return commentsBefore;
+        },
+    };
+}
+describe("gatherBranchCommentText else-if behavior (Story 026.0-DEV-ELSE-IF-ANNOTATION-POSITION)", () => {
+    it("[REQ-DUAL-POSITION-DETECTION-ELSE-IF] detects annotations placed before the else-if keyword", () => {
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [
+                {
+                    value: "@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+                },
+                { value: "@req REQ-DUAL-POSITION-DETECTION-ELSE-IF" },
+            ],
+            // lines are unused in this case because we short-circuit on before-text annotations.
+            lines: [],
+        });
+        const node = {
+            type: "IfStatement",
+            loc: { start: { line: 10 } },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: node,
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent);
+        expect(text).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-DUAL-POSITION-DETECTION-ELSE-IF");
+    });
+    it("[REQ-FALLBACK-LOGIC-ELSE-IF] falls back to annotations between condition and body when before-else-if comments lack annotations", () => {
+        const lines = [
+            "if (a) {",
+            "  doA();",
+            "} else if (b && c) {",
+            "  // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+            "  // @req REQ-FALLBACK-LOGIC-ELSE-IF",
+            "  doB();",
+            "}",
+        ];
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [{ value: "// some unrelated comment" }],
+            lines,
+        });
+        const node = {
+            type: "IfStatement",
+            loc: { start: { line: 3 } },
+            test: { loc: { end: { line: 3 } } },
+            consequent: {
+                type: "BlockStatement",
+                loc: { start: { line: 6 } },
+            },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: node,
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent);
+        expect(text).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-FALLBACK-LOGIC-ELSE-IF");
+    });
+    it("[REQ-POSITION-PRIORITY-ELSE-IF] prefers before-else-if annotations when both positions are present", () => {
+        const lines = [
+            "if (a) {",
+            "  doA();",
+            "} else if (b) {",
+            "  // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+            "  // @req REQ-POSITION-PRIORITY-ELSE-IF-BETWEEN",
+            "  doB();",
+            "}",
+        ];
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [
+                {
+                    value: "@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+                },
+                { value: "@req REQ-POSITION-PRIORITY-ELSE-IF" },
+            ],
+            lines,
+        });
+        const node = {
+            type: "IfStatement",
+            loc: { start: { line: 3 } },
+            test: { loc: { end: { line: 3 } } },
+            consequent: {
+                type: "BlockStatement",
+                loc: { start: { line: 6 } },
+            },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: node,
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent);
+        // The helper should use the before-else-if annotations and not need to
+        // fall back to between-condition-and-body comments.
+        expect(text).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-POSITION-PRIORITY-ELSE-IF");
+        expect(text).not.toContain("REQ-POSITION-PRIORITY-ELSE-IF-BETWEEN");
+    });
+});

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

@@ -157,6 +157,20 @@ describe("reqAnnotationDetection advanced heuristics (Story 003.0-DEV-FUNCTION-A
         const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
         expect(has).toBe(false);
     });
+    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when range[0] is not a number", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({ text: "/* @req REQ-IN-TEXT-BUT-INVALID-RANGE */" });
+            },
+        };
+        const node = {
+            // First element of range is not a number; guard on numeric start index should trigger
+            range: ["not-a-number", 10],
+            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
@@ -244,4 +258,55 @@ describe("reqAnnotationDetection advanced heuristics (Story 003.0-DEV-FUNCTION-A
         const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, { parent: {} });
         expect(has).toBe(true);
     });
+    it("[REQ-ANNOTATION-REQ-DETECTION] linesBeforeHasReq returns true when preceding lines contain @req marker", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({
+                    lines: [
+                        "// some header",
+                        "/** @req REQ-LINE-BEFORE */",
+                        "function foo() {}",
+                    ],
+                });
+            },
+        };
+        const node = {
+            // Node starts on line 3 (1-based), so line 2 is inspected by linesBeforeHasReq
+            loc: { start: { line: 3 } },
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] parentChainHasReq returns true when leadingComments contain @supports and getCommentsBefore is unusable", () => {
+        const context = {
+            getSourceCode() {
+                return {
+                    // Not a callable function; forces parentChainHasReq to rely on leadingComments
+                    getCommentsBefore: 42,
+                };
+            },
+        };
+        const node = {
+            parent: {
+                leadingComments: [
+                    { value: "some other comment" },
+                    {
+                        value: "@supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-FROM-LEADING-COMMENT",
+                    },
+                ],
+                parent: {},
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] returns true when jsdoc has @req even if context is undefined", () => {
+        const jsdoc = { value: "/** @req REQ-JSDOC-NO-CONTEXT */" };
+        const node = {
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], undefined, node);
+        expect(has).toBe(true);
+    });
 });

package/package.json

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

@@ -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-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).
+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 for 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,7 +68,9 @@ 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. 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; for `else if` branches, the rule accepts annotations either immediately before the `else if` keyword or on comment-only lines between the `else if (condition)` and the first statement of the consequent body, matching Prettier’s wrapped style.
+Description: Ensures significant code branches (if/else chains, loops, switch cases, try/catch) have both `@story` and `@req` annotations in nearby comments. When you adopt multi-story `@supports` annotations, a single `@supports <storyPath> <REQ-ID>...` line placed in any of the valid branch comment locations is treated as satisfying both the story and requirement presence checks for that branch, while detailed format validation of the `@supports` value (including story paths and requirement IDs) continues to be handled by `traceability/valid-annotation-format`, `traceability/valid-story-reference`, and `traceability/valid-req-reference`.
+
+For most branches, the rule looks for annotations in comments immediately preceding the branch keyword (for example, the line above an `if` or `for` statement). For `catch` clauses and `else if` branches, the rule is formatter-aware and accepts annotations in additional positions that common formatters like Prettier use when they reflow code.
 
 Options:
 
@@ -76,8 +78,22 @@ Options:
 
 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.
+- **Catch clauses**:
+  - Valid locations for `@story` / `@req` annotations are either immediately before the `catch` keyword or on the first comment-only lines inside the catch block (before any executable statements). A single `@supports` annotation in either of these locations is also accepted as covering both story and requirement presence for the catch branch.
+  - If annotations exist in both locations, 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 block body so that formatters like Prettier keep them attached to the branch.
+
+- **Else-if branches**:
+  - Valid locations for `@story` / `@req` annotations include:
+    - Line or block comments immediately before the `else if` line.
+    - Comment-only lines between the `else if (condition)` and the opening `{` of the consequent block (for styles where the condition and block are on separate lines).
+    - The first comment-only lines inside the consequent block body, which is where formatters like Prettier often move comments when they wrap long `else if` conditions. For a concrete before/after example of this formatter-aware behavior, see [user-docs/examples.md](examples.md) (section **6. Branch annotations with if/else/else-if and Prettier**).
+  - When annotations appear in more than one of these locations, the rule prefers the comments immediately before the `else if` line, then comments between the condition and the block, and finally comments inside the block body. This precedence is designed to closely mirror real-world formatter behavior and matches the formatter-aware scenarios described in stories 025.0 and 026.0.
+  - When auto-fixing missing annotations on an `else if` branch, the rule inserts placeholder comments as the first comment-only line inside the consequent block body (just after the opening `{`), which is a stable location under Prettier and similar formatters. As with catch clauses, a single `@supports` annotation placed in any of these accepted locations is treated as equivalent to having both `@story` and `@req` comments for that branch, with deep format and existence checks delegated to the other validation rules.
+
+For a concrete illustration of how these rules interact with Prettier, see the formatter-aware if/else/else-if example in [user-docs/examples.md](examples.md) (section **6. Branch annotations with if/else/else-if and Prettier**), which shows both the hand-written and formatted code that the rule considers valid.
+
+These behaviors are intentionally limited to `catch` clauses and `else if` branches; other branch types (plain `if`, `else`, loops, and `switch` cases) continue to use the simpler "comments immediately before the branch" association model for both validation and auto-fix placement.
 
 Default Severity: `error`
 Example:
@@ -689,4 +705,5 @@ If `--from` or `--to` is missing, the CLI prints an error, shows the help text,
 In CI:
 
 ```bash
-npm run traceability:verify
+npm run traceability:verify
+```

package/user-docs/examples.md

@@ -114,3 +114,65 @@ function performOperation(input: string): string {
   return "ok";
 }
 ```
+
+## 6. Branch annotations with if/else/else-if and Prettier
+
+This example shows how to keep `traceability/require-branch-annotation` satisfied while still running Prettier on your code.
+
+### 6.1 Before formatting
+
+In this version, annotations are placed immediately before each significant branch. This is a simple layout that is easy to read and accepted by the rule:
+
+```ts
+function pickCategory(score: number): string {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-BRANCH-DETECTION
+  if (score >= 80) {
+    return "high";
+  }
+  // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+  // @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
+  else if (score >= 50) {
+    return "medium";
+  }
+  // You can annotate `else` using the same pattern if you treat it as a significant branch.
+  else {
+    return "low";
+  }
+}
+```
+
+You can run just the branch-annotation rule via the CLI:
+
+```bash
+npx eslint --no-eslintrc \
+  --rule "traceability/require-branch-annotation:error" \
+  pick-category.ts
+```
+
+### 6.2 After formatting with Prettier
+
+Prettier may reflow your `else if` line, wrap the condition, or move comments into the body of the branch. The `traceability/require-branch-annotation` rule is formatter-aware and will still recognize valid annotations in supported positions, such as the first comment-only lines inside the block body:
+
+```ts
+function pickCategory(score: number): string {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-BRANCH-DETECTION
+  if (score >= 80) {
+    return "high";
+  } else if (score >= 50) {
+    // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+    // @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
+    return "medium";
+  } else {
+    return "low";
+  }
+}
+```
+
+Depending on your Prettier version and configuration, the exact layout of the `else if` line and braces may differ, but as long as your annotations are in one of the supported locations, the rule will accept them.
+
+- Notes:
+  - For most branch types, `traceability/require-branch-annotation` associates comments immediately before the branch keyword (such as `if`, `else`, `switch`, `case`) with that branch.
+  - For `catch` clauses and `else if` branches, the rule is formatter-aware and also looks at comments between the condition and the block, as well as the first comment-only lines inside the block body, so you do not need to fight Prettier if it moves your annotations.
+  - When annotations exist in more than one place around an `else if` branch, the rule prefers comments immediately before the `else if` line, then comments between the condition and the block, and finally comments inside the block body, matching the behavior described in the API reference and stories `025.0` and `026.0`.

package/user-docs/migration-guide.md

@@ -188,6 +188,15 @@ You can introduce `@supports` gradually without breaking existing code:
 
 Detailed semantics and edge cases (path validation, scoped requirement IDs, and multi-story fixtures) are ultimately governed by your own stories and requirements. For typical migrations, this guide together with the plugin’s API reference is sufficient.
 
+### 3.2 Else-if branch annotations and formatter compatibility
+
+Versions 1.x of `eslint-plugin-traceability` extend the `traceability/require-branch-annotation` rule to better support formatter-driven layouts for `else if` branches. In most projects you **do not need to change existing annotations**:
+
+- Comments immediately before an `else if` line remain valid and continue to satisfy the rule.
+- When formatters such as Prettier move comments between the `else if (condition)` and the opening `{`, or into the first comment-only lines inside the `{ ... }` block, those annotations are now also recognized and associated with the correct branch.
+
+If you previously added suppressions or workaround comments around `else if` branches due to formatter conflicts, you can usually remove those workarounds after upgrading to 1.x as long as your annotations live in one of the supported locations. For new code, you can place annotations either directly above the `else if` or, when you know a formatter will wrap a long condition, on the first comment-only line inside the consequent block body, which is where the rule places auto-fix placeholders by default.
+
 ## 4. Test and Validate
 
 Run your test suite to confirm everything passes: