eslint-plugin-traceability 1.18.0 → 1.19.1

package/CHANGELOG.md

@@ -1,9 +1,10 @@
-# [1.18.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.17.1...v1.18.0) (2025-12-18)
+## [1.19.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.0...v1.19.1) (2025-12-18)
 
 
-### Features
+### Bug Fixes
 
-* add annotationPlacement option for branch annotations ([9cf4189](https://github.com/voder-ai/eslint-plugin-traceability/commit/9cf41897cdbc962eb41f304847ba8a911987d0fd))
+* 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))
 
 # Changelog
 

package/lib/src/rules/no-redundant-annotation.js

@@ -86,7 +86,14 @@ function getScopePairs(context, scopeNode, parent) {
     const sourceCode = context.getSourceCode();
     // Branch-style scope: use the branch helpers to collect comment text.
     if (branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES.includes(scopeNode.type)) {
-        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent);
+        /**
+         * Inside-brace annotations used as branch-level indicators (inside placement
+         * mode) should not be folded into scopePairs for redundancy purposes; only
+         * before-brace annotations define the covering scope here.
+         *
+         * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-NON-REDUNDANT-INSIDE REQ-PLACEMENT-CONFIG
+         */
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent, "before");
         return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(text);
     }
     const comments = getScopeCommentsFromJSDocAndLeading(sourceCode, scopeNode);

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

@@ -41,7 +41,7 @@ export declare function scanCommentLinesInRange(lines: string[], startIndex: num
  * @supports REQ-DUAL-POSITION-DETECTION
  * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
-export declare function gatherBranchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, parent?: any, _annotationPlacement?: AnnotationPlacement): string;
+export declare function gatherBranchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, parent?: any, annotationPlacement?: AnnotationPlacement): string;
 /**
  * Report missing @story annotation tag on a branch node when that branch lacks a corresponding @story reference in its comments.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md

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

@@ -161,20 +161,81 @@ function isElseIfBranch(node, parent) {
         parent.type === "IfStatement" &&
         parent.alternate === node);
 }
+function getInsideCatchCommentText(sourceCode, node) {
+    const getCommentsInside = sourceCode.getCommentsInside;
+    if (node.body && typeof getCommentsInside === "function") {
+        try {
+            const insideComments = getCommentsInside(node.body) || [];
+            const insideText = insideComments.map(extractCommentValue).join(" ");
+            if (insideText) {
+                return insideText;
+            }
+        }
+        catch {
+            // fall through to line-based fallback
+        }
+    }
+    if (node.body && node.body.loc && node.body.loc.start && node.body.loc.end) {
+        const lines = sourceCode.lines;
+        const startIndex = node.body.loc.start.line - 1;
+        const endIndex = node.body.loc.end.line - 1;
+        const insideText = scanCommentLinesInRange(lines, startIndex + 1, endIndex);
+        if (insideText) {
+            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, beforeText) {
-    if (/@story\b/.test(beforeText) || /@req\b/.test(beforeText)) {
+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;
+}
+/**
+ * Gather annotation text for simple IfStatement branches, honoring the configured placement.
+ * When placement is "before", this helper preserves the existing behavior by returning the
+ * leading comment text unchanged. When placement is "inside", it switches to inside-brace
+ * semantics and scans for comments at the top of the consequent block.
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-INSIDE-BRACE-PLACEMENT
+ * @supports REQ-PLACEMENT-CONFIG
+ * @supports REQ-DEFAULT-BACKWARD-COMPAT
+ */
+function gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText) {
+    if (annotationPlacement === "before") {
+        return beforeText;
+    }
+    if (annotationPlacement !== "inside") {
         return beforeText;
     }
+    if (!node.consequent || node.consequent.type !== "BlockStatement") {
+        return "";
+    }
+    const consequent = node.consequent;
     const getCommentsInside = sourceCode.getCommentsInside;
-    if (node.body && typeof getCommentsInside === "function") {
+    if (typeof getCommentsInside === "function") {
         try {
-            const insideComments = getCommentsInside(node.body) || [];
+            const insideComments = getCommentsInside(consequent) || [];
             const insideText = insideComments.map(extractCommentValue).join(" ");
             if (insideText) {
                 return insideText;
@@ -184,16 +245,20 @@ function gatherCatchClauseCommentText(sourceCode, node, beforeText) {
             // fall through to line-based fallback
         }
     }
-    if (node.body && node.body.loc && node.body.loc.start && node.body.loc.end) {
+    if (consequent.loc &&
+        consequent.loc.start &&
+        consequent.loc.end &&
+        typeof consequent.loc.start.line === "number" &&
+        typeof consequent.loc.end.line === "number") {
         const lines = sourceCode.lines;
-        const startIndex = node.body.loc.start.line - 1;
-        const endIndex = node.body.loc.end.line - 1;
+        const startIndex = consequent.loc.start.line - 1;
+        const endIndex = consequent.loc.end.line - 1;
         const insideText = scanCommentLinesInRange(lines, startIndex + 1, endIndex);
         if (insideText) {
             return insideText;
         }
     }
-    return beforeText;
+    return "";
 }
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function scanElseIfPrecedingComments(sourceCode, node) {
@@ -310,48 +375,46 @@ function gatherSwitchCaseCommentText(sourceCode, node) {
     }
     return comments.join(" ");
 }
-/**
- * Gather leading comment text for a branch node.
- * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
- * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
- * @supports REQ-DUAL-POSITION-DETECTION
- * @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
-     */
+function gatherBranchCommentTextByType(sourceCode, node, parent, context) {
+    const { annotationPlacement, beforeText } = context;
     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);
+        return gatherCatchClauseCommentText(sourceCode, node, annotationPlacement, beforeText);
     }
-    /**
-     * Conditional branch for IfStatement else-if nodes that may include inline comments
-     * after the else-if condition but before the consequent body.
-     * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
-     * @supports REQ-DUAL-POSITION-DETECTION
-     */
     if (node.type === "IfStatement") {
-        return gatherElseIfCommentText(sourceCode, node, parent, beforeText);
+        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);
+        return (0, branch_annotation_loop_helpers_1.gatherLoopCommentText)(sourceCode, node, annotationPlacement, beforeText);
+    }
+    return null;
+}
+/**
+ * Gather leading comment text for a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ */
+function gatherBranchCommentText(sourceCode, node, parent, annotationPlacement = "before") {
+    const beforeComments = sourceCode.getCommentsBefore(node) || [];
+    const beforeText = beforeComments.map(extractCommentValue).join(" ");
+    const handled = gatherBranchCommentTextByType(sourceCode, node, parent, {
+        annotationPlacement,
+        beforeText,
+    });
+    if (handled != null) {
+        return handled;
     }
     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

@@ -52,6 +52,47 @@ function getBaseBranchIndentAndInsertPos(sourceCode, node, _annotationPlacement)
     }
     return { indent, insertPos };
 }
+/**
+ * Determine whether a node represents an else-if branch that should be used for
+ * determining comment insertion position.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ */
+function isElseIfBranchForInsert(node, parent) {
+    return (node &&
+        node.type === "IfStatement" &&
+        parent &&
+        parent.type === "IfStatement" &&
+        parent.alternate === node);
+}
+/**
+ * Compute indentation and insert position for IfStatement branches, handling
+ * both simple if and else-if cases, respecting the configured annotation
+ * placement and indentation rules.
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG REQ-INDENTATION-CORRECT
+ */
+function getIfStatementIndentAndInsertPos(sourceCode, node, options, context) {
+    const { parent, annotationPlacement } = options;
+    let { indent, insertPos } = context;
+    const hasBlockConsequent = node.consequent &&
+        node.consequent.type === "BlockStatement" &&
+        node.consequent.loc &&
+        node.consequent.loc.start;
+    if (!hasBlockConsequent) {
+        return context;
+    }
+    const isElseIf = isElseIfBranchForInsert(node, parent);
+    const isSimpleIfInsidePlacement = annotationPlacement === "inside" && !isElseIf;
+    if (isSimpleIfInsidePlacement || isElseIf) {
+        const commentLine = node.consequent.loc.start.line + 1;
+        const commentLineInfo = getIndentAndInsertPosForLine(sourceCode, commentLine, indent);
+        indent = commentLineInfo.indent;
+        insertPos = commentLineInfo.insertPos;
+        context.indent = indent;
+        context.insertPos = insertPos;
+    }
+    return context;
+}
 /**
  * Compute which annotations are missing for a branch based on its gathered comment text.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -70,19 +111,14 @@ function getBranchMissingFlags(sourceCode, node, parent, annotationPlacement) {
  * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 function getBranchIndentAndInsertPos(sourceCode, node, parent, annotationPlacement) {
-    let { indent, insertPos } = getBaseBranchIndentAndInsertPos(sourceCode, node, annotationPlacement);
-    if (node.type === "IfStatement" &&
-        parent &&
-        parent.type === "IfStatement" &&
-        parent.alternate === node &&
-        node.consequent &&
-        node.consequent.type === "BlockStatement" &&
-        node.consequent.loc &&
-        node.consequent.loc.start) {
-        const commentLine = node.consequent.loc.start.line + 1;
-        const commentLineInfo = getIndentAndInsertPosForLine(sourceCode, commentLine, indent);
-        indent = commentLineInfo.indent;
-        insertPos = commentLineInfo.insertPos;
+    const { indent, insertPos } = getBaseBranchIndentAndInsertPos(sourceCode, node, annotationPlacement);
+    if (node.type === "IfStatement") {
+        const context = { indent, insertPos };
+        const updatedContext = getIfStatementIndentAndInsertPos(sourceCode, node, { parent, annotationPlacement }, context);
+        return {
+            indent: updatedContext.indent,
+            insertPos: updatedContext.insertPos,
+        };
     }
     return { indent, insertPos };
 }

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

@@ -196,10 +196,34 @@ if (condition) {}`,
                 options: [{ annotationPlacement: "before" }],
             },
             {
-                name: "[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] if-statement with before-brace annotations using annotationPlacement: 'inside' (temporary backward-compatible behavior)",
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] if-statement annotated inside block under annotationPlacement: 'inside' (Story 028.0)",
+                code: `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-PLACEMENT-CONFIG
-if (condition) {}`,
+// @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" }],
             },
             {
@@ -422,6 +446,64 @@ if (a) {
 }`,
                 errors: makeMissingAnnotationErrors("@story", "@req", "@story", "@req"),
             },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-BEFORE-BRACE-ERROR][REQ-PLACEMENT-CONFIG] before-brace annotations ignored when annotationPlacement: 'inside'",
+                code: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-BEFORE-BRACE-ERROR
+if (condition) {
+  doSomething();
+}`,
+                options: [{ annotationPlacement: "inside" }],
+                output: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-BEFORE-BRACE-ERROR
+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"),
+            },
         ],
     });
     runRule({

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

@@ -110,4 +110,137 @@ 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
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-DEFAULT-BACKWARD-COMPAT
+ */
+describe("gatherBranchCommentText annotationPlacement wiring (Story 028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION)", () => {
+    it("[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] honors configured placement for simple if-statements", () => {
+        const sourceCode = {
+            lines: [
+                "function demo() {",
+                "  if (condition) {",
+                "    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md",
+                "    // @req REQ-INSIDE",
+                "    doSomething();",
+                "  }",
+                "}",
+            ],
+            getCommentsBefore: jest
+                .fn()
+                .mockReturnValue([
+                { value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md" },
+                { value: "@req REQ-BEFORE" },
+            ]),
+        };
+        const ifNode = {
+            type: "IfStatement",
+            loc: {
+                start: { line: 2, column: 2 },
+                end: { line: 5, column: 3 },
+            },
+            consequent: {
+                type: "BlockStatement",
+                loc: {
+                    start: { line: 2, column: 18 },
+                    end: { line: 5, column: 3 },
+                },
+            },
+        };
+        const parent = {
+            type: "BlockStatement",
+            body: [ifNode],
+        };
+        const beforeText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, ifNode, parent, "before");
+        expect(beforeText).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(beforeText).toContain("@req REQ-BEFORE");
+        const insideText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, ifNode, parent, "inside");
+        expect(insideText).toContain("@story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md");
+        expect(insideText).toContain("@req REQ-INSIDE");
+        expect(insideText).not.toContain("@req REQ-BEFORE");
+    });
 });

package/package.json

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