eslint-plugin-traceability 1.19.1 → 1.19.2

package/CHANGELOG.md

@@ -1,10 +1,9 @@
-## [1.19.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.0...v1.19.1) (2025-12-18)
+## [1.19.2](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.1...v1.19.2) (2025-12-18)
 
 
 ### Bug Fixes
 
-* apply inside placement semantics to loop branches ([e0ba06f](https://github.com/voder-ai/eslint-plugin-traceability/commit/e0ba06fb9aba6947c6ac675f65cc1fb4639dc785))
-* honor inside placement for catch clauses in branch annotation rule ([0e7a8e0](https://github.com/voder-ai/eslint-plugin-traceability/commit/0e7a8e01505bfa1e37e013dfda00e866f975ad33))
+* honor annotationPlacement for else-if branches and refactor helpers ([8f747dc](https://github.com/voder-ai/eslint-plugin-traceability/commit/8f747dc8546ae8e5033cfe4aa9c394ca668a45d5))
 
 # Changelog
 

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

@@ -9,6 +9,7 @@ exports.reportMissingReq = reportMissingReq;
 const branch_annotation_report_helpers_1 = require("./branch-annotation-report-helpers");
 Object.defineProperty(exports, "reportMissingAnnotations", { enumerable: true, get: function () { return branch_annotation_report_helpers_1.reportMissingAnnotations; } });
 const branch_annotation_loop_helpers_1 = require("./branch-annotation-loop-helpers");
+const branch_annotation_if_helpers_1 = require("./branch-annotation-if-helpers");
 const PRE_COMMENT_OFFSET = 2; // number of lines above branch to inspect for comments
 /**
  * Valid branch types for require-branch-annotation rule.
@@ -153,14 +154,6 @@ function scanCommentLinesInRange(lines, startIndex, endIndexInclusive) {
     }
     return comments.join(" ");
 }
-/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-function isElseIfBranch(node, parent) {
-    return (node &&
-        node.type === "IfStatement" &&
-        parent &&
-        parent.type === "IfStatement" &&
-        parent.alternate === node);
-}
 function getInsideCatchCommentText(sourceCode, node) {
     const getCommentsInside = sourceCode.getCommentsInside;
     if (node.body && typeof getCommentsInside === "function") {
@@ -261,109 +254,6 @@ function gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, before
     return "";
 }
 /** @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 commentText = getCommentTextAtLine(lines, i);
-        if (!commentText) {
-            break;
-        }
-        comments.unshift(commentText);
-        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;
-    // Lines in sourceCode are 0-based indexes, but loc.line values are 1-based.
-    // We want to scan comments strictly between the condition and the
-    // consequent body, so we start at the line after the condition's end and
-    // stop at the line immediately before the consequent's starting line.
-    const startIndex = conditionEndLine; // already the next logical line index when 0-based
-    const endIndexExclusive = consequentStartLine - 1;
-    if (endIndexExclusive <= startIndex) {
-        return "";
-    }
-    return scanCommentLinesInRange(lines, startIndex, endIndexExclusive - 1);
-}
-/** @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
- * 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
- */
-function gatherElseIfCommentText(sourceCode, node, parent, beforeText) {
-    if (beforeText &&
-        (/@story\b/.test(beforeText) ||
-            /@req\b/.test(beforeText) ||
-            /@supports\b/.test(beforeText))) {
-        return beforeText;
-    }
-    if (!isElseIfBranch(node, parent)) {
-        return beforeText;
-    }
-    const beforeElseText = scanElseIfPrecedingComments(sourceCode, node);
-    if (beforeElseText &&
-        (/@story\b/.test(beforeElseText) ||
-            /@req\b/.test(beforeElseText) ||
-            /@supports\b/.test(beforeElseText))) {
-        return beforeElseText;
-    }
-    if (!hasValidElseIfBlockLoc(node)) {
-        return beforeText;
-    }
-    const betweenText = scanElseIfBetweenConditionAndBody(sourceCode, node);
-    if (betweenText) {
-        return betweenText;
-    }
-    const insideText = scanElseIfInsideBlockComments(sourceCode, node);
-    if (insideText) {
-        return insideText;
-    }
-    return beforeText;
-}
-/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function gatherSwitchCaseCommentText(sourceCode, node) {
     const lines = sourceCode.lines;
     const startLine = node.loc.start.line;
@@ -375,7 +265,15 @@ function gatherSwitchCaseCommentText(sourceCode, node) {
     }
     return comments.join(" ");
 }
-function gatherBranchCommentTextByType(sourceCode, node, parent, context) {
+/**
+ * Helper that gathers comment text for non-IfStatement branch types using
+ * straightforward behavior (SwitchCase, CatchClause, and loop statements).
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports REQ-COMMENT-ASSOCIATION
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-PLACEMENT-CONFIG
+ */
+function gatherNonIfBranchCommentText(sourceCode, node, context) {
     const { annotationPlacement, beforeText } = context;
     if (node.type === "SwitchCase") {
         return gatherSwitchCaseCommentText(sourceCode, node);
@@ -383,12 +281,6 @@ function gatherBranchCommentTextByType(sourceCode, node, parent, context) {
     if (node.type === "CatchClause") {
         return gatherCatchClauseCommentText(sourceCode, node, annotationPlacement, beforeText);
     }
-    if (node.type === "IfStatement") {
-        if (isElseIfBranch(node, parent)) {
-            return gatherElseIfCommentText(sourceCode, node, parent, beforeText);
-        }
-        return gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText);
-    }
     if (node.type === "ForStatement" ||
         node.type === "ForInStatement" ||
         node.type === "ForOfStatement" ||
@@ -398,6 +290,54 @@ function gatherBranchCommentTextByType(sourceCode, node, parent, context) {
     }
     return null;
 }
+/**
+ * Helper that gathers comment text for IfStatement branches, including both
+ * simple if and else-if specific logic.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports REQ-COMMENT-ASSOCIATION
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports REQ-DUAL-POSITION-DETECTION
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-PLACEMENT-CONFIG
+ * @supports REQ-DEFAULT-BACKWARD-COMPAT
+ */
+function gatherIfBranchCommentText(sourceCode, node, parent, context) {
+    const { annotationPlacement, beforeText } = context;
+    if (node.type !== "IfStatement") {
+        return null;
+    }
+    if ((0, branch_annotation_if_helpers_1.isElseIfBranch)(node, parent)) {
+        return (0, branch_annotation_if_helpers_1.gatherElseIfCommentText)(sourceCode, node, parent, {
+            annotationPlacement,
+            beforeText,
+        });
+    }
+    return gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText);
+}
+/**
+ * Internal helper that performs type-based dispatch for gathering branch comment text.
+ * This keeps the public gatherBranchCommentTextByType wrapper small for ESLint limits.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports REQ-COMMENT-ASSOCIATION
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports REQ-DUAL-POSITION-DETECTION
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-PLACEMENT-CONFIG
+ */
+function gatherBranchCommentTextByTypeInternal(sourceCode, node, parent, context) {
+    const nonIfResult = gatherNonIfBranchCommentText(sourceCode, node, context);
+    if (nonIfResult != null) {
+        return nonIfResult;
+    }
+    const ifResult = gatherIfBranchCommentText(sourceCode, node, parent, context);
+    if (ifResult != null) {
+        return ifResult;
+    }
+    return null;
+}
+function gatherBranchCommentTextByType(sourceCode, node, parent, context) {
+    return gatherBranchCommentTextByTypeInternal(sourceCode, node, parent, context);
+}
 /**
  * Gather leading comment text for a branch node.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md

package/lib/src/utils/branch-annotation-if-helpers.d.ts

@@ -0,0 +1,12 @@
+import type { Rule } from "eslint";
+import type { AnnotationPlacement } from "./branch-annotation-helpers";
+export declare function isElseIfBranch(node: any, parent: any | undefined): boolean;
+export declare function hasValidElseIfBlockLoc(node: any): boolean;
+export declare function scanElseIfPrecedingComments(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;
+export declare function scanElseIfBetweenConditionAndBody(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;
+export declare function scanElseIfInsideBlockComments(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;
+export declare function getInsideElseIfCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;
+export declare function gatherElseIfCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, parent: any | undefined, options: {
+    annotationPlacement: AnnotationPlacement;
+    beforeText: string;
+}): string;

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

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isElseIfBranch = isElseIfBranch;
+exports.hasValidElseIfBlockLoc = hasValidElseIfBlockLoc;
+exports.scanElseIfPrecedingComments = scanElseIfPrecedingComments;
+exports.scanElseIfBetweenConditionAndBody = scanElseIfBetweenConditionAndBody;
+exports.scanElseIfInsideBlockComments = scanElseIfInsideBlockComments;
+exports.getInsideElseIfCommentText = getInsideElseIfCommentText;
+exports.gatherElseIfCommentText = gatherElseIfCommentText;
+const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
+/**
+ * Small shared helpers for IfStatement/else-if specific annotation handling.
+ * Extracted from branch-annotation-helpers to keep that file within ESLint
+ * max-lines limits while preserving behaviour.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ */
+const PRE_COMMENT_OFFSET = 2; // kept in sync with main helpers
+function getCommentTextAtLine(lines, index) {
+    const line = lines[index];
+    if (!line || !line.trim()) {
+        return null;
+    }
+    if (!/^\s*(\/\/|\/\*)/.test(line)) {
+        return null;
+    }
+    return line.trim();
+}
+function isElseIfBranch(node, parent) {
+    return (node &&
+        node.type === "IfStatement" &&
+        parent &&
+        parent.type === "IfStatement" &&
+        parent.alternate === node);
+}
+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);
+}
+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 commentText = getCommentTextAtLine(lines, i);
+        if (!commentText) {
+            break;
+        }
+        comments.unshift(commentText);
+        i--;
+        scanned++;
+    }
+    return comments.join(" ");
+}
+function scanElseIfBetweenConditionAndBody(sourceCode, node) {
+    const lines = sourceCode.lines;
+    const conditionEndLine = node.test.loc.end.line;
+    const consequentStartLine = node.consequent.loc.start.line;
+    const startIndex = conditionEndLine;
+    const endIndexExclusive = consequentStartLine - 1;
+    if (endIndexExclusive <= startIndex) {
+        return "";
+    }
+    return (0, branch_annotation_helpers_1.scanCommentLinesInRange)(lines, startIndex, endIndexExclusive - 1);
+}
+function scanElseIfInsideBlockComments(sourceCode, node) {
+    const lines = sourceCode.lines;
+    const consequentStartLine = node.consequent.loc.start.line;
+    const comments = [];
+    let lineIndex = consequentStartLine;
+    while (lineIndex < lines.length) {
+        const lineText = getCommentTextAtLine(lines, lineIndex);
+        if (!lineText) {
+            break;
+        }
+        comments.push(lineText);
+        lineIndex++;
+    }
+    return comments.join(" ");
+}
+function getInsideElseIfCommentText(sourceCode, node) {
+    if (!hasValidElseIfBlockLoc(node)) {
+        return "";
+    }
+    const insideText = scanElseIfInsideBlockComments(sourceCode, node);
+    if (insideText) {
+        return insideText;
+    }
+    return "";
+}
+function gatherElseIfCommentText(sourceCode, node, parent, options) {
+    const { annotationPlacement, beforeText } = options;
+    if (!isElseIfBranch(node, parent)) {
+        return beforeText;
+    }
+    if (annotationPlacement === "inside") {
+        return getInsideElseIfCommentText(sourceCode, node);
+    }
+    if (beforeText &&
+        (/@story\b/.test(beforeText) ||
+            /@req\b/.test(beforeText) ||
+            /@supports\b/.test(beforeText))) {
+        return beforeText;
+    }
+    const beforeElseText = scanElseIfPrecedingComments(sourceCode, node);
+    if (beforeElseText &&
+        (/@story\b/.test(beforeElseText) ||
+            /@req\b/.test(beforeElseText) ||
+            /@supports\b/.test(beforeElseText))) {
+        return beforeElseText;
+    }
+    if (!hasValidElseIfBlockLoc(node)) {
+        return beforeText;
+    }
+    const betweenText = scanElseIfBetweenConditionAndBody(sourceCode, node);
+    if (betweenText) {
+        return betweenText;
+    }
+    const insideText = scanElseIfInsideBlockComments(sourceCode, node);
+    if (insideText) {
+        return insideText;
+    }
+    return beforeText;
+}

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

@@ -83,7 +83,8 @@ function getIfStatementIndentAndInsertPos(sourceCode, node, options, context) {
     }
     const isElseIf = isElseIfBranchForInsert(node, parent);
     const isSimpleIfInsidePlacement = annotationPlacement === "inside" && !isElseIf;
-    if (isSimpleIfInsidePlacement || isElseIf) {
+    if (annotationPlacement === "inside" &&
+        (isSimpleIfInsidePlacement || isElseIf)) {
         const commentLine = node.consequent.loc.start.line + 1;
         const commentLineInfo = getIndentAndInsertPosForLine(sourceCode, commentLine, indent);
         indent = commentLineInfo.indent;

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

@@ -501,6 +501,60 @@ try {
 catch (error) {
   // @story <story-file>.story.md
   handleError(error);
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-BEFORE-BRACE-ERROR][REQ-PLACEMENT-CONFIG] before-else-if annotations ignored when annotationPlacement: 'inside' for else-if branch (Story 028.0)",
+                code: `if (a) {
+  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+  // @req REQ-OUTER-IF-INSIDE
+  doA();
+}
+// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-ELSE-IF-BEFORE
+else if (b) {
+  doB();
+}`,
+                options: [{ annotationPlacement: "inside" }],
+                output: `if (a) {
+  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+  // @req REQ-OUTER-IF-INSIDE
+  doA();
+}
+// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-ELSE-IF-BEFORE
+else if (b) {
+  // @story <story-file>.story.md
+  doB();
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] else-if branch annotated inside block but initial if branch missing annotation under annotationPlacement: 'inside' (Story 028.0)",
+                code: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-INSIDE-OUTER-IF
+if (a) {
+  doA();
+} else if (b) {
+  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+  // @req REQ-INSIDE-ELSE-IF
+  doB();
+} else {
+  doC();
+}`,
+                options: [{ annotationPlacement: "inside" }],
+                output: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-INSIDE-OUTER-IF
+if (a) {
+  // @story <story-file>.story.md
+  doA();
+} else if (b) {
+  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+  // @req REQ-INSIDE-ELSE-IF
+  doB();
+} else {
+  doC();
 }`,
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },

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

@@ -8,7 +8,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 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", () => {
+    it("[REQ-PRETTIER-AUTOFIX-ELSE-IF] inserts annotations before the else-if line in Prettier-compatible default 'before' mode", () => {
         const lines = [
             "if (a) {",
             "  doA();",
@@ -24,6 +24,7 @@ describe("Else-if insert position (Story 026.0-DEV-ELSE-IF-ANNOTATION-POSITION)"
             })),
         };
         const context = {
+            options: [{ annotationPlacement: "before" }],
             getSourceCode() {
                 return {
                     lines,
@@ -69,12 +70,12 @@ describe("Else-if insert position (Story 026.0-DEV-ELSE-IF-ANNOTATION-POSITION)"
         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)
+        // ensure we are inserting before the else-if line (line 4) when placement is 'before'
         const expectedIndex = context
             .getSourceCode()
-            .getIndexFromLoc({ line: 5, column: 0 });
+            .getIndexFromLoc({ line: 4, 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);
+        // and that the inserted text is prefixed with the base indentation from line 4
+        expect(text.startsWith("")).toBe(true);
     });
 });

package/lib/tests/utils/branch-annotation-helpers.test.js

@@ -243,4 +243,72 @@ describe("gatherBranchCommentText annotationPlacement wiring (Story 028.0-DEV-AN
         expect(insideText).toContain("@req REQ-INSIDE");
         expect(insideText).not.toContain("@req REQ-BEFORE");
     });
+    it("[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] honors Story 028.0 inside-placement semantics for else-if branches while preserving Story 026.0 before-else behavior", () => {
+        const sourceCode = {
+            lines: [
+                "function demoElseIf(x) {", // 1
+                "  if (x === 1) {", // 2
+                "    // @story inside-if", // 3
+                "    doOne();", // 4
+                "  }", // 5
+                "  // @story docs/stories/026.0-DEV-BRANCH-ANNOTATIONS-ELSE-BRANCHES.story.md", // 6 (before else-if)
+                "  // @req REQ-BEFORE-ELSE", // 7
+                "  else if (x === 2) {", // 8
+                "    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md", // 9 (inside else-if)
+                "    // @req REQ-ELSE-IF-INSIDE", // 10
+                "    doTwo();", // 11
+                "  }", // 12
+                "}", // 13
+            ],
+            getCommentsBefore: jest.fn().mockImplementation((node) => {
+                // Simulate ESLint getCommentsBefore only returning comments that are truly
+                // "before" the node they are querying.
+                // Our chain has:
+                // - before-if comments not used in this test
+                // - line 6-7 as before-else-if comments
+                if (node && node.loc && node.loc.start && node.loc.start.line === 2) {
+                    // before the initial if (not used in assertions here)
+                    return [
+                        { value: "@story BEFORE-IF" },
+                        { value: "@req REQ-BEFORE-IF" },
+                    ];
+                }
+                if (node && node.loc && node.loc.start && node.loc.start.line === 8) {
+                    // before the else-if branch (Story 026.0 semantics)
+                    return [
+                        {
+                            value: "@story docs/stories/026.0-DEV-BRANCH-ANNOTATIONS-ELSE-BRANCHES.story.md",
+                        },
+                        { value: "@req REQ-BEFORE-ELSE" },
+                    ];
+                }
+                return [];
+            }),
+        };
+        const elseIfNode = {
+            type: "IfStatement",
+            loc: {
+                start: { line: 8, column: 2 },
+                end: { line: 12, column: 3 },
+            },
+            consequent: {
+                type: "BlockStatement",
+                loc: {
+                    start: { line: 8, column: 22 },
+                    end: { line: 12, column: 3 },
+                },
+            },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: elseIfNode,
+        };
+        const beforeText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, elseIfNode, parent, "before");
+        expect(beforeText).toContain("@story docs/stories/026.0-DEV-BRANCH-ANNOTATIONS-ELSE-BRANCHES.story.md");
+        expect(beforeText).toContain("@req REQ-BEFORE-ELSE");
+        const insideText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, elseIfNode, parent, "inside");
+        expect(insideText).toBe("");
+        expect(insideText).not.toContain("REQ-BEFORE-ELSE");
+        expect(insideText).not.toContain("docs/stories/026.0-DEV-BRANCH-ANNOTATIONS-ELSE-BRANCHES.story.md");
+    });
 });

package/package.json

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