eslint-plugin-traceability 1.3.0 → 1.4.0

package/lib/src/index.d.ts

@@ -4,7 +4,7 @@
  * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
  */
 export declare const rules: {
-    "require-story-annotation": any;
+    "require-story-annotation": import("eslint").Rule.RuleModule;
     "require-req-annotation": any;
     "require-branch-annotation": import("eslint").Rule.RuleModule;
     "valid-annotation-format": any;
@@ -41,7 +41,7 @@ export declare const configs: {
 };
 declare const _default: {
     rules: {
-        "require-story-annotation": any;
+        "require-story-annotation": import("eslint").Rule.RuleModule;
         "require-req-annotation": any;
         "require-branch-annotation": import("eslint").Rule.RuleModule;
         "valid-annotation-format": any;

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

@@ -1,41 +1,6 @@
 "use strict";
-/* eslint-disable max-lines-per-function */
-/****
- * Rule to enforce @story and @req annotations on significant code branches
- * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
- * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-const DEFAULT_BRANCH_TYPES = [
-    "IfStatement",
-    "SwitchCase",
-    "TryStatement",
-    "CatchClause",
-    "ForStatement",
-    "ForOfStatement",
-    "ForInStatement",
-    "WhileStatement",
-    "DoWhileStatement",
-];
-/**
- * Gather leading comments for a node, with fallback for SwitchCase.
- */
-function gatherCommentText(sourceCode, node) {
-    if (node.type === "SwitchCase") {
-        const lines = sourceCode.lines;
-        const startLine = node.loc.start.line;
-        let i = startLine - 2;
-        const comments = [];
-        while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
-            comments.unshift(lines[i].trim());
-            i--;
-        }
-        return comments.join(" ");
-    }
-    const comments = sourceCode.getCommentsBefore(node) || [];
-    return comments.map((c) => c.value).join(" ");
-}
+const branch_annotation_helpers_1 = require("../utils/branch-annotation-helpers");
 const rule = {
     meta: {
         type: "problem",
@@ -61,120 +26,29 @@ const rule = {
             },
         ],
     },
+    /**
+     * Create visitor for require-branch-annotation rule.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
+     * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+     */
     create(context) {
-        const sourceCode = context.getSourceCode();
-        const options = context.options[0] || {};
-        if (Array.isArray(options.branchTypes)) {
-            const invalidTypes = options.branchTypes.filter((t) => !DEFAULT_BRANCH_TYPES.includes(t));
-            if (invalidTypes.length > 0) {
-                return {
-                    Program(node) {
-                        invalidTypes.forEach((t) => {
-                            context.report({
-                                node,
-                                message: `Value "${t}" should be equal to one of the allowed values: ${DEFAULT_BRANCH_TYPES.join(", ")}`,
-                            });
-                        });
-                    },
-                };
-            }
-        }
-        const branchTypes = Array.isArray(options.branchTypes)
-            ? options.branchTypes
-            : Array.from(DEFAULT_BRANCH_TYPES);
-        let storyFixCount = 0;
-        function reportBranch(node) {
-            const text = gatherCommentText(sourceCode, node);
-            const missingStory = !/@story\b/.test(text);
-            const missingReq = !/@req\b/.test(text);
-            const indent = sourceCode.lines[node.loc.start.line - 1].match(/^(\s*)/)?.[1] || "";
-            const insertPos = sourceCode.getIndexFromLoc({
-                line: node.loc.start.line,
-                column: 0,
-            });
-            if (missingStory) {
-                if (storyFixCount === 0) {
-                    context.report({
-                        node,
-                        messageId: "missingAnnotation",
-                        data: { missing: "@story" },
-                        fix: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`),
-                    });
-                    storyFixCount++;
-                }
-                else {
-                    context.report({
-                        node,
-                        messageId: "missingAnnotation",
-                        data: { missing: "@story" },
-                    });
-                }
-            }
-            if (missingReq) {
-                if (!missingStory) {
-                    context.report({
-                        node,
-                        messageId: "missingAnnotation",
-                        data: { missing: "@req" },
-                        fix: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`),
-                    });
-                }
-                else {
-                    context.report({
-                        node,
-                        messageId: "missingAnnotation",
-                        data: { missing: "@req" },
-                    });
-                }
-            }
+        const branchTypesOrListener = (0, branch_annotation_helpers_1.validateBranchTypes)(context);
+        if (!Array.isArray(branchTypesOrListener)) {
+            return branchTypesOrListener;
         }
-        return {
-            IfStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            SwitchCase(node) {
-                if (node.test == null || !branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            TryStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            CatchClause(node) {
-                if (!branchTypes.includes(node.type))
+        const branchTypes = branchTypesOrListener;
+        const storyFixCountRef = { count: 0 };
+        const handlers = {};
+        branchTypes.forEach((type) => {
+            handlers[type] = (node) => {
+                if (type === "SwitchCase" && node.test == null) {
                     return;
-                reportBranch(node);
-            },
-            ForStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            ForOfStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            ForInStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            WhileStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            DoWhileStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-        };
+                }
+                (0, branch_annotation_helpers_1.reportMissingAnnotations)(context, node, storyFixCountRef);
+            };
+        });
+        return handlers;
     },
 };
 exports.default = rule;

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

@@ -1,12 +1,3 @@
-/**
- * Rule to enforce @story annotation on functions, function expressions, arrow functions, and methods
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Require @story annotation on functions
- * @req REQ-OPTIONS-SCOPE - Support configuring which function types to enforce via options
- * @req REQ-EXPORT-PRIORITY - Add exportPriority option to target exported or non-exported
- * @req REQ-UNIFIED-CHECK - Implement unified checkNode for all supported node types
- * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
- * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
- */
-declare const _default: any;
-export default _default;
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

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

@@ -1,184 +1,164 @@
 "use strict";
-/**
- * Rule to enforce @story annotation on functions, function expressions, arrow functions, and methods
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Require @story annotation on functions
- * @req REQ-OPTIONS-SCOPE - Support configuring which function types to enforce via options
- * @req REQ-EXPORT-PRIORITY - Add exportPriority option to target exported or non-exported
- * @req REQ-UNIFIED-CHECK - Implement unified checkNode for all supported node types
- * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
- * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
- */
 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"];
 /**
- * Determine if a node is exported via export declaration.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-EXPORT-PRIORITY - Determine if function node has export declaration ancestor
+ * Determine if a node is in an export declaration
  */
 function isExportedNode(node) {
-    let current = node;
-    while (current) {
-        if (current.type === "ExportNamedDeclaration" ||
-            current.type === "ExportDefaultDeclaration") {
+    let p = node.parent;
+    while (p) {
+        if (p.type === "ExportNamedDeclaration" ||
+            p.type === "ExportDefaultDeclaration") {
             return true;
         }
-        current = current.parent;
+        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} */`;
 /**
- * Find nearest ancestor node of specified types.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-OPTIONS-SCOPE - Support configuring which function types to enforce via options
+ * Check if @story annotation already present in JSDoc or preceding comments
  */
-function findAncestorNode(node, types) {
-    let current = node.parent;
-    while (current) {
-        if (types.includes(current.type)) {
-            return current;
-        }
-        current = current.parent;
+function hasStoryAnnotation(sourceCode, node) {
+    const jsdoc = sourceCode.getJSDocComment(node);
+    if (jsdoc?.value.includes("@story")) {
+        return true;
     }
-    return null;
+    const comments = sourceCode.getCommentsBefore(node) || [];
+    return comments.some((c) => c.value.includes("@story"));
 }
 /**
- * Determine if node should be checked based on scope and exportPriority.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-OPTIONS-SCOPE
- * @req REQ-EXPORT-PRIORITY
- * @req REQ-UNIFIED-CHECK
+ * Get the name of the function-like node
  */
-function shouldCheckNode(node, scope, exportPriority) {
-    if (node.type === "FunctionExpression" &&
-        node.parent?.type === "MethodDefinition") {
-        return false;
-    }
-    if (!scope.includes(node.type)) {
-        return false;
-    }
-    const exported = isExportedNode(node);
-    if ((exportPriority === "exported" && !exported) ||
-        (exportPriority === "non-exported" && exported)) {
-        return false;
+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 true;
+    return "<unknown>";
 }
 /**
- * Resolve the AST node to annotate or check.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-UNIFIED-CHECK
+ * Determine AST node where annotation should be inserted
  */
 function resolveTargetNode(sourceCode, node) {
-    let target = node;
-    if (node.type === "FunctionDeclaration") {
-        const exp = findAncestorNode(node, [
-            "ExportNamedDeclaration",
-            "ExportDefaultDeclaration",
-        ]);
-        if (exp) {
-            target = exp;
-        }
+    if (node.type === "TSMethodSignature") {
+        // Interface method signature -> insert on interface
+        return node.parent.parent;
     }
-    else if (node.type === "FunctionExpression" ||
+    if (node.type === "FunctionExpression" ||
         node.type === "ArrowFunctionExpression") {
-        const exp = findAncestorNode(node, [
-            "ExportNamedDeclaration",
-            "ExportDefaultDeclaration",
-        ]);
-        if (exp) {
-            target = exp;
-        }
-        else {
-            const anc = findAncestorNode(node, [
-                "VariableDeclaration",
-                "ExpressionStatement",
-            ]);
-            if (anc) {
-                target = anc;
+        const parent = node.parent;
+        if (parent.type === "VariableDeclarator") {
+            const varDecl = parent.parent;
+            if (varDecl.parent && varDecl.parent.type === "ExportNamedDeclaration") {
+                return varDecl.parent;
             }
+            return varDecl;
         }
-    }
-    else if (node.type === "TSMethodSignature") {
-        const exp = findAncestorNode(node, ["TSInterfaceDeclaration"]);
-        if (exp) {
-            target = exp;
+        if (parent.type === "ExportNamedDeclaration") {
+            return parent;
+        }
+        if (parent.type === "ExpressionStatement") {
+            return parent;
         }
     }
-    else if (node.type === "MethodDefinition") {
-        target = node;
-    }
-    return target;
+    return node;
 }
 /**
- * Check if the target node has @story annotation.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED
+ * Report missing @story annotation on function or method
  */
-function hasStoryAnnotation(sourceCode, target) {
-    const jsdoc = sourceCode.getJSDocComment(target);
-    if (jsdoc?.value.includes("@story")) {
-        return true;
+function reportMissing(context, sourceCode, node, target) {
+    if (hasStoryAnnotation(sourceCode, node) ||
+        hasStoryAnnotation(sourceCode, target)) {
+        return;
     }
-    const comments = sourceCode.getCommentsBefore(target) || [];
-    return comments.some((c) => c.value.includes("@story"));
+    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`),
+            },
+        ],
+    });
 }
 /**
- * Check for @story annotation on function-like nodes.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-UNIFIED-CHECK
- * @req REQ-ANNOTATION-REQUIRED
+ * Report missing @story annotation on class methods
  */
-function checkStoryAnnotation(sourceCode, context, node, scope, exportPriority) {
-    if (!shouldCheckNode(node, scope, exportPriority)) {
-        return;
-    }
-    // Special handling for TSMethodSignature: allow annotation on the method itself
-    if (node.type === "TSMethodSignature") {
-        // If annotated on the method signature, skip
-        if (hasStoryAnnotation(sourceCode, node)) {
-            return;
-        }
-        // Otherwise, check on interface declaration
-        const intf = resolveTargetNode(sourceCode, node);
-        if (hasStoryAnnotation(sourceCode, intf)) {
-            return;
-        }
-        // Missing annotation: report on the interface declaration
-        context.report({
-            node: intf,
-            messageId: "missingStory",
-            fix(fixer) {
-                const indentLevel = intf.loc.start.column;
-                const indent = " ".repeat(indentLevel);
-                const insertPos = intf.range[0] - indentLevel;
-                return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}/** @story <story-file>.story.md */\n`);
-            },
-        });
-        return;
-    }
-    const target = resolveTargetNode(sourceCode, node);
-    if (hasStoryAnnotation(sourceCode, target)) {
+function reportMethod(context, sourceCode, node) {
+    if (hasStoryAnnotation(sourceCode, node)) {
         return;
     }
     context.report({
         node,
         messageId: "missingStory",
-        fix(fixer) {
-            const indentLevel = target.loc.start.column;
-            const indent = " ".repeat(indentLevel);
-            const insertPos = target.range[0] - indentLevel;
-            return fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}/** @story <story-file>.story.md */\n`);
-        },
+        data: { name: getNodeName(node) },
+        suggest: [
+            {
+                desc: `Add JSDoc @story annotation for function '${getNodeName(node)}', e.g., ${ANNOTATION}`,
+                fix: (fixer) => fixer.insertTextBefore(node, `${ANNOTATION}\n  `),
+            },
+        ],
     });
 }
-exports.default = {
+/**
+ * Check if this node is within scope and matches exportPriority
+ */
+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",
         docs: {
-            description: "Require @story annotations on selected functions",
+            description: "Require @story annotations on functions",
             recommended: "error",
         },
-        fixable: "code",
+        hasSuggestions: true,
         messages: {
             missingStory: "Missing @story annotation (REQ-ANNOTATION-REQUIRED)",
         },
@@ -188,21 +168,10 @@ exports.default = {
                 properties: {
                     scope: {
                         type: "array",
-                        items: {
-                            enum: [
-                                "FunctionDeclaration",
-                                "FunctionExpression",
-                                "ArrowFunctionExpression",
-                                "MethodDefinition",
-                                "TSDeclareFunction",
-                                "TSMethodSignature",
-                            ],
-                        },
+                        items: { type: "string", enum: DEFAULT_SCOPE },
                         uniqueItems: true,
                     },
-                    exportPriority: {
-                        enum: ["all", "exported", "non-exported"],
-                    },
+                    exportPriority: { type: "string", enum: EXPORT_PRIORITY_VALUES },
                 },
                 additionalProperties: false,
             },
@@ -210,39 +179,53 @@ exports.default = {
     },
     create(context) {
         const sourceCode = context.getSourceCode();
-        const options = context.options[0] || {};
-        const scope = options.scope || [
-            "FunctionDeclaration",
-            "FunctionExpression",
-            "ArrowFunctionExpression",
-            "MethodDefinition",
-            "TSDeclareFunction",
-            "TSMethodSignature",
-        ];
-        const exportPriority = options.exportPriority || "all";
+        const opts = context.options[0] ||
+            {};
+        const scope = opts.scope || DEFAULT_SCOPE;
+        const exportPriority = opts.exportPriority || "all";
         return {
             FunctionDeclaration(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+                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);
             },
             FunctionExpression(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                if (node.parent && node.parent.type === "MethodDefinition")
+                    return;
+                const target = resolveTargetNode(sourceCode, node);
+                reportMissing(context, sourceCode, node, target);
             },
             ArrowFunctionExpression(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                const target = resolveTargetNode(sourceCode, node);
+                reportMissing(context, sourceCode, node, target);
             },
-            MethodDefinition(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
-            },
-            // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-            // @req REQ-FUNCTION-DETECTION - Detect TS-specific function syntax
             TSDeclareFunction(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                reportMissing(context, sourceCode, node, node);
             },
-            // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-            // @req REQ-FUNCTION-DETECTION - Detect TS-specific function syntax
             TSMethodSignature(node) {
-                checkStoryAnnotation(sourceCode, context, node, scope, exportPriority);
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                const target = resolveTargetNode(sourceCode, node);
+                reportMissing(context, sourceCode, node, target);
+            },
+            MethodDefinition(node) {
+                if (!shouldProcessNode(node, scope, exportPriority))
+                    return;
+                reportMethod(context, sourceCode, node);
             },
         };
     },
 };
+exports.default = rule;

package/lib/src/utils/branch-annotation-helpers.d.ts

@@ -0,0 +1,46 @@
+import type { Rule } from "eslint";
+/**
+ * Valid branch types for require-branch-annotation rule.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-SIGNIFICANCE-CRITERIA - Define criteria for which branches require annotations
+ */
+export declare const DEFAULT_BRANCH_TYPES: readonly ["IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement"];
+/**
+ * Type for branch nodes supported by require-branch-annotation rule.
+ */
+export type BranchType = (typeof DEFAULT_BRANCH_TYPES)[number];
+/**
+ * Validate branchTypes configuration option and return branch types to enforce,
+ * or return an ESLint listener if configuration is invalid.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+ */
+export declare function validateBranchTypes(context: Rule.RuleContext): BranchType[] | Rule.RuleListener;
+/**
+ * Gather leading comment text for a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
+ */
+export declare function gatherBranchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;
+/**
+ * Report missing @story annotation on a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
+ */
+export declare function reportMissingStory(context: Rule.RuleContext, node: any, indent: string, insertPos: number, storyFixCountRef: {
+    count: number;
+}): void;
+/**
+ * Report missing @req annotation on a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
+ */
+export declare function reportMissingReq(context: Rule.RuleContext, node: any, indent: string, insertPos: number, missingStory: boolean): void;
+/**
+ * Report missing annotations on a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
+ */
+export declare function reportMissingAnnotations(context: Rule.RuleContext, node: any, storyFixCountRef: {
+    count: number;
+}): void;

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

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BRANCH_TYPES = void 0;
+exports.validateBranchTypes = validateBranchTypes;
+exports.gatherBranchCommentText = gatherBranchCommentText;
+exports.reportMissingStory = reportMissingStory;
+exports.reportMissingReq = reportMissingReq;
+exports.reportMissingAnnotations = reportMissingAnnotations;
+/**
+ * Valid branch types for require-branch-annotation rule.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-SIGNIFICANCE-CRITERIA - Define criteria for which branches require annotations
+ */
+exports.DEFAULT_BRANCH_TYPES = [
+    "IfStatement",
+    "SwitchCase",
+    "TryStatement",
+    "CatchClause",
+    "ForStatement",
+    "ForOfStatement",
+    "ForInStatement",
+    "WhileStatement",
+    "DoWhileStatement",
+];
+/**
+ * Validate branchTypes configuration option and return branch types to enforce,
+ * or return an ESLint listener if configuration is invalid.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+ */
+function validateBranchTypes(context) {
+    const options = context.options[0] || {};
+    if (Array.isArray(options.branchTypes)) {
+        const invalidTypes = options.branchTypes.filter((t) => !exports.DEFAULT_BRANCH_TYPES.includes(t));
+        if (invalidTypes.length > 0) {
+            return {
+                Program(node) {
+                    invalidTypes.forEach((t) => {
+                        context.report({
+                            node,
+                            message: `Value "${t}" should be equal to one of the allowed values: ${exports.DEFAULT_BRANCH_TYPES.join(", ")}`,
+                        });
+                    });
+                },
+            };
+        }
+    }
+    return Array.isArray(options.branchTypes)
+        ? options.branchTypes
+        : Array.from(exports.DEFAULT_BRANCH_TYPES);
+}
+/**
+ * Gather leading comment text for a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
+ */
+function gatherBranchCommentText(sourceCode, node) {
+    if (node.type === "SwitchCase") {
+        const lines = sourceCode.lines;
+        const startLine = node.loc.start.line;
+        let i = startLine - 2;
+        const comments = [];
+        while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
+            comments.unshift(lines[i].trim());
+            i--;
+        }
+        return comments.join(" ");
+    }
+    const comments = sourceCode.getCommentsBefore(node) || [];
+    return comments.map((c) => c.value).join(" ");
+}
+/**
+ * Report missing @story annotation on a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
+ */
+function reportMissingStory(context, node, indent, insertPos, storyFixCountRef) {
+    if (storyFixCountRef.count === 0) {
+        context.report({
+            node,
+            messageId: "missingAnnotation",
+            data: { missing: "@story" },
+            fix: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`),
+        });
+        storyFixCountRef.count++;
+    }
+    else {
+        context.report({
+            node,
+            messageId: "missingAnnotation",
+            data: { missing: "@story" },
+        });
+    }
+}
+/**
+ * Report missing @req annotation on a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
+ */
+function reportMissingReq(context, node, indent, insertPos, missingStory) {
+    if (!missingStory) {
+        context.report({
+            node,
+            messageId: "missingAnnotation",
+            data: { missing: "@req" },
+            fix: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`),
+        });
+    }
+    else {
+        context.report({
+            node,
+            messageId: "missingAnnotation",
+            data: { missing: "@req" },
+        });
+    }
+}
+/**
+ * Report missing annotations on a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
+ */
+function reportMissingAnnotations(context, node, storyFixCountRef) {
+    const sourceCode = context.getSourceCode();
+    const text = gatherBranchCommentText(sourceCode, node);
+    const missingStory = !/@story\b/.test(text);
+    const missingReq = !/@req\b/.test(text);
+    const indent = sourceCode.lines[node.loc.start.line - 1].match(/^(\s*)/)?.[1] || "";
+    const insertPos = sourceCode.getIndexFromLoc({
+        line: node.loc.start.line,
+        column: 0,
+    });
+    const actions = [
+        {
+            missing: missingStory,
+            fn: reportMissingStory,
+            args: [context, node, indent, insertPos, storyFixCountRef],
+        },
+        {
+            missing: missingReq,
+            fn: reportMissingReq,
+            args: [context, node, indent, insertPos, missingStory],
+        },
+    ];
+    actions.forEach(({ missing, fn, args }) => missing && fn(...args));
+}

package/lib/tests/integration/cli-integration.test.js

@@ -76,10 +76,8 @@ function baz() {}`,
         });
         return result;
     }
-    tests.forEach((testCase) => {
-        it(`[REQ-PLUGIN-STRUCTURE] ${testCase.name}`, () => {
-            const result = runEslint(testCase.code, testCase.rule);
-            expect(result.status).toBe(testCase.expectedStatus);
-        });
+    it.each(tests)("[REQ-PLUGIN-STRUCTURE] $name", ({ code, rule, expectedStatus }) => {
+        const result = runEslint(code, rule);
+        expect(result.status).toBe(expectedStatus);
     });
 });

package/lib/tests/maintenance/index.test.d.ts

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

package/lib/tests/maintenance/index.test.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Ensure all maintenance tools are exported correctly
+ */
+const maintenance_1 = require("../../src/maintenance");
+describe("Maintenance Tools Index Exports (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    it("[REQ-MAINT-DETECT] should export detectStaleAnnotations as a function", () => {
+        expect(typeof maintenance_1.detectStaleAnnotations).toBe("function");
+    });
+    it("[REQ-MAINT-UPDATE] should export updateAnnotationReferences as a function", () => {
+        expect(typeof maintenance_1.updateAnnotationReferences).toBe("function");
+    });
+    it("[REQ-MAINT-BATCH] should export batchUpdateAnnotations as a function", () => {
+        expect(typeof maintenance_1.batchUpdateAnnotations).toBe("function");
+    });
+    it("[REQ-MAINT-VERIFY] should export verifyAnnotations as a function", () => {
+        expect(typeof maintenance_1.verifyAnnotations).toBe("function");
+    });
+    it("[REQ-MAINT-REPORT] should export generateMaintenanceReport as a function", () => {
+        expect(typeof maintenance_1.generateMaintenanceReport).toBe("function");
+    });
+});

package/lib/tests/rules/error-reporting.test.d.ts

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

package/lib/tests/rules/error-reporting.test.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-SPECIFIC - Specific details about what annotation is missing or invalid
+ * @req REQ-ERROR-SUGGESTION - Suggest concrete steps to fix the issue
+ * @req REQ-ERROR-CONTEXT - Include relevant context in error messages
+ */
+const eslint_1 = require("eslint");
+const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
+const ruleTester = new eslint_1.RuleTester({
+    languageOptions: {
+        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+    },
+});
+describe("Error Reporting Enhancements for require-story-annotation (Story 007.0-DEV-ERROR-REPORTING)", () => {
+    ruleTester.run("require-story-annotation", require_story_annotation_1.default, {
+        valid: [
+            {
+                name: "[007.0-DEV-ERROR-REPORTING] valid with existing annotation",
+                code: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */ function foo() {}`,
+            },
+        ],
+        invalid: [
+            {
+                name: "[REQ-ERROR-SPECIFIC] missing @story annotation should report specific details and suggestion",
+                code: `function bar() {}`,
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        data: { name: "bar" },
+                        suggestions: [
+                            {
+                                desc: "Add JSDoc @story annotation for function 'bar', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                output: "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ],
+    });
+});

package/lib/tests/rules/require-story-annotation.test.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// @ts-nocheck
 /**
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -65,52 +66,100 @@ declare function tsDecl(): void;`,
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story annotation on function",
                 code: `function bar() {}`,
-                output: `/** @story <story-file>.story.md */\nfunction bar() {}`,
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'bar', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on function expression",
                 code: `const fnExpr = function() {};`,
-                output: `/** @story <story-file>.story.md */\nconst fnExpr = function() {};`,
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'fnExpr', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on arrow function",
                 code: `const arrowFn = () => {};`,
-                output: `/** @story <story-file>.story.md */\nconst arrowFn = () => {};`,
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'arrowFn', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst arrowFn = () => {};`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on class method",
                 code: `class C {\n  method() {}\n}`,
-                output: `class C {\n  /** @story <story-file>.story.md */\n  method() {}\n}`,
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `class C {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on TS declare function",
                 code: `declare function tsDecl(): void;`,
-                output: `/** @story <story-file>.story.md */
-declare function tsDecl(): void;`,
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2020, sourceType: "module" },
                 },
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'tsDecl', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on TS method signature",
-                code: `interface D {
-  method(): void;
-}`,
-                output: `/** @story <story-file>.story.md */
-interface D {
-  method(): void;
-}`,
+                code: `interface D {\n  method(): void;\n}`,
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2020, sourceType: "module" },
                 },
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ninterface D {\n  method(): void;\n}`,
+                            },
+                        ],
+                    },
+                ],
             },
         ],
     });
@@ -131,16 +180,34 @@ interface D {
             {
                 name: "[exportPriority] exported function missing @story annotation",
                 code: `export function exportedMissing() {}`,
-                output: `/** @story <story-file>.story.md */\nexport function exportedMissing() {}`,
                 options: [{ exportPriority: "exported" }],
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'exportedMissing', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nexport function exportedMissing() {}`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[exportPriority] exported arrow function missing @story annotation",
                 code: `export const arrowExported = () => {};`,
-                output: `/** @story <story-file>.story.md */\nexport const arrowExported = () => {};`,
                 options: [{ exportPriority: "exported" }],
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'arrowExported', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nexport const arrowExported = () => {};`,
+                            },
+                        ],
+                    },
+                ],
             },
         ],
     });
@@ -157,8 +224,17 @@ interface D {
                 name: "[scope] function declaration missing annotation when scope is FunctionDeclaration",
                 code: `function onlyDecl() {}`,
                 options: [{ scope: ["FunctionDeclaration"] }],
-                output: `/** @story <story-file>.story.md */\nfunction onlyDecl() {}`,
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'onlyDecl', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction onlyDecl() {}`,
+                            },
+                        ],
+                    },
+                ],
             },
         ],
     });

package/lib/tests/utils/branch-annotation-helpers.test.d.ts

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

package/lib/tests/utils/branch-annotation-helpers.test.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Unit tests for branch annotation helpers
+ * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+ */
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+describe("validateBranchTypes helper", () => {
+    let context;
+    beforeEach(() => {
+        context = { options: [], report: jest.fn() };
+    });
+    it("should return default branch types when no options provided", () => {
+        const result = (0, branch_annotation_helpers_1.validateBranchTypes)(context);
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toEqual(branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES);
+    });
+    it("should return custom branch types when valid options provided", () => {
+        context.options = [{ branchTypes: ["IfStatement", "ForStatement"] }];
+        const result = (0, branch_annotation_helpers_1.validateBranchTypes)(context);
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toEqual(["IfStatement", "ForStatement"]);
+    });
+    it("should return listener when invalid branch types provided and report errors", () => {
+        const invalid = ["UnknownType", "Foo"];
+        context.options = [{ branchTypes: invalid }];
+        // Invoke helper
+        const result = (0, branch_annotation_helpers_1.validateBranchTypes)(context);
+        // Should return a listener object
+        expect(typeof result).toBe("object");
+        expect(result).toHaveProperty("Program");
+        // Call the Program listener
+        const fakeNode = {};
+        result.Program(fakeNode);
+        // report should be called for each invalid type
+        expect(context.report).toHaveBeenCalledTimes(invalid.length);
+        invalid.forEach((t) => {
+            expect(context.report).toHaveBeenCalledWith(expect.objectContaining({
+                node: fakeNode,
+                message: expect.stringContaining(`Value "${t}" should be equal to one of the allowed values:`),
+            }));
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",