eslint-plugin-traceability 1.19.1 → 1.19.3

package/CHANGELOG.md

@@ -1,10 +1,9 @@
-## [1.19.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.0...v1.19.1) (2025-12-18)
+## [1.19.3](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.2...v1.19.3) (2025-12-18)
 
 
 ### Bug Fixes
 
-* apply inside placement semantics to loop branches ([e0ba06f](https://github.com/voder-ai/eslint-plugin-traceability/commit/e0ba06fb9aba6947c6ac675f65cc1fb4639dc785))
-* honor inside placement for catch clauses in branch annotation rule ([0e7a8e0](https://github.com/voder-ai/eslint-plugin-traceability/commit/0e7a8e01505bfa1e37e013dfda00e866f975ad33))
+* support inside placement for switch cases in branch helpers ([3fd08d1](https://github.com/voder-ai/eslint-plugin-traceability/commit/3fd08d1314085a7aa9894f6248dbb7f42a07bda0))
 
 # Changelog
 

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

@@ -9,7 +9,8 @@ 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 PRE_COMMENT_OFFSET = 2; // number of lines above branch to inspect for comments
+const branch_annotation_if_helpers_1 = require("./branch-annotation-if-helpers");
+const branch_annotation_switch_helpers_1 = require("./branch-annotation-switch-helpers");
 /**
  * Valid branch types for require-branch-annotation rule.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -153,14 +154,6 @@ function scanCommentLinesInRange(lines, startIndex, endIndexInclusive) {
     }
     return comments.join(" ");
 }
-/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-function isElseIfBranch(node, parent) {
-    return (node &&
-        node.type === "IfStatement" &&
-        parent &&
-        parent.type === "IfStatement" &&
-        parent.alternate === node);
-}
 function getInsideCatchCommentText(sourceCode, node) {
     const getCommentsInside = sourceCode.getCommentsInside;
     if (node.body && typeof getCommentsInside === "function") {
@@ -186,6 +179,30 @@ function getInsideCatchCommentText(sourceCode, node) {
     }
     return "";
 }
+/**
+ * Gather comment text from the first contiguous comment lines inside a TryStatement block body.
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+function getInsideTryBlockCommentText(sourceCode, node) {
+    const block = node && node.block;
+    if (!block ||
+        block.type !== "BlockStatement" ||
+        !block.loc ||
+        !block.loc.start ||
+        !block.loc.end ||
+        typeof block.loc.start.line !== "number" ||
+        typeof block.loc.end.line !== "number") {
+        return "";
+    }
+    const lines = sourceCode.lines;
+    const startIndex = block.loc.start.line - 1;
+    const endIndex = block.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
@@ -260,144 +277,105 @@ function gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, before
     }
     return "";
 }
-/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-function scanElseIfPrecedingComments(sourceCode, node) {
-    const lines = sourceCode.lines;
-    if (!node.loc || !node.loc.start || typeof node.loc.start.line !== "number") {
-        return "";
-    }
-    const startLine = node.loc.start.line - 1;
-    const comments = [];
-    let i = startLine - 1;
-    let scanned = 0;
-    while (i >= 0 && scanned < PRE_COMMENT_OFFSET) {
-        const commentText = getCommentTextAtLine(lines, i);
-        if (!commentText) {
-            break;
+function handleTryCatchBranch(sourceCode, node, context) {
+    const { annotationPlacement, beforeText } = context;
+    if (node.type === "TryStatement") {
+        if (annotationPlacement === "inside") {
+            const insideText = getInsideTryBlockCommentText(sourceCode, node);
+            if (insideText) {
+                return insideText;
+            }
+            return "";
         }
-        comments.unshift(commentText);
-        i--;
-        scanned++;
+        return beforeText;
     }
-    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 "";
+    if (node.type === "CatchClause") {
+        return gatherCatchClauseCommentText(sourceCode, node, annotationPlacement, beforeText);
     }
-    return scanCommentLinesInRange(lines, startIndex, endIndexExclusive - 1);
+    return null;
 }
-/** @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++;
+function handleLoopBranch(sourceCode, node, context) {
+    const { annotationPlacement, beforeText } = context;
+    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 comments.join(" ");
+    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.
- * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
- * @supports REQ-DUAL-POSITION-DETECTION
- * @supports REQ-FALLBACK-LOGIC
+ * 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 gatherElseIfCommentText(sourceCode, node, parent, beforeText) {
-    if (beforeText &&
-        (/@story\b/.test(beforeText) ||
-            /@req\b/.test(beforeText) ||
-            /@supports\b/.test(beforeText))) {
-        return beforeText;
-    }
-    if (!isElseIfBranch(node, parent)) {
-        return beforeText;
-    }
-    const beforeElseText = scanElseIfPrecedingComments(sourceCode, node);
-    if (beforeElseText &&
-        (/@story\b/.test(beforeElseText) ||
-            /@req\b/.test(beforeElseText) ||
-            /@supports\b/.test(beforeElseText))) {
-        return beforeElseText;
-    }
-    if (!hasValidElseIfBlockLoc(node)) {
-        return beforeText;
-    }
-    const betweenText = scanElseIfBetweenConditionAndBody(sourceCode, node);
-    if (betweenText) {
-        return betweenText;
+function gatherNonIfBranchCommentText(sourceCode, node, context) {
+    if (node.type === "SwitchCase") {
+        const { annotationPlacement, beforeText } = context;
+        return (0, branch_annotation_switch_helpers_1.gatherSwitchCaseCommentText)(sourceCode, node, annotationPlacement, beforeText);
     }
-    const insideText = scanElseIfInsideBlockComments(sourceCode, node);
-    if (insideText) {
-        return insideText;
+    const tryCatchResult = handleTryCatchBranch(sourceCode, node, context);
+    if (tryCatchResult != null) {
+        return tryCatchResult;
     }
-    return beforeText;
-}
-/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-function gatherSwitchCaseCommentText(sourceCode, node) {
-    const lines = sourceCode.lines;
-    const startLine = node.loc.start.line;
-    let i = startLine - PRE_COMMENT_OFFSET;
-    const comments = [];
-    while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
-        comments.unshift(lines[i].trim());
-        i--;
+    const loopResult = handleLoopBranch(sourceCode, node, context);
+    if (loopResult != null) {
+        return loopResult;
     }
-    return comments.join(" ");
+    return null;
 }
-function gatherBranchCommentTextByType(sourceCode, node, parent, context) {
+/**
+ * Helper that gathers comment text for IfStatement branches, including both
+ * simple if and else-if specific logic.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports REQ-COMMENT-ASSOCIATION
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports REQ-DUAL-POSITION-DETECTION
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-PLACEMENT-CONFIG
+ * @supports REQ-DEFAULT-BACKWARD-COMPAT
+ */
+function gatherIfBranchCommentText(sourceCode, node, parent, context) {
     const { annotationPlacement, beforeText } = context;
-    if (node.type === "SwitchCase") {
-        return gatherSwitchCaseCommentText(sourceCode, node);
+    if (node.type !== "IfStatement") {
+        return null;
     }
-    if (node.type === "CatchClause") {
-        return gatherCatchClauseCommentText(sourceCode, node, annotationPlacement, beforeText);
+    if ((0, branch_annotation_if_helpers_1.isElseIfBranch)(node, parent)) {
+        return (0, branch_annotation_if_helpers_1.gatherElseIfCommentText)(sourceCode, node, parent, {
+            annotationPlacement,
+            beforeText,
+        });
     }
-    if (node.type === "IfStatement") {
-        if (isElseIfBranch(node, parent)) {
-            return gatherElseIfCommentText(sourceCode, node, parent, beforeText);
-        }
-        return gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText);
+    return gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText);
+}
+/**
+ * Internal helper that performs type-based dispatch for gathering branch comment text.
+ * This keeps the public gatherBranchCommentTextByType wrapper small for ESLint limits.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports REQ-COMMENT-ASSOCIATION
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports REQ-DUAL-POSITION-DETECTION
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-PLACEMENT-CONFIG
+ */
+function gatherBranchCommentTextByTypeInternal(sourceCode, node, parent, context) {
+    const nonIfResult = gatherNonIfBranchCommentText(sourceCode, node, context);
+    if (nonIfResult != null) {
+        return nonIfResult;
     }
-    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);
+    const ifResult = gatherIfBranchCommentText(sourceCode, node, parent, context);
+    if (ifResult != null) {
+        return ifResult;
     }
     return null;
 }
+function gatherBranchCommentTextByType(sourceCode, node, parent, context) {
+    return gatherBranchCommentTextByTypeInternal(sourceCode, node, parent, context);
+}
 /**
  * Gather leading comment text for a branch node.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md

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

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

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

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

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

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

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

@@ -0,0 +1,11 @@
+import type { Rule } from "eslint";
+import { type AnnotationPlacement } from "./branch-annotation-helpers";
+/**
+ * Gather annotation text for SwitchCase branches, honoring the configured placement
+ * while preserving legacy before-branch behavior in the default mode.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-PLACEMENT-CONFIG
+ * @supports REQ-INSIDE-BRACE-PLACEMENT
+ */
+export declare function gatherSwitchCaseCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, annotationPlacement: AnnotationPlacement, beforeText: string): string;

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

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatherSwitchCaseCommentText = gatherSwitchCaseCommentText;
+const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
+/**
+ * Gather comment text from the first contiguous comment lines "inside" a SwitchCase body.
+ * Prefers a BlockStatement consequent when present, with a fallback to the entire case range.
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-INSIDE-BRACE-PLACEMENT
+ * @supports REQ-PLACEMENT-CONFIG
+ */
+function getInsideSwitchCaseCommentText(sourceCode, node) {
+    const lines = sourceCode.lines;
+    const firstConsequent = node.consequent && node.consequent[0];
+    if (firstConsequent &&
+        firstConsequent.type === "BlockStatement" &&
+        firstConsequent.loc &&
+        firstConsequent.loc.start &&
+        firstConsequent.loc.end &&
+        typeof firstConsequent.loc.start.line === "number" &&
+        typeof firstConsequent.loc.end.line === "number") {
+        const startIndex = firstConsequent.loc.start.line - 1;
+        const endIndex = firstConsequent.loc.end.line - 1;
+        const insideText = (0, branch_annotation_helpers_1.scanCommentLinesInRange)(lines, startIndex + 1, endIndex);
+        if (insideText) {
+            return insideText;
+        }
+        return "";
+    }
+    if (node.loc &&
+        node.loc.start &&
+        node.loc.end &&
+        typeof node.loc.start.line === "number" &&
+        typeof node.loc.end.line === "number") {
+        const startIndex = node.loc.start.line - 1;
+        const endIndex = node.loc.end.line - 1;
+        const insideText = (0, branch_annotation_helpers_1.scanCommentLinesInRange)(lines, startIndex + 1, endIndex);
+        if (insideText) {
+            return insideText;
+        }
+    }
+    return "";
+}
+/**
+ * Gather annotation text for SwitchCase branches, honoring the configured placement
+ * while preserving legacy before-branch behavior in the default mode.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-PLACEMENT-CONFIG
+ * @supports REQ-INSIDE-BRACE-PLACEMENT
+ */
+function gatherSwitchCaseCommentText(sourceCode, node, annotationPlacement, beforeText) {
+    if (annotationPlacement === "inside") {
+        const insideText = getInsideSwitchCaseCommentText(sourceCode, node);
+        if (insideText) {
+            return insideText;
+        }
+        return "";
+    }
+    if (/@story\b/.test(beforeText) ||
+        /@req\b/.test(beforeText) ||
+        /@supports\b/.test(beforeText)) {
+        return beforeText;
+    }
+    // In before-placement mode, rely on the caller's beforeText and any
+    // configured PRE_COMMENT_OFFSET logic in the main helpers module.
+    return beforeText;
+}

package/lib/tests/integration/annotation-placement-inside-prettier.integration.test.d.ts

@@ -0,0 +1 @@
+export {};