eslint-plugin-traceability 1.4.3 → 1.4.4

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

@@ -1,198 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-// Default node types to check for function annotations
-const DEFAULT_SCOPE = [
-    "FunctionDeclaration",
-    "FunctionExpression",
-    "ArrowFunctionExpression",
-    "MethodDefinition",
-    "TSDeclareFunction",
-    "TSMethodSignature",
-];
-const EXPORT_PRIORITY_VALUES = ["all", "exported", "non-exported"];
+const require_story_visitors_1 = require("./helpers/require-story-visitors");
+const require_story_helpers_1 = require("./helpers/require-story-helpers");
 /**
- * Determine if a node is in an export declaration
+ * ESLint rule to require @story annotations on functions/methods.
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED
- * @param {any} node - AST node to check for export ancestry
- * @returns {boolean} true if node is within an export declaration
  */
-function isExportedNode(node) {
-    let p = node.parent;
-    while (p) {
-        if (p.type === "ExportNamedDeclaration" ||
-            p.type === "ExportDefaultDeclaration") {
-            return true;
-        }
-        p = p.parent;
-    }
-    return false;
-}
-// Path to the story file for annotations
-const STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
-const ANNOTATION = `/** @story ${STORY_PATH} */`;
-/**
- * Check if @story annotation already present in JSDoc or preceding comments
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - AST node to inspect for existing annotations
- * @returns {boolean} true if @story annotation already present
- */
-function hasStoryAnnotation(sourceCode, node) {
-    const jsdoc = sourceCode.getJSDocComment(node);
-    if (jsdoc?.value.includes("@story")) {
-        return true;
-    }
-    const comments = sourceCode.getCommentsBefore(node) || [];
-    return comments.some((c) => c.value.includes("@story"));
-}
-/**
- * Get the name of the function-like node
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {any} node - AST node representing a function-like construct
- * @returns {string} the resolved name or "<unknown>"
- */
-function getNodeName(node) {
-    let current = node;
-    while (current) {
-        if (current.type === "VariableDeclarator" &&
-            current.id &&
-            typeof current.id.name === "string") {
-            return current.id.name;
-        }
-        if ((current.type === "FunctionDeclaration" ||
-            current.type === "TSDeclareFunction") &&
-            current.id &&
-            typeof current.id.name === "string") {
-            return current.id.name;
-        }
-        if ((current.type === "MethodDefinition" ||
-            current.type === "TSMethodSignature") &&
-            current.key &&
-            typeof current.key.name === "string") {
-            return current.key.name;
-        }
-        current = current.parent;
-    }
-    return "<unknown>";
-}
-/**
- * Determine AST node where annotation should be inserted
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {any} sourceCode - ESLint sourceCode object (unused but kept for parity)
- * @param {any} node - function-like AST node to resolve target for
- * @returns {any} AST node that should receive the annotation
- */
-function resolveTargetNode(sourceCode, node) {
-    if (node.type === "TSMethodSignature") {
-        // Interface method signature -> insert on interface
-        return node.parent.parent;
-    }
-    if (node.type === "FunctionExpression" ||
-        node.type === "ArrowFunctionExpression") {
-        const parent = node.parent;
-        if (parent.type === "VariableDeclarator") {
-            const varDecl = parent.parent;
-            if (varDecl.parent && varDecl.parent.type === "ExportNamedDeclaration") {
-                return varDecl.parent;
-            }
-            return varDecl;
-        }
-        if (parent.type === "ExportNamedDeclaration") {
-            return parent;
-        }
-        if (parent.type === "ExpressionStatement") {
-            return parent;
-        }
-    }
-    return node;
-}
-/**
- * Report missing @story annotation on function or method
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {Rule.RuleContext} context - ESLint rule context
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - function AST node missing annotation
- * @param {any} target - AST node where annotation should be inserted
- */
-function reportMissing(context, sourceCode, node, target) {
-    if (hasStoryAnnotation(sourceCode, node) ||
-        hasStoryAnnotation(sourceCode, target)) {
-        return;
-    }
-    let name = getNodeName(node);
-    if (node.type === "TSDeclareFunction" && node.id && node.id.name) {
-        name = node.id.name;
-    }
-    context.report({
-        node,
-        messageId: "missingStory",
-        data: { name },
-        suggest: [
-            {
-                desc: `Add JSDoc @story annotation for function '${name}', e.g., ${ANNOTATION}`,
-                fix: (fixer) => fixer.insertTextBefore(target, `${ANNOTATION}\n`),
-            },
-        ],
-    });
-}
-/**
- * Report missing @story annotation on class methods
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {Rule.RuleContext} context - ESLint rule context
- * @param {any} sourceCode - ESLint sourceCode object
- * @param {any} node - MethodDefinition AST node
- */
-function reportMethod(context, sourceCode, node) {
-    if (hasStoryAnnotation(sourceCode, node)) {
-        return;
-    }
-    context.report({
-        node,
-        messageId: "missingStory",
-        data: { name: getNodeName(node) },
-        suggest: [
-            {
-                desc: `Add JSDoc @story annotation for function '${getNodeName(node)}', e.g., ${ANNOTATION}`,
-                fix: (fixer) => fixer.insertTextBefore(node, `${ANNOTATION}\n  `),
-            },
-        ],
-    });
-}
-/**
- * Check if this node is within scope and matches exportPriority
- *
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
- * @param {any} node - AST node to evaluate
- * @param {string[]} scope - allowed node types
- * @param {string} exportPriority - 'all' | 'exported' | 'non-exported'
- * @returns {boolean} whether node should be processed
- */
-function shouldProcessNode(node, scope, exportPriority) {
-    if (!scope.includes(node.type)) {
-        return false;
-    }
-    const exported = isExportedNode(node);
-    if (exportPriority === "exported" && !exported) {
-        return false;
-    }
-    if (exportPriority === "non-exported" && exported) {
-        return false;
-    }
-    return true;
-}
 const rule = {
     meta: {
         type: "problem",
@@ -210,99 +25,43 @@ const rule = {
                 properties: {
                     scope: {
                         type: "array",
-                        items: { type: "string", enum: DEFAULT_SCOPE },
+                        items: { type: "string", enum: require_story_helpers_1.DEFAULT_SCOPE },
                         uniqueItems: true,
                     },
-                    exportPriority: { type: "string", enum: EXPORT_PRIORITY_VALUES },
+                    exportPriority: { type: "string", enum: require_story_helpers_1.EXPORT_PRIORITY_VALUES },
                 },
                 additionalProperties: false,
             },
         ],
     },
     /**
-     * Create the rule visitor functions for require-story-annotation.
+     * Create the rule visitor functions.
+     *
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-     * @req REQ-CREATE-HOOK - Provide create(context) hook for rule behavior
+     * @req REQ-CREATE-HOOK
      */
     create(context) {
         const sourceCode = context.getSourceCode();
-        const opts = context.options[0] ||
-            {};
-        const scope = opts.scope || DEFAULT_SCOPE;
+        const opts = (context.options && context.options[0]) || {};
+        const scope = opts.scope || require_story_helpers_1.DEFAULT_SCOPE;
         const exportPriority = opts.exportPriority || "all";
-        return {
-            FunctionDeclaration(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                let target = node;
-                if (node.parent &&
-                    (node.parent.type === "ExportNamedDeclaration" ||
-                        node.parent.type === "ExportDefaultDeclaration")) {
-                    target = node.parent;
-                }
-                reportMissing(context, sourceCode, node, target);
-            },
-            /**
-             * Handle FunctionExpression nodes
-             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-ANNOTATION-REQUIRED
-             * @param {any} node - FunctionExpression AST node
-             */
-            FunctionExpression(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                if (node.parent && node.parent.type === "MethodDefinition")
-                    return;
-                const target = resolveTargetNode(sourceCode, node);
-                reportMissing(context, sourceCode, node, target);
-            },
-            /**
-             * Handle ArrowFunctionExpression nodes
-             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-ANNOTATION-REQUIRED
-             * @param {any} node - ArrowFunctionExpression AST node
-             */
-            ArrowFunctionExpression(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                const target = resolveTargetNode(sourceCode, node);
-                reportMissing(context, sourceCode, node, target);
-            },
-            /**
-             * Handle TSDeclareFunction nodes
-             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-ANNOTATION-REQUIRED
-             * @param {any} node - TSDeclareFunction AST node
-             */
-            TSDeclareFunction(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                reportMissing(context, sourceCode, node, node);
-            },
-            /**
-             * Handle TSMethodSignature nodes
-             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-ANNOTATION-REQUIRED
-             * @param {any} node - TSMethodSignature AST node
-             */
-            TSMethodSignature(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                const target = resolveTargetNode(sourceCode, node);
-                reportMissing(context, sourceCode, node, target);
-            },
-            /**
-             * Handle MethodDefinition nodes
-             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-ANNOTATION-REQUIRED
-             * @param {any} node - MethodDefinition AST node
-             */
-            MethodDefinition(node) {
-                if (!shouldProcessNode(node, scope, exportPriority))
-                    return;
-                reportMethod(context, sourceCode, node);
-            },
-        };
+        /**
+         * Debug log at the start of create to help diagnose rule activation in tests.
+         *
+         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+         * @req REQ-DEBUG-LOG
+         */
+        console.debug("require-story-annotation:create", typeof context.getFilename === "function"
+            ? context.getFilename()
+            : "<unknown>");
+        // Local closure that binds configured scope and export priority to the helper.
+        const should = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority);
+        // Delegate visitor construction to helper to keep this file concise.
+        return (0, require_story_visitors_1.buildVisitors)(context, sourceCode, {
+            shouldProcessNode: should,
+            scope,
+            exportPriority,
+        });
     },
 };
 exports.default = rule;

package/lib/src/utils/branch-annotation-helpers.js

@@ -31,28 +31,47 @@ exports.DEFAULT_BRANCH_TYPES = [
  */
 function validateBranchTypes(context) {
     const options = context.options[0] || {};
+    /**
+     * Conditional branch checking whether branchTypes option was provided.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-CONDITIONAL - Trace configuration branch existence check
+     */
     if (Array.isArray(options.branchTypes)) {
-        // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-        // @req REQ-TRACEABILITY-FILTER-CALLBACK - Trace filter callback for invalid branch type detection
-        const invalidTypes = options.branchTypes.filter((t) => !exports.DEFAULT_BRANCH_TYPES.includes(t));
+        /**
+         * Predicate to determine whether a provided branch type is invalid.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-FILTER-CALLBACK - Trace filter callback for invalid branch type detection
+         */
+        function isInvalidType(t) {
+            return !exports.DEFAULT_BRANCH_TYPES.includes(t);
+        }
+        const invalidTypes = options.branchTypes.filter(isInvalidType);
+        /**
+         * Conditional branch checking whether any invalid types were found.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-INVALID-DETECTION - Trace handling when invalid types are detected
+         */
         if (invalidTypes.length > 0) {
             /**
              * Program listener produced when configuration is invalid.
              * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
              * @req REQ-TRACEABILITY-PROGRAM-LISTENER - Trace Program listener reporting invalid config values
              */
-            return {
-                Program(node) {
-                    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-                    // @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace reporting for each invalid type
-                    invalidTypes.forEach((t) => {
-                        context.report({
-                            node,
-                            message: `Value "${t}" should be equal to one of the allowed values: ${exports.DEFAULT_BRANCH_TYPES.join(", ")}`,
-                        });
+            function ProgramHandler(node) {
+                /**
+                 * Report a single invalid type for the given Program node.
+                 * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+                 * @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace reporting for each invalid type
+                 */
+                function reportInvalidType(t) {
+                    context.report({
+                        node,
+                        message: `Value "${t}" should be equal to one of the allowed values: ${exports.DEFAULT_BRANCH_TYPES.join(", ")}`,
                     });
-                },
-            };
+                }
+                invalidTypes.forEach(reportInvalidType);
+            }
+            return { Program: ProgramHandler };
         }
     }
     return Array.isArray(options.branchTypes)
@@ -65,6 +84,11 @@ function validateBranchTypes(context) {
  * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
  */
 function gatherBranchCommentText(sourceCode, node) {
+    /**
+     * Conditional branch for SwitchCase nodes that may include inline comments.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-SWITCHCASE-COMMENTS - Trace collection of preceding comments for SwitchCase
+     */
     if (node.type === "SwitchCase") {
         const lines = sourceCode.lines;
         const startLine = node.loc.start.line;
@@ -79,9 +103,15 @@ function gatherBranchCommentText(sourceCode, node) {
         return comments.join(" ");
     }
     const comments = sourceCode.getCommentsBefore(node) || [];
-    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-    // @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
-    return comments.map((c) => c.value).join(" ");
+    /**
+     * Mapper to extract the text value from a comment node.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-MAP-CALLBACK - Trace mapping of comment nodes to their text values
+     */
+    function commentToValue(c) {
+        return c.value;
+    }
+    return comments.map(commentToValue).join(" ");
 }
 /**
  * Report missing @story annotation on a branch node.
@@ -90,15 +120,25 @@ function gatherBranchCommentText(sourceCode, node) {
  */
 function reportMissingStory(context, node, options) {
     const { indent, insertPos, storyFixCountRef } = options;
+    /**
+     * Conditional branch deciding whether to offer an auto-fix for the missing story.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-FIX-DECISION - Trace decision to provide fixer for missing @story
+     */
     if (storyFixCountRef.count === 0) {
+        /**
+         * Fixer that inserts a default @story annotation above the branch.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer function used to insert missing @story
+         */
+        function insertStoryFixer(fixer) {
+            return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`);
+        }
         context.report({
             node,
             messageId: "missingAnnotation",
             data: { missing: "@story" },
-            fix: 
-            // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-            // @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer arrow function used to insert missing @story
-            (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`),
+            fix: insertStoryFixer,
         });
         storyFixCountRef.count++;
     }
@@ -117,15 +157,25 @@ function reportMissingStory(context, node, options) {
  */
 function reportMissingReq(context, node, options) {
     const { indent, insertPos, missingStory } = options;
+    /**
+     * Conditional branch deciding whether to offer an auto-fix for the missing req.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-FIX-DECISION - Trace decision to provide fixer for missing @req
+     */
     if (!missingStory) {
+        /**
+         * Fixer that inserts a default @req annotation above the branch.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer function used to insert missing @req
+         */
+        function insertReqFixer(fixer) {
+            return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`);
+        }
         context.report({
             node,
             messageId: "missingAnnotation",
             data: { missing: "@req" },
-            fix: 
-            // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-            // @req REQ-TRACEABILITY-FIX-ARROW - Trace fixer arrow function used to insert missing @req
-            (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`),
+            fix: insertReqFixer,
         });
     }
     else {
@@ -163,10 +213,20 @@ function reportMissingAnnotations(context, node, storyFixCountRef) {
             args: [context, node, { indent, insertPos, missingStory }],
         },
     ];
-    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-    // @req REQ-TRACEABILITY-ACTIONS-FOREACH - Trace processing of actions array to report missing annotations
-    actions.forEach(({ missing, fn, args }) => 
-    // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-    // @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace callback handling for each action item
-    missing && fn(...args));
+    /**
+     * Process a single action from the actions array.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-TRACEABILITY-ACTIONS-FOREACH - Trace processing of actions array to report missing annotations
+     */
+    function processAction(item) {
+        /**
+         * Callback invoked for each action to decide and execute reporting.
+         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+         * @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace callback handling for each action item
+         */
+        if (item.missing) {
+            item.fn(...item.args);
+        }
+    }
+    actions.forEach(processAction);
 }

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

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