eslint-plugin-traceability 1.20.0 → 1.21.1

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/rules/valid-annotation-format.js

@@ -5,7 +5,9 @@ const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-f
 const valid_annotation_format_validators_1 = require("./helpers/valid-annotation-format-validators");
 function handleImplementsLine(normalized, pending, deps) {
     const { context, comment, options } = deps;
-    const isImplements = /@supports\b/.test(normalized);
+    // Only match `@supports` at the START of the normalized line to avoid
+    // false matches when this keyword appears in prose
+    const isImplements = /^@supports\b/.test(normalized);
     if (!isImplements) {
         return pending;
     }
@@ -15,8 +17,10 @@ function handleImplementsLine(normalized, pending, deps) {
 }
 function handleStoryOrReqLine(normalized, pending, deps) {
     const { context, comment, options } = deps;
-    const isStory = /@story\b/.test(normalized);
-    const isReq = /@req\b/.test(normalized);
+    // Only match `@story`/`@req` at the START of the normalized line to avoid
+    // false matches when these keywords appear in prose (e.g., "@returns ... `@story` annotations")
+    const isStory = /^@story\b/.test(normalized);
+    const isReq = /^@req\b/.test(normalized);
     if (!isStory && !isReq) {
         return pending;
     }
@@ -81,7 +85,7 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     if (afterStoryOrReq !== pending) {
         return afterStoryOrReq;
     }
-    // Implement JSDoc tag coexistence behavior: terminate @story/@req values when a new non-traceability JSDoc tag line (e.g., @param, @returns) is encountered.
+    // Implement JSDoc tag coexistence behavior: terminate `@story`/`@req` values when a new non-traceability JSDoc tag line (e.g., @param, @returns) is encountered.
     // @supports docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md REQ-ANNOTATION-TERMINATION REQ-CONTINUATION-LOGIC
     if ((0, valid_annotation_format_internal_1.isNonTraceabilityJSDocTagLine)(normalized)) {
         (0, valid_annotation_format_validators_1.finalizePendingAnnotation)(context, comment, options, pending);
@@ -96,13 +100,13 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     return extendPendingAnnotation(normalized, pending);
 }
 /**
- * Process a single comment node and validate any @story/@req/@supports annotations it contains.
+ * Process a single comment node and validate any `@story`/`@req`/`@supports` annotations it contains.
  *
- * Supports @story and @req annotations whose values span multiple lines within the same
+ * Supports `@story` and `@req` annotations whose values span multiple lines within the same
  * comment block, collapsing whitespace so that the logical value can be
  * validated against the configured patterns.
  *
- * @supports annotations are validated immediately per-line and are not
+ * `@supports` annotations are validated immediately per-line and are not
  * accumulated into pending multi-line state.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
@@ -172,8 +176,8 @@ exports.default = {
         },
         schema: (0, valid_annotation_options_1.getRuleSchema)(),
         /**
-         * This rule's fixable support is limited to safe @story path suffix normalization per Story 008.0.
-         * Fixes are limited strictly to adjusting the suffix portion of the @story path (e.g., adding
+         * This rule's fixable support is limited to safe `@story` path suffix normalization per Story 008.0.
+         * Fixes are limited strictly to adjusting the suffix portion of the `@story` path (e.g., adding
          * `.md` or `.story.md`), preserving all other comment text and whitespace exactly as written.
          *
          * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
@@ -204,7 +208,7 @@ exports.default = {
         const optionErrors = (0, valid_annotation_options_1.getOptionErrors)();
         return {
             /**
-             * Program-level handler that inspects all comments for @story, @req, and @supports tags
+             * Program-level handler that inspects all comments for `@story`, `@req`, and `@supports` tags
              *
              * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
              * @story docs/stories/008.0-DEV-AUTO-FIX.story.md

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

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkReqAnnotation = checkReqAnnotation;
+/* eslint-disable traceability/valid-annotation-format */
 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 +182,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/reqAnnotationDetection.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasReqAnnotation = hasReqAnnotation;
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Shared @req detection helpers used by annotation-checker utilities.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md

package/lib/tests/config/eslint-config-validation.test.js

@@ -1,4 +1,5 @@
 "use strict";
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Tests for ESLint config rule schemas.
  *

package/lib/tests/config/flat-config-presets-integration.test.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Tests for: docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
  * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md

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

@@ -1,4 +1,5 @@
 "use strict";
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Tests for the require-story-annotation rule schema configuration.
  *
@@ -19,6 +20,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/fixtures/stale/example.js

@@ -1,3 +1,4 @@
 "use strict";
+/* eslint-disable traceability/valid-annotation-format */
 // Sample code with stale annotation
 // @story docs/stories/non-existent.story.md

package/lib/tests/fixtures/update/example.js

@@ -1,3 +1,4 @@
 "use strict";
+/* eslint-disable traceability/valid-annotation-format */
 // Sample code with annotation to update
 // @story docs/stories/old.story.md

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

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Prettier integration tests for annotationPlacement: "inside" across multiple branch types.
  * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md

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

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Prettier integration tests for CatchClause annotation positions.
  * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md

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

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Prettier integration tests for else-if annotation positions.
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md

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

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatWithPrettier = formatWithPrettier;
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Shared helpers for Prettier-based integration tests.
  * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md

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/integration/require-traceability-test-callbacks.integration.test.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Integration tests for require-traceability with configurable test callback exclusion.
  *

package/lib/tests/maintenance/detect-isolated.test.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md

package/lib/tests/perf/maintenance-large-workspace.test.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Performance and stress tests for maintenance tools on large workspaces.
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-VERIFY REQ-MAINT-REPORT REQ-MAINT-UPDATE REQ-MAINT-BATCH

package/lib/tests/perf/valid-annotation-format-large-file.test.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Performance tests for valid-annotation-format on large annotated files.
  *

package/lib/tests/plugin-setup.test.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md

package/lib/tests/rules/error-reporting.test.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Tests for: docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md

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/lib/tests/rules/require-test-traceability.test.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Tests for:
  * - docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md

package/lib/tests/utils/branch-annotation-catch-insert-position.test.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Unit tests for CatchClause insert position calculation.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md

package/lib/tests/utils/branch-annotation-else-if-insert-position.test.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Unit tests for else-if insert position calculation.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Unit tests for branch annotation helpers
  * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md

package/package.json

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