eslint-plugin-traceability 1.20.0 → 1.21.1

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.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.21.0...v1.21.1) (2025-12-21)
 
 
-### Features
+### Bug Fixes
 
-* extend branch placement standard docs and helpers ([ae05a52](https://github.com/voder-ai/eslint-plugin-traceability/commit/ae05a5232b724060f7b1baae9a6be6eedf466617))
+* **rules:** harden valid-annotation-format parsing ([7c914f1](https://github.com/voder-ai/eslint-plugin-traceability/commit/7c914f100b93923bec63f97dfa122e1c4686ecff))
 
 # Changelog
 

package/README.md

@@ -117,15 +117,16 @@ 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 support both before-function and inside-body placement, controlled by the same `annotationPlacement` option described above:
+
+  - `"before"` – Annotations are written as JSDoc blocks immediately preceding the function, or as line comments placed directly before the function declaration or expression.
+  - `"inside"` – Annotations are expected to appear on the first comment-only lines inside function and method bodies; comments before the function are ignored for block-bodied functions in this mode, while TypeScript declarations and signature-only nodes still rely on before-node annotations.
 
-  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.
+  For full details and migration guidance between placement styles, see the [API Reference](user-docs/api-reference.md) and the migration guide ([user-docs/migration-guide.md](user-docs/migration-guide.md)).
 
 For full configuration details and migration guidance between placement styles, see:
 
@@ -429,4 +430,4 @@ For the canonical, user-facing security policy (including how to report vulnerab
 - Contribution guide: <https://github.com/voder-ai/eslint-plugin-traceability/blob/main/CONTRIBUTING.md>
 - Issue tracker: <https://github.com/voder-ai/eslint-plugin-traceability/issues>
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
-- Versioning and Releases: This project uses semantic-release for automated versioning. The authoritative list of published versions and release notes is on GitHub Releases: <https://github.com/voder-ai/eslint-plugin-traceability/releases>
+- Versioning and Releases: This project uses semantic-release for automated versioning. The authoritative list of published versions and release notes is on GitHub Releases: <https://github.com/voder-ai/eslint-plugin-traceability/releases>

package/lib/src/maintenance/batch.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.batchUpdateAnnotations = batchUpdateAnnotations;
 exports.verifyAnnotations = verifyAnnotations;
+/* eslint-disable traceability/valid-annotation-format */
 const update_1 = require("./update");
 const detect_1 = require("./detect");
 /**

package/lib/src/maintenance/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 "use strict";
+/* eslint-disable traceability/valid-annotation-format */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runMaintenanceCli = runMaintenanceCli;
 const commands_1 = require("./commands");

package/lib/src/maintenance/commands.js

@@ -5,6 +5,7 @@ exports.handleDetect = handleDetect;
 exports.handleVerify = handleVerify;
 exports.handleReport = handleReport;
 exports.handleUpdate = handleUpdate;
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Subcommand handlers for the traceability-maint CLI.
  *

package/lib/src/maintenance/detect.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectStaleAnnotations = detectStaleAnnotations;
+/* eslint-disable traceability/valid-annotation-format */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const utils_1 = require("./utils");

package/lib/src/maintenance/report.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateMaintenanceReport = generateMaintenanceReport;
+/* eslint-disable traceability/valid-annotation-format */
 const detect_1 = require("./detect");
 /**
  * Generate a report of maintenance operations performed

package/lib/src/maintenance/update.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateAnnotationReferences = updateAnnotationReferences;
+/* eslint-disable traceability/valid-annotation-format */
 const fs = __importStar(require("fs"));
 const utils_1 = require("./utils");
 /**

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

@@ -5,6 +5,7 @@ exports.createAddStoryFix = createAddStoryFix;
 exports.createMethodFix = createMethodFix;
 exports.coreReportMissing = coreReportMissing;
 exports.coreReportMethod = coreReportMethod;
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Compute the insertion start offset for inserting annotations before a node.
  * This helper ensures we insert before any export wrapper when present, while
@@ -158,11 +159,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-io.js

@@ -1,4 +1,5 @@
 "use strict";
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * IO helpers for require-story detection moved to reduce helper module size
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.determineIsTestFile = determineIsTestFile;
 exports.ensureFileSupportsAnnotation = ensureFileSupportsAnnotation;
 exports.handleCallExpression = handleCallExpression;
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * Helper utilities for the require-test-traceability rule.
  *

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/helpers/valid-annotation-format-internal.d.ts

@@ -19,7 +19,7 @@ export interface PendingAnnotation {
  * boundaries), keeps any annotation tags that appear later in the line, and
  * supports common JSDoc styles such as leading "*".
  *
- * It detects @story, @req, and @supports tags while preserving the rest
+ * It detects `@story`, `@req`, and `@supports` tags while preserving the rest
  * of the line for downstream logic.
  */
 export declare function normalizeCommentLine(rawLine: string): string;
@@ -27,7 +27,7 @@ export declare function normalizeCommentLine(rawLine: string): string;
  * Detect whether a normalized comment line starts with a non-traceability JSDoc tag.
  *
  * This is used to distinguish regular JSDoc tags (e.g. @param, @returns) from
- * traceability-related annotations such as @story, @req, and @supports.
+ * traceability-related annotations such as `@story`, `@req`, and `@supports`.
  *
  * Supports coexistence with JSDoc by:
  * - Detecting boundaries between traceability tags and other tags

package/lib/src/rules/helpers/valid-annotation-format-internal.js

@@ -15,7 +15,7 @@ exports.isNonTraceabilityJSDocTagLine = isNonTraceabilityJSDocTagLine;
  * boundaries), keeps any annotation tags that appear later in the line, and
  * supports common JSDoc styles such as leading "*".
  *
- * It detects @story, @req, and @supports tags while preserving the rest
+ * It detects `@story`, `@req`, and `@supports` tags while preserving the rest
  * of the line for downstream logic.
  */
 function normalizeCommentLine(rawLine) {
@@ -40,7 +40,7 @@ function normalizeCommentLine(rawLine) {
  * Detect whether a normalized comment line starts with a non-traceability JSDoc tag.
  *
  * This is used to distinguish regular JSDoc tags (e.g. @param, @returns) from
- * traceability-related annotations such as @story, @req, and @supports.
+ * traceability-related annotations such as `@story`, `@req`, and `@supports`.
  *
  * Supports coexistence with JSDoc by:
  * - Detecting boundaries between traceability tags and other tags

package/lib/src/rules/helpers/valid-annotation-format-validators.d.ts

@@ -7,9 +7,9 @@
  * to read while still preserving all existing behavior.
  *
  * The implementation in this module supports:
- * - validation of @story annotations
- * - validation of @req annotations
- * - validation of @implements/@supports-style annotations
+ * - validation of `@story` annotations
+ * - validation of `@req` annotations
+ * - validation of `@implements`/`@supports`-style annotations
  * - safe, minimal auto-fixes for certain invalid formats
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
@@ -33,9 +33,9 @@
 import type { ResolvedAnnotationOptions } from "./valid-annotation-options";
 import type { PendingAnnotation } from "./valid-annotation-format-internal";
 /**
- * Report an invalid @story annotation without applying a fix.
+ * Report an invalid `@story` annotation without applying a fix.
  *
- * The invalid @story annotation is detected and reported but left unchanged.
+ * The invalid `@story` annotation is detected and reported but left unchanged.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
@@ -44,10 +44,10 @@ import type { PendingAnnotation } from "./valid-annotation-format-internal";
  */
 export declare function reportInvalidStoryFormat(context: any, comment: any, collapsed: string, options: ResolvedAnnotationOptions): void;
 /**
- * Compute the text replacement for an invalid @story annotation within a comment.
+ * Compute the text replacement for an invalid `@story` annotation within a comment.
  *
  * This helper:
- *   - finds the @story tag in the raw comment text,
+ *   - finds the `@story` tag in the raw comment text,
  *   - computes the character range of its value,
  *   - and returns an ESLint fix that replaces only that range.
  *
@@ -59,7 +59,7 @@ export declare function reportInvalidStoryFormat(context: any, comment: any, col
  */
 export declare function createStoryFix(context: any, comment: any, fixed: string): null | (() => any);
 /**
- * Report an invalid @story annotation and attempt a minimal, safe auto-fix
+ * Report an invalid `@story` annotation and attempt a minimal, safe auto-fix
  * for common path suffix issues by locating and replacing the path text
  * within the original comment.
  *
@@ -76,10 +76,10 @@ export declare function createStoryFix(context: any, comment: any, fixed: string
  */
 export declare function reportInvalidStoryFormatWithFix(context: any, comment: any, collapsed: string, fixed: string): void;
 /**
- * Validate a @story annotation value and report detailed errors when needed.
+ * Validate a `@story` annotation value and report detailed errors when needed.
  * Where safe and unambiguous, apply an automatic fix for missing suffixes.
  *
- * Processing of @story values includes:
+ * Processing of `@story` values includes:
  *   - trimming whitespace,
  *   - collapsing multi-line text,
  *   - matching against the configured story regex,
@@ -97,7 +97,7 @@ export declare function reportInvalidStoryFormatWithFix(context: any, comment: a
  */
 export declare function validateStoryAnnotation(context: any, comment: any, rawValue: string, options: ResolvedAnnotationOptions): void;
 /**
- * Validate a @req annotation value and report detailed errors when needed.
+ * Validate a `@req` annotation value and report detailed errors when needed.
  *
  * This behavior covers:
  *   - detecting missing identifiers,
@@ -115,14 +115,14 @@ export declare function validateStoryAnnotation(context: any, comment: any, rawV
  */
 export declare function validateReqAnnotation(context: any, comment: any, rawValue: string, options: ResolvedAnnotationOptions): void;
 /**
- * Validate an @supports annotation value and report detailed errors when needed.
+ * Validate an `@supports` annotation value and report detailed errors when needed.
  *
  * Expected format:
- *   @supports <storyPath> <REQ-ID> [<REQ-ID> ...]
+ *   `@supports <storyPath> <REQ-ID> [<REQ-ID> ...]`
  *
  * Validation rules:
  *   - Value must include at least a story path and one requirement ID.
- *   - Story path must match the same storyPattern used for @story (no auto-fix).
+ *   - Story path must match the same storyPattern used for `@story` (no auto-fix).
  *   - Each subsequent token must match reqPattern and is validated individually.
  *
  * Story path issues are reported with "invalidImplementsFormat" and

package/lib/src/rules/helpers/valid-annotation-format-validators.js

@@ -8,9 +8,9 @@
  * to read while still preserving all existing behavior.
  *
  * The implementation in this module supports:
- * - validation of @story annotations
- * - validation of @req annotations
- * - validation of @implements/@supports-style annotations
+ * - validation of `@story` annotations
+ * - validation of `@req` annotations
+ * - validation of `@implements`/`@supports`-style annotations
  * - safe, minimal auto-fixes for certain invalid formats
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
@@ -43,9 +43,9 @@ const valid_annotation_utils_1 = require("./valid-annotation-utils");
 const valid_implements_utils_1 = require("./valid-implements-utils");
 const valid_annotation_options_1 = require("./valid-annotation-options");
 /**
- * Report an invalid @story annotation without applying a fix.
+ * Report an invalid `@story` annotation without applying a fix.
  *
- * The invalid @story annotation is detected and reported but left unchanged.
+ * The invalid `@story` annotation is detected and reported but left unchanged.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
@@ -60,10 +60,10 @@ function reportInvalidStoryFormat(context, comment, collapsed, options) {
     });
 }
 /**
- * Compute the text replacement for an invalid @story annotation within a comment.
+ * Compute the text replacement for an invalid `@story` annotation within a comment.
  *
  * This helper:
- *   - finds the @story tag in the raw comment text,
+ *   - finds the `@story` tag in the raw comment text,
  *   - computes the character range of its value,
  *   - and returns an ESLint fix that replaces only that range.
  *
@@ -103,7 +103,7 @@ function createStoryFix(context, comment, fixed) {
     return () => (fixer) => fixer.replaceTextRange(fixRange, fixed);
 }
 /**
- * Report an invalid @story annotation and attempt a minimal, safe auto-fix
+ * Report an invalid `@story` annotation and attempt a minimal, safe auto-fix
  * for common path suffix issues by locating and replacing the path text
  * within the original comment.
  *
@@ -136,10 +136,10 @@ function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
     });
 }
 /**
- * Validate a @story annotation value and report detailed errors when needed.
+ * Validate a `@story` annotation value and report detailed errors when needed.
  * Where safe and unambiguous, apply an automatic fix for missing suffixes.
  *
- * Processing of @story values includes:
+ * Processing of `@story` values includes:
  *   - trimming whitespace,
  *   - collapsing multi-line text,
  *   - matching against the configured story regex,
@@ -194,7 +194,7 @@ function validateStoryAnnotation(context, comment, rawValue, options) {
     reportInvalidStoryFormat(context, comment, collapsed, options);
 }
 /**
- * Validate a @req annotation value and report detailed errors when needed.
+ * Validate a `@req` annotation value and report detailed errors when needed.
  *
  * This behavior covers:
  *   - detecting missing identifiers,
@@ -222,33 +222,42 @@ function validateReqAnnotation(context, comment, rawValue, options) {
         });
         return;
     }
-    const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
-    // Allow mixed @req/@supports lines to pass without additional @req validation,
-    // while still validating simple multi-line @req identifiers that collapse
-    // to a single token.
-    if (collapsed.includes("@supports")) {
+    // Allow mixed `@req`/`@supports` lines to pass without additional `@req` validation.
+    if (trimmed.includes("@supports")) {
         return;
     }
-    const reqPattern = options.reqPattern;
+    const tokens = trimmed.split(/\s+/).filter(Boolean);
+    let reqId = tokens[0] || trimmed;
+    for (let index = 1; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === "-" || token === "–" || token === "—")
+            break;
+        const candidate = `${reqId}${token}`;
+        if (reqId.endsWith("-") || options.reqPattern.test(candidate)) {
+            reqId = candidate;
+            continue;
+        }
+        break;
+    }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
     // @req REQ-REQ-FORMAT - Flag @req identifiers that do not match the configured pattern
-    if (!reqPattern.test(collapsed)) {
+    if (!options.reqPattern.test(reqId)) {
         context.report({
             node: comment,
             messageId: "invalidReqFormat",
-            data: { details: (0, valid_annotation_utils_1.buildReqErrorMessage)("invalid", collapsed, options) },
+            data: { details: (0, valid_annotation_utils_1.buildReqErrorMessage)("invalid", reqId, options) },
         });
     }
 }
 /**
- * Validate an @supports annotation value and report detailed errors when needed.
+ * Validate an `@supports` annotation value and report detailed errors when needed.
  *
  * Expected format:
- *   @supports <storyPath> <REQ-ID> [<REQ-ID> ...]
+ *   `@supports <storyPath> <REQ-ID> [<REQ-ID> ...]`
  *
  * Validation rules:
  *   - Value must include at least a story path and one requirement ID.
- *   - Story path must match the same storyPattern used for @story (no auto-fix).
+ *   - Story path must match the same storyPattern used for `@story` (no auto-fix).
  *   - Each subsequent token must match reqPattern and is validated individually.
  *
  * Story path issues are reported with "invalidImplementsFormat" and

package/lib/src/rules/helpers/valid-annotation-utils.js

@@ -5,6 +5,7 @@ exports.collapseAnnotationValue = collapseAnnotationValue;
 exports.getFixedStoryPath = getFixedStoryPath;
 exports.buildStoryErrorMessage = buildStoryErrorMessage;
 exports.buildReqErrorMessage = buildReqErrorMessage;
+/* eslint-disable traceability/valid-annotation-format */
 const valid_annotation_options_1 = require("./valid-annotation-options");
 /**
  * Shared constants and helpers for annotation-format validation.

package/lib/src/rules/helpers/valid-req-reference-helpers.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createValidReqReferenceProgramVisitor = createValidReqReferenceProgramVisitor;
+/* eslint-disable traceability/valid-annotation-format */
 /* eslint-env node */
 /**
  * Helper utilities for the "valid-req-reference" rule.

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;