eslint-plugin-traceability 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.15.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.14.1...v1.15.0) (2025-12-08)
+# [1.16.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.15.0...v1.16.0) (2025-12-09)
 
 
 ### Features
 
-* add unified require-traceability rule and exports ([c92ce8f](https://github.com/voder-ai/eslint-plugin-traceability/commit/c92ce8f467cc4968dc2dea2abb0927eca08c9ace))
+* add excludeTestCallbacks option for test framework callbacks ([108510d](https://github.com/voder-ai/eslint-plugin-traceability/commit/108510d361f45c9ff75118ee266970dcbabd3fb8))
 
 # Changelog
 

package/README.md

@@ -46,16 +46,59 @@ export default [
 ];
 ```
 
+### Canonical function-level rule and legacy aliases
+
+For function-level checks, `traceability/require-traceability` is the **canonical** rule. It ensures that in-scope functions and methods have both story coverage and requirement coverage, and it understands both the modern `@supports` format and the legacy `@story` / `@req` pairs.
+
+The older rule keys:
+
+- `traceability/require-story-annotation`
+- `traceability/require-req-annotation`
+
+remain available as **backward-compatible aliases** that are wired to the same underlying engine. Existing configurations that reference these legacy keys will continue to behave as before. New configurations should normally prefer the unified `traceability/require-traceability` rule and treat the legacy keys as compatibility shims or for gradual migration.
+
+A concise flat-config example that enables the unified function-level rule and commonly used supporting rules explicitly:
+
+```js
+// eslint.config.js
+import traceability from "eslint-plugin-traceability";
+
+export default [
+  {
+    plugins: {
+      traceability,
+    },
+    rules: {
+      // Canonical function-level rule (preferred for new configs)
+      "traceability/require-traceability": "error",
+
+      // Common supporting rules
+      "traceability/require-branch-annotation": "warn",
+      "traceability/valid-annotation-format": "error",
+      "traceability/valid-story-reference": "error",
+      "traceability/valid-req-reference": "error",
+
+      // Optional: enforce test traceability conventions
+      "traceability/require-test-traceability": "warn",
+    },
+  },
+];
+```
+
 ### Available Rules
 
-- `traceability/require-story-annotation` Enforces presence of `@story` annotations. (See the rule documentation in the plugin's user guide.)
-- `traceability/require-req-annotation` Enforces presence of `@req` annotations. (See the rule documentation in the plugin's user guide.)
-- `traceability/require-branch-annotation` Enforces presence of branch annotations. (See the rule documentation in the plugin's user guide.)
-- `traceability/valid-annotation-format` Enforces correct format of traceability annotations. (See the rule documentation in the plugin's user guide.)
-- `traceability/valid-story-reference` Validates that `@story` references point to existing story files. (See the rule documentation in the plugin's user guide.)
-- `traceability/valid-req-reference` Validates that `@req` references point to existing requirement IDs. (See the rule documentation in the plugin's user guide.)
-- `traceability/require-test-traceability` Enforces traceability conventions in test files by requiring file-level `@supports` annotations, story references in `describe` blocks, and `[REQ-...]` prefixes in `it`/`test` names. (See the rule documentation in the plugin's user guide.)
-- `traceability/prefer-supports-annotation` Recommends migration from legacy `@story`/`@req` annotations to `@supports` (opt-in; disabled by default in the presets and must be explicitly enabled). The legacy rule name `traceability/prefer-implements-annotation` remains available as a deprecated alias. (See the rule documentation in the plugin's user guide.)
+The plugin exposes several rules. For **new configurations**, the unified function-level rule and `@supports` annotations are the canonical choice; the `@story` and `@req` forms remain available primarily for backward compatibility and gradual migration.
+
+- `traceability/require-traceability` – **Unified function-level traceability rule.** Ensures that in-scope functions and methods have both story coverage and requirement coverage. It accepts either `@supports` (preferred for new code) or legacy `@story` / `@req` annotations and is enabled by default in the plugin's `recommended` and `strict` presets.
+- `traceability/require-story-annotation` – Legacy function-level rule key that focuses on the **story** side of function-level traceability. It is kept for backward compatibility and is wired to the same underlying engine as `traceability/require-traceability`, so existing configurations that refer to this rule continue to work. New configurations should normally rely on `traceability/require-traceability` instead of enabling this rule directly.
+- `traceability/require-req-annotation` – Legacy function-level rule key that focuses on the **requirement** side of function-level traceability. Like `traceability/require-story-annotation`, it is retained for backward compatibility and conceptually composes the same checks exposed by `traceability/require-traceability`. New configurations can usually rely on the unified rule alone unless you have specific reasons to tune the legacy keys separately.
+- `traceability/require-branch-annotation` – Enforces presence of branch annotations on significant control-flow branches (if/else, switch cases, loops, try/catch). Branch annotations can use a single `@supports` line (preferred) or the older `@story`/`@req` pair for backward compatibility. (See the rule documentation in the plugin's user guide.)
+- `traceability/valid-annotation-format` – Enforces correct format of traceability annotations, including `@supports` (preferred), `@story`, and `@req`. (See the rule documentation in the plugin's user guide.)
+- `traceability/valid-story-reference` – Validates that story references (whether written via `@story` or embedded in `@supports`) point to existing story files. (See the rule documentation in the plugin's user guide.)
+- `traceability/valid-req-reference` – Validates that requirement identifiers (whether written via `@req` or embedded in `@supports`) point to existing requirement IDs in your story files. (See the rule documentation in the plugin's user guide.)
+- `traceability/require-test-traceability` – Enforces traceability conventions in test files by requiring file-level `@supports` annotations, story references in `describe` blocks, and `[REQ-...]` prefixes in `it`/`test` names. (See the rule documentation in the plugin's user guide.)
+- `traceability/no-redundant-annotation` – Detects and optionally removes redundant traceability annotations on simple leaf statements that are already covered by an enclosing annotated scope. It is enabled at severity `warn` in both the `recommended` and `strict` presets by default; consumers can override its severity (including promoting it to `error`) or disable it explicitly in their ESLint configuration if they prefer.
+- `traceability/prefer-supports-annotation` – Optional migration helper that recommends converting legacy single-story `@story`/`@req` JSDoc blocks and inline comments into the newer `@supports` format. It is disabled by default and must be explicitly enabled. The legacy rule name `traceability/prefer-implements-annotation` remains available as a deprecated alias. (See the rule documentation in the plugin's user guide.)
 
 Configuration options: For detailed per-rule options (such as scopes, branch types, and story directory settings), see the individual rule docs in the plugin's user guide and the consolidated [API Reference](user-docs/api-reference.md).
 
@@ -83,15 +126,17 @@ export default [
 
 ```js
 /**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- *   // Point this to your own project's story/requirements file, not to this plugin's internal docs.
- * @req REQ-ANNOTATION-REQUIRED
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED
+ *   // Prefer @supports for new implementations; @story/@req remain supported for
+ *   // legacy and simple single-story code paths.
  */
 function initAuth() {
   // implementation...
 }
 ```
 
+`@supports` is the canonical format for new, multi-story integrations and richer traceability. The legacy `@story` and `@req` forms are kept for backward compatibility and remain appropriate for simple, single-story functions or where a gradual migration is preferred.
+
 3. Run ESLint:
 
 ```bash
@@ -148,10 +193,12 @@ For a full description of options and JSON payloads, see the [Maintenance API an
 You can validate the plugin by running ESLint CLI with the plugin on a sample file:
 
 ```bash
-# Validate missing @story annotation (should report an error)
-npx eslint --no-eslintrc --config eslint.config.js sample.js --rule 'traceability/require-story-annotation:error'
+# Validate missing function-level traceability (should report an error)
+npx eslint --no-eslintrc --config eslint.config.js sample.js --rule 'traceability/require-traceability:error'
 ```
 
+If you have existing configurations that reference the legacy function-level keys, you can also validate them directly by enabling `traceability/require-story-annotation` and `traceability/require-req-annotation` instead.
+
 This command runs ESLint with the plugin, pointing at `eslint.config.js` flat config.
 
 Replace `sample.js` with your JavaScript or TypeScript file.
@@ -237,6 +284,7 @@ For the canonical, user-facing security policy (including how to report vulnerab
 - ESLint v9 Setup Guide: [user-docs/eslint-9-setup-guide.md](user-docs/eslint-9-setup-guide.md)
 - API Reference: [user-docs/api-reference.md](user-docs/api-reference.md)
 - Examples: [user-docs/examples.md](user-docs/examples.md)
+- Traceability Overview and FAQ: [user-docs/traceability-overview.md](user-docs/traceability-overview.md)
 - Migration Guide: [user-docs/migration-guide.md](user-docs/migration-guide.md)
 - Full README: <https://github.com/voder-ai/eslint-plugin-traceability#readme>
 - Contribution guide: <https://github.com/voder-ai/eslint-plugin-traceability/blob/main/CONTRIBUTING.md>

package/lib/src/index.js

@@ -76,6 +76,65 @@ RULE_NAMES.forEach(
         };
     }
 });
+/**
+ * Wire up the unified function-annotation rule and its backward-compatible
+ * aliases so that:
+ * - traceability/require-traceability is the canonical rule implementation
+ * - traceability/require-story-annotation and
+ *   traceability/require-req-annotation act as aliases that share the same
+ *   underlying logic while preserving their legacy metadata (docs, schema,
+ *   and diagnostics).
+ *
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED REQ-CONFIGURABLE-SCOPE REQ-EXPORT-PRIORITY
+ */
+{
+    const unifiedRule = rules["require-traceability"];
+    const legacyStoryRule = rules["require-story-annotation"];
+    const legacyReqRule = rules["require-req-annotation"];
+    if (unifiedRule) {
+        const createAliasRule = (legacyRule) => {
+            if (!legacyRule) {
+                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 = {
+                ...unifiedRule,
+                meta: mergedMeta,
+                create: unifiedRule.create,
+            };
+            return aliasRule;
+        };
+        rules["require-story-annotation"] = createAliasRule(legacyStoryRule);
+        rules["require-req-annotation"] = createAliasRule(legacyReqRule);
+    }
+}
 /**
  * @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

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

@@ -133,7 +133,7 @@ function createMissingStoryReportDescriptor(config) {
         fix: allowFix ? baseFix : undefined,
         suggest: [
             {
-                desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
+                desc: `Add traceability annotation for function '${name}' using @supports (preferred) or @story (legacy), for example: ${effectiveTemplate.replace("@story", "@supports")}`,
                 fix: baseFix,
             },
         ],

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

@@ -17,10 +17,15 @@ import { DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, STORY_PATH } from "./require-sto
 interface ReportOptions {
     annotationTemplateOverride?: string;
     autoFixToggle?: boolean;
+    excludeTestCallbacks?: boolean;
 }
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-declare function getAnnotationTemplate(override?: string): string;
-declare function shouldApplyAutoFix(autoFix: boolean | undefined): boolean;
+declare function getAnnotationTemplate(override?: string, _options?: {
+    excludeTestCallbacks?: boolean;
+}): string;
+declare function shouldApplyAutoFix(autoFix: boolean | undefined, _options?: {
+    excludeTestCallbacks?: boolean;
+}): boolean;
 /**
  * Determine if a node is in an export declaration
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -65,7 +70,9 @@ 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): boolean;
+declare function shouldProcessNode(node: any, scope: string[], exportPriority?: string, options?: {
+    excludeTestCallbacks?: boolean;
+}): 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,14 +23,31 @@ 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([
+    "it",
+    "test",
+    "describe",
+    "fit",
+    "xit",
+    "ftest",
+    "xtest",
+    "fdescribe",
+    "xdescribe",
+]);
+const TEST_FUNCTION_CONCURRENT_PROP = "concurrent";
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-function getAnnotationTemplate(override) {
+function getAnnotationTemplate(override, _options) {
     if (typeof override === "string" && override.trim().length > 0) {
         return override.trim();
     }
     return `/** @story ${require_story_core_1.STORY_PATH} */`;
 }
-function shouldApplyAutoFix(autoFix) {
+function shouldApplyAutoFix(autoFix, _options) {
     if (autoFix === false) {
         return false;
     }
@@ -42,8 +59,10 @@ function shouldApplyAutoFix(autoFix) {
  */
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function buildTemplateConfig(options) {
-    const effectiveTemplate = getAnnotationTemplate(options?.annotationTemplateOverride);
-    const allowFix = shouldApplyAutoFix(options?.autoFixToggle);
+    const effectiveTemplate = getAnnotationTemplate(options?.annotationTemplateOverride, { excludeTestCallbacks: options?.excludeTestCallbacks });
+    const allowFix = shouldApplyAutoFix(options?.autoFixToggle, {
+        excludeTestCallbacks: options?.excludeTestCallbacks,
+    });
     return { effectiveTemplate, allowFix };
 }
 /**
@@ -89,6 +108,43 @@ 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(), fit(), xit(), ftest(), xtest(), fdescribe(), xdescribe()
+ * - 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.
@@ -102,7 +158,10 @@ function isEffectivelyAnonymousFunction(node) {
  *
  * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-ARROW-FUNCTION-EXCLUDED REQ-NESTED-FUNCTION-INHERITANCE
  */
-function requiresOwnFunctionAnnotation(node) {
+function requiresOwnFunctionAnnotation(node, options) {
+    if (isTestFrameworkCallback(node, options)) {
+        return false;
+    }
     // Anonymous arrow functions used as callbacks are excluded from function-level
     // requirements when they are nested inside another function or method.
     if (isAnonymousArrowFunction(node) &&
@@ -306,12 +365,12 @@ function extractName(node) {
     return "(anonymous)";
 }
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-function shouldProcessNode(node, scope, exportPriority = "all") {
+function shouldProcessNode(node, scope, exportPriority = "all", options) {
     if (node &&
         (node.type === "FunctionDeclaration" ||
             node.type === "FunctionExpression" ||
             node.type === "ArrowFunctionExpression") &&
-        !requiresOwnFunctionAnnotation(node)) {
+        !requiresOwnFunctionAnnotation(node, options)) {
         return false;
     }
     if (!scope.includes(node.type)) {

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

@@ -48,49 +48,13 @@ function normalizeOptions(raw) {
     };
 }
 /**
- * Compute the story/requirement pairs for annotations that apply to the
- * given scope node.
- *
- * For branch scopes we reuse the same comment-gathering helper used by
- * the require-branch-annotation rule so that REQ-SCOPE-INHERITANCE
- * aligns with existing behavior.
+ * Collect comments around a scope node using JSDoc, leading comments,
+ * and any comments that appear immediately before the node.
  *
  * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE
  */
-function getScopePairs(context, scopeNode, parent) {
-    const sourceCode = context.getSourceCode();
-    // Branch-style scope: use the branch helpers to collect comment text.
-    if (branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES.includes(scopeNode.type)) {
-        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent);
-        return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(text);
-    }
-    // Function-like scopes: collect from JSDoc and leading/before comments
-    const FUNCTION_LIKE_TYPES = new Set([
-        "FunctionDeclaration",
-        "FunctionExpression",
-        "ArrowFunctionExpression",
-        "MethodDefinition",
-        "TSDeclareFunction",
-        "TSMethodSignature",
-    ]);
+function getScopeCommentsFromJSDocAndLeading(sourceCode, scopeNode) {
     const comments = [];
-    if (FUNCTION_LIKE_TYPES.has(scopeNode.type)) {
-        const jsdoc = sourceCode.getJSDocComment
-            ? sourceCode.getJSDocComment(scopeNode)
-            : null;
-        const before = sourceCode.getCommentsBefore
-            ? sourceCode.getCommentsBefore(scopeNode) || []
-            : [];
-        if (jsdoc) {
-            comments.push(jsdoc);
-        }
-        if (Array.isArray(scopeNode.leadingComments)) {
-            comments.push(...scopeNode.leadingComments);
-        }
-        comments.push(...before);
-        return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(comments);
-    }
-    // Fallback: inspect JSDoc and leading comments around the scope node.
     const jsdoc = sourceCode.getJSDocComment
         ? sourceCode.getJSDocComment(scopeNode)
         : null;
@@ -104,6 +68,28 @@ function getScopePairs(context, scopeNode, parent) {
         comments.push(...scopeNode.leadingComments);
     }
     comments.push(...before);
+    return comments;
+}
+/**
+ * Compute the story/requirement pairs for annotations that apply to the
+ * given scope node.
+ *
+ * For branch scopes we reuse the same comment-gathering helper used by
+ * the require-branch-annotation rule so that REQ-SCOPE-INHERITANCE
+ * aligns with existing behavior. For non-branch scopes, we reuse a
+ * shared helper that collects JSDoc, leading, and immediately-before
+ * comments around the scope node.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE
+ */
+function getScopePairs(context, scopeNode, parent) {
+    const sourceCode = context.getSourceCode();
+    // Branch-style scope: use the branch helpers to collect comment text.
+    if (branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES.includes(scopeNode.type)) {
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, scopeNode, parent);
+        return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromText)(text);
+    }
+    const comments = getScopeCommentsFromJSDocAndLeading(sourceCode, scopeNode);
     return (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(comments);
 }
 /**
@@ -162,14 +148,12 @@ function collectScopePairs(context, startingScopeNode, maxScopeDepth) {
     return result;
 }
 /**
- * Determine whether a statement is redundant relative to the provided
- * scopePairs and options, and when so return the associated annotation
- * comments. Returns null when the statement should not be treated as
- * redundant.
+ * Extract statement-level comments and story/requirement pairs that are
+ * relevant for redundancy analysis within a given scope.
  *
- * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-STATEMENT-SIGNIFICANCE REQ-CONFIGURABLE-STRICTNESS
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-STATEMENT-SIGNIFICANCE REQ-SCOPE-ANALYSIS
  */
-function getRedundantStatementContext(context, stmt, scopePairs, options) {
+function getStatementPairsForRedundancy(context, stmt, scopePairs, options) {
     if (scopePairs.size === 0) {
         return null;
     }
@@ -187,22 +171,56 @@ function getRedundantStatementContext(context, stmt, scopePairs, options) {
     if (stmtPairs.size === 0) {
         return null;
     }
-    // When emphasis duplication is allowed, treat a single fully-covered
-    // pair as intentional emphasis and skip reporting.
-    if (options.allowEmphasisDuplication && stmtPairs.size === 1) {
-        if ((0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
-            return null;
-        }
+    return { comments: stmtComments, pairs: stmtPairs };
+}
+/**
+ * Decide whether the provided statement-level pairs should be considered
+ * redundant within the given scope, respecting configuration options.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-CONFIGURABLE-STRICTNESS
+ */
+function isStatementRedundantWithinScope(stmtPairs, scopePairs, options) {
+    if (options.allowEmphasisDuplication &&
+        stmtPairs.size === 1 &&
+        (0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
+        return false;
     }
     if (!(0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
-        return null;
+        return false;
     }
-    // At this point the statement-level annotations are fully
-    // covered by the parent/ancestor scopes and therefore redundant.
-    const annotationComments = stmtComments.filter((comment) => {
+    return true;
+}
+/**
+ * Filter a list of comments down to those that contain traceability
+ * annotations relevant for redundancy detection.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SAFE-REMOVAL REQ-REDUNDANCY-PATTERNS
+ */
+function getAnnotationCommentsFromStatement(comments) {
+    return comments.filter((comment) => {
         const commentText = typeof comment.value === "string" ? comment.value : "";
         return /@story\b|@req\b|@supports\b/.test(commentText);
     });
+}
+/**
+ * Determine whether a statement is redundant relative to the provided
+ * scopePairs and options, using helper functions to gather statement
+ * pairs, apply redundancy rules, and collect the associated annotation
+ * comments. Returns null when the statement should not be treated as
+ * redundant.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-STATEMENT-SIGNIFICANCE REQ-CONFIGURABLE-STRICTNESS
+ */
+function getRedundantStatementContext(context, stmt, scopePairs, options) {
+    const stmtInfo = getStatementPairsForRedundancy(context, stmt, scopePairs, options);
+    if (!stmtInfo) {
+        return null;
+    }
+    const { comments, pairs } = stmtInfo;
+    if (!isStatementRedundantWithinScope(pairs, scopePairs, options)) {
+        return null;
+    }
+    const annotationComments = getAnnotationCommentsFromStatement(comments);
     if (annotationComments.length === 0) {
         return null;
     }

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

@@ -79,7 +79,7 @@ const rule = {
     meta: {
         type: "problem",
         docs: {
-            description: "Require @story and @req annotations on code branches",
+            description: "Require traceability annotations on significant code branches, preferring @supports for combined story and requirement coverage while still accepting legacy @story and @req comments.",
             recommended: "error",
         },
         fixable: "code",
@@ -88,7 +88,7 @@ const rule = {
              * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
              * @req REQ-ERROR-CONSISTENCY - Use shared branch error message convention with {{missing}} placeholder
              */
-            missingAnnotation: "Branch is missing required annotation: {{missing}}.",
+            missingAnnotation: "Branch is missing required traceability annotation: {{missing}}. Prefer using a single @supports line that links this branch to its story and requirements (for example, '@supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION'), or add the missing legacy tag if you are not yet using @supports.",
         },
         schema: [
             {

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

@@ -7,7 +7,7 @@ const rule = {
         type: "problem",
         fixable: "code",
         docs: {
-            description: "Require @req annotations on function-like exports (declarations, expressions, and methods, excluding arrow functions)",
+            description: "Require traceability annotations on function-like exports, preferring @supports for requirement coverage while still accepting legacy @req annotations.",
             recommended: "error",
         },
         messages: {
@@ -23,7 +23,7 @@ const rule = {
              * This rule uses ESLint's message data placeholders for the function name,
              * specifically the {{name}} placeholder populated via context.report.
              */
-            missingReq: "Function '{{functionName}}' is missing a required @req annotation. Add a JSDoc or line comment with @req (for example, '@req REQ-EXAMPLE') referencing the appropriate requirement from the story file.",
+            missingReq: "Function '{{functionName}}' is missing required traceability annotations. Prefer adding an @supports line that links this function to at least one requirement (for example, '@supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-EXAMPLE'), or, when you are limited to a single-story context, add a legacy @req annotation such as '@req REQ-EXAMPLE' referencing the appropriate requirement from the story file.",
         },
         schema: [
             {

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

@@ -18,7 +18,7 @@ const rule = {
     meta: {
         type: "problem",
         docs: {
-            description: "Require @story annotations on functions and auto-fix missing annotations where possible",
+            description: "Require traceability annotations on functions and methods, preferring @supports for story coverage while still accepting legacy @story annotations, and provide optional auto-fix for missing annotations.",
             recommended: "error",
         },
         hasSuggestions: true,
@@ -33,7 +33,7 @@ const rule = {
          */
         fixable: "code",
         messages: {
-            missingStory: "Function '{{name}}' 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.",
+            missingStory: "Function '{{name}}' 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.",
         },
         schema: [
             {
@@ -48,6 +48,7 @@ const rule = {
                     annotationTemplate: { type: "string" },
                     methodAnnotationTemplate: { type: "string" },
                     autoFix: { type: "boolean" },
+                    excludeTestCallbacks: { type: "boolean" },
                 },
                 additionalProperties: false,
             },
@@ -75,6 +76,9 @@ const rule = {
             ? opts.methodAnnotationTemplate.trim()
             : undefined;
         const autoFix = typeof opts.autoFix === "boolean" ? opts.autoFix : true;
+        const excludeTestCallbacks = typeof opts.excludeTestCallbacks === "boolean"
+            ? opts.excludeTestCallbacks
+            : true;
         /**
          * Optional debug logging for troubleshooting this rule.
          * Developers can temporarily uncomment the block below to log when the rule
@@ -90,7 +94,7 @@ 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);
+        const should = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority, { excludeTestCallbacks });
         // Delegate visitor construction to helper to keep this file concise.
         return (0, require_story_visitors_1.buildVisitors)(context, sourceCode, {
             shouldProcessNode: should,
@@ -99,6 +103,7 @@ const rule = {
             annotationTemplate,
             methodAnnotationTemplate,
             autoFix,
+            excludeTestCallbacks,
         });
     },
 };

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) || {};