eslint-plugin-traceability 1.20.0 → 1.21.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.20.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.4...v1.20.0) (2025-12-18)
+# [1.21.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.20.0...v1.21.0) (2025-12-19)
 
 
 ### Features
 
-* extend branch placement standard docs and helpers ([ae05a52](https://github.com/voder-ai/eslint-plugin-traceability/commit/ae05a5232b724060f7b1baae9a6be6eedf466617))
+* support inside-brace placement for function-level rules ([064b1a4](https://github.com/voder-ai/eslint-plugin-traceability/commit/064b1a4e7627b5e35afd074752724ab5958e9d8b))
 
 # Changelog
 

package/README.md

@@ -117,15 +117,15 @@ Traceability annotations are typically placed immediately adjacent to the code t
   }
   ```
 
+  The `annotationPlacement` option is also supported by the function-level rules (`traceability/require-story-annotation` and `traceability/require-req-annotation`) when you configure them directly. In `"inside"` mode, these rules treat only the first comment-only lines inside function and method bodies as satisfying the annotation requirement; JSDoc and before-function comments are ignored for block-bodied functions and methods, while TypeScript declarations and signature-only nodes continue to use before-node annotations.
+
 - **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.
 
-  Function-level rules now support the same placement configuration model as branches:
-  - By default, annotations are still placed immediately before the function (JSDoc or line comments).
-  - When you configure `annotationPlacement: "inside"` on `traceability/require-story-annotation`, the rule prefers annotations as the first comment-only lines inside the function or method body, mirroring the branch-level inside-brace standard from Story 028.0. Declaration-only shapes such as `TSDeclareFunction` and `TSMethodSignature` remain before-function only, since they have no executable body.
+  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, but that behaviour is not yet implemented in the current release.
 
 For full configuration details and migration guidance between placement styles, see:
 

package/lib/src/rules/helpers/require-story-core.d.ts

@@ -38,6 +38,7 @@ import type { Rule } from "eslint";
 type CoreReportOptions = {
     annotationTemplateOverride?: string;
     autoFixToggle?: boolean;
+    annotationPlacement?: "before" | "inside";
 };
 type ReportDeps = {
     hasStoryAnnotation: (_sourceCode: any, _node: any) => boolean;
@@ -53,6 +54,7 @@ type ReportDeps = {
     shouldApplyAutoFix: (_autoFix: boolean | undefined) => boolean;
     createAddStoryFix: (_target: any, _annotationTemplate: string) => any;
     createMethodFix: (_node: any, _annotationTemplate: string) => any;
+    hasStoryAnnotationWithPlacement?: (_sourceCode: any, _node: any, _placement: "before" | "inside") => boolean;
 };
 /**
  * Core helper to report a missing @story annotation for a function-like node.

package/lib/src/rules/helpers/require-story-core.js

@@ -158,11 +158,13 @@ function coreReportMissing(deps, context, sourceCode, config) {
     const { node, target: passedTarget, options = {} } = config;
     withSafeReporting("coreReportMissing", () => {
         const annotationPlacement = resolveAnnotationPlacement(options);
-        if (typeof deps.hasStoryAnnotationWithPlacement === "function" &&
-            deps.hasStoryAnnotationWithPlacement(sourceCode, node, annotationPlacement)) {
-            return;
+        const hasWithPlacement = deps.hasStoryAnnotationWithPlacement;
+        if (typeof hasWithPlacement === "function") {
+            if (hasWithPlacement(sourceCode, node, annotationPlacement)) {
+                return;
+            }
         }
-        if (deps.hasStoryAnnotation(sourceCode, node)) {
+        else if (deps.hasStoryAnnotation(sourceCode, node)) {
             return;
         }
         const functionName = deps.getReportedFunctionName(node);

package/lib/src/rules/helpers/require-story-helpers.d.ts

@@ -18,6 +18,7 @@ import { type CallbackExclusionOptions } from "./test-callback-exclusion";
 interface ReportOptions extends CallbackExclusionOptions {
     annotationTemplateOverride?: string;
     autoFixToggle?: boolean;
+    annotationPlacement?: "before" | "inside";
 }
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 declare function getAnnotationTemplate(override?: string, _options?: CallbackExclusionOptions): string;
@@ -53,7 +54,24 @@ declare function leadingCommentsHasStory(node: any): boolean;
  * @req REQ-ANNOTATION-REQUIRED - Detect existing story annotations in JSDoc or comments
  */
 declare function hasStoryAnnotation(sourceCode: any, node: any): boolean;
-declare const hasStoryAnnotationWithPlacement: typeof hasStoryAnnotation;
+/**
+ * Placement-aware story detection helper used by core reporting.
+ *
+ * When annotationPlacement is "inside" and the node supports inside-brace
+ * semantics, this helper only treats annotations found on the first
+ * comment-only lines inside the function or method body as satisfying the
+ * requirement. JSDoc and before-function comments are intentionally ignored so
+ * that misplaced annotations are reported as violations under the inside
+ * standard.
+ *
+ * For nodes that do not support inside placement (such as TS declarations,
+ * signature-only nodes, or functions without block bodies), this helper
+ * delegates to the existing hasStoryAnnotation heuristics so that they
+ * continue to rely on before-function placement.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+declare function hasStoryAnnotationWithPlacement(sourceCode: any, node: any, annotationPlacement: "before" | "inside"): boolean;
 /**
  * Determine AST node where annotation should be inserted
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md

package/lib/src/rules/helpers/require-story-helpers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.getNodeName = exports.hasStoryAnnotationWithPlacement = exports.STORY_PATH = void 0;
+exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.getNodeName = exports.STORY_PATH = void 0;
 exports.getAnnotationTemplate = getAnnotationTemplate;
 exports.shouldApplyAutoFix = shouldApplyAutoFix;
 exports.isExportedNode = isExportedNode;
@@ -8,6 +8,7 @@ exports.jsdocHasStory = jsdocHasStory;
 exports.commentsBeforeHasStory = commentsBeforeHasStory;
 exports.leadingCommentsHasStory = leadingCommentsHasStory;
 exports.hasStoryAnnotation = hasStoryAnnotation;
+exports.hasStoryAnnotationWithPlacement = hasStoryAnnotationWithPlacement;
 exports.extractName = extractName;
 exports.resolveTargetNode = resolveTargetNode;
 exports.shouldProcessNode = shouldProcessNode;
@@ -19,6 +20,7 @@ Object.defineProperty(exports, "parentChainHasStory", { enumerable: true, get: f
 Object.defineProperty(exports, "fallbackTextBeforeHasStory", { enumerable: true, get: function () { return require_story_io_1.fallbackTextBeforeHasStory; } });
 const require_story_utils_1 = require("./require-story-utils");
 Object.defineProperty(exports, "getNodeName", { enumerable: true, get: function () { return require_story_utils_1.getNodeName; } });
+const function_annotation_helpers_1 = require("../../utils/function-annotation-helpers");
 const require_story_core_1 = require("./require-story-core");
 Object.defineProperty(exports, "DEFAULT_SCOPE", { enumerable: true, get: function () { return require_story_core_1.DEFAULT_SCOPE; } });
 Object.defineProperty(exports, "EXPORT_PRIORITY_VALUES", { enumerable: true, get: function () { return require_story_core_1.EXPORT_PRIORITY_VALUES; } });
@@ -220,9 +222,49 @@ function hasStoryAnnotation(sourceCode, node) {
     }
     return false;
 }
-// Placement-aware alias reserved for future inside-brace function placement.
-const hasStoryAnnotationWithPlacement = hasStoryAnnotation;
-exports.hasStoryAnnotationWithPlacement = hasStoryAnnotationWithPlacement;
+/**
+ * Placement-aware story detection helper used by core reporting.
+ *
+ * When annotationPlacement is "inside" and the node supports inside-brace
+ * semantics, this helper only treats annotations found on the first
+ * comment-only lines inside the function or method body as satisfying the
+ * requirement. JSDoc and before-function comments are intentionally ignored so
+ * that misplaced annotations are reported as violations under the inside
+ * standard.
+ *
+ * For nodes that do not support inside placement (such as TS declarations,
+ * signature-only nodes, or functions without block bodies), this helper
+ * delegates to the existing hasStoryAnnotation heuristics so that they
+ * continue to rely on before-function placement.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+function hasStoryAnnotationWithPlacement(sourceCode, node, annotationPlacement) {
+    // Backward-compatible default: use existing heuristics when placement is
+    // "before" or when the function does not support inside-brace semantics.
+    if (annotationPlacement !== "inside" ||
+        !(0, function_annotation_helpers_1.supportsInsidePlacementForFunction)(node)) {
+        return hasStoryAnnotation(sourceCode, node);
+    }
+    try {
+        const insideText = (0, function_annotation_helpers_1.getFunctionInsideBodyCommentText)(sourceCode, node);
+        if (typeof insideText === "string" &&
+            (insideText.includes("@story") || insideText.includes("@supports"))) {
+            return true;
+        }
+    }
+    catch (error) {
+        if (process.env.TRACEABILITY_DEBUG === "1") {
+            // Debug logging only when explicitly enabled for troubleshooting helper failures.
+            console.error("[traceability] hasStoryAnnotationWithPlacement failed for node", error?.message ?? error);
+        }
+    }
+    // In inside-placement mode for block-bodied functions and methods we
+    // intentionally do not fall back to before-function heuristics; callers
+    // should treat this as a missing annotation so that misplaced comments are
+    // reported as violations.
+    return false;
+}
 /**
  * Determine AST node where annotation should be inserted
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -375,6 +417,7 @@ function resolveAnnotationTargetNode(sourceCode, node, passedTarget) {
 function reportMissing(context, sourceCode, config) {
     (0, require_story_core_1.coreReportMissing)({
         hasStoryAnnotation,
+        hasStoryAnnotationWithPlacement,
         getReportedFunctionName,
         resolveAnnotationTargetNode,
         getNameNodeForReport,
@@ -390,6 +433,7 @@ function reportMissing(context, sourceCode, config) {
 function reportMethod(context, sourceCode, config) {
     (0, require_story_core_1.coreReportMethod)({
         hasStoryAnnotation,
+        hasStoryAnnotationWithPlacement,
         getReportedFunctionName,
         resolveAnnotationTargetNode,
         getNameNodeForReport,

package/lib/src/rules/helpers/require-story-visitors.js

@@ -33,6 +33,7 @@ function buildFunctionDeclarationVisitor(context, sourceCode, options) {
             options: {
                 annotationTemplateOverride: options.annotationTemplate,
                 autoFixToggle: options.autoFix,
+                annotationPlacement: options.annotationPlacement,
             },
         });
     }
@@ -68,6 +69,7 @@ function buildFunctionExpressionVisitor(context, sourceCode, options) {
             options: {
                 annotationTemplateOverride: options.annotationTemplate,
                 autoFixToggle: options.autoFix,
+                annotationPlacement: options.annotationPlacement,
             },
         });
     }
@@ -96,6 +98,7 @@ function buildArrowFunctionVisitor(context, sourceCode, options) {
             options: {
                 annotationTemplateOverride: options.annotationTemplate,
                 autoFixToggle: options.autoFix,
+                annotationPlacement: options.annotationPlacement,
             },
         });
     }
@@ -123,6 +126,7 @@ function buildTSDeclareFunctionVisitor(context, sourceCode, options) {
             options: {
                 annotationTemplateOverride: options.annotationTemplate,
                 autoFixToggle: options.autoFix,
+                annotationPlacement: options.annotationPlacement,
             },
         });
     }
@@ -151,6 +155,7 @@ function buildTSMethodSignatureVisitor(context, sourceCode, options) {
             options: {
                 annotationTemplateOverride: options.methodAnnotationTemplate ?? options.annotationTemplate,
                 autoFixToggle: options.autoFix,
+                annotationPlacement: options.annotationPlacement,
             },
         });
     }
@@ -177,6 +182,7 @@ function buildMethodDefinitionVisitor(context, sourceCode, options) {
             options: {
                 annotationTemplateOverride: options.methodAnnotationTemplate ?? options.annotationTemplate,
                 autoFixToggle: options.autoFix,
+                annotationPlacement: options.annotationPlacement,
             },
         });
     }

package/lib/src/rules/helpers/test-callback-exclusion.d.ts

@@ -21,6 +21,7 @@ import type { TSESTree } from "@typescript-eslint/utils";
 interface CallbackExclusionOptions {
     excludeTestCallbacks?: boolean;
     additionalTestHelperNames?: string[];
+    annotationPlacement?: "before" | "inside";
 }
 type TraceabilityNodeWithParent = TSESTree.Node & {
     parent?: TraceabilityNodeWithParent | null;

package/lib/src/rules/require-req-annotation.d.ts

@@ -7,9 +7,8 @@
  * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of which exports are checked
  * @req REQ-EXPORT-PRIORITY - Allow configuration of export priority behavior
  *
- * Note: This rule accepts annotationPlacement for configuration parity with
- * require-story-annotation, but currently still requires annotations before
- * the function (no inside-function support yet).
+ * This rule honors the same `annotationPlacement` semantics as
+ * `require-story-annotation` for block-bodied functions and methods.
  */
 import type { Rule } from "eslint";
 declare const rule: Rule.RuleModule;

package/lib/src/rules/require-req-annotation.js

@@ -59,7 +59,13 @@ const rule = {
         const rawScope = options?.scope;
         const scope = Array.isArray(rawScope) && rawScope.length > 0 ? rawScope : require_story_helpers_1.DEFAULT_SCOPE;
         const exportPriority = options?.exportPriority ?? "all";
-        const shouldCheck = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority);
+        const rawAnnotationPlacement = options?.annotationPlacement;
+        const annotationPlacement = rawAnnotationPlacement === "inside" || rawAnnotationPlacement === "before"
+            ? rawAnnotationPlacement
+            : "before";
+        const shouldCheck = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority, {
+            annotationPlacement,
+        });
         /**
          * Helper to conditionally run the annotation check only when the node
          * should be processed according to scope/exportPriority.
@@ -67,7 +73,10 @@ const rule = {
         const runCheck = (node) => {
             if (!shouldCheck(node))
                 return;
-            (0, annotation_checker_1.checkReqAnnotation)(context, node, { enableFix: false });
+            (0, annotation_checker_1.checkReqAnnotation)(context, node, {
+                enableFix: false,
+                annotationPlacement,
+            });
         };
         return {
             /**

package/lib/src/rules/require-story-annotation.js

@@ -2,6 +2,43 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const require_story_visitors_1 = require("./helpers/require-story-visitors");
 const require_story_helpers_1 = require("./helpers/require-story-helpers");
+function getNormalizedOptions(context) {
+    const sourceCode = context.getSourceCode();
+    const opts = (context.options && context.options[0]) || {};
+    const scope = opts.scope || require_story_helpers_1.DEFAULT_SCOPE;
+    const exportPriority = opts.exportPriority || "all";
+    const annotationTemplate = typeof opts.annotationTemplate === "string" &&
+        opts.annotationTemplate.trim().length > 0
+        ? opts.annotationTemplate.trim()
+        : undefined;
+    const methodAnnotationTemplate = typeof opts.methodAnnotationTemplate === "string" &&
+        opts.methodAnnotationTemplate.trim().length > 0
+        ? opts.methodAnnotationTemplate.trim()
+        : undefined;
+    const autoFix = typeof opts.autoFix === "boolean" ? opts.autoFix : true;
+    const excludeTestCallbacks = typeof opts.excludeTestCallbacks === "boolean"
+        ? opts.excludeTestCallbacks
+        : true;
+    const additionalTestHelperNames = Array.isArray(opts.additionalTestHelperNames) &&
+        opts.additionalTestHelperNames.every((name) => typeof name === "string")
+        ? opts.additionalTestHelperNames
+        : undefined;
+    const rawAnnotationPlacement = opts.annotationPlacement;
+    const annotationPlacement = rawAnnotationPlacement === "inside" || rawAnnotationPlacement === "before"
+        ? rawAnnotationPlacement
+        : "before";
+    return {
+        sourceCode,
+        scope,
+        exportPriority,
+        annotationTemplate,
+        methodAnnotationTemplate,
+        autoFix,
+        excludeTestCallbacks,
+        additionalTestHelperNames,
+        annotationPlacement,
+    };
+}
 /**
  * ESLint rule to require @story annotations on functions/methods.
  *
@@ -58,6 +95,12 @@ const rule = {
                         items: { type: "string" },
                         uniqueItems: true,
                     },
+                    /**
+                     * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG REQ-DEFAULT-BACKWARD-COMPAT REQ-ALL-BLOCK-TYPES
+                     */
+                    annotationPlacement: {
+                        enum: ["before", "inside"],
+                    },
                 },
                 additionalProperties: false,
             },
@@ -72,26 +115,7 @@ const rule = {
      * @req REQ-AUTOFIX-MISSING - The create hook wires in visitors that are capable of providing auto-fix suggestions for missing @story annotations.
      */
     create(context) {
-        const sourceCode = context.getSourceCode();
-        const opts = (context.options && context.options[0]) || {};
-        const scope = opts.scope || require_story_helpers_1.DEFAULT_SCOPE;
-        const exportPriority = opts.exportPriority || "all";
-        const annotationTemplate = typeof opts.annotationTemplate === "string" &&
-            opts.annotationTemplate.trim().length > 0
-            ? opts.annotationTemplate.trim()
-            : undefined;
-        const methodAnnotationTemplate = typeof opts.methodAnnotationTemplate === "string" &&
-            opts.methodAnnotationTemplate.trim().length > 0
-            ? opts.methodAnnotationTemplate.trim()
-            : undefined;
-        const autoFix = typeof opts.autoFix === "boolean" ? opts.autoFix : true;
-        const excludeTestCallbacks = typeof opts.excludeTestCallbacks === "boolean"
-            ? opts.excludeTestCallbacks
-            : true;
-        const additionalTestHelperNames = Array.isArray(opts.additionalTestHelperNames) &&
-            opts.additionalTestHelperNames.every((name) => typeof name === "string")
-            ? opts.additionalTestHelperNames
-            : undefined;
+        const { sourceCode, scope, exportPriority, annotationTemplate, methodAnnotationTemplate, autoFix, excludeTestCallbacks, additionalTestHelperNames, annotationPlacement, } = getNormalizedOptions(context);
         /**
          * Optional debug logging for troubleshooting this rule.
          * Developers can temporarily uncomment the block below to log when the rule
@@ -110,6 +134,7 @@ const rule = {
         const should = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority, {
             excludeTestCallbacks,
             additionalTestHelperNames,
+            annotationPlacement,
         });
         // Delegate visitor construction to helper to keep this file concise.
         return (0, require_story_visitors_1.buildVisitors)(context, sourceCode, {
@@ -121,6 +146,7 @@ const rule = {
             autoFix,
             excludeTestCallbacks,
             additionalTestHelperNames,
+            annotationPlacement,
         });
     },
 };

package/lib/src/utils/annotation-checker.d.ts

@@ -13,4 +13,5 @@
  */
 export declare function checkReqAnnotation(context: any, node: any, options?: {
     enableFix?: boolean;
+    annotationPlacement?: "before" | "inside";
 }): void;

package/lib/src/utils/annotation-checker.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkReqAnnotation = checkReqAnnotation;
 const require_story_utils_1 = require("../rules/helpers/require-story-utils");
 const reqAnnotationDetection_1 = require("./reqAnnotationDetection");
+const function_annotation_helpers_1 = require("./function-annotation-helpers");
 /**
  * Helper to retrieve the JSDoc comment for a node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -180,7 +181,19 @@ function reportMissing(context, node, enableFix = true) {
  */
 function checkReqAnnotation(context, node, options) {
     const { enableFix = true } = options ?? {};
+    const annotationPlacement = options?.annotationPlacement === "inside" ||
+        options?.annotationPlacement === "before"
+        ? options.annotationPlacement
+        : "before";
     const sourceCode = context.getSourceCode();
+    if (annotationPlacement === "inside" &&
+        (0, function_annotation_helpers_1.supportsInsidePlacementForFunction)(node)) {
+        const insideText = (0, function_annotation_helpers_1.getFunctionInsideBodyCommentText)(sourceCode, node);
+        if (typeof insideText === "string" &&
+            (insideText.includes("@req") || insideText.includes("@supports"))) {
+            return;
+        }
+    }
     const jsdoc = getJsdocComment(sourceCode, node);
     const leading = getLeadingComments(node);
     const comments = getCommentsBefore(sourceCode, node);

package/lib/tests/config/require-story-annotation-config.test.js

@@ -19,6 +19,7 @@ describe("ESLint Configuration Rule Options (Story 002.0-DEV-ESLINT-CONFIG)", ()
         const schema = require_story_annotation_1.default.meta.schema[0];
         expect(schema.properties).toHaveProperty("scope");
         expect(schema.properties).toHaveProperty("exportPriority");
+        expect(schema.properties).toHaveProperty("annotationPlacement");
         expect(schema.additionalProperties).toBe(false);
     });
 });

package/lib/tests/integration/require-traceability-aliases.integration.test.js

@@ -109,6 +109,32 @@ describe("Unified require-traceability and aliases integration (Story 010.4-DEV-
             expect(messages).toHaveLength(0);
         });
     });
+    it("[REQ-INSIDE-BRACE-PLACEMENT][REQ-ALL-BLOCK-TYPES] unified rule and aliases accept inside-brace annotations when annotationPlacement is 'inside'", async () => {
+        const codeWithInsideAnnotations = `function foo() {\n  // @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-FN-INSIDE\n  return 1;\n}`;
+        const config = [
+            {
+                rules: {
+                    "traceability/require-traceability": "error",
+                    "traceability/require-story-annotation": [
+                        "error",
+                        {
+                            annotationPlacement: "inside",
+                        },
+                    ],
+                    "traceability/require-req-annotation": [
+                        "error",
+                        {
+                            annotationPlacement: "inside",
+                        },
+                    ],
+                },
+            },
+        ];
+        const result = await lintTextWithConfig(codeWithInsideAnnotations, "example.js", config);
+        const ruleIds = result.messages.map((m) => m.ruleId);
+        expect(ruleIds).not.toContain("traceability/require-story-annotation");
+        expect(ruleIds).not.toContain("traceability/require-req-annotation");
+    });
     it("[REQ-PRESETS-CANONICAL-RULE] recommended preset surfaces unified and legacy diagnostics together for missing annotations", async () => {
         const result = await lintTextWithConfig(codeMissingAll, "example.js", index_1.configs.recommended);
         const ruleIds = result.messages.map((m) => m.ruleId).sort();

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

@@ -137,6 +137,26 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
                 code: `class C {\n  /** @req REQ-EXAMPLE */\n  m() {}\n}`,
                 options: [{ exportPriority: "non-exported" }],
             },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-ALL-BLOCK-TYPES] function-level @supports requirement inside body is valid when annotationPlacement is 'inside'",
+                code: `function withInsideReq() {\n  // @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-FN-INSIDE\n  return 1;\n}`,
+                options: [{ annotationPlacement: "inside" }],
+            },
+            (0, ts_language_options_1.withTsLanguageOptions)({
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-ALL-BLOCK-TYPES] method-level @req inside body is valid when annotationPlacement is 'inside'",
+                code: `class C {\n  method() {\n    // @req REQ-METHOD-INSIDE\n    return 1;\n  }\n}`,
+                options: [{ annotationPlacement: "inside" }],
+            }),
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT] before-function @req remains valid when annotationPlacement is 'inside' (REQ-REQ-PLACEMENT-BC)",
+                code: `/**\n * @req REQ-BEFORE-FN\n */\nfunction beforeReqOnly() {\n  return 1;\n}`,
+                options: [{ annotationPlacement: "inside" }],
+            },
+            (0, ts_language_options_1.withTsLanguageOptions)({
+                name: "[REQ-INSIDE-BRACE-PLACEMENT] before-method @req remains valid when annotationPlacement is 'inside' (REQ-REQ-PLACEMENT-BC)",
+                code: `class C {\n  /**\n   * @req REQ-BEFORE-METHOD\n   */\n  method() {\n    return 1;\n  }\n}`,
+                options: [{ annotationPlacement: "inside" }],
+            }),
         ],
         invalid: [
             {

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

@@ -105,6 +105,21 @@ describe('Vitest suite', () => {
                 code: `withTestCase("does something", () => {});`,
                 options: [{ additionalTestHelperNames: ["withTestCase"] }],
             },
+            {
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-ALL-BLOCK-TYPES] function-level @supports annotation inside body is valid when annotationPlacement is 'inside'",
+                code: `function insideAnnotated() {\n  // @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-FN\n  return 1;\n}`,
+                options: [{ annotationPlacement: "inside" }],
+            },
+            (0, ts_language_options_1.withTsLanguageOptions)({
+                name: "[REQ-INSIDE-BRACE-PLACEMENT][REQ-ALL-BLOCK-TYPES] function-level @story annotation inside body is valid when annotationPlacement is 'inside' (TS)",
+                code: `function insideAnnotatedTs() {\n  // @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\n  return 1;\n}`,
+                options: [{ annotationPlacement: "inside" }],
+            }),
+            (0, ts_language_options_1.withTsLanguageOptions)({
+                name: "[REQ-INSIDE-BRACE-PLACEMENT] before-method @story remains valid when annotationPlacement is 'inside' (placement BC)",
+                code: `class C {\n  /** @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md */\n  method() {\n    return 1;\n  }\n}`,
+                options: [{ annotationPlacement: "inside" }],
+            }),
         ],
         invalid: [
             {
@@ -237,6 +252,17 @@ describe('Vitest suite', () => {
                     },
                 ],
             },
+            {
+                name: "[REQ-BEFORE-BRACE-ERROR][REQ-INSIDE-BRACE-PLACEMENT] before-function annotation is ignored when annotationPlacement is 'inside'",
+                code: `// @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md\nfunction beforeOnly() {\n  return 1;\n}`,
+                options: [{ annotationPlacement: "inside", autoFix: false }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: 1, // satisfy TypeScript's SuggestionOutput[] typing while asserting suggestion count
+                    },
+                ],
+            },
         ],
     });
     ruleTester.run("require-story-annotation with exportPriority option", require_story_annotation_1.default, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",

package/user-docs/api-reference.md

@@ -26,7 +26,7 @@ For function-level traceability, the plugin exposes a unified rule and two legac
 - `traceability/require-traceability` is the **canonical function-level rule** for new configurations. It ensures functions and methods have both story coverage and requirement coverage, and it accepts either `@supports` (preferred) or legacy `@story` / `@req` annotations.
 - `traceability/require-story-annotation` and `traceability/require-req-annotation` are **backward-compatible aliases** that focus on the story and requirement aspects separately. They are retained for existing configurations and share the same underlying implementation model as the unified rule, but new ESLint configs should normally rely on `traceability/require-traceability` rather than enabling these legacy keys directly.
 
-All three rule keys can still be configured individually if you need fine-grained control (for example, to tune severities separately), but the recommended and strict presets enable `traceability/require-traceability` by default and keep the legacy keys primarily for projects that adopted them before the unified rule existed. When the underlying function rules are configured with `annotationPlacement: "inside"`, the unified `require-traceability` rule honours inside-brace placement for function and method bodies in the same formatter-aware way that `require-branch-annotation` handles branches.
+All three rule keys can still be configured individually if you need fine-grained control (for example, to tune severities separately), but the recommended and strict presets enable `traceability/require-traceability` by default and keep the legacy keys primarily for projects that adopted them before the unified rule existed. Current releases support `annotationPlacement` on both the branch-level rule and the function-level rules, so you can standardize on inside-brace placement for if/else/try/catch/switch/function/loop blocks. When you leave `annotationPlacement` unspecified, all rules default to the historical before-function/before-branch behavior for backward compatibility.
 
 ### traceability/require-traceability
 
@@ -44,7 +44,7 @@ Options:
 - `methodAnnotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations for class methods and TypeScript method signatures. When omitted or blank, falls back to `annotationTemplate` if provided, otherwise the built-in template.
 - `autoFix` (boolean, optional) – When set to `false`, disables all automatic fix behavior for this rule while retaining its suggestions and diagnostics. When omitted or `true`, the rule behaves as before, inserting placeholder annotations in `--fix` mode.
 - `excludeTestCallbacks` (boolean, optional) – When `true` (default), excludes anonymous arrow functions that are direct callbacks to common test framework functions (for example, Jest/Mocha/Vitest `describe`/`it`/`test`/`beforeEach`/`afterEach`/`beforeAll`/`afterAll`, plus focused/skipped/concurrent variants such as `fdescribe`, `xdescribe`, `fit`, `xit`, `test.concurrent`, `describe.concurrent`) from function-level annotation requirements. This assumes those test files are already covered by file-level `@supports` annotations and `traceability/require-test-traceability`. When set to `false`, these callbacks are treated like any other arrow function and must be annotated when in-scope.
-- `annotationPlacement` ("before" | "inside", optional) – Controls whether the rule looks for annotations immediately before functions (`"before"`, the default and backward-compatible behaviour) or allows annotations as the first comment-only lines inside function and method bodies (`"inside"`). In inside mode, the rule continues to treat TypeScript declarations and signature-only nodes (such as `TSDeclareFunction` and `TSMethodSignature`) as before-function only, since they have no executable body.
+- `annotationPlacement` ("before" | "inside", optional)  Controls whether the rule treats before-function comments as the source of annotations (`"before"`, the default and backward-compatible behavior) or instead requires annotations as the first comment-only lines inside function and method bodies (`"inside"`). In `"inside"` mode, JSDoc and before-function comments are ignored for block-bodied functions and methods, and only inside-body comments are considered; declaration-only nodes (e.g., TS signatures) continue to use before-node annotations.
 
 Default Severity: `error`
 Example:
@@ -71,7 +71,7 @@ Options:
 
 - `scope` (string[], optional) – Controls which function-like node types are required to have @req annotations. Allowed values: "FunctionDeclaration", "FunctionExpression", "MethodDefinition", "TSDeclareFunction", "TSMethodSignature". Default: ["FunctionDeclaration", "FunctionExpression", "MethodDefinition", "TSDeclareFunction", "TSMethodSignature"].
 - `exportPriority` ("all" | "exported" | "non-exported", optional) – Controls whether the rule checks all functions, only exported ones, or only non-exported ones. Default: "all".
-- `annotationPlacement` ("before" | "inside", optional) – Accepted for configuration parity with `require-story-annotation`; requirement annotations are still evaluated using before-function comments and JSDoc today, so `"inside"` does not change behaviour yet.
+- `annotationPlacement` ("before" | "inside", optional)  Controls whether the rule treats before-function comments as the source of annotations (`"before"`, the default and backward-compatible behavior) or instead requires annotations as the first comment-only lines inside function and method bodies (`"inside"`). In `"inside"` mode, JSDoc and before-function comments are ignored for block-bodied functions and methods, and only inside-body comments are considered; declaration-only nodes (e.g., TS signatures) continue to use before-node annotations.
 
 Default Severity: `error`
 Example (with both `@story` and `@req`, as typically used when both rules are enabled):
@@ -115,7 +115,7 @@ Behavior notes:
 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. Story `028.0-DEV-FUNCTION-PLACEMENT` also extends this inside-brace standard to function and method bodies via `require-story-annotation` when configured, so projects can apply a single inside-brace rule consistently to both branches and functions.
+- `"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. Story `028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION` standardizes inside-brace placement for supported branch constructs; function-level rules continue to use before-function annotations until a future story extends the same standard to functions.
 
 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.