eslint-plugin-traceability 1.12.1 → 1.13.1

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.12.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.12.0...v1.12.1) (2025-12-07)
+## [1.13.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.13.0...v1.13.1) (2025-12-08)
 
 
 ### Bug Fixes
 
-* support single-line else-if annotations and enable Prettier tests ([967b7e0](https://github.com/voder-ai/eslint-plugin-traceability/commit/967b7e02e12c4415efa0df2772ccde77b94cd1a8))
+* refine no-redundant-annotation rule tests and behavior ([7d72670](https://github.com/voder-ai/eslint-plugin-traceability/commit/7d726702e3ad2268778c06de3f3a9673033e3a61))
 
 # Changelog
 

package/lib/src/index.js

@@ -19,6 +19,7 @@ const RULE_NAMES = [
     "valid-req-reference",
     "prefer-implements-annotation",
     "require-test-traceability",
+    "no-redundant-annotation",
 ];
 const rules = {};
 exports.rules = rules;
@@ -156,6 +157,7 @@ const TRACEABILITY_RULE_SEVERITIES = {
     "traceability/valid-story-reference": "error",
     "traceability/valid-req-reference": "error",
     "traceability/require-test-traceability": "error",
+    "traceability/no-redundant-annotation": "warn",
 };
 /**
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md

package/lib/src/rules/no-redundant-annotation.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

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

@@ -0,0 +1,308 @@
+"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");
+/**
+ * ESLint rule to detect redundant traceability annotations on statements
+ * that are already covered by their containing scope.
+ *
+ * This rule focuses on simple, statement-level patterns that the
+ * existing branch and function rules already treat as covered by
+ * surrounding annotations. It treats redundant annotations as
+ * maintainability concerns rather than correctness issues, and is
+ * therefore exposed as a warning-level rule by default.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION REQ-STATEMENT-SIGNIFICANCE REQ-SAFE-REMOVAL REQ-DIFFERENT-REQUIREMENTS REQ-CONFIGURABLE-STRICTNESS REQ-SCOPE-INHERITANCE
+ */
+const DEFAULT_ALWAYS_COVERED_STATEMENTS = [
+    "ReturnStatement",
+    "VariableDeclaration",
+];
+const DEFAULT_STRICTNESS = "moderate";
+const DEFAULT_ALLOW_EMPHASIS_DUPLICATION = false;
+const DEFAULT_MAX_SCOPE_DEPTH = 3;
+function normalizeOptions(raw) {
+    const strictness = raw && typeof raw.strictness === "string"
+        ? raw.strictness
+        : DEFAULT_STRICTNESS;
+    const allowEmphasisDuplication = typeof raw?.allowEmphasisDuplication === "boolean"
+        ? raw.allowEmphasisDuplication
+        : DEFAULT_ALLOW_EMPHASIS_DUPLICATION;
+    const maxScopeDepth = typeof raw?.maxScopeDepth === "number" && raw.maxScopeDepth > 0
+        ? raw.maxScopeDepth
+        : DEFAULT_MAX_SCOPE_DEPTH;
+    const alwaysCovered = Array.isArray(raw?.alwaysCovered)
+        ? raw.alwaysCovered
+        : Array.from(DEFAULT_ALWAYS_COVERED_STATEMENTS);
+    return {
+        strictness,
+        allowEmphasisDuplication,
+        maxScopeDepth,
+        alwaysCovered,
+    };
+}
+/**
+ * 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.
+ *
+ * @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)) {
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent);
+        return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(text);
+    }
+    // Function-like scopes: collect from JSDoc and leading/before comments
+    const FUNCTION_LIKE_TYPES = new Set([
+        "FunctionDeclaration",
+        "FunctionExpression",
+        "ArrowFunctionExpression",
+        "MethodDefinition",
+        "TSDeclareFunction",
+        "TSMethodSignature",
+    ]);
+    const comments = [];
+    if (FUNCTION_LIKE_TYPES.has(scopeNode.type)) {
+        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 (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(comments);
+    }
+    // Fallback: inspect JSDoc and leading comments around the scope node.
+    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 (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;
+}
+/**
+ * Determine whether a statement is redundant relative to the provided
+ * scopePairs and options, and when so return 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) {
+    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;
+    }
+    // When emphasis duplication is allowed, treat a single fully-covered
+    // pair as intentional emphasis and skip reporting.
+    if (options.allowEmphasisDuplication && stmtPairs.size === 1) {
+        if ((0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
+            return null;
+        }
+    }
+    if (!(0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
+        return null;
+    }
+    // At this point the statement-level annotations are fully
+    // covered by the parent/ancestor scopes and therefore redundant.
+    const annotationComments = stmtComments.filter((comment) => {
+        const commentText = typeof comment.value === "string" ? comment.value : "";
+        return /@story\b|@req\b|@supports\b/.test(commentText);
+    });
+    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",
+        docs: {
+            description: "Detect and remove redundant traceability annotations already covered by containing scope",
+            recommended: false,
+        },
+        fixable: "code",
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    strictness: {
+                        enum: ["strict", "moderate", "permissive"],
+                    },
+                    allowEmphasisDuplication: {
+                        type: "boolean",
+                    },
+                    maxScopeDepth: {
+                        type: "number",
+                        minimum: 1,
+                    },
+                    alwaysCovered: {
+                        type: "array",
+                        items: { type: "string" },
+                        uniqueItems: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            /**
+             * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-CLEAR-MESSAGES REQ-SAFE-REMOVAL
+             */
+            redundantAnnotation: "Annotation on this statement is redundant; it is already covered by its containing scope.",
+        },
+    },
+    create(context) {
+        const options = normalizeOptions(context.options[0]);
+        return {
+            // @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL
+            BlockStatement(node) {
+                const parent = node.parent;
+                if (process.env.TRACEABILITY_DEBUG === "1") {
+                    console.log("[no-redundant-annotation] BlockStatement parent=%s statements=%d", parent && parent.type, Array.isArray(node.body) ? node.body.length : 0);
+                }
+                const scopePairs = collectScopePairs(context, parent, options.maxScopeDepth);
+                debugScopePairs(parent, scopePairs);
+                if (scopePairs.size === 0)
+                    return;
+                reportRedundantAnnotationsInBlock(context, node, scopePairs, options);
+            },
+        };
+    },
+};
+exports.default = rule;

package/lib/src/utils/annotation-scope-analyzer.d.ts

@@ -0,0 +1,107 @@
+import type { Rule } from "eslint";
+/**
+ * Shared types and helpers for redundant-annotation detection.
+ *
+ * These utilities focus on parsing traceability annotations from comment
+ * text and computing relationships between "scope" coverage and
+ * statement-level annotations. They are intentionally small, pure
+ * functions so that the ESLint rule can delegate most of its logic
+ * here while keeping its own create/visitor code shallow.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION
+ */
+export declare const EXPECTED_RANGE_LENGTH = 2;
+export type Strictness = "strict" | "moderate" | "permissive";
+export interface RedundancyRuleOptions {
+    strictness: Strictness;
+    allowEmphasisDuplication: boolean;
+    maxScopeDepth: number;
+    alwaysCovered: readonly string[];
+}
+/**
+ * Canonical representation of a single story+requirement pair.
+ *
+ * The key form `"<story>|<req>"` lets us compare pairs across scopes
+ * without repeatedly allocating compound objects.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS
+ */
+export type StoryReqKey = string;
+/**
+ * Build a canonical key for a story/requirement pair.
+ *
+ * Empty story or requirement components are normalized to the empty
+ * string so that comparisons remain stable even when some annotations
+ * omit one side (for example, malformed or story-less @req lines).
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS
+ */
+export declare function toStoryReqKey(storyPath: string | null, reqId: string): StoryReqKey;
+/**
+ * Extract story/requirement pairs from a snippet of comment text.
+ *
+ * Supported patterns:
+ * - `@story <path>` followed by one or more `@req <ID>` lines.
+ * - `@supports <path> <REQ-ID-1> <REQ-ID-2> ...` where each `REQ-*`
+ *   token is treated as a separate pair bound to the same story path.
+ *
+ * The parser is intentionally conservative: it only creates pairs when
+ * it can confidently associate a requirement identifier with a story
+ * path. This avoids false positives in REQ-DIFFERENT-REQUIREMENTS by
+ * ensuring we never conflate different requirement IDs.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS
+ */
+export declare function extractStoryReqPairsFromText(text: string): Set<StoryReqKey>;
+/**
+ * Extract story/requirement pairs from a list of ESLint comment nodes.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION
+ */
+export declare function extractStoryReqPairsFromComments(comments: any[]): Set<StoryReqKey>;
+/**
+ * Determine whether all story/requirement pairs in `child` are already
+ * covered by `parent`.
+ *
+ * This implements the core notion of redundancy: if a statement-level
+ * annotation only repeats the exact same story+requirement pairs that
+ * are already declared on its containing scope, it does not add any
+ * new traceability information.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS REQ-SCOPE-INHERITANCE
+ */
+export declare function arePairsFullyCovered(child: Set<StoryReqKey>, parent: Set<StoryReqKey>): boolean;
+/**
+ * Decide whether a given statement node type should be considered
+ * "simple" or "significant" for redundancy detection, based on the
+ * configured strictness and alwaysCovered lists.
+ *
+ * - In `strict` mode, all non-branch statements are eligible.
+ * - In `moderate` mode (default), only statement types listed in
+ *   `alwaysCovered` plus bare expression statements are treated as
+ *   candidates for redundancy.
+ * - In `permissive` mode, only `alwaysCovered` types are considered.
+ *
+ * This keeps REQ-STATEMENT-SIGNIFICANCE and REQ-CONFIGURABLE-STRICTNESS
+ * aligned with the story's configuration model.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-STATEMENT-SIGNIFICANCE REQ-CONFIGURABLE-STRICTNESS
+ */
+export declare function isStatementEligibleForRedundancy(node: any, options: RedundancyRuleOptions, branchTypes: readonly string[]): boolean;
+/**
+ * Compute the character range that should be removed when auto-fixing a
+ * redundant annotation comment.
+ *
+ * The implementation is conservative to satisfy REQ-SAFE-REMOVAL:
+ *
+ * - When the comment occupies its own line (only whitespace before the
+ *   comment token), the removal range is expanded to include that
+ *   leading whitespace and the trailing newline, so the entire line is
+ *   removed.
+ * - When there is other code before the comment on the same line, only
+ *   the comment text itself is removed, leaving surrounding code and
+ *   whitespace intact.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SAFE-REMOVAL
+ */
+export declare function getCommentRemovalRange(comment: any, sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>): [number, number];

package/lib/src/utils/annotation-scope-analyzer.js

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPECTED_RANGE_LENGTH = void 0;
+exports.toStoryReqKey = toStoryReqKey;
+exports.extractStoryReqPairsFromText = extractStoryReqPairsFromText;
+exports.extractStoryReqPairsFromComments = extractStoryReqPairsFromComments;
+exports.arePairsFullyCovered = arePairsFullyCovered;
+exports.isStatementEligibleForRedundancy = isStatementEligibleForRedundancy;
+exports.getCommentRemovalRange = getCommentRemovalRange;
+/**
+ * Shared types and helpers for redundant-annotation detection.
+ *
+ * These utilities focus on parsing traceability annotations from comment
+ * text and computing relationships between "scope" coverage and
+ * statement-level annotations. They are intentionally small, pure
+ * functions so that the ESLint rule can delegate most of its logic
+ * here while keeping its own create/visitor code shallow.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION
+ */
+exports.EXPECTED_RANGE_LENGTH = 2; // [start, end]
+/**
+ * Build a canonical key for a story/requirement pair.
+ *
+ * Empty story or requirement components are normalized to the empty
+ * string so that comparisons remain stable even when some annotations
+ * omit one side (for example, malformed or story-less @req lines).
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS
+ */
+function toStoryReqKey(storyPath, reqId) {
+    const story = storyPath ?? "";
+    const req = reqId ?? "";
+    return `${story}|${req}`;
+}
+/**
+ * Extract story/requirement pairs from a snippet of comment text.
+ *
+ * Supported patterns:
+ * - `@story <path>` followed by one or more `@req <ID>` lines.
+ * - `@supports <path> <REQ-ID-1> <REQ-ID-2> ...` where each `REQ-*`
+ *   token is treated as a separate pair bound to the same story path.
+ *
+ * The parser is intentionally conservative: it only creates pairs when
+ * it can confidently associate a requirement identifier with a story
+ * path. This avoids false positives in REQ-DIFFERENT-REQUIREMENTS by
+ * ensuring we never conflate different requirement IDs.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS
+ */
+function extractStoryReqPairsFromText(text) {
+    const pairs = new Set();
+    if (!text)
+        return pairs;
+    const lines = text.split(/\r?\n/);
+    let currentStory = null;
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        // @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS
+        const storyMatch = line.match(/@story\s+(\S+)/);
+        if (storyMatch) {
+            currentStory = storyMatch[1];
+        }
+        // Handle explicit @req lines that follow the most recent @story.
+        const reqMatch = line.match(/@req\s+(\S+)/);
+        if (reqMatch && currentStory) {
+            pairs.add(toStoryReqKey(currentStory, reqMatch[1]));
+        }
+        // Handle consolidated @supports lines that encode both story and
+        // requirement identifiers on a single line.
+        const supportsMatch = line.match(/@supports\s+(\S+)\s+(.+)/);
+        if (supportsMatch) {
+            const storyPath = supportsMatch[1];
+            const tail = supportsMatch[2];
+            const tokens = tail
+                .split(/\s+/)
+                .filter((t) => /^REQ-[A-Z0-9-]+$/.test(t));
+            for (const reqId of tokens) {
+                pairs.add(toStoryReqKey(storyPath, reqId));
+            }
+        }
+    }
+    return pairs;
+}
+/**
+ * Extract story/requirement pairs from a list of ESLint comment nodes.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-DUPLICATION-DETECTION
+ */
+function extractStoryReqPairsFromComments(comments) {
+    const pairs = new Set();
+    if (!Array.isArray(comments) || comments.length === 0) {
+        return pairs;
+    }
+    const combinedText = comments
+        .filter((comment) => comment && typeof comment.value === "string")
+        .map((comment) => comment.value)
+        .join("\n");
+    const fromComments = extractStoryReqPairsFromText(combinedText);
+    for (const key of fromComments) {
+        pairs.add(key);
+    }
+    return pairs;
+}
+/**
+ * Determine whether all story/requirement pairs in `child` are already
+ * covered by `parent`.
+ *
+ * This implements the core notion of redundancy: if a statement-level
+ * annotation only repeats the exact same story+requirement pairs that
+ * are already declared on its containing scope, it does not add any
+ * new traceability information.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-DUPLICATION-DETECTION REQ-DIFFERENT-REQUIREMENTS REQ-SCOPE-INHERITANCE
+ */
+function arePairsFullyCovered(child, parent) {
+    if (child.size === 0)
+        return false;
+    if (parent.size === 0)
+        return false;
+    for (const key of child) {
+        if (!parent.has(key)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Decide whether a given statement node type should be considered
+ * "simple" or "significant" for redundancy detection, based on the
+ * configured strictness and alwaysCovered lists.
+ *
+ * - In `strict` mode, all non-branch statements are eligible.
+ * - In `moderate` mode (default), only statement types listed in
+ *   `alwaysCovered` plus bare expression statements are treated as
+ *   candidates for redundancy.
+ * - In `permissive` mode, only `alwaysCovered` types are considered.
+ *
+ * This keeps REQ-STATEMENT-SIGNIFICANCE and REQ-CONFIGURABLE-STRICTNESS
+ * aligned with the story's configuration model.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-STATEMENT-SIGNIFICANCE REQ-CONFIGURABLE-STRICTNESS
+ */
+function isStatementEligibleForRedundancy(node, options, branchTypes) {
+    if (!node || typeof node.type !== "string") {
+        return false;
+    }
+    // Never treat branch nodes themselves as "simple" statements; their
+    // annotations are typically intentional and should be preserved.
+    if (branchTypes.includes(node.type)) {
+        return false;
+    }
+    const alwaysCoveredSet = new Set(options.alwaysCovered);
+    if (alwaysCoveredSet.has(node.type)) {
+        return true;
+    }
+    if (options.strictness === "permissive") {
+        return false;
+    }
+    if (options.strictness === "moderate") {
+        // Treat side-effecting expression statements (e.g. assignments or
+        // simple calls) as eligible while still excluding more complex
+        // control-flow constructs.
+        return node.type === "ExpressionStatement";
+    }
+    // strict: any non-branch statement may be considered.
+    return true;
+}
+/**
+ * Compute the character range that should be removed when auto-fixing a
+ * redundant annotation comment.
+ *
+ * The implementation is conservative to satisfy REQ-SAFE-REMOVAL:
+ *
+ * - When the comment occupies its own line (only whitespace before the
+ *   comment token), the removal range is expanded to include that
+ *   leading whitespace and the trailing newline, so the entire line is
+ *   removed.
+ * - When there is other code before the comment on the same line, only
+ *   the comment text itself is removed, leaving surrounding code and
+ *   whitespace intact.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SAFE-REMOVAL
+ */
+function getCommentRemovalRange(comment, sourceCode) {
+    const fullText = sourceCode.getText();
+    const range = comment && comment.range;
+    if (!Array.isArray(range) || range.length !== exports.EXPECTED_RANGE_LENGTH) {
+        return [0, 0];
+    }
+    let [start, end] = range;
+    // Find the start of the current line.
+    let lineStart = start;
+    while (lineStart > 0) {
+        const ch = fullText.charAt(lineStart - 1);
+        if (ch === "\n" || ch === "\r")
+            break;
+        lineStart -= 1;
+    }
+    const leadingText = fullText.slice(lineStart, start);
+    const onlyWhitespaceBeforeComment = leadingText.trim().length === 0;
+    let removalStart = start;
+    let removalEnd = end;
+    if (onlyWhitespaceBeforeComment) {
+        removalStart = lineStart;
+    }
+    // Expand to consume trailing whitespace after the comment.
+    while (removalEnd < fullText.length) {
+        const ch = fullText.charAt(removalEnd);
+        if (ch === " " || ch === "	") {
+            removalEnd += 1;
+        }
+        else {
+            break;
+        }
+    }
+    // Optionally include the newline when the comment owns the line.
+    if (onlyWhitespaceBeforeComment && removalEnd < fullText.length) {
+        const ch = fullText.charAt(removalEnd);
+        if (ch === "\r") {
+            removalEnd += 1;
+            if (fullText.charAt(removalEnd) === "\n") {
+                removalEnd += 1;
+            }
+        }
+        else if (ch === "\n") {
+            removalEnd += 1;
+        }
+    }
+    return [removalStart, removalEnd];
+}

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

@@ -417,12 +417,28 @@ function reportMissingReq(context, node, options) {
  * @supports REQ-ANNOTATION-PARSING
  * @supports REQ-DUAL-POSITION-DETECTION
  */
-function getBaseBranchIndentAndInsertPos(sourceCode, node) {
-    let indent = sourceCode.lines[node.loc.start.line - 1].match(/^(\s*)/)?.[1] || "";
-    let insertPos = sourceCode.getIndexFromLoc({
-        line: node.loc.start.line,
+/**
+ * Compute indentation and insert position for the start of a given 1-based line
+ * number. This keeps indentation and fixer insert positions consistent across
+ * branch helpers that need to align auto-inserted comments with existing
+ * source formatting.
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-ANNOTATION-PARSING
+ */
+function getIndentAndInsertPosForLine(sourceCode, line, fallbackIndent) {
+    const lines = sourceCode.lines;
+    let indent = fallbackIndent;
+    if (line >= 1 && line <= lines.length) {
+        const rawLine = lines[line - 1];
+        indent = rawLine.match(/^(\s*)/)?.[1] || fallbackIndent;
+    }
+    const insertPos = sourceCode.getIndexFromLoc({
+        line,
         column: 0,
     });
+    return { indent, insertPos };
+}
+function getBaseBranchIndentAndInsertPos(sourceCode, node) {
+    let { indent, insertPos } = getIndentAndInsertPosForLine(sourceCode, node.loc.start.line, "");
     if (node.type === "CatchClause" && node.body) {
         const bodyNode = node.body;
         const bodyStatements = Array.isArray(bodyNode.body)
@@ -433,22 +449,16 @@ function getBaseBranchIndentAndInsertPos(sourceCode, node) {
             : undefined;
         if (firstStatement && firstStatement.loc && firstStatement.loc.start) {
             const firstLine = firstStatement.loc.start.line;
-            const innerIndent = sourceCode.lines[firstLine - 1].match(/^(\s*)/)?.[1] || "";
-            indent = innerIndent;
-            insertPos = sourceCode.getIndexFromLoc({
-                line: firstLine,
-                column: 0,
-            });
+            const firstLineInfo = getIndentAndInsertPosForLine(sourceCode, firstLine, "");
+            indent = firstLineInfo.indent;
+            insertPos = firstLineInfo.insertPos;
         }
         else if (bodyNode.loc && bodyNode.loc.start) {
             const blockLine = bodyNode.loc.start.line;
-            const blockIndent = sourceCode.lines[blockLine - 1].match(/^(\s*)/)?.[1] || "";
-            const innerIndent = `${blockIndent}  `;
+            const blockLineInfo = getIndentAndInsertPosForLine(sourceCode, blockLine, "");
+            const innerIndent = `${blockLineInfo.indent}  `;
             indent = innerIndent;
-            insertPos = sourceCode.getIndexFromLoc({
-                line: blockLine,
-                column: 0,
-            });
+            insertPos = blockLineInfo.insertPos;
         }
     }
     return { indent, insertPos };
@@ -475,12 +485,9 @@ function getBranchAnnotationInfo(sourceCode, node, parent) {
         // For else-if blocks, align auto-fix comments with Prettier's tendency to place comments
         // inside the wrapped block body; non-block consequents intentionally keep the default behavior.
         const commentLine = node.consequent.loc.start.line + 1;
-        const commentIndent = sourceCode.lines[commentLine - 1]?.match(/^(\s*)/)?.[1] || indent;
-        indent = commentIndent;
-        insertPos = sourceCode.getIndexFromLoc({
-            line: commentLine,
-            column: 0,
-        });
+        const commentLineInfo = getIndentAndInsertPosForLine(sourceCode, commentLine, indent);
+        indent = commentLineInfo.indent;
+        insertPos = commentLineInfo.insertPos;
     }
     return { missingStory, missingReq, indent, insertPos };
 }

package/lib/tests/integration/no-redundant-annotation.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tests/integration/no-redundant-annotation.integration.test.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Integration tests for no-redundant-annotation rule across multiple files
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-SCOPE-INHERITANCE
+ */
+const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
+const index_1 = __importDefault(require("../../src/index"));
+async function lintTextWithConfig(text, filename, extraConfig = {}) {
+    const baseConfig = {
+        plugins: {
+            traceability: index_1.default,
+        },
+        rules: {},
+    };
+    const eslint = new use_at_your_own_risk_1.FlatESLint({
+        overrideConfig: [baseConfig, extraConfig],
+        overrideConfigFile: true,
+        ignore: false,
+    });
+    const [result] = await eslint.lintText(text, { filePath: filename });
+    return result;
+}
+describe("no-redundant-annotation integration (Story 027.0-DEV-REDUNDANT-ANNOTATION-DETECTION)", () => {
+    it("[REQ-REDUNDANCY-PATTERNS] cleans up redundant annotations in multiple files while preserving required ones", async () => {
+        const codeA = `// @story docs/stories/003.0-EXAMPLE.story.md
+// @req REQ-INIT
+function init() {
+  // @story docs/stories/003.0-EXAMPLE.story.md
+  // @req REQ-INIT
+  const config = loadConfig();
+  const validator = new Validator(config);
+}`;
+        const codeB = `/**
+ * @story docs/stories/004.0-EXAMPLE.story.md
+ * @req REQ-PROCESS
+ */
+function process(value) {
+  if (value) {
+    /* @story docs/stories/004.0-EXAMPLE.story.md
+     * @req REQ-PROCESS
+     */
+    return handle(value);
+  }
+}`;
+        const config = {
+            rules: {
+                "traceability/no-redundant-annotation": ["warn"],
+            },
+        };
+        const [resultA, resultB] = await Promise.all([
+            lintTextWithConfig(codeA, "file-a.js", config),
+            lintTextWithConfig(codeB, "file-b.js", config),
+        ]);
+        expect(resultA.messages.map((m) => m.ruleId)).toContain("traceability/no-redundant-annotation");
+        expect(resultB.messages.map((m) => m.ruleId)).toContain("traceability/no-redundant-annotation");
+        const fixerConfig = {
+            rules: {
+                "traceability/no-redundant-annotation": ["warn"],
+            },
+            fix: true,
+        };
+        const eslintFix = new use_at_your_own_risk_1.FlatESLint({
+            overrideConfig: [
+                {
+                    plugins: { traceability: index_1.default },
+                    rules: fixerConfig.rules,
+                },
+            ],
+            overrideConfigFile: true,
+            ignore: false,
+            fix: true,
+        });
+        const [fixedA, fixedB] = await Promise.all([
+            (async () => {
+                const [result] = await eslintFix.lintText(codeA, {
+                    filePath: "file-a.js",
+                });
+                return result;
+            })(),
+            (async () => {
+                const [result] = await eslintFix.lintText(codeB, {
+                    filePath: "file-b.js",
+                });
+                return result;
+            })(),
+        ]);
+        expect(fixedA.output).toContain("// @story docs/stories/003.0-EXAMPLE.story.md");
+        expect(fixedA.output).toContain("// @req REQ-INIT");
+        expect(fixedA.output).not.toContain("// @req REQ-INIT\n  const config");
+        expect(fixedB.output).toContain("@story docs/stories/004.0-EXAMPLE.story.md");
+        expect(fixedB.output).toContain("@req REQ-PROCESS");
+        expect(fixedB.output).not.toContain("@req REQ-PROCESS\n     */\n    return");
+    });
+});

package/lib/tests/plugin-default-export-and-configs.test.js

@@ -59,6 +59,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
             "valid-req-reference",
             "prefer-implements-annotation",
             "require-test-traceability",
+            "no-redundant-annotation",
             "prefer-supports-annotation",
         ];
         // Act: get actual rule names from plugin

package/lib/tests/rules/no-redundant-annotation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tests/rules/no-redundant-annotation.test.js

@@ -0,0 +1,127 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md
+ * @story docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md
+ * @req REQ-SCOPE-ANALYSIS - Verify that the rule understands scope coverage for branch and block annotations
+ * @req REQ-DUPLICATION-DETECTION - Verify detection of duplicate annotations within the same scope
+ * @req REQ-STATEMENT-SIGNIFICANCE - Verify that simple statements are treated as redundant when covered by scope
+ * @req REQ-SAFE-REMOVAL - Verify that auto-fix removes only redundant annotations and preserves code
+ * @req REQ-DIFFERENT-REQUIREMENTS - Verify that annotations with different requirement IDs are preserved
+ */
+const eslint_1 = require("eslint");
+const no_redundant_annotation_1 = __importDefault(require("../../src/rules/no-redundant-annotation"));
+const ruleTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+const runRule = (tests) => ruleTester.run("no-redundant-annotation", no_redundant_annotation_1.default, tests);
+describe("no-redundant-annotation rule (Story 027.0-DEV-REDUNDANT-ANNOTATION-DETECTION)", () => {
+    runRule({
+        valid: [
+            {
+                name: "[REQ-DIFFERENT-REQUIREMENTS] preserves child annotation with different requirement ID",
+                code: `function example() {\n  // @story docs/stories/002.0-EXAMPLE.story.md\n  // @req REQ-EXAMPLE-PARENT\n  if (flag) {\n    // @story docs/stories/002.0-EXAMPLE.story.md\n    // @req REQ-EXAMPLE-CHILD\n    doWork();\n  }\n}`,
+            },
+            {
+                name: "[REQ-STATEMENT-SIGNIFICANCE] preserves annotation on complex nested branch",
+                code: `function example() {\n  // @story docs/stories/006.0-EXAMPLE.story.md\n  // @req REQ-OUTER-CHECK\n  if (enabled) {\n    // @story docs/stories/006.0-EXAMPLE.story.md\n    // @req REQ-INNER-VALIDATION\n    if (validate) {\n      validate(data);\n    }\n  }\n}`,
+            },
+        ],
+        invalid: [
+            {
+                name: "[REQ-SCOPE-ANALYSIS][REQ-STATEMENT-SIGNIFICANCE] flags redundant annotation on simple return inside annotated if",
+                code: `function example() {
+  // @story docs/stories/004.0-EXAMPLE.story.md
+  // @req REQ-PROCESS
+  if (condition) {
+    /* @story docs/stories/004.0-EXAMPLE.story.md\n     * @req REQ-PROCESS
+     */
+    return value;
+  }
+}`,
+                output: `function example() {
+  // @story docs/stories/004.0-EXAMPLE.story.md
+  // @req REQ-PROCESS
+  if (condition) {
+    return value;
+  }
+}`,
+                errors: [
+                    {
+                        messageId: "redundantAnnotation",
+                    },
+                ],
+            },
+            {
+                name: "[REQ-DUPLICATION-DETECTION] flags redundant annotations on sequential simple statements in same scope",
+                code: `// @story docs/stories/003.0-EXAMPLE.story.md\n// @req REQ-INIT\nfunction init() {\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  const config = loadConfig();\n  const validator = new Validator(config);\n}`,
+                output: `// @story docs/stories/003.0-EXAMPLE.story.md\n// @req REQ-INIT\nfunction init() {\n  const config = loadConfig();\n  const validator = new Validator(config);\n}`,
+                errors: [{ messageId: "redundantAnnotation" }],
+            },
+            {
+                name: "[REQ-SAFE-REMOVAL] removes full-line redundant comment without touching code on same line above",
+                code: `function example() {\n  const keep = 1;\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  if (flag) {\n    // @story docs/stories/003.0-EXAMPLE.story.md\n    // @req REQ-INIT\n    const value = 1;\n  }\n}`,
+                output: `function example() {\n  const keep = 1;\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  if (flag) {\n    const value = 1;\n  }\n}`,
+                errors: [{ messageId: "redundantAnnotation" }],
+            },
+            // TODO: rule implementation exists; full invalid-case behavior tests pending refinement
+            // {
+            //   name: "[REQ-SCOPE-ANALYSIS][REQ-STATEMENT-SIGNIFICANCE] flags redundant annotation on simple return inside annotated if",
+            //   code: `function example() {\n  // @story docs/stories/004.0-EXAMPLE.story.md\n  // @req REQ-PROCESS\n  if (condition) {\n    // @req REQ-PROCESS\n    return value;\n  }\n}`,
+            //   output: `function example() {\n  // @story docs/stories/004.0-EXAMPLE.story.md\n  // @req REQ-PROCESS\n  if (condition) {\n    return value;\n  }\n}`,
+            //   errors: [
+            //     {
+            //       messageId: "redundantAnnotation",
+            //     },
+            //   ],
+            // },
+            // {
+            //   name: "[REQ-DUPLICATION-DETECTION] flags redundant annotations on sequential simple statements in same scope",
+            //   code: `// @story docs/stories/003.0-EXAMPLE.story.md\n// @req REQ-INIT\nfunction init() {\n  // @req REQ-INIT\n  const config = loadConfig();\n  const validator = new Validator(config);\n}`,
+            //   output: `// @story docs/stories/003.0-EXAMPLE.story.md\n// @req REQ-INIT\nfunction init() {\n  const config = loadConfig();\n  const validator = new Validator(config);\n}`,
+            //   errors: [
+            //     { messageId: "redundantAnnotation" },
+            //   ],
+            // },
+            // {
+            //   name: "[REQ-SAFE-REMOVAL] removes full-line redundant comment without touching code on same line above",
+            //   code: `function example() {\n  const keep = 1;\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  if (flag) {\n    // @req REQ-INIT\n    const value = 1;\n  }\n}`,
+            //   output: `function example() {\n  const keep = 1;\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  if (flag) {\n    const value = 1;\n  }\n}`,
+            //   errors: [
+            //     { messageId: "redundantAnnotation" },
+            //   ],
+            // },
+        ],
+    });
+    runRule({
+        valid: [
+            {
+                name: "[REQ-CONFIGURABLE-STRICTNESS] permissive mode does not flag expression statements as redundant",
+                options: [{ strictness: "permissive" }],
+                code: `function example() {\n  // @story docs/stories/004.0-EXAMPLE.story.md\n  // @req REQ-PROCESS\n  if (condition) {\n    // @story docs/stories/004.0-EXAMPLE.story.md\n    // @req REQ-PROCESS\n    doSomething();\n  }\n}`,
+            },
+            {
+                name: "[REQ-CONFIGURABLE-STRICTNESS] allowEmphasisDuplication skips single covered pair",
+                options: [{ allowEmphasisDuplication: true }],
+                code: `function example() {\n  // @story docs/stories/004.0-EXAMPLE.story.md\n  // @req REQ-PROCESS\n  if (condition) {\n    // @story docs/stories/004.0-EXAMPLE.story.md\n    // @req REQ-PROCESS\n    return value;\n  }\n}`,
+            },
+            {
+                name: "[REQ-SCOPE-INHERITANCE] maxScopeDepth=1 does not treat grandparent function annotations as covering nested block",
+                options: [{ maxScopeDepth: 1 }],
+                code: `/**\n * @story docs/stories/004.0-EXAMPLE.story.md\n * @req REQ-PROCESS\n */\nfunction example() {\n  if (outer) {\n    {\n      // @story docs/stories/004.0-EXAMPLE.story.md\n      // @req REQ-PROCESS\n      const value = compute();\n    }\n  }\n}`,
+            },
+        ],
+        invalid: [
+            {
+                name: "[REQ-SCOPE-INHERITANCE] maxScopeDepth>1 treats function-level annotations as covering nested block statements",
+                options: [{ maxScopeDepth: 4 }],
+                code: `/**\n * @story docs/stories/004.0-EXAMPLE.story.md\n * @req REQ-PROCESS\n */\nfunction example() {\n  if (outer) {\n    {\n      // @story docs/stories/004.0-EXAMPLE.story.md\n      // @req REQ-PROCESS\n      const value = compute();\n    }\n  }\n}`,
+                output: `/**\n * @story docs/stories/004.0-EXAMPLE.story.md\n * @req REQ-PROCESS\n */\nfunction example() {\n  if (outer) {\n    {\n      const value = compute();\n    }\n  }\n}`,
+                errors: [{ messageId: "redundantAnnotation" }],
+            },
+        ],
+    });
+});

package/lib/tests/utils/annotation-scope-analyzer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tests/utils/annotation-scope-analyzer.test.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const annotation_scope_analyzer_1 = require("../../src/utils/annotation-scope-analyzer");
+describe("annotation-scope-analyzer helpers (Story 027.0-DEV-REDUNDANT-ANNOTATION-DETECTION)", () => {
+    it("[REQ-DUPLICATION-DETECTION] builds stable story/req keys", () => {
+        const key = (0, annotation_scope_analyzer_1.toStoryReqKey)("docs/stories/001.story.md", "REQ-ONE");
+        expect(key).toBe("docs/stories/001.story.md|REQ-ONE");
+    });
+    it("[REQ-DUPLICATION-DETECTION] extracts pairs from @story/@req sequences", () => {
+        const text = `// @story docs/stories/001.story.md\n// @req REQ-ONE`;
+        const pairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(text);
+        expect(Array.from(pairs)).toEqual([
+            "docs/stories/001.story.md|REQ-ONE",
+        ]);
+    });
+    it("[REQ-SCOPE-ANALYSIS] extracts pairs from @supports lines", () => {
+        const text = `// @supports docs/stories/002.story.md REQ-A REQ-B OTHER`;
+        const pairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(text);
+        expect(pairs.has("docs/stories/002.story.md|REQ-A")).toBe(true);
+        expect(pairs.has("docs/stories/002.story.md|REQ-B")).toBe(true);
+    });
+    it("[REQ-DUPLICATION-DETECTION] aggregates pairs across comments", () => {
+        const comments = [
+            { value: "// @story docs/stories/001.story.md\n// @req REQ-ONE" },
+            { value: "// @supports docs/stories/002.story.md REQ-TWO" },
+        ];
+        const pairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(comments);
+        expect(pairs.size).toBe(2);
+    });
+    it("[REQ-DUPLICATION-DETECTION] determines full coverage correctly", () => {
+        const parent = new Set([
+            "story|REQ-ONE",
+            "story|REQ-TWO",
+        ]);
+        const childCovered = new Set(["story|REQ-ONE"]);
+        const childNotCovered = new Set(["story|REQ-THREE"]);
+        expect((0, annotation_scope_analyzer_1.arePairsFullyCovered)(childCovered, parent)).toBe(true);
+        expect((0, annotation_scope_analyzer_1.arePairsFullyCovered)(childNotCovered, parent)).toBe(false);
+    });
+    it("[REQ-STATEMENT-SIGNIFICANCE] respects alwaysCovered and strictness levels", () => {
+        const base = {
+            strictness: "moderate",
+            allowEmphasisDuplication: false,
+            maxScopeDepth: 3,
+            alwaysCovered: ["ReturnStatement"],
+        };
+        const branchTypes = ["IfStatement"];
+        expect((0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)({ type: "ReturnStatement" }, base, branchTypes)).toBe(true);
+        expect((0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)({ type: "ExpressionStatement" }, base, branchTypes)).toBe(true);
+        expect((0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)({ type: "IfStatement" }, base, branchTypes)).toBe(false);
+    });
+    it("[REQ-SAFE-REMOVAL] computes removal range for full-line comment", () => {
+        const source = `const x = 1;\n// @story docs/stories/001.story.md\nconst y = 2;\n`;
+        const sourceCode = {
+            getText() {
+                return source;
+            },
+        };
+        const start = source.indexOf("// @story");
+        const end = start + "// @story docs/stories/001.story.md".length;
+        const comment = { range: [start, end] };
+        const [removalStart, removalEnd] = (0, annotation_scope_analyzer_1.getCommentRemovalRange)(comment, sourceCode);
+        const removed = source.slice(0, removalStart) + source.slice(removalEnd);
+        expect(removed).toBe("const x = 1;\nconst y = 2;\n");
+    });
+    it("[REQ-SAFE-REMOVAL] returns [0, 0] for comments with invalid range length (EXPECTS EXPECTED_RANGE_LENGTH usage)", () => {
+        const source = "const x = 1;";
+        const sourceCode = {
+            getText() {
+                return source;
+            },
+        };
+        const comment = { range: [0] };
+        const range = (0, annotation_scope_analyzer_1.getCommentRemovalRange)(comment, sourceCode);
+        expect(range).toEqual([0, 0]);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.12.1",
+  "version": "1.13.1",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",

package/user-docs/api-reference.md

@@ -268,6 +268,42 @@ describe("Refunds flow docs/stories/010.0-PAYMENTS.story.md", () => {
 });
 ```
 
+### traceability/no-redundant-annotation
+
+Description: Detects and optionally removes **redundant** traceability annotations on code that is already covered by an enclosing annotated scope. It focuses on simple, statement-level constructs—such as `return` statements, basic variable declarations, and other leaf statements—where repeating the same `@story` / `@req` / `@supports` information adds noise without improving coverage. When run with `--fix`, the rule offers safe auto-fixes that remove only the redundant comments while preserving all annotations that are required to maintain correct traceability.
+
+The rule is designed to complement the core presence and validation rules: it never treats removing a redundant annotation as valid if doing so would leave the underlying requirement or story **uncovered** according to the plugin’s normal rules. It only targets comments whose traceability content is already implied by a surrounding function, method, or branch annotation.
+
+Options:
+
+The rule accepts an optional configuration object:
+
+- `strictness` (`"strict" | "moderate" | "permissive"`, optional)  Controls how broadly statements are considered eligible for redundancy.
+  - `"strict"`  Treats any non-branch statement as a candidate for redundancy once it is covered by a containing annotated scope. This is the most aggressive mode and is useful in codebases that want to push almost all traceability down to function/branch level only.
+  - `"moderate"` (default)  Focuses on obviously leaf-like statements: anything in `alwaysCovered` **plus** bare `ExpressionStatement` nodes (for example, simple calls or assignments) that are not themselves branches. This mode balances redundancy cleanup with readability.
+  - `"permissive"`  Only treats AST node types listed in `alwaysCovered` as candidates. Other statements are ignored even when they are technically covered by an enclosing scope, which is useful when you prefer more explicit, local annotations.
+- `allowEmphasisDuplication` (boolean, optional)  When `true`, allows a statement-level annotation that repeats a **single** fully-covered story/requirement pair from its parent scope purely for emphasis (for example, a guard clause with its own comment) and **does not** report it as redundant. When omitted or `false` (the default), even emphasis-only duplicates are treated as redundant when they add no new coverage.
+- `maxScopeDepth` (number, optional)  Limits how far up the ancestor chain the rule searches for covering scopes when deciding whether a statements annotations are redundant. A value of `1` restricts checks to the immediate parent scope; larger values allow the rule to consider annotations on enclosing branches and functions further up the tree. The default is `3`, which is suitable for most common function and branch nesting patterns, but you can increase it (for example, to `4` or higher) in projects that use additional nested blocks inside annotated functions.
+- `alwaysCovered` (string[], optional)  List of AST statement `node.type` strings that your project treats as "always covered" by their containing scope when that scope is annotated. By default, the rule treats `ReturnStatement` and `VariableDeclaration` as always-covered leaf statements. You can extend or override this list to tune which statement types are considered trivial enough to inherit coverage from their parent scopes.
+
+Behavior notes:
+
+- The rule only inspects comments that contain recognized traceability annotations (`@story`, `@req`, `@supports`) and are attached to simple statements (returns, expression statements, variable declarations, and similar leaf nodes). It intentionally does **not** attempt to de-duplicate annotations on functions, classes, or major branches, which remain the responsibility of the core rules. When a statement has multiple redundant traceability comments (for example, a small comment block that repeats both @story and @req lines), the rule reports a **single** diagnostic for that statement and, in fix mode, removes all of the redundant annotation comments associated with it in a single grouped fix.
+- Auto-fix removes only the redundant traceability lines (and any now-empty comment delimiters when safe) while preserving surrounding non-traceability text in the same comment where possible.
+- When no enclosing scope with compatible coverage is found within `maxScopeDepth`, the annotation is not considered redundant and is left unchanged.
+
+Default Severity: `warn`
+
+This rule is **not** enabled in the `recommended` or `strict` presets by default. To use it, add it explicitly to your ESLint configuration with an appropriate severity level:
+
+```jsonc
+{
+  "rules": {
+    "traceability/no-redundant-annotation": "warn",
+  },
+}
+```
+
 ### traceability/prefer-supports-annotation
 
 Description: An optional, opt-in migration helper that encourages converting legacy single‑story `@story` + `@req` JSDoc blocks into the newer multi‑story `@supports` format. The rule is **disabled by default** and is **not included in any built‑in preset**; you enable it explicitly and control its behavior entirely via ESLint severity (`"off" | "warn" | "error"`). It does not change what the core rules consider valid—it only adds migration recommendations and safe auto‑fixes on top of existing validation. The legacy rule key `traceability/prefer-implements-annotation` is still recognized as a **deprecated alias** for `traceability/prefer-supports-annotation` so that existing configurations continue to work unchanged.