eslint-plugin-traceability 1.19.4 → 1.21.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.19.4](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.19.3...v1.19.4) (2025-12-18)
+# [1.21.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.20.0...v1.21.0) (2025-12-19)
 
 
-### Bug Fixes
+### Features
 
-* migrate before-brace annotations into inside-brace placement ([c8c381d](https://github.com/voder-ai/eslint-plugin-traceability/commit/c8c381d5f5fbd39fdb626e9dd6fe2dd837bffb53))
+* support inside-brace placement for function-level rules ([064b1a4](https://github.com/voder-ai/eslint-plugin-traceability/commit/064b1a4e7627b5e35afd074752724ab5958e9d8b))
 
 # Changelog
 

package/README.md

@@ -117,13 +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.
 
-  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.
+  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

@@ -139,6 +139,10 @@ function createMissingStoryReportDescriptor(config) {
         ],
     };
 }
+function resolveAnnotationPlacement(options) {
+    const raw = options?.annotationPlacement;
+    return raw === "inside" || raw === "before" ? raw : "before";
+}
 /**
  * Core helper to report a missing @story annotation for a function-like node.
  * This reporting utility delegates behavior to injected dependencies so that
@@ -153,7 +157,14 @@ function createMissingStoryReportDescriptor(config) {
 function coreReportMissing(deps, context, sourceCode, config) {
     const { node, target: passedTarget, options = {} } = config;
     withSafeReporting("coreReportMissing", () => {
-        if (deps.hasStoryAnnotation(sourceCode, node)) {
+        const annotationPlacement = resolveAnnotationPlacement(options);
+        const hasWithPlacement = deps.hasStoryAnnotationWithPlacement;
+        if (typeof hasWithPlacement === "function") {
+            if (hasWithPlacement(sourceCode, node, annotationPlacement)) {
+                return;
+            }
+        }
+        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,6 +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;
+/**
+ * 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
@@ -84,4 +103,4 @@ declare function reportMethod(context: Rule.RuleContext, sourceCode: any, config
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED
  */
-export { STORY_PATH, getAnnotationTemplate, shouldApplyAutoFix, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, getNodeName, extractName, resolveTargetNode, shouldProcessNode, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, reportMissing, reportMethod, };
+export { STORY_PATH, getAnnotationTemplate, shouldApplyAutoFix, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, hasStoryAnnotationWithPlacement, getNodeName, extractName, resolveTargetNode, shouldProcessNode, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, reportMissing, reportMethod, };

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

@@ -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,6 +222,49 @@ function hasStoryAnnotation(sourceCode, node) {
     }
     return false;
 }
+/**
+ * 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
@@ -372,6 +417,7 @@ function resolveAnnotationTargetNode(sourceCode, node, passedTarget) {
 function reportMissing(context, sourceCode, config) {
     (0, require_story_core_1.coreReportMissing)({
         hasStoryAnnotation,
+        hasStoryAnnotationWithPlacement,
         getReportedFunctionName,
         resolveAnnotationTargetNode,
         getNameNodeForReport,
@@ -387,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

@@ -6,6 +6,9 @@
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of which exports are checked
  * @req REQ-EXPORT-PRIORITY - Allow configuration of export priority behavior
+ *
+ * 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

@@ -39,6 +39,9 @@ const rule = {
                     exportPriority: {
                         enum: require_story_helpers_1.EXPORT_PRIORITY_VALUES,
                     },
+                    annotationPlacement: {
+                        enum: ["before", "inside"],
+                    },
                 },
                 additionalProperties: false,
             },
@@ -56,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.
@@ -64,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.d.ts

@@ -17,6 +17,10 @@ import type { Rule } from "eslint";
 /**
  * ESLint rule to require @story annotations on functions/methods.
  *
+ * This rule participates in Story 028.0 placement standardization by supporting
+ * configurable annotation placement, including inside-brace function annotations
+ * when configured.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md

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

@@ -2,9 +2,50 @@
 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.
  *
+ * This rule participates in Story 028.0 placement standardization by supporting
+ * configurable annotation placement, including inside-brace function annotations
+ * when configured.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
@@ -54,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,
             },
@@ -68,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
@@ -106,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, {
@@ -117,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/src/utils/function-annotation-helpers.d.ts

@@ -0,0 +1,23 @@
+import type { Rule } from "eslint";
+/**
+ * Determine whether a function-like node can support inside-brace
+ * placement semantics. Only nodes with a concrete BlockStatement body are
+ * eligible; TypeScript declarations and signature-only nodes are
+ * intentionally excluded.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES
+ */
+export declare function supportsInsidePlacementForFunction(node: any): boolean;
+/**
+ * Gather the concatenated comment text from the first contiguous
+ * comment-only lines inside a function body. When no such comments are
+ * present or the node has no block body, an empty string is returned.
+ *
+ * This mirrors the branch helpers' behaviour for inside-brace placement
+ * (for example, simple if-statements and switch cases) so that
+ * function-level rules can share the same mental model: annotations live
+ * on the first comment-only line(s) inside the body braces.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-ALL-BLOCK-TYPES
+ */
+export declare function getFunctionInsideBodyCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;

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

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportsInsidePlacementForFunction = supportsInsidePlacementForFunction;
+exports.getFunctionInsideBodyCommentText = getFunctionInsideBodyCommentText;
+const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
+/**
+ * Helpers for determining function-body annotation placement.
+ *
+ * These utilities are shared between the function-level traceability rules
+ * (require-story-annotation, require-req-annotation) so they can honour the
+ * same "inside" placement semantics used by branch rules when
+ * `annotationPlacement: "inside"` is configured.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
+ */
+/**
+ * Locate the BlockStatement that represents the executable body of a
+ * function-like construct. Returns null when the node has no block body
+ * (for example, TypeScript declarations or arrow functions with
+ * expression bodies).
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES
+ */
+function getFunctionBodyBlock(node) {
+    if (!node || typeof node.type !== "string") {
+        return null;
+    }
+    if (node.type === "FunctionDeclaration" ||
+        node.type === "FunctionExpression" ||
+        node.type === "ArrowFunctionExpression") {
+        const body = node.body;
+        return body && body.type === "BlockStatement" ? body : null;
+    }
+    if (node.type === "MethodDefinition") {
+        const value = node.value;
+        if (value && value.type === "FunctionExpression") {
+            const body = value.body;
+            return body && body.type === "BlockStatement" ? body : null;
+        }
+    }
+    return null;
+}
+/**
+ * Determine whether a function-like node can support inside-brace
+ * placement semantics. Only nodes with a concrete BlockStatement body are
+ * eligible; TypeScript declarations and signature-only nodes are
+ * intentionally excluded.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES
+ */
+function supportsInsidePlacementForFunction(node) {
+    return !!getFunctionBodyBlock(node);
+}
+/**
+ * Gather the concatenated comment text from the first contiguous
+ * comment-only lines inside a function body. When no such comments are
+ * present or the node has no block body, an empty string is returned.
+ *
+ * This mirrors the branch helpers' behaviour for inside-brace placement
+ * (for example, simple if-statements and switch cases) so that
+ * function-level rules can share the same mental model: annotations live
+ * on the first comment-only line(s) inside the body braces.
+ *
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-ALL-BLOCK-TYPES
+ */
+function getFunctionInsideBodyCommentText(sourceCode, node) {
+    const block = getFunctionBodyBlock(node);
+    if (!block ||
+        !block.loc ||
+        !block.loc.start ||
+        !block.loc.end ||
+        typeof block.loc.start.line !== "number" ||
+        typeof block.loc.end.line !== "number") {
+        return "";
+    }
+    const getCommentsInside = sourceCode.getCommentsInside;
+    if (typeof getCommentsInside === "function") {
+        try {
+            const insideComments = getCommentsInside(block) || [];
+            const insideText = insideComments
+                .filter((c) => c && typeof c.value === "string")
+                .map((c) => c.value)
+                .join(" ");
+            if (insideText) {
+                return insideText;
+            }
+        }
+        catch {
+            // Fall through to the line-based fallback when structured comment
+            // retrieval is unavailable or fails.
+        }
+    }
+    const lines = sourceCode.lines;
+    if (!Array.isArray(lines)) {
+        return "";
+    }
+    const startIndex = block.loc.start.line - 1;
+    const endIndex = block.loc.end.line - 1;
+    const insideText = (0, branch_annotation_helpers_1.scanCommentLinesInRange)(lines, startIndex + 1, endIndex);
+    return insideText || "";
+}

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.19.4",
+  "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.
+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,6 +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 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:
@@ -70,6 +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)  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):
@@ -113,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.
+- `"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.