eslint-plugin-traceability 1.19.2 → 1.19.4

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.19.2](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.1...v1.19.2) (2025-12-18)
+## [1.19.4](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.3...v1.19.4) (2025-12-18)
 
 
 ### Bug Fixes
 
-* honor annotationPlacement for else-if branches and refactor helpers ([8f747dc](https://github.com/voder-ai/eslint-plugin-traceability/commit/8f747dc8546ae8e5033cfe4aa9c394ca668a45d5))
+* migrate before-brace annotations into inside-brace placement ([c8c381d](https://github.com/voder-ai/eslint-plugin-traceability/commit/c8c381d5f5fbd39fdb626e9dd6fe2dd837bffb53))
 
 # Changelog
 

package/README.md

@@ -89,6 +89,47 @@ export default [
 ];
 ```
 
+### Annotation Placement
+
+Traceability annotations are typically placed immediately adjacent to the code they index. The plugin exposes explicit placement options for branch-level rules and a stable, conventional placement for function-level rules.
+
+- **Branch-level (`traceability/require-branch-annotation`)**
+
+  `require-branch-annotation` supports an `annotationPlacement` option:
+  - `"before"` – Annotation appears **immediately before** the branch statement (default).
+  - `"inside"` – Annotation appears as the **first comment-only lines inside** the branch block.
+
+  In `"inside"` mode, the rule expects the annotation to be the first meaningful content inside blocks for `if` / `else` / loops / `try` / `catch` / `finally` / `switch` cases.
+
+  Example (`if` statement):
+
+  ```js
+  // annotationPlacement: "before"
+  // @supports docs/stories/auth.md REQ-AUTH-VALIDATION
+  if (isValidUser(user)) {
+    performLogin(user);
+  }
+
+  // annotationPlacement: "inside"
+  if (isValidUser(user)) {
+    // @supports docs/stories/auth.md REQ-AUTH-VALIDATION
+    performLogin(user);
+  }
+  ```
+
+- **Function-level (`traceability/require-story-annotation`, `traceability/require-req-annotation`)**
+
+  Function-level rules continue to accept annotations:
+  - As JSDoc blocks immediately preceding the function, or
+  - As line comments placed directly before the function declaration or expression.
+
+  This placement is stable and supported for all current versions. Future versions may introduce an **inside-brace** placement mode for function bodies (similar to branch blocks) to align function annotations with the branch-level `"inside"` standard.
+
+For full configuration details and migration guidance between placement styles, see:
+
+- `traceability/require-branch-annotation` rule docs: [docs/rules/require-branch-annotation.md](docs/rules/require-branch-annotation.md)
+- Migration guide: [user-docs/migration-guide.md](user-docs/migration-guide.md)
+
 ### Available Rules
 
 The plugin exposes several rules. For **new configurations**, the unified function-level rule and `@supports` annotations are the canonical choice; the `@story` and `@req` forms remain available primarily for backward compatibility and gradual migration.

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

@@ -53,6 +53,8 @@ export declare function reportMissingStory(context: Rule.RuleContext, node: any,
     storyFixCountRef: {
         count: number;
     };
+    annotationPlacement: AnnotationPlacement;
+    sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>;
 }): void;
 /**
  * Report missing @req annotation tag on a branch node when that branch has no linked requirement identifier in its associated comments.

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

@@ -10,7 +10,8 @@ const branch_annotation_report_helpers_1 = require("./branch-annotation-report-h
 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
+const branch_annotation_switch_helpers_1 = require("./branch-annotation-switch-helpers");
+const branch_annotation_story_fix_helpers_1 = require("./branch-annotation-story-fix-helpers");
 /**
  * Valid branch types for require-branch-annotation rule.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -179,6 +180,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
@@ -253,17 +278,33 @@ function gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, before
     }
     return "";
 }
-/** @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--;
+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 "";
+        }
+        return beforeText;
     }
-    return comments.join(" ");
+    if (node.type === "CatchClause") {
+        return gatherCatchClauseCommentText(sourceCode, node, annotationPlacement, beforeText);
+    }
+    return null;
+}
+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 null;
 }
 /**
  * Helper that gathers comment text for non-IfStatement branch types using
@@ -274,19 +315,17 @@ function gatherSwitchCaseCommentText(sourceCode, node) {
  * @supports REQ-PLACEMENT-CONFIG
  */
 function gatherNonIfBranchCommentText(sourceCode, node, context) {
-    const { annotationPlacement, beforeText } = context;
     if (node.type === "SwitchCase") {
-        return gatherSwitchCaseCommentText(sourceCode, node);
+        const { annotationPlacement, beforeText } = context;
+        return (0, branch_annotation_switch_helpers_1.gatherSwitchCaseCommentText)(sourceCode, node, annotationPlacement, beforeText);
     }
-    if (node.type === "CatchClause") {
-        return gatherCatchClauseCommentText(sourceCode, node, annotationPlacement, beforeText);
+    const tryCatchResult = handleTryCatchBranch(sourceCode, node, context);
+    if (tryCatchResult != null) {
+        return tryCatchResult;
     }
-    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 loopResult = handleLoopBranch(sourceCode, node, context);
+    if (loopResult != null) {
+        return loopResult;
     }
     return null;
 }
@@ -364,21 +403,20 @@ function gatherBranchCommentText(sourceCode, node, parent, annotationPlacement =
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  */
 function reportMissingStory(context, node, options) {
-    const { indent, insertPos, storyFixCountRef } = options;
+    const { indent, insertPos, storyFixCountRef, annotationPlacement, sourceCode, } = options;
     /**
      * Conditional branch deciding whether to offer an auto-fix for the missing story.
      * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
      * @req REQ-TRACEABILITY-FIX-DECISION - Trace decision to provide fixer for missing @story
      */
     if (storyFixCountRef.count === 0) {
-        /**
-         * Fixer that inserts a default @story tag above the branch.
-         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-         * @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer function used to insert missing @story
-         */
-        function insertStoryFixer(fixer) {
-            return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`);
-        }
+        const insertStoryFixer = (0, branch_annotation_story_fix_helpers_1.createStoryFixer)({
+            annotationPlacement,
+            sourceCode,
+            node,
+            insertPos,
+            indent,
+        });
         context.report({
             node,
             messageId: "missingAnnotation",

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

@@ -0,0 +1,52 @@
+import type { Rule } from "eslint";
+import type { AnnotationPlacement } from "./branch-annotation-helpers";
+/**
+ * Shared helpers for computing inside-brace indentation and insert positions
+ * for branch nodes used by require-branch-annotation. This module isolates
+ * the inside-placement logic so that the main report helpers stay small and
+ * within ESLint's max-lines-per-function limits.
+ *
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG REQ-INDENTATION-CORRECT
+ */
+type SourceCode = ReturnType<Rule.RuleContext["getSourceCode"]>;
+type IndentHelperContext = {
+    getInsideBlockIndentAndInsertPos: (_sourceCode: SourceCode, _blockNode: any, _baseFallbackIndent: string) => {
+        indent: string;
+        insertPos: number;
+    };
+    getIndentAndInsertPosForLine: (_sourceCode: SourceCode, _line: number, _fallbackIndent: string) => {
+        indent: string;
+        insertPos: number;
+    };
+};
+type BranchIndentOptions = {
+    sourceCode: SourceCode;
+    node: any;
+    indent: string;
+};
+/**
+ * Inside-placement helper used by getBaseBranchIndentAndInsertPos to select the
+ * correct inside-placement strategy for the base branch.
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+export declare function computeInsideBaseIndentAndInsertPos(options: {
+    sourceCode: SourceCode;
+    node: any;
+    annotationPlacement: AnnotationPlacement;
+    currentIndent: string;
+}, context: IndentHelperContext): {
+    indent: string;
+    insertPos: number;
+} | null;
+/**
+ * Apply inside-placement overrides for non-if branches (switch, try, loops, catch).
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+export declare function applyInsidePlacementOverridesForBranch(options: BranchIndentOptions & {
+    annotationPlacement: AnnotationPlacement;
+}, context: IndentHelperContext): {
+    indent: string;
+    insertPos: number;
+} | null;
+export {};

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

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeInsideBaseIndentAndInsertPos = computeInsideBaseIndentAndInsertPos;
+exports.applyInsidePlacementOverridesForBranch = applyInsidePlacementOverridesForBranch;
+function isLoopNode(node) {
+    return (node.type === "ForStatement" ||
+        node.type === "ForInStatement" ||
+        node.type === "ForOfStatement" ||
+        node.type === "WhileStatement" ||
+        node.type === "DoWhileStatement");
+}
+function computeInsideCatchIndentAndInsertPos(sourceCode, node, currentIndent, context) {
+    if (!(node.type === "CatchClause" && node.body)) {
+        return null;
+    }
+    const bodyNode = node.body;
+    if (!bodyNode.loc || !bodyNode.loc.start) {
+        return null;
+    }
+    return context.getInsideBlockIndentAndInsertPos(sourceCode, bodyNode, currentIndent);
+}
+function computeInsideLoopIndentAndInsertPos(options, context) {
+    const { sourceCode, node, indent } = options;
+    if (!isLoopNode(node) ||
+        !node.body ||
+        node.body.type !== "BlockStatement" ||
+        !node.body.loc ||
+        !node.body.loc.start) {
+        return null;
+    }
+    return context.getInsideBlockIndentAndInsertPos(sourceCode, node.body, indent);
+}
+function computeInsideTryOrSwitchIndentAndInsertPos(sourceCode, node, currentIndent, context) {
+    if (!((node.type === "TryStatement" || node.type === "SwitchCase") &&
+        node.consequent &&
+        Array.isArray(node.consequent) &&
+        node.consequent.length > 0)) {
+        return null;
+    }
+    const firstStatement = node.consequent[0];
+    if (!firstStatement || !firstStatement.loc || !firstStatement.loc.start) {
+        return null;
+    }
+    const commentLineInfo = context.getIndentAndInsertPosForLine(sourceCode, firstStatement.loc.start.line, currentIndent);
+    return {
+        indent: commentLineInfo.indent,
+        insertPos: commentLineInfo.insertPos,
+    };
+}
+function computeInsideTryBlockIndentAndInsertPos(options, context) {
+    const { sourceCode, node, indent } = options;
+    if (!(node.type === "TryStatement" &&
+        node.block &&
+        node.block.type === "BlockStatement" &&
+        node.block.loc &&
+        node.block.loc.start)) {
+        return null;
+    }
+    return context.getInsideBlockIndentAndInsertPos(sourceCode, node.block, indent);
+}
+function computeInsideSwitchCaseIndentAndInsertPos(options, context) {
+    const { sourceCode, node, indent } = options;
+    if (!(node.type === "SwitchCase" &&
+        node.consequent &&
+        Array.isArray(node.consequent) &&
+        node.consequent.length > 0)) {
+        return null;
+    }
+    const firstStatement = node.consequent[0];
+    if (!firstStatement || !firstStatement.loc || !firstStatement.loc.start) {
+        return null;
+    }
+    // Prefer line-based helper for consistency with other callers.
+    const commentLineInfo = context.getIndentAndInsertPosForLine(sourceCode, firstStatement.loc.start.line, indent);
+    return {
+        indent: commentLineInfo.indent,
+        insertPos: commentLineInfo.insertPos,
+    };
+}
+function computeInsideCatchBlockIndentAndInsertPos(options, context) {
+    const { sourceCode, node, indent } = options;
+    if (!(node.type === "CatchClause" &&
+        node.body &&
+        node.body.type === "BlockStatement" &&
+        node.body.loc &&
+        node.body.loc.start)) {
+        return null;
+    }
+    return context.getInsideBlockIndentAndInsertPos(sourceCode, node.body, indent);
+}
+/**
+ * Inside-placement helper used by getBaseBranchIndentAndInsertPos to select the
+ * correct inside-placement strategy for the base branch.
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+function computeInsideBaseIndentAndInsertPos(options, context) {
+    const { sourceCode, node, annotationPlacement, currentIndent } = options;
+    if (annotationPlacement !== "inside") {
+        return null;
+    }
+    const catchInside = computeInsideCatchIndentAndInsertPos(sourceCode, node, currentIndent, context);
+    if (catchInside) {
+        return catchInside;
+    }
+    const loopInside = computeInsideLoopIndentAndInsertPos({ sourceCode, node, indent: currentIndent }, context);
+    if (loopInside) {
+        return loopInside;
+    }
+    const tryOrSwitchInside = computeInsideTryOrSwitchIndentAndInsertPos(sourceCode, node, currentIndent, context);
+    if (tryOrSwitchInside) {
+        return tryOrSwitchInside;
+    }
+    return null;
+}
+/**
+ * Apply inside-placement overrides for non-if branches (switch, try, loops, catch).
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+function applyInsidePlacementOverridesForBranch(options, context) {
+    const { annotationPlacement } = options;
+    if (annotationPlacement !== "inside") {
+        return null;
+    }
+    const calculators = [
+        computeInsideSwitchCaseIndentAndInsertPos,
+        computeInsideTryBlockIndentAndInsertPos,
+        computeInsideLoopIndentAndInsertPos,
+        computeInsideCatchBlockIndentAndInsertPos,
+    ];
+    for (const calculator of calculators) {
+        const result = calculator(options, context);
+        if (result) {
+            return result;
+        }
+    }
+    return null;
+}

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

@@ -5,6 +5,7 @@ import type { Rule } from "eslint";
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
  * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 export declare function reportMissingAnnotations(context: Rule.RuleContext, node: any, storyFixCountRef: {

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reportMissingAnnotations = reportMissingAnnotations;
 const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
+const branch_annotation_indent_helpers_1 = require("./branch-annotation-indent-helpers");
 /**
  * Compute indentation and insert position for the start of a given 1-based line
  * number. This keeps indentation and fixer insert positions consistent across
@@ -23,11 +24,43 @@ function getIndentAndInsertPosForLine(sourceCode, line, fallbackIndent) {
     return { indent, insertPos };
 }
 /**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ * Compute indentation and insert position for the first "inner" line of a
+ * BlockStatement, used for inside-brace insertion.
+ * Falls back to the block's own line with one extra indent step if it has no
+ * body statements.
  */
-function getBaseBranchIndentAndInsertPos(sourceCode, node, _annotationPlacement) {
-    let { indent, insertPos } = getIndentAndInsertPosForLine(sourceCode, node.loc.start.line, "");
+function getInsideBlockIndentAndInsertPos(sourceCode, blockNode, baseFallbackIndent) {
+    let indent = baseFallbackIndent;
+    let insertPos = sourceCode.getIndexFromLoc({
+        line: blockNode.loc.start.line,
+        column: 0,
+    });
+    const bodyStatements = Array.isArray(blockNode.body)
+        ? blockNode.body
+        : undefined;
+    const firstStatement = bodyStatements && bodyStatements.length > 0 ? bodyStatements[0] : undefined;
+    if (firstStatement && firstStatement.loc && firstStatement.loc.start) {
+        const firstLine = firstStatement.loc.start.line;
+        const firstLineInfo = getIndentAndInsertPosForLine(sourceCode, firstLine, baseFallbackIndent);
+        indent = firstLineInfo.indent;
+        insertPos = firstLineInfo.insertPos;
+    }
+    else if (blockNode.loc && blockNode.loc.start) {
+        const blockLine = blockNode.loc.start.line;
+        const blockLineInfo = getIndentAndInsertPosForLine(sourceCode, blockLine, baseFallbackIndent);
+        const innerIndent = `${blockLineInfo.indent}  `;
+        indent = innerIndent;
+        insertPos = blockLineInfo.insertPos;
+    }
+    return { indent, insertPos };
+}
+/**
+ * Apply the base catch-clause indentation/insert-position fallback used by
+ * getBaseBranchIndentAndInsertPos when no inside-placement override is applied.
+ */
+function applyCatchClauseBaseIndentFallback(sourceCode, node, currentIndent, currentInsertPos) {
+    let indent = currentIndent;
+    let insertPos = currentInsertPos;
     if (node.type === "CatchClause" && node.body) {
         const bodyNode = node.body;
         const bodyStatements = Array.isArray(bodyNode.body)
@@ -52,6 +85,27 @@ function getBaseBranchIndentAndInsertPos(sourceCode, node, _annotationPlacement)
     }
     return { indent, insertPos };
 }
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ */
+function getBaseBranchIndentAndInsertPos(sourceCode, node, annotationPlacement) {
+    let { indent, insertPos } = getIndentAndInsertPosForLine(sourceCode, node.loc.start.line, "");
+    const indentHelpers = {
+        getInsideBlockIndentAndInsertPos,
+        getIndentAndInsertPosForLine,
+    };
+    const insideBase = (0, branch_annotation_indent_helpers_1.computeInsideBaseIndentAndInsertPos)({
+        sourceCode,
+        node,
+        annotationPlacement,
+        currentIndent: indent,
+    }, indentHelpers);
+    if (insideBase) {
+        return insideBase;
+    }
+    return applyCatchClauseBaseIndentFallback(sourceCode, node, indent, insertPos);
+}
 /**
  * Determine whether a node represents an else-if branch that should be used for
  * determining comment insertion position.
@@ -112,7 +166,8 @@ 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) {
-    const { indent, insertPos } = getBaseBranchIndentAndInsertPos(sourceCode, node, annotationPlacement);
+    const base = getBaseBranchIndentAndInsertPos(sourceCode, node, annotationPlacement);
+    let { indent, insertPos } = base;
     if (node.type === "IfStatement") {
         const context = { indent, insertPos };
         const updatedContext = getIfStatementIndentAndInsertPos(sourceCode, node, { parent, annotationPlacement }, context);
@@ -121,6 +176,19 @@ function getBranchIndentAndInsertPos(sourceCode, node, parent, annotationPlaceme
             insertPos: updatedContext.insertPos,
         };
     }
+    const indentHelpers = {
+        getInsideBlockIndentAndInsertPos,
+        getIndentAndInsertPosForLine,
+    };
+    const insideOverride = (0, branch_annotation_indent_helpers_1.applyInsidePlacementOverridesForBranch)({
+        sourceCode,
+        node,
+        indent,
+        annotationPlacement,
+    }, indentHelpers);
+    if (insideOverride) {
+        return insideOverride;
+    }
     return { indent, insertPos };
 }
 /**
@@ -137,12 +205,22 @@ function getBranchAnnotationInfo(sourceCode, node, parent, annotationPlacement)
     const { indent, insertPos } = getBranchIndentAndInsertPos(sourceCode, node, parent, annotationPlacement);
     return { missingStory, missingReq, indent, insertPos };
 }
+function processMissingAnnotationActions(context, node, actions) {
+    /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+    function processAction(item) {
+        if (item.missing) {
+            item.fn(...item.args);
+        }
+    }
+    actions.forEach(processAction);
+}
 /**
  * Report missing annotations on a branch node.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
  * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 function reportMissingAnnotations(context, node, storyFixCountRef) {
@@ -159,7 +237,17 @@ function reportMissingAnnotations(context, node, storyFixCountRef) {
         {
             missing: missingStory,
             fn: branch_annotation_helpers_1.reportMissingStory,
-            args: [context, node, { indent, insertPos, storyFixCountRef }],
+            args: [
+                context,
+                node,
+                {
+                    indent,
+                    insertPos,
+                    storyFixCountRef,
+                    annotationPlacement,
+                    sourceCode,
+                },
+            ],
         },
         {
             missing: missingReq,
@@ -167,11 +255,5 @@ function reportMissingAnnotations(context, node, storyFixCountRef) {
             args: [context, node, { indent, insertPos, missingStory }],
         },
     ];
-    /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-    function processAction(item) {
-        if (item.missing) {
-            item.fn(...item.args);
-        }
-    }
-    actions.forEach(processAction);
+    processMissingAnnotationActions(context, node, actions);
 }

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

@@ -0,0 +1,27 @@
+import type { Rule } from "eslint";
+import type { AnnotationPlacement } from "./branch-annotation-helpers";
+/**
+ * Context object for building story-fixers used by require-branch-annotation.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG REQ-INSIDE-BRACE-PLACEMENT
+ */
+export interface StoryFixContext {
+    annotationPlacement: AnnotationPlacement;
+    sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>;
+    node: any;
+    insertPos: number;
+    indent: string;
+}
+/**
+ * Create a fixer function that inserts or migrates a @story comment for a
+ * missing branch annotation, honoring the configured placement mode.
+ * When annotationPlacement is "inside", this helper uses
+ * buildInsidePlacementStoryFixes to migrate existing before-branch
+ * annotations into the standardized inside-brace location. Otherwise, it
+ * preserves the original "before" behavior of inserting directly above
+ * the branch.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-AUTO-FIX-MIGRATION REQ-INDENTATION-CORRECT
+ */
+export declare function createStoryFixer(ctx: StoryFixContext): (fixer: any) => any;

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStoryFixer = createStoryFixer;
+/**
+ * Build the individual fixes needed when migrating existing before-branch
+ * annotations into inside-brace placement. This helper is responsible for
+ * removing redundant before-branch comments that already contain
+ * traceability tags and inserting the canonical placeholder inside the
+ * branch body at the computed insertion position.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-AUTO-FIX-MIGRATION REQ-INSIDE-BRACE-PLACEMENT
+ */
+function buildInsidePlacementStoryFixes(ctx, fixer) {
+    const { sourceCode, node, insertPos, indent } = ctx;
+    const fixes = [];
+    const beforeComments = sourceCode.getCommentsBefore(node) || [];
+    const removableComments = beforeComments.filter((c) => /@story\b/.test(c.value) ||
+        /@req\b/.test(c.value) ||
+        /@supports\b/.test(c.value));
+    removableComments.forEach((comment) => {
+        fixes.push(fixer.remove(comment));
+    });
+    fixes.push(fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`));
+    return fixes;
+}
+/**
+ * Create a fixer function that inserts or migrates a @story comment for a
+ * missing branch annotation, honoring the configured placement mode.
+ * When annotationPlacement is "inside", this helper uses
+ * buildInsidePlacementStoryFixes to migrate existing before-branch
+ * annotations into the standardized inside-brace location. Otherwise, it
+ * preserves the original "before" behavior of inserting directly above
+ * the branch.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-AUTO-FIX-MIGRATION REQ-INDENTATION-CORRECT
+ */
+function createStoryFixer(ctx) {
+    const { annotationPlacement, insertPos, indent } = ctx;
+    function insertStoryFixer(fixer) {
+        if (annotationPlacement === "inside") {
+            return buildInsidePlacementStoryFixes(ctx, fixer);
+        }
+        return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`);
+    }
+    return insertStoryFixer;
+}

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;