eslint-plugin-traceability 1.4.2 → 1.4.4

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,69 +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);
-            },
-            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);
-            },
-            ArrowFunctionExpression(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                const target = resolveTargetNode(sourceCode, node);
-                reportMissing(context, sourceCode, node, target);
-            },
-            TSDeclareFunction(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                reportMissing(context, sourceCode, node, node);
-            },
-            TSMethodSignature(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                const target = resolveTargetNode(sourceCode, node);
-                reportMissing(context, sourceCode, node, target);
-            },
-            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/utils/branch-annotation-helpers.js

@@ -31,19 +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)) {
-        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) {
-            return {
-                Program(node) {
-                    invalidTypes.forEach((t) => {
-                        context.report({
-                            node,
-                            message: `Value "${t}" should be equal to one of the allowed values: ${exports.DEFAULT_BRANCH_TYPES.join(", ")}`,
-                        });
+            /**
+             * 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
+             */
+            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)
@@ -56,11 +84,18 @@ 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;
         let i = startLine - PRE_COMMENT_OFFSET;
         const comments = [];
+        // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+        // @req REQ-TRACEABILITY-WHILE - Trace while loop that collects preceding comments for SwitchCase
         while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
             comments.unshift(lines[i].trim());
             i--;
@@ -68,7 +103,15 @@ function gatherBranchCommentText(sourceCode, node) {
         return comments.join(" ");
     }
     const comments = sourceCode.getCommentsBefore(node) || [];
-    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.
@@ -77,12 +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: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`),
+            fix: insertStoryFixer,
         });
         storyFixCountRef.count++;
     }
@@ -101,12 +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: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`),
+            fix: insertReqFixer,
         });
     }
     else {
@@ -144,5 +213,20 @@ function reportMissingAnnotations(context, node, storyFixCountRef) {
             args: [context, node, { indent, insertPos, missingStory }],
         },
     ];
-    actions.forEach(({ missing, fn, args }) => 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/maintenance/detect-isolated.test.js

@@ -87,11 +87,24 @@ describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)",
 `;
         fs.writeFileSync(filePath, content, "utf8");
         // Remove read permission
-        fs.chmodSync(dir, 0o000);
-        expect(() => (0, detect_1.detectStaleAnnotations)(tmpDir2)).toThrow();
-        // Restore permissions
-        fs.chmodSync(dir, 0o700);
-        // Cleanup temporary directory
-        fs.rmSync(tmpDir2, { recursive: true, force: true });
+        try {
+            fs.chmodSync(dir, 0o000);
+            expect(() => (0, detect_1.detectStaleAnnotations)(tmpDir2)).toThrow();
+        }
+        finally {
+            // Restore permissions and cleanup temporary directory, ignoring errors during cleanup
+            try {
+                fs.chmodSync(dir, 0o700);
+            }
+            catch {
+                // ignore
+            }
+            try {
+                fs.rmSync(tmpDir2, { recursive: true, force: true });
+            }
+            catch {
+                // ignore
+            }
+        }
     });
 });

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

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

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

@@ -0,0 +1,173 @@
+"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-ANNOTATION-REQUIRED - Verify helper functions in require-story helpers produce correct fixes and reporting behavior
+ */
+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 Helpers (Story 003.0)", () => {
+    test("createAddStoryFix uses parent range start when available", () => {
+        const target = {
+            type: "FunctionDeclaration",
+            range: [20, 40],
+            parent: { type: "ExportNamedDeclaration", range: [10, 50] },
+        };
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixFn = (0, require_story_core_1.createAddStoryFix)(target);
+        const result = fixFn(fixer);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
+        const calledArgs = fixer.insertTextBeforeRange.mock.calls[0];
+        expect(calledArgs[0]).toEqual([10, 10]);
+        expect(calledArgs[1]).toBe(`${require_story_helpers_1.ANNOTATION}\n`);
+        expect(result).toEqual({ r: [10, 10], t: `${require_story_helpers_1.ANNOTATION}\n` });
+    });
+    test("createMethodFix falls back to node.range when parent not export", () => {
+        const node = {
+            type: "MethodDefinition",
+            range: [30, 60],
+            parent: { type: "ClassBody" },
+        };
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixFn = (0, require_story_core_1.createMethodFix)(node);
+        const res = fixFn(fixer);
+        expect(fixer.insertTextBeforeRange.mock.calls[0][0]).toEqual([30, 30]);
+        expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(`${require_story_helpers_1.ANNOTATION}\n  `);
+        expect(res).toEqual({ r: [30, 30], t: `${require_story_helpers_1.ANNOTATION}\n  ` });
+    });
+    test("reportMissing does not call context.report if JSDoc contains @story", () => {
+        const node = {
+            type: "FunctionDeclaration",
+            id: { name: "fn" },
+            range: [0, 10],
+        };
+        const fakeSource = {
+            getJSDocComment: () => ({
+                value: "@story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md",
+            }),
+            getText: () => "",
+        };
+        const context = {
+            getSourceCode: () => fakeSource,
+            report: jest.fn(),
+        };
+        (0, require_story_core_1.reportMissing)(context, fakeSource, node, node);
+        expect(context.report).not.toHaveBeenCalled();
+    });
+    test("reportMissing calls context.report when no JSDoc story present", () => {
+        const node = {
+            type: "FunctionDeclaration",
+            id: { name: "fn2" },
+            range: [0, 10],
+        };
+        const fakeSource = {
+            getJSDocComment: () => null,
+            getText: () => "",
+        };
+        const context = {
+            getSourceCode: () => fakeSource,
+            report: jest.fn(),
+        };
+        (0, require_story_core_1.reportMissing)(context, fakeSource, 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");
+    });
+    /**
+     * Additional helper tests for story annotations and IO helpers
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-ANNOTATION-REQUIRED - Verify resolveTargetNode/getNodeName/shouldProcessNode and IO helpers
+     */
+    test("resolveTargetNode prefers parent when parent is ExportNamedDeclaration", () => {
+        const fakeSource = { getText: () => "" };
+        const node = {
+            type: "FunctionExpression",
+            range: [5, 10],
+            parent: { type: "ExportNamedDeclaration", range: [1, 20] },
+        };
+        const resolved = (0, require_story_helpers_1.resolveTargetNode)(fakeSource, node);
+        expect(resolved).toBe(node.parent);
+    });
+    test("resolveTargetNode falls back to node when parent is not an export", () => {
+        const fakeSource = { getText: () => "" };
+        const node = {
+            type: "FunctionDeclaration",
+            range: [5, 10],
+            parent: { type: "ClassBody", range: [1, 20] },
+        };
+        const resolved = (0, require_story_helpers_1.resolveTargetNode)(fakeSource, node);
+        expect(resolved).toBe(node);
+    });
+    test("getNodeName extracts names from common node shapes", () => {
+        const funcNode = {
+            type: "FunctionDeclaration",
+            id: { name: "myFunc" },
+        };
+        const propNode = { type: "MethodDefinition", key: { name: "myProp" } };
+        expect((0, require_story_helpers_1.getNodeName)(funcNode)).toBe("myFunc");
+        expect((0, require_story_helpers_1.getNodeName)(propNode)).toBe("myProp");
+    });
+    test("shouldProcessNode returns booleans for typical node types", () => {
+        const funcDecl = { type: "FunctionDeclaration" };
+        const varDecl = { type: "VariableDeclaration" };
+        expect((0, require_story_helpers_1.shouldProcessNode)(funcDecl, require_story_helpers_1.DEFAULT_SCOPE)).toBeTruthy();
+        expect((0, require_story_helpers_1.shouldProcessNode)(varDecl, require_story_helpers_1.DEFAULT_SCOPE)).toBeFalsy();
+    });
+    test("linesBeforeHasStory detects preceding JSDoc story text", () => {
+        const jsdoc = "/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\n";
+        const rest = "function fn() {}\n";
+        const full = jsdoc + rest;
+        const fakeSource = {
+            getText: () => full,
+            getJSDocComment: () => ({
+                value: "@story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md",
+            }),
+            lines: full.split(/\r?\n/),
+        };
+        const nodeLine = fakeSource.lines.findIndex((l) => l.includes("function fn() {}")) + 1;
+        const node = {
+            type: "FunctionDeclaration",
+            range: [full.indexOf("function"), full.length],
+            loc: { start: { line: nodeLine } },
+        };
+        const has = (0, require_story_helpers_1.linesBeforeHasStory)(fakeSource, node);
+        expect(has).toBeTruthy();
+    });
+    test("fallbackTextBeforeHasStory returns boolean when called with source text and range", () => {
+        const jsdoc = "/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\n";
+        const rest = "function fnB() {}\n";
+        const full = jsdoc + rest;
+        const fakeSource = {
+            getText: () => full,
+        };
+        const node = {
+            type: "FunctionDeclaration",
+            range: [full.indexOf("function"), full.length],
+        };
+        const res = (0, require_story_helpers_1.fallbackTextBeforeHasStory)(fakeSource, node);
+        expect(typeof res).toBe("boolean");
+        expect(res).toBeTruthy();
+    });
+    test("parentChainHasStory returns true when ancestors have JSDoc story", () => {
+        const fakeSource = {
+            getCommentsBefore: () => [
+                {
+                    type: "Block",
+                    value: "@story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md",
+                },
+            ],
+        };
+        const node = {
+            type: "Identifier",
+            parent: { parent: { type: "ExportNamedDeclaration" } },
+        };
+        const res = (0, require_story_helpers_1.parentChainHasStory)(fakeSource, node);
+        expect(res).toBeTruthy();
+    });
+});

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

@@ -0,0 +1,6 @@
+/**
+ * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Edge case tests for IO helpers (linesBeforeHasStory/fallbackTextBeforeHasStory/parentChainHasStory)
+ */
+export {};