eslint-plugin-traceability 1.15.0 → 1.16.1

package/lib/src/rules/require-traceability.js

@@ -27,21 +27,20 @@ const rule = {
     meta: {
         type: "problem",
         docs: {
-            description: "Require @story and @req (or @supports) annotations on functions and methods",
+            description: "Require both story and requirement traceability annotations on functions and methods via the unified alias rule",
             recommended: "error",
         },
-        hasSuggestions: Boolean(storyRule.meta?.hasSuggestions) ||
-            Boolean(reqRule.meta?.hasSuggestions),
-        fixable: (storyRule.meta && storyRule.meta.fixable) ||
-            (reqRule.meta && reqRule.meta.fixable) ||
-            undefined,
+        hasSuggestions: true,
+        fixable: undefined,
         messages: {
+            // Unified messageId for potential future direct use by this rule.
+            missingTraceability: "Function '{{name}}' must declare both story and requirement traceability annotations.",
+            // Preserve underlying rule messageIds so that composed listeners can
+            // continue to report using their original IDs.
             ...(storyRule.meta?.messages ?? {}),
             ...(reqRule.meta?.messages ?? {}),
         },
-        schema: (storyRule.meta && storyRule.meta.schema) ??
-            (reqRule.meta && reqRule.meta.schema) ??
-            [],
+        schema: [],
     },
     create(context) {
         const storyListeners = storyRule.create(context) || {};

package/lib/src/utils/annotation-checker.js

@@ -119,17 +119,19 @@ function getNameNodeForReqReport(node) {
     return node;
 }
 /**
- * Helper to report a missing @req annotation via the ESLint context API.
- * Uses getNodeName to provide a readable name for the node.
+ * Helper to build the report options object for missing traceability annotations.
+ * Uses getNodeName to provide a readable name for the node. @supports is the
+ * preferred format for expressing traceability to one or more requirements and
+ * stories, while @req is treated as a legacy shorthand for single-story usage.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
- * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
+ * @req REQ-ANNOTATION-REPORTING - Report missing traceability annotations to context
  * @req REQ-ERROR-SPECIFIC - Provide specific error details including node name
  * @req REQ-ERROR-LOCATION - Include contextual location information in errors
  * @req REQ-ERROR-SUGGESTION - Provide actionable suggestions or fixes where possible
  * @req REQ-ERROR-CONTEXT - Include contextual hints to help understand the error
  */
-function reportMissing(context, node, enableFix = true) {
+function buildMissingReqReportOptions(node, enableFix) {
     const parentNode = node?.parent;
     const name = getReportedName(node, parentNode);
     const nameNode = getNameNodeForReqReport(node);
@@ -144,6 +146,23 @@ function reportMissing(context, node, enableFix = true) {
     if (enableFix) {
         reportOptions.fix = createMissingReqFix(node);
     }
+    return reportOptions;
+}
+/**
+ * Helper to report missing traceability annotations via the ESLint context API.
+ * Uses getNodeName to provide a readable name for the node. @supports is the
+ * preferred format for expressing traceability to one or more requirements and
+ * stories, while @req is treated as a legacy shorthand for single-story usage.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ANNOTATION-REPORTING - Report missing traceability annotations to context
+ * @req REQ-ERROR-SPECIFIC - Provide specific error details including node name
+ * @req REQ-ERROR-LOCATION - Include contextual location information in errors
+ * @req REQ-ERROR-SUGGESTION - Provide actionable suggestions or fixes where possible
+ * @req REQ-ERROR-CONTEXT - Include contextual hints to help understand the error
+ */
+function reportMissing(context, node, enableFix = true) {
+    const reportOptions = buildMissingReqReportOptions(node, enableFix);
     context.report(reportOptions);
 }
 /**

package/lib/tests/cli-error-handling.test.js

@@ -11,12 +11,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
+const originalNodePath = process.env.NODE_PATH;
 describe("CLI Error Handling for Traceability Plugin (Story 001.0-DEV-PLUGIN-SETUP)", () => {
     beforeAll(() => {
         // Simulate missing plugin build by deleting lib directory (if exist)
         // In tests, assume plugin built to lib/src/index.js; point plugin import to src/index.ts via env
         process.env.NODE_PATH = path_1.default.resolve(__dirname, "../src");
     });
+    afterAll(() => {
+        if (originalNodePath === undefined) {
+            delete process.env.NODE_PATH;
+        }
+        else {
+            process.env.NODE_PATH = originalNodePath;
+        }
+    });
     it("[REQ-ERROR-HANDLING] should exit with error when rule module missing", () => {
         const eslintPkgDir = path_1.default.dirname(require.resolve("eslint/package.json"));
         const eslintCliPath = path_1.default.join(eslintPkgDir, "bin", "eslint.js");
@@ -40,6 +49,6 @@ describe("CLI Error Handling for Traceability Plugin (Story 001.0-DEV-PLUGIN-SET
         });
         // Expect non-zero exit and missing annotation message on stdout
         expect(result.status).not.toBe(0);
-        expect(result.stdout).toContain("Function 'foo' must have an explicit @story annotation. Add a JSDoc or line comment with @story that points to the implementing story file, such as docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md");
+        expect(result.stdout).toContain("Function 'foo' must declare a traceability annotation. Prefer adding an @supports line that links this function to at least one story (for example, '@supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED'), or, when you only need a single-story reference, add a legacy @story annotation that points to the implementing story file, such as docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md");
     });
 });

package/lib/tests/integration/cli-integration.test.js

@@ -33,6 +33,7 @@ describe("CLI Integration (Story 001.0-DEV-PLUGIN-SETUP)", () => {
             name: "does not report error when @story annotation is present",
             code: `/**
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
  */
 function foo() {}`,
             rule: "traceability/require-story-annotation:error",
@@ -65,6 +66,10 @@ function baz() {}`,
             expectedStatus: 1,
         },
     ];
+    /**
+     * Helper to run ESLint CLI with a single rule for integration tests
+     * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE
+     */
     function runEslint(code, rule) {
         const args = [
             "--no-config-lookup",

package/lib/tests/integration/require-traceability-aliases.integration.test.js

@@ -0,0 +1,126 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Integration tests for unified require-traceability rule and its legacy aliases.
+ *
+ * @supports docs/stories/010.4-DEV-UNIFIED-FUNCTION-RULE-AND-ALIASES.story.md REQ-UNIFIED-ALIAS-ENGINE REQ-SUPPORTS-FIRST-MODEL REQ-PRESETS-CANONICAL-RULE
+ */
+const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
+const index_1 = __importStar(require("../../src/index"));
+async function lintTextWithConfig(text, filename, extraConfig) {
+    const baseConfig = {
+        plugins: {
+            traceability: index_1.default,
+        },
+    };
+    const eslint = new use_at_your_own_risk_1.FlatESLint({
+        overrideConfig: [baseConfig, ...extraConfig],
+        overrideConfigFile: true,
+        ignore: false,
+    });
+    const [result] = await eslint.lintText(text, { filePath: filename });
+    return result;
+}
+describe("Unified require-traceability and aliases integration (Story 010.4-DEV-UNIFIED-FUNCTION-RULE-AND-ALIASES)", () => {
+    const codeMissingAll = "function foo() {}";
+    const codeWithSupportsOnly = `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction foo() {}`;
+    const codeWithStoryAndReq = `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction foo() {}`;
+    async function getDiagnosticsForRule(ruleKey, code) {
+        const config = [
+            {
+                rules: {
+                    [ruleKey]: "error",
+                },
+            },
+        ];
+        const result = await lintTextWithConfig(code, "example.js", config);
+        return result.messages.map((m) => ({
+            ruleId: m.ruleId,
+            messageId: m.messageId,
+        }));
+    }
+    it("[REQ-UNIFIED-ALIAS-ENGINE] canonical and alias keys all report missing traceability on unannotated function", async () => {
+        const ruleKeys = [
+            "traceability/require-traceability",
+            "traceability/require-story-annotation",
+            "traceability/require-req-annotation",
+        ];
+        const results = await Promise.all(ruleKeys.map((ruleKey) => getDiagnosticsForRule(ruleKey, codeMissingAll)));
+        results.forEach((messages, index) => {
+            const ruleKey = ruleKeys[index];
+            expect(messages.length).toBeGreaterThan(0);
+            messages.forEach((msg) => {
+                expect(msg.ruleId).toBe(ruleKey);
+            });
+        });
+    });
+    it("[REQ-SUPPORTS-FIRST-MODEL] @supports-only annotation satisfies all three rule keys", async () => {
+        const ruleKeys = [
+            "traceability/require-traceability",
+            "traceability/require-story-annotation",
+            "traceability/require-req-annotation",
+        ];
+        const results = await Promise.all(ruleKeys.map((ruleKey) => getDiagnosticsForRule(ruleKey, codeWithSupportsOnly)));
+        results.forEach((messages) => {
+            expect(messages).toHaveLength(0);
+        });
+    });
+    it("[REQ-SUPPORTS-FIRST-MODEL] @story + @req annotation satisfies all three rule keys", async () => {
+        const ruleKeys = [
+            "traceability/require-traceability",
+            "traceability/require-story-annotation",
+            "traceability/require-req-annotation",
+        ];
+        const results = await Promise.all(ruleKeys.map((ruleKey) => getDiagnosticsForRule(ruleKey, codeWithStoryAndReq)));
+        results.forEach((messages) => {
+            expect(messages).toHaveLength(0);
+        });
+    });
+    it("[REQ-PRESETS-CANONICAL-RULE] recommended preset surfaces unified and legacy diagnostics together for missing annotations", async () => {
+        const result = await lintTextWithConfig(codeMissingAll, "example.js", index_1.configs.recommended);
+        const ruleIds = result.messages.map((m) => m.ruleId).sort();
+        expect(ruleIds).toContain("traceability/require-traceability");
+        expect(ruleIds).toContain("traceability/require-story-annotation");
+        expect(ruleIds).toContain("traceability/require-req-annotation");
+    });
+    it("[REQ-PRESETS-CANONICAL-RULE] strict preset surfaces unified and legacy diagnostics together for missing annotations", async () => {
+        const result = await lintTextWithConfig(codeMissingAll, "example.js", index_1.configs.strict);
+        const ruleIds = result.messages.map((m) => m.ruleId).sort();
+        expect(ruleIds).toContain("traceability/require-traceability");
+        expect(ruleIds).toContain("traceability/require-story-annotation");
+        expect(ruleIds).toContain("traceability/require-req-annotation");
+    });
+});

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

@@ -95,4 +95,27 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
         const recommendedRules = index_1.configs.recommended[0].rules;
         expect(strictRules).toEqual(recommendedRules);
     });
+    describe("Unified function-annotation rule aliases (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
+        it("[REQ-ANNOTATION-REQUIRED] legacy rule names share the unified require-traceability implementation", () => {
+            const unified = index_1.rules["require-traceability"];
+            const storyAlias = index_1.rules["require-story-annotation"];
+            const reqAlias = index_1.rules["require-req-annotation"];
+            expect(typeof unified.create).toBe("function");
+            expect(storyAlias.create).toBe(unified.create);
+            expect(reqAlias.create).toBe(unified.create);
+        });
+        it("[REQ-CONFIGURABLE-SCOPE] alias rules preserve metadata needed for configuration and diagnostics", () => {
+            const unified = index_1.rules["require-traceability"];
+            const storyAlias = index_1.rules["require-story-annotation"];
+            const reqAlias = index_1.rules["require-req-annotation"];
+            // All variants should expose a schema and messages map so that options
+            // like scope/exportPriority and the core diagnostics remain available.
+            expect(unified.meta?.schema).toBeDefined();
+            expect(storyAlias.meta?.schema).toBeDefined();
+            expect(reqAlias.meta?.schema).toBeDefined();
+            expect(unified.meta?.messages).toBeDefined();
+            expect(storyAlias.meta?.messages).toBeDefined();
+            expect(reqAlias.meta?.messages).toBeDefined();
+        });
+    });
 });

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

@@ -46,7 +46,7 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                             messageId: "missingStory",
                             suggestions: [
                                 {
-                                    desc: "Add JSDoc @story annotation for function 'autoFixMe', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    desc: "Add traceability annotation for function 'autoFixMe' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
                                     output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction autoFixMe() {}`,
                                 },
                             ],
@@ -62,7 +62,7 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                             messageId: "missingStory",
                             suggestions: [
                                 {
-                                    desc: "Add JSDoc @story annotation for function 'fnExpr', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    desc: "Add traceability annotation for function 'fnExpr' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
                                     output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
                                 },
                             ],
@@ -78,7 +78,7 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                             messageId: "missingStory",
                             suggestions: [
                                 {
-                                    desc: "Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    desc: "Add traceability annotation for function 'method' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
                                     output: `class C {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
                                 },
                             ],
@@ -98,7 +98,7 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                             messageId: "missingStory",
                             suggestions: [
                                 {
-                                    desc: "Add JSDoc @story annotation for function 'tsDecl', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    desc: "Add traceability annotation for function 'tsDecl' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
                                     output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
                                 },
                             ],
@@ -118,7 +118,7 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                             messageId: "missingStory",
                             suggestions: [
                                 {
-                                    desc: "Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    desc: "Add traceability annotation for function 'method' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
                                     output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ninterface D {\n  method(): void;\n}`,
                                 },
                             ],
@@ -220,7 +220,7 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                             messageId: "missingStory",
                             suggestions: [
                                 {
-                                    desc: "Add JSDoc @story annotation for function 'needsFixOnce', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    desc: "Add traceability annotation for function 'needsFixOnce' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
                                     output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction needsFixOnce() {}`,
                                 },
                             ],
@@ -236,7 +236,7 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                             messageId: "missingStory",
                             suggestions: [
                                 {
-                                    desc: "Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    desc: "Add traceability annotation for function 'method' using @supports (preferred) or @story (legacy), for example: /** @supports 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}`,
                                 },
                             ],

package/lib/tests/rules/error-reporting.test.js

@@ -91,7 +91,7 @@ describe("Error Reporting Enhancements for require-story-annotation (Story 007.0
             expect(Array.isArray(error.suggest)).toBe(true);
             expect(error.suggest.length).toBeGreaterThanOrEqual(1);
             const suggestion = error.suggest[0];
-            expect(suggestion.desc).toBe("Add JSDoc @story annotation for function 'bar', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */");
+            expect(suggestion.desc).toBe("Add traceability annotation for function 'bar' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */");
             expect(suggestion.fix).toBeDefined();
         });
     });

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

@@ -29,6 +29,14 @@ describe("no-redundant-annotation rule (Story 027.0-DEV-REDUNDANT-ANNOTATION-DET
                 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}`,
             },
+            {
+                name: "[REQ-SUPPORTS-COVERAGE] preserves non-redundant mixed @supports/@req pairs when only partially covered by scope",
+                code: `function example() {\n  /**\n   * @story docs/stories/010.0-EXAMPLE.story.md\n   * @req REQ-FN-LEVEL\n   * @supports REQ-SHARED\n   */\n  if (flag) {\n    // @story docs/stories/010.0-EXAMPLE.story.md\n    // @req REQ-BRANCH-SPECIFIC\n    // @supports REQ-SHARED\n    doThing();\n  }\n}`,
+            },
+            {
+                name: "[REQ-SCOPE-ANALYSIS] preserves annotations on both branch and statement when they intentionally duplicate each other",
+                code: `function example() {\n  if (condition) { // @story docs/stories/007.0-EXAMPLE.story.md @req REQ-BRANCH\n    // @story docs/stories/007.0-EXAMPLE.story.md\n    // @req REQ-BRANCH\n    doBranchWork();\n  }\n}`,
+            },
         ],
         invalid: [
             {
@@ -67,6 +75,18 @@ describe("no-redundant-annotation rule (Story 027.0-DEV-REDUNDANT-ANNOTATION-DET
                 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" }],
             },
+            {
+                name: "[REQ-SCOPE-INHERITANCE] flags redundant statement annotation when scopePairs come from parent function JSDoc",
+                code: `/**\n * @story docs/stories/008.0-EXAMPLE.story.md\n * @req REQ-FUNC\n */\nfunction example() {\n  // @story docs/stories/008.0-EXAMPLE.story.md\n  // @req REQ-FUNC\n  const result = compute();\n}`,
+                output: `/**\n * @story docs/stories/008.0-EXAMPLE.story.md\n * @req REQ-FUNC\n */\nfunction example() {\n  const result = compute();\n}`,
+                errors: [{ messageId: "redundantAnnotation" }],
+            },
+            {
+                name: "[REQ-SUPPORTS-COVERAGE][REQ-DUPLICATION-DETECTION] flags redundant statement with multiple fully-covered @supports pairs",
+                code: `/**\n * @story docs/stories/009.0-EXAMPLE.story.md\n * @supports REQ-SUP-A, REQ-SUP-B\n */\nfunction example() {\n  // @story docs/stories/009.0-EXAMPLE.story.md\n  // @supports REQ-SUP-A, REQ-SUP-B\n  const supported = checkSupport();\n}`,
+                output: `/**\n * @story docs/stories/009.0-EXAMPLE.story.md\n * @supports REQ-SUP-A, REQ-SUP-B\n */\nfunction example() {\n  const supported = checkSupport();\n}`,
+                errors: [{ messageId: "redundantAnnotation" }],
+            },
             // TODO: rule implementation exists; full invalid-case behavior tests pending refinement
             // {
             //   name: "[REQ-SCOPE-ANALYSIS][REQ-STATEMENT-SIGNIFICANCE] flags redundant annotation on simple return inside annotated if",

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

@@ -65,6 +65,41 @@ declare function tsDecl(): void;`,
                 name: "[REQ-NESTED-FUNCTION-INHERITANCE] anonymous inner function inherits outer annotation",
                 code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction outer() {\n  const inner = function() {\n    return 1;\n  };\n  return inner();\n}`,
             },
+            {
+                name: "[REQ-TEST-CALLBACK-EXCLUSION][Story 003.0] default exclusion of Jest-style anonymous test callbacks",
+                code: `/**
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-TEST-CALLBACK-EXCLUSION
+ */
+describe('Feature X', () => {
+  it('does something', () => {});
+});
+
+// Mocha-style suite/context/specify examples
+suite('Mocha suite', () => {
+  beforeEach(() => {});
+  afterEach(() => {});
+  before(() => {});
+  after(() => {});
+
+  test('Mocha test', () => {});
+  specify('Mocha specify', () => {});
+  context('Mocha context', () => {
+    it('nested it', () => {});
+  });
+});
+
+// Vitest-style APIs including hooks and bench
+describe('Vitest suite', () => {
+  beforeEach(() => {});
+  afterEach(() => {});
+  beforeAll(() => {});
+  afterAll(() => {});
+
+  it('Vitest it', () => {});
+  test('Vitest test', () => {});
+  bench('Vitest bench', () => {});
+});`,
+            },
         ],
         invalid: [
             {
@@ -77,7 +112,7 @@ declare function tsDecl(): void;`,
                         messageId: "missingStory",
                         suggestions: [
                             {
-                                desc: `Add JSDoc @story annotation for function 'bar', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                desc: `Add traceability annotation for function 'bar' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
                                 output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}`,
                             },
                         ],
@@ -93,7 +128,7 @@ declare function tsDecl(): void;`,
                         messageId: "missingStory",
                         suggestions: [
                             {
-                                desc: `Add JSDoc @story annotation for function 'fnExpr', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                desc: `Add traceability annotation for function 'fnExpr' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
                                 output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
                             },
                         ],
@@ -110,7 +145,7 @@ declare function tsDecl(): void;`,
                         data: { name: "method", functionName: "method" },
                         suggestions: [
                             {
-                                desc: `Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                desc: `Add traceability annotation for function 'method' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
                                 output: `class C {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
                             },
                         ],
@@ -126,7 +161,7 @@ declare function tsDecl(): void;`,
                         messageId: "missingStory",
                         suggestions: [
                             {
-                                desc: `Add JSDoc @story annotation for function 'tsDecl', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                desc: `Add traceability annotation for function 'tsDecl' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
                                 output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
                             },
                         ],
@@ -142,7 +177,7 @@ declare function tsDecl(): void;`,
                         messageId: "missingStory",
                         suggestions: [
                             {
-                                desc: `Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                desc: `Add traceability annotation for function 'method' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
                                 output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ninterface D {\n  method(): void;\n}`,
                             },
                         ],
@@ -158,7 +193,7 @@ declare function tsDecl(): void;`,
                         messageId: "missingStory",
                         suggestions: [
                             {
-                                desc: `Add JSDoc @story annotation for function 'handler', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                desc: `Add traceability annotation for function 'handler' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
                                 output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst handler = () => {};`,
                             },
                         ],
@@ -174,7 +209,7 @@ declare function tsDecl(): void;`,
                         messageId: "missingStory",
                         suggestions: [
                             {
-                                desc: `Add JSDoc @story annotation for function 'innerNamed', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                desc: `Add traceability annotation for function 'innerNamed' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
                                 output: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction outer() {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction innerNamed() {\n    return 1;\n  }\n  return innerNamed();\n}`,
                             },
                         ],
@@ -207,7 +242,7 @@ declare function tsDecl(): void;`,
                         messageId: "missingStory",
                         suggestions: [
                             {
-                                desc: `Add JSDoc @story annotation for function 'exportedMissing', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                desc: `Add traceability annotation for function 'exportedMissing' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
                                 output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nexport function exportedMissing() {}`,
                             },
                         ],
@@ -224,7 +259,7 @@ declare function tsDecl(): void;`,
                         messageId: "missingStory",
                         suggestions: [
                             {
-                                desc: `Add JSDoc @story annotation for function 'arrowExported', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                desc: `Add traceability annotation for function 'arrowExported' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
                                 output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nexport const arrowExported = () => {};`,
                             },
                         ],
@@ -252,7 +287,7 @@ declare function tsDecl(): void;`,
                         messageId: "missingStory",
                         suggestions: [
                             {
-                                desc: `Add JSDoc @story annotation for function 'onlyDecl', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                desc: `Add traceability annotation for function 'onlyDecl' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
                                 output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction onlyDecl() {}`,
                             },
                         ],
@@ -261,4 +296,34 @@ declare function tsDecl(): void;`,
             },
         ],
     });
+    ruleTester.run("require-story-annotation with excludeTestCallbacks option", require_story_annotation_1.default, {
+        valid: [
+            {
+                name: "[REQ-TEST-CALLBACK-EXCLUSION][Story 003.0] non-test arrow function annotated when excludeTestCallbacks=false",
+                code: `/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ */
+const handler = () => {};`,
+                options: [{ excludeTestCallbacks: false }],
+            },
+        ],
+        invalid: [
+            {
+                name: "[REQ-TEST-CALLBACK-EXCLUSION][Story 003.0] Jest-style it() callback requires annotation when excludeTestCallbacks=false",
+                code: `it('does something', () => {});`,
+                options: [{ excludeTestCallbacks: false, autoFix: false }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add traceability annotation for function '(anonymous)' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `it('does something', /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n() => {});`,
+                            },
+                        ],
+                    },
+                ],
+            },
+        ],
+    });
 });