eslint-plugin-traceability 1.5.1 → 1.6.1

package/lib/src/rules/valid-req-reference.js

@@ -7,21 +7,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Rule to validate @req annotation references refer to existing requirements in story files
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Parse story files to extract requirement identifiers
- * @req REQ-DEEP-MATCH - Validate @req references against story file content
- * @req REQ-DEEP-CACHE - Cache parsed story content for performance
- * @req REQ-DEEP-PATH - Protect against path traversal in story paths
+ * @req REQ-DEEP-PARSE - Parse comments and extract story/requirement metadata
+ * @req REQ-DEEP-MATCH - Match @req annotations to story file requirements
+ * @req REQ-DEEP-CACHE - Cache requirement IDs per story file for efficient validation
+ * @req REQ-DEEP-PATH - Validate and resolve story file paths safely
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 /**
  * Extract the story path from a JSDoc comment.
- * Parses comment.value lines for @story annotation.
- * @param comment any JSDoc comment node
- * @returns story path or null if not found
- *
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Extracts @story annotation from comment content
+ * @req REQ-DEEP-PARSE - Parse JSDoc comment lines to locate @story annotations
  */
 function extractStoryPath(comment) {
     const rawLines = comment.value.split(/\r?\n/);
@@ -37,14 +33,11 @@ function extractStoryPath(comment) {
 /**
  * Validate a @req annotation line against the extracted story content.
  * Performs path validation, file reading, caching, and requirement existence checks.
- *
- * @param opts options bag
- *
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PATH - Validates and protects against path traversal and absolute paths
- * @req REQ-DEEP-CACHE - Caches parsed story files to avoid repeated IO
- * @req REQ-DEEP-MATCH - Ensures referenced requirement IDs exist in the story file
- * @req REQ-DEEP-PARSE - Parses story file content to find REQ- identifiers
+ * @req REQ-DEEP-PATH - Validate and resolve referenced story file paths
+ * @req REQ-DEEP-CACHE - Cache requirement IDs discovered in story files
+ * @req REQ-DEEP-MATCH - Verify that a referenced requirement ID exists in the story
+ * @req REQ-DEEP-PARSE - Parse story file contents to extract requirement identifiers
  */
 function validateReqLine(opts) {
     const { comment, context, line, storyPath, cwd, reqCache } = opts;
@@ -96,15 +89,10 @@ function validateReqLine(opts) {
     }
 }
 /**
- * Handle a single annotation line.
- * @story Updates the current story path when encountering an @story annotation
- * @req Validates the requirement reference against the current story content
- *
- * @param opts handler options
- *
+ * Handle a single annotation line for story or requirement metadata.
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Recognizes @story and @req annotation lines
- * @req REQ-DEEP-MATCH - Delegates @req validation to validateReqLine
+ * @req REQ-DEEP-PARSE - Parse annotation lines for @story and @req tags
+ * @req REQ-DEEP-MATCH - Dispatch @req lines for validation against story requirements
  */
 function handleAnnotationLine(opts) {
     const { line, comment, context, cwd, reqCache, storyPath } = opts;
@@ -119,14 +107,11 @@ function handleAnnotationLine(opts) {
     return storyPath;
 }
 /**
- * Handle JSDoc story and req annotations.
- *
- * @param opts options for comment handling
- *
+ * Handle JSDoc story and req annotations for a single comment block.
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-PARSE - Parses comment blocks to extract annotation lines
- * @req REQ-DEEP-MATCH - Uses handleAnnotationLine to validate @req entries
- * @req REQ-DEEP-CACHE - Passes shared cache for parsed story files
+ * @req REQ-DEEP-PARSE - Iterate comment lines to process @story/@req annotations
+ * @req REQ-DEEP-MATCH - Coordinate annotation handling across a comment block
+ * @req REQ-DEEP-CACHE - Maintain and reuse discovered story path across comments
  */
 function handleComment(opts) {
     const { comment, context, cwd, reqCache, rawStoryPath } = opts;
@@ -147,30 +132,25 @@ function handleComment(opts) {
 }
 /**
  * Create a Program listener that iterates comments and validates annotations.
- *
- * @param context ESLint rule context
- * @returns Program visitor function
- *
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
- * @req REQ-DEEP-CACHE - Maintains a cache across comment processing
- * @req REQ-DEEP-PATH - Resolves and protects story paths against traversal
+ * @req REQ-DEEP-CACHE - Initialize and share a requirement cache for the program
+ * @req REQ-DEEP-PATH - Derive the working directory context for path resolution
  */
 function programListener(context) {
     const sourceCode = context.getSourceCode();
     const cwd = process.cwd();
     const reqCache = new Map();
     let rawStoryPath = null;
+    /**
+     * Program visitor that walks all comments to validate story/requirement references.
+     * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+     * @req REQ-DEEP-PARSE - Collect all comments from the source code
+     * @req REQ-DEEP-MATCH - Drive comment-level handling for traceability checks
+     * @req REQ-DEEP-CACHE - Reuse story path and requirement cache across comments
+     * @req REQ-DEEP-PATH - Ensure validation respects project-relative paths
+     */
     return function Program() {
         const comments = sourceCode.getAllComments() || [];
-        /**
-         * Process each comment to handle story and requirement annotations.
-         *
-         * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
-         * @req REQ-DEEP-PARSE - Parse annotations from comment blocks
-         * @req REQ-DEEP-MATCH - Validate @req references found in comments
-         * @req REQ-DEEP-CACHE - Use cache for parsed story files to avoid repeated IO
-         * @req REQ-DEEP-PATH - Enforce path validation when resolving story files
-         */
         comments.forEach((comment) => {
             rawStoryPath = handleComment({
                 comment,
@@ -197,12 +177,11 @@ exports.default = {
     },
     /**
      * Rule create entrypoint that returns the Program visitor.
-     *
      * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
-     * @req REQ-DEEP-MATCH - Entrypoint orchestrates validation of @req annotations
-     * @req REQ-DEEP-PARSE - Uses parsing helpers to extract annotations and story paths
-     * @req REQ-DEEP-CACHE - Establishes cache used during validation
-     * @req REQ-DEEP-PATH - Ensures path validation is applied during checks
+     * @req REQ-DEEP-MATCH - Register the Program visitor with ESLint
+     * @req REQ-DEEP-PARSE - Integrate comment parsing into the ESLint rule lifecycle
+     * @req REQ-DEEP-CACHE - Ensure cache and context are wired into the listener
+     * @req REQ-DEEP-PATH - Propagate path context into the program listener
      */
     create(context) {
         return { Program: programListener(context) };

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.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,160 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-AUTOFIX-MISSING - Verify ESLint --fix automatically adds missing @story annotations to functions
+ * @req REQ-AUTOFIX-FORMAT - Verify ESLint --fix corrects simple annotation format issues for @story annotations
+ */
+const eslint_1 = require("eslint");
+const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
+const valid_annotation_format_1 = __importDefault(require("../../src/rules/valid-annotation-format"));
+const functionRuleTester = new eslint_1.RuleTester({
+    languageOptions: {
+        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+    },
+});
+const formatRuleTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
+    describe("[REQ-AUTOFIX-MISSING] require-story-annotation auto-fix", () => {
+        functionRuleTester.run("require-story-annotation --fix", require_story_annotation_1.default, {
+            valid: [
+                {
+                    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: [
+                {
+                    name: "[REQ-AUTOFIX-MISSING] adds @story before function declaration when missing",
+                    code: `function autoFixMe() {}`,
+                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction autoFixMe() {}`,
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'autoFixMe', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction autoFixMe() {}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    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}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+    describe("[REQ-AUTOFIX-FORMAT] valid-annotation-format auto-fix", () => {
+        formatRuleTester.run("valid-annotation-format --fix simple @story extension issues", valid_annotation_format_1.default, {
+            valid: [
+                {
+                    name: "[REQ-AUTOFIX-FORMAT] already-correct story path is unchanged",
+                    code: `// @story docs/stories/005.0-DEV-EXAMPLE.story.md`,
+                },
+            ],
+            invalid: [
+                {
+                    name: "[REQ-AUTOFIX-FORMAT] adds .md extension for .story path",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
+                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                    errors: [
+                        {
+                            messageId: "invalidStoryFormat",
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-FORMAT] adds .story.md extension when missing entirely",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION`,
+                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                    errors: [
+                        {
+                            messageId: "invalidStoryFormat",
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+});

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

@@ -29,6 +29,7 @@ describe("Error Reporting Enhancements for require-story-annotation (Story 007.0
             {
                 name: "[REQ-ERROR-SPECIFIC] missing @story annotation should report specific details and suggestion",
                 code: `function bar() {}`,
+                output: "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}",
                 errors: [
                     {
                         messageId: "missingStory",

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" } }],
+            },
         ],
     });
 });