eslint-plugin-traceability 1.21.1 → 1.22.0

package/lib/src/rules/prefer-implements-annotation.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-format-internal");
+const prefer_implements_inline_1 = require("./helpers/prefer-implements-inline");
 // Maximum number of distinct @story paths allowed before treating as "multi-story".
 // @req REQ-MULTI-STORY-DETECT - Centralized threshold constant for detecting multi-story patterns
 const MULTI_STORY_THRESHOLD = 1;
@@ -223,173 +224,17 @@ function processBlockComment(comment, context) {
     });
 }
 /**
- * Extract the leading whitespace and `//` prefix from a line comment's full
- * source text so that new inline annotations can be inserted with matching
- * indentation and formatting.
- *
- * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
- * @req REQ-MIGRATE-INLINE
- */
-function getLinePrefixFromText(fullText) {
-    const match = fullText.match(/^(\s*\/\/\s*)/);
-    return match ? match[1] : "";
-}
-/**
- * Attempt to construct an inline auto-fix that replaces a contiguous
- * sequence of `@story` and `@req` line comments with a single `@supports`
- * annotation while preserving the original comment prefix.
- *
- * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
- * @req REQ-MIGRATE-INLINE
- */
-function tryBuildInlineAutoFix(context, comments, storyIndex, reqIndices) {
-    const sourceCode = context.getSourceCode();
-    const storyComment = comments[storyIndex];
-    const storyNormalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(storyComment.value || "");
-    if (!storyNormalized || !/^@story\b/.test(storyNormalized)) {
-        return null;
-    }
-    const storyParts = storyNormalized.split(/\s+/);
-    if (storyParts.length !== MIN_STORY_TOKENS) {
-        return null;
-    }
-    const storyPath = storyParts[1];
-    const reqIds = [];
-    for (const idx of reqIndices) {
-        const reqComment = comments[idx];
-        const reqNormalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(reqComment.value || "");
-        if (!reqNormalized || !/^@req\b/.test(reqNormalized)) {
-            return null;
-        }
-        const reqParts = reqNormalized.split(/\s+/);
-        if (reqParts.length !== MIN_REQ_TOKENS) {
-            return null;
-        }
-        reqIds.push(reqParts[1]);
-    }
-    if (!reqIds.length) {
-        return null;
-    }
-    const fullText = sourceCode.text.slice(storyComment.range[0], storyComment.range[1]);
-    const linePrefix = getLinePrefixFromText(fullText);
-    const implAnnotation = `@supports ${storyPath} ${reqIds.join(" ")}`;
-    const implLine = `${linePrefix}${implAnnotation}`;
-    const start = storyComment.range[0];
-    const end = comments[reqIndices[reqIndices.length - 1]].range[1];
-    return (fixer) => fixer.replaceTextRange([start, end], implLine);
-}
-/**
- * Coordinate detection and optional migration of a single inline `@story`
- * comment and its following `@req` comments, reporting diagnostics and
- * scheduling auto-fixes where safe.
+ * ESLint rule: prefer-implements-annotation
  *
- * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
- * @req REQ-MIGRATE-INLINE
- */
-function collectReqIndicesAfterStory(group, startIndex) {
-    const n = group.length;
-    const reqIndices = [];
-    let j = startIndex + 1;
-    while (j < n) {
-        const next = group[j];
-        const nextNormalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(next.value || "");
-        if (!nextNormalized || /^@supports\b/.test(nextNormalized)) {
-            break;
-        }
-        if (/^@req\b/.test(nextNormalized)) {
-            reqIndices.push(j);
-            j += 1;
-            continue;
-        }
-        break;
-    }
-    return { reqIndices, nextIndex: j };
-}
-function handleInlineStorySequence(context, group, startIndex) {
-    const current = group[startIndex];
-    const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
-    if (!normalized || !/^@story\b/.test(normalized)) {
-        return startIndex + 1;
-    }
-    if (/^@supports\b/.test(normalized)) {
-        return startIndex + 1;
-    }
-    const storyIndex = startIndex;
-    const { reqIndices, nextIndex } = collectReqIndicesAfterStory(group, startIndex);
-    if (reqIndices.length === 0) {
-        context.report({
-            node: current,
-            messageId: "preferImplements",
-        });
-        return startIndex + 1;
-    }
-    const fix = tryBuildInlineAutoFix(context, group, storyIndex, reqIndices);
-    if (fix) {
-        context.report({
-            node: current,
-            messageId: "preferImplements",
-            fix,
-        });
-    }
-    else {
-        context.report({
-            node: current,
-            messageId: "preferImplements",
-        });
-    }
-    return nextIndex;
-}
-/**
- * Process a contiguous group of inline line comments, identifying legacy
- * `@story`/`@req` sequences and scheduling the corresponding diagnostics
- * and potential auto-fixes for migration to `@supports`.
+ * Recommend migrating from legacy `@story` + `@req` annotations to the
+ * newer `@supports` format. This rule is **disabled by default** and
+ * is intended as an optional, opt-in migration aid.
  *
  * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
- * @req REQ-MIGRATE-INLINE
- */
-function advanceInlineGroupIndex(context, group, currentIndex) {
-    const current = group[currentIndex];
-    const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
-    if (!normalized || !/^@story\b/.test(normalized)) {
-        return currentIndex + 1;
-    }
-    return handleInlineStorySequence(context, group, currentIndex);
-}
-function processInlineGroup(context, group) {
-    if (group.length === 0)
-        return;
-    let i = 0;
-    while (i < group.length) {
-        i = advanceInlineGroupIndex(context, group, i);
-    }
-}
-/**
- * Scan sequences of Line comments for inline legacy @story/@req patterns and
- * report diagnostics and optional auto-fixes.
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
  */
-function processInlineComments(context, lineComments) {
-    if (!lineComments.length)
-        return;
-    // Group by contiguous line numbers
-    let group = [lineComments[0]];
-    const flushGroup = () => {
-        processInlineGroup(context, group);
-        group = [];
-    };
-    for (let idx = 1; idx < lineComments.length; idx++) {
-        const prev = lineComments[idx - 1];
-        const curr = lineComments[idx];
-        if (curr.loc.start.line === prev.loc.start.line + 1 &&
-            curr.loc.start.column === prev.loc.start.column) {
-            group.push(curr);
-        }
-        else {
-            flushGroup();
-            group.push(curr);
-        }
-    }
-    flushGroup();
-}
 /**
  * ESLint rule: prefer-implements-annotation
  *
@@ -472,7 +317,7 @@ const preferImplementsAnnotationRule = {
                     processBlockComment(comment, context);
                 });
                 const lineComments = comments.filter((comment) => comment.type === "Line");
-                processInlineComments(context, lineComments);
+                (0, prefer_implements_inline_1.processInlineComments)(context, lineComments);
             },
         };
     },

package/lib/src/rules/require-traceability.d.ts

@@ -2,6 +2,14 @@
  * Composite ESLint rule that enforces both story and requirement traceability
  * annotations on functions and methods.
  *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Require both @story and @req annotations via composition
+ * @req REQ-FUNCTION-DETECTION - Detect functions via composed rules
+ * @req REQ-CONFIGURABLE-SCOPE - Support scope configuration through underlying rules
+ * @req REQ-EXPORT-PRIORITY - Support export priority through underlying rules
+ * @req REQ-ERROR-LOCATION - Report errors at function locations via composed rules
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript syntax via composed rules
+ *
  * Implements Story 003.0-DEV-FUNCTION-ANNOTATIONS with:
  * - REQ-ANNOTATION-REQUIRED
  * - REQ-FUNCTION-DETECTION

package/lib/src/rules/require-traceability.js

@@ -3,6 +3,14 @@
  * Composite ESLint rule that enforces both story and requirement traceability
  * annotations on functions and methods.
  *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Require both @story and @req annotations via composition
+ * @req REQ-FUNCTION-DETECTION - Detect functions via composed rules
+ * @req REQ-CONFIGURABLE-SCOPE - Support scope configuration through underlying rules
+ * @req REQ-EXPORT-PRIORITY - Support export priority through underlying rules
+ * @req REQ-ERROR-LOCATION - Report errors at function locations via composed rules
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript syntax via composed rules
+ *
  * Implements Story 003.0-DEV-FUNCTION-ANNOTATIONS with:
  * - REQ-ANNOTATION-REQUIRED
  * - REQ-FUNCTION-DETECTION

package/lib/src/utils/annotation-checker.d.ts

@@ -1,15 +1,16 @@
 /**
  * Helper to check @req annotation presence on TS declare functions and method signatures.
+ *
  * This helper is intentionally scope/exportPriority agnostic and focuses solely
  * on detection and reporting of @req annotations for the given node.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
  * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
  * @param context - ESLint rule context used to obtain source and report problems
  * @param node - Function-like AST node whose surrounding comments should be inspected
- * @param options - Optional configuration controlling behaviour (e.g., enableFix)
- * @returns void
+ * @param options - Optional configuration controlling behaviour (e.g., enableFix, annotationPlacement)
  */
 export declare function checkReqAnnotation(context: any, node: any, options?: {
     enableFix?: boolean;

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

@@ -169,16 +169,17 @@ function reportMissing(context, node, enableFix = true) {
 }
 /**
  * Helper to check @req annotation presence on TS declare functions and method signatures.
+ *
  * This helper is intentionally scope/exportPriority agnostic and focuses solely
  * on detection and reporting of @req annotations for the given node.
+ *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
  * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
  * @param context - ESLint rule context used to obtain source and report problems
  * @param node - Function-like AST node whose surrounding comments should be inspected
- * @param options - Optional configuration controlling behaviour (e.g., enableFix)
- * @returns void
+ * @param options - Optional configuration controlling behaviour (e.g., enableFix, annotationPlacement)
  */
 function checkReqAnnotation(context, node, options) {
     const { enableFix = true } = options ?? {};

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

@@ -0,0 +1,22 @@
+import type { Rule } from "eslint";
+/**
+ * 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
+ */
+export declare function getInsideCatchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;
+/**
+ * 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
+ */
+export declare function getInsideTryBlockCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any): string;

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;