eslint-plugin-traceability 1.13.1 → 1.14.1

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

@@ -175,6 +175,13 @@ function analyzeComment(comment) {
     });
     return { hasStory, hasReq, hasImplements, storyPaths };
 }
+/**
+ * Check whether a given set of story paths represents multiple story/req
+ * blocks within the same comment, which cannot be safely auto-migrated.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
+ * @req REQ-MIGRATE-INLINE
+ */
 function hasMultipleStories(storyPaths) {
     // @req REQ-MULTI-STORY-DETECT - Use named threshold constant instead of a magic number
     return storyPaths.size > MULTI_STORY_THRESHOLD;
@@ -186,7 +193,7 @@ function hasMultipleStories(storyPaths) {
  *
  * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-OPTIONAL-WARNING REQ-MULTI-STORY-DETECT REQ-AUTO-FIX REQ-VALID-OUTPUT
  */
-function processComment(comment, context) {
+function processBlockComment(comment, context) {
     const { hasStory, hasReq, hasImplements, storyPaths } = analyzeComment(comment);
     if (!hasStory || !hasReq) {
         return;
@@ -215,6 +222,169 @@ function processComment(comment, context) {
         fix: fix ?? undefined,
     });
 }
+/**
+ * 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.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
+ * @req REQ-MIGRATE-INLINE
+ */
+function handleInlineStorySequence(context, group, startIndex) {
+    const n = group.length;
+    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 = [];
+    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;
+    }
+    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 reqIndices[reqIndices.length - 1] + 1;
+}
+/**
+ * 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`.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
+ * @req REQ-MIGRATE-INLINE
+ */
+function processInlineGroup(context, group) {
+    if (group.length === 0)
+        return;
+    const n = group.length;
+    let i = 0;
+    while (i < n) {
+        const current = group[i];
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
+        if (!normalized || !/^@story\b/.test(normalized)) {
+            i += 1;
+            continue;
+        }
+        i = handleInlineStorySequence(context, group, i);
+    }
+}
+/**
+ * Scan sequences of Line comments for inline legacy @story/@req patterns and
+ * report diagnostics and optional auto-fixes.
+ */
+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
  *
@@ -292,11 +462,12 @@ const preferImplementsAnnotationRule = {
              */
             Program() {
                 const comments = sourceCode.getAllComments() || [];
-                comments
-                    .filter((comment) => comment.type === "Block")
-                    .forEach((comment) => {
-                    processComment(comment, context);
+                const blockComments = comments.filter((comment) => comment.type === "Block");
+                blockComments.forEach((comment) => {
+                    processBlockComment(comment, context);
                 });
+                const lineComments = comments.filter((comment) => comment.type === "Line");
+                processInlineComments(context, lineComments);
             },
         };
     },

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

@@ -1,6 +1,74 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const branch_annotation_helpers_1 = require("../utils/branch-annotation-helpers");
+/**
+ * @supports Switch case node detection for fall-through handling
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-SWITCH-CASE-ANNOTATION
+ * @req REQ-SWITCH-DEFAULT-REQUIRED
+ * @req REQ-SWITCH-FALLTHROUGH
+ */
+function isSwitchCaseNode(node) {
+    return (!!node && typeof node === "object" && node.type === "SwitchCase");
+}
+/**
+ * Sentinel index value used when a SwitchCase is not found in its parent's cases array.
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SWITCH-FALLTHROUGH
+ */
+const INVALID_INDEX = -1;
+/**
+ * Determine whether a SwitchCase is an intermediate fall-through label
+ * that should not require its own annotation.
+ *
+ * An intermediate fall-through case:
+ * - Has an empty consequent array
+ * - Has a following SwitchCase sibling in the same SwitchStatement
+ * - That following sibling has a non-empty consequent array
+ *
+ * @supports Switch fall-through behavior for branch annotations
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-SWITCH-CASE-ANNOTATION
+ * @req REQ-SWITCH-DEFAULT-REQUIRED
+ * @req REQ-SWITCH-FALLTHROUGH
+ */
+function isFallthroughIntermediateCase(node) {
+    if (!isSwitchCaseNode(node))
+        return false;
+    // Default cases must always be annotated when they represent a branch.
+    if (node.test == null) {
+        return false;
+    }
+    if (!Array.isArray(node.consequent) || node.consequent.length > 0) {
+        return false;
+    }
+    const parent = node.parent;
+    if (!parent ||
+        parent.type !== "SwitchStatement" ||
+        !Array.isArray(parent.cases)) {
+        return false;
+    }
+    const cases = parent.cases;
+    const index = cases.indexOf(node);
+    if (index === INVALID_INDEX) {
+        return false;
+    }
+    // Walk forward from this case until we either find a case with a non-empty
+    // consequent (shared body) or run out of cases. All empty cases in this
+    // prefix are treated as intermediate labels that participate in fall-through
+    // but do not themselves require annotations. The last case with the shared
+    // body remains subject to annotation requirements.
+    let j = index;
+    while (j < cases.length &&
+        (!Array.isArray(cases[j].consequent) || cases[j].consequent.length === 0)) {
+        j++;
+    }
+    if (j >= cases.length) {
+        // No later case with a body; treat this as an independent branch that
+        // should be annotated when appropriate.
+        return false;
+    }
+    return true;
+}
 /**
  * ESLint rule definition for require-branch-annotation.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -66,7 +134,11 @@ const rule = {
              * @req REQ-CONFIGURABLE-SCOPE
              */
             handlers[type] = function branchHandler(node) {
-                if (type === "SwitchCase" && node.test == null) {
+                if (type === "SwitchCase" &&
+                    isSwitchCaseNode(node) &&
+                    isFallthroughIntermediateCase(node)) {
+                    // Skip intermediate fall-through labels; only the last case before a shared code block
+                    // requires its own annotation per REQ-SWITCH-FALLTHROUGH.
                     return;
                 }
                 (0, branch_annotation_helpers_1.reportMissingAnnotations)(context, node, storyFixCountRef);

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

@@ -72,6 +72,14 @@ const rule = {
             missingReqPrefix: "Test name should start with requirement ID (e.g., '[REQ-MAINT-DETECT] ...').",
         },
     },
+    /**
+     * Wire up the ESLint rule visitors that enforce test traceability conventions
+     * for supported test frameworks.
+     *
+     * @story docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
+     * @req REQ-TEST-FILE-SUPPORTS REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX
+     * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PREFIX-FORMAT
+     */
     create(context) {
         const filename = context.getFilename();
         const rawOptions = (context.options && context.options[0]) || {};

package/lib/src/rules/valid-req-reference.js

@@ -31,6 +31,10 @@ exports.default = {
     /**
      * Rule create entrypoint that returns the Program visitor.
      * Delegates to createValidReqReferenceProgramVisitor helper.
+     *
+     * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+     * @req REQ-REQ-VALIDATION - Validate that requirement references in annotations resolve to known requirements
+     * @req REQ-REQ-FILE-EXISTS - Ensure that referenced story files exist before validating requirement references
      */
     create(context) {
         return {

package/lib/src/rules/valid-story-reference.d.ts

@@ -6,5 +6,14 @@
  * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
  */
 import type { Rule } from "eslint";
+/**
+ * ESLint rule factory: configures and returns visitors that validate story
+ * references in @story and @supports annotations across all comments.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-STORY-FILE-EXISTS - Ensure each referenced story in @story/@supports annotations points to an existing file
+ * @req REQ-STORY-CONTENT - Provide a foundation for deeper story content validation by guaranteeing valid references
+ */
 declare const _default: Rule.RuleModule;
 export default _default;

package/lib/src/rules/valid-story-reference.js

@@ -195,6 +195,15 @@ function handleComment(opts) {
         }
     }
 }
+/**
+ * ESLint rule factory: configures and returns visitors that validate story
+ * references in @story and @supports annotations across all comments.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+ * @req REQ-STORY-FILE-EXISTS - Ensure each referenced story in @story/@supports annotations points to an existing file
+ * @req REQ-STORY-CONTENT - Provide a foundation for deeper story content validation by guaranteeing valid references
+ */
 exports.default = {
     meta: {
         type: "problem",

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

@@ -1,4 +1,5 @@
 import type { Rule } from "eslint";
+import { reportMissingAnnotations } from "./branch-annotation-report-helpers";
 /**
  * Valid branch types for require-branch-annotation rule.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -16,6 +17,16 @@ export type BranchType = (typeof DEFAULT_BRANCH_TYPES)[number];
  * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
  */
 export declare function validateBranchTypes(context: Rule.RuleContext): BranchType[] | Rule.RuleListener;
+/**
+ * Scan contiguous formatter-aware comment lines between the provided 0-based
+ * start and end indices (inclusive), stopping when a non-comment or blank line
+ * is encountered. This helper is used as a line-based fallback when
+ * structured comment APIs are not available for branch bodies.
+ * @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-FALLBACK-LOGIC
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-FALLBACK-LOGIC-ELSE-IF
+ */
+export declare function scanCommentLinesInRange(lines: string[], startIndex: number, endIndexInclusive: number): string;
 /**
  * Gather leading comment text for a branch node.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -46,13 +57,4 @@ export declare function reportMissingReq(context: Rule.RuleContext, node: any, o
     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
- * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
- * @supports REQ-DUAL-POSITION-DETECTION
- */
-export declare function reportMissingAnnotations(context: Rule.RuleContext, node: any, storyFixCountRef: {
-    count: number;
-}): void;
+export { reportMissingAnnotations };

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

@@ -1,11 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_BRANCH_TYPES = void 0;
+exports.reportMissingAnnotations = exports.DEFAULT_BRANCH_TYPES = void 0;
 exports.validateBranchTypes = validateBranchTypes;
+exports.scanCommentLinesInRange = scanCommentLinesInRange;
 exports.gatherBranchCommentText = gatherBranchCommentText;
 exports.reportMissingStory = reportMissingStory;
 exports.reportMissingReq = reportMissingReq;
-exports.reportMissingAnnotations = reportMissingAnnotations;
+const branch_annotation_report_helpers_1 = require("./branch-annotation-report-helpers");
+Object.defineProperty(exports, "reportMissingAnnotations", { enumerable: true, get: function () { return branch_annotation_report_helpers_1.reportMissingAnnotations; } });
+const branch_annotation_loop_helpers_1 = require("./branch-annotation-loop-helpers");
 const PRE_COMMENT_OFFSET = 2; // number of lines above branch to inspect for comments
 /**
  * Valid branch types for require-branch-annotation rule.
@@ -150,6 +153,7 @@ function scanCommentLinesInRange(lines, startIndex, endIndexInclusive) {
     }
     return comments.join(" ");
 }
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function isElseIfBranch(node, parent) {
     return (node &&
         node.type === "IfStatement" &&
@@ -294,6 +298,18 @@ function gatherElseIfCommentText(sourceCode, node, parent, beforeText) {
     }
     return beforeText;
 }
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+function gatherSwitchCaseCommentText(sourceCode, node) {
+    const lines = sourceCode.lines;
+    const startLine = node.loc.start.line;
+    let i = startLine - PRE_COMMENT_OFFSET;
+    const comments = [];
+    while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
+        comments.unshift(lines[i].trim());
+        i--;
+    }
+    return comments.join(" ");
+}
 /**
  * Gather leading comment text for a branch node.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
@@ -308,17 +324,7 @@ function gatherBranchCommentText(sourceCode, node, parent) {
      * @req REQ-TRACEABILITY-SWITCHCASE-COMMENTS - Trace collection of preceding comments for SwitchCase
      */
     if (node.type === "SwitchCase") {
-        const lines = sourceCode.lines;
-        const startLine = node.loc.start.line;
-        let i = startLine - PRE_COMMENT_OFFSET;
-        const comments = [];
-        // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-        // @req REQ-TRACEABILITY-WHILE - Trace while loop that collects preceding comments for SwitchCase
-        while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
-            comments.unshift(lines[i].trim());
-            i--;
-        }
-        return comments.join(" ");
+        return gatherSwitchCaseCommentText(sourceCode, node);
     }
     const beforeComments = sourceCode.getCommentsBefore(node) || [];
     const beforeText = beforeComments.map(extractCommentValue).join(" ");
@@ -334,6 +340,18 @@ function gatherBranchCommentText(sourceCode, node, parent) {
     if (node.type === "IfStatement") {
         return gatherElseIfCommentText(sourceCode, node, parent, beforeText);
     }
+    /**
+     * Conditional branch for loop nodes that may include annotations either on the loop
+     * statement itself or at the top of the loop body, allowing flexible placement.
+     * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-LOOP-ANNOTATION REQ-LOOP-PLACEMENT-FLEXIBLE
+     */
+    if (node.type === "ForStatement" ||
+        node.type === "ForInStatement" ||
+        node.type === "ForOfStatement" ||
+        node.type === "WhileStatement" ||
+        node.type === "DoWhileStatement") {
+        return (0, branch_annotation_loop_helpers_1.gatherLoopCommentText)(sourceCode, node, beforeText);
+    }
     return beforeText;
 }
 /**
@@ -409,130 +427,3 @@ function reportMissingReq(context, node, options) {
         });
     }
 }
-/**
- * Compute the base indent and insert position for a branch node, including
- * special handling for CatchClause bodies.
- * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
- * @supports REQ-ANNOTATION-PARSING
- * @supports REQ-DUAL-POSITION-DETECTION
- */
-/**
- * Compute indentation and insert position for the start of a given 1-based line
- * number. This keeps indentation and fixer insert positions consistent across
- * branch helpers that need to align auto-inserted comments with existing
- * source formatting.
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-ANNOTATION-PARSING
- */
-function getIndentAndInsertPosForLine(sourceCode, line, fallbackIndent) {
-    const lines = sourceCode.lines;
-    let indent = fallbackIndent;
-    if (line >= 1 && line <= lines.length) {
-        const rawLine = lines[line - 1];
-        indent = rawLine.match(/^(\s*)/)?.[1] || fallbackIndent;
-    }
-    const insertPos = sourceCode.getIndexFromLoc({
-        line,
-        column: 0,
-    });
-    return { indent, insertPos };
-}
-function getBaseBranchIndentAndInsertPos(sourceCode, node) {
-    let { indent, insertPos } = getIndentAndInsertPosForLine(sourceCode, node.loc.start.line, "");
-    if (node.type === "CatchClause" && node.body) {
-        const bodyNode = node.body;
-        const bodyStatements = Array.isArray(bodyNode.body)
-            ? bodyNode.body
-            : undefined;
-        const firstStatement = bodyStatements && bodyStatements.length > 0
-            ? bodyStatements[0]
-            : undefined;
-        if (firstStatement && firstStatement.loc && firstStatement.loc.start) {
-            const firstLine = firstStatement.loc.start.line;
-            const firstLineInfo = getIndentAndInsertPosForLine(sourceCode, firstLine, "");
-            indent = firstLineInfo.indent;
-            insertPos = firstLineInfo.insertPos;
-        }
-        else if (bodyNode.loc && bodyNode.loc.start) {
-            const blockLine = bodyNode.loc.start.line;
-            const blockLineInfo = getIndentAndInsertPosForLine(sourceCode, blockLine, "");
-            const innerIndent = `${blockLineInfo.indent}  `;
-            indent = innerIndent;
-            insertPos = blockLineInfo.insertPos;
-        }
-    }
-    return { indent, insertPos };
-}
-/**
- * Compute annotation-related metadata for 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
- * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
- * @supports REQ-DUAL-POSITION-DETECTION
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
- */
-function getBranchAnnotationInfo(sourceCode, node, parent) {
-    const text = gatherBranchCommentText(sourceCode, node, parent);
-    const hasSupports = /@supports\b/.test(text);
-    const missingStory = !/@story\b/.test(text) && !hasSupports;
-    const missingReq = !/@req\b/.test(text) && !hasSupports;
-    let { indent, insertPos } = getBaseBranchIndentAndInsertPos(sourceCode, node);
-    if (isElseIfBranch(node, parent) &&
-        node.consequent &&
-        node.consequent.type === "BlockStatement" &&
-        node.consequent.loc &&
-        node.consequent.loc.start) {
-        // For else-if blocks, align auto-fix comments with Prettier's tendency to place comments
-        // inside the wrapped block body; non-block consequents intentionally keep the default behavior.
-        const commentLine = node.consequent.loc.start.line + 1;
-        const commentLineInfo = getIndentAndInsertPosForLine(sourceCode, commentLine, indent);
-        indent = commentLineInfo.indent;
-        insertPos = commentLineInfo.insertPos;
-    }
-    return { missingStory, missingReq, indent, insertPos };
-}
-/**
- * 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
- * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
- * @supports REQ-DUAL-POSITION-DETECTION
- */
-function reportMissingAnnotations(context, node, storyFixCountRef) {
-    const sourceCode = context.getSourceCode();
-    /**
-     * Determine the direct parent of the node using the parent reference on the node.
-     * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
-     * @supports REQ-DUAL-POSITION-DETECTION
-     */
-    const parent = node.parent;
-    const { missingStory, missingReq, indent, insertPos } = getBranchAnnotationInfo(sourceCode, node, parent);
-    const actions = [
-        {
-            missing: missingStory,
-            fn: reportMissingStory,
-            args: [context, node, { indent, insertPos, storyFixCountRef }],
-        },
-        {
-            missing: missingReq,
-            fn: reportMissingReq,
-            args: [context, node, { indent, insertPos, missingStory }],
-        },
-    ];
-    /**
-     * Process a single action from the actions array.
-     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-     * @req REQ-TRACEABILITY-ACTIONS-FOREACH - Trace processing of actions array to report missing annotations
-     */
-    function processAction(item) {
-        /**
-         * Callback invoked for each action to decide and execute reporting.
-         * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-         * @req REQ-TRACEABILITY-FOR-EACH-CALLBACK - Trace callback handling for each action item
-         */
-        if (item.missing) {
-            item.fn(...item.args);
-        }
-    }
-    actions.forEach(processAction);
-}

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

@@ -0,0 +1,9 @@
+import type { Rule } from "eslint";
+/**
+ * Gather annotation text for loop branches, supporting annotations either on the
+ * loop statement itself or on the first comment lines inside the loop body.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-LOOP-ANNOTATION
+ * @req REQ-LOOP-PLACEMENT-FLEXIBLE
+ */
+export declare function gatherLoopCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, beforeText: string): string;

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

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatherLoopCommentText = gatherLoopCommentText;
+const branch_annotation_helpers_1 = require("./branch-annotation-helpers");
+/**
+ * Gather annotation text for loop branches, supporting annotations either on the
+ * loop statement itself or on the first comment lines inside the loop body.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-LOOP-ANNOTATION
+ * @req REQ-LOOP-PLACEMENT-FLEXIBLE
+ */
+function gatherLoopCommentText(sourceCode, node, beforeText) {
+    if (/@story\b/.test(beforeText) ||
+        /@req\b/.test(beforeText) ||
+        /@supports\b/.test(beforeText)) {
+        return beforeText;
+    }
+    const body = node.body;
+    if (body &&
+        body.type === "BlockStatement" &&
+        body.loc &&
+        body.loc.start &&
+        body.loc.end) {
+        const lines = sourceCode.lines;
+        const startIndex = body.loc.start.line; // first line inside block body (start.line is 1-based)
+        const endIndex = body.loc.end.line - 1;
+        const insideText = (0, branch_annotation_helpers_1.scanCommentLinesInRange)(lines, startIndex, endIndex);
+        if (insideText &&
+            (/@story\b/.test(insideText) ||
+                /@req\b/.test(insideText) ||
+                /@supports\b/.test(insideText))) {
+            return insideText;
+        }
+    }
+    return beforeText;
+}

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

@@ -0,0 +1,11 @@
+import type { Rule } from "eslint";
+/**
+ * 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
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports REQ-DUAL-POSITION-DETECTION
+ */
+export declare function reportMissingAnnotations(context: Rule.RuleContext, node: any, storyFixCountRef: {
+    count: number;
+}): void;