eslint-plugin-traceability 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.18.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.17.1...v1.18.0) (2025-12-18)
+# [1.19.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.18.0...v1.19.0) (2025-12-18)
 
 
 ### Features
 
-* add annotationPlacement option for branch annotations ([9cf4189](https://github.com/voder-ai/eslint-plugin-traceability/commit/9cf41897cdbc962eb41f304847ba8a911987d0fd))
+* enforce inside-brace placement mode for branch annotations ([5c2129a](https://github.com/voder-ai/eslint-plugin-traceability/commit/5c2129a7c25717dc4ce14bf55bc4541ae07e5539))
 
 # 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

@@ -195,6 +195,55 @@ function gatherCatchClauseCommentText(sourceCode, node, beforeText) {
     }
     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 (typeof getCommentsInside === "function") {
+        try {
+            const insideComments = getCommentsInside(consequent) || [];
+            const insideText = insideComments.map(extractCommentValue).join(" ");
+            if (insideText) {
+                return insideText;
+            }
+        }
+        catch {
+            // fall through to line-based fallback
+        }
+    }
+    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 = consequent.loc.start.line - 1;
+        const endIndex = consequent.loc.end.line - 1;
+        const insideText = scanCommentLinesInRange(lines, startIndex + 1, endIndex);
+        if (insideText) {
+            return insideText;
+        }
+    }
+    return "";
+}
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function scanElseIfPrecedingComments(sourceCode, node) {
     const lines = sourceCode.lines;
@@ -318,7 +367,7 @@ function gatherSwitchCaseCommentText(sourceCode, node) {
  * @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") {
+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
@@ -333,13 +382,21 @@ function gatherBranchCommentText(sourceCode, node, parent, _annotationPlacement
         return gatherCatchClauseCommentText(sourceCode, node, beforeText);
     }
     /**
-     * Conditional branch for IfStatement else-if nodes that may include inline comments
-     * after the else-if condition but before the consequent body.
+     * 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") {
-        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

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,12 @@ 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)",
-                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-PLACEMENT-CONFIG
-if (condition) {}`,
+                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" }],
             },
             {
@@ -422,6 +424,22 @@ 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"),
+            },
         ],
     });
     runRule({

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

@@ -111,3 +111,55 @@ describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () =
         expect(loopText).toBe("@story loop branch story loop details");
     });
 });
+/**
+ * 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.0",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",