eslint-plugin-traceability 1.21.0 → 1.22.0

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

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInsideCatchCommentText = getInsideCatchCommentText;
+exports.getInsideTryBlockCommentText = getInsideTryBlockCommentText;
+const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
+const comment_text_helpers_1 = require("./comment-text-helpers");
+/**
+ * Gather comment text from inside a CatchClause body.
+ *
+ * Uses dual-position detection strategy: first attempts getCommentsInside API,
+ * then falls back to line-based scanning if API is unavailable or returns empty.
+ *
+ * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+ * @req REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @param sourceCode - ESLint source code object providing comment access APIs
+ * @param node - CatchClause AST node whose body will be scanned for comments
+ * @returns Concatenated comment text from inside the catch body, or empty string if none found
+ */
+function getInsideCatchCommentText(sourceCode, node) {
+    const getCommentsInside = sourceCode.getCommentsInside;
+    if (node.body && typeof getCommentsInside === "function") {
+        try {
+            const insideComments = getCommentsInside(node.body) || [];
+            const insideText = insideComments.map(comment_text_helpers_1.extractCommentValue).join(" ");
+            if (insideText) {
+                return insideText;
+            }
+        }
+        catch {
+            // fall through to line-based fallback
+        }
+    }
+    if (node.body && node.body.loc && node.body.loc.start && node.body.loc.end) {
+        const lines = sourceCode.lines;
+        const startIndex = node.body.loc.start.line - 1;
+        const endIndex = node.body.loc.end.line - 1;
+        const insideText = (0, branch_annotation_helpers_1.scanCommentLinesInRange)(lines, startIndex + 1, endIndex);
+        if (insideText) {
+            return insideText;
+        }
+    }
+    return "";
+}
+/**
+ * Gather comment text from the first contiguous comment lines inside a TryStatement block body.
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT
+ * @param sourceCode - ESLint source code object providing line access
+ * @param node - TryStatement AST node whose block will be scanned for comments
+ * @returns Concatenated comment text from inside the try block, or empty string if none found
+ */
+function getInsideTryBlockCommentText(sourceCode, node) {
+    const block = node && node.block;
+    if (!block ||
+        block.type !== "BlockStatement" ||
+        !block.loc ||
+        !block.loc.start ||
+        !block.loc.end ||
+        typeof block.loc.start.line !== "number" ||
+        typeof block.loc.end.line !== "number") {
+        return "";
+    }
+    const lines = sourceCode.lines;
+    const startIndex = block.loc.start.line - 1;
+    const endIndex = block.loc.end.line - 1;
+    const insideText = (0, branch_annotation_helpers_1.scanCommentLinesInRange)(lines, startIndex + 1, endIndex);
+    if (insideText) {
+        return insideText;
+    }
+    return "";
+}

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

@@ -12,6 +12,9 @@ const branch_annotation_loop_helpers_1 = require("./branch-annotation-loop-helpe
 const branch_annotation_if_helpers_1 = require("./branch-annotation-if-helpers");
 const branch_annotation_switch_helpers_1 = require("./branch-annotation-switch-helpers");
 const branch_annotation_story_fix_helpers_1 = require("./branch-annotation-story-fix-helpers");
+const branch_annotation_catch_helpers_1 = require("./branch-annotation-catch-helpers");
+const branch_validation_1 = require("./branch-validation");
+const comment_text_helpers_1 = require("./comment-text-helpers");
 /**
  * Valid branch types for require-branch-annotation rule.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -35,96 +38,7 @@ exports.DEFAULT_BRANCH_TYPES = [
  * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
  */
 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)) {
-        /**
-         * 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
-             */
-            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)
-        ? options.branchTypes
-        : Array.from(exports.DEFAULT_BRANCH_TYPES);
-}
-/**
- * Extract the raw 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 extractCommentValue(_c) {
-    return _c.value;
-}
-/**
- * Extract trimmed comment text for a given source line index or return null
- * when the line is blank or not a comment. This helper centralizes the
- * formatter-aware rules used by branch helpers when scanning for contiguous
- * comment lines around branches.
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
- * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
- * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
- */
-function getCommentTextAtLine(lines, index) {
-    const line = lines[index];
-    if (!line || !line.trim()) {
-        return null;
-    }
-    if (!/^\s*(\/\/|\/\*)/.test(line)) {
-        return null;
-    }
-    return line.trim();
-}
-/**
- * Collect a single contiguous comment line at the given index, appending its
- * trimmed text to the accumulator. Returns true when a valid comment was
- * collected and false when scanning should stop (blank or non-comment line).
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
- * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
- * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
- */
-function collectCommentLine(lines, index, comments) {
-    const commentText = getCommentTextAtLine(lines, index);
-    if (!commentText) {
-        return false;
-    }
-    comments.push(commentText);
-    return true;
+    return (0, branch_validation_1.validateBranchTypes)(context, exports.DEFAULT_BRANCH_TYPES);
 }
 /**
  * Scan contiguous formatter-aware comment lines between the provided 0-based
@@ -148,62 +62,13 @@ function scanCommentLinesInRange(lines, startIndex, endIndexInclusive) {
     const lastIndex = Math.min(endIndexInclusive, lines.length - 1);
     let i = startIndex;
     while (i <= lastIndex) {
-        if (!collectCommentLine(lines, i, comments)) {
+        if (!(0, comment_text_helpers_1.collectCommentLine)(lines, i, comments)) {
             break;
         }
         i++;
     }
     return comments.join(" ");
 }
-function getInsideCatchCommentText(sourceCode, node) {
-    const getCommentsInside = sourceCode.getCommentsInside;
-    if (node.body && typeof getCommentsInside === "function") {
-        try {
-            const insideComments = getCommentsInside(node.body) || [];
-            const insideText = insideComments.map(extractCommentValue).join(" ");
-            if (insideText) {
-                return insideText;
-            }
-        }
-        catch {
-            // fall through to line-based fallback
-        }
-    }
-    if (node.body && node.body.loc && node.body.loc.start && node.body.loc.end) {
-        const lines = sourceCode.lines;
-        const startIndex = node.body.loc.start.line - 1;
-        const endIndex = node.body.loc.end.line - 1;
-        const insideText = scanCommentLinesInRange(lines, startIndex + 1, endIndex);
-        if (insideText) {
-            return insideText;
-        }
-    }
-    return "";
-}
-/**
- * Gather comment text from the first contiguous comment lines inside a TryStatement block body.
- * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG
- */
-function getInsideTryBlockCommentText(sourceCode, node) {
-    const block = node && node.block;
-    if (!block ||
-        block.type !== "BlockStatement" ||
-        !block.loc ||
-        !block.loc.start ||
-        !block.loc.end ||
-        typeof block.loc.start.line !== "number" ||
-        typeof block.loc.end.line !== "number") {
-        return "";
-    }
-    const lines = sourceCode.lines;
-    const startIndex = block.loc.start.line - 1;
-    const endIndex = block.loc.end.line - 1;
-    const insideText = scanCommentLinesInRange(lines, startIndex + 1, endIndex);
-    if (insideText) {
-        return insideText;
-    }
-    return "";
-}
 /**
  * Gather annotation text for CatchClause nodes, supporting both before-catch and inside-catch positions.
  * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
@@ -212,7 +77,7 @@ function getInsideTryBlockCommentText(sourceCode, node) {
  */
 function gatherCatchClauseCommentText(sourceCode, node, annotationPlacement, beforeText) {
     if (annotationPlacement === "inside") {
-        const insideText = getInsideCatchCommentText(sourceCode, node);
+        const insideText = (0, branch_annotation_catch_helpers_1.getInsideCatchCommentText)(sourceCode, node);
         if (insideText) {
             return insideText;
         }
@@ -223,7 +88,7 @@ function gatherCatchClauseCommentText(sourceCode, node, annotationPlacement, bef
         /@supports\b/.test(beforeText)) {
         return beforeText;
     }
-    const insideText = getInsideCatchCommentText(sourceCode, node);
+    const insideText = (0, branch_annotation_catch_helpers_1.getInsideCatchCommentText)(sourceCode, node);
     if (insideText) {
         return insideText;
     }
@@ -235,54 +100,13 @@ function gatherCatchClauseCommentText(sourceCode, node, annotationPlacement, bef
  * leading comment text unchanged. When placement is "inside", it switches to inside-brace
  * semantics and scans for comments at the top of the consequent block.
  * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
- * @supports REQ-INSIDE-BRACE-PLACEMENT
- * @supports REQ-PLACEMENT-CONFIG
- * @supports REQ-DEFAULT-BACKWARD-COMPAT
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG REQ-DEFAULT-BACKWARD-COMPAT
  */
-function gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText) {
-    if (annotationPlacement === "before") {
-        return beforeText;
-    }
-    if (annotationPlacement !== "inside") {
-        return beforeText;
-    }
-    if (!node.consequent || node.consequent.type !== "BlockStatement") {
-        return "";
-    }
-    const consequent = node.consequent;
-    const getCommentsInside = sourceCode.getCommentsInside;
-    if (typeof getCommentsInside === "function") {
-        try {
-            const insideComments = getCommentsInside(consequent) || [];
-            const insideText = insideComments.map(extractCommentValue).join(" ");
-            if (insideText) {
-                return insideText;
-            }
-        }
-        catch {
-            // fall through to line-based fallback
-        }
-    }
-    if (consequent.loc &&
-        consequent.loc.start &&
-        consequent.loc.end &&
-        typeof consequent.loc.start.line === "number" &&
-        typeof consequent.loc.end.line === "number") {
-        const lines = sourceCode.lines;
-        const startIndex = consequent.loc.start.line - 1;
-        const endIndex = consequent.loc.end.line - 1;
-        const insideText = scanCommentLinesInRange(lines, startIndex + 1, endIndex);
-        if (insideText) {
-            return insideText;
-        }
-    }
-    return "";
-}
 function handleTryCatchBranch(sourceCode, node, context) {
     const { annotationPlacement, beforeText } = context;
     if (node.type === "TryStatement") {
         if (annotationPlacement === "inside") {
-            const insideText = getInsideTryBlockCommentText(sourceCode, node);
+            const insideText = (0, branch_annotation_catch_helpers_1.getInsideTryBlockCommentText)(sourceCode, node);
             if (insideText) {
                 return insideText;
             }
@@ -351,7 +175,7 @@ function gatherIfBranchCommentText(sourceCode, node, parent, context) {
             beforeText,
         });
     }
-    return gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText);
+    return (0, branch_annotation_if_helpers_1.gatherSimpleIfCommentText)(sourceCode, node, annotationPlacement, beforeText);
 }
 /**
  * Internal helper that performs type-based dispatch for gathering branch comment text.
@@ -387,7 +211,7 @@ function gatherBranchCommentTextByType(sourceCode, node, parent, context) {
  */
 function gatherBranchCommentText(sourceCode, node, parent, annotationPlacement = "before") {
     const beforeComments = sourceCode.getCommentsBefore(node) || [];
-    const beforeText = beforeComments.map(extractCommentValue).join(" ");
+    const beforeText = beforeComments.map(comment_text_helpers_1.extractCommentValue).join(" ");
     const handled = gatherBranchCommentTextByType(sourceCode, node, parent, {
         annotationPlacement,
         beforeText,

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

@@ -10,3 +10,4 @@ export declare function gatherElseIfCommentText(sourceCode: ReturnType<Rule.Rule
     annotationPlacement: AnnotationPlacement;
     beforeText: string;
 }): string;
+export declare function gatherSimpleIfCommentText(sourceCode: any, node: any, annotationPlacement: "before" | "inside", beforeText: string): string;

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

@@ -7,6 +7,7 @@ exports.scanElseIfBetweenConditionAndBody = scanElseIfBetweenConditionAndBody;
 exports.scanElseIfInsideBlockComments = scanElseIfInsideBlockComments;
 exports.getInsideElseIfCommentText = getInsideElseIfCommentText;
 exports.gatherElseIfCommentText = gatherElseIfCommentText;
+exports.gatherSimpleIfCommentText = gatherSimpleIfCommentText;
 const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
 /**
  * Small shared helpers for IfStatement/else-if specific annotation handling.
@@ -135,3 +136,61 @@ function gatherElseIfCommentText(sourceCode, node, parent, options) {
     }
     return beforeText;
 }
+/**
+ * Try to get comments from inside a node using getCommentsInside if available.
+ */
+function tryGetCommentsInsideNode(sourceCode, consequent) {
+    const getCommentsInside = sourceCode.getCommentsInside;
+    if (typeof getCommentsInside !== "function") {
+        return "";
+    }
+    try {
+        const insideComments = getCommentsInside(consequent) || [];
+        const extractCommentValue = (c) => c.value;
+        return insideComments.map(extractCommentValue).join(" ");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Scan for comments at the start of a block using line-based fallback.
+ */
+function scanBlockStartComments(sourceCode, consequent) {
+    if (!consequent.loc ||
+        !consequent.loc.start ||
+        !consequent.loc.end ||
+        typeof consequent.loc.start.line !== "number" ||
+        typeof consequent.loc.end.line !== "number") {
+        return "";
+    }
+    const lines = sourceCode.lines;
+    const startIndex = consequent.loc.start.line - 1;
+    const endIndex = consequent.loc.end.line - 1;
+    const comments = [];
+    const lastIndex = Math.min(endIndex, lines.length - 1);
+    let i = startIndex + 1;
+    while (i <= lastIndex) {
+        const line = lines[i];
+        if (!line || !line.trim() || !/^\s*(\/\/|\/\*)/.test(line)) {
+            break;
+        }
+        comments.push(line.trim());
+        i++;
+    }
+    return comments.join(" ");
+}
+function gatherSimpleIfCommentText(sourceCode, node, annotationPlacement, beforeText) {
+    if (annotationPlacement !== "inside") {
+        return beforeText;
+    }
+    if (!node.consequent || node.consequent.type !== "BlockStatement") {
+        return "";
+    }
+    const consequent = node.consequent;
+    const insideText = tryGetCommentsInsideNode(sourceCode, consequent);
+    if (insideText) {
+        return insideText;
+    }
+    return scanBlockStartComments(sourceCode, consequent);
+}

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

@@ -7,7 +7,7 @@ import type { AnnotationPlacement } from "./branch-annotation-helpers";
  * within ESLint's max-lines-per-function limits.
  *
  * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
- * @supports REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG REQ-INDENTATION-CORRECT
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT REQ-PLACEMENT-CONFIG REQ-INDENTATION-CORRECT
  */
 type SourceCode = ReturnType<Rule.RuleContext["getSourceCode"]>;
 type IndentHelperContext = {

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

@@ -3,9 +3,15 @@ import { type AnnotationPlacement } from "./branch-annotation-helpers";
 /**
  * Gather annotation text for SwitchCase branches, honoring the configured placement
  * while preserving legacy before-branch behavior in the default mode.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
- * @supports REQ-PLACEMENT-CONFIG
- * @supports REQ-INSIDE-BRACE-PLACEMENT
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT
+ * @param sourceCode - ESLint source code object for accessing line/comment data
+ * @param node - SwitchCase AST node to gather annotations from
+ * @param annotationPlacement - Placement mode ("inside" or "before")
+ * @param beforeText - Pre-gathered text from before the case statement
+ * @returns Combined annotation text based on placement mode and detected annotations
  */
 export declare function gatherSwitchCaseCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, annotationPlacement: AnnotationPlacement, beforeText: string): string;

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

@@ -6,8 +6,8 @@ const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
  * Gather comment text from the first contiguous comment lines "inside" a SwitchCase body.
  * Prefers a BlockStatement consequent when present, with a fallback to the entire case range.
  * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
- * @supports REQ-INSIDE-BRACE-PLACEMENT
- * @supports REQ-PLACEMENT-CONFIG
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 function getInsideSwitchCaseCommentText(sourceCode, node) {
     const lines = sourceCode.lines;
@@ -44,10 +44,16 @@ function getInsideSwitchCaseCommentText(sourceCode, node) {
 /**
  * Gather annotation text for SwitchCase branches, honoring the configured placement
  * while preserving legacy before-branch behavior in the default mode.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
- * @supports REQ-PLACEMENT-CONFIG
- * @supports REQ-INSIDE-BRACE-PLACEMENT
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-INSIDE-BRACE-PLACEMENT
+ * @param sourceCode - ESLint source code object for accessing line/comment data
+ * @param node - SwitchCase AST node to gather annotations from
+ * @param annotationPlacement - Placement mode ("inside" or "before")
+ * @param beforeText - Pre-gathered text from before the case statement
+ * @returns Combined annotation text based on placement mode and detected annotations
  */
 function gatherSwitchCaseCommentText(sourceCode, node, annotationPlacement, beforeText) {
     if (annotationPlacement === "inside") {

package/lib/src/utils/branch-validation.d.ts

@@ -0,0 +1,9 @@
+import type { Rule } from "eslint";
+import type { BranchType } from "./branch-annotation-helpers";
+/**
+ * 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, DEFAULT_BRANCH_TYPES: readonly BranchType[]): BranchType[] | Rule.RuleListener;

package/lib/src/utils/branch-validation.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateBranchTypes = validateBranchTypes;
+/**
+ * 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, DEFAULT_BRANCH_TYPES) {
+    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)) {
+        /**
+         * 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 !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
+             */
+            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: ${DEFAULT_BRANCH_TYPES.join(", ")}`,
+                    });
+                }
+                invalidTypes.forEach(reportInvalidType);
+            }
+            return { Program: ProgramHandler };
+        }
+    }
+    return Array.isArray(options.branchTypes)
+        ? options.branchTypes
+        : Array.from(DEFAULT_BRANCH_TYPES);
+}

package/lib/src/utils/comment-text-helpers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Low-level comment text extraction helpers for branch annotation processing.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-COMMENT-ASSOCIATION - Extract and normalize comment text from various comment node types
+ */
+/**
+ * Extract the raw 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
+ */
+export declare function extractCommentValue(_c: any): string;
+/**
+ * Extract trimmed comment text for a given source line index or return null
+ * when the line is blank or not a comment. This helper centralizes the
+ * formatter-aware rules used by branch helpers when scanning for contiguous
+ * comment lines around branches.
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
+ */
+export declare function getCommentTextAtLine(lines: string[], index: number): string | null;
+/**
+ * Collect a single contiguous comment line at the given index, appending its
+ * trimmed text to the accumulator. Returns true when a valid comment was
+ * collected and false when scanning should stop (blank or non-comment line).
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
+ */
+export declare function collectCommentLine(lines: string[], index: number, comments: string[]): boolean;

package/lib/src/utils/comment-text-helpers.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Low-level comment text extraction helpers for branch annotation processing.
+ *
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-COMMENT-ASSOCIATION - Extract and normalize comment text from various comment node types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractCommentValue = extractCommentValue;
+exports.getCommentTextAtLine = getCommentTextAtLine;
+exports.collectCommentLine = collectCommentLine;
+/**
+ * Extract the raw 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 extractCommentValue(_c) {
+    return _c.value;
+}
+/**
+ * Extract trimmed comment text for a given source line index or return null
+ * when the line is blank or not a comment. This helper centralizes the
+ * formatter-aware rules used by branch helpers when scanning for contiguous
+ * comment lines around branches.
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
+ */
+function getCommentTextAtLine(lines, index) {
+    const line = lines[index];
+    if (!line || !line.trim()) {
+        return null;
+    }
+    if (!/^\s*(\/\/|\/\*)/.test(line)) {
+        return null;
+    }
+    return line.trim();
+}
+/**
+ * Collect a single contiguous comment line at the given index, appending its
+ * trimmed text to the accumulator. Returns true when a valid comment was
+ * collected and false when scanning should stop (blank or non-comment line).
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-COMMENT-ASSOCIATION
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION REQ-FALLBACK-LOGIC
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF
+ */
+function collectCommentLine(lines, index, comments) {
+    const commentText = getCommentTextAtLine(lines, index);
+    if (!commentText) {
+        return false;
+    }
+    comments.push(commentText);
+    return true;
+}