eslint-plugin-traceability 1.19.0 → 1.19.1

package/CHANGELOG.md

@@ -1,9 +1,10 @@
-# [1.19.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.18.0...v1.19.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
 
-* enforce inside-brace placement mode for branch annotations ([5c2129a](https://github.com/voder-ai/eslint-plugin-traceability/commit/5c2129a7c25717dc4ce14bf55bc4541ae07e5539))
+* 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/utils/branch-annotation-helpers.js

@@ -161,16 +161,7 @@ function isElseIfBranch(node, 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 +184,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;
 }
 /**
@@ -359,56 +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 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);
+        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/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,48 @@ 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"),
             },

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

package/package.json

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