eslint-plugin-traceability 1.4.3 → 1.4.5

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

@@ -1,198 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-// Default node types to check for function annotations
-const DEFAULT_SCOPE = [
-    "FunctionDeclaration",
-    "FunctionExpression",
-    "ArrowFunctionExpression",
-    "MethodDefinition",
-    "TSDeclareFunction",
-    "TSMethodSignature",
-];
-const EXPORT_PRIORITY_VALUES = ["all", "exported", "non-exported"];
+const require_story_visitors_1 = require("./helpers/require-story-visitors");
+const require_story_helpers_1 = require("./helpers/require-story-helpers");
 /**
- * Determine if a node is in an export declaration
+ * ESLint rule to require @story annotations on functions/methods.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED
- * @param {any} node - AST node to check for export ancestry
- * @returns {boolean} true if node is within an export declaration
  */
-function isExportedNode(node) {
-    let p = node.parent;
-    while (p) {
-        if (p.type === "ExportNamedDeclaration" ||
-            p.type === "ExportDefaultDeclaration") {
-            return true;
-        }
-        p = p.parent;
-    }
-    return false;
-}
-// Path to the story file for annotations
-const STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
-const ANNOTATION = `/** @story ${STORY_PATH} */`;
-/**
- * Check if @story annotation already present in JSDoc or preceding comments
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - AST node to inspect for existing annotations
- * @returns {boolean} true if @story annotation already present
- */
-function hasStoryAnnotation(sourceCode, node) {
-    const jsdoc = sourceCode.getJSDocComment(node);
-    if (jsdoc?.value.includes("@story")) {
-        return true;
-    }
-    const comments = sourceCode.getCommentsBefore(node) || [];
-    return comments.some((c) => c.value.includes("@story"));
-}
-/**
- * Get the name of the function-like node
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {any} node - AST node representing a function-like construct
- * @returns {string} the resolved name or "<unknown>"
- */
-function getNodeName(node) {
-    let current = node;
-    while (current) {
-        if (current.type === "VariableDeclarator" &&
-            current.id &&
-            typeof current.id.name === "string") {
-            return current.id.name;
-        }
-        if ((current.type === "FunctionDeclaration" ||
-            current.type === "TSDeclareFunction") &&
-            current.id &&
-            typeof current.id.name === "string") {
-            return current.id.name;
-        }
-        if ((current.type === "MethodDefinition" ||
-            current.type === "TSMethodSignature") &&
-            current.key &&
-            typeof current.key.name === "string") {
-            return current.key.name;
-        }
-        current = current.parent;
-    }
-    return "<unknown>";
-}
-/**
- * Determine AST node where annotation should be inserted
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {any} sourceCode - ESLint sourceCode object (unused but kept for parity)
- * @param {any} node - function-like AST node to resolve target for
- * @returns {any} AST node that should receive the annotation
- */
-function resolveTargetNode(sourceCode, node) {
-    if (node.type === "TSMethodSignature") {
-        // Interface method signature -> insert on interface
-        return node.parent.parent;
-    }
-    if (node.type === "FunctionExpression" ||
-        node.type === "ArrowFunctionExpression") {
-        const parent = node.parent;
-        if (parent.type === "VariableDeclarator") {
-            const varDecl = parent.parent;
-            if (varDecl.parent && varDecl.parent.type === "ExportNamedDeclaration") {
-                return varDecl.parent;
-            }
-            return varDecl;
-        }
-        if (parent.type === "ExportNamedDeclaration") {
-            return parent;
-        }
-        if (parent.type === "ExpressionStatement") {
-            return parent;
-        }
-    }
-    return node;
-}
-/**
- * Report missing @story annotation on function or method
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {Rule.RuleContext} context - ESLint rule context
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - function AST node missing annotation
- * @param {any} target - AST node where annotation should be inserted
- */
-function reportMissing(context, sourceCode, node, target) {
-    if (hasStoryAnnotation(sourceCode, node) ||
-        hasStoryAnnotation(sourceCode, target)) {
-        return;
-    }
-    let name = getNodeName(node);
-    if (node.type === "TSDeclareFunction" && node.id && node.id.name) {
-        name = node.id.name;
-    }
-    context.report({
-        node,
-        messageId: "missingStory",
-        data: { name },
-        suggest: [
-            {
-                desc: `Add JSDoc @story annotation for function '${name}', e.g., ${ANNOTATION}`,
-                fix: (fixer) => fixer.insertTextBefore(target, `${ANNOTATION}\n`),
-            },
-        ],
-    });
-}
-/**
- * Report missing @story annotation on class methods
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {Rule.RuleContext} context - ESLint rule context
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - MethodDefinition AST node
- */
-function reportMethod(context, sourceCode, node) {
-    if (hasStoryAnnotation(sourceCode, node)) {
-        return;
-    }
-    context.report({
-        node,
-        messageId: "missingStory",
-        data: { name: getNodeName(node) },
-        suggest: [
-            {
-                desc: `Add JSDoc @story annotation for function '${getNodeName(node)}', e.g., ${ANNOTATION}`,
-                fix: (fixer) => fixer.insertTextBefore(node, `${ANNOTATION}\n  `),
-            },
-        ],
-    });
-}
-/**
- * Check if this node is within scope and matches exportPriority
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {any} node - AST node to evaluate
- * @param {string[]} scope - allowed node types
- * @param {string} exportPriority - 'all' | 'exported' | 'non-exported'
- * @returns {boolean} whether node should be processed
- */
-function shouldProcessNode(node, scope, exportPriority) {
-    if (!scope.includes(node.type)) {
-        return false;
-    }
-    const exported = isExportedNode(node);
-    if (exportPriority === "exported" && !exported) {
-        return false;
-    }
-    if (exportPriority === "non-exported" && exported) {
-        return false;
-    }
-    return true;
-}
 const rule = {
     meta: {
         type: "problem",
@@ -210,99 +25,43 @@ const rule = {
                 properties: {
                     scope: {
                         type: "array",
-                        items: { type: "string", enum: DEFAULT_SCOPE },
+                        items: { type: "string", enum: require_story_helpers_1.DEFAULT_SCOPE },
                         uniqueItems: true,
                     },
-                    exportPriority: { type: "string", enum: EXPORT_PRIORITY_VALUES },
+                    exportPriority: { type: "string", enum: require_story_helpers_1.EXPORT_PRIORITY_VALUES },
                 },
                 additionalProperties: false,
             },
         ],
     },
     /**
-     * Create the rule visitor functions for require-story-annotation.
+     * Create the rule visitor functions.
+     *
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-     * @req REQ-CREATE-HOOK - Provide create(context) hook for rule behavior
+     * @req REQ-CREATE-HOOK
      */
     create(context) {
         const sourceCode = context.getSourceCode();
-        const opts = context.options[0] ||
-            {};
-        const scope = opts.scope || DEFAULT_SCOPE;
+        const opts = (context.options && context.options[0]) || {};
+        const scope = opts.scope || require_story_helpers_1.DEFAULT_SCOPE;
         const exportPriority = opts.exportPriority || "all";
-        return {
-            FunctionDeclaration(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                let target = node;
-                if (node.parent &&
-                    (node.parent.type === "ExportNamedDeclaration" ||
-                        node.parent.type === "ExportDefaultDeclaration")) {
-                    target = node.parent;
-                }
-                reportMissing(context, sourceCode, node, target);
-            },
-            /**
-             * Handle FunctionExpression nodes
-             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-ANNOTATION-REQUIRED
-             * @param {any} node - FunctionExpression AST node
-             */
-            FunctionExpression(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                if (node.parent && node.parent.type === "MethodDefinition")
-                    return;
-                const target = resolveTargetNode(sourceCode, node);
-                reportMissing(context, sourceCode, node, target);
-            },
-            /**
-             * Handle ArrowFunctionExpression nodes
-             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-ANNOTATION-REQUIRED
-             * @param {any} node - ArrowFunctionExpression AST node
-             */
-            ArrowFunctionExpression(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                const target = resolveTargetNode(sourceCode, node);
-                reportMissing(context, sourceCode, node, target);
-            },
-            /**
-             * Handle TSDeclareFunction nodes
-             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-ANNOTATION-REQUIRED
-             * @param {any} node - TSDeclareFunction AST node
-             */
-            TSDeclareFunction(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                reportMissing(context, sourceCode, node, node);
-            },
-            /**
-             * Handle TSMethodSignature nodes
-             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-ANNOTATION-REQUIRED
-             * @param {any} node - TSMethodSignature AST node
-             */
-            TSMethodSignature(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                const target = resolveTargetNode(sourceCode, node);
-                reportMissing(context, sourceCode, node, target);
-            },
-            /**
-             * Handle MethodDefinition nodes
-             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-ANNOTATION-REQUIRED
-             * @param {any} node - MethodDefinition AST node
-             */
-            MethodDefinition(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                reportMethod(context, sourceCode, node);
-            },
-        };
+        /**
+         * Debug log at the start of create to help diagnose rule activation in tests.
+         *
+         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+         * @req REQ-DEBUG-LOG
+         */
+        console.debug("require-story-annotation:create", typeof context.getFilename === "function"
+            ? context.getFilename()
+            : "<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);
+        // Delegate visitor construction to helper to keep this file concise.
+        return (0, require_story_visitors_1.buildVisitors)(context, sourceCode, {
+            shouldProcessNode: should,
+            scope,
+            exportPriority,
+        });
     },
 };
 exports.default = rule;

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

@@ -162,6 +162,15 @@ function programListener(context) {
     let rawStoryPath = null;
     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,

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

@@ -94,6 +94,10 @@ function handleComment(opts) {
     const { commentNode, context, cwd, storyDirs, allowAbsolute, requireExt } = opts;
     const lines = commentNode.value
         .split(/\r?\n/)
+        /**
+         * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+         * @req REQ-ANNOTATION-VALIDATION - Ensure each annotation line is parsed
+         */
         .map((l) => l.replace(/^[^@]*/, "").trim());
     for (const line of lines) {
         if (line.startsWith("@story")) {

package/lib/src/utils/branch-annotation-helpers.js

@@ -31,28 +31,47 @@ exports.DEFAULT_BRANCH_TYPES = [
  */
 function validateBranchTypes(context) {
     const options = context.options[0] || {};
+    /**
+     * Conditional branch checking whether branchTypes option was provided.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-CONDITIONAL - Trace configuration branch existence check
+     */
     if (Array.isArray(options.branchTypes)) {
-        // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-        // @req REQ-TRACEABILITY-FILTER-CALLBACK - Trace filter callback for invalid branch type detection
-        const invalidTypes = options.branchTypes.filter((t) => !exports.DEFAULT_BRANCH_TYPES.includes(t));
+        /**
+         * Predicate to determine whether a provided branch type is invalid.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-FILTER-CALLBACK - Trace filter callback for invalid branch type detection
+         */
+        function isInvalidType(t) {
+            return !exports.DEFAULT_BRANCH_TYPES.includes(t);
+        }
+        const invalidTypes = options.branchTypes.filter(isInvalidType);
+        /**
+         * Conditional branch checking whether any invalid types were found.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-INVALID-DETECTION - Trace handling when invalid types are detected
+         */
         if (invalidTypes.length > 0) {
             /**
              * Program listener produced when configuration is invalid.
              * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
              * @req REQ-TRACEABILITY-PROGRAM-LISTENER - Trace Program listener reporting invalid config values
              */
-            return {
-                Program(node) {
-                    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-                    // @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace reporting for each invalid type
-                    invalidTypes.forEach((t) => {
-                        context.report({
-                            node,
-                            message: `Value "${t}" should be equal to one of the allowed values: ${exports.DEFAULT_BRANCH_TYPES.join(", ")}`,
-                        });
+            function ProgramHandler(node) {
+                /**
+                 * Report a single invalid type for the given Program node.
+                 * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+                 * @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace reporting for each invalid type
+                 */
+                function reportInvalidType(t) {
+                    context.report({
+                        node,
+                        message: `Value "${t}" should be equal to one of the allowed values: ${exports.DEFAULT_BRANCH_TYPES.join(", ")}`,
                     });
-                },
-            };
+                }
+                invalidTypes.forEach(reportInvalidType);
+            }
+            return { Program: ProgramHandler };
         }
     }
     return Array.isArray(options.branchTypes)
@@ -65,6 +84,11 @@ function validateBranchTypes(context) {
  * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
  */
 function gatherBranchCommentText(sourceCode, node) {
+    /**
+     * Conditional branch for SwitchCase nodes that may include inline comments.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-SWITCHCASE-COMMENTS - Trace collection of preceding comments for SwitchCase
+     */
     if (node.type === "SwitchCase") {
         const lines = sourceCode.lines;
         const startLine = node.loc.start.line;
@@ -79,9 +103,15 @@ function gatherBranchCommentText(sourceCode, node) {
         return comments.join(" ");
     }
     const comments = sourceCode.getCommentsBefore(node) || [];
-    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-    // @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
-    return comments.map((c) => c.value).join(" ");
+    /**
+     * Mapper to extract the text value from a comment node.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
+     */
+    function commentToValue(c) {
+        return c.value;
+    }
+    return comments.map(commentToValue).join(" ");
 }
 /**
  * Report missing @story annotation on a branch node.
@@ -90,15 +120,25 @@ function gatherBranchCommentText(sourceCode, node) {
  */
 function reportMissingStory(context, node, options) {
     const { indent, insertPos, storyFixCountRef } = options;
+    /**
+     * Conditional branch deciding whether to offer an auto-fix for the missing story.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-FIX-DECISION - Trace decision to provide fixer for missing @story
+     */
     if (storyFixCountRef.count === 0) {
+        /**
+         * Fixer that inserts a default @story annotation above the branch.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer function used to insert missing @story
+         */
+        function insertStoryFixer(fixer) {
+            return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`);
+        }
         context.report({
             node,
             messageId: "missingAnnotation",
             data: { missing: "@story" },
-            fix: 
-            // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-            // @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer arrow function used to insert missing @story
-            (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`),
+            fix: insertStoryFixer,
         });
         storyFixCountRef.count++;
     }
@@ -117,15 +157,25 @@ function reportMissingStory(context, node, options) {
  */
 function reportMissingReq(context, node, options) {
     const { indent, insertPos, missingStory } = options;
+    /**
+     * Conditional branch deciding whether to offer an auto-fix for the missing req.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-FIX-DECISION - Trace decision to provide fixer for missing @req
+     */
     if (!missingStory) {
+        /**
+         * Fixer that inserts a default @req annotation above the branch.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer function used to insert missing @req
+         */
+        function insertReqFixer(fixer) {
+            return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`);
+        }
         context.report({
             node,
             messageId: "missingAnnotation",
             data: { missing: "@req" },
-            fix: 
-            // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-            // @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer arrow function used to insert missing @req
-            (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`),
+            fix: insertReqFixer,
         });
     }
     else {
@@ -163,10 +213,20 @@ function reportMissingAnnotations(context, node, storyFixCountRef) {
             args: [context, node, { indent, insertPos, missingStory }],
         },
     ];
-    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-    // @req REQ-TRACEABILITY-ACTIONS-FOREACH - Trace processing of actions array to report missing annotations
-    actions.forEach(({ missing, fn, args }) => 
-    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-    // @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace callback handling for each action item
-    missing && fn(...args));
+    /**
+     * Process a single action from the actions array.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-ACTIONS-FOREACH - Trace processing of actions array to report missing annotations
+     */
+    function processAction(item) {
+        /**
+         * Callback invoked for each action to decide and execute reporting.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace callback handling for each action item
+         */
+        if (item.missing) {
+            item.fn(...item.args);
+        }
+    }
+    actions.forEach(processAction);
 }

package/lib/tests/rules/require-story-core.branches.test.d.ts

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

package/lib/tests/rules/require-story-core.branches.test.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Branch tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Cover additional branch cases in require-story-core (addStoryFixer/reportMissing)
+ */
+const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
+const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");
+describe("Require Story Core branches (Story 003.0)", () => {
+    test("createAddStoryFix falls back to 0 when target is falsy", () => {
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixFn = (0, require_story_core_1.createAddStoryFix)(null);
+        const res = fixFn(fixer);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
+        const args = fixer.insertTextBeforeRange.mock.calls[0];
+        expect(args[0]).toEqual([0, 0]);
+        expect(args[1]).toBe(`${require_story_helpers_1.ANNOTATION}\n`);
+        expect(res).toEqual({ r: [0, 0], t: `${require_story_helpers_1.ANNOTATION}\n` });
+    });
+    test("createAddStoryFix uses target.range when parent not export and parent.range missing", () => {
+        const target = {
+            type: "FunctionDeclaration",
+            range: [21, 33],
+            parent: { type: "ClassBody" },
+        };
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixFn = (0, require_story_core_1.createAddStoryFix)(target);
+        const res = fixFn(fixer);
+        expect(fixer.insertTextBeforeRange.mock.calls[0][0]).toEqual([21, 21]);
+        expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(`${require_story_helpers_1.ANNOTATION}\n`);
+        expect(res).toEqual({ r: [21, 21], t: `${require_story_helpers_1.ANNOTATION}\n` });
+    });
+    test("createAddStoryFix prefers ExportDefaultDeclaration parent.range when present", () => {
+        const target = {
+            type: "FunctionDeclaration",
+            range: [50, 70],
+            parent: { type: "ExportDefaultDeclaration", range: [5, 100] },
+        };
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixFn = (0, require_story_core_1.createAddStoryFix)(target);
+        const res = fixFn(fixer);
+        expect(fixer.insertTextBeforeRange.mock.calls[0][0]).toEqual([5, 5]);
+        expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(`${require_story_helpers_1.ANNOTATION}\n`);
+        expect(res).toEqual({ r: [5, 5], t: `${require_story_helpers_1.ANNOTATION}\n` });
+    });
+    test("reportMissing uses context.getSourceCode fallback when sourceCode not provided and still reports", () => {
+        const node = {
+            type: "FunctionDeclaration",
+            id: { name: "fnX" },
+            range: [0, 10],
+        };
+        const fakeSource = {
+            /* intentionally missing getJSDocComment to exercise branch */ getText: () => "",
+        };
+        const context = { getSourceCode: () => fakeSource, report: jest.fn() };
+        (0, require_story_core_1.reportMissing)(context, undefined, node, node);
+        expect(context.report).toHaveBeenCalledTimes(1);
+        const call = context.report.mock.calls[0][0];
+        expect(call.node).toBe(node);
+        expect(call.messageId).toBe("missingStory");
+    });
+});

package/lib/tests/rules/require-story-core.test.d.ts

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

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

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Verify createMethodFix and reportMethod behaviors
+ */
+const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
+const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");
+describe("Require Story Core (Story 003.0)", () => {
+    test("createMethodFix uses parent range start when parent is export", () => {
+        const node = {
+            type: "MethodDefinition",
+            range: [30, 60],
+            parent: { type: "ExportNamedDeclaration", range: [12, 90] },
+        };
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixFn = (0, require_story_core_1.createMethodFix)(node);
+        const result = fixFn(fixer);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
+        const calledArgs = fixer.insertTextBeforeRange.mock.calls[0];
+        expect(calledArgs[0]).toEqual([12, 12]);
+        expect(calledArgs[1]).toBe(`${require_story_helpers_1.ANNOTATION}\n  `);
+        expect(result).toEqual({ r: [12, 12], t: `${require_story_helpers_1.ANNOTATION}\n  ` });
+    });
+    test("reportMethod calls context.report with proper data and suggest.fix works", () => {
+        const node = {
+            type: "MethodDefinition",
+            key: { name: "myMethod" },
+            range: [40, 80],
+            parent: { type: "ClassBody" },
+        };
+        const fakeSource = { getText: () => "" };
+        const context = {
+            getSourceCode: () => fakeSource,
+            report: jest.fn(),
+        };
+        (0, require_story_core_1.reportMethod)(context, fakeSource, node, node);
+        expect(context.report).toHaveBeenCalledTimes(1);
+        const call = context.report.mock.calls[0][0];
+        expect(call.messageId).toBe("missingStory");
+        expect(call.data).toEqual({ name: "myMethod" });
+        // The suggest fix should be a function; exercise it with a mock fixer
+        expect(Array.isArray(call.suggest)).toBe(true);
+        expect(typeof call.suggest[0].fix).toBe("function");
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixResult = call.suggest[0].fix(fixer);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalled();
+        const args = fixer.insertTextBeforeRange.mock.calls[0];
+        expect(args[0]).toEqual([40, 40]);
+        expect(args[1]).toBe(`${require_story_helpers_1.ANNOTATION}\n  `);
+        expect(fixResult).toEqual({ r: [40, 40], t: `${require_story_helpers_1.ANNOTATION}\n  ` });
+    });
+});

package/lib/tests/rules/require-story-helpers.test.d.ts

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