eslint-plugin-traceability 1.16.1 → 1.17.1

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.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.17.0...v1.17.1) (2025-12-10)
 
 
 ### Bug Fixes
 
-* broaden test callback exclusion coverage for function annotations ([8078745](https://github.com/voder-ai/eslint-plugin-traceability/commit/80787455dcba39724158f378fce54ae78a75b59b))
+* avoid redundant-annotation false positives for catch blocks ([2ac69e2](https://github.com/voder-ai/eslint-plugin-traceability/commit/2ac69e2a03b54cf29bf2bc175771bf3b23aba6e9))
 
 # Changelog
 

package/lib/src/index.js

@@ -86,61 +86,77 @@ RULE_NAMES.forEach(
  *   and diagnostics).
  *
  * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED REQ-CONFIGURABLE-SCOPE REQ-EXPORT-PRIORITY
+ * @supports docs/stories/010.4-DEV-UNIFIED-FUNCTION-RULE-AND-ALIASES.story.md REQ-UNIFIED-ALIAS-ENGINE
  */
-{
+function createAliasRuleMeta(unifiedRule, legacyRule) {
+    if (!legacyRule) {
+        return null;
+    }
+    const baseMeta = (unifiedRule.meta ?? {});
+    const legacyMeta = (legacyRule.meta ?? {});
+    return {
+        ...baseMeta,
+        ...legacyMeta,
+        docs: {
+            ...(baseMeta.docs ?? {}),
+            ...(legacyMeta.docs ?? {}),
+        },
+        messages: {
+            ...(baseMeta.messages ?? {}),
+            ...(legacyMeta.messages ?? {}),
+        },
+        schema: legacyMeta.schema ??
+            baseMeta.schema ??
+            [],
+        hasSuggestions: legacyMeta.hasSuggestions ??
+            baseMeta.hasSuggestions,
+        fixable: legacyMeta.fixable ??
+            baseMeta.fixable,
+        deprecated: legacyMeta.deprecated ??
+            baseMeta.deprecated,
+        replacedBy: legacyMeta.replacedBy ??
+            baseMeta.replacedBy,
+        type: legacyMeta.type ??
+            baseMeta.type ??
+            "problem",
+    };
+}
+/**
+ * Wire up the unified `require-traceability` rule and its legacy alias rules
+ * so that they share the same implementation while preserving legacy metadata.
+ *
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED REQ-EXPORT-PRIORITY
+ * @supports docs/stories/010.4-DEV-UNIFIED-FUNCTION-RULE-AND-ALIASES.story.md REQ-UNIFIED-ALIAS-ENGINE
+ */
+function wireUnifiedFunctionAnnotationAliases() {
     const unifiedRule = rules["require-traceability"];
     const legacyStoryRule = rules["require-story-annotation"];
     const legacyReqRule = rules["require-req-annotation"];
     if (unifiedRule) {
         const createAliasRule = (legacyRule) => {
-            if (!legacyRule) {
+            const mergedMeta = createAliasRuleMeta(unifiedRule, legacyRule);
+            if (!mergedMeta) {
                 return unifiedRule;
             }
-            const baseMeta = (unifiedRule.meta ?? {});
-            const legacyMeta = (legacyRule.meta ?? {});
-            const mergedMeta = {
-                ...baseMeta,
-                ...legacyMeta,
-                docs: {
-                    ...(baseMeta.docs ?? {}),
-                    ...(legacyMeta.docs ?? {}),
-                },
-                messages: {
-                    ...(baseMeta.messages ?? {}),
-                    ...(legacyMeta.messages ?? {}),
-                },
-                schema: legacyMeta.schema ??
-                    baseMeta.schema ??
-                    [],
-                hasSuggestions: legacyMeta.hasSuggestions ??
-                    baseMeta.hasSuggestions,
-                fixable: legacyMeta.fixable ??
-                    baseMeta.fixable,
-                deprecated: legacyMeta.deprecated ??
-                    baseMeta.deprecated,
-                replacedBy: legacyMeta.replacedBy ??
-                    baseMeta.replacedBy,
-                type: legacyMeta.type ??
-                    baseMeta.type ??
-                    "problem",
-            };
-            const aliasRule = {
+            return {
                 ...unifiedRule,
                 meta: mergedMeta,
                 create: unifiedRule.create,
             };
-            return aliasRule;
         };
         rules["require-story-annotation"] = createAliasRule(legacyStoryRule);
         rules["require-req-annotation"] = createAliasRule(legacyReqRule);
     }
 }
+wireUnifiedFunctionAnnotationAliases();
 /**
  * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-RULE-NAME
  * Wire up traceability/prefer-supports-annotation as the primary rule name and
  * traceability/prefer-implements-annotation as its deprecated alias.
+ *
+ * @supports docs/stories/010.4-DEV-UNIFIED-FUNCTION-RULE-AND-ALIASES.story.md REQ-MIGRATION-RULE-NAMING
  */
-{
+function wirePreferSupportsAlias() {
     const implementsRule = rules["prefer-implements-annotation"];
     if (implementsRule) {
         const originalMeta = implementsRule.meta ?? {};
@@ -163,6 +179,7 @@ RULE_NAMES.forEach(
         }
     }
 }
+wirePreferSupportsAlias();
 /**
  * Plugin metadata used by ESLint for debugging and caching.
  *
@@ -226,6 +243,9 @@ const TRACEABILITY_RULE_SEVERITIES = {
  * @req REQ-ERROR-SEVERITY - Map rule types to appropriate ESLint severity levels (errors vs warnings)
  * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
  * @req REQ-CONFIG-PRESETS - Provide flat-config presets that self-register the plugin and core rules
+ *
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SEVERITY
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md REQ-CONFIG-PRESETS
  */
 function createTraceabilityFlatConfig() {
     return {

package/lib/src/maintenance/commands.d.ts

@@ -7,6 +7,7 @@ export declare const EXIT_USAGE = 2;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
  * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
  */
 export declare function handleDetect(normalized: NormalizedCliArgs): number;
 /**
@@ -14,6 +15,7 @@ export declare function handleDetect(normalized: NormalizedCliArgs): number;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
  * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY REQ-MAINT-SAFE
  */
 export declare function handleVerify(normalized: NormalizedCliArgs): number;
 /**
@@ -21,6 +23,7 @@ export declare function handleVerify(normalized: NormalizedCliArgs): number;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
  * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 export declare function handleReport(normalized: NormalizedCliArgs): number;
 /**
@@ -28,5 +31,6 @@ export declare function handleReport(normalized: NormalizedCliArgs): number;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
  * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE REQ-MAINT-SAFE
  */
 export declare function handleUpdate(normalized: NormalizedCliArgs): number;

package/lib/src/maintenance/commands.js

@@ -28,6 +28,7 @@ exports.EXIT_USAGE = 2;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
  * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
  */
 function handleDetect(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
@@ -54,6 +55,7 @@ Run 'traceability-maint report' for a structured summary.`);
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
  * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY REQ-MAINT-SAFE
  */
 function handleVerify(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
@@ -71,6 +73,7 @@ function handleVerify(normalized) {
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
  * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 function handleReport(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
@@ -96,6 +99,7 @@ function handleReport(normalized) {
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - CLI surface for updating annotation references
  * @req REQ-MAINT-SAFE - Provide dry-run mode and explicit parameter checks
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE REQ-MAINT-SAFE
  */
 function handleUpdate(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);

package/lib/src/maintenance/index.d.ts

@@ -7,6 +7,7 @@
  * @req REQ-MAINT-VERIFY
  * @req REQ-MAINT-REPORT
  * @req REQ-MAINT-SAFE
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-UPDATE REQ-MAINT-BATCH REQ-MAINT-VERIFY REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 export { detectStaleAnnotations } from "./detect";
 export { updateAnnotationReferences } from "./update";

package/lib/src/maintenance/index.js

@@ -10,6 +10,7 @@ exports.generateMaintenanceReport = exports.verifyAnnotations = exports.batchUpd
  * @req REQ-MAINT-VERIFY
  * @req REQ-MAINT-REPORT
  * @req REQ-MAINT-SAFE
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-UPDATE REQ-MAINT-BATCH REQ-MAINT-VERIFY REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 var detect_1 = require("./detect");
 Object.defineProperty(exports, "detectStaleAnnotations", { enumerable: true, get: function () { return detect_1.detectStaleAnnotations; } });

package/lib/src/maintenance/report.js

@@ -12,8 +12,8 @@ const detect_1 = require("./detect");
  */
 function generateMaintenanceReport(codebasePath) {
     const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);
-    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-SAFE - When no stale annotations are found, return empty string to indicate no actions required
-    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-REPORT - When stale annotations exist, produce a newline-separated report
+    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE - When no stale annotations are found, return empty string to indicate no actions required
+    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT - When stale annotations exist, produce a newline-separated report
     if (staleAnnotations.length === 0) {
         return "";
     }

package/lib/src/maintenance/update.js

@@ -40,6 +40,7 @@ const utils_1 = require("./utils");
  * Helper to process a single file for annotation reference updates
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
  */
 function processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCountRef) {
     const content = fs.readFileSync(fullPath, "utf8"); // getAllFiles already returns regular files
@@ -78,8 +79,7 @@ function updateAnnotationReferences(codebasePath, oldPath, newPath) {
      * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
      * @req REQ-MAINT-UPDATE
      */
-    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-    // @req REQ-MAINT-UPDATE
+    // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
     if (!fs.existsSync(codebasePath) ||
         !fs.statSync(codebasePath).isDirectory()) {
         return 0;
@@ -92,11 +92,13 @@ function updateAnnotationReferences(codebasePath, oldPath, newPath) {
      * Iterate over all files and replace annotation references
      * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
      * @req REQ-MAINT-UPDATE
+     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
      */
     /**
      * Loop over each discovered file path
      * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
      * @req REQ-MAINT-UPDATE
+     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
      */
     for (const fullPath of files) {
         processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCountRef);

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,43 @@
+/**
+ * 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
+ */
+import type { TSESTree } from "@typescript-eslint/utils";
+/**
+ * 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[];
+}
+type TraceabilityNodeWithParent = TSESTree.Node & {
+    parent?: TraceabilityNodeWithParent | null;
+};
+/**
+ * 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: TraceabilityNodeWithParent | null | undefined, options?: CallbackExclusionOptions): boolean;
+export type { CallbackExclusionOptions };
+export { isTestFrameworkCallback };

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

@@ -0,0 +1,100 @@
+"use strict";
+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 callExpressionParent = parent;
+    const callee = callExpressionParent.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/helpers/valid-annotation-format-validators.js

@@ -175,8 +175,8 @@ function validateStoryAnnotation(context, comment, rawValue, options) {
         return;
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-PATH-FORMAT - Reject @story values containing internal whitespace as invalid
-    if (/\s/.test(trimmed)) {
+    // @req REQ-PATH-FORMAT - Reject @story values containing internal whitespace that do not collapse into a valid story path
+    if (/\s/.test(trimmed) && !pathPattern.test(collapsed)) {
         reportInvalidStoryFormat(context, comment, collapsed, options);
         return;
     }
@@ -223,6 +223,12 @@ function validateReqAnnotation(context, comment, rawValue, options) {
         return;
     }
     const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
+    // Allow mixed @req/@supports lines to pass without additional @req validation,
+    // while still validating simple multi-line @req identifiers that collapse
+    // to a single token.
+    if (collapsed.includes("@supports")) {
+        return;
+    }
     const reqPattern = options.reqPattern;
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
     // @req REQ-REQ-FORMAT - Flag @req identifiers that do not match the configured pattern

package/lib/src/rules/no-redundant-annotation.js

@@ -326,6 +326,10 @@ const rule = {
                 if (process.env.TRACEABILITY_DEBUG === "1") {
                     console.log("[no-redundant-annotation] BlockStatement parent=%s statements=%d", parent && parent.type, Array.isArray(node.body) ? node.body.length : 0);
                 }
+                // @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-CATCH-BLOCK-HANDLING
+                if (parent && parent.type === "CatchClause") {
+                    return;
+                }
                 const scopePairs = collectScopePairs(context, parent, options.maxScopeDepth);
                 debugScopePairs(parent, scopePairs);
                 if (scopePairs.size === 0)