eslint-plugin-traceability 1.19.0 → 1.19.2

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.19.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.18.0...v1.19.0) (2025-12-18)
+## [1.19.2](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.1...v1.19.2) (2025-12-18)
 
 
-### Features
+### Bug Fixes
 
-* enforce inside-brace placement mode for branch annotations ([5c2129a](https://github.com/voder-ai/eslint-plugin-traceability/commit/5c2129a7c25717dc4ce14bf55bc4541ae07e5539))
+* 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,24 +154,7 @@ 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);
-}
-/**
- * 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;
-    }
+function getInsideCatchCommentText(sourceCode, node) {
     const getCommentsInside = sourceCode.getCommentsInside;
     if (node.body && typeof getCommentsInside === "function") {
         try {
@@ -193,6 +177,31 @@ function gatherCatchClauseCommentText(sourceCode, node, beforeText) {
             return insideText;
         }
     }
+    return "";
+}
+/**
+ * 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, annotationPlacement, beforeText) {
+    if (annotationPlacement === "inside") {
+        const insideText = getInsideCatchCommentText(sourceCode, node);
+        if (insideText) {
+            return insideText;
+        }
+        return "";
+    }
+    if (/@story\b/.test(beforeText) ||
+        /@req\b/.test(beforeText) ||
+        /@supports\b/.test(beforeText)) {
+        return beforeText;
+    }
+    const insideText = getInsideCatchCommentText(sourceCode, node);
+    if (insideText) {
+        return insideText;
+    }
     return beforeText;
 }
 /**
@@ -245,119 +254,89 @@ function gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, before
     return "";
 }
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-function scanElseIfPrecedingComments(sourceCode, node) {
+function gatherSwitchCaseCommentText(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 startLine = node.loc.start.line;
+    let i = startLine - PRE_COMMENT_OFFSET;
     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);
+    while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
+        comments.unshift(lines[i].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;
-    // 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 "";
+/**
+ * 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);
     }
-    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++;
+    if (node.type === "CatchClause") {
+        return gatherCatchClauseCommentText(sourceCode, node, annotationPlacement, beforeText);
     }
-    return comments.join(" ");
+    if (node.type === "ForStatement" ||
+        node.type === "ForInStatement" ||
+        node.type === "ForOfStatement" ||
+        node.type === "WhileStatement" ||
+        node.type === "DoWhileStatement") {
+        return (0, branch_annotation_loop_helpers_1.gatherLoopCommentText)(sourceCode, node, annotationPlacement, beforeText);
+    }
+    return null;
 }
 /**
- * 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.
+ * 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
- * @supports REQ-FALLBACK-LOGIC
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-PLACEMENT-CONFIG
+ * @supports REQ-DEFAULT-BACKWARD-COMPAT
  */
-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;
+function gatherIfBranchCommentText(sourceCode, node, parent, context) {
+    const { annotationPlacement, beforeText } = context;
+    if (node.type !== "IfStatement") {
+        return null;
     }
-    if (!hasValidElseIfBlockLoc(node)) {
-        return beforeText;
+    if ((0, branch_annotation_if_helpers_1.isElseIfBranch)(node, parent)) {
+        return (0, branch_annotation_if_helpers_1.gatherElseIfCommentText)(sourceCode, node, parent, {
+            annotationPlacement,
+            beforeText,
+        });
     }
-    const betweenText = scanElseIfBetweenConditionAndBody(sourceCode, node);
-    if (betweenText) {
-        return betweenText;
+    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 insideText = scanElseIfInsideBlockComments(sourceCode, node);
-    if (insideText) {
-        return insideText;
+    const ifResult = gatherIfBranchCommentText(sourceCode, node, parent, context);
+    if (ifResult != null) {
+        return ifResult;
     }
-    return beforeText;
+    return null;
 }
-/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-function gatherSwitchCaseCommentText(sourceCode, node) {
-    const lines = sourceCode.lines;
-    const startLine = node.loc.start.line;
-    let i = startLine - PRE_COMMENT_OFFSET;
-    const comments = [];
-    while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
-        comments.unshift(lines[i].trim());
-        i--;
-    }
-    return comments.join(" ");
+function gatherBranchCommentTextByType(sourceCode, node, parent, context) {
+    return gatherBranchCommentTextByTypeInternal(sourceCode, node, parent, context);
 }
 /**
  * Gather leading comment text for a branch node.
@@ -368,47 +347,14 @@ function gatherSwitchCaseCommentText(sourceCode, node) {
  * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 function gatherBranchCommentText(sourceCode, node, parent, annotationPlacement = "before") {
-    /**
-     * Conditional branch for SwitchCase nodes that may include inline comments.
-     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-     * @req REQ-TRACEABILITY-SWITCHCASE-COMMENTS - Trace collection of preceding comments for SwitchCase
-     */
-    if (node.type === "SwitchCase") {
-        return gatherSwitchCaseCommentText(sourceCode, node);
-    }
     const beforeComments = sourceCode.getCommentsBefore(node) || [];
     const beforeText = beforeComments.map(extractCommentValue).join(" ");
-    if (node.type === "CatchClause") {
-        return gatherCatchClauseCommentText(sourceCode, node, beforeText);
-    }
-    /**
-     * Conditional branch for IfStatement nodes, distinguishing between else-if branches
-     * (which preserve dual-position behavior) and simple if-branches that can honor
-     * the configured annotation placement (before or inside braces).
-     * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
-     * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-     * @supports REQ-DUAL-POSITION-DETECTION
-     * @supports REQ-INSIDE-BRACE-PLACEMENT
-     * @supports REQ-PLACEMENT-CONFIG
-     * @supports REQ-DEFAULT-BACKWARD-COMPAT
-     */
-    if (node.type === "IfStatement") {
-        if (isElseIfBranch(node, parent)) {
-            return gatherElseIfCommentText(sourceCode, node, parent, beforeText);
-        }
-        return gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText);
-    }
-    /**
-     * Conditional branch for loop nodes that may include annotations either on the loop
-     * statement itself or at the top of the loop body, allowing flexible placement.
-     * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-LOOP-ANNOTATION REQ-LOOP-PLACEMENT-FLEXIBLE
-     */
-    if (node.type === "ForStatement" ||
-        node.type === "ForInStatement" ||
-        node.type === "ForOfStatement" ||
-        node.type === "WhileStatement" ||
-        node.type === "DoWhileStatement") {
-        return (0, branch_annotation_loop_helpers_1.gatherLoopCommentText)(sourceCode, node, beforeText);
+    const handled = gatherBranchCommentTextByType(sourceCode, node, parent, {
+        annotationPlacement,
+        beforeText,
+    });
+    if (handled != null) {
+        return handled;
     }
     return beforeText;
 }

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-loop-helpers.d.ts

@@ -1,4 +1,5 @@
 import type { Rule } from "eslint";
+import { type AnnotationPlacement } from "./branch-annotation-helpers";
 /**
  * Gather annotation text for loop branches, supporting annotations either on the
  * loop statement itself or on the first comment lines inside the loop body.
@@ -6,4 +7,4 @@ import type { Rule } from "eslint";
  * @req REQ-LOOP-ANNOTATION
  * @req REQ-LOOP-PLACEMENT-FLEXIBLE
  */
-export declare function gatherLoopCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, beforeText: string): string;
+export declare function gatherLoopCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, annotationPlacement: AnnotationPlacement, beforeText: string): string;

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

@@ -2,19 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.gatherLoopCommentText = gatherLoopCommentText;
 const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
-/**
- * Gather annotation text for loop branches, supporting annotations either on the
- * loop statement itself or on the first comment lines inside the loop body.
- * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @req REQ-LOOP-ANNOTATION
- * @req REQ-LOOP-PLACEMENT-FLEXIBLE
- */
-function gatherLoopCommentText(sourceCode, node, beforeText) {
-    if (/@story\b/.test(beforeText) ||
-        /@req\b/.test(beforeText) ||
-        /@supports\b/.test(beforeText)) {
-        return beforeText;
-    }
+function getInsideLoopCommentText(sourceCode, node) {
     const body = node.body;
     if (body &&
         body.type === "BlockStatement" &&
@@ -32,5 +20,31 @@ function gatherLoopCommentText(sourceCode, node, beforeText) {
             return insideText;
         }
     }
+    return "";
+}
+/**
+ * Gather annotation text for loop branches, supporting annotations either on the
+ * loop statement itself or on the first comment lines inside the loop body.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-LOOP-ANNOTATION
+ * @req REQ-LOOP-PLACEMENT-FLEXIBLE
+ */
+function gatherLoopCommentText(sourceCode, node, annotationPlacement, beforeText) {
+    if (annotationPlacement === "inside") {
+        const insideText = getInsideLoopCommentText(sourceCode, node);
+        if (insideText) {
+            return insideText;
+        }
+        return "";
+    }
+    if (/@story\b/.test(beforeText) ||
+        /@req\b/.test(beforeText) ||
+        /@supports\b/.test(beforeText)) {
+        return beforeText;
+    }
+    const insideText = getInsideLoopCommentText(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

@@ -201,6 +201,28 @@ if (condition) {}`,
   // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
   // @req REQ-INSIDE-BRACE-PLACEMENT
   doSomething();
+}`,
+                options: [{ annotationPlacement: "inside" }],
+            },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] catch clause annotated inside block under annotationPlacement: 'inside' (Story 028.0)",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-TRY
+try {
+  doSomething();
+} catch (error) {
+  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+  // @req REQ-INSIDE-CATCH
+  handleError(error);
+}`,
+                options: [{ annotationPlacement: "inside" }],
+            },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] for-of loop annotated inside block under annotationPlacement: 'inside' (Story 028.0)",
+                code: `for (const item of items) {
+  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+  // @req REQ-LOOP-INSIDE
+  process(item);
 }`,
                 options: [{ annotationPlacement: "inside" }],
             },
@@ -437,6 +459,102 @@ if (condition) {
 if (condition) {
   // @story <story-file>.story.md
   doSomething();
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-BEFORE-BRACE-ERROR][REQ-PLACEMENT-CONFIG] before-loop annotations ignored when annotationPlacement: 'inside' for loops",
+                code: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-LOOP-BEFORE
+for (const item of items) {
+  process(item);
+}`,
+                options: [{ annotationPlacement: "inside" }],
+                output: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-LOOP-BEFORE
+// @story <story-file>.story.md
+for (const item of items) {
+  process(item);
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-BEFORE-BRACE-ERROR][REQ-PLACEMENT-CONFIG] before-catch annotations ignored when annotationPlacement: 'inside' for CatchClause",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-TRY
+try {
+  doSomething();
+}
+// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-CATCH-BEFORE
+catch (error) {
+  handleError(error);
+}`,
+                options: [{ annotationPlacement: "inside" }],
+                output: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-TRY
+try {
+  doSomething();
+}
+// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-CATCH-BEFORE
+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

@@ -110,6 +110,87 @@ describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () =
         expect(sourceCodeLoop.getCommentsBefore).toHaveBeenCalledWith(forNode);
         expect(loopText).toBe("@story loop branch story loop details");
     });
+    it("[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] uses inside-loop comments when annotationPlacement is 'inside' and ignores before-loop annotations", () => {
+        const sourceCode = {
+            lines: [
+                "// @story before-loop should be ignored in inside mode",
+                "for (const item of items) {",
+                "  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md",
+                "  // @req REQ-LOOP-INSIDE",
+                "  process(item);",
+                "}",
+            ],
+            getCommentsBefore: jest
+                .fn()
+                .mockReturnValue([
+                { value: "@story before-loop should be ignored in inside mode" },
+            ]),
+        };
+        const loopNode = {
+            type: "ForOfStatement",
+            loc: {
+                start: { line: 2, column: 0 },
+                end: { line: 5, column: 1 },
+            },
+            body: {
+                type: "BlockStatement",
+                loc: {
+                    start: { line: 2, column: 27 },
+                    end: { line: 5, column: 1 },
+                },
+            },
+        };
+        const parent = {
+            type: "BlockStatement",
+            body: [loopNode],
+        };
+        const insideText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, loopNode, parent, "inside");
+        expect(insideText).toContain("@story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md");
+        expect(insideText).toContain("@req REQ-LOOP-INSIDE");
+        expect(insideText).not.toContain("before-loop should be ignored");
+    });
+    it("[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] uses inside-catch comments when annotationPlacement is 'inside' and ignores before-catch annotations", () => {
+        const sourceCode = {
+            lines: [
+                "// @story before-catch should be ignored in inside mode",
+                "try {",
+                "  doSomething();",
+                "}",
+                "catch (error) {",
+                "  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md",
+                "  // @req REQ-CATCH-INSIDE",
+                "  handleError(error);",
+                "}",
+            ],
+            getCommentsBefore: jest
+                .fn()
+                .mockReturnValue([
+                { value: "@story before-catch should be ignored in inside mode" },
+            ]),
+        };
+        const catchNode = {
+            type: "CatchClause",
+            loc: {
+                start: { line: 5, column: 0 },
+                end: { line: 8, column: 1 },
+            },
+            body: {
+                type: "BlockStatement",
+                loc: {
+                    start: { line: 5, column: 14 },
+                    end: { line: 8, column: 1 },
+                },
+            },
+        };
+        const parent = {
+            type: "TryStatement",
+            handler: catchNode,
+        };
+        const insideText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, catchNode, parent, "inside");
+        expect(insideText).toContain("@story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md");
+        expect(insideText).toContain("@req REQ-CATCH-INSIDE");
+        expect(insideText).not.toContain("before-catch should be ignored");
+    });
 });
 /**
  * Tests for annotationPlacement wiring at helper level
@@ -162,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.0",
+  "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",