eslint-plugin-traceability 1.19.3 → 1.19.4

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.19.3](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.2...v1.19.3) (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
 
-* support inside placement for switch cases in branch helpers ([3fd08d1](https://github.com/voder-ai/eslint-plugin-traceability/commit/3fd08d1314085a7aa9894f6248dbb7f42a07bda0))
+* 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

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "reportMissingAnnotations", { enumerable: true, g
 const branch_annotation_loop_helpers_1 = require("./branch-annotation-loop-helpers");
 const branch_annotation_if_helpers_1 = require("./branch-annotation-if-helpers");
 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
@@ -402,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/tests/rules/require-branch-annotation.test.js

@@ -473,16 +473,7 @@ try {
   handleError(error);
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-BRANCH-TRY
-// @story <story-file>.story.md
-try {
-  doSomething();
-} catch (error) {
-  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-  // @req REQ-INSIDE-CATCH
-  handleError(error);
-}`,
+                output: "\n\ntry {\n  // @story <story-file>.story.md\n  doSomething();\n} catch (error) {\n  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n  // @req REQ-INSIDE-CATCH\n  handleError(error);\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -493,12 +484,7 @@ 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();
-}`,
+                output: "\n\nif (condition) {\n  // @story <story-file>.story.md\n  doSomething();\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -509,12 +495,7 @@ 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);
-}`,
+                output: "\n\nfor (const item of items) {\n  // @story <story-file>.story.md\n  process(item);\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -530,17 +511,7 @@ catch (error) {
   handleError(error);
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-BRANCH-TRY
-// @story <story-file>.story.md
-try {
-  doSomething();
-}
-// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-// @req REQ-CATCH-BEFORE
-catch (error) {
-  handleError(error);
-}`,
+                output: "\n\ntry {\n  // @story <story-file>.story.md\n  doSomething();\n}\n// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n// @req REQ-CATCH-BEFORE\ncatch (error) {\n  handleError(error);\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req", "@story", "@req"),
             },
             {
@@ -553,14 +524,7 @@ try {
   cleanup();
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-// @req REQ-TRY-BEFORE
-// @story <story-file>.story.md
-try {
-  doWork();
-} finally {
-  cleanup();
-}`,
+                output: "\n\ntry {\n  // @story <story-file>.story.md\n  doWork();\n} finally {\n  cleanup();\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -576,17 +540,7 @@ else if (b) {
   doB();
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `if (a) {
-  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-  // @req REQ-OUTER-IF-INSIDE
-  doA();
-}
-// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-// @req REQ-ELSE-IF-BEFORE
-else if (b) {
-  // @story <story-file>.story.md
-  doB();
-}`,
+                output: "if (a) {\n  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n  // @req REQ-OUTER-IF-INSIDE\n  doA();\n}\n// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n// @req REQ-ELSE-IF-BEFORE\nelse if (b) {\n  // @story <story-file>.story.md\n  doB();\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -603,18 +557,7 @@ if (a) {
   doC();
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-// @req REQ-INSIDE-OUTER-IF
-if (a) {
-  // @story <story-file>.story.md
-  doA();
-} else if (b) {
-  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-  // @req REQ-INSIDE-ELSE-IF
-  doB();
-} else {
-  doC();
-}`,
+                output: "\n\nif (a) {\n  // @story <story-file>.story.md\n  doA();\n} else if (b) {\n  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n  // @req REQ-INSIDE-ELSE-IF\n  doB();\n} else {\n  doC();\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
             {
@@ -627,14 +570,7 @@ if (a) {
   }
 }`,
                 options: [{ annotationPlacement: "inside" }],
-                output: `switch (value) {
-  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-  // @req REQ-SWITCH-BEFORE
-  // @story <story-file>.story.md
-  case 'a': {
-    doSomething();
-  }
-}`,
+                output: "switch (value) {\n  \n  \n  // @story <story-file>.story.md\n  case 'a': {\n    doSomething();\n  }\n}",
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
         ],

package/package.json

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

package/user-docs/api-reference.md

@@ -811,4 +811,5 @@ If `--from` or `--to` is missing, the CLI prints an error, shows the help text,
 In CI:
 
 ```bash
-npm run traceability:verify
+npm run traceability:verify
+```

package/user-docs/migration-guide.md

@@ -354,6 +354,46 @@ The full API reference documents all options, but the most important knobs for m
 
 For most teams, the defaults in the recommended preset are a good starting point; you can then tune these options incrementally as your traceability style and `@supports` usage stabilize.
 
+### 3.4 Inside-brace branch annotation placement (optional)
+
+Story 028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION introduces an **inside-brace** placement standard for branch annotations. Instead of placing annotations directly above a branch, you can configure `traceability/require-branch-annotation` to look for annotations as the first comment-only lines **inside** each block body.
+
+The feature is controlled by the `annotationPlacement` option on `require-branch-annotation`:
+
+```js
+// eslint.config.js (flat config example)
+import traceability from "eslint-plugin-traceability";
+
+export default [
+  traceability.configs.recommended,
+  {
+    rules: {
+      "traceability/require-branch-annotation": [
+        "error",
+        {
+          annotationPlacement: "inside", // "before" (default) or "inside"
+        },
+      ],
+    },
+  },
+];
+```
+
+With `annotationPlacement: "inside"`, the rule expects annotations in these locations:
+
+- `if` / `else if` / `else`: first comment-only lines inside the `{ ... }` block.
+- Loops: first comment-only lines inside the loop body.
+- `try` / `catch` / `finally`: first comment-only lines inside the corresponding block body.
+- `switch` cases: first comment-only lines inside the `case` body when it is a block (`case 'a': { ... }`).
+
+Before-brace annotations are still honored when you leave `annotationPlacement` at the default value (`"before"`), so you can migrate gradually:
+
+1. **Start in default mode** — keep `annotationPlacement` unspecified (or set to `"before"`) and continue using your existing `// @story` / `// @req` comments above branches.
+2. **Introduce inside-brace style for new code** — when adding or refactoring branches, place annotations on the first comment-only line inside the block body. This layout plays nicely with Prettier and is what the rule’s auto-fix uses for `if`/`else if` and similar branches.
+3. **Opt-in to `annotationPlacement: "inside"`** — once your codebase is mostly using inside-brace annotations, enable the option. Branches that still rely only on before-brace comments will be reported as missing annotations in inside mode, and the rule’s autofix can insert placeholders at the correct inside location to help you complete the migration.
+
+The default configuration in 1.x keeps `annotationPlacement` at `"before"` for backward compatibility, so existing projects do not need to change anything unless they want the new inside-brace behavior.
+
 ## 4. Test and Validate
 
 Run your test suite to confirm everything passes: