eslint-plugin-traceability 1.11.0 → 1.11.2

package/lib/tests/rules/require-branch-annotation.test.js

@@ -11,6 +11,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-ERROR-SPECIFIC - Branch-level missing-annotation error messages are specific and informative
  * @req REQ-ERROR-CONSISTENCY - Branch-level missing-annotation error messages follow shared conventions
  * @req REQ-ERROR-SUGGESTION - Branch-level missing-annotation errors include suggestions when applicable
+ * @req REQ-NESTED-HANDLING - Nested branch annotations are correctly enforced without duplicative reporting
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION REQ-NESTED-HANDLING
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SPECIFIC REQ-ERROR-CONSISTENCY REQ-ERROR-SUGGESTION
  */
 const eslint_1 = require("eslint");
 const require_branch_annotation_1 = __importDefault(require("../../src/rules/require-branch-annotation"));
@@ -120,6 +123,18 @@ while (condition) {
   // @req REQ-BRANCH-DETECTION
   case 'a':
     break;
+}`,
+            },
+            {
+                name: "[REQ-NESTED-HANDLING] nested if-statements with annotations on outer and inner branches",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-DETECTION
+if (outer) {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-NESTED-HANDLING
+  if (inner) {
+    doWork();
+  }
 }`,
             },
             {
@@ -244,6 +259,25 @@ try {
   // @story <story-file>.story.md
   case 'a':
     break;
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
+            {
+                name: "[REQ-NESTED-HANDLING] missing annotations on nested if-statement inside annotated outer branch",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-DETECTION
+if (outer) {
+  if (inner) {
+    doWork();
+  }
+}`,
+                output: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-DETECTION
+if (outer) {
+  // @story <story-file>.story.md
+  if (inner) {
+    doWork();
+  }
 }`,
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },

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

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Edge-case tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @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
  */
 const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
 const require_story_core_test_helpers_1 = require("../utils/require-story-core-test-helpers");

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

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @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
  */
 const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
 const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");

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

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-AUTOFIX - Verify createMethodFix and reportMethod behaviors
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-AUTOFIX
  */
 const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
 const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");

package/lib/tests/rules/require-story-helpers-edgecases.test.d.ts

@@ -2,5 +2,6 @@
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-HELPERS-EDGE-CASES - Edge-case behavior tests for helpers in require-story-helpers.ts
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-HELPERS-EDGE-CASES
  */
 export {};

package/lib/tests/rules/require-story-helpers-edgecases.test.js

@@ -3,6 +3,7 @@
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-HELPERS-EDGE-CASES - Edge-case behavior tests for helpers in require-story-helpers.ts
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-HELPERS-EDGE-CASES
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");

package/lib/tests/rules/require-story-helpers.test.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Verify helper functions in require-story helpers produce correct fixes and reporting behavior
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED
  */
 const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
 const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");
@@ -49,7 +50,7 @@ describe("Require Story Helpers (Story 003.0)", () => {
     test("reportMissing does not call context.report if JSDoc contains @story", () => {
         const node = {
             type: "FunctionDeclaration",
-            id: { name: "fn" },
+            id: { type: "Identifier", name: "fn" },
             range: [0, 10],
         };
         const fakeSource = {
@@ -68,7 +69,7 @@ describe("Require Story Helpers (Story 003.0)", () => {
     test("reportMissing calls context.report when no JSDoc story present", () => {
         const node = {
             type: "FunctionDeclaration",
-            id: { name: "fn2" },
+            id: { type: "Identifier", name: "fn2" },
             range: [0, 10],
         };
         const fakeSource = {
@@ -82,7 +83,7 @@ describe("Require Story Helpers (Story 003.0)", () => {
         (0, require_story_helpers_1.reportMissing)(context, fakeSource, { node, target: node });
         expect(context.report).toHaveBeenCalledTimes(1);
         const call = context.report.mock.calls[0][0];
-        expect(call.node).toBe(node);
+        expect(call.node).toBe(node.id);
         expect(call.messageId).toBe("missingStory");
     });
     /**

package/lib/tests/rules/require-story-io-behavior.test.d.ts

@@ -2,5 +2,6 @@
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-IO-BEHAVIOR-EDGE-CASES - Edge-case behavior tests for IO helpers in require-story-io.ts
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-IO-BEHAVIOR-EDGE-CASES
  */
 export {};

package/lib/tests/rules/require-story-io-behavior.test.js

@@ -3,6 +3,7 @@
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-IO-BEHAVIOR-EDGE-CASES - Edge-case behavior tests for IO helpers in require-story-io.ts
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-IO-BEHAVIOR-EDGE-CASES
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const require_story_io_1 = require("../../src/rules/helpers/require-story-io");

package/lib/tests/rules/require-story-io.edgecases.test.d.ts

@@ -2,5 +2,6 @@
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Edge case tests for IO helpers (linesBeforeHasStory/fallbackTextBeforeHasStory/parentChainHasStory)
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED
  */
 export {};

package/lib/tests/rules/require-story-io.edgecases.test.js

@@ -3,6 +3,7 @@
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Edge case tests for IO helpers (linesBeforeHasStory/fallbackTextBeforeHasStory/parentChainHasStory)
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const require_story_io_1 = require("../../src/rules/helpers/require-story-io");

package/lib/tests/rules/require-story-visitors-edgecases.test.d.ts

@@ -2,5 +2,6 @@
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-VISITORS-BEHAVIOR - Behavior tests for visitors in require-story-visitors.ts
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-VISITORS-BEHAVIOR
  */
 export {};

package/lib/tests/rules/require-story-visitors-edgecases.test.js

@@ -3,6 +3,7 @@
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-VISITORS-BEHAVIOR - Behavior tests for visitors in require-story-visitors.ts
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-VISITORS-BEHAVIOR
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const require_story_visitors_1 = require("../../src/rules/helpers/require-story-visitors");

package/lib/tests/rules/valid-annotation-format-internal.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for: docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md
+ * @story docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md
+ * @req REQ-IGNORE-INLINE-CODE - Strip backtick-wrapped content before annotation detection
+ * @req REQ-PRESERVE-BOUNDARIES - Replace backtick-wrapped content with spaces to preserve word boundaries
+ * @req REQ-CENTRALIZED-FILTER - Apply backtick filtering in normalizeCommentLine for all rules
+ */
+export {};

package/lib/tests/rules/valid-annotation-format-internal.test.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Tests for: docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md
+ * @story docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md
+ * @req REQ-IGNORE-INLINE-CODE - Strip backtick-wrapped content before annotation detection
+ * @req REQ-PRESERVE-BOUNDARIES - Replace backtick-wrapped content with spaces to preserve word boundaries
+ * @req REQ-CENTRALIZED-FILTER - Apply backtick filtering in normalizeCommentLine for all rules
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const valid_annotation_format_internal_1 = require("../../src/rules/helpers/valid-annotation-format-internal");
+(0, globals_1.describe)("normalizeCommentLine inline code filtering (Story 024.0-DEV-IGNORE-INLINE-CODE-REFS)", () => {
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE] ignores backtick-wrapped @story in line without real annotations", () => {
+        const raw = "This rule uses `@story` and other tags";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("This rule uses          and other tags");
+        (0, globals_1.expect)(normalized).not.toMatch(/@story|@req|@supports/);
+    });
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE] ignores backtick-wrapped @req in line without real annotations", () => {
+        const raw = "Legacy pattern `@req` should not be treated as annotation";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("Legacy pattern        should not be treated as annotation");
+        (0, globals_1.expect)(normalized).not.toMatch(/@story|@req|@supports/);
+    });
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE][REQ-PRESERVE-BOUNDARIES] preserves spacing when removing backtick segments", () => {
+        const raw = "`@story` + `@req` docs";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("         +        docs");
+        (0, globals_1.expect)(normalized).not.toMatch(/@story|@req|@supports/);
+    });
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE] still detects real @story annotation outside backticks", () => {
+        const raw = "using `@supports` and real @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("@story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md");
+    });
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE][REQ-PRESERVE-BOUNDARIES] handles multiple backtick segments on one line", () => {
+        const raw = "first `@story` and second `@req` markers";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("first          and second        markers");
+        (0, globals_1.expect)(normalized).not.toMatch(/@story|@req|@supports/);
+    });
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE] leaves lines without backticks unchanged apart from existing normalization", () => {
+        const raw = " * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("@story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md");
+    });
+});

package/lib/tests/rules/valid-story-reference.test.js

@@ -45,6 +45,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-ERROR-CONTEXT - Verify file-related error messages include contextual information (path, underlying error)
  * @req REQ-ERROR-CONSISTENCY - Verify file-related error messages follow consistent formatting and identifiers
  * @req REQ-ERROR-HANDLING - Verify file-related errors are reported via diagnostics instead of uncaught exceptions
+ * @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-FILE-EXISTENCE REQ-CONFIGURABLE-PATHS
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SPECIFIC REQ-ERROR-CONTEXT REQ-ERROR-CONSISTENCY REQ-ERROR-HANDLING
  */
 const eslint_1 = require("eslint");
 const valid_story_reference_1 = __importDefault(require("../../src/rules/valid-story-reference"));

package/lib/tests/utils/annotation-checker.test.js

@@ -6,6 +6,7 @@ exports.runAnnotationCheckerTests = runAnnotationCheckerTests;
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  * @req REQ-TEST-UTILS-TS-LANG - Shared TS RuleTester language options helper
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-TYPESCRIPT-SUPPORT REQ-TEST-UTILS-TS-LANG
  */
 const eslint_1 = require("eslint");
 const annotation_checker_1 = require("../../src/utils/annotation-checker");
@@ -52,7 +53,7 @@ const rule = {
         };
     },
 };
-describe("annotation-checker helper", () => {
+describe("annotation-checker helper (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
     runAnnotationCheckerTests("annotation-checker", {
         rule,
         valid: [

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

@@ -5,9 +5,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-CONFIGURABLE-SCOPE
  */
 const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
-describe("validateBranchTypes helper", () => {
+describe("validateBranchTypes helper (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () => {
     let context;
     beforeEach(() => {
         context = { options: [], report: jest.fn() };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "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",
@@ -29,7 +29,7 @@
     "lint": "eslint --config eslint.config.js \"src/**/*.{js,ts}\" \"tests/**/*.{js,ts}\" --max-warnings=0",
     "test": "jest --ci --bail",
     "ci-verify": "npm run type-check && npm run lint && npm run format:check && npm run duplication && npm run check:traceability && npm test && npm run audit:ci && npm run safety:deps",
-    "ci-verify:full": "npm run check:traceability && npm run safety:deps && npm run audit:ci && npm run build && npm run type-check && npm run lint-plugin-check && npm run lint -- --max-warnings=0 && npm run duplication && npm run test -- --coverage && npm run format:check && npm audit --omit=dev --audit-level=high && npm run audit:dev-high",
+    "ci-verify:full": "npm run check:traceability && npm run safety:deps && npm run audit:ci && npm run build && npm run type-check && npm run lint-plugin-check && npm run lint -- --max-warnings=0 && npm run duplication && npm run test -- --coverage && npm run format:check && npm audit --omit=dev --audit-level=high && npm run audit:dev-high && npm run check:ci-artifacts",
     "ci-verify:fast": "npm run type-check && npm run check:traceability && npm run duplication && jest --ci --bail --passWithNoTests --testPathPatterns 'tests/(rules|maintenance)'",
     "format": "prettier --write .",
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",

package/user-docs/api-reference.md

@@ -86,19 +86,19 @@ 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; more advanced path normalization strategies and selective toggles to enable or disable specific auto-fix behaviors are not yet implemented. You can also disable this suffix-normalization behavior explicitly via the `autoFix` option when you prefer purely diagnostic checks.
+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.
 
 Options:
 
 This rule accepts an optional configuration object. The primary configuration shape is **nested**:
 
 - `story` (object, optional) – Configuration for `@story` values.
-  - `pattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that all `@story` values must match. If provided, the rule validates each `@story` against this pattern in addition to its built‑in structural checks. By default, the plugin uses a pattern equivalent to `^docs/stories/.*\.story\.md$`, which matches a typical project convention such as `docs/stories/<name>.story.md`; you can override this to match however your own project organizes story files.
-  - `example` (string, optional) – A short example `@story` path shown in error messages when `story.pattern` is configured. The built-in default example is `"docs/stories/001.0-EXAMPLE.story.md"`, intended as a generic illustration of a project story file, and does not refer to this plugin’s internal documentation.
+  - `pattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that all `@story` values must match. If provided, the rule validates each `@story` against this pattern in addition to its built‑in structural checks. By default, the plugin uses a pattern equivalent to `^docs/stories/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$`, which matches typical project conventions such as `docs/stories/005.0-DEV-EXAMPLE.story.md`; you can override this to match however your own project organizes story files.
+  - `example` (string, optional) – A short example `@story` path shown in error messages when `story.pattern` is configured. The built-in default example is `"docs/stories/005.0-DEV-EXAMPLE.story.md"`, intended as a generic illustration of a project story file, and does not refer to this plugin’s internal documentation.
 - `req` (object, optional) – Configuration for `@req` values.
-  - `pattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that all `@req` values must match. If provided, the rule validates each `@req` identifier against this pattern. Defaults to the value returned by `getDefaultReqPattern()`, which is equivalent to `^REQ-[A-Z0-9_-]+$`, matching IDs such as `REQ-USER-AUTH` or `REQ-1234`.
-  - `example` (string, optional) – A short example requirement ID shown in error messages when `req.pattern` is configured. Defaults to the value returned by `getDefaultReqExample()`, `"REQ-USER-AUTH"`. This value is used **only** for guidance and does not affect validation.
-- `autoFix` (boolean, optional) – When set to `false`, disables all automatic suffix-normalization fixes while keeping validation and error messages intact. When omitted or `true`, the rule continues to apply safe suffix-only auto-fixes in `--fix` mode.
+  - `pattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that all `@req` values must match. If provided, the rule validates each `@req` identifier against this pattern. Defaults to the value returned by `getDefaultReqPattern()`, which is equivalent to `^REQ-[A-Z0-9-]+$`, matching IDs such as `REQ-USER-AUTH` or `REQ-1234`.
+  - `example` (string, optional) – A short example requirement ID shown in error messages when `req.pattern` is configured. Defaults to the value returned by `getDefaultReqExample()`, `"REQ-EXAMPLE"`. This value is used **only** for guidance and does not affect validation.
+- `autoFix` (boolean, optional) – When set to `false`, disables all automatic suffix-normalization fixes while keeping validation and error messages intact. When omitted or `true`, the rule continues to apply safe `@story` suffix-only auto-fixes in `--fix` mode.
 
 For backward compatibility, the rule also supports **flat shorthand** fields that map directly to the nested properties:
 
@@ -113,6 +113,8 @@ Behavior notes:
 - When options are omitted, the rule behaves exactly as in earlier versions, relying on its built‑in defaults and path‑suffix normalization logic only.
 - The pattern checks are additional validation; they do not change the existing auto‑fix behavior, which remains limited to safe `@story` suffix normalization described above.
 
+You can customize these validations to match your own naming conventions by overriding `story.pattern`/`storyPathPattern` and `req.pattern`/`requirementIdPattern`. This is useful when you store stories outside `docs/stories`, avoid `DEV` in filenames, or use a different requirement ID scheme instead of the default `REQ-...` format. Any custom values must still be valid JavaScript regular expression **sources** (without surrounding `/` characters).
+
 #### Migration and mixed usage
 
 The `valid-annotation-format` rule is intentionally **backward compatible** with existing code that only uses `@story` and `@req`. You can:
@@ -210,16 +212,18 @@ The rule accepts an optional configuration object:
 - `testFilePatterns` (string[], optional) – **Path-substring patterns** used to identify test files. For each file, the rule normalizes the file path to use forward slashes and then checks whether it contains at least one of the configured pattern strings. This is intentionally simpler than full glob matching and avoids adding extra runtime dependencies. Defaults to `["/tests/", "/test/", "/__tests__", ".test.", ".spec."]`. For most projects, these defaults behave like "any file under a `tests` or `test` directory, or any file whose name includes `.test.` or `.spec.`". If you prefer a different layout, supply custom substrings that uniquely identify your test files.
 - `requireDescribeStory` (boolean, optional) – When `true` (default), requires that each top-level `describe` block include a story reference somewhere in its description text (for example, a path such as `docs/stories/010.0-PAYMENTS.story.md` or a shorter project-specific alias that your team uses consistently).
 - `requireTestReqPrefix` (boolean, optional) – When `true` (default), requires each `it`/`test` block name to begin with a requirement identifier in square brackets, such as `[REQ-PAYMENTS-REFUND]`. The exact `REQ-` pattern is shared with the `valid-annotation-format` rule’s requirement ID checks.
-- `describePattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that the `describe` description text must match when `requireDescribeStory` is enabled. This lets you enforce a project-specific format such as requiring a canonical story path or a `STORY-` style identifier in the `describe` string. If omitted, a built-in default that loosely matches a typical story path (similar to `docs/stories/<name>.story.md`) is used.
+- `describePattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that the `describe` description text must match when `requireDescribeStory` is enabled. This lets you enforce a project-specific format such as requiring a canonical story path or a `STORY-` style identifier in the `describe` string. If omitted, the default is equivalent to `"Story [0-9]+\\.[0-9]+-"`, which expects the description to include a story label such as `"Story 021.0-DEV-TEST-TRACEABILITY"`. You can override this to instead require full story paths or whatever story-labeling convention your project prefers.
 - `autoFixTestTemplate` (boolean, optional) – When `true` (default), allows the rule’s `--fix` mode to insert a file-level `@supports` placeholder template at the top of test files that are missing it. The template is intentionally non-semantic and includes TODO-style guidance so humans can later replace it with a real story path and requirement IDs; disabling this option prevents the rule from inserting the template automatically.
 - `autoFixTestPrefixFormat` (boolean, optional) – When `true` (default), enables safe normalization of malformed `[REQ-XXX]` prefixes in `it`/`test` names during `--fix`. The rule only rewrites prefixes that already contain a recognizable requirement identifier and limits changes to formatting concerns (spacing, square brackets vs. parentheses, underscore and dash usage, and letter casing) without fabricating new IDs or guessing requirement names.
 - `testSupportsTemplate` (string, optional) – Overrides the default file-level `@supports` placeholder template used when `autoFixTestTemplate` is enabled. This string should be a complete JSDoc-style block (for example, including `/**`, `*`, and `*/`) that encodes your project’s preferred TODO guidance or placeholder story path; it is inserted verbatim at the top of matching test files that lack a `@supports` annotation, and is never interpreted or expanded by the rule.
 
+You can tune these options to fit your own testing and naming conventions: adjust `testFilePatterns` to match your project’s test layout (including monorepos or non-standard folders), override `describePattern` if you prefer full `docs/stories/...` paths or a different story-labeling scheme in `describe` strings, and change `requireTestReqPrefix` and `autoFixTestPrefixFormat` if you want to relax, enforce, or customize the `[REQ-...]` prefix requirements for test names.
+
 Behavior notes:
 
 - The rule only analyzes files whose normalized paths contain at least one of the `testFilePatterns` substrings.
 - File-level `@supports` annotations are typically placed in a JSDoc block at the top of the file; the rule checks that at least one `@supports` tag is present and that it includes a story/requirement reference (for example, `@supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND`).
-- Top-level `describe` calls (such as `describe("payments refunds docs/stories/010.0-PAYMENTS.story.md", ...)`) are inspected when `requireDescribeStory` is `true`. Their first argument must be a string literal that satisfies `describePattern`.
+- Top-level `describe` calls (such as `describe("Story 010.0-DEV-PAYMENTS", ...)`) are inspected when `requireDescribeStory` is `true`. Their first argument must be a string literal that satisfies `describePattern`.
 - Test cases declared via `it(...)` or `test(...)` must use a string literal name beginning with a requirement prefix like `[REQ-PAYMENTS-REFUND]` when `requireTestReqPrefix` is `true`.
 
 Default Severity: `error`
@@ -242,6 +246,109 @@ describe("Refunds flow docs/stories/010.0-PAYMENTS.story.md", () => {
 });
 ```
 
+### traceability/prefer-implements-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.
+
+Options: None – this rule does not accept a configuration object. All tuning is done via the ESLint rule level (`"off"`, `"warn"`, `"error"`).
+
+This rule focuses on **single‑story** legacy blocks where automatic migration is unambiguous. It inspects JSDoc comments attached to function‑like constructs and looks for the following patterns:
+
+- A single `@story` annotation with one story path.
+- One or more simple `@req` lines in the same block (each with a single requirement ID).
+- No `@supports` annotations yet present in that block.
+
+When these conditions are met, the rule recommends replacing the legacy block with a single `@supports` line that encodes the same relationship between the story and its requirements.
+
+Main behaviors:
+
+1. **Single‑story legacy blocks → `preferImplements` (auto‑fixable)**  
+   When a JSDoc block contains exactly one `@story` path and one or more simple `@req` identifiers, and no `@supports` tags, the rule reports a `preferImplements` diagnostic. In `--fix` mode, and when it is safe to do so, it rewrites the block to a consolidated `@supports` annotation of the form:
+
+   ```js
+   /**
+    * @supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND REQ-PAYMENTS-EDGE
+    */
+   ```
+
+   Conceptually, the auto‑fix:
+   - Extracts the single `@story` value.
+   - Collects the requirement IDs from each `@req` line in that block.
+   - Emits a single `@supports story-path#REQ-1 REQ-2 ...` line (or your project’s equivalent anchor scheme).
+
+   All legacy `@story` and `@req` tags in that block are removed as part of the fix, since their meaning is now captured by the `@supports` line. The fix is only applied when the story path and requirement IDs are straightforward to parse; complex or ambiguous shapes are left for manual migration.
+
+2. **Mixed usage with existing `@supports` → `cannotAutoFix` (manual migration)**  
+   If a JSDoc block already contains at least one `@supports` annotation **and** still has legacy `@story`/`@req` tags, the rule treats this as a mixed‑style block. In this case, it reports a `cannotAutoFix` diagnostic that includes a human‑readable `reason` explaining that the block already uses `@supports` and must be cleaned up manually.
+
+   The rule **does not** attempt to merge or rewrite mixed blocks automatically, to avoid guessing your intended story/requirement grouping. All annotations in such blocks are left unchanged; you are expected to convert them to your preferred `@supports` shape by hand.
+
+3. **Multiple distinct `@story` paths → `multiStoryDetected` (manual migration)**  
+   When the same JSDoc block contains **multiple different `@story` paths**, the rule reports a `multiStoryDetected` diagnostic and leaves the block unchanged. This scenario usually indicates integration code that implements requirements from several stories, and the correct multi-story `@supports` representation depends on how your project organizes those relationships.
+
+   Because there is no universally safe way to automatically group requirements across multiple stories, the rule does **not** attempt any auto‑fix in this case. Instead, it highlights the block so humans can migrate it to one or more explicit `@supports` annotations following your multi‑story conventions.
+
+Deliberate non‑targets and ignored comments:
+
+- JSDoc blocks that contain **only** `@story`, **only** `@req`, or **only** `@supports` are **not** modified by this rule. They remain valid and continue to be governed solely by the core rules such as `require-story-annotation`, `require-req-annotation`, and `valid-annotation-format`.
+- Inline or line comments like `// @story ...`, `// @req ...`, or `// @supports ...` are intentionally ignored by this migration helper; they are still checked by the underlying validation rules where applicable.
+- Any block that does not match the “single story + simple requirements, no supports” shape is treated conservatively: the rule may report a diagnostic to flag the legacy/mixed pattern, but it will not rewrite comments unless it is clearly safe.
+
+Interaction with other rules:
+
+- Enabling this rule does **not** change what is required or permitted by:
+  - `traceability/valid-annotation-format`
+  - `traceability/valid-req-reference`
+  - `traceability/require-story-annotation`
+  - `traceability/require-req-annotation`
+- All existing `@story` + `@req` blocks that pass those rules are still valid when this rule is off. Turning it on simply adds a migration layer that nudges you toward the consolidated `@supports` style and, where unambiguous, performs structural rewrites on your behalf.
+
+Example: single‑story auto‑fix
+
+Given this legacy JSDoc block:
+
+```js
+/**
+ * @story docs/stories/010.0-PAYMENTS.story.md
+ * @req REQ-PAYMENTS-REFUND
+ * @req REQ-PAYMENTS-REFUND-EDGE
+ */
+function issueRefund() {
+  // ...
+}
+```
+
+With `traceability/prefer-implements-annotation` enabled and ESLint run with `--fix`, the rule rewrites it to:
+
+```js
+/**
+ * @supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND REQ-PAYMENTS-REFUND-EDGE
+ */
+function issueRefund() {
+  // ...
+}
+```
+
+All other function‑level rules (such as `require-story-annotation`, `require-req-annotation`, and `valid-annotation-format`) continue to validate the resulting `@supports` annotation according to your existing configuration.
+
+Configuration example (opt‑in at `"warn"`):
+
+```js
+// eslint.config.js (flat config)
+import js from "@eslint/js";
+import traceability from "eslint-plugin-traceability";
+
+export default [
+  js.configs.recommended,
+  traceability.configs.recommended,
+  {
+    rules: {
+      "traceability/prefer-implements-annotation": "warn",
+    },
+  },
+];
+```
+
 ## Configuration Presets
 
 The plugin provides two built-in presets for easy configuration:

package/user-docs/examples.md

@@ -84,7 +84,7 @@ Create a Jest test file, for example `tests/dev-test-traceability.spec.ts`:
  * @supports docs/stories/021.0-DEV-TEST-TRACEABILITY.story.md#REQ-TEST-TRACEABILITY
  */
 
-describe("docs/stories/021.0-DEV-TEST-TRACEABILITY.story.md", () => {
+describe("Story 021.0-DEV-TEST-TRACEABILITY", () => {
   it("[REQ-TEST-TRACEABILITY] should handle the primary test scenario", () => {
     // Arrange
     const input = "happy-path";

package/user-docs/migration-guide.md

@@ -73,8 +73,41 @@ For teams that want to gradually migrate from `@story` + `@req` to `@supports`,
   }
   ```
 
-- When enabled, it offers **conservative auto-fixes** that rewrite eligible `@story` + `@req` combinations into equivalent `@supports` lines, without attempting risky or ambiguous transformations.
-- Detailed behavior, limitations, and examples are documented in the project’s internal rule documentation, which is primarily intended for maintainers; most users can rely on this guide and the API reference for day-to-day usage.
+This rule is an **optional migration aid**, not a deprecation notice. `@story` and `@req` remain fully supported, and there is no hard requirement or deadline to migrate existing annotations. Use the rule only where `@supports` gives you clearer, multi-story traceability.
+
+When enabled, it offers **conservative auto-fixes** that rewrite eligible `@story` + `@req` combinations into equivalent `@supports` lines, without attempting risky or ambiguous transformations. It intentionally refuses to modify comments that are even slightly unclear, and will instead surface diagnostics that explain what needs manual attention.
+
+Aligned with the internal rule behavior, the key cases are:
+
+- **Simple, single-story JSDoc blocks**  
+  For comments that contain exactly one `@story` path and one or more simple `@req` lines, the rule:
+  - Reports a recommendation to consolidate them, and
+  - In `--fix` mode, converts them into a single `@supports` line that keeps the same story path and requirement IDs.
+
+- **Mixed `@story` / `@req` plus existing `@supports`**  
+  For comments that already contain one or more `@supports` lines alongside `@story` and/or `@req`, the rule:
+  - Reports a diagnostic explaining that mixed usage cannot be auto-fixed safely, and
+  - Leaves the comment unchanged so you can decide how to migrate it manually.
+
+- **Multiple distinct `@story` paths**  
+  For comments that refer to more than one different `@story` path, the rule:
+  - Reports that multiple stories were detected, and
+  - Requires you to manually convert them into separate `@supports` lines (one per story path, each followed by the appropriate requirement IDs).
+
+- **Intentionally ignored comments**  
+  The following are **ignored** by this rule and remain valid:
+  - Comments that contain only `@story` lines,
+  - Comments that contain only `@req` lines,
+  - Comments that contain only `@supports` lines, and
+  - Line comments such as `// @story ...`.
+
+  These forms are still supported by the plugin and are not modified by `traceability/prefer-implements-annotation`.
+
+A typical migration path is:
+
+- Start with the rule set to `"off"` while you introduce `@supports` in new or refactored code.
+- Enable it as `"warn"` to get non-breaking guidance and auto-fixes for straightforward cases.
+- Optionally move to `"error"` once you want to strictly enforce `@supports` usage for all JSDoc blocks that are eligible for safe conversion.
 
 #### When to keep `@story` + `@req`