eslint-plugin-traceability 1.10.1 → 1.11.1

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

@@ -1,17 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = void 0;
+exports.EXPORT_PRIORITY_VALUES = exports.STORY_PATH = exports.DEFAULT_SCOPE = void 0;
 exports.createAddStoryFix = createAddStoryFix;
 exports.createMethodFix = createMethodFix;
-exports.reportMissing = reportMissing;
-exports.reportMethod = reportMethod;
-const require_story_helpers_1 = require("./require-story-helpers");
+exports.coreReportMissing = coreReportMissing;
+exports.coreReportMethod = coreReportMethod;
 /**
  * Create a fixer function that inserts a @story annotation before the target node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-AUTOFIX - Provide automatic fix function for missing @story annotations
  */
-function createAddStoryFix(target) {
+function createAddStoryFix(target, annotationTemplate) {
     /**
      * Fixer that inserts a @story annotation before the target node.
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -29,7 +28,7 @@ function createAddStoryFix(target) {
                     ? target.range[0]
                     : 0
             : 0;
-        return fixer.insertTextBeforeRange([start, start], `${require_story_helpers_1.ANNOTATION}\n`);
+        return fixer.insertTextBeforeRange([start, start], `${annotationTemplate}\n`);
     }
     return addStoryFixer;
 }
@@ -38,7 +37,7 @@ function createAddStoryFix(target) {
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
  */
-function createMethodFix(node) {
+function createMethodFix(node, annotationTemplate) {
     /**
      * Fixer that inserts a @story annotation before a method node.
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -56,7 +55,7 @@ function createMethodFix(node) {
                     ? node.range[0]
                     : 0
             : 0;
-        return fixer.insertTextBeforeRange([start, start], `${require_story_helpers_1.ANNOTATION}\n  `);
+        return fixer.insertTextBeforeRange([start, start], `${annotationTemplate}\n  `);
     }
     return methodFixer;
 }
@@ -72,71 +71,95 @@ exports.DEFAULT_SCOPE = [
     "TSMethodSignature",
     "TSDeclareFunction",
 ];
+/**
+ * Path to the story file for function-annotation helpers.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Provide a single source of truth for the canonical story path used by helper modules
+ */
+exports.STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
 /**
  * Allowed values for export priority option.
  */
 exports.EXPORT_PRIORITY_VALUES = ["all", "exported", "non-exported"];
 /**
- * Report a missing @story annotation for a general function-like node.
+ * Core helper to report a missing @story annotation for a function-like node.
+ * Delegates actual behavior to injected dependencies so higher-level helpers
+ * can remain small while sharing error-reporting behavior.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-AUTOFIX - Report missing annotation and provide autofix using createAddStoryFix
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-AUTOFIX-MISSING
+ * @req REQ-ERROR-SPECIFIC
  */
-function reportMissing(context, sourceCode, node, target) {
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-AUTOFIX - Prefer provided sourceCode, fallback to context.getSourceCode()
-    const sc = sourceCode || context.getSourceCode();
-    /**
-     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-     * @req REQ-AUTOFIX - Only attempt to read JSDoc comment if source supports it
-     */
-    if (typeof sc?.getJSDocComment === "function") {
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQUIRED - Skip reporting when JSDoc already contains @story
-        const js = sc.getJSDocComment(node);
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQUIRED - If @story present in JSDoc, do not report
-        if (js && typeof js.value === "string" && js.value.includes("@story"))
+function coreReportMissing(deps, context, sourceCode, config) {
+    const { node, target: passedTarget, options = {} } = config;
+    try {
+        if (deps.hasStoryAnnotation(sourceCode, node)) {
             return;
+        }
+        const functionName = deps.getReportedFunctionName(node);
+        const resolvedTarget = deps.resolveAnnotationTargetNode(sourceCode, node, passedTarget);
+        const nameNode = deps.getNameNodeForReport(node);
+        const { effectiveTemplate, allowFix } = deps.buildTemplateConfig(options);
+        const name = functionName;
+        context.report({
+            node: nameNode,
+            messageId: "missingStory",
+            data: { name, functionName: name },
+            fix: allowFix
+                ? deps.createAddStoryFix(resolvedTarget, effectiveTemplate)
+                : undefined,
+            suggest: [
+                {
+                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
+                    fix: deps.createAddStoryFix(resolvedTarget, effectiveTemplate),
+                },
+            ],
+        });
+    }
+    catch {
+        /* noop */
     }
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQUIRED - Resolve function name for reporting, default to <unknown>
-    const name = node && node.id && node.id.name ? node.id.name : "<unknown>";
-    const resolvedTarget = target ?? node;
-    const nameNode = node && node.id && node.id.type === "Identifier"
-        ? node.id
-        : node && node.key && node.key.type === "Identifier"
-            ? node.key
-            : node;
-    context.report({
-        node: nameNode,
-        messageId: "missingStory",
-        data: { name },
-        suggest: [
-            {
-                desc: `Add JSDoc @story annotation for function '${name}', e.g., ${require_story_helpers_1.ANNOTATION}`,
-                fix: createAddStoryFix(resolvedTarget),
-            },
-        ],
-    });
 }
 /**
- * Report missing @story annotation for methods
+ * Core helper to report a missing @story annotation for a method-like node.
+ * Delegates actual behavior to injected dependencies while keeping this
+ * module focused on core error-reporting behavior.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ * @req REQ-AUTOFIX-MISSING
+ * @req REQ-ERROR-SPECIFIC
  */
-function reportMethod(context, sourceCode, node, target) {
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQUIRED - Resolve method name for reporting, default to <unknown>
-    const name = node && node.key && node.key.name ? node.key.name : "<unknown>";
-    context.report({
-        node,
-        messageId: "missingStory",
-        data: { name },
-        suggest: [
-            {
-                desc: `Add JSDoc @story annotation for function '${name}', e.g., ${require_story_helpers_1.ANNOTATION}`,
-                fix: createMethodFix(target ?? node),
-            },
-        ],
-    });
+function coreReportMethod(deps, context, sourceCode, config) {
+    const { node, target: passedTarget, options = {} } = config;
+    try {
+        if (deps.hasStoryAnnotation(sourceCode, node)) {
+            return;
+        }
+        const resolvedTarget = passedTarget ?? deps.resolveAnnotationTargetNode(sourceCode, node, null);
+        const name = deps.extractName(node);
+        const nameNode = (node.key && node.key.type === "Identifier" && node.key) || node;
+        const effectiveTemplate = deps.getAnnotationTemplate(options.annotationTemplateOverride);
+        const allowFix = deps.shouldApplyAutoFix(options.autoFixToggle);
+        context.report({
+            node: nameNode,
+            messageId: "missingStory",
+            data: { name, functionName: name },
+            fix: allowFix
+                ? deps.createMethodFix(resolvedTarget, effectiveTemplate)
+                : undefined,
+            suggest: [
+                {
+                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
+                    fix: deps.createMethodFix(resolvedTarget, effectiveTemplate),
+                },
+            ],
+        });
+    }
+    catch {
+        /* noop */
+    }
 }

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

@@ -1,29 +1,27 @@
 /**
  * Helpers for the "require-story" rule
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-ANNOTATION-REQUIRED - File-level header for rule helper utilities
+ * @req REQ-AUTOFIX-MISSING
+ * @req REQ-AUTOFIX-TEMPLATE
+ * @req REQ-AUTOFIX-SELECTIVE
  */
 import type { Rule } from "eslint";
 import { linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory } from "./require-story-io";
 import { getNodeName } from "./require-story-utils";
-import { DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES } from "./require-story-core";
-/**
- * Path to the story file for annotations
- */
-declare const STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
-declare const ANNOTATION = "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */";
+import { DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, STORY_PATH } from "./require-story-core";
 /**
- * Number of physical source lines to inspect before a node when searching for @story text
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Replace magic number for lookback lines with named constant
+ * Derive the annotation template, optionally using an override.
+ * When override is a non-empty string, its trimmed value is used.
+ * Otherwise, the default template is returned.
  */
-declare const LOOKBACK_LINES = 4;
+declare function getAnnotationTemplate(override?: string): string;
 /**
- * Window (in characters) to inspect before a node as a fallback when searching for @story text
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Replace magic number for fallback text window with named constant
+ * Determine whether auto-fix should be applied.
+ * Explicit false disables auto-fix; all other values enable it.
  */
-declare const FALLBACK_WINDOW = 800;
+declare function shouldApplyAutoFix(autoFix: boolean | undefined): boolean;
 /**
  * Determine if a node is in an export declaration
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -96,42 +94,23 @@ declare function extractName(node: any): string;
  * @returns {boolean} whether node should be processed
  */
 declare function shouldProcessNode(node: any, scope: string[], exportPriority?: string): boolean;
-/**
- * Report a missing @story annotation for a function-like node
- * Provides a suggestion to add the annotation.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing annotations with suggestion
- * @req REQ-AUTOFIX-MISSING - Provide autofix for missing annotations while preserving suggestions
- * @req REQ-ERROR-SPECIFIC - Error reports must include both name and functionName in the data payload for specific function context
- * @param {Rule.RuleContext} context - ESLint rule context used to report
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - AST node that is missing the annotation
- * @param {any} [passedTarget] - optional AST node to use as insertion target instead of resolving from node
- */
-declare function reportMissing(context: Rule.RuleContext, sourceCode: any, node: any, passedTarget?: any): void;
-/**
- * Report a missing @story annotation for a method-like node
- * Provides a suggestion to update the method/interface with the annotation.
- * The error data payload uses both name and functionName for consistent, specific error context.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
- * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing method/interface annotations with suggestion
- * @req REQ-AUTOFIX-MISSING - Provide autofix for missing method/interface annotations while preserving suggestions
- * @req REQ-ERROR-SPECIFIC - Method error reports must include both name and functionName in the data payload for specific function context
- * @req REQ-ERROR-LOCATION - Method error reports must use the method name node to anchor error location
- * @req REQ-ERROR-CONTEXT - Method error reports must include functionName data for consistent error context
- * @param {Rule.RuleContext} context - ESLint rule context to report
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - AST node that is missing the annotation
- * @param {any} [passedTarget] - optional AST node to use as insertion target instead of resolving from node
- */
-declare function reportMethod(context: Rule.RuleContext, sourceCode: any, node: any, passedTarget?: any): void;
+interface ReportOptions {
+    annotationTemplateOverride?: string;
+    autoFixToggle?: boolean;
+}
+declare function reportMissing(context: Rule.RuleContext, sourceCode: any, config: {
+    node: any;
+    target?: any;
+    options?: ReportOptions;
+}): void;
+declare function reportMethod(context: Rule.RuleContext, sourceCode: any, config: {
+    node: any;
+    target?: any;
+    options?: ReportOptions;
+}): void;
 /**
  * Explicit exports for require-story-annotation consumers
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Explicitly export helper functions and constants used by requiring modules
  */
-export { STORY_PATH, ANNOTATION, LOOKBACK_LINES, FALLBACK_WINDOW, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, getNodeName, extractName, resolveTargetNode, shouldProcessNode, reportMissing, reportMethod, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, };
+export { STORY_PATH, getAnnotationTemplate, shouldApplyAutoFix, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, getNodeName, extractName, resolveTargetNode, shouldProcessNode, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, reportMissing, reportMethod, };

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

@@ -1,6 +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.FALLBACK_WINDOW = exports.LOOKBACK_LINES = exports.ANNOTATION = exports.STORY_PATH = void 0;
+exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.getNodeName = exports.STORY_PATH = void 0;
+exports.getAnnotationTemplate = getAnnotationTemplate;
+exports.shouldApplyAutoFix = shouldApplyAutoFix;
 exports.isExportedNode = isExportedNode;
 exports.jsdocHasStory = jsdocHasStory;
 exports.commentsBeforeHasStory = commentsBeforeHasStory;
@@ -20,27 +22,28 @@ Object.defineProperty(exports, "getNodeName", { enumerable: true, get: function
 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; } });
 /**
- * Path to the story file for annotations
+ * Derive the annotation template, optionally using an override.
+ * When override is a non-empty string, its trimmed value is used.
+ * Otherwise, the default template is returned.
  */
-const STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
-exports.STORY_PATH = STORY_PATH;
-const ANNOTATION = `/** @story ${STORY_PATH} */`;
-exports.ANNOTATION = ANNOTATION;
-/**
- * Number of physical source lines to inspect before a node when searching for @story text
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Replace magic number for lookback lines with named constant
- */
-const LOOKBACK_LINES = 4;
-exports.LOOKBACK_LINES = LOOKBACK_LINES;
+function getAnnotationTemplate(override) {
+    if (typeof override === "string" && override.trim().length > 0) {
+        return override.trim();
+    }
+    return `/** @story ${require_story_core_1.STORY_PATH} */`;
+}
 /**
- * Window (in characters) to inspect before a node as a fallback when searching for @story text
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Replace magic number for fallback text window with named constant
+ * Determine whether auto-fix should be applied.
+ * Explicit false disables auto-fix; all other values enable it.
  */
-const FALLBACK_WINDOW = 800;
-exports.FALLBACK_WINDOW = FALLBACK_WINDOW;
+function shouldApplyAutoFix(autoFix) {
+    if (autoFix === false) {
+        return false;
+    }
+    return true;
+}
 /**
  * Determine if a node is in an export declaration
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -126,7 +129,7 @@ function hasStoryAnnotation(sourceCode, node) {
         if (leadingCommentsHasStory(node)) {
             return true;
         }
-        if ((0, require_story_io_1.linesBeforeHasStory)(sourceCode, node, LOOKBACK_LINES)) {
+        if ((0, require_story_io_1.linesBeforeHasStory)(sourceCode, node)) {
             return true;
         }
         if ((0, require_story_io_1.parentChainHasStory)(sourceCode, node)) {
@@ -173,6 +176,54 @@ function resolveTargetNode(sourceCode, node) {
     }
     return node;
 }
+/**
+ * Extract a direct Identifier name when available on the given node.
+ * This focuses only on plain Identifier nodes and ignores container shapes.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract direct Identifier-based names from nodes
+ * @param {any} node - AST node to inspect
+ * @returns {string | null} identifier name or null when not applicable
+ */
+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.
+ * Supports common function and method containers, including literal keys.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Normalize container id/key-based names into a single helper
+ * @param {any} node - AST node that may contain id/key name information
+ * @returns {string | null} resolved container name or null when unavailable
+ */
+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.
  * Walks up the parent chain and inspects common properties (id, key, name, Identifier nodes).
@@ -182,33 +233,21 @@ function resolveTargetNode(sourceCode, node) {
  * @returns {string} extracted name or "(anonymous)" when no name found
  */
 function extractName(node) {
-    let n = node;
-    while (n) {
-        // Direct Identifier node
-        if (n.type === "Identifier" && typeof n.name === "string") {
-            return n.name;
-        }
-        // id property (FunctionDeclaration, etc.)
-        if (n.id && n.id.type === "Identifier" && typeof n.id.name === "string") {
-            return n.id.name;
+    let current = node;
+    while (current) {
+        const directIdentifierName = getDirectIdentifierName(current);
+        if (directIdentifierName) {
+            return directIdentifierName;
         }
-        // key property (Property, MethodDefinition, etc.)
-        if (n.key &&
-            n.key.type === "Identifier" &&
-            typeof n.key.name === "string") {
-            return n.key.name;
+        const containerName = getContainerKeyOrIdName(current);
+        if (containerName) {
+            return containerName;
         }
-        // name property (some nodes may have a 'name' string directly)
-        if (typeof n.name === "string" && n.name.length > 0) {
-            return n.name;
+        const directName = current.name;
+        if (typeof directName === "string" && directName.length > 0) {
+            return directName;
         }
-        // computed keys may have an Identifier inside
-        if (n.key &&
-            n.key.type === "Literal" &&
-            typeof n.key.value === "string") {
-            return n.key.value;
-        }
-        n = n.parent;
+        current = current.parent;
     }
     return "(anonymous)";
 }
@@ -235,86 +274,85 @@ function shouldProcessNode(node, scope, exportPriority = "all") {
     return true;
 }
 /**
- * Report a missing @story annotation for a function-like node
- * Provides a suggestion to add the annotation.
+ * Resolve the effective function name to report for a node.
+ * Normalizes id/key handling before delegating to extractName.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing annotations with suggestion
- * @req REQ-AUTOFIX-MISSING - Provide autofix for missing annotations while preserving suggestions
- * @req REQ-ERROR-SPECIFIC - Error reports must include both name and functionName in the data payload for specific function context
- * @param {Rule.RuleContext} context - ESLint rule context used to report
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - AST node that is missing the annotation
- * @param {any} [passedTarget] - optional AST node to use as insertion target instead of resolving from node
+ * @req REQ-ANNOTATION-REQUIRED - Centralize reported function name resolution
+ * @param {any} node - AST node used to derive the function name
+ * @returns {string} resolved function name
  */
-function reportMissing(context, sourceCode, node, passedTarget) {
-    try {
-        const functionName = extractName(node && (node.id || node.key) ? node.id || node.key : node);
-        if (hasStoryAnnotation(sourceCode, node)) {
-            return;
-        }
-        const resolvedTarget = passedTarget ?? resolveTargetNode(sourceCode, node);
-        const name = functionName;
-        const nameNode = (node.id && node.id.type === "Identifier" && node.id) ||
-            (node.key && node.key.type === "Identifier" && node.key) ||
-            node;
-        context.report({
-            node: nameNode,
-            messageId: "missingStory",
-            data: { name, functionName: name },
-            fix: (0, require_story_core_1.createAddStoryFix)(resolvedTarget),
-            suggest: [
-                {
-                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${ANNOTATION}`,
-                    fix: (0, require_story_core_1.createAddStoryFix)(resolvedTarget),
-                },
-            ],
-        });
+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.
+ * Prefers Identifier nodes from id/key properties when available.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Normalize name node selection for error reporting
+ * @param {any} node - AST node used for error anchoring
+ * @returns {any} node to use as the report location
+ */
+function getNameNodeForReport(node) {
+    if (node?.id?.type === "Identifier") {
+        return node.id;
     }
-    catch {
-        /* noop */
+    if (node?.key?.type === "Identifier") {
+        return node.key;
     }
+    return node;
 }
 /**
- * Report a missing @story annotation for a method-like node
- * Provides a suggestion to update the method/interface with the annotation.
- * The error data payload uses both name and functionName for consistent, specific error context.
+ * 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
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
- * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing method/interface annotations with suggestion
- * @req REQ-AUTOFIX-MISSING - Provide autofix for missing method/interface annotations while preserving suggestions
- * @req REQ-ERROR-SPECIFIC - Method error reports must include both name and functionName in the data payload for specific function context
- * @req REQ-ERROR-LOCATION - Method error reports must use the method name node to anchor error location
- * @req REQ-ERROR-CONTEXT - Method error reports must include functionName data for consistent error context
- * @param {Rule.RuleContext} context - ESLint rule context to report
+ * @req REQ-ANNOTATION-REQUIRED - Centralize annotation target node resolution
  * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - AST node that is missing the annotation
- * @param {any} [passedTarget] - optional AST node to use as insertion target instead of resolving from node
+ * @param {any} node - original function-like AST node
+ * @param {any} passedTarget - optional explicit annotation target
+ * @returns {any} node that should receive the annotation
  */
-function reportMethod(context, sourceCode, node, passedTarget) {
-    try {
-        if (hasStoryAnnotation(sourceCode, node)) {
-            return;
-        }
-        const resolvedTarget = passedTarget ?? resolveTargetNode(sourceCode, node);
-        const name = extractName(node);
-        const nameNode = (node.key && node.key.type === "Identifier" && node.key) || node;
-        context.report({
-            node: nameNode,
-            messageId: "missingStory",
-            data: { name, functionName: name },
-            fix: (0, require_story_core_1.createMethodFix)(resolvedTarget),
-            suggest: [
-                {
-                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${ANNOTATION}`,
-                    fix: (0, require_story_core_1.createMethodFix)(resolvedTarget),
-                },
-            ],
-        });
-    }
-    catch {
-        /* noop */
-    }
+function resolveAnnotationTargetNode(sourceCode, node, passedTarget) {
+    return passedTarget ?? resolveTargetNode(sourceCode, node);
+}
+/**
+ * Build the effective annotation template and autofix toggle
+ * from the provided report options.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Normalize template and autofix configuration
+ * @param {ReportOptions} [options] - optional report configuration
+ * @returns {{ effectiveTemplate: string; allowFix: boolean }} template and autofix flags
+ */
+function buildTemplateConfig(options) {
+    const effectiveTemplate = getAnnotationTemplate(options?.annotationTemplateOverride);
+    const allowFix = shouldApplyAutoFix(options?.autoFixToggle);
+    return { effectiveTemplate, allowFix };
+}
+function reportMissing(context, sourceCode, config) {
+    (0, require_story_core_1.coreReportMissing)({
+        hasStoryAnnotation,
+        getReportedFunctionName,
+        resolveAnnotationTargetNode,
+        getNameNodeForReport,
+        buildTemplateConfig,
+        extractName,
+        getAnnotationTemplate,
+        shouldApplyAutoFix,
+        createAddStoryFix: require_story_core_1.createAddStoryFix,
+        createMethodFix: require_story_core_1.createMethodFix,
+    }, context, sourceCode, config);
+}
+function reportMethod(context, sourceCode, config) {
+    (0, require_story_core_1.coreReportMethod)({
+        hasStoryAnnotation,
+        getReportedFunctionName,
+        resolveAnnotationTargetNode,
+        getNameNodeForReport,
+        buildTemplateConfig,
+        extractName,
+        getAnnotationTemplate,
+        shouldApplyAutoFix,
+        createAddStoryFix: require_story_core_1.createAddStoryFix,
+        createMethodFix: require_story_core_1.createMethodFix,
+    }, context, sourceCode, config);
 }