eslint-plugin-traceability 1.21.0 → 1.22.0

package/lib/src/rules/no-redundant-annotation.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const branch_annotation_helpers_1 = require("../utils/branch-annotation-helpers");
-const annotation_scope_analyzer_1 = require("../utils/annotation-scope-analyzer");
+const redundancy_detector_1 = require("../utils/redundancy-detector");
 /**
  * ESLint rule to detect redundant traceability annotations on statements
  * that are already covered by their containing scope.
@@ -47,239 +46,6 @@ function normalizeOptions(raw) {
         alwaysCovered,
     };
 }
-/**
- * Collect comments around a scope node using JSDoc, leading comments,
- * and any comments that appear immediately before the node.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE
- */
-function getScopeCommentsFromJSDocAndLeading(sourceCode, scopeNode) {
-    const comments = [];
-    const jsdoc = sourceCode.getJSDocComment
-        ? sourceCode.getJSDocComment(scopeNode)
-        : null;
-    const before = sourceCode.getCommentsBefore
-        ? sourceCode.getCommentsBefore(scopeNode) || []
-        : [];
-    if (jsdoc) {
-        comments.push(jsdoc);
-    }
-    if (Array.isArray(scopeNode.leadingComments)) {
-        comments.push(...scopeNode.leadingComments);
-    }
-    comments.push(...before);
-    return comments;
-}
-/**
- * Compute the story/requirement pairs for annotations that apply to the
- * given scope node.
- *
- * For branch scopes we reuse the same comment-gathering helper used by
- * the require-branch-annotation rule so that REQ-SCOPE-INHERITANCE
- * aligns with existing behavior. For non-branch scopes, we reuse a
- * shared helper that collects JSDoc, leading, and immediately-before
- * comments around the scope node.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE
- */
-function getScopePairs(context, scopeNode, parent) {
-    const sourceCode = context.getSourceCode();
-    // Branch-style scope: use the branch helpers to collect comment text.
-    if (branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES.includes(scopeNode.type)) {
-        /**
-         * Inside-brace annotations used as branch-level indicators (inside placement
-         * mode) should not be folded into scopePairs for redundancy purposes; only
-         * before-brace annotations define the covering scope here.
-         *
-         * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-NON-REDUNDANT-INSIDE REQ-PLACEMENT-CONFIG
-         */
-        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent, "before");
-        return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(text);
-    }
-    const comments = getScopeCommentsFromJSDocAndLeading(sourceCode, scopeNode);
-    return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(comments);
-}
-/**
- * Collect the comments directly associated with a statement node.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-STATEMENT-SIGNIFICANCE REQ-SCOPE-ANALYSIS
- */
-function getStatementComments(context, node) {
-    const sourceCode = context.getSourceCode();
-    const comments = [];
-    if (sourceCode.getCommentsBefore) {
-        comments.push(...(sourceCode.getCommentsBefore(node) || []));
-    }
-    if (Array.isArray(node.leadingComments)) {
-        comments.push(...node.leadingComments);
-    }
-    return comments;
-}
-/**
- * Debug helper for logging scope-level pairs in TRACEABILITY_DEBUG mode.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS
- */
-function debugScopePairs(scopeNode, scopePairs) {
-    if (process.env.TRACEABILITY_DEBUG !== "1") {
-        return;
-    }
-    console.log("[no-redundant-annotation] Scope node type=%s pairs=%o", scopeNode && scopeNode.type, Array.from(scopePairs));
-}
-/**
- * Walk up enclosing scopes starting from the given scope node and
- * accumulate all story/requirement pairs, limited by maxScopeDepth.
- *
- * This keeps REQ-SCOPE-INHERITANCE and REQ-CONFIGURABLE-STRICTNESS
- * aligned with the story's configuration model while delegating the
- * actual comment parsing to getScopePairs.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE REQ-CONFIGURABLE-STRICTNESS
- */
-function collectScopePairs(context, startingScopeNode, maxScopeDepth) {
-    const result = new Set();
-    if (!startingScopeNode || maxScopeDepth <= 0) {
-        return result;
-    }
-    let current = startingScopeNode;
-    let depth = 0;
-    while (current && depth < maxScopeDepth) {
-        const parent = current.parent;
-        const pairs = getScopePairs(context, current, parent);
-        for (const key of pairs) {
-            result.add(key);
-        }
-        current = parent;
-        depth += 1;
-    }
-    return result;
-}
-/**
- * Extract statement-level comments and story/requirement pairs that are
- * relevant for redundancy analysis within a given scope.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-STATEMENT-SIGNIFICANCE REQ-SCOPE-ANALYSIS
- */
-function getStatementPairsForRedundancy(context, stmt, scopePairs, options) {
-    if (scopePairs.size === 0) {
-        return null;
-    }
-    if (!(0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(stmt, options, branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES)) {
-        return null;
-    }
-    const stmtComments = getStatementComments(context, stmt);
-    if (stmtComments.length === 0) {
-        return null;
-    }
-    const stmtPairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(stmtComments);
-    if (process.env.TRACEABILITY_DEBUG === "1") {
-        console.log("[no-redundant-annotation] Statement type=%s eligible=%s commentCount=%d pairs=%o", stmt && stmt.type, (0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(stmt, options, branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES), stmtComments.length, Array.from(stmtPairs));
-    }
-    if (stmtPairs.size === 0) {
-        return null;
-    }
-    return { comments: stmtComments, pairs: stmtPairs };
-}
-/**
- * Decide whether the provided statement-level pairs should be considered
- * redundant within the given scope, respecting configuration options.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-CONFIGURABLE-STRICTNESS
- */
-function isStatementRedundantWithinScope(stmtPairs, scopePairs, options) {
-    if (options.allowEmphasisDuplication &&
-        stmtPairs.size === 1 &&
-        (0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
-        return false;
-    }
-    if (!(0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
-        return false;
-    }
-    return true;
-}
-/**
- * Filter a list of comments down to those that contain traceability
- * annotations relevant for redundancy detection.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SAFE-REMOVAL REQ-REDUNDANCY-PATTERNS
- */
-function getAnnotationCommentsFromStatement(comments) {
-    return comments.filter((comment) => {
-        const commentText = typeof comment.value === "string" ? comment.value : "";
-        return /@story\b|@req\b|@supports\b/.test(commentText);
-    });
-}
-/**
- * Determine whether a statement is redundant relative to the provided
- * scopePairs and options, using helper functions to gather statement
- * pairs, apply redundancy rules, and collect the associated annotation
- * comments. Returns null when the statement should not be treated as
- * redundant.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-STATEMENT-SIGNIFICANCE REQ-CONFIGURABLE-STRICTNESS
- */
-function getRedundantStatementContext(context, stmt, scopePairs, options) {
-    const stmtInfo = getStatementPairsForRedundancy(context, stmt, scopePairs, options);
-    if (!stmtInfo) {
-        return null;
-    }
-    const { comments, pairs } = stmtInfo;
-    if (!isStatementRedundantWithinScope(pairs, scopePairs, options)) {
-        return null;
-    }
-    const annotationComments = getAnnotationCommentsFromStatement(comments);
-    if (annotationComments.length === 0) {
-        return null;
-    }
-    return { comments: annotationComments };
-}
-/**
- * Compute unique removal ranges for the given annotation comments.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SAFE-REMOVAL
- */
-function getRemovalRangesForAnnotationComments(comments, sourceCode) {
-    const rangeMap = new Map();
-    for (const comment of comments) {
-        const [removalStart, removalEnd] = (0, annotation_scope_analyzer_1.getCommentRemovalRange)(comment, sourceCode);
-        const key = `${removalStart}:${removalEnd}`;
-        if (!rangeMap.has(key)) {
-            rangeMap.set(key, [removalStart, removalEnd]);
-        }
-    }
-    return Array.from(rangeMap.values()).sort((a, b) => b[0] - a[0]);
-}
-/**
- * Analyze a block's statements and report redundant traceability annotations.
- *
- * This helper encapsulates the iteration and reporting logic so that the
- * BlockStatement visitor remains small and focused on scope setup.
- *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-STATEMENT-SIGNIFICANCE
- */
-function reportRedundantAnnotationsInBlock(context, blockNode, scopePairs, options) {
-    const statements = Array.isArray(blockNode.body) ? blockNode.body : [];
-    if (statements.length === 0 || scopePairs.size === 0)
-        return;
-    const sourceCode = context.getSourceCode();
-    for (const stmt of statements) {
-        const info = getRedundantStatementContext(context, stmt, scopePairs, options);
-        if (!info) {
-            continue;
-        }
-        const ranges = getRemovalRangesForAnnotationComments(info.comments, sourceCode);
-        if (ranges.length === 0) {
-            continue;
-        }
-        context.report({
-            node: stmt,
-            messageId: "redundantAnnotation",
-            fix(fixer) {
-                return ranges.map(([start, end]) => fixer.removeRange([start, end]));
-            },
-        });
-    }
-}
 const rule = {
     meta: {
         type: "suggestion",
@@ -337,11 +103,11 @@ const rule = {
                 if (parent && parent.type === "CatchClause") {
                     return;
                 }
-                const scopePairs = collectScopePairs(context, parent, options.maxScopeDepth);
-                debugScopePairs(parent, scopePairs);
+                const scopePairs = (0, redundancy_detector_1.collectScopePairs)(context, parent, options.maxScopeDepth);
+                (0, redundancy_detector_1.debugScopePairs)(parent, scopePairs);
                 if (scopePairs.size === 0)
                     return;
-                reportRedundantAnnotationsInBlock(context, node, scopePairs, options);
+                (0, redundancy_detector_1.reportRedundantAnnotationsInBlock)(context, node, scopePairs, options);
             },
         };
     },

package/lib/src/rules/prefer-implements-annotation.d.ts

@@ -23,6 +23,18 @@
  * @req REQ-AUTO-FIX - Provide safe, opt-in auto-fix for simple legacy patterns
  */
 import type { Rule } from "eslint";
+/**
+ * ESLint rule: prefer-implements-annotation
+ *
+ * Recommend migrating from legacy `@story` + `@req` annotations to the
+ * newer `@supports` format. This rule is **disabled by default** and
+ * is intended as an optional, opt-in migration aid.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
+ */
 /**
  * ESLint rule: prefer-implements-annotation
  *

package/lib/src/rules/prefer-implements-annotation.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-format-internal");
+const prefer_implements_inline_1 = require("./helpers/prefer-implements-inline");
 // Maximum number of distinct @story paths allowed before treating as "multi-story".
 // @req REQ-MULTI-STORY-DETECT - Centralized threshold constant for detecting multi-story patterns
 const MULTI_STORY_THRESHOLD = 1;
@@ -223,173 +224,17 @@ function processBlockComment(comment, context) {
     });
 }
 /**
- * Extract the leading whitespace and `//` prefix from a line comment's full
- * source text so that new inline annotations can be inserted with matching
- * indentation and formatting.
- *
- * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
- * @req REQ-MIGRATE-INLINE
- */
-function getLinePrefixFromText(fullText) {
-    const match = fullText.match(/^(\s*\/\/\s*)/);
-    return match ? match[1] : "";
-}
-/**
- * Attempt to construct an inline auto-fix that replaces a contiguous
- * sequence of `@story` and `@req` line comments with a single `@supports`
- * annotation while preserving the original comment prefix.
- *
- * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
- * @req REQ-MIGRATE-INLINE
- */
-function tryBuildInlineAutoFix(context, comments, storyIndex, reqIndices) {
-    const sourceCode = context.getSourceCode();
-    const storyComment = comments[storyIndex];
-    const storyNormalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(storyComment.value || "");
-    if (!storyNormalized || !/^@story\b/.test(storyNormalized)) {
-        return null;
-    }
-    const storyParts = storyNormalized.split(/\s+/);
-    if (storyParts.length !== MIN_STORY_TOKENS) {
-        return null;
-    }
-    const storyPath = storyParts[1];
-    const reqIds = [];
-    for (const idx of reqIndices) {
-        const reqComment = comments[idx];
-        const reqNormalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(reqComment.value || "");
-        if (!reqNormalized || !/^@req\b/.test(reqNormalized)) {
-            return null;
-        }
-        const reqParts = reqNormalized.split(/\s+/);
-        if (reqParts.length !== MIN_REQ_TOKENS) {
-            return null;
-        }
-        reqIds.push(reqParts[1]);
-    }
-    if (!reqIds.length) {
-        return null;
-    }
-    const fullText = sourceCode.text.slice(storyComment.range[0], storyComment.range[1]);
-    const linePrefix = getLinePrefixFromText(fullText);
-    const implAnnotation = `@supports ${storyPath} ${reqIds.join(" ")}`;
-    const implLine = `${linePrefix}${implAnnotation}`;
-    const start = storyComment.range[0];
-    const end = comments[reqIndices[reqIndices.length - 1]].range[1];
-    return (fixer) => fixer.replaceTextRange([start, end], implLine);
-}
-/**
- * Coordinate detection and optional migration of a single inline `@story`
- * comment and its following `@req` comments, reporting diagnostics and
- * scheduling auto-fixes where safe.
+ * ESLint rule: prefer-implements-annotation
  *
- * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
- * @req REQ-MIGRATE-INLINE
- */
-function collectReqIndicesAfterStory(group, startIndex) {
-    const n = group.length;
-    const reqIndices = [];
-    let j = startIndex + 1;
-    while (j < n) {
-        const next = group[j];
-        const nextNormalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(next.value || "");
-        if (!nextNormalized || /^@supports\b/.test(nextNormalized)) {
-            break;
-        }
-        if (/^@req\b/.test(nextNormalized)) {
-            reqIndices.push(j);
-            j += 1;
-            continue;
-        }
-        break;
-    }
-    return { reqIndices, nextIndex: j };
-}
-function handleInlineStorySequence(context, group, startIndex) {
-    const current = group[startIndex];
-    const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
-    if (!normalized || !/^@story\b/.test(normalized)) {
-        return startIndex + 1;
-    }
-    if (/^@supports\b/.test(normalized)) {
-        return startIndex + 1;
-    }
-    const storyIndex = startIndex;
-    const { reqIndices, nextIndex } = collectReqIndicesAfterStory(group, startIndex);
-    if (reqIndices.length === 0) {
-        context.report({
-            node: current,
-            messageId: "preferImplements",
-        });
-        return startIndex + 1;
-    }
-    const fix = tryBuildInlineAutoFix(context, group, storyIndex, reqIndices);
-    if (fix) {
-        context.report({
-            node: current,
-            messageId: "preferImplements",
-            fix,
-        });
-    }
-    else {
-        context.report({
-            node: current,
-            messageId: "preferImplements",
-        });
-    }
-    return nextIndex;
-}
-/**
- * Process a contiguous group of inline line comments, identifying legacy
- * `@story`/`@req` sequences and scheduling the corresponding diagnostics
- * and potential auto-fixes for migration to `@supports`.
+ * Recommend migrating from legacy `@story` + `@req` annotations to the
+ * newer `@supports` format. This rule is **disabled by default** and
+ * is intended as an optional, opt-in migration aid.
  *
  * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
- * @req REQ-MIGRATE-INLINE
- */
-function advanceInlineGroupIndex(context, group, currentIndex) {
-    const current = group[currentIndex];
-    const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
-    if (!normalized || !/^@story\b/.test(normalized)) {
-        return currentIndex + 1;
-    }
-    return handleInlineStorySequence(context, group, currentIndex);
-}
-function processInlineGroup(context, group) {
-    if (group.length === 0)
-        return;
-    let i = 0;
-    while (i < group.length) {
-        i = advanceInlineGroupIndex(context, group, i);
-    }
-}
-/**
- * Scan sequences of Line comments for inline legacy @story/@req patterns and
- * report diagnostics and optional auto-fixes.
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
  */
-function processInlineComments(context, lineComments) {
-    if (!lineComments.length)
-        return;
-    // Group by contiguous line numbers
-    let group = [lineComments[0]];
-    const flushGroup = () => {
-        processInlineGroup(context, group);
-        group = [];
-    };
-    for (let idx = 1; idx < lineComments.length; idx++) {
-        const prev = lineComments[idx - 1];
-        const curr = lineComments[idx];
-        if (curr.loc.start.line === prev.loc.start.line + 1 &&
-            curr.loc.start.column === prev.loc.start.column) {
-            group.push(curr);
-        }
-        else {
-            flushGroup();
-            group.push(curr);
-        }
-    }
-    flushGroup();
-}
 /**
  * ESLint rule: prefer-implements-annotation
  *
@@ -472,7 +317,7 @@ const preferImplementsAnnotationRule = {
                     processBlockComment(comment, context);
                 });
                 const lineComments = comments.filter((comment) => comment.type === "Line");
-                processInlineComments(context, lineComments);
+                (0, prefer_implements_inline_1.processInlineComments)(context, lineComments);
             },
         };
     },

package/lib/src/rules/require-traceability.d.ts

@@ -2,6 +2,14 @@
  * Composite ESLint rule that enforces both story and requirement traceability
  * annotations on functions and methods.
  *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Require both @story and @req annotations via composition
+ * @req REQ-FUNCTION-DETECTION - Detect functions via composed rules
+ * @req REQ-CONFIGURABLE-SCOPE - Support scope configuration through underlying rules
+ * @req REQ-EXPORT-PRIORITY - Support export priority through underlying rules
+ * @req REQ-ERROR-LOCATION - Report errors at function locations via composed rules
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript syntax via composed rules
+ *
  * Implements Story 003.0-DEV-FUNCTION-ANNOTATIONS with:
  * - REQ-ANNOTATION-REQUIRED
  * - REQ-FUNCTION-DETECTION

package/lib/src/rules/require-traceability.js

@@ -3,6 +3,14 @@
  * Composite ESLint rule that enforces both story and requirement traceability
  * annotations on functions and methods.
  *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Require both @story and @req annotations via composition
+ * @req REQ-FUNCTION-DETECTION - Detect functions via composed rules
+ * @req REQ-CONFIGURABLE-SCOPE - Support scope configuration through underlying rules
+ * @req REQ-EXPORT-PRIORITY - Support export priority through underlying rules
+ * @req REQ-ERROR-LOCATION - Report errors at function locations via composed rules
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript syntax via composed rules
+ *
  * Implements Story 003.0-DEV-FUNCTION-ANNOTATIONS with:
  * - REQ-ANNOTATION-REQUIRED
  * - REQ-FUNCTION-DETECTION

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

@@ -1,15 +1,16 @@
 /**
  * Helper to check @req annotation presence on TS declare functions and method signatures.
+ *
  * This helper is intentionally scope/exportPriority agnostic and focuses solely
  * on detection and reporting of @req annotations for the given node.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
  * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
  * @param context - ESLint rule context used to obtain source and report problems
  * @param node - Function-like AST node whose surrounding comments should be inspected
- * @param options - Optional configuration controlling behaviour (e.g., enableFix)
- * @returns void
+ * @param options - Optional configuration controlling behaviour (e.g., enableFix, annotationPlacement)
  */
 export declare function checkReqAnnotation(context: any, node: any, options?: {
     enableFix?: boolean;

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

@@ -1,6 +1,7 @@
 "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");
@@ -168,16 +169,17 @@ function reportMissing(context, node, enableFix = true) {
 }
 /**
  * Helper to check @req annotation presence on TS declare functions and method signatures.
+ *
  * This helper is intentionally scope/exportPriority agnostic and focuses solely
  * on detection and reporting of @req annotations for the given node.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
  * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
  * @param context - ESLint rule context used to obtain source and report problems
  * @param node - Function-like AST node whose surrounding comments should be inspected
- * @param options - Optional configuration controlling behaviour (e.g., enableFix)
- * @returns void
+ * @param options - Optional configuration controlling behaviour (e.g., enableFix, annotationPlacement)
  */
 function checkReqAnnotation(context, node, options) {
     const { enableFix = true } = options ?? {};

package/lib/src/utils/branch-annotation-catch-helpers.d.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "eslint";
+/**
+ * Gather comment text from inside a CatchClause body.
+ *
+ * Uses dual-position detection strategy: first attempts getCommentsInside API,
+ * then falls back to line-based scanning if API is unavailable or returns empty.
+ *
+ * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+ * @req REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @param sourceCode - ESLint source code object providing comment access APIs
+ * @param node - CatchClause AST node whose body will be scanned for comments
+ * @returns Concatenated comment text from inside the catch body, or empty string if none found
+ */
+export declare function getInsideCatchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;
+/**
+ * Gather comment text from the first contiguous comment lines inside a TryStatement block body.
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT
+ * @param sourceCode - ESLint source code object providing line access
+ * @param node - TryStatement AST node whose block will be scanned for comments
+ * @returns Concatenated comment text from inside the try block, or empty string if none found
+ */
+export declare function getInsideTryBlockCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;