eslint-plugin-traceability 1.11.0 → 1.11.1

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

@@ -1,6 +1,6 @@
 "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.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;
@@ -22,11 +22,7 @@ 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; } });
-/**
- * Path to the story file for annotations
- */
-const STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
-exports.STORY_PATH = STORY_PATH;
+Object.defineProperty(exports, "STORY_PATH", { enumerable: true, get: function () { return require_story_core_1.STORY_PATH; } });
 /**
  * Derive the annotation template, optionally using an override.
  * When override is a non-empty string, its trimmed value is used.
@@ -36,7 +32,7 @@ function getAnnotationTemplate(override) {
     if (typeof override === "string" && override.trim().length > 0) {
         return override.trim();
     }
-    return `/** @story ${STORY_PATH} */`;
+    return `/** @story ${require_story_core_1.STORY_PATH} */`;
 }
 /**
  * Determine whether auto-fix should be applied.
@@ -48,20 +44,6 @@ function shouldApplyAutoFix(autoFix) {
     }
     return true;
 }
-/**
- * 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;
-/**
- * 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
- */
-const FALLBACK_WINDOW = 800;
-exports.FALLBACK_WINDOW = FALLBACK_WINDOW;
 /**
  * Determine if a node is in an export declaration
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -147,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)) {
@@ -194,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).
@@ -203,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)";
 }
@@ -256,94 +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 {{ node: any; target?: any; options?: ReportOptions }} config - configuration containing the node to report, optional insertion target, and optional report options
+ * @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, config) {
-    const { node, target: passedTarget, options = {} } = config;
-    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;
-        const effectiveTemplate = getAnnotationTemplate(options.annotationTemplateOverride);
-        const allowFix = shouldApplyAutoFix(options.autoFixToggle);
-        context.report({
-            node: nameNode,
-            messageId: "missingStory",
-            data: { name, functionName: name },
-            fix: allowFix
-                ? (0, require_story_core_1.createAddStoryFix)(resolvedTarget, effectiveTemplate)
-                : undefined,
-            suggest: [
-                {
-                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
-                    fix: (0, require_story_core_1.createAddStoryFix)(resolvedTarget, effectiveTemplate),
-                },
-            ],
-        });
+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 {{ node: any; target?: any; options?: ReportOptions }} config - configuration containing the node to report, optional insertion target, and optional report options
+ * @param {any} node - original function-like AST node
+ * @param {any} passedTarget - optional explicit annotation target
+ * @returns {any} node that should receive the annotation
  */
+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) {
-    const { node, target: passedTarget, options = {} } = config;
-    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;
-        const effectiveTemplate = getAnnotationTemplate(options.annotationTemplateOverride);
-        const allowFix = shouldApplyAutoFix(options.autoFixToggle);
-        context.report({
-            node: nameNode,
-            messageId: "missingStory",
-            data: { name, functionName: name },
-            fix: allowFix
-                ? (0, require_story_core_1.createMethodFix)(resolvedTarget, effectiveTemplate)
-                : undefined,
-            suggest: [
-                {
-                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
-                    fix: (0, require_story_core_1.createMethodFix)(resolvedTarget, effectiveTemplate),
-                },
-            ],
-        });
-    }
-    catch {
-        /* noop */
-    }
+    (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);
 }

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

@@ -133,42 +133,32 @@ function parentChainHasStory(sourceCode, node) {
     return false;
 }
 /**
- * Fallback: inspect text immediately preceding the node in sourceCode.getText to find @story
- * Also accepts @supports annotations as satisfying story presence for this rule.
+ * Safely compute the starting range index for fallback text scanning.
+ * Centralizes guards around sourceCode.getText and node.range structure.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @supports annotations as satisfying story presence in fallback checks
+ * @req REQ-ANNOTATION-REQUIRED - Centralize guards for fallback range computation
  */
-function fallbackTextBeforeHasStory(sourceCode, node) {
-    // Skip fallback text inspection when the sourceCode API or node range information is not available.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQUIRED - Avoid throwing when source text or range metadata cannot be read
-    if (typeof sourceCode?.getText !== "function" ||
-        !Array.isArray((node && node.range) || [])) {
-        return false;
+function getFallbackRangeStart(sourceCode, node) {
+    if (typeof sourceCode?.getText !== "function") {
+        return null;
     }
-    const range = node.range;
-    // Guard against malformed range values that cannot provide a numeric start index for slicing.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQUIRED - Validate node range structure before computing fallback window
+    const range = (node && node.range) || null;
     if (!Array.isArray(range) || typeof range[0] !== "number") {
-        return false;
+        return null;
     }
+    return range[0];
+}
+/**
+ * Safely slice a bounded fallback text window immediately preceding the node start index.
+ * Restricts scanning to a fixed-size window and treats IO/slicing failures as non-fatal.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Restrict fallback text scanning to a safe, fixed-size window and handle failures gracefully
+ */
+function getFallbackTextWindow(sourceCode, nodeStartIndex) {
+    const start = Math.max(0, nodeStartIndex - exports.FALLBACK_WINDOW);
     try {
-        // Limit the fallback inspection window to a bounded region immediately preceding the node.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQUIRED - Restrict fallback text scanning to a safe, fixed-size window
-        const start = Math.max(0, range[0] - exports.FALLBACK_WINDOW);
-        const textBefore = sourceCode.getText().slice(start, range[0]);
-        // Detect any @story or @supports marker that appears within the bounded fallback window.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQUIRED - Recognize story annotations discovered via fallback text scanning
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Recognize @supports annotations discovered via fallback text scanning
-        if (typeof textBefore === "string" &&
-            (textBefore.includes("@story") || textBefore.includes("@supports"))) {
-            return true;
-        }
+        const textBefore = sourceCode.getText().slice(start, nodeStartIndex);
+        return typeof textBefore === "string" ? textBefore : null;
     }
     catch {
         /*
@@ -176,6 +166,36 @@ function fallbackTextBeforeHasStory(sourceCode, node) {
          * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
          * @req REQ-ANNOTATION-REQUIRED - Treat fallback text inspection failures as "no annotation" instead of raising
          */
+        return null;
     }
-    return false;
+}
+/**
+ * Detect whether the provided fallback text window contains a story marker.
+ * Recognizes both @story and @supports annotations in the inspected text.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Recognize story annotations discovered via fallback text scanning
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Recognize @supports annotations discovered via fallback text scanning
+ */
+function fallbackTextHasMarker(textBefore) {
+    if (typeof textBefore !== "string") {
+        return false;
+    }
+    return textBefore.includes("@story") || textBefore.includes("@supports");
+}
+/**
+ * Fallback: inspect text immediately preceding the node in sourceCode.getText to find @story
+ * Also accepts @supports annotations as satisfying story presence for this rule.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @supports annotations as satisfying story presence in fallback checks
+ */
+function fallbackTextBeforeHasStory(sourceCode, node) {
+    const nodeStartIndex = getFallbackRangeStart(sourceCode, node);
+    if (nodeStartIndex === null) {
+        return false;
+    }
+    const textBefore = getFallbackTextWindow(sourceCode, nodeStartIndex);
+    return fallbackTextHasMarker(textBefore);
 }

package/lib/src/rules/helpers/valid-annotation-options.d.ts

@@ -119,6 +119,9 @@ export declare function getRuleSchema(): {
         requirementIdExample: {
             type: string;
         };
+        autoFix: {
+            type: string;
+        };
     };
     additionalProperties: boolean;
 }[];

package/lib/src/rules/helpers/valid-annotation-options.js

@@ -105,46 +105,88 @@ function resolveExample(nestedExample, flatExample, defaultExample) {
     }
     return defaultExample;
 }
-/**
- * Resolve user options into concrete, validated configuration.
- * Falls back to existing defaults when options are not provided or invalid.
- */
-function resolveOptions(rawOptions) {
-    optionErrors = [];
-    const user = normalizeUserOptions(rawOptions);
-    const nestedStoryPattern = user?.story?.pattern;
-    const flatStoryPattern = user?.storyPathPattern;
-    const nestedStoryExample = user?.story?.example;
-    const flatStoryExample = user?.storyPathExample;
-    const nestedReqPattern = user?.req?.pattern;
-    const flatReqPattern = user?.requirementIdPattern;
-    const nestedReqExample = user?.req?.example;
-    const flatReqExample = user?.requirementIdExample;
+function getUserOptions(rawOptions) {
+    return normalizeUserOptions(rawOptions);
+}
+function resolveAutoFixFlag(user) {
     const autoFixFlag = user?.autoFix;
-    const autoFix = typeof autoFixFlag === "boolean" ? autoFixFlag : true;
-    const storyPattern = resolvePattern({
+    return typeof autoFixFlag === "boolean" ? autoFixFlag : true;
+}
+function resolveStoryPattern(nestedStoryPattern, flatStoryPattern) {
+    return resolvePattern({
         nestedPattern: nestedStoryPattern,
         nestedFieldName: "story.pattern",
         flatPattern: flatStoryPattern,
         flatFieldName: "storyPathPattern",
         defaultPattern: getDefaultStoryPattern(),
     });
-    const reqPattern = resolvePattern({
+}
+function resolveReqPattern(nestedReqPattern, flatReqPattern) {
+    return resolvePattern({
         nestedPattern: nestedReqPattern,
         nestedFieldName: "req.pattern",
         flatPattern: flatReqPattern,
         flatFieldName: "requirementIdPattern",
         defaultPattern: getDefaultReqPattern(),
     });
-    const storyExample = resolveExample(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
-    const reqExample = resolveExample(nestedReqExample, flatReqExample, getDefaultReqExample());
-    resolvedDefaults = {
+}
+function resolveStoryExample(nestedStoryExample, flatStoryExample) {
+    return resolveExample(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
+}
+function resolveReqExample(nestedReqExample, flatReqExample) {
+    return resolveExample(nestedReqExample, flatReqExample, getDefaultReqExample());
+}
+function getStoryPatternInputs(user) {
+    return {
+        nestedStoryPattern: user?.story?.pattern,
+        flatStoryPattern: user?.storyPathPattern,
+    };
+}
+function getStoryExampleInputs(user) {
+    return {
+        nestedStoryExample: user?.story?.example,
+        flatStoryExample: user?.storyPathExample,
+    };
+}
+function getReqPatternInputs(user) {
+    return {
+        nestedReqPattern: user?.req?.pattern,
+        flatReqPattern: user?.requirementIdPattern,
+    };
+}
+function getReqExampleInputs(user) {
+    return {
+        nestedReqExample: user?.req?.example,
+        flatReqExample: user?.requirementIdExample,
+    };
+}
+function resolveOptionsInternal(user) {
+    const { nestedStoryPattern, flatStoryPattern } = getStoryPatternInputs(user);
+    const { nestedStoryExample, flatStoryExample } = getStoryExampleInputs(user);
+    const { nestedReqPattern, flatReqPattern } = getReqPatternInputs(user);
+    const { nestedReqExample, flatReqExample } = getReqExampleInputs(user);
+    const autoFix = resolveAutoFixFlag(user);
+    const storyPattern = resolveStoryPattern(nestedStoryPattern, flatStoryPattern);
+    const reqPattern = resolveReqPattern(nestedReqPattern, flatReqPattern);
+    const storyExample = resolveStoryExample(nestedStoryExample, flatStoryExample);
+    const reqExample = resolveReqExample(nestedReqExample, flatReqExample);
+    return {
         storyPattern,
         storyExample,
         reqPattern,
         reqExample,
         autoFix,
     };
+}
+/**
+ * Resolve user options into concrete, validated configuration.
+ * Falls back to existing defaults when options are not provided or invalid.
+ */
+function resolveOptions(rawOptions) {
+    optionErrors = [];
+    const user = getUserOptions(rawOptions);
+    const resolved = resolveOptionsInternal(user);
+    resolvedDefaults = resolved;
     return resolvedDefaults;
 }
 /**
@@ -175,6 +217,7 @@ function getRuleSchema() {
                 storyPathExample: { type: "string" },
                 requirementIdPattern: { type: "string" },
                 requirementIdExample: { type: "string" },
+                autoFix: { type: "boolean" },
             },
             additionalProperties: false,
         },

package/lib/src/utils/annotation-checker.js

@@ -90,6 +90,34 @@ function createMissingReqFix(node) {
         return fixer.insertTextBefore(target, "/** @req <REQ-ID> */\n");
     };
 }
+/**
+ * Resolve the display name used when reporting a missing @req annotation.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REPORTING - Use consistent naming when reporting missing @req
+ * @req REQ-ERROR-SPECIFIC - Derive a specific, human-readable name for the node
+ */
+function getReportedName(contextNode, parentNode) {
+    const rawName = (0, require_story_utils_1.getNodeName)(contextNode) ?? (0, require_story_utils_1.getNodeName)(parentNode);
+    return rawName ?? "(anonymous)";
+}
+/**
+ * Determine the AST sub-node that should be used as the location for reporting.
+ * Prefers Identifier nodes (id or key) over the broader function-like node.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REPORTING - Report missing @req on the most relevant node
+ * @req REQ-ERROR-SPECIFIC - Target the identifier when available for precise errors
+ */
+function getNameNodeForReqReport(node) {
+    const candidateId = node.id;
+    if (candidateId && candidateId.type === "Identifier") {
+        return candidateId;
+    }
+    const candidateKey = node.key;
+    if (candidateKey && candidateKey.type === "Identifier") {
+        return candidateKey;
+    }
+    return node;
+}
 /**
  * Helper to report a missing @req annotation via the ESLint context API.
  * Uses getNodeName to provide a readable name for the node.
@@ -102,13 +130,9 @@ function createMissingReqFix(node) {
  * @req REQ-ERROR-CONTEXT - Include contextual hints to help understand the error
  */
 function reportMissing(context, node, enableFix = true) {
-    const rawName = (0, require_story_utils_1.getNodeName)(node) ?? (node && (0, require_story_utils_1.getNodeName)(node.parent));
-    const name = rawName ?? "(anonymous)";
-    const nameNode = (node && node.id && node.id.type === "Identifier"
-        ? node.id
-        : node && node.key && node.key.type === "Identifier"
-            ? node.key
-            : node) ?? node;
+    const parentNode = node?.parent;
+    const name = getReportedName(node, parentNode);
+    const nameNode = getNameNodeForReqReport(node);
     const reportOptions = {
         node: nameNode,
         messageId: "missingReq",