eslint-plugin-traceability 1.6.0 → 1.6.1

package/lib/src/rules/require-req-annotation.d.ts

@@ -1,7 +1,12 @@
-/**
+/****
+ * Rule to enforce @req annotation on functions
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-RULE-EXPORT - Export the rule object for ESLint
  * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
+ * @req REQ-FUNCTION-DETECTION - Detect function declarations, function expressions, and method definitions (including TypeScript declarations)
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of which exports are checked
+ * @req REQ-EXPORT-PRIORITY - Allow configuration of export priority behavior
  */
-declare const _default: any;
-export default _default;
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

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

@@ -1,37 +1,59 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-/****
- * Rule to enforce @req annotation on functions
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
- * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
- * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
- */
+const require_story_helpers_1 = require("./helpers/require-story-helpers");
 const annotation_checker_1 = require("../utils/annotation-checker");
-/**
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-RULE-EXPORT - Export the rule object for ESLint
- * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
- */
-exports.default = {
+const rule = {
     meta: {
         type: "problem",
         fixable: "code",
         docs: {
-            description: "Require @req annotations on functions",
+            description: "Require @req annotations on function-like exports (declarations, expressions, and methods, excluding arrow functions)",
             recommended: "error",
         },
         messages: {
             missingReq: "Missing @req annotation for function '{{name}}' (REQ-ANNOTATION-REQUIRED)",
         },
-        schema: [],
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    scope: {
+                        type: "array",
+                        items: {
+                            enum: require_story_helpers_1.DEFAULT_SCOPE,
+                        },
+                        uniqueItems: true,
+                    },
+                    exportPriority: {
+                        enum: require_story_helpers_1.EXPORT_PRIORITY_VALUES,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
     },
     /**
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
      * @req REQ-CREATE-HOOK - Provide create(context) hook for rule behavior
-     * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
+     * @req REQ-FUNCTION-DETECTION - Detect function declarations, function expressions, and method definitions (including TS-specific nodes)
+     * @req REQ-CONFIGURABLE-SCOPE - Respect configurable scope of which exports are checked
+     * @req REQ-EXPORT-PRIORITY - Respect configurable export priority when determining which nodes to check
      */
     create(context) {
+        const options = context.options?.[0] ?? {};
+        const rawScope = options?.scope;
+        const scope = Array.isArray(rawScope) && rawScope.length > 0 ? rawScope : require_story_helpers_1.DEFAULT_SCOPE;
+        const exportPriority = options?.exportPriority ?? "all";
+        const shouldCheck = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority);
+        /**
+         * Helper to conditionally run the annotation check only when the node
+         * should be processed according to scope/exportPriority.
+         */
+        const runCheck = (node) => {
+            if (!shouldCheck(node))
+                return;
+            (0, annotation_checker_1.checkReqAnnotation)(context, node, { enableFix: false });
+        };
         return {
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -39,18 +61,44 @@ exports.default = {
              * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on function declarations
              */
             FunctionDeclaration(node) {
-                return (0, annotation_checker_1.checkReqAnnotation)(context, node);
+                runCheck(node);
+            },
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-FUNCTION-DETECTION - Detect function expressions
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on function expressions
+             */
+            FunctionExpression(node) {
+                if (node.parent && node.parent.type === "MethodDefinition") {
+                    return;
+                }
+                runCheck(node);
             },
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+             * @req REQ-FUNCTION-DETECTION - Detect method definitions
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on method definitions
              */
-            TSDeclareFunction: (node) => (0, annotation_checker_1.checkReqAnnotation)(context, node),
+            MethodDefinition(node) {
+                runCheck(node);
+            },
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript declare functions
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on TS declare functions
+             */
+            TSDeclareFunction(node) {
+                runCheck(node);
+            },
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript method signatures
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on TS method signatures
              */
-            TSMethodSignature: (node) => (0, annotation_checker_1.checkReqAnnotation)(context, node),
+            TSMethodSignature(node) {
+                runCheck(node);
+            },
         };
     },
 };
+exports.default = rule;

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

@@ -7,6 +7,9 @@
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-AUTOFIX-MISSING - This rule supports auto-fixing missing @story annotations per Story 008.0 auto-fix behavior.
+ * @req REQ-AUTOFIX-SAFE - Auto-fix behavior only inserts @story annotation JSDoc comments and never changes executable or runtime code.
+ * @req REQ-AUTOFIX-PRESERVE - Auto-fix inserts a minimal placeholder JSDoc in a way that preserves existing surrounding formatting and structure.
  */
 import type { Rule } from "eslint";
 /**
@@ -15,6 +18,7 @@ import type { Rule } from "eslint";
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-AUTOFIX-MISSING - This rule participates in auto-fix for missing @story annotations.
  */
 declare const rule: Rule.RuleModule;
 export default rule;

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

@@ -8,15 +8,25 @@ const require_story_helpers_1 = require("./helpers/require-story-helpers");
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-AUTOFIX-MISSING - This rule participates in auto-fix for missing @story annotations.
  */
 const rule = {
     meta: {
         type: "problem",
         docs: {
-            description: "Require @story annotations on functions",
+            description: "Require @story annotations on functions and auto-fix missing annotations where possible",
             recommended: "error",
         },
         hasSuggestions: true,
+        /**
+         * Auto-fix support for inserting @story annotations.
+         *
+         * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+         * @req REQ-ANNOTATION-REQUIRED
+         * @req REQ-AUTOFIX-MISSING - `fixable: \"code\"` is used to implement REQ-AUTOFIX-MISSING for missing @story annotations.
+         * @req REQ-AUTOFIX-SAFE - Auto-fix is conservative and only adds a single-line JSDoc @story annotation without modifying existing runtime expressions.
+         * @req REQ-AUTOFIX-PRESERVE - Auto-fix behavior preserves surrounding code formatting and indentation when inserting the placeholder JSDoc.
+         */
         fixable: "code",
         messages: {
             missingStory: "Missing @story annotation for function '{{name}}' (REQ-ANNOTATION-REQUIRED)",
@@ -42,6 +52,7 @@ const rule = {
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
      * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
      * @req REQ-CREATE-HOOK
+     * @req REQ-AUTOFIX-MISSING - The create hook wires in visitors that are capable of providing auto-fix suggestions for missing @story annotations.
      */
     create(context) {
         const sourceCode = context.getSourceCode();

package/lib/src/rules/valid-annotation-format.js

@@ -8,6 +8,7 @@ const STORY_EXAMPLE_PATH = "docs/stories/005.0-DEV-EXAMPLE.story.md";
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-PRESERVE - Avoid risky text replacements when the annotation tag cannot be located
  */
 const TAG_NOT_FOUND_INDEX = -1;
 /**
@@ -89,6 +90,8 @@ function buildReqErrorMessage(kind, value) {
  *
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and never broaden the referenced path
+ * @req REQ-AUTOFIX-PRESERVE - Preserve surrounding formatting when normalizing story path suffixes
  */
 function getFixedStoryPath(original) {
     if (original.includes("..")) {
@@ -124,10 +127,18 @@ function reportInvalidStoryFormat(context, comment, collapsed) {
  * for common path suffix issues by locating and replacing the path text
  * within the original comment.
  *
+ * This helper:
+ *   - only adjusts the story path suffix when a safe, well-understood
+ *     transformation is available, satisfying REQ-AUTOFIX-SAFE.
+ *   - preserves all surrounding comment formatting, spacing, and text
+ *     outside the path substring, satisfying REQ-AUTOFIX-PRESERVE.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and avoid changing semantics
+ * @req REQ-AUTOFIX-PRESERVE - Auto-fix must preserve surrounding formatting and comments
  */
 function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
     const sourceCode = context.getSourceCode();
@@ -317,6 +328,15 @@ exports.default = {
             invalidReqFormat: "{{details}}",
         },
         schema: [],
+        /**
+         * This rule's fixable support is limited to safe @story path suffix normalization per Story 008.0.
+         * Fixes are limited strictly to adjusting the suffix portion of the @story path (e.g., adding
+         * `.md` or `.story.md`), preserving all other comment text and whitespace exactly as written.
+         *
+         * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+         * @req REQ-AUTOFIX-SAFE
+         * @req REQ-AUTOFIX-PRESERVE
+         */
         fixable: "code",
     },
     /**

package/lib/src/utils/annotation-checker.d.ts

@@ -1,6 +1,12 @@
 /**
  * Helper to check @req annotation presence on TS declare functions and method signatures.
+ * This helper is intentionally scope/exportPriority agnostic and focuses solely
+ * on detection and reporting of @req annotations for the given node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+ * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
+ * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
  */
-export declare function checkReqAnnotation(context: any, node: any): void;
+export declare function checkReqAnnotation(context: any, node: any, options?: {
+    enableFix?: boolean;
+}): void;

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

@@ -48,11 +48,41 @@ function commentContainsReq(c) {
  * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
  */
 function hasReqAnnotation(jsdoc, comments) {
+    // BRANCH @req detection on JSDoc or comments
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQ-DETECTION
     return ((jsdoc &&
         typeof jsdoc.value === "string" &&
         jsdoc.value.includes("@req")) ||
         comments.some(commentContainsReq));
 }
+/**
+ * Determine the most appropriate node to attach an inserted JSDoc to.
+ * Prefers outer function-like constructs such as methods, variable declarators,
+ * or wrapping expression statements for function expressions.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-AUTOFIX - Provide autofix for missing @req annotation
+ */
+function getFixTargetNode(node) {
+    const parent = node && node.parent;
+    if (!parent) {
+        return node;
+    }
+    // If the node is part of a class/obj method definition, attach to the MethodDefinition
+    if (parent.type === "MethodDefinition") {
+        return parent;
+    }
+    // If the node is the init of a variable declarator, attach to the VariableDeclarator
+    if (parent.type === "VariableDeclarator" && parent.init === node) {
+        return parent;
+    }
+    // If the parent is an expression statement (e.g. IIFE or assigned via expression),
+    // attach to the outer ExpressionStatement.
+    if (parent.type === "ExpressionStatement") {
+        return parent;
+    }
+    return node;
+}
 /**
  * Creates a fix function that inserts a missing @req JSDoc before the node.
  * Returned function is a proper named function so no inline arrow is used.
@@ -60,8 +90,9 @@ function hasReqAnnotation(jsdoc, comments) {
  * @req REQ-ANNOTATION-AUTOFIX - Provide autofix for missing @req annotation
  */
 function createMissingReqFix(node) {
+    const target = getFixTargetNode(node);
     return function missingReqFix(fixer) {
-        return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
+        return fixer.insertTextBefore(target, "/** @req <REQ-ID> */\n");
     };
 }
 /**
@@ -73,29 +104,41 @@ function createMissingReqFix(node) {
  * @req REQ-ERROR-SPECIFIC - Provide specific error details including node name
  * @req REQ-ERROR-LOCATION - Include contextual location information in errors
  */
-function reportMissing(context, node) {
-    const rawName = (0, require_story_utils_1.getNodeName)(node);
+function reportMissing(context, node, enableFix = true) {
+    const rawName = (0, require_story_utils_1.getNodeName)(node) ?? (node && (0, require_story_utils_1.getNodeName)(node.parent));
     const name = rawName ?? "(anonymous)";
-    context.report({
+    const reportOptions = {
         node,
         messageId: "missingReq",
         data: { name },
-        fix: createMissingReqFix(node),
-    });
+    };
+    if (enableFix) {
+        reportOptions.fix = createMissingReqFix(node);
+    }
+    context.report(reportOptions);
 }
 /**
  * Helper to check @req annotation presence on TS declare functions and method signatures.
+ * This helper is intentionally scope/exportPriority agnostic and focuses solely
+ * on detection and reporting of @req annotations for the given node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+ * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
+ * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
  */
-function checkReqAnnotation(context, node) {
+function checkReqAnnotation(context, node, options) {
+    const { enableFix = true } = options ?? {};
     const sourceCode = context.getSourceCode();
     const jsdoc = getJsdocComment(sourceCode, node);
     const leading = getLeadingComments(node);
     const comments = getCommentsBefore(sourceCode, node);
     const all = combineComments(leading, comments);
     const hasReq = hasReqAnnotation(jsdoc, all);
+    // BRANCH when a @req annotation is missing and must be reported
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQ-DETECTION
+    // @req REQ-ANNOTATION-REPORTING
     if (!hasReq) {
-        reportMissing(context, node);
+        reportMissing(context, node, enableFix);
     }
 }

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

@@ -28,6 +28,10 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                     name: "[REQ-AUTOFIX-MISSING] already annotated function is unchanged",
                     code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction alreadyAnnotated() {}`,
                 },
+                {
+                    name: "[REQ-AUTOFIX-MISSING] already annotated class method is unchanged",
+                    code: `class A {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                },
             ],
             invalid: [
                 {
@@ -46,6 +50,78 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                         },
                     ],
                 },
+                {
+                    name: "[REQ-AUTOFIX-MISSING] adds @story before function expression when missing",
+                    code: `const fnExpr = function() {};`,
+                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'fnExpr', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-MISSING] adds @story before class method when missing",
+                    code: `class C {\n  method() {}\n}`,
+                    output: `class C {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'method', e.g., /** @story 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}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-MISSING] adds @story before TS declare function when missing",
+                    code: `declare function tsDecl(): void;`,
+                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
+                    languageOptions: {
+                        parser: require("@typescript-eslint/parser"),
+                        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+                    },
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'tsDecl', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-MISSING] adds @story before TS method signature when missing",
+                    code: `interface D {\n  method(): void;\n}`,
+                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ninterface D {\n  method(): void;\n}`,
+                    languageOptions: {
+                        parser: require("@typescript-eslint/parser"),
+                        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+                    },
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'method', e.g., /** @story 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}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
             ],
         });
     });

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

@@ -44,24 +44,80 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
                 },
             },
+            {
+                name: "[REQ-FUNCTION-DETECTION][Story 003.0] valid FunctionExpression with @req annotation",
+                code: `const fn = /**\n * @req REQ-EXAMPLE\n */\nfunction() {};`,
+            },
+            {
+                name: "[REQ-FUNCTION-DETECTION][Story 003.0] valid MethodDefinition with @req annotation",
+                code: `class C {\n  /**\n   * @req REQ-EXAMPLE\n   */\n  m() {}\n}`,
+            },
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT][REQ-FUNCTION-DETECTION][Story 003.0] valid TS FunctionExpression in variable declarator with @req",
+                code: `const fn = /**\n * @req REQ-EXAMPLE\n */\nfunction () {};`,
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT][REQ-FUNCTION-DETECTION][Story 003.0] valid exported TS FunctionExpression in variable declarator with @req",
+                code: `export const fn = /**\n * @req REQ-EXAMPLE\n */\nfunction () {};`,
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
+            {
+                name: "[REQ-CONFIGURABLE-SCOPE][Story 003.0] FunctionExpression ignored when scope only includes FunctionDeclaration",
+                code: `const fn = function () {};`,
+                options: [{ scope: ["FunctionDeclaration"] }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported function ignored when exportPriority is 'exported'",
+                code: `function nonExported() {}`,
+                options: [{ exportPriority: "exported" }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported function required when exportPriority is 'exported'",
+                code: `/** @req REQ-EXAMPLE */\nexport function exportedFn() {}`,
+                options: [{ exportPriority: "exported" }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported function ignored when exportPriority is 'non-exported'",
+                code: `export function exportedFn() {}`,
+                options: [{ exportPriority: "non-exported" }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported function required when exportPriority is 'non-exported'",
+                code: `/** @req REQ-EXAMPLE */\nfunction nonExported() {}`,
+                options: [{ exportPriority: "non-exported" }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported method ignored when exportPriority is 'non-exported'",
+                code: `export class C {\n  m() {}\n}`,
+                options: [{ exportPriority: "non-exported" }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported method required when exportPriority is 'non-exported'",
+                code: `class C {\n  /** @req REQ-EXAMPLE */\n  m() {}\n}`,
+                options: [{ exportPriority: "non-exported" }],
+            },
         ],
         invalid: [
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @req on function without JSDoc",
                 code: `function baz() {}`,
-                output: `/** @req <REQ-ID> */\nfunction baz() {}`,
                 errors: [{ messageId: "missingReq", data: { name: "baz" } }],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @req on function with only @story annotation",
                 code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction qux() {}`,
-                output: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\n/** @req <REQ-ID> */\nfunction qux() {}`,
                 errors: [{ messageId: "missingReq", data: { name: "qux" } }],
             },
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSDeclareFunction",
                 code: `declare function baz(): void;`,
-                output: `/** @req <REQ-ID> */\ndeclare function baz(): void;`,
                 errors: [{ messageId: "missingReq", data: { name: "baz" } }],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
@@ -71,13 +127,92 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSMethodSignature",
                 code: `interface I { method(): void; }`,
-                output: `interface I { /** @req <REQ-ID> */\nmethod(): void; }`,
                 errors: [{ messageId: "missingReq", data: { name: "method" } }],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
                 },
             },
+            {
+                name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on FunctionExpression assigned to variable",
+                code: `const fn = function () {};`,
+                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+            },
+            {
+                name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on anonymous FunctionExpression (no variable name)",
+                code: `(function () {})();`,
+                errors: [{ messageId: "missingReq", data: { name: "(anonymous)" } }],
+            },
+            {
+                name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on MethodDefinition in class",
+                code: `class C {\n  m() {}\n}`,
+                errors: [{ messageId: "missingReq" }],
+            },
+            {
+                name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on MethodDefinition in object literal",
+                code: `const o = { m() {} };`,
+                errors: [{ messageId: "missingReq" }],
+            },
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT][REQ-FUNCTION-DETECTION][Story 003.0] missing @req on TS FunctionExpression in variable declarator",
+                code: `const fn = function () {};`,
+                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT][REQ-FUNCTION-DETECTION][Story 003.0] missing @req on exported TS FunctionExpression in variable declarator",
+                code: `export const fn = function () {};`,
+                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
+            {
+                name: "[REQ-CONFIGURABLE-SCOPE][Story 003.0] FunctionDeclaration still reported when scope only includes FunctionDeclaration",
+                code: `function scoped() {}`,
+                options: [{ scope: ["FunctionDeclaration"] }],
+                errors: [{ messageId: "missingReq", data: { name: "scoped" } }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported function reported when exportPriority is 'exported'",
+                code: `export function exportedFn() {}`,
+                options: [{ exportPriority: "exported" }],
+                errors: [{ messageId: "missingReq", data: { name: "exportedFn" } }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported function reported when exportPriority is 'non-exported'",
+                code: `function nonExported() {}`,
+                options: [{ exportPriority: "non-exported" }],
+                errors: [{ messageId: "missingReq", data: { name: "nonExported" } }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported method reported when exportPriority is 'exported'",
+                code: `export class C {\n  m() {}\n}`,
+                errors: [{ messageId: "missingReq" }],
+                options: [{ exportPriority: "exported" }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported method reported when exportPriority is 'non-exported'",
+                code: `class C {\n  m() {}\n}`,
+                errors: [{ messageId: "missingReq" }],
+                options: [{ exportPriority: "non-exported" }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported FunctionExpression reported when exportPriority is 'exported'",
+                code: `export const fn = function () {};`,
+                options: [{ exportPriority: "exported" }],
+                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+            },
+            {
+                name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported FunctionExpression reported when exportPriority is 'non-exported'",
+                code: `const fn = function () {};`,
+                options: [{ exportPriority: "non-exported" }],
+                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+            },
         ],
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "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",