eslint-plugin-traceability 1.16.1 → 1.17.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.16.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.16.0...v1.16.1) (2025-12-09)
+# [1.17.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.16.1...v1.17.0) (2025-12-09)
 
 
-### Bug Fixes
+### Features
 
-* broaden test callback exclusion coverage for function annotations ([8078745](https://github.com/voder-ai/eslint-plugin-traceability/commit/80787455dcba39724158f378fce54ae78a75b59b))
+* allow configuring additional excluded test helper callbacks ([d266197](https://github.com/voder-ai/eslint-plugin-traceability/commit/d26619721b1826fe97d01a63647f07505e35c846))
 
 # Changelog
 

package/lib/src/rules/helpers/require-story-helpers.d.ts

@@ -11,21 +11,17 @@ import type { Rule } from "eslint";
 import { linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory } from "./require-story-io";
 import { getNodeName } from "./require-story-utils";
 import { DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, STORY_PATH } from "./require-story-core";
+import { type CallbackExclusionOptions } from "./test-callback-exclusion";
 /**
  * Shared configuration helpers
  */
-interface ReportOptions {
+interface ReportOptions extends CallbackExclusionOptions {
     annotationTemplateOverride?: string;
     autoFixToggle?: boolean;
-    excludeTestCallbacks?: boolean;
 }
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-declare function getAnnotationTemplate(override?: string, _options?: {
-    excludeTestCallbacks?: boolean;
-}): string;
-declare function shouldApplyAutoFix(autoFix: boolean | undefined, _options?: {
-    excludeTestCallbacks?: boolean;
-}): boolean;
+declare function getAnnotationTemplate(override?: string, _options?: CallbackExclusionOptions): string;
+declare function shouldApplyAutoFix(autoFix: boolean | undefined, _options?: CallbackExclusionOptions): boolean;
 /**
  * Determine if a node is in an export declaration
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -70,9 +66,7 @@ declare function resolveTargetNode(sourceCode: any, node: any): any;
  */
 declare function extractName(node: any): string;
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-declare function shouldProcessNode(node: any, scope: string[], exportPriority?: string, options?: {
-    excludeTestCallbacks?: boolean;
-}): boolean;
+declare function shouldProcessNode(node: any, scope: string[], exportPriority?: string, options?: CallbackExclusionOptions): boolean;
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 declare function reportMissing(context: Rule.RuleContext, sourceCode: any, config: {
     node: any;

package/lib/src/rules/helpers/require-story-helpers.js

@@ -23,38 +23,7 @@ const require_story_core_1 = require("./require-story-core");
 Object.defineProperty(exports, "DEFAULT_SCOPE", { enumerable: true, get: function () { return require_story_core_1.DEFAULT_SCOPE; } });
 Object.defineProperty(exports, "EXPORT_PRIORITY_VALUES", { enumerable: true, get: function () { return require_story_core_1.EXPORT_PRIORITY_VALUES; } });
 Object.defineProperty(exports, "STORY_PATH", { enumerable: true, get: function () { return require_story_core_1.STORY_PATH; } });
-/**
- * Known test framework function names and variants.
- * Includes Jest, Mocha, Vitest and their focused/skipped/concurrent variants.
- * @req REQ-TEST-CALLBACK-EXCLUSION
- */
-const TEST_FUNCTION_NAMES = new Set([
-    // Core test/describe-style functions (Jest, Mocha, Vitest share many of these)
-    "it",
-    "test",
-    "describe",
-    "suite",
-    // Focused variants
-    "fit",
-    "ftest",
-    "fdescribe",
-    "fsuite",
-    // Skipped variants
-    "xit",
-    "xtest",
-    "xdescribe",
-    "xsuite",
-    // Additional common aliases
-    "context",
-    "specify",
-    "before",
-    "after",
-    "beforeEach",
-    "afterEach",
-    "beforeAll",
-    "afterAll",
-]);
-const TEST_FUNCTION_CONCURRENT_PROP = "concurrent";
+const test_callback_exclusion_1 = require("./test-callback-exclusion");
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function getAnnotationTemplate(override, _options) {
     if (typeof override === "string" && override.trim().length > 0) {
@@ -74,9 +43,13 @@ function shouldApplyAutoFix(autoFix, _options) {
  */
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function buildTemplateConfig(options) {
-    const effectiveTemplate = getAnnotationTemplate(options?.annotationTemplateOverride, { excludeTestCallbacks: options?.excludeTestCallbacks });
+    const effectiveTemplate = getAnnotationTemplate(options?.annotationTemplateOverride, {
+        excludeTestCallbacks: options?.excludeTestCallbacks,
+        additionalTestHelperNames: options?.additionalTestHelperNames,
+    });
     const allowFix = shouldApplyAutoFix(options?.autoFixToggle, {
         excludeTestCallbacks: options?.excludeTestCallbacks,
+        additionalTestHelperNames: options?.additionalTestHelperNames,
     });
     return { effectiveTemplate, allowFix };
 }
@@ -123,46 +96,6 @@ function isEffectivelyAnonymousFunction(node) {
     }
     return true;
 }
-/**
- * Determine whether a node represents a callback passed to a known test
- * framework function (Jest, Mocha, Vitest, etc).
- *
- * Supports:
- * - it(), test(), describe(), suite(), context(), specify()
- * - lifecycle hooks: before(), after(), beforeEach(), afterEach(), beforeAll(), afterAll()
- * - focused variants: fit(), ftest(), fdescribe(), fsuite()
- * - skipped variants and helpers: xit(), xtest(), xdescribe(), xsuite()
- * - their .concurrent variants (e.g., it.concurrent(), test.concurrent())
- *
- * @req REQ-TEST-CALLBACK-EXCLUSION
- */
-function isTestFrameworkCallback(node, options) {
-    if (options?.excludeTestCallbacks === false) {
-        return false;
-    }
-    if (!node || node.type !== "ArrowFunctionExpression") {
-        return false;
-    }
-    const parent = node.parent;
-    if (!parent || parent.type !== "CallExpression") {
-        return false;
-    }
-    const callee = parent.callee;
-    if (callee.type === "Identifier") {
-        return TEST_FUNCTION_NAMES.has(callee.name);
-    }
-    if (callee.type === "MemberExpression" &&
-        !callee.computed &&
-        callee.property &&
-        callee.property.type === "Identifier" &&
-        callee.property.name === TEST_FUNCTION_CONCURRENT_PROP) {
-        const obj = callee.object;
-        if (obj && obj.type === "Identifier") {
-            return TEST_FUNCTION_NAMES.has(obj.name);
-        }
-    }
-    return false;
-}
 /**
  * Determine whether a function node is required to carry its own annotation
  * according to Story 004.0-DEV-BRANCH-ANNOTATIONS rules.
@@ -177,7 +110,7 @@ function isTestFrameworkCallback(node, options) {
  * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-ARROW-FUNCTION-EXCLUDED REQ-NESTED-FUNCTION-INHERITANCE
  */
 function requiresOwnFunctionAnnotation(node, options) {
-    if (isTestFrameworkCallback(node, options)) {
+    if ((0, test_callback_exclusion_1.isTestFrameworkCallback)(node, options)) {
         return false;
     }
     // Anonymous arrow functions used as callbacks are excluded from function-level

package/lib/src/rules/helpers/test-callback-exclusion.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared helpers for determining whether a function-like node should be
+ * treated as a test framework callback that may be excluded from
+ * function-level annotation requirements.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/013-exclude-test-framework-callbacks.proposed.md
+ * @req REQ-TEST-CALLBACK-EXCLUSION - Provide reusable test callback exclusion logic
+ */
+/**
+ * Options controlling how test callbacks are treated by the helpers.
+ *
+ * - excludeTestCallbacks: when false, no callbacks are excluded and all
+ *   function-like nodes are treated as regular functions.
+ * - additionalTestHelperNames: optional array of additional helper names that
+ *   should be treated like built-in test functions when excludeTestCallbacks
+ *   is enabled.
+ */
+interface CallbackExclusionOptions {
+    excludeTestCallbacks?: boolean;
+    additionalTestHelperNames?: string[];
+}
+/**
+ * Determine whether a node represents a callback passed to a known test
+ * framework function (Jest, Mocha, Vitest, etc).
+ *
+ * Supports:
+ * - it(), test(), describe(), suite(), context(), specify()
+ * - lifecycle hooks: before(), after(), beforeEach(), afterEach(), beforeAll(), afterAll()
+ * - focused variants: fit(), ftest(), fdescribe(), fsuite()
+ * - skipped variants and helpers: xit(), xtest(), xdescribe(), xsuite()
+ * - their .concurrent variants (e.g., it.concurrent(), test.concurrent())
+ *
+ * @req REQ-TEST-CALLBACK-EXCLUSION
+ */
+declare function isTestFrameworkCallback(node: any, options?: CallbackExclusionOptions): boolean;
+export type { CallbackExclusionOptions };
+export { isTestFrameworkCallback };

package/lib/src/rules/helpers/test-callback-exclusion.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Shared helpers for determining whether a function-like node should be
+ * treated as a test framework callback that may be excluded from
+ * function-level annotation requirements.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/013-exclude-test-framework-callbacks.proposed.md
+ * @req REQ-TEST-CALLBACK-EXCLUSION - Provide reusable test callback exclusion logic
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTestFrameworkCallback = isTestFrameworkCallback;
+/**
+ * Known test framework function names and variants.
+ * Includes Jest, Mocha, Vitest and their focused/skipped/concurrent variants.
+ *
+ * @req REQ-TEST-CALLBACK-EXCLUSION
+ */
+const TEST_FUNCTION_NAMES = new Set([
+    // Core test/describe-style functions (Jest, Mocha, Vitest share many of these)
+    "it",
+    "test",
+    "describe",
+    "suite",
+    // Focused variants
+    "fit",
+    "ftest",
+    "fdescribe",
+    "fsuite",
+    // Skipped variants
+    "xit",
+    "xtest",
+    "xdescribe",
+    "xsuite",
+    // Additional common aliases
+    "context",
+    "specify",
+    "before",
+    "after",
+    "beforeEach",
+    "afterEach",
+    "beforeAll",
+    "afterAll",
+]);
+const TEST_FUNCTION_CONCURRENT_PROP = "concurrent";
+/**
+ * Determine if a function name should be treated as a recognized test helper,
+ * including core test functions and any configured additional helper names.
+ *
+ * Vitest's `bench` is explicitly never treated as an excluded test callback,
+ * even if it appears in additionalTestHelperNames, to preserve the story
+ * requirement that bench callbacks always require annotations.
+ *
+ * @req REQ-TEST-CALLBACK-EXCLUSION
+ */
+function isRecognizedTestHelperName(name, options) {
+    if (name === "bench") {
+        return false;
+    }
+    if (TEST_FUNCTION_NAMES.has(name)) {
+        return true;
+    }
+    if (options?.additionalTestHelperNames &&
+        Array.isArray(options.additionalTestHelperNames)) {
+        return options.additionalTestHelperNames.includes(name);
+    }
+    return false;
+}
+/**
+ * Determine whether a node represents a callback passed to a known test
+ * framework function (Jest, Mocha, Vitest, etc).
+ *
+ * Supports:
+ * - it(), test(), describe(), suite(), context(), specify()
+ * - lifecycle hooks: before(), after(), beforeEach(), afterEach(), beforeAll(), afterAll()
+ * - focused variants: fit(), ftest(), fdescribe(), fsuite()
+ * - skipped variants and helpers: xit(), xtest(), xdescribe(), xsuite()
+ * - their .concurrent variants (e.g., it.concurrent(), test.concurrent())
+ *
+ * @req REQ-TEST-CALLBACK-EXCLUSION
+ */
+function isTestFrameworkCallback(node, options) {
+    if (options?.excludeTestCallbacks === false) {
+        return false;
+    }
+    if (!node || node.type !== "ArrowFunctionExpression") {
+        return false;
+    }
+    const parent = node.parent;
+    if (!parent || parent.type !== "CallExpression") {
+        return false;
+    }
+    const callee = parent.callee;
+    if (callee.type === "Identifier") {
+        return isRecognizedTestHelperName(callee.name, options);
+    }
+    if (callee.type === "MemberExpression" &&
+        !callee.computed &&
+        callee.property &&
+        callee.property.type === "Identifier" &&
+        callee.property.name === TEST_FUNCTION_CONCURRENT_PROP) {
+        const obj = callee.object;
+        if (obj && obj.type === "Identifier") {
+            return isRecognizedTestHelperName(obj.name, options);
+        }
+    }
+    return false;
+}

package/lib/src/rules/require-story-annotation.js

@@ -49,6 +49,11 @@ const rule = {
                     methodAnnotationTemplate: { type: "string" },
                     autoFix: { type: "boolean" },
                     excludeTestCallbacks: { type: "boolean" },
+                    additionalTestHelperNames: {
+                        type: "array",
+                        items: { type: "string" },
+                        uniqueItems: true,
+                    },
                 },
                 additionalProperties: false,
             },
@@ -79,6 +84,10 @@ const rule = {
         const excludeTestCallbacks = typeof opts.excludeTestCallbacks === "boolean"
             ? opts.excludeTestCallbacks
             : true;
+        const additionalTestHelperNames = Array.isArray(opts.additionalTestHelperNames) &&
+            opts.additionalTestHelperNames.every((name) => typeof name === "string")
+            ? opts.additionalTestHelperNames
+            : undefined;
         /**
          * Optional debug logging for troubleshooting this rule.
          * Developers can temporarily uncomment the block below to log when the rule
@@ -94,7 +103,10 @@ const rule = {
         //     : "<unknown>",
         // );
         // Local closure that binds configured scope and export priority to the helper.
-        const should = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority, { excludeTestCallbacks });
+        const should = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority, {
+            excludeTestCallbacks,
+            additionalTestHelperNames,
+        });
         // Delegate visitor construction to helper to keep this file concise.
         return (0, require_story_visitors_1.buildVisitors)(context, sourceCode, {
             shouldProcessNode: should,
@@ -104,6 +116,7 @@ const rule = {
             methodAnnotationTemplate,
             autoFix,
             excludeTestCallbacks,
+            additionalTestHelperNames,
         });
     },
 };

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

@@ -100,6 +100,11 @@ describe('Vitest suite', () => {
   bench('Vitest bench', () => {});
 });`,
             },
+            {
+                name: "[REQ-TEST-CALLBACK-EXCLUSION][Story 003.0] additionalTestHelperNames excludes configured helper callbacks when excludeTestCallbacks=true",
+                code: `withTestCase("does something", () => {});`,
+                options: [{ additionalTestHelperNames: ["withTestCase"] }],
+            },
         ],
         invalid: [
             {
@@ -216,6 +221,22 @@ describe('Vitest suite', () => {
                     },
                 ],
             },
+            {
+                name: "[REQ-TEST-CALLBACK-EXCLUSION][Story 003.0] bench callback still reported even when included in additionalTestHelperNames",
+                code: `bench("bench case", () => {});`,
+                options: [{ additionalTestHelperNames: ["bench"], 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: `bench("bench case", /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n() => {});`,
+                            },
+                        ],
+                    },
+                ],
+            },
         ],
     });
     ruleTester.run("require-story-annotation with exportPriority option", require_story_annotation_1.default, {

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

@@ -401,4 +401,73 @@ describe("Require Story Helpers (Story 003.0)", () => {
         });
         expect(result).toBeTruthy();
     });
+    /**
+     * Additional coverage for nested and helper-wrapped test callbacks.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-TEST-CALLBACK-EXCLUSION - Document how nested and wrapper-based callbacks interact with exclusion logic
+     */
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Nested anonymous arrow inside it() callback is excluded via nested-function inheritance", () => {
+        const outerCallback = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "it" },
+            },
+        };
+        const innerCallback = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "BlockStatement",
+                parent: outerCallback,
+            },
+        };
+        // Outer callback is treated as a test framework callback and excluded.
+        const outerResult = (0, require_story_helpers_1.shouldProcessNode)(outerCallback, require_story_helpers_1.DEFAULT_SCOPE);
+        // Inner anonymous arrow inherits from its nested parent and is also excluded.
+        const innerResult = (0, require_story_helpers_1.shouldProcessNode)(innerCallback, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(outerResult).toBeFalsy();
+        expect(innerResult).toBeFalsy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow callback passed to local wrapper around describe() is not treated as a test callback", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "withDescribe" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(result).toBeTruthy();
+    });
+    /**
+     * Additional coverage for configurable test helper names.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-TEST-CALLBACK-EXCLUSION - Verify additionalTestHelperNames interacts correctly with exclusion logic
+     */
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow callback passed to configured additionalTestHelperNames helper is excluded by default", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "withTest" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            additionalTestHelperNames: ["withTest"],
+        });
+        expect(result).toBeFalsy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] bench callback is never excluded even when included in additionalTestHelperNames", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "bench" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            additionalTestHelperNames: ["bench"],
+        });
+        expect(result).toBeTruthy();
+    });
 });

package/package.json

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