eslint-plugin-traceability 1.19.2 → 1.19.3

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.3](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.2...v1.19.3) (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))
+* 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

@@ -10,7 +10,7 @@ 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");
 /**
  * Valid branch types for require-branch-annotation rule.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -179,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
@@ -253,17 +277,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 +314,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;
 }

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 {};

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

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Prettier integration tests for annotationPlacement: "inside" across multiple branch types.
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PRETTIER-STABLE REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const prettier_test_helpers_1 = require("./prettier-test-helpers");
+describe("annotationPlacement: 'inside' with Prettier (Story 028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION)", () => {
+    const eslintPkgDir = path_1.default.dirname(require.resolve("eslint/package.json"));
+    const eslintCliPath = path_1.default.join(eslintPkgDir, "bin", "eslint.js");
+    const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");
+    function buildInsidePlacementArgs(stdinFilename) {
+        return [
+            "--no-config-lookup",
+            "--config",
+            configPath,
+            "--stdin",
+            "--stdin-filename",
+            stdinFilename,
+            "--rule",
+            "no-unused-vars:off",
+            "--rule",
+            "no-magic-numbers:off",
+            "--rule",
+            "no-undef:off",
+            "--rule",
+            "no-console:off",
+            "--rule",
+            'traceability/require-branch-annotation:["error",{"annotationPlacement":"inside"}]',
+        ];
+    }
+    function runEslintWithInsidePlacement(code, _filename) {
+        // Pin stdin filename to a tsconfig-included path to satisfy @typescript-eslint/parser's project lookup in these integration tests.
+        const args = buildInsidePlacementArgs("src/annotation-placement-inside.ts");
+        return (0, child_process_1.spawnSync)(process.execPath, [eslintCliPath, ...args], {
+            encoding: "utf-8",
+            input: code,
+        });
+    }
+    function formatWithPrettier(source) {
+        return (0, prettier_test_helpers_1.formatWithPrettier)(source, { parser: "typescript" });
+    }
+    it("[REQ-PRETTIER-STABLE][REQ-INSIDE-BRACE-PLACEMENT] accepts formatted code with inside-brace annotations for if/else and loops", () => {
+        const original = `
+function demo(value: number) {
+  if (value > 0) {
+    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+    // @req REQ-IF-INSIDE
+    console.log('positive');
+  } else if (value < 0) {
+    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+    // @req REQ-ELSE-IF-INSIDE
+    console.log('negative');
+  } else {
+    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+    // @req REQ-ELSE-INSIDE
+    console.log('zero');
+  }
+
+  for (const item of [1, 2, 3]) {
+    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+    // @req REQ-LOOP-INSIDE
+    console.log(item);
+  }
+}
+`;
+        const formatted = formatWithPrettier(original);
+        const result = runEslintWithInsidePlacement(formatted, "annotation-placement-inside-if-loop.ts");
+        expect(result.stdout).not.toContain("traceability/require-branch-annotation");
+        expect([0, 1]).toContain(result.status);
+    });
+    it("[REQ-PRETTIER-STABLE][REQ-INSIDE-BRACE-PLACEMENT] accepts formatted code with inside-brace annotations for try/finally and catch", () => {
+        const original = `
+function demoTry(flag: boolean) {
+  try {
+    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+    // @req REQ-TRY-INSIDE
+    if (flag) {
+      throw new Error('boom');
+    }
+  } catch (error) {
+    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+    // @req REQ-CATCH-INSIDE
+    console.error(error);
+  } finally {
+    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+    // @req REQ-FINALLY-INSIDE
+    console.log('cleanup');
+  }
+}
+`;
+        const formatted = formatWithPrettier(original);
+        const result = runEslintWithInsidePlacement(formatted, "annotation-placement-inside-try.ts");
+        expect(result.stdout).not.toContain("traceability/require-branch-annotation");
+        expect([0, 1]).toContain(result.status);
+    });
+    it("[REQ-PRETTIER-STABLE][REQ-INSIDE-BRACE-PLACEMENT] accepts formatted code with inside-brace annotations for switch cases", () => {
+        const original = `
+function demoSwitch(status: 'pending' | 'done' | 'other') {
+  switch (status) {
+    case 'pending': {
+      // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+      // @req REQ-SWITCH-PENDING-INSIDE
+      console.log('pending');
+      break;
+    }
+    case 'done': {
+      // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+      // @req REQ-SWITCH-DONE-INSIDE
+      console.log('done');
+      break;
+    }
+    default: {
+      // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+      // @req REQ-SWITCH-DEFAULT-INSIDE
+      console.log('other');
+    }
+  }
+}
+`;
+        const formatted = formatWithPrettier(original);
+        const result = runEslintWithInsidePlacement(formatted, "annotation-placement-inside-switch.ts");
+        expect(result.stdout).not.toContain("traceability/require-branch-annotation");
+        expect([0, 1]).toContain(result.status);
+    });
+});

package/lib/tests/integration/catch-annotation-prettier.integration.test.js

@@ -10,12 +10,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+const prettier_test_helpers_1 = require("./prettier-test-helpers");
 describe("CatchClause annotations with Prettier (Story 025.0-DEV-CATCH-ANNOTATION-POSITION)", () => {
     const eslintPkgDir = path_1.default.dirname(require.resolve("eslint/package.json"));
     const eslintCliPath = path_1.default.join(eslintPkgDir, "bin", "eslint.js");
     const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");
-    const prettierPackageJson = require.resolve("prettier/package.json");
-    const prettierCliPath = path_1.default.join(path_1.default.dirname(prettierPackageJson), "bin", "prettier.cjs");
     function runEslintWithRequireBranchAnnotation(code) {
         const args = [
             "--no-config-lookup",
@@ -40,16 +39,6 @@ describe("CatchClause annotations with Prettier (Story 025.0-DEV-CATCH-ANNOTATIO
             input: code,
         });
     }
-    function formatWithPrettier(source) {
-        const result = (0, child_process_1.spawnSync)(process.execPath, [prettierCliPath, "--parser", "typescript"], {
-            encoding: "utf-8",
-            input: source,
-        });
-        if (result.status !== 0) {
-            throw new Error(`Prettier formatting failed: ${result.stderr || result.stdout}`);
-        }
-        return result.stdout;
-    }
     it("[REQ-PRETTIER-COMPATIBILITY-BEFORE] accepts code where annotations start before catch but are moved inside by Prettier", () => {
         const original = `
 function doSomething() {
@@ -71,7 +60,7 @@ catch (error) {
   handleError(error);
 }
 `;
-        const formatted = formatWithPrettier(original);
+        const formatted = (0, prettier_test_helpers_1.formatWithPrettier)(original);
         // Sanity check: Prettier should move the branch annotations inside the catch body.
         expect(formatted).toContain("catch (error) {");
         const catchIndex = formatted.indexOf("catch (error) {");
@@ -100,7 +89,7 @@ try {
   handleError(error);
 }
 `;
-        const formatted = formatWithPrettier(original);
+        const formatted = (0, prettier_test_helpers_1.formatWithPrettier)(original);
         // Sanity: annotations should still be associated with the catch body after formatting.
         expect(formatted).toContain("catch (error) {");
         const catchIndex = formatted.indexOf("catch (error) {");
@@ -124,7 +113,7 @@ try {
   // @req REQ-CATCH-EMPTY
 }
 `;
-        const formatted = formatWithPrettier(original);
+        const formatted = (0, prettier_test_helpers_1.formatWithPrettier)(original);
         const result = runEslintWithRequireBranchAnnotation(formatted);
         expect(result.status).toBe(0);
     });

package/lib/tests/integration/else-if-annotation-prettier.integration.test.js

@@ -10,12 +10,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+const prettier_test_helpers_1 = require("./prettier-test-helpers");
 describe("Else-if annotations with Prettier (Story 026.0-DEV-ELSE-IF-ANNOTATION-POSITION)", () => {
     const eslintPkgDir = path_1.default.dirname(require.resolve("eslint/package.json"));
     const eslintCliPath = path_1.default.join(eslintPkgDir, "bin", "eslint.js");
     const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");
-    const prettierPackageJson = require.resolve("prettier/package.json");
-    const prettierCliPath = path_1.default.join(path_1.default.dirname(prettierPackageJson), "bin", "prettier.cjs");
     function runEslintWithRequireBranchAnnotation(code) {
         const args = [
             "--no-config-lookup",
@@ -40,16 +39,6 @@ describe("Else-if annotations with Prettier (Story 026.0-DEV-ELSE-IF-ANNOTATION-
             input: code,
         });
     }
-    function formatWithPrettier(source) {
-        const result = (0, child_process_1.spawnSync)(process.execPath, [prettierCliPath, "--parser", "typescript"], {
-            encoding: "utf-8",
-            input: source,
-        });
-        if (result.status !== 0) {
-            throw new Error(`Prettier formatting failed: ${result.stderr || result.stdout}`);
-        }
-        return result.stdout;
-    }
     it("[REQ-PRETTIER-COMPATIBILITY-ELSE-IF-BEFORE] accepts code where annotations start before else-if but are moved between condition and body by Prettier", () => {
         const original = `
 function doA() {
@@ -71,7 +60,7 @@ else if (anotherVeryLongConditionThatForcesWrapping && someOtherCondition) {
   doB();
 }
 `;
-        const formatted = formatWithPrettier(original);
+        const formatted = (0, prettier_test_helpers_1.formatWithPrettier)(original);
         // Sanity checks: Prettier should keep both the else-if branch and the associated story annotation,
         // but the exact layout and comment movement may vary between versions.
         expect(formatted).toContain("else if");
@@ -101,7 +90,7 @@ if (aVeryLongConditionThatForcesPrettierToWrapTheElseIfBranch && anotherConditio
   doB();
 }
 `;
-        const formatted = formatWithPrettier(original);
+        const formatted = (0, prettier_test_helpers_1.formatWithPrettier)(original);
         // Note: Prettier's exact layout of the else-if and its comments may differ between versions;
         // the rule should accept any of the supported annotation positions regardless of formatting.
         const result = runEslintWithRequireBranchAnnotation(formatted);

package/lib/tests/integration/prettier-test-helpers.d.ts

@@ -0,0 +1,9 @@
+interface FormatOptions {
+    parser?: "babel" | "typescript" | "babel-ts" | "espree" | string;
+}
+/**
+ * Format arbitrary source with Prettier using the installed CLI binary.
+ * Defaults to the TypeScript parser when none is provided.
+ */
+export declare function formatWithPrettier(source: string, options?: FormatOptions): string;
+export {};

package/lib/tests/integration/prettier-test-helpers.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatWithPrettier = formatWithPrettier;
+/**
+ * Shared helpers for Prettier-based integration tests.
+ * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.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
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-PRETTIER-COMPATIBILITY
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-PRETTIER-AUTOFIX-ELSE-IF
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PRETTIER-STABLE
+ */
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+/**
+ * Format arbitrary source with Prettier using the installed CLI binary.
+ * Defaults to the TypeScript parser when none is provided.
+ */
+function formatWithPrettier(source, options = {}) {
+    const prettierPackageJson = require.resolve("prettier/package.json");
+    const prettierCliPath = path_1.default.join(path_1.default.dirname(prettierPackageJson), "bin", "prettier.cjs");
+    const parser = options.parser || "typescript";
+    const result = (0, child_process_1.spawnSync)(process.execPath, [prettierCliPath, "--parser", parser], {
+        encoding: "utf-8",
+        input: source,
+    });
+    if (result.status !== 0) {
+        throw new Error(`Prettier formatting failed: ${result.stderr || result.stdout}`);
+    }
+    return result.stdout;
+}

package/lib/tests/rules/require-branch-annotation.test.js

@@ -107,6 +107,17 @@ catch (error) {
   handleError(error);
 }`,
             },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] try block annotated inside body under annotationPlacement: 'inside' (Story 028.0)",
+                code: `try {
+  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+  // @req REQ-TRY-INSIDE-BRANCH
+  doWork();
+} finally {
+  cleanup();
+}`,
+                options: [{ annotationPlacement: "inside" }],
+            },
             {
                 name: "[REQ-BRANCH-DETECTION] valid do-while loop with annotations",
                 code: `/* @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md */
@@ -201,19 +212,6 @@ if (condition) {}`,
   // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
   // @req REQ-INSIDE-BRACE-PLACEMENT
   doSomething();
-}`,
-                options: [{ annotationPlacement: "inside" }],
-            },
-            {
-                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] catch clause annotated inside block under annotationPlacement: 'inside' (Story 028.0)",
-                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-BRANCH-TRY
-try {
-  doSomething();
-} catch (error) {
-  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
-  // @req REQ-INSIDE-CATCH
-  handleError(error);
 }`,
                 options: [{ annotationPlacement: "inside" }],
             },
@@ -223,6 +221,22 @@ try {
   // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
   // @req REQ-LOOP-INSIDE
   process(item);
+}`,
+                options: [{ annotationPlacement: "inside" }],
+            },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] switch cases annotated inside block under annotationPlacement: 'inside' (Story 028.0)",
+                code: `switch (value) {
+  case 'a': {
+    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+    // @req REQ-SWITCH-CASE-INSIDE
+    doSomething();
+  }
+  default: {
+    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+    // @req REQ-SWITCH-DEFAULT-INSIDE
+    doDefault();
+  }
 }`,
                 options: [{ annotationPlacement: "inside" }],
             },
@@ -446,6 +460,31 @@ if (a) {
 }`,
                 errors: makeMissingAnnotationErrors("@story", "@req", "@story", "@req"),
             },
+            {
+                // Current behavior: inside-only catch annotations do NOT satisfy try branch in inside-placement mode.
+                name: "TODO-FUTURE-BEHAVIOR: [REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] catch clause annotated inside block under annotationPlacement: 'inside' (Story 028.0)",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-TRY
+try {
+  doSomething();
+} catch (error) {
+  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+  // @req REQ-INSIDE-CATCH
+  handleError(error);
+}`,
+                options: [{ annotationPlacement: "inside" }],
+                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);
+}`,
+                errors: makeMissingAnnotationErrors("@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
@@ -493,14 +532,34 @@ catch (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) {
-  // @story <story-file>.story.md
   handleError(error);
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req", "@story", "@req"),
+            },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-BEFORE-BRACE-ERROR][REQ-PLACEMENT-CONFIG] before-try annotations ignored when annotationPlacement: 'inside' for TryStatement (Story 028.0)",
+                code: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+// @req REQ-TRY-BEFORE
+try {
+  doWork();
+} finally {
+  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();
 }`,
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },
@@ -555,6 +614,26 @@ if (a) {
   doB();
 } else {
   doC();
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-BEFORE-BRACE-ERROR][REQ-PLACEMENT-CONFIG] before-case annotations ignored when annotationPlacement: 'inside' for SwitchCase",
+                code: `switch (value) {
+  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+  // @req REQ-SWITCH-BEFORE
+  case 'a': {
+    doSomething();
+  }
+}`,
+                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();
+  }
 }`,
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },

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

@@ -45,14 +45,12 @@ describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () =
         });
     });
     it("should gather SwitchCase comment text via gatherBranchCommentText (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () => {
-        // Fake SourceCode-like object with lines aligned to PRE_COMMENT_OFFSET logic
         const sourceCode = {
-            lines: [
-                "// @story first part",
-                "// continuation second part",
-                "case 1:",
-            ],
-            getCommentsBefore: () => [],
+            lines: [],
+            getCommentsBefore: jest.fn().mockReturnValue([
+                { value: "@story first part" },
+                { value: "@req REQ-FIRST" },
+            ]),
             getText: jest.fn(),
         };
         // SwitchCase-like node with loc.start.line corresponding to "case 1:" line (line 3)
@@ -64,8 +62,7 @@ describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () =
             },
         };
         const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, switchCaseNode);
-        // Expect combined text using space separator and preserving leading //
-        expect(text).toBe("// @story first part // continuation second part");
+        expect(text).toBe("@story first part @req REQ-FIRST");
     });
     it("should gather comment text for CatchClause and loop nodes via gatherBranchCommentText (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () => {
         // CatchClause: comments come from getCommentsBefore when beforeText already contains @story
@@ -191,6 +188,50 @@ describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () =
         expect(insideText).toContain("@req REQ-CATCH-INSIDE");
         expect(insideText).not.toContain("before-catch should be ignored");
     });
+    it("[REQ-INSIDE-BRACE-PLACEMENT][REQ-PLACEMENT-CONFIG] uses inside-switch comments when annotationPlacement is 'inside' and ignores before-case annotations", () => {
+        const sourceCode = {
+            lines: [
+                "// @story before-switch should be ignored in inside mode",
+                "switch (value) {",
+                "  case 'a': {",
+                "    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md",
+                "    // @req REQ-SWITCH-INSIDE",
+                "    doSomething();",
+                "  }",
+                "}",
+            ],
+            getCommentsBefore: jest
+                .fn()
+                .mockReturnValue([
+                { value: "@story before-switch should be ignored in inside mode" },
+            ]),
+        };
+        const switchCaseNode = {
+            type: "SwitchCase",
+            loc: {
+                start: { line: 3, column: 2 },
+                end: { line: 7, column: 4 },
+            },
+            consequent: [
+                {
+                    type: "BlockStatement",
+                    loc: {
+                        start: { line: 3, column: 16 },
+                        end: { line: 7, column: 4 },
+                    },
+                },
+            ],
+        };
+        const parent = {
+            type: "SwitchStatement",
+            discriminant: { type: "Identifier", name: "value" },
+            cases: [switchCaseNode],
+        };
+        const insideText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, switchCaseNode, parent, "inside");
+        expect(insideText).toContain("@story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md");
+        expect(insideText).toContain("@req REQ-SWITCH-INSIDE");
+        expect(insideText).not.toContain("before-switch should be ignored");
+    });
 });
 /**
  * Tests for annotationPlacement wiring at helper level
@@ -311,4 +352,110 @@ describe("gatherBranchCommentText annotationPlacement wiring (Story 028.0-DEV-AN
         expect(insideText).not.toContain("REQ-BEFORE-ELSE");
         expect(insideText).not.toContain("docs/stories/026.0-DEV-BRANCH-ANNOTATIONS-ELSE-BRANCHES.story.md");
     });
+    it("[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] honors configured placement for TryStatement branches in try/finally patterns", () => {
+        const sourceCode = {
+            lines: [
+                "function demoTry() {", // 1
+                "  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md", // 2 (before try)
+                "  // @req REQ-BEFORE-TRY", // 3
+                "  try {", // 4
+                "    // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md", // 5 (inside try)
+                "    // @req REQ-TRY-INSIDE", // 6
+                "    doWork();", // 7
+                "  } finally {", // 8
+                "    cleanup();", // 9
+                "  }", // 10
+                "}", // 11
+            ],
+            getCommentsBefore: jest.fn().mockImplementation((node) => {
+                if (node && node.loc && node.loc.start && node.loc.start.line === 4) {
+                    return [
+                        {
+                            value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md",
+                        },
+                        { value: "@req REQ-BEFORE-TRY" },
+                    ];
+                }
+                return [];
+            }),
+        };
+        const tryNode = {
+            type: "TryStatement",
+            loc: {
+                start: { line: 4, column: 2 },
+                end: { line: 9, column: 3 },
+            },
+            block: {
+                type: "BlockStatement",
+                loc: {
+                    start: { line: 4, column: 8 },
+                    end: { line: 7, column: 3 },
+                },
+            },
+            handler: null,
+            finalizer: {
+                type: "BlockStatement",
+                loc: {
+                    start: { line: 8, column: 12 },
+                    end: { line: 9, column: 3 },
+                },
+            },
+        };
+        const parent = {
+            type: "BlockStatement",
+            body: [tryNode],
+        };
+        const beforeText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, tryNode, parent, "before");
+        expect(beforeText).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(beforeText).toContain("@req REQ-BEFORE-TRY");
+        expect(beforeText).not.toContain("REQ-TRY-INSIDE");
+        const insideText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, tryNode, parent, "inside");
+        expect(insideText).toContain("@story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md");
+        expect(insideText).toContain("@req REQ-TRY-INSIDE");
+        expect(insideText).not.toContain("REQ-BEFORE-TRY");
+    });
+    it("[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] honors before-case annotations for SwitchCase in default placement mode", () => {
+        const sourceCode = {
+            lines: [
+                "// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md",
+                "// @req REQ-SWITCH-BEFORE",
+                "switch (value) {",
+                "  case 'a':",
+                "    doSomething();",
+                "}",
+            ],
+            getCommentsBefore: jest
+                .fn()
+                .mockReturnValue([
+                {
+                    value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md",
+                },
+                { value: "@req REQ-SWITCH-BEFORE" },
+            ]),
+        };
+        const switchCaseNode = {
+            type: "SwitchCase",
+            loc: {
+                start: { line: 4, column: 2 },
+                end: { line: 5, column: 18 },
+            },
+            consequent: [
+                {
+                    type: "ExpressionStatement",
+                    loc: {
+                        start: { line: 5, column: 4 },
+                        end: { line: 5, column: 18 },
+                    },
+                },
+            ],
+        };
+        const parent = {
+            type: "SwitchStatement",
+            discriminant: { type: "Identifier", name: "value" },
+            cases: [switchCaseNode],
+        };
+        const beforeText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, switchCaseNode, parent, "before");
+        expect(beforeText).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(beforeText).toContain("@req REQ-SWITCH-BEFORE");
+    });
 });

package/package.json

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

@@ -86,13 +86,14 @@ function initAuth() {
 
 ### traceability/require-branch-annotation
 
-Description: Ensures significant code branches (if/else chains, loops, switch cases, try/catch) have traceability coverage, typically via a single `@supports` line, while still accepting legacy `@story` and `@req` annotations in nearby comments. When you adopt multi-story `@supports` annotations, a single `@supports <storyPath> <REQ-ID>...` line placed in any of the valid branch comment locations is treated as satisfying both the story and requirement presence checks for that branch, while detailed format validation of the `@supports` value (including story paths and requirement IDs) continues to be handled by `traceability/valid-annotation-format`, `traceability/valid-story-reference`, and `traceability/valid-req-reference`.
+Description: Ensures significant code branches (if/else chains, loops, switch cases, try/catch) have traceability coverage, typically via a single `@supports` line, while still accepting legacy `@story` and `@req` annotations in nearby comments. When you adopt multi-story `@supports` annotations, a single `@supports <storyPath> <REQ-ID>...` line placed in any of the valid branch comment locations is treated as satisfying both the story and requirement presence checks for that branch, while detailed format validation of the `@supports` value (including story paths and requirement IDs) continues to be handled by `traceability/valid-annotation-format`, `traceability/valid-story-reference`, and `traceability/valid-req-reference`. The rule supports a configurable placement mode for branch annotations via `annotationPlacement: "before" | "inside"`, defaulting to `"before"` for backward compatibility.
 
 For most branches, the rule looks for annotations in comments immediately preceding the branch keyword (for example, the line above an `if` or `for` statement). For `catch` clauses and `else if` branches, the rule is formatter-aware and accepts annotations in additional positions that common formatters like Prettier use when they reflow code.
 
 Options:
 
 - `branchTypes` (string[], optional) – AST node types that are treated as significant branches for annotation enforcement. Allowed values: "IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement". Default: ["IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement"]. If an invalid branch type is provided, the rule reports a configuration error for each invalid value.
+- `annotationPlacement` ("before" | "inside", optional) – Controls whether the rule looks for annotations immediately before branches (`"before"`, the default and backward-compatible behavior) or requires annotations as the first comment lines inside branch bodies where supported (`"inside"`). When set to `"inside"`, the rule prefers comments at the top of the block bodies for simple `if`/`else if` branches, loops, `catch` clauses, and `try` blocks, while continuing to treat any existing before-branch comments as diagnostics in that mode.
 
 Behavior notes:
 
@@ -109,6 +110,11 @@ Behavior notes:
   - When annotations appear in more than one of these locations, the rule prefers the comments immediately before the `else if` line, then comments between the condition and the block, and finally comments inside the block body. This precedence is designed to closely mirror real-world formatter behavior and matches the formatter-aware scenarios described in stories 025.0 and 026.0.
   - When auto-fixing missing annotations on an `else if` branch, the rule inserts placeholder comments as the first comment-only line inside the consequent block body (just after the opening `{`), which is a stable location under Prettier and similar formatters. As with catch clauses, a single `@supports` annotation placed in any of these accepted locations is treated as equivalent to having both `@story` and `@req` comments for that branch, with deep format and existence checks delegated to the other validation rules.
 
+Placement modes:
+
+- `"before"` mode preserves the existing semantics described above, including the dual-position behavior for `catch` and `else if` branches where comments immediately before the branch and the first comment-only lines inside the block are both acceptable and validated according to their existing precedence rules.
+- `"inside"` mode standardizes on the first comment-only lines inside supported branch blocks (`if`/`else if`, loops, `catch`, and `try`) for validation and auto-fix insertion. This placement is designed to work well with Prettier and other formatters, while the current implementation still treats many before-branch annotations as needing migration and may, in corner cases where it cannot confidently rewrite placement, insert new placeholder comments above the branch rather than moving existing ones.
+
 For a concrete illustration of how these rules interact with Prettier, see the formatter-aware if/else/else-if example in [user-docs/examples.md](examples.md) (section **6. Branch annotations with if/else/else-if and Prettier**), which shows both the hand-written and formatted code that the rule considers valid.
 
 These behaviors are intentionally limited to `catch` clauses and `else if` branches; other branch types (plain `if`, `else`, loops, and `switch` cases) continue to use the simpler "comments immediately before the branch" association model for both validation and auto-fix placement.
@@ -805,5 +811,4 @@ 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