eslint-plugin-traceability 1.12.0 → 1.13.0

package/lib/tests/rules/auto-fix-behavior-008.test.js

@@ -8,7 +8,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-AUTOFIX-MISSING - Verify ESLint --fix automatically adds missing @story annotations to functions
  * @req REQ-AUTOFIX-FORMAT - Verify ESLint --fix corrects simple annotation format issues for @story annotations
- * @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-MISSING REQ-AUTOFIX-FORMAT
+ * @req REQ-AUTOFIX-IDEMPOTENT - Verify ESLint --fix is idempotent and produces no changes on subsequent runs
+ * @req REQ-AUTOFIX-SINGLE-APPLICATION - Verify ESLint --fix does not apply the same fix multiple times or create duplicate annotations
+ * @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-MISSING REQ-AUTOFIX-FORMAT REQ-AUTOFIX-IDEMPOTENT REQ-AUTOFIX-SINGLE-APPLICATION
  */
 const eslint_1 = require("eslint");
 const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
@@ -196,4 +198,88 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
             ],
         });
     });
+    describe("[REQ-AUTOFIX-IDEMPOTENT] and [REQ-AUTOFIX-SINGLE-APPLICATION] require-story-annotation", () => {
+        functionRuleTester.run("require-story-annotation --fix idempotent behavior", require_story_annotation_1.default, {
+            valid: [
+                {
+                    name: "[REQ-AUTOFIX-IDEMPOTENT] second run on already fixed function produces no changes",
+                    code: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction fixedOnce() {}`,
+                },
+                {
+                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] already annotated code does not receive duplicate annotations",
+                    code: `class E {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                },
+            ],
+            invalid: [
+                {
+                    name: "[REQ-AUTOFIX-IDEMPOTENT] first run adds annotation; subsequent run is a no-op for function declarations",
+                    code: `function needsFixOnce() {}`,
+                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction needsFixOnce() {}`,
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'needsFixOnce', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction needsFixOnce() {}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] does not duplicate annotations for class methods on subsequent runs",
+                    code: `class F {\n  method() {}\n}`,
+                    output: `class F {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `class F {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+    describe("[REQ-AUTOFIX-IDEMPOTENT] and [REQ-AUTOFIX-SINGLE-APPLICATION] valid-annotation-format", () => {
+        formatRuleTester.run("valid-annotation-format --fix idempotent behavior", valid_annotation_format_1.default, {
+            valid: [
+                {
+                    name: "[REQ-AUTOFIX-IDEMPOTENT] second run after suffix normalization produces no changes",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                },
+                {
+                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] already-correct suffix is not altered or extended again",
+                    code: `// @story docs/stories/005.0-DEV-EXAMPLE.story.md`,
+                },
+            ],
+            invalid: [
+                {
+                    name: "[REQ-AUTOFIX-IDEMPOTENT] adds .story.md once; subsequent run sees no further change",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION`,
+                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                    errors: [
+                        {
+                            messageId: "invalidStoryFormat",
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] converts .story to .story.md only once and does not double-append",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
+                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                    errors: [
+                        {
+                            messageId: "invalidStoryFormat",
+                        },
+                    ],
+                },
+            ],
+        });
+    });
 });

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,63 @@
+"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: [
+        // 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" },
+        //   ],
+        // },
+        ],
+    });
+});

package/lib/tests/rules/require-story-core.autofix.test.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-AUTOFIX - Cover additional branch cases in require-story-core (addStoryFixer/reportMissing)
  * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-AUTOFIX
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-RESILIENCE
  */
 const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
 const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");
@@ -37,4 +38,29 @@ describe("Require Story Core (Story 003.0)", () => {
         expect(call.node).toBe(node);
         expect(call.messageId).toBe("missingStory");
     });
+    test("coreReportMissing swallows dependency errors and does not break lint run", () => {
+        const deps = {
+            hasStoryAnnotation: () => {
+                throw new Error("boom");
+            },
+            getReportedFunctionName: () => "fnX",
+            resolveAnnotationTargetNode: () => ({ type: "FunctionDeclaration" }),
+            getNameNodeForReport: (node) => node,
+            buildTemplateConfig: () => ({
+                effectiveTemplate: "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                allowFix: true,
+            }),
+            extractName: () => "fnX",
+            getAnnotationTemplate: () => "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+            shouldApplyAutoFix: () => true,
+            createAddStoryFix: () => () => ({}),
+            createMethodFix: () => () => ({}),
+        };
+        const context = {
+            report: jest.fn(),
+        };
+        const node = { type: "FunctionDeclaration" };
+        expect(() => (0, require_story_core_1.coreReportMissing)(deps, context, {}, { node })).not.toThrow();
+        expect(context.report).not.toHaveBeenCalled();
+    });
 });

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/lib/tests/utils/branch-annotation-else-if-position.test.js

@@ -104,4 +104,42 @@ describe("gatherBranchCommentText else-if behavior (Story 026.0-DEV-ELSE-IF-ANNO
         expect(text).toContain("@req REQ-POSITION-PRIORITY-ELSE-IF");
         expect(text).not.toContain("REQ-POSITION-PRIORITY-ELSE-IF-BETWEEN");
     });
+    it("[REQ-SINGLE-LINE-ELSE-IF-SUPPORT] detects annotations on single-line else-if without braces when placed before the else-if keyword", () => {
+        const lines = [
+            "let suggestion;",
+            "// @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+            "// @req REQ-SINGLE-LINE-ELSE-IF-SUPPORT",
+            "if (arg === \"--json\") suggestion = \"--format=json\";",
+            "// @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+            "// @req REQ-SINGLE-LINE-ELSE-IF-SUPPORT",
+            "else if (arg.startsWith(\"--format\")) suggestion = \"--format\";",
+        ];
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [
+                {
+                    value: "@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+                },
+                { value: "@req REQ-SINGLE-LINE-ELSE-IF-SUPPORT" },
+            ],
+            lines,
+        });
+        const node = {
+            type: "IfStatement",
+            loc: { start: { line: 7 } },
+            test: { loc: { end: { line: 7 } } },
+            consequent: {
+                // single-line consequent without BlockStatement braces in the real-world source;
+                // for this helper-level test we only care that loc values exist and are consistent.
+                type: "ExpressionStatement",
+                loc: { start: { line: 7 } },
+            },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: node,
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent);
+        expect(text).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-SINGLE-LINE-ELSE-IF-SUPPORT");
+    });
 });

package/lib/tests/utils/req-annotation-detection.test.js

@@ -309,4 +309,50 @@ describe("reqAnnotationDetection advanced heuristics (Story 003.0-DEV-FUNCTION-A
         const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], undefined, node);
         expect(has).toBe(true);
     });
+    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqAnnotation returns true when advanced heuristics find req via linesBeforeHasReq", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({
+                    lines: [
+                        "// header without req",
+                        "/** @req REQ-ADV-LINES */",
+                        "function bar() {}",
+                    ],
+                });
+            },
+        };
+        const node = {
+            loc: { start: { line: 3 } },
+            parent: {},
+        };
+        const jsdoc = { value: "/** no req here */" };
+        const comments = [{ value: "no req or supports here" }];
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, comments, context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqAnnotation returns true when advanced heuristics find req via parentChainHasReq", () => {
+        const sourceCode = {
+            getCommentsBefore(n) {
+                if (n && n.isReqParent) {
+                    return [{ value: "/* @req REQ-ADV-PARENT */" }];
+                }
+                return [{ value: "no req here" }];
+            },
+        };
+        const context = {
+            getSourceCode() {
+                return sourceCode;
+            },
+        };
+        const node = {
+            parent: {
+                isReqParent: true,
+                parent: {},
+            },
+        };
+        const jsdoc = { value: "/** jsdoc without requirement */" };
+        const comments = [{ value: "comment without requirement" }];
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, comments, context, node);
+        expect(has).toBe(true);
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "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` (`"conservative" | "balanced" | "aggressive"`, optional) – Controls how eagerly redundancy is inferred.
+  - `"conservative"` – Only removes annotations when they are an exact structural duplicate of their containing scope (same story path and requirement IDs, no extras). Intended to minimize false positives.
+  - `"balanced"` (default) – Treats annotations as redundant when they do not add any **new** requirements or stories beyond what is already declared on the nearest enclosing scope, allowing for minor formatting differences.
+  - `"aggressive"` – Additionally flags cases where the inner annotation merely reorders or partially repeats the same requirement set, or where emphasis-only duplication (such as repeating a single requirement for emphasis) is considered redundant. Use with care in projects that rely heavily on local commentary.
+- `allowEmphasisDuplication` (boolean, optional) – When `true`, allows a statement-level annotation that repeats a **single** requirement or story from its parent purely to emphasize a critical line or edge case (for example, a guard clause that deserves its own comment), even when it would otherwise be considered redundant under the current `strictness`. Defaults to `true`. Set to `false` if you prefer to remove all covered duplicates, including emphasis-style comments.
+- `maxScopeDepth` (number, optional) – Limits how deep the rule will search for covering scopes when deciding whether an annotation is redundant. A depth of `1` (the default) considers only the nearest enclosing function/method or branch. Larger values allow walking further up nested scopes (e.g., inner blocks inside loops inside functions). Increasing this value can find more redundancy but may also make reasoning about coverage more subtle.
+- `alwaysCovered` (string[], optional) – A list of short annotation **aliases** or requirement patterns that your project treats as “implicitly covered” by higher-level documentation (for example, high-level safety or logging requirements that apply to an entire module). Any annotation whose requirement/story ID matches one of these entries is treated as redundant when it appears on simple leaf statements beneath the already-covered area, even if there is no local function-level annotation. Entries are compared as literal strings; pattern-like values (such as `"REQ-LOGGING-*"` or `"REQ-SAFETY"`) are project-specific conventions and are not treated as regular expressions by this rule.
+
+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.
+- 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.
@@ -705,5 +741,4 @@ If `--from` or `--to` is missing, the CLI prints an error, shows the help text,
 In CI:
 
 ```bash
-npm run traceability:verify
-```
+npm run traceability:verify