eslint-plugin-traceability 1.4.3 → 1.4.5

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

@@ -0,0 +1,293 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.FALLBACK_WINDOW = exports.LOOKBACK_LINES = exports.ANNOTATION = exports.STORY_PATH = void 0;
+exports.isExportedNode = isExportedNode;
+exports.jsdocHasStory = jsdocHasStory;
+exports.commentsBeforeHasStory = commentsBeforeHasStory;
+exports.leadingCommentsHasStory = leadingCommentsHasStory;
+exports.hasStoryAnnotation = hasStoryAnnotation;
+exports.getNodeName = getNodeName;
+exports.resolveTargetNode = resolveTargetNode;
+exports.shouldProcessNode = shouldProcessNode;
+exports.reportMissing = reportMissing;
+exports.reportMethod = reportMethod;
+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_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;
+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;
+/**
+ * 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
+ * @req REQ-ANNOTATION-REQUIRED - Check node ancestry to find export declarations
+ * @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;
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQUIRED - Walk parent chain to find Export declarations
+    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
+ * @param {any} sourceCode - ESLint sourceCode object
+ * @param {any} node - AST node to inspect
+ * @returns {boolean} true if JSDoc contains @story
+ */
+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
+ * @param {any} sourceCode - ESLint sourceCode object
+ * @param {any} node - AST node to inspect
+ * @returns {boolean} true if any preceding comment contains @story
+ */
+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
+ * @param {any} node - AST node to inspect
+ * @returns {boolean} true if any leading comment contains @story
+ */
+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
+ * @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) {
+    try {
+        if (jsdocHasStory(sourceCode, node)) {
+            return true;
+        }
+        if (commentsBeforeHasStory(sourceCode, node)) {
+            return true;
+        }
+        if (leadingCommentsHasStory(node)) {
+            return true;
+        }
+        if ((0, require_story_io_1.linesBeforeHasStory)(sourceCode, node, LOOKBACK_LINES)) {
+            return true;
+        }
+        if ((0, require_story_io_1.parentChainHasStory)(sourceCode, node)) {
+            return true;
+        }
+        if ((0, require_story_io_1.fallbackTextBeforeHasStory)(sourceCode, node)) {
+            return true;
+        }
+    }
+    catch {
+        /* noop */
+    }
+    return false;
+}
+/**
+ * Get the name of the function-like node
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Resolve a human-friendly name for a function-like AST node
+ * @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 - Determine correct insertion target for annotation
+ * @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;
+}
+/**
+ * Check if this node is within scope and matches exportPriority
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Determine whether a node should be processed by rule
+ * @param {any} node - AST node to evaluate
+ * @param {string[]} scope - allowed node types
+ * @param {string} [exportPriority='all'] - 'all' | 'exported' | 'non-exported' (default: 'all')
+ * @returns {boolean} whether node should be processed
+ */
+function shouldProcessNode(node, scope, exportPriority = "all") {
+    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;
+}
+/**
+ * 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
+ * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing annotations with suggestion
+ * @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
+ */
+function reportMissing(context, sourceCode, node, passedTarget) {
+    try {
+        const functionName = getNodeName(node);
+        if (hasStoryAnnotation(sourceCode, node)) {
+            return;
+        }
+        const resolvedTarget = passedTarget ?? resolveTargetNode(sourceCode, node);
+        const name = functionName;
+        context.report({
+            node,
+            messageId: "missingStory",
+            data: { name },
+            suggest: [
+                {
+                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${ANNOTATION}`,
+                    fix: (0, require_story_core_1.createAddStoryFix)(resolvedTarget),
+                },
+            ],
+        });
+    }
+    catch {
+        /* noop */
+    }
+}
+/**
+ * Report a missing @story annotation for a method-like node
+ * Provides a suggestion to update the method/interface with the annotation.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing method/interface annotations with suggestion
+ * @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
+ */
+function reportMethod(context, sourceCode, node, passedTarget) {
+    try {
+        if (hasStoryAnnotation(sourceCode, node)) {
+            return;
+        }
+        const resolvedTarget = passedTarget ?? resolveTargetNode(sourceCode, node);
+        const name = getNodeName(node);
+        context.report({
+            node,
+            messageId: "missingStory",
+            data: { name },
+            suggest: [
+                {
+                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${ANNOTATION}`,
+                    fix: (0, require_story_core_1.createMethodFix)(resolvedTarget),
+                },
+            ],
+        });
+    }
+    catch {
+        /* noop */
+    }
+}

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

@@ -0,0 +1,35 @@
+/**
+ * IO helpers for require-story detection moved to reduce helper module size
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract IO bound helpers to separate module
+ */
+/**
+ * Number of source lines to inspect before a node when searching for @story markers.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Expose lookback size as constant for reuse
+ */
+export declare const LOOKBACK_LINES = 4;
+/**
+ * Number of characters to include in the fallback textual inspection window before a node.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Expose fallback window size as constant for reuse
+ */
+export declare const FALLBACK_WINDOW = 800;
+/**
+ * Inspect a fixed number of physical source lines before the node for @story text
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract line-based detection into helper
+ */
+export declare function linesBeforeHasStory(sourceCode: any, node: any, lookback?: number): boolean;
+/**
+ * Walk parent chain and check comments before each parent and their leadingComments
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract parent-chain comment detection into helper
+ */
+export declare function parentChainHasStory(sourceCode: any, node: any): boolean;
+/**
+ * Fallback: inspect text immediately preceding the node in sourceCode.getText to find @story
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
+ */
+export declare function fallbackTextBeforeHasStory(sourceCode: any, node: any): boolean;

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

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * IO helpers for require-story detection moved to reduce helper module size
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract IO bound helpers to separate module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FALLBACK_WINDOW = exports.LOOKBACK_LINES = void 0;
+exports.linesBeforeHasStory = linesBeforeHasStory;
+exports.parentChainHasStory = parentChainHasStory;
+exports.fallbackTextBeforeHasStory = fallbackTextBeforeHasStory;
+/**
+ * Number of source lines to inspect before a node when searching for @story markers.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Expose lookback size as constant for reuse
+ */
+exports.LOOKBACK_LINES = 4;
+/**
+ * Number of characters to include in the fallback textual inspection window before a node.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Expose fallback window size as constant for reuse
+ */
+exports.FALLBACK_WINDOW = 800;
+/**
+ * Inspect a fixed number of physical source lines before the node for @story text
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract line-based detection into helper
+ */
+function linesBeforeHasStory(sourceCode, node, lookback = exports.LOOKBACK_LINES) {
+    const lines = sourceCode && sourceCode.lines;
+    const startLine = node && node.loc && typeof node.loc.start?.line === "number"
+        ? node.loc.start.line
+        : null;
+    if (!Array.isArray(lines) || typeof startLine !== "number") {
+        return false;
+    }
+    const from = Math.max(0, startLine - 1 - lookback);
+    const to = Math.max(0, startLine - 1);
+    for (let i = from; i < to; i++) {
+        const text = lines[i];
+        if (typeof text === "string" && text.includes("@story")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Walk parent chain and check comments before each parent and their leadingComments
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract parent-chain comment detection into helper
+ */
+function parentChainHasStory(sourceCode, node) {
+    let p = node && node.parent;
+    while (p) {
+        const pComments = typeof sourceCode?.getCommentsBefore === "function"
+            ? sourceCode.getCommentsBefore(p) || []
+            : [];
+        if (Array.isArray(pComments) &&
+            pComments.some(
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-ANNOTATION-REQUIRED - Detect @story in parent comments via value inspection
+             */
+            (c) => typeof c.value === "string" && c.value.includes("@story"))) {
+            return true;
+        }
+        const pLeading = p.leadingComments || [];
+        if (Array.isArray(pLeading) &&
+            pLeading.some(
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-ANNOTATION-REQUIRED - Detect @story in parent leadingComments via value inspection
+             */
+            (c) => typeof c.value === "string" && c.value.includes("@story"))) {
+            return true;
+        }
+        p = p.parent;
+    }
+    return false;
+}
+/**
+ * Fallback: inspect text immediately preceding the node in sourceCode.getText to find @story
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
+ */
+function fallbackTextBeforeHasStory(sourceCode, node) {
+    if (typeof sourceCode?.getText !== "function" ||
+        !Array.isArray((node && node.range) || [])) {
+        return false;
+    }
+    const range = node.range;
+    if (!Array.isArray(range) || typeof range[0] !== "number") {
+        return false;
+    }
+    try {
+        // Limit the fallback inspect window to a reasonable size
+        const start = Math.max(0, range[0] - exports.FALLBACK_WINDOW);
+        const textBefore = sourceCode.getText().slice(start, range[0]);
+        if (typeof textBefore === "string" && textBefore.includes("@story")) {
+            return true;
+        }
+    }
+    catch {
+        /* noop */
+    }
+    return false;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Visitor builders for require-story-annotation rule
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-EXTRACT-VISITORS - Extract visitor logic into helper module to reduce rule file size
+ */
+import type { Rule } from "eslint";
+/**
+ * Build visitor handlers for various function-like AST nodes.
+ * Returns merged listener object from smaller builders.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-BUILD-VISITORS - Provide visitor implementations for rule create()
+ */
+export declare function buildVisitors(context: Rule.RuleContext, sourceCode: any, options: any): Rule.RuleListener;

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

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Visitor builders for require-story-annotation rule
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-EXTRACT-VISITORS - Extract visitor logic into helper module to reduce rule file size
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVisitors = buildVisitors;
+const require_story_helpers_1 = require("./require-story-helpers");
+/**
+ * Build visitor for FunctionDeclaration nodes.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-BUILD-VISITORS-FNDECL - Provide visitor for FunctionDeclaration
+ */
+function buildFunctionDeclarationVisitor(context, sourceCode, options) {
+    /**
+     * Handle FunctionDeclaration nodes.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-ANNOTATION-REQUIRED - Report missing @story on function declarations
+     */
+    function handleFunctionDeclaration(node) {
+        /**
+         * Debug logging for visitor entry
+         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+         * @req REQ-DEBUG-LOG - Provide debug logging for visitor entry
+         */
+        console.debug("require-story-annotation:FunctionDeclaration", typeof context.getFilename === "function"
+            ? context.getFilename()
+            : "<unknown>", node && node.id ? node.id.name : "<anonymous>");
+        if (!options.shouldProcessNode(node))
+            return;
+        const target = (0, require_story_helpers_1.resolveTargetNode)(sourceCode, node);
+        (0, require_story_helpers_1.reportMissing)(context, sourceCode, node, target);
+    }
+    return {
+        FunctionDeclaration: handleFunctionDeclaration,
+    };
+}
+/**
+ * Build visitor for FunctionExpression nodes.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-BUILD-VISITORS-FNEXPR - Provide visitor for FunctionExpression
+ */
+function buildFunctionExpressionVisitor(context, sourceCode, options) {
+    /**
+     * Handle FunctionExpression nodes.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-ANNOTATION-REQUIRED - Report missing @story on function expressions
+     */
+    function handleFunctionExpression(node) {
+        if (!options.shouldProcessNode(node))
+            return;
+        /**
+         * Do not report when function expression is a MethodDefinition
+         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+         * @req REQ-METHOD-SKIP - Skip MethodDefinition function expressions
+         */
+        if (node.parent && node.parent.type === "MethodDefinition")
+            return;
+        const target = (0, require_story_helpers_1.resolveTargetNode)(sourceCode, node);
+        (0, require_story_helpers_1.reportMissing)(context, sourceCode, node, target);
+    }
+    return {
+        FunctionExpression: handleFunctionExpression,
+    };
+}
+/**
+ * Build visitor for ArrowFunctionExpression nodes.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-BUILD-VISITORS-ARROW - Provide visitor for ArrowFunctionExpression
+ */
+function buildArrowFunctionVisitor(context, sourceCode, options) {
+    /**
+     * Handle ArrowFunctionExpression nodes.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-ANNOTATION-REQUIRED - Report missing @story on arrow functions
+     */
+    function handleArrowFunctionExpression(node) {
+        if (!options.shouldProcessNode(node))
+            return;
+        const target = (0, require_story_helpers_1.resolveTargetNode)(sourceCode, node);
+        (0, require_story_helpers_1.reportMissing)(context, sourceCode, node, target);
+    }
+    return {
+        ArrowFunctionExpression: handleArrowFunctionExpression,
+    };
+}
+/**
+ * Build visitor for TypeScript TSDeclareFunction nodes.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-BUILD-VISITORS-TSDECL - Provide visitor for TSDeclareFunction
+ */
+function buildTSDeclareFunctionVisitor(context, sourceCode, options) {
+    /**
+     * Handle TSDeclareFunction nodes.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-ANNOTATION-REQUIRED - Report missing @story on TS declare functions
+     */
+    function handleTSDeclareFunction(node) {
+        if (!options.shouldProcessNode(node))
+            return;
+        (0, require_story_helpers_1.reportMissing)(context, sourceCode, node, node);
+    }
+    return {
+        TSDeclareFunction: handleTSDeclareFunction,
+    };
+}
+/**
+ * Build visitor for TypeScript TSMethodSignature nodes.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-BUILD-VISITORS-TSMSIG - Provide visitor for TSMethodSignature
+ */
+function buildTSMethodSignatureVisitor(context, sourceCode, options) {
+    /**
+     * Handle TSMethodSignature nodes.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-ANNOTATION-REQUIRED - Report missing @story on TS method signatures
+     */
+    function handleTSMethodSignature(node) {
+        if (!options.shouldProcessNode(node))
+            return;
+        const target = (0, require_story_helpers_1.resolveTargetNode)(sourceCode, node);
+        (0, require_story_helpers_1.reportMissing)(context, sourceCode, node, target);
+    }
+    return {
+        TSMethodSignature: handleTSMethodSignature,
+    };
+}
+/**
+ * Build visitor for MethodDefinition nodes.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-BUILD-VISITORS-METHODDEF - Provide visitor for MethodDefinition
+ */
+function buildMethodDefinitionVisitor(context, sourceCode, options) {
+    /**
+     * Handle MethodDefinition nodes (class/object methods).
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-ANNOTATION-REQUIRED - Report missing @story on class/object methods
+     */
+    function handleMethodDefinition(node) {
+        if (!options.shouldProcessNode(node))
+            return;
+        (0, require_story_helpers_1.reportMethod)(context, sourceCode, node);
+    }
+    return {
+        MethodDefinition: handleMethodDefinition,
+    };
+}
+/**
+ * Build visitor handlers for various function-like AST nodes.
+ * Returns merged listener object from smaller builders.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-BUILD-VISITORS - Provide visitor implementations for rule create()
+ */
+function buildVisitors(context, sourceCode, options) {
+    const fnDecl = buildFunctionDeclarationVisitor(context, sourceCode, options);
+    const fnExpr = buildFunctionExpressionVisitor(context, sourceCode, options);
+    const arrow = buildArrowFunctionVisitor(context, sourceCode, options);
+    const tsDecl = buildTSDeclareFunctionVisitor(context, sourceCode, options);
+    const tsSig = buildTSMethodSignatureVisitor(context, sourceCode, options);
+    const methodDef = buildMethodDefinitionVisitor(context, sourceCode, options);
+    return Object.assign({}, fnDecl, fnExpr, arrow, tsDecl, tsSig, methodDef);
+}

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

@@ -1,3 +1,18 @@
+/**
+ * ESLint rule module: require-story-annotation
+ *
+ * This file implements the ESLint rule that requires @story annotations
+ * on functions and methods according to configured scope and export priority.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ */
 import type { Rule } from "eslint";
+/**
+ * ESLint rule to require @story annotations on functions/methods.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ */
 declare const rule: Rule.RuleModule;
 export default rule;