eslint-plugin-traceability 1.21.1 → 1.22.0

package/lib/src/utils/branch-annotation-if-helpers.js

@@ -7,6 +7,7 @@ exports.scanElseIfBetweenConditionAndBody = scanElseIfBetweenConditionAndBody;
 exports.scanElseIfInsideBlockComments = scanElseIfInsideBlockComments;
 exports.getInsideElseIfCommentText = getInsideElseIfCommentText;
 exports.gatherElseIfCommentText = gatherElseIfCommentText;
+exports.gatherSimpleIfCommentText = gatherSimpleIfCommentText;
 const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
 /**
  * Small shared helpers for IfStatement/else-if specific annotation handling.
@@ -135,3 +136,61 @@ function gatherElseIfCommentText(sourceCode, node, parent, options) {
     }
     return beforeText;
 }
+/**
+ * Try to get comments from inside a node using getCommentsInside if available.
+ */
+function tryGetCommentsInsideNode(sourceCode, consequent) {
+    const getCommentsInside = sourceCode.getCommentsInside;
+    if (typeof getCommentsInside !== "function") {
+        return "";
+    }
+    try {
+        const insideComments = getCommentsInside(consequent) || [];
+        const extractCommentValue = (c) => c.value;
+        return insideComments.map(extractCommentValue).join(" ");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Scan for comments at the start of a block using line-based fallback.
+ */
+function scanBlockStartComments(sourceCode, consequent) {
+    if (!consequent.loc ||
+        !consequent.loc.start ||
+        !consequent.loc.end ||
+        typeof consequent.loc.start.line !== "number" ||
+        typeof consequent.loc.end.line !== "number") {
+        return "";
+    }
+    const lines = sourceCode.lines;
+    const startIndex = consequent.loc.start.line - 1;
+    const endIndex = consequent.loc.end.line - 1;
+    const comments = [];
+    const lastIndex = Math.min(endIndex, lines.length - 1);
+    let i = startIndex + 1;
+    while (i <= lastIndex) {
+        const line = lines[i];
+        if (!line || !line.trim() || !/^\s*(\/\/|\/\*)/.test(line)) {
+            break;
+        }
+        comments.push(line.trim());
+        i++;
+    }
+    return comments.join(" ");
+}
+function gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText) {
+    if (annotationPlacement !== "inside") {
+        return beforeText;
+    }
+    if (!node.consequent || node.consequent.type !== "BlockStatement") {
+        return "";
+    }
+    const consequent = node.consequent;
+    const insideText = tryGetCommentsInsideNode(sourceCode, consequent);
+    if (insideText) {
+        return insideText;
+    }
+    return scanBlockStartComments(sourceCode, consequent);
+}

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

@@ -7,7 +7,7 @@ import type { AnnotationPlacement } from "./branch-annotation-helpers";
  * within ESLint's max-lines-per-function limits.
  *
  * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
- * @supports REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG REQ-INDENTATION-CORRECT
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG REQ-INDENTATION-CORRECT
  */
 type SourceCode = ReturnType<Rule.RuleContext["getSourceCode"]>;
 type IndentHelperContext = {

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

@@ -3,9 +3,15 @@ import { type AnnotationPlacement } from "./branch-annotation-helpers";
 /**
  * Gather annotation text for SwitchCase branches, honoring the configured placement
  * while preserving legacy before-branch behavior in the default mode.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
- * @supports REQ-PLACEMENT-CONFIG
- * @supports REQ-INSIDE-BRACE-PLACEMENT
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT
+ * @param sourceCode - ESLint source code object for accessing line/comment data
+ * @param node - SwitchCase AST node to gather annotations from
+ * @param annotationPlacement - Placement mode ("inside" or "before")
+ * @param beforeText - Pre-gathered text from before the case statement
+ * @returns Combined annotation text based on placement mode and detected annotations
  */
 export declare function gatherSwitchCaseCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, annotationPlacement: AnnotationPlacement, beforeText: string): string;

package/lib/src/utils/branch-annotation-switch-helpers.js

@@ -6,8 +6,8 @@ const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
  * Gather comment text from the first contiguous comment lines "inside" a SwitchCase body.
  * Prefers a BlockStatement consequent when present, with a fallback to the entire case range.
  * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
- * @supports REQ-INSIDE-BRACE-PLACEMENT
- * @supports REQ-PLACEMENT-CONFIG
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 function getInsideSwitchCaseCommentText(sourceCode, node) {
     const lines = sourceCode.lines;
@@ -44,10 +44,16 @@ function getInsideSwitchCaseCommentText(sourceCode, node) {
 /**
  * Gather annotation text for SwitchCase branches, honoring the configured placement
  * while preserving legacy before-branch behavior in the default mode.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
- * @supports REQ-PLACEMENT-CONFIG
- * @supports REQ-INSIDE-BRACE-PLACEMENT
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT
+ * @param sourceCode - ESLint source code object for accessing line/comment data
+ * @param node - SwitchCase AST node to gather annotations from
+ * @param annotationPlacement - Placement mode ("inside" or "before")
+ * @param beforeText - Pre-gathered text from before the case statement
+ * @returns Combined annotation text based on placement mode and detected annotations
  */
 function gatherSwitchCaseCommentText(sourceCode, node, annotationPlacement, beforeText) {
     if (annotationPlacement === "inside") {

package/lib/src/utils/branch-validation.d.ts

@@ -0,0 +1,9 @@
+import type { Rule } from "eslint";
+import type { BranchType } from "./branch-annotation-helpers";
+/**
+ * Validate branchTypes configuration option and return branch types to enforce,
+ * or return an ESLint listener if configuration is invalid.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+ */
+export declare function validateBranchTypes(context: Rule.RuleContext, DEFAULT_BRANCH_TYPES: readonly BranchType[]): BranchType[] | Rule.RuleListener;

package/lib/src/utils/branch-validation.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateBranchTypes = validateBranchTypes;
+/**
+ * Validate branchTypes configuration option and return branch types to enforce,
+ * or return an ESLint listener if configuration is invalid.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+ */
+function validateBranchTypes(context, DEFAULT_BRANCH_TYPES) {
+    const options = context.options[0] || {};
+    /**
+     * Conditional branch checking whether branchTypes option was provided.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-CONDITIONAL - Trace configuration branch existence check
+     */
+    if (Array.isArray(options.branchTypes)) {
+        /**
+         * Predicate to determine whether a provided branch type is invalid.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-FILTER-CALLBACK - Trace filter callback for invalid branch type detection
+         */
+        function isInvalidType(t) {
+            return !DEFAULT_BRANCH_TYPES.includes(t);
+        }
+        const invalidTypes = options.branchTypes.filter(isInvalidType);
+        /**
+         * Conditional branch checking whether any invalid types were found.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-INVALID-DETECTION - Trace handling when invalid types are detected
+         */
+        if (invalidTypes.length > 0) {
+            /**
+             * Program listener produced when configuration is invalid.
+             * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+             * @req REQ-TRACEABILITY-PROGRAM-LISTENER - Trace Program listener reporting invalid config values
+             */
+            function ProgramHandler(node) {
+                /**
+                 * Report a single invalid type for the given Program node.
+                 * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+                 * @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace reporting for each invalid type
+                 */
+                function reportInvalidType(t) {
+                    context.report({
+                        node,
+                        message: `Value "${t}" should be equal to one of the allowed values: ${DEFAULT_BRANCH_TYPES.join(", ")}`,
+                    });
+                }
+                invalidTypes.forEach(reportInvalidType);
+            }
+            return { Program: ProgramHandler };
+        }
+    }
+    return Array.isArray(options.branchTypes)
+        ? options.branchTypes
+        : Array.from(DEFAULT_BRANCH_TYPES);
+}

package/lib/src/utils/comment-text-helpers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Low-level comment text extraction helpers for branch annotation processing.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-COMMENT-ASSOCIATION - Extract and normalize comment text from various comment node types
+ */
+/**
+ * Extract the raw value from a comment node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
+ */
+export declare function extractCommentValue(_c: any): string;
+/**
+ * Extract trimmed comment text for a given source line index or return null
+ * when the line is blank or not a comment. This helper centralizes the
+ * formatter-aware rules used by branch helpers when scanning for contiguous
+ * comment lines around branches.
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
+ */
+export declare function getCommentTextAtLine(lines: string[], index: number): string | null;
+/**
+ * Collect a single contiguous comment line at the given index, appending its
+ * trimmed text to the accumulator. Returns true when a valid comment was
+ * collected and false when scanning should stop (blank or non-comment line).
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
+ */
+export declare function collectCommentLine(lines: string[], index: number, comments: string[]): boolean;

package/lib/src/utils/comment-text-helpers.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Low-level comment text extraction helpers for branch annotation processing.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-COMMENT-ASSOCIATION - Extract and normalize comment text from various comment node types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractCommentValue = extractCommentValue;
+exports.getCommentTextAtLine = getCommentTextAtLine;
+exports.collectCommentLine = collectCommentLine;
+/**
+ * Extract the raw value from a comment node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
+ */
+function extractCommentValue(_c) {
+    return _c.value;
+}
+/**
+ * Extract trimmed comment text for a given source line index or return null
+ * when the line is blank or not a comment. This helper centralizes the
+ * formatter-aware rules used by branch helpers when scanning for contiguous
+ * comment lines around branches.
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
+ */
+function getCommentTextAtLine(lines, index) {
+    const line = lines[index];
+    if (!line || !line.trim()) {
+        return null;
+    }
+    if (!/^\s*(\/\/|\/\*)/.test(line)) {
+        return null;
+    }
+    return line.trim();
+}
+/**
+ * Collect a single contiguous comment line at the given index, appending its
+ * trimmed text to the accumulator. Returns true when a valid comment was
+ * collected and false when scanning should stop (blank or non-comment line).
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
+ */
+function collectCommentLine(lines, index, comments) {
+    const commentText = getCommentTextAtLine(lines, index);
+    if (!commentText) {
+        return false;
+    }
+    comments.push(commentText);
+    return true;
+}

package/lib/src/utils/redundancy-detector.d.ts

@@ -0,0 +1,85 @@
+import type { Rule } from "eslint";
+import { type RedundancyRuleOptions } from "./annotation-scope-analyzer";
+/**
+ * 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
+ */
+export declare function getScopeCommentsFromJSDocAndLeading(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]> | any, scopeNode: any): any[];
+/**
+ * Extract traceability pairs (story-req combinations) from comments
+ * directly attached to the provided scope node.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE
+ */
+export declare function getScopePairs(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, scopeNode: any, parent: any): Set<string>;
+/**
+ * Collect statement's immediate comments (leading, trailing, JSDoc).
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-STATEMENT-SIGNIFICANCE REQ-SAFE-REMOVAL
+ */
+export declare function getStatementComments(context: Rule.RuleContext, node: any): any[];
+/**
+ * Debug log scope pairs when TRACEABILITY_DEBUG is enabled.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS
+ */
+export declare function debugScopePairs(scopeNode: any, scopePairs: Set<string>): void;
+/**
+ * Recursively collect traceability pairs from the given scope node and
+ * its ancestors up to maxDepth levels.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-INHERITANCE REQ-CONFIGURABLE-STRICTNESS
+ */
+export declare function collectScopePairs(context: Rule.RuleContext, scopeNode: any, maxDepth: number): Set<string>;
+/**
+ * Gather pairs and comments from a statement for redundancy checking.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-STATEMENT-SIGNIFICANCE REQ-CONFIGURABLE-STRICTNESS REQ-DIFFERENT-REQUIREMENTS
+ */
+export declare function getStatementPairsForRedundancy(context: Rule.RuleContext, stmt: any, scopePairs: Set<string>, options: RedundancyRuleOptions): {
+    comments: any[];
+    pairs: Set<string>;
+} | null;
+/**
+ * Determine whether statement pairs are redundant within scope pairs
+ * according to configured options.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-CONFIGURABLE-STRICTNESS
+ */
+export declare function isStatementRedundantWithinScope(stmtPairs: Set<string>, scopePairs: Set<string>, options: RedundancyRuleOptions): boolean;
+/**
+ * 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
+ */
+export declare function getAnnotationCommentsFromStatement(comments: any[]): any[];
+/**
+ * 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
+ */
+export declare function getRedundantStatementContext(context: Rule.RuleContext, stmt: any, scopePairs: Set<string>, options: RedundancyRuleOptions): {
+    comments: any[];
+} | null;
+/**
+ * Compute unique removal ranges for the given annotation comments.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SAFE-REMOVAL
+ */
+export declare function getRemovalRangesForAnnotationComments(comments: any[], sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>): [number, number][];
+/**
+ * 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
+ */
+export declare function reportRedundantAnnotationsInBlock(context: Rule.RuleContext, blockNode: any, scopePairs: Set<string>, options: RedundancyRuleOptions): void;

package/lib/src/utils/redundancy-detector.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getScopeCommentsFromJSDocAndLeading = getScopeCommentsFromJSDocAndLeading;
+exports.getScopePairs = getScopePairs;
+exports.getStatementComments = getStatementComments;
+exports.debugScopePairs = debugScopePairs;
+exports.collectScopePairs = collectScopePairs;
+exports.getStatementPairsForRedundancy = getStatementPairsForRedundancy;
+exports.isStatementRedundantWithinScope = isStatementRedundantWithinScope;
+exports.getAnnotationCommentsFromStatement = getAnnotationCommentsFromStatement;
+exports.getRedundantStatementContext = getRedundantStatementContext;
+exports.getRemovalRangesForAnnotationComments = getRemovalRangesForAnnotationComments;
+exports.reportRedundantAnnotationsInBlock = reportRedundantAnnotationsInBlock;
+const annotation_scope_analyzer_1 = require("./annotation-scope-analyzer");
+const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
+/**
+ * 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;
+}
+/**
+ * Extract traceability pairs (story-req combinations) from comments
+ * directly attached to the provided scope node.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE
+ */
+function getScopePairs(sourceCode, scopeNode, parent) {
+    if (branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES.includes(scopeNode.type)) {
+        const commentText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent, "before");
+        return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(commentText);
+    }
+    const directComments = getScopeCommentsFromJSDocAndLeading(sourceCode, scopeNode);
+    if (directComments.length === 0) {
+        return new Set();
+    }
+    return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(directComments);
+}
+/**
+ * Collect statement's immediate comments (leading, trailing, JSDoc).
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-STATEMENT-SIGNIFICANCE REQ-SAFE-REMOVAL
+ */
+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);
+    }
+    const jsdoc = sourceCode.getJSDocComment
+        ? sourceCode.getJSDocComment(node)
+        : null;
+    if (jsdoc) {
+        comments.push(jsdoc);
+    }
+    return comments;
+}
+/**
+ * Debug log scope pairs when TRACEABILITY_DEBUG is enabled.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS
+ */
+function debugScopePairs(scopeNode, scopePairs) {
+    if (process.env.TRACEABILITY_DEBUG === "1") {
+        console.log("[no-redundant-annotation] Scope %s has %d pairs: %s", scopeNode && scopeNode.type, scopePairs.size, Array.from(scopePairs)
+            .map((p) => `"${p}"`)
+            .join(", "));
+    }
+}
+/**
+ * Recursively collect traceability pairs from the given scope node and
+ * its ancestors up to maxDepth levels.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-INHERITANCE REQ-CONFIGURABLE-STRICTNESS
+ */
+function collectScopePairs(context, scopeNode, maxDepth) {
+    const allPairs = new Set();
+    let currentNode = scopeNode;
+    let depth = 0;
+    while (currentNode && depth < maxDepth) {
+        const parent = currentNode.parent;
+        const nodePairs = getScopePairs(context.getSourceCode(), currentNode, parent);
+        nodePairs.forEach((pair) => allPairs.add(pair));
+        if (allPairs.size > 0 && depth > 0) {
+            break;
+        }
+        currentNode = parent;
+        depth++;
+    }
+    return allPairs;
+}
+/**
+ * Gather pairs and comments from a statement for redundancy checking.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-STATEMENT-SIGNIFICANCE REQ-CONFIGURABLE-STRICTNESS REQ-DIFFERENT-REQUIREMENTS
+ */
+function getStatementPairsForRedundancy(context, stmt, scopePairs, options) {
+    if (!(0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(stmt, options, branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES)) {
+        return null;
+    }
+    const comments = getStatementComments(context, stmt);
+    if (comments.length === 0) {
+        return null;
+    }
+    const pairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(comments);
+    if (process.env.TRACEABILITY_DEBUG === "1") {
+        console.log("[no-redundant-annotation] Statement %s has %d pairs: %s (scope has %d)", stmt.type, pairs.size, Array.from(pairs)
+            .map((p) => `"${p}"`)
+            .join(", "), scopePairs.size);
+    }
+    if (pairs.size === 0) {
+        return null;
+    }
+    return { comments, pairs };
+}
+/**
+ * Determine whether statement pairs are redundant within scope pairs
+ * according to configured options.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS 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]));
+            },
+        });
+    }
+}

package/lib/tests/maintenance/storyParser.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for storyParser module
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-DEEP-PARSE - Test parsing story file content to identify available requirements
+ * @req REQ-DEEP-FORMAT - Test finding requirement IDs in multiple markdown contexts
+ * @req REQ-DEEP-SECTION - Test handling requirements in different story file sections
+ */
+export {};