eslint-plugin-traceability 1.15.0 → 1.16.1

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

@@ -6,6 +6,12 @@ describe("annotation-scope-analyzer helpers (Story 027.0-DEV-REDUNDANT-ANNOTATIO
         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] normalizes missing story or requirement to empty segments", () => {
+        const noStory = (0, annotation_scope_analyzer_1.toStoryReqKey)(null, "REQ-ONE");
+        const noReq = (0, annotation_scope_analyzer_1.toStoryReqKey)("docs/stories/001.story.md", undefined);
+        expect(noStory).toBe("|REQ-ONE");
+        expect(noReq).toBe("docs/stories/001.story.md|");
+    });
     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);
@@ -13,6 +19,10 @@ describe("annotation-scope-analyzer helpers (Story 027.0-DEV-REDUNDANT-ANNOTATIO
             "docs/stories/001.story.md|REQ-ONE",
         ]);
     });
+    it("[REQ-DUPLICATION-DETECTION] returns empty set when text has no annotations", () => {
+        const pairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)("");
+        expect(pairs.size).toBe(0);
+    });
     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);
@@ -27,6 +37,10 @@ describe("annotation-scope-analyzer helpers (Story 027.0-DEV-REDUNDANT-ANNOTATIO
         const pairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(comments);
         expect(pairs.size).toBe(2);
     });
+    it("[REQ-DUPLICATION-DETECTION] returns empty set for empty comments list", () => {
+        const pairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)([]);
+        expect(pairs.size).toBe(0);
+    });
     it("[REQ-DUPLICATION-DETECTION] determines full coverage correctly", () => {
         const parent = new Set([
             "story|REQ-ONE",
@@ -37,6 +51,11 @@ describe("annotation-scope-analyzer helpers (Story 027.0-DEV-REDUNDANT-ANNOTATIO
         expect((0, annotation_scope_analyzer_1.arePairsFullyCovered)(childCovered, parent)).toBe(true);
         expect((0, annotation_scope_analyzer_1.arePairsFullyCovered)(childNotCovered, parent)).toBe(false);
     });
+    it("[REQ-DUPLICATION-DETECTION] treats empty child or parent as not covered", () => {
+        const nonEmpty = new Set(["story|REQ-ONE"]);
+        expect((0, annotation_scope_analyzer_1.arePairsFullyCovered)(new Set(), nonEmpty)).toBe(false);
+        expect((0, annotation_scope_analyzer_1.arePairsFullyCovered)(nonEmpty, new Set())).toBe(false);
+    });
     it("[REQ-STATEMENT-SIGNIFICANCE] respects alwaysCovered and strictness levels", () => {
         const base = {
             strictness: "moderate",
@@ -49,6 +68,39 @@ describe("annotation-scope-analyzer helpers (Story 027.0-DEV-REDUNDANT-ANNOTATIO
         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-CONFIGURABLE-STRICTNESS] treats permissive mode as only honoring alwaysCovered list", () => {
+        const options = {
+            strictness: "permissive",
+            allowEmphasisDuplication: false,
+            maxScopeDepth: 3,
+            alwaysCovered: ["ReturnStatement"],
+        };
+        const branchTypes = ["IfStatement"];
+        expect((0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)({ type: "ReturnStatement" }, options, branchTypes)).toBe(true);
+        expect((0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)({ type: "ExpressionStatement" }, options, branchTypes)).toBe(false);
+    });
+    it("[REQ-CONFIGURABLE-STRICTNESS] treats strict mode as allowing any non-branch statement", () => {
+        const options = {
+            strictness: "strict",
+            allowEmphasisDuplication: false,
+            maxScopeDepth: 3,
+            alwaysCovered: [],
+        };
+        const branchTypes = ["IfStatement"];
+        expect((0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)({ type: "ExpressionStatement" }, options, branchTypes)).toBe(true);
+        expect((0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)({ type: "IfStatement" }, options, branchTypes)).toBe(false);
+    });
+    it("[REQ-STATEMENT-SIGNIFICANCE] returns false for null or non-node values", () => {
+        const options = {
+            strictness: "moderate",
+            allowEmphasisDuplication: false,
+            maxScopeDepth: 3,
+            alwaysCovered: [],
+        };
+        const branchTypes = [];
+        expect((0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(null, options, branchTypes)).toBe(false);
+        expect((0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)({}, options, 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 = {
@@ -63,6 +115,77 @@ describe("annotation-scope-analyzer helpers (Story 027.0-DEV-REDUNDANT-ANNOTATIO
         const removed = source.slice(0, removalStart) + source.slice(removalEnd);
         expect(removed).toBe("const x = 1;\nconst y = 2;\n");
     });
+    it("[REQ-SAFE-REMOVAL] computes removal range for full-line comment with Windows newlines", () => {
+        const source = "const x = 1;\r\n// @story docs/stories/001.story.md\r\nconst y = 2;\r\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;\r\nconst y = 2;\r\n");
+    });
+    it("[REQ-SAFE-REMOVAL] computes removal range for full-line comment with standalone CR newline", () => {
+        const source = "const x = 1;\r// @story docs/stories/001.story.md\rconst y = 2;\r";
+        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;\rconst y = 2;\r");
+    });
+    it("[REQ-SAFE-REMOVAL] computes removal range for inline comment", () => {
+        const source = "const x = 1; // @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] consumes trailing spaces and tabs following a 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] handles full-line comment at end of file without trailing newline", () => {
+        const source = "const x = 1;\n// @story docs/stories/001.story.md";
+        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;\n");
+        expect(removalEnd).toBe(source.length);
+    });
     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 = {
@@ -74,4 +197,15 @@ describe("annotation-scope-analyzer helpers (Story 027.0-DEV-REDUNDANT-ANNOTATIO
         const range = (0, annotation_scope_analyzer_1.getCommentRemovalRange)(comment, sourceCode);
         expect(range).toEqual([0, 0]);
     });
+    it("[REQ-SAFE-REMOVAL] returns [0, 0] when comment range is not an array", () => {
+        const source = "const x = 1;";
+        const sourceCode = {
+            getText() {
+                return source;
+            },
+        };
+        const comment = { range: null };
+        const range = (0, annotation_scope_analyzer_1.getCommentRemovalRange)(comment, sourceCode);
+        expect(range).toEqual([0, 0]);
+    });
 });

package/lib/tests/utils/branch-annotation-helpers.test.js

@@ -44,4 +44,70 @@ describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () =
             }));
         });
     });
+    it("should gather SwitchCase comment text via gatherBranchCommentText (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () => {
+        // Fake SourceCode-like object with lines aligned to PRE_COMMENT_OFFSET logic
+        const sourceCode = {
+            lines: [
+                "// @story first part",
+                "// continuation second part",
+                "case 1:",
+            ],
+            getCommentsBefore: () => [],
+            getText: jest.fn(),
+        };
+        // SwitchCase-like node with loc.start.line corresponding to "case 1:" line (line 3)
+        const switchCaseNode = {
+            type: "SwitchCase",
+            loc: {
+                start: { line: 3, column: 0 },
+                end: { line: 3, column: 7 },
+            },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, switchCaseNode);
+        // Expect combined text using space separator and preserving leading //
+        expect(text).toBe("// @story first part // continuation second part");
+    });
+    it("should gather comment text for CatchClause and loop nodes via gatherBranchCommentText (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () => {
+        // CatchClause: comments come from getCommentsBefore when beforeText already contains @story
+        const catchComments = [
+            { type: "Line", value: "@story catch branch story" },
+            { type: "Line", value: "additional info" },
+        ];
+        const sourceCodeCatch = {
+            getCommentsBefore: jest.fn().mockReturnValue(catchComments),
+            getText: jest.fn().mockReturnValue("@story existing beforeText"),
+            lines: [],
+        };
+        const catchNode = {
+            type: "CatchClause",
+            loc: {
+                start: { line: 10, column: 0 },
+                end: { line: 12, column: 1 },
+            },
+        };
+        const catchText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCodeCatch, catchNode);
+        expect(sourceCodeCatch.getCommentsBefore).toHaveBeenCalledWith(catchNode);
+        expect(catchText).toContain("@story catch branch story");
+        expect(catchText).toContain("additional info");
+        // Loop node: ForStatement currently uses beforeComments.map(extractCommentValue).join(" ")
+        const loopComments = [
+            { type: "Line", value: "@story loop branch story" },
+            { type: "Block", value: "loop details" },
+        ];
+        const sourceCodeLoop = {
+            getCommentsBefore: jest.fn().mockReturnValue(loopComments),
+            getText: jest.fn().mockReturnValue("@story loop beforeText"),
+            lines: [],
+        };
+        const forNode = {
+            type: "ForStatement",
+            loc: {
+                start: { line: 20, column: 0 },
+                end: { line: 25, column: 1 },
+            },
+        };
+        const loopText = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCodeLoop, forNode);
+        expect(sourceCodeLoop.getCommentsBefore).toHaveBeenCalledWith(forNode);
+        expect(loopText).toBe("@story loop branch story loop details");
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.15.0",
+  "version": "1.16.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",
@@ -90,7 +90,7 @@
     "lint-staged": "^16.2.7",
     "prettier": "^3.6.2",
     "semantic-release": "25.0.2",
-    "ts-jest": "^29.4.5",
+    "ts-jest": "^29.4.6",
     "typescript": "^5.9.3",
     "secretlint": "11.2.5",
     "@secretlint/secretlint-rule-preset-recommend": "11.2.5"

package/user-docs/api-reference.md

@@ -11,19 +11,30 @@ Security and dependency hygiene for the published package are enforced by the sa
 
 Each rule enforces traceability conventions in your code. Below is a summary of each rule exposed by this plugin.
 
+For function-level traceability, new configurations should treat `traceability/require-traceability` as the **canonical** rule: it composes both story and requirement checks and understands both the newer `@supports` style and the legacy `@story` / `@req` pairing. The older keys `traceability/require-story-annotation` and `traceability/require-req-annotation` remain available as **backward-compatible aliases** so existing configs keep working, but they are no longer the primary entry points and are mainly useful when you need to tune severities independently. For new and multi-story scenarios, prefer `@supports` annotations; `@story` and `@req` remain valid and are still appropriate for simple single-story code paths where a consolidated `@supports` tag is not yet required.
+
 In addition to the core `@story` and `@req` annotations, the plugin also understands `@supports` for code that fulfills requirements from multiple stories—for example, a consuming project might use a path like
 `@supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND`
 to indicate that a given function supports a particular requirement from a payments story document within that project’s own `docs/stories` tree. For a detailed explanation of `@supports` behavior and validation, see [Migration Guide](migration-guide.md) (section **3.1 Multi-story @supports annotations**). Additional background on multi-story semantics is available in the project’s internal rule documentation, which is intended for maintainers rather than end users.
 
 The `prefer-supports-annotation` rule is an **opt-in migration helper** that is disabled by default and **not** part of any built-in preset. It can be enabled and given a severity like `"warn"` or `"error"` using normal ESLint rule configuration when you want to gradually encourage multi-story `@supports` usage. The legacy rule key `traceability/prefer-implements-annotation` remains available as a **deprecated alias** for backward compatibility, but new configurations should prefer `traceability/prefer-supports-annotation`. Detailed behavior and migration guidance are documented in the project’s internal rule documentation, which is targeted for maintainers; typical end users can rely on the high-level guidance in this API reference and the [Migration Guide](migration-guide.md).
 
+### Function-level rules overview
+
+For function-level traceability, the plugin exposes a unified rule and two legacy keys:
+
+- `traceability/require-traceability` is the **canonical function-level rule** for new configurations. It ensures functions and methods have both story coverage and requirement coverage, and it accepts either `@supports` (preferred) or legacy `@story` / `@req` annotations.
+- `traceability/require-story-annotation` and `traceability/require-req-annotation` are **backward-compatible aliases** that focus on the story and requirement aspects separately. They are retained for existing configurations and share the same underlying implementation model as the unified rule, but new ESLint configs should normally rely on `traceability/require-traceability` rather than enabling these legacy keys directly.
+
+All three rule keys can still be configured individually if you need fine-grained control (for example, to tune severities separately), but the recommended and strict presets enable `traceability/require-traceability` by default and keep the legacy keys primarily for projects that adopted them before the unified rule existed.
+
 ### traceability/require-traceability
 
 Description: Unified function-level traceability rule that composes the behavior of `traceability/require-story-annotation` and `traceability/require-req-annotation`. When enabled, it enforces that in‑scope functions and methods carry both a story reference (`@story` or an equivalent `@supports` tag) and at least one requirement reference (`@req` or, when configured, `@supports`). The recommended flat‑config presets in this plugin enable `traceability/require-traceability` by default alongside the legacy rule keys for backward compatibility, so that existing configurations referring to `traceability/require-story-annotation` or `traceability/require-req-annotation` continue to work without change.
 
 ### traceability/require-story-annotation
 
-Description: Ensures every function declaration has a JSDoc comment with an `@story` annotation referencing the related user story. When you adopt multi-story `@supports` annotations, this rule also accepts `@supports` as an alternative way to prove story coverage, so either `@story` or at least one `@supports` tag will satisfy the presence check. When run with `--fix`, the rule inserts a single-line placeholder JSDoc `@story` annotation above missing functions, methods, TypeScript declare functions, and interface method signatures using a built-in template aligned with Story 008.0. This template is now configurable on a per-rule basis, and the rule exposes an explicit auto-fix toggle so you can choose between diagnostic-only behavior and automatic placeholder insertion. The default template remains aligned with Story 008.0, but you can now customize it per rule configuration and optionally disable auto-fix entirely when you only want diagnostics without edits.
+Description: **Legacy function-level key:** This rule key is retained for backward compatibility and conceptually composes the same checks as `traceability/require-traceability`. New configurations should normally enable `traceability/require-traceability` instead and rely on this key only when you need to tune it independently. Ensures every function declaration has a traceability annotation, preferring `@supports` for story coverage while still accepting legacy `@story` annotations referencing the related user story. When you adopt multi-story `@supports` annotations, this rule also accepts `@supports` as an alternative way to prove story coverage, so either `@story` or at least one `@supports` tag will satisfy the presence check. When run with `--fix`, the rule inserts a single-line placeholder JSDoc `@story` annotation above missing functions, methods, TypeScript declare functions, and interface method signatures using a built-in template aligned with Story 008.0. This template is now configurable on a per-rule basis, and the rule exposes an explicit auto-fix toggle so you can choose between diagnostic-only behavior and automatic placeholder insertion. The default template remains aligned with Story 008.0, but you can now customize it per rule configuration and optionally disable auto-fix entirely when you only want diagnostics without edits.
 
 Options:
 
@@ -32,6 +43,7 @@ Options:
 - `annotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations for functions and non-method constructs. When omitted or blank, the built-in template from Story 008.0 is used.
 - `methodAnnotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations for class methods and TypeScript method signatures. When omitted or blank, falls back to `annotationTemplate` if provided, otherwise the built-in template.
 - `autoFix` (boolean, optional) – When set to `false`, disables all automatic fix behavior for this rule while retaining its suggestions and diagnostics. When omitted or `true`, the rule behaves as before, inserting placeholder annotations in `--fix` mode.
+- `excludeTestCallbacks` (boolean, optional) – When `true` (default), excludes anonymous arrow functions that are direct callbacks to common test framework functions (for example, Jest/Mocha/Vitest `describe`/`it`/`test`/`beforeEach`/`afterEach`/`beforeAll`/`afterAll`, plus focused/skipped/concurrent variants such as `fdescribe`, `xdescribe`, `fit`, `xit`, `test.concurrent`, `describe.concurrent`) from function-level annotation requirements. This assumes those test files are already covered by file-level `@supports` annotations and `traceability/require-test-traceability`. When set to `false`, these callbacks are treated like any other arrow function and must be annotated when in-scope.
 
 Default Severity: `error`
 Example:
@@ -46,9 +58,11 @@ function initAuth() {
 }
 ```
 
+Among the supported scopes, anonymous callbacks passed directly to common test framework functions are excluded from annotation requirements by default via `excludeTestCallbacks`; projects that prefer stricter enforcement for these callbacks can disable this exclusion by setting `excludeTestCallbacks: false` in their rule configuration.
+
 ### traceability/require-req-annotation
 
-Description: Ensures that function-like constructs consistently declare their linked requirement using an `@req` annotation in JSDoc. The rule targets the same function-like node types as `traceability/require-story-annotation` (standard function declarations, non-arrow function expressions used as callbacks or assignments, class/object methods, TypeScript declare functions, and interface method signatures), and enforces that each of them has at least one `@req` tag in the nearest associated JSDoc comment. When you adopt multi-story `@supports` annotations, this rule also treats `@supports story-path REQ-ID...` tags as satisfying the requirement coverage check, although deep verification of requirement IDs continues to be handled by `traceability/valid-req-reference`. Arrow functions (`ArrowFunctionExpression`) are not currently checked by this rule.
+Description: **Legacy function-level key:** This rule key is retained for backward compatibility and conceptually composes the same checks as `traceability/require-traceability`. New configurations should normally enable `traceability/require-traceability` instead and rely on this key only when you need to tune it independently. Ensures that function-like constructs consistently declare their linked requirements via traceability annotations, preferring `@supports` when possible while still accepting `@req`. The rule targets the same function-like node types as `traceability/require-story-annotation` (standard function declarations, non-arrow function expressions used as callbacks or assignments, class/object methods, TypeScript declare functions, and interface method signatures), and enforces that each of them has at least one `@req` tag in the nearest associated JSDoc comment. When you adopt multi-story `@supports` annotations, this rule also treats `@supports story-path REQ-ID...` tags as satisfying the requirement coverage check, although deep verification of requirement IDs continues to be handled by `traceability/valid-req-reference`. Arrow functions (`ArrowFunctionExpression`) are not currently checked by this rule.
 
 This rule is typically used alongside `traceability/require-story-annotation` so that each function-level traceability block includes both an `@story` and an `@req` annotation, but it can also be enabled independently if you only want to enforce requirement linkage. Unlike `traceability/require-story-annotation`, this rule does not currently provide an auto-fix mode for inserting placeholder `@req` annotations; it only reports missing or malformed requirement annotations on the configured scopes.
 
@@ -72,7 +86,7 @@ function initAuth() {
 
 ### traceability/require-branch-annotation
 
-Description: Ensures significant code branches (if/else chains, loops, switch cases, try/catch) have both `@story` and `@req` annotations in nearby comments. When you adopt multi-story `@supports` annotations, a single `@supports <storyPath> <REQ-ID>...` line placed in any of the valid branch comment locations is treated as satisfying both the story and requirement presence checks for that branch, while detailed format validation of the `@supports` value (including story paths and requirement IDs) continues to be handled by `traceability/valid-annotation-format`, `traceability/valid-story-reference`, and `traceability/valid-req-reference`.
+Description: Ensures significant code branches (if/else chains, loops, switch cases, try/catch) have traceability coverage, typically via a single `@supports` line, while still accepting legacy `@story` and `@req` annotations in nearby comments. When you adopt multi-story `@supports` annotations, a single `@supports <storyPath> <REQ-ID>...` line placed in any of the valid branch comment locations is treated as satisfying both the story and requirement presence checks for that branch, while detailed format validation of the `@supports` value (including story paths and requirement IDs) continues to be handled by `traceability/valid-annotation-format`, `traceability/valid-story-reference`, and `traceability/valid-req-reference`.
 
 For most branches, the rule looks for annotations in comments immediately preceding the branch keyword (for example, the line above an `if` or `for` statement). For `catch` clauses and `else if` branches, the rule is formatter-aware and accepts annotations in additional positions that common formatters like Prettier use when they reflow code.
 
@@ -112,7 +126,7 @@ if (error) {
 
 ### traceability/valid-annotation-format
 
-Description: Validates that all traceability annotations (`@story`, `@req`) follow the correct JSDoc or inline comment format. When run with `--fix`, the rule limits changes to safe `@story` path suffix normalization only—for example, adding `.md` when the path ends with `.story`, or adding `.story.md` when the base path has no extension—using targeted replacements implemented in the `getFixedStoryPath` and `reportInvalidStoryFormatWithFix` helpers. It does not change directories, infer new story names, or modify any surrounding comment text or whitespace, in line with Story 008.0. Selective disabling of this suffix-normalization auto-fix behavior is available via the `autoFix` option, which defaults to `true` for backward compatibility.
+Description: Validates that all traceability annotations (`@supports` as the preferred form for new code, plus legacy `@story` and `@req`) follow the correct JSDoc or inline comment format. When run with `--fix`, the rule limits changes to safe `@story` path suffix normalization only—for example, adding `.md` when the path ends with `.story`, or adding `.story.md` when the base path has no extension—using targeted replacements implemented in the `getFixedStoryPath` and `reportInvalidStoryFormatWithFix` helpers. It does not change directories, infer new story names, or modify any surrounding comment text or whitespace, in line with Story 008.0. Selective disabling of this suffix-normalization auto-fix behavior is available via the `autoFix` option, which defaults to `true` for backward compatibility.
 
 Options:
 
@@ -150,21 +164,34 @@ The `valid-annotation-format` rule is intentionally **backward compatible** with
 Deep requirement checking for both `@req` and `@supports` is handled by the `valid-req-reference` rule in the plugin's internal docs. Advanced edge cases and internal semantics are mainly of interest to maintainers; typical end users can rely on the options and examples in this API reference when configuring the rule for their projects.
 
 Default Severity: `error`
-Example:
+
+Primary example (recommended `@supports` style):
+
+```javascript
+/**
+ * @supports docs/stories/005.0-DEV-VALIDATION.story.md#REQ-FORMAT-VALIDATION
+ */
+function example() {
+  // ...
+}
+```
+
+Legacy example (`@story` + `@req`, still valid but not preferred for new code):
 
 ```javascript
 /**
  * @story docs/stories/005.0-DEV-VALIDATION.story.md
  * @req REQ-FORMAT-VALIDATION
  */
-function example() {
+function legacyExample() {
   // ...
 }
 ```
 
 ### traceability/valid-story-reference
 
-Description: Checks that the file paths in `@story` annotations point to existing story markdown files.
+Description: Checks that the story file paths used by traceability annotations point to existing story markdown files in an `@supports`‑first world. Modern code typically encodes story paths in `@supports` tags (for example, `@supports docs/stories/010.0-PAYMENTS.story.md#REQ-ID`), but this rule continues to operate on the underlying `@story` values for file‑existence checks, keeping legacy annotations and mixed blocks fully supported.
+
 Options:
 Configure rule behavior using an options object with these properties:
 
@@ -190,31 +217,57 @@ Example configuration:
 ```
 
 Default Severity: `error`
-Example:
+
+Primary example (recommended `@supports` style, with a companion `@story` used for existence checks):
+
+```javascript
+/**
+ * @supports docs/stories/006.0-DEV-STORY-EXISTS.story.md#REQ-STORY-EXISTS
+ * @story docs/stories/006.0-DEV-STORY-EXISTS.story.md // used for file-existence validation; kept for backward compatibility
+ */
+function example() {
+  // ...
+}
+```
+
+Legacy-only example (`@story` + `@req`, still supported as an input to this rule):
 
 ```javascript
 /**
  * @story docs/stories/006.0-DEV-STORY-EXISTS.story.md
  * @req REQ-STORY-EXISTS
  */
-function example() {
+function legacyExample() {
   // ...
 }
 ```
 
 ### traceability/valid-req-reference
 
-Description: Verifies that the IDs used in `@req` annotations match known requirement identifiers.
+Description: Verifies that the requirement IDs used in traceability annotations match known requirement identifiers, whether they appear in modern `@supports` tags or in legacy `@req` annotations.
+
 Options: None
 Default Severity: `error`
-Example:
+
+Primary example (recommended `@supports` style with requirement IDs):
+
+```javascript
+/**
+ * @supports docs/stories/007.0-DEV-REQ-REFERENCE.story.md#REQ-VALID-REFERENCE REQ-VALID-REFERENCE-EDGE
+ */
+function example() {
+  // ...
+}
+```
+
+Legacy example (`@story` + `@req`, still valid for backward compatibility):
 
 ```javascript
 /**
  * @story docs/stories/007.0-DEV-REQ-REFERENCE.story.md
  * @req REQ-VALID-REFERENCE
  */
-function example() {
+function legacyExample() {
   // ...
 }
 ```
@@ -296,12 +349,14 @@ Behavior notes:
 
 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:
+This rule is enabled at severity `warn` in both the `recommended` and `strict` presets. You can override its behavior in your own configuration — for example, by raising it to `error` for stricter enforcement, or by explicitly disabling it if you prefer to keep statement-level duplication.
+
+Configuration example (override preset severity from `warn` to `error`):
 
 ```jsonc
 {
   "rules": {
-    "traceability/no-redundant-annotation": "warn",
+    "traceability/no-redundant-annotation": "error",
   },
 }
 ```
@@ -327,7 +382,7 @@ Main behaviors:
 
    ```js
    /**
-    * @supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND REQ-PAYMENTS-EDGE
+    * @supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND REQ-PAYMENTS-REFUND-EDGE
     */
    ```
 
@@ -432,6 +487,7 @@ Core rules enabled by the `recommended` preset:
 - `traceability/valid-story-reference`: `error`
 - `traceability/valid-req-reference`: `error`
 - `traceability/require-test-traceability`: `error`
+- `traceability/no-redundant-annotation`: `warn`
 
 Usage:
 

package/user-docs/examples.md

@@ -43,7 +43,21 @@ npx eslint "src/**/*.js"
 
 ## 3. CLI Invocation Example
 
-You can use the plugin without a config file by specifying rules inline:
+You can use the plugin without a config file by specifying rules inline. The recommended approach for new setups is to use the unified `traceability/require-traceability` rule:
+
+```bash
+npx eslint --no-eslintrc \
+  --rule "traceability/require-traceability:error" \
+  sample.js
+```
+
+This unified function-level rule enforces both story and requirement coverage via `@supports` (preferred) or, for backward compatibility, via legacy `@story`/`@req` annotations.
+
+Replace `sample.js` with your JavaScript or TypeScript file.
+
+### 3.1 Legacy aliases (for existing configurations)
+
+If you have older configurations that already refer to the legacy keys `traceability/require-story-annotation` and `traceability/require-req-annotation`, you can still enable them explicitly to avoid breaking those setups:
 
 ```bash
 npx eslint --no-eslintrc \
@@ -53,9 +67,7 @@ npx eslint --no-eslintrc \
 ```
 
 - `--no-eslintrc` tells ESLint to ignore user configs.
-- `--rule` options enable the traceability rules you need.
-
-Replace `sample.js` with your JavaScript or TypeScript file.
+- `--rule` options enable either the unified rule (recommended for new configurations) or the legacy aliases when you must preserve older setups.
 
 ## 4. Linting a Specific Directory
 
@@ -103,6 +115,9 @@ describe("Story 021.0-DEV-TEST-TRACEABILITY", () => {
     // Act
     const result = performOperation(input);
 
+    // Assert
+    const result = performOperation(input);
+
     // Assert
     expect(result).toBe("edge-ok");
   });
@@ -125,13 +140,11 @@ In this version, annotations are placed immediately before each significant bran
 
 ```ts
 function pickCategory(score: number): string {
-  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-  // @req REQ-BRANCH-DETECTION
+  // @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION
   if (score >= 80) {
     return "high";
   }
-  // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
-  // @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
+  // @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF
   else if (score >= 50) {
     return "medium";
   }
@@ -156,13 +169,11 @@ Prettier may reflow your `else if` line, wrap the condition, or move comments in
 
 ```ts
 function pickCategory(score: number): string {
-  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-  // @req REQ-BRANCH-DETECTION
+  // @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION
   if (score >= 80) {
     return "high";
   } else if (score >= 50) {
-    // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
-    // @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
+    // @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF
     return "medium";
   } else {
     return "low";
@@ -173,6 +184,6 @@ function pickCategory(score: number): string {
 Depending on your Prettier version and configuration, the exact layout of the `else if` line and braces may differ, but as long as your annotations are in one of the supported locations, the rule will accept them.
 
 - Notes:
-  - For most branch types, `traceability/require-branch-annotation` associates comments immediately before the branch keyword (such as `if`, `else`, `switch`, `case`) with that branch.
+  - For most branch types, `traceability/require-branch-annotation` associates comments immediately before the branch keyword (such as `if`, `else`, `switch`, `case`) with that branch. Branches can be annotated either with a single `@supports` line (preferred), or with the older `@story`/`@req` pair for backward compatibility. The rule treats a valid `@supports` annotation as satisfying both the story and requirement presence checks.
   - For `catch` clauses and `else if` branches, the rule is formatter-aware and also looks at comments between the condition and the block, as well as the first comment-only lines inside the block body, so you do not need to fight Prettier if it moves your annotations.
   - When annotations exist in more than one place around an `else if` branch, the rule prefers comments immediately before the `else if` line, then comments between the condition and the block, and finally comments inside the block body, matching the behavior described in the API reference and stories `025.0` and `026.0`.