eslint-plugin-traceability 1.21.0 → 1.22.0

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

@@ -1,16 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.getNodeName = exports.STORY_PATH = void 0;
+exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.resolveTargetNode = exports.extractName = exports.hasStoryAnnotationWithPlacement = exports.hasStoryAnnotation = exports.leadingCommentsHasStory = exports.commentsBeforeHasStory = exports.jsdocHasStory = exports.isExportedNode = exports.STORY_PATH = void 0;
 exports.getAnnotationTemplate = getAnnotationTemplate;
 exports.shouldApplyAutoFix = shouldApplyAutoFix;
-exports.isExportedNode = isExportedNode;
-exports.jsdocHasStory = jsdocHasStory;
-exports.commentsBeforeHasStory = commentsBeforeHasStory;
-exports.leadingCommentsHasStory = leadingCommentsHasStory;
-exports.hasStoryAnnotation = hasStoryAnnotation;
-exports.hasStoryAnnotationWithPlacement = hasStoryAnnotationWithPlacement;
-exports.extractName = extractName;
-exports.resolveTargetNode = resolveTargetNode;
 exports.shouldProcessNode = shouldProcessNode;
 exports.reportMissing = reportMissing;
 exports.reportMethod = reportMethod;
@@ -18,14 +10,22 @@ const require_story_io_1 = require("./require-story-io");
 Object.defineProperty(exports, "linesBeforeHasStory", { enumerable: true, get: function () { return require_story_io_1.linesBeforeHasStory; } });
 Object.defineProperty(exports, "parentChainHasStory", { enumerable: true, get: function () { return require_story_io_1.parentChainHasStory; } });
 Object.defineProperty(exports, "fallbackTextBeforeHasStory", { enumerable: true, get: function () { return require_story_io_1.fallbackTextBeforeHasStory; } });
-const require_story_utils_1 = require("./require-story-utils");
-Object.defineProperty(exports, "getNodeName", { enumerable: true, get: function () { return require_story_utils_1.getNodeName; } });
-const function_annotation_helpers_1 = require("../../utils/function-annotation-helpers");
 const require_story_core_1 = require("./require-story-core");
 Object.defineProperty(exports, "DEFAULT_SCOPE", { enumerable: true, get: function () { return require_story_core_1.DEFAULT_SCOPE; } });
 Object.defineProperty(exports, "EXPORT_PRIORITY_VALUES", { enumerable: true, get: function () { return require_story_core_1.EXPORT_PRIORITY_VALUES; } });
 Object.defineProperty(exports, "STORY_PATH", { enumerable: true, get: function () { return require_story_core_1.STORY_PATH; } });
 const test_callback_exclusion_1 = require("./test-callback-exclusion");
+const require_story_name_extraction_1 = require("./require-story-name-extraction");
+Object.defineProperty(exports, "extractName", { enumerable: true, get: function () { return require_story_name_extraction_1.extractName; } });
+const require_story_node_utils_1 = require("./require-story-node-utils");
+Object.defineProperty(exports, "isExportedNode", { enumerable: true, get: function () { return require_story_node_utils_1.isExportedNode; } });
+Object.defineProperty(exports, "resolveTargetNode", { enumerable: true, get: function () { return require_story_node_utils_1.resolveTargetNode; } });
+const require_story_comment_detection_1 = require("./require-story-comment-detection");
+Object.defineProperty(exports, "jsdocHasStory", { enumerable: true, get: function () { return require_story_comment_detection_1.jsdocHasStory; } });
+Object.defineProperty(exports, "commentsBeforeHasStory", { enumerable: true, get: function () { return require_story_comment_detection_1.commentsBeforeHasStory; } });
+Object.defineProperty(exports, "leadingCommentsHasStory", { enumerable: true, get: function () { return require_story_comment_detection_1.leadingCommentsHasStory; } });
+Object.defineProperty(exports, "hasStoryAnnotation", { enumerable: true, get: function () { return require_story_comment_detection_1.hasStoryAnnotation; } });
+Object.defineProperty(exports, "hasStoryAnnotationWithPlacement", { enumerable: true, get: function () { return require_story_comment_detection_1.hasStoryAnnotationWithPlacement; } });
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function getAnnotationTemplate(override, _options) {
     if (typeof override === "string" && override.trim().length > 0) {
@@ -55,49 +55,6 @@ function buildTemplateConfig(options) {
     });
     return { effectiveTemplate, allowFix };
 }
-/**
- * Determine whether a node represents an anonymous arrow function expression
- * where the parent variable declarator has no explicit Identifier name.
- *
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-ARROW-FUNCTION-EXCLUDED
- */
-function isAnonymousArrowFunction(node) {
-    return !!node && node.type === "ArrowFunctionExpression";
-}
-/**
- * Determine whether a function-like node is nested within another function.
- *
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-NESTED-FUNCTION-INHERITANCE
- */
-function isNestedFunction(node) {
-    let current = node?.parent;
-    while (current) {
-        if (current.type === "FunctionDeclaration" ||
-            current.type === "FunctionExpression" ||
-            current.type === "ArrowFunctionExpression" ||
-            current.type === "MethodDefinition" ||
-            current.type === "TSDeclareFunction" ||
-            current.type === "TSMethodSignature") {
-            return true;
-        }
-        current = current.parent;
-    }
-    return false;
-}
-/**
- * Determine whether a function-like node is effectively anonymous for the
- * purposes of nested-function inheritance. Named functions must always carry
- * their own annotations, while anonymous nested functions may inherit.
- *
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-NESTED-FUNCTION-INHERITANCE
- */
-function isEffectivelyAnonymousFunction(node) {
-    const name = getContainerKeyOrIdName(node) ?? getDirectIdentifierName(node);
-    if (typeof name === "string" && name.length > 0 && name !== "(anonymous)") {
-        return false;
-    }
-    return true;
-}
 /**
  * Determine whether a function node is required to carry its own annotation
  * according to Story 004.0-DEV-BRANCH-ANNOTATIONS rules.
@@ -117,249 +74,16 @@ function requiresOwnFunctionAnnotation(node, options) {
     }
     // Anonymous arrow functions used as callbacks are excluded from function-level
     // requirements when they are nested inside another function or method.
-    if (isAnonymousArrowFunction(node) &&
-        isNestedFunction(node) &&
-        isEffectivelyAnonymousFunction(node)) {
+    if ((0, require_story_node_utils_1.isAnonymousArrowFunction)(node) &&
+        (0, require_story_node_utils_1.isNestedFunction)(node) &&
+        (0, require_story_node_utils_1.isEffectivelyAnonymousFunction)(node)) {
         return false;
     }
-    if (isNestedFunction(node) && isEffectivelyAnonymousFunction(node)) {
+    if ((0, require_story_node_utils_1.isNestedFunction)(node) && (0, require_story_node_utils_1.isEffectivelyAnonymousFunction)(node)) {
         return false;
     }
     return true;
 }
-/**
- * Determine if a node is in an export declaration
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Check node ancestry to find export declarations
- */
-function isExportedNode(node) {
-    let p = node.parent;
-    while (p) {
-        if (p.type === "ExportNamedDeclaration" ||
-            p.type === "ExportDefaultDeclaration") {
-            return true;
-        }
-        p = p.parent;
-    }
-    return false;
-}
-/**
- * Check whether the JSDoc associated with node contains @story
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Extract JSDoc based detection into helper
- */
-function jsdocHasStory(sourceCode, node) {
-    if (typeof sourceCode?.getJSDocComment !== "function") {
-        return false;
-    }
-    const jsdoc = sourceCode.getJSDocComment(node);
-    return !!(jsdoc &&
-        typeof jsdoc.value === "string" &&
-        jsdoc.value.includes("@story"));
-}
-/**
- * Check whether comments returned by sourceCode.getCommentsBefore contain @story
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Extract comment-before detection into helper
- */
-function commentsBeforeHasStory(sourceCode, node) {
-    if (typeof sourceCode?.getCommentsBefore !== "function") {
-        return false;
-    }
-    const commentsBefore = sourceCode.getCommentsBefore(node) || [];
-    return (Array.isArray(commentsBefore) &&
-        commentsBefore.some((c) => typeof c.value === "string" && c.value.includes("@story")));
-}
-/**
- * Check whether leadingComments attached to the node contain @story
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Extract leadingComments detection into helper
- */
-function leadingCommentsHasStory(node) {
-    const leadingComments = (node && node.leadingComments) || [];
-    return (Array.isArray(leadingComments) &&
-        leadingComments.some((c) => typeof c.value === "string" && c.value.includes("@story")));
-}
-/**
- * Check if @story annotation already present in JSDoc or preceding comments
- * Consolidates a variety of heuristics through smaller helpers.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Detect existing story annotations in JSDoc or comments
- */
-function hasStoryAnnotation(sourceCode, node) {
-    try {
-        // Direct, node-local checks always apply first.
-        if (jsdocHasStory(sourceCode, node)) {
-            return true;
-        }
-        if (commentsBeforeHasStory(sourceCode, node)) {
-            return true;
-        }
-        if (leadingCommentsHasStory(node)) {
-            return true;
-        }
-        if (!isNestedFunction(node) && (0, require_story_io_1.linesBeforeHasStory)(sourceCode, node)) {
-            return true;
-        }
-        const canInherit = isNestedFunction(node) && isEffectivelyAnonymousFunction(node);
-        // Only nodes that are allowed to inherit annotations (e.g., nested anonymous
-        // callbacks) may treat parent-chain comments or broad fallback text as
-        // satisfying the annotation requirement.
-        if (canInherit && (0, require_story_io_1.parentChainHasStory)(sourceCode, node)) {
-            return true;
-        }
-        if (canInherit && (0, require_story_io_1.fallbackTextBeforeHasStory)(sourceCode, node)) {
-            return true;
-        }
-        if (canInherit) {
-            return true;
-        }
-    }
-    catch (error) {
-        if (process.env.TRACEABILITY_DEBUG === "1") {
-            console.error("[traceability] hasStoryAnnotation failed for node", error?.message ?? error);
-        }
-    }
-    return false;
-}
-/**
- * Placement-aware story detection helper used by core reporting.
- *
- * When annotationPlacement is "inside" and the node supports inside-brace
- * semantics, this helper only treats annotations found on the first
- * comment-only lines inside the function or method body as satisfying the
- * requirement. JSDoc and before-function comments are intentionally ignored so
- * that misplaced annotations are reported as violations under the inside
- * standard.
- *
- * For nodes that do not support inside placement (such as TS declarations,
- * signature-only nodes, or functions without block bodies), this helper
- * delegates to the existing hasStoryAnnotation heuristics so that they
- * continue to rely on before-function placement.
- *
- * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-ALL-BLOCK-TYPES REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
- */
-function hasStoryAnnotationWithPlacement(sourceCode, node, annotationPlacement) {
-    // Backward-compatible default: use existing heuristics when placement is
-    // "before" or when the function does not support inside-brace semantics.
-    if (annotationPlacement !== "inside" ||
-        !(0, function_annotation_helpers_1.supportsInsidePlacementForFunction)(node)) {
-        return hasStoryAnnotation(sourceCode, node);
-    }
-    try {
-        const insideText = (0, function_annotation_helpers_1.getFunctionInsideBodyCommentText)(sourceCode, node);
-        if (typeof insideText === "string" &&
-            (insideText.includes("@story") || insideText.includes("@supports"))) {
-            return true;
-        }
-    }
-    catch (error) {
-        if (process.env.TRACEABILITY_DEBUG === "1") {
-            // Debug logging only when explicitly enabled for troubleshooting helper failures.
-            console.error("[traceability] hasStoryAnnotationWithPlacement failed for node", error?.message ?? error);
-        }
-    }
-    // In inside-placement mode for block-bodied functions and methods we
-    // intentionally do not fall back to before-function heuristics; callers
-    // should treat this as a missing annotation so that misplaced comments are
-    // reported as violations.
-    return false;
-}
-/**
- * Determine AST node where annotation should be inserted
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Determine correct insertion target for 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;
-}
-/**
- * Extract a direct Identifier name when available on the given node.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Extract direct Identifier-based names from nodes
- */
-function getDirectIdentifierName(node) {
-    if (node &&
-        node.type === "Identifier" &&
-        typeof node.name === "string" &&
-        node.name.length > 0) {
-        return node.name;
-    }
-    return null;
-}
-/**
- * Normalize container nodes that expose names via id/key properties.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Normalize container id/key-based names into a single helper
- */
-function getContainerKeyOrIdName(node) {
-    if (!node) {
-        return null;
-    }
-    if (node.id) {
-        const idName = (0, require_story_utils_1.getNodeName)(node.id);
-        if (typeof idName === "string" && idName.length > 0) {
-            return idName;
-        }
-    }
-    if (node.key) {
-        const keyName = (0, require_story_utils_1.getNodeName)(node.key);
-        if (typeof keyName === "string" && keyName.length > 0) {
-            return keyName;
-        }
-        if (node.key.type === "Literal" &&
-            typeof node.key.value === "string" &&
-            node.key.value.length > 0) {
-            return node.key.value;
-        }
-    }
-    return null;
-}
-/**
- * Small utility to walk the node and its parents to extract an Identifier or key name.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Walk node and parents to find Identifier/Key name
- */
-function extractName(node) {
-    let current = node;
-    while (current) {
-        const directIdentifierName = getDirectIdentifierName(current);
-        if (directIdentifierName) {
-            return directIdentifierName;
-        }
-        const containerName = getContainerKeyOrIdName(current);
-        if (containerName) {
-            return containerName;
-        }
-        const directName = current.name;
-        if (typeof directName === "string" && directName.length > 0) {
-            return directName;
-        }
-        current = current.parent;
-    }
-    return "(anonymous)";
-}
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function shouldProcessNode(node, scope, exportPriority = "all", options) {
     if (node &&
@@ -372,7 +96,7 @@ function shouldProcessNode(node, scope, exportPriority = "all", options) {
     if (!scope.includes(node.type)) {
         return false;
     }
-    const exported = isExportedNode(node);
+    const exported = (0, require_story_node_utils_1.isExportedNode)(node);
     if (exportPriority === "exported" && !exported) {
         return false;
     }
@@ -381,48 +105,16 @@ function shouldProcessNode(node, scope, exportPriority = "all", options) {
     }
     return true;
 }
-/**
- * Resolve the effective function name to report for a node.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Centralize reported function name resolution
- */
-function getReportedFunctionName(node) {
-    const candidate = node && (node.id || node.key) ? node.id || node.key : node;
-    return extractName(candidate);
-}
-/**
- * Determine the most appropriate AST node to anchor error location for a report.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Normalize name node selection for error reporting
- */
-function getNameNodeForReport(node) {
-    if (node?.id?.type === "Identifier") {
-        return node.id;
-    }
-    if (node?.key?.type === "Identifier") {
-        return node.key;
-    }
-    return node;
-}
-/**
- * Resolve the node that should receive the @story annotation,
- * respecting an explicitly passed target when provided.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Centralize annotation target node resolution
- */
-function resolveAnnotationTargetNode(sourceCode, node, passedTarget) {
-    return passedTarget ?? resolveTargetNode(sourceCode, node);
-}
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function reportMissing(context, sourceCode, config) {
     (0, require_story_core_1.coreReportMissing)({
-        hasStoryAnnotation,
-        hasStoryAnnotationWithPlacement,
-        getReportedFunctionName,
-        resolveAnnotationTargetNode,
-        getNameNodeForReport,
+        hasStoryAnnotation: require_story_comment_detection_1.hasStoryAnnotation,
+        hasStoryAnnotationWithPlacement: require_story_comment_detection_1.hasStoryAnnotationWithPlacement,
+        getReportedFunctionName: require_story_name_extraction_1.getReportedFunctionName,
+        resolveAnnotationTargetNode: require_story_node_utils_1.resolveAnnotationTargetNode,
+        getNameNodeForReport: require_story_name_extraction_1.getNameNodeForReport,
         buildTemplateConfig,
-        extractName,
+        extractName: require_story_name_extraction_1.extractName,
         getAnnotationTemplate,
         shouldApplyAutoFix,
         createAddStoryFix: require_story_core_1.createAddStoryFix,
@@ -432,13 +124,13 @@ function reportMissing(context, sourceCode, config) {
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function reportMethod(context, sourceCode, config) {
     (0, require_story_core_1.coreReportMethod)({
-        hasStoryAnnotation,
-        hasStoryAnnotationWithPlacement,
-        getReportedFunctionName,
-        resolveAnnotationTargetNode,
-        getNameNodeForReport,
+        hasStoryAnnotation: require_story_comment_detection_1.hasStoryAnnotation,
+        hasStoryAnnotationWithPlacement: require_story_comment_detection_1.hasStoryAnnotationWithPlacement,
+        getReportedFunctionName: require_story_name_extraction_1.getReportedFunctionName,
+        resolveAnnotationTargetNode: require_story_node_utils_1.resolveAnnotationTargetNode,
+        getNameNodeForReport: require_story_name_extraction_1.getNameNodeForReport,
         buildTemplateConfig,
-        extractName,
+        extractName: require_story_name_extraction_1.extractName,
         getAnnotationTemplate,
         shouldApplyAutoFix,
         createAddStoryFix: require_story_core_1.createAddStoryFix,

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

@@ -1,4 +1,5 @@
 "use strict";
+/* eslint-disable traceability/valid-annotation-format */
 /**
  * IO helpers for require-story detection moved to reduce helper module size
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md

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

@@ -0,0 +1,35 @@
+/**
+ * Extract a direct Identifier name when available on the given node.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract direct Identifier-based names from nodes
+ */
+export declare function getDirectIdentifierName(node: any): string | null;
+/**
+ * Normalize container nodes that expose names via id/key properties.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Normalize container id/key-based names into a single helper
+ */
+export declare function getContainerKeyOrIdName(node: any): string | null;
+/**
+ * Small utility to walk the node and its parents to extract an Identifier or key name.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Walk node and parents to find Identifier/Key name
+ */
+export declare function extractName(node: any): string;
+/**
+ * Resolve the effective function name to report for a node.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Centralize reported function name resolution
+ */
+export declare function getReportedFunctionName(node: any): string;
+/**
+ * Determine the most appropriate AST node to anchor error location for a report.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Normalize name node selection for error reporting
+ */
+export declare function getNameNodeForReport(node: any): any;

package/lib/src/rules/helpers/require-story-name-extraction.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDirectIdentifierName = getDirectIdentifierName;
+exports.getContainerKeyOrIdName = getContainerKeyOrIdName;
+exports.extractName = extractName;
+exports.getReportedFunctionName = getReportedFunctionName;
+exports.getNameNodeForReport = getNameNodeForReport;
+/**
+ * Name extraction utilities for require-story rule
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - File-level header for name extraction utilities
+ */
+const require_story_utils_1 = require("./require-story-utils");
+/**
+ * Extract a direct Identifier name when available on the given node.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract direct Identifier-based names from nodes
+ */
+function getDirectIdentifierName(node) {
+    if (node &&
+        node.type === "Identifier" &&
+        typeof node.name === "string" &&
+        node.name.length > 0) {
+        return node.name;
+    }
+    return null;
+}
+/**
+ * Normalize container nodes that expose names via id/key properties.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Normalize container id/key-based names into a single helper
+ */
+function getContainerKeyOrIdName(node) {
+    if (!node) {
+        return null;
+    }
+    if (node.id) {
+        const idName = (0, require_story_utils_1.getNodeName)(node.id);
+        if (typeof idName === "string" && idName.length > 0) {
+            return idName;
+        }
+    }
+    if (node.key) {
+        const keyName = (0, require_story_utils_1.getNodeName)(node.key);
+        if (typeof keyName === "string" && keyName.length > 0) {
+            return keyName;
+        }
+        if (node.key.type === "Literal" &&
+            typeof node.key.value === "string" &&
+            node.key.value.length > 0) {
+            return node.key.value;
+        }
+    }
+    return null;
+}
+/**
+ * Small utility to walk the node and its parents to extract an Identifier or key name.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Walk node and parents to find Identifier/Key name
+ */
+function extractName(node) {
+    let current = node;
+    while (current) {
+        const directIdentifierName = getDirectIdentifierName(current);
+        if (directIdentifierName) {
+            return directIdentifierName;
+        }
+        const containerName = getContainerKeyOrIdName(current);
+        if (containerName) {
+            return containerName;
+        }
+        const directName = current.name;
+        if (typeof directName === "string" && directName.length > 0) {
+            return directName;
+        }
+        current = current.parent;
+    }
+    return "(anonymous)";
+}
+/**
+ * Resolve the effective function name to report for a node.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Centralize reported function name resolution
+ */
+function getReportedFunctionName(node) {
+    const candidate = node && (node.id || node.key) ? node.id || node.key : node;
+    return extractName(candidate);
+}
+/**
+ * Determine the most appropriate AST node to anchor error location for a report.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Normalize name node selection for error reporting
+ */
+function getNameNodeForReport(node) {
+    if (node?.id?.type === "Identifier") {
+        return node.id;
+    }
+    if (node?.key?.type === "Identifier") {
+        return node.key;
+    }
+    return node;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Determine whether a node represents an anonymous arrow function expression
+ * where the parent variable declarator has no explicit Identifier name.
+ *
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-ARROW-FUNCTION-EXCLUDED
+ */
+export declare function isAnonymousArrowFunction(node: any): boolean;
+/**
+ * Determine whether a function-like node is nested within another function.
+ *
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-NESTED-FUNCTION-INHERITANCE
+ */
+export declare function isNestedFunction(node: any): boolean;
+/**
+ * Determine whether a function-like node is effectively anonymous for the
+ * purposes of nested-function inheritance. Named functions must always carry
+ * their own annotations, while anonymous nested functions may inherit.
+ *
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-NESTED-FUNCTION-INHERITANCE
+ */
+export declare function isEffectivelyAnonymousFunction(node: any): boolean;
+/**
+ * Determine if a node is in an export declaration
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Check node ancestry to find export declarations
+ */
+export declare function isExportedNode(node: any): boolean;
+/**
+ * Determine AST node where annotation should be inserted
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Determine correct insertion target for annotation
+ */
+export declare function resolveTargetNode(sourceCode: any, node: any): any;
+/**
+ * Resolve the node that should receive the `@story` annotation,
+ * respecting an explicitly passed target when provided.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Centralize annotation target node resolution
+ */
+export declare function resolveAnnotationTargetNode(sourceCode: any, node: any, passedTarget: any): any;