eslint-plugin-traceability 1.11.4 → 1.12.1

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.11.4](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.11.3...v1.11.4) (2025-12-06)
+## [1.12.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.12.0...v1.12.1) (2025-12-07)
 
 
 ### Bug Fixes
 
-* add else-if branch annotation support and tests ([15652db](https://github.com/voder-ai/eslint-plugin-traceability/commit/15652db094d23a261a39acaab76de585f460fda3))
+* support single-line else-if annotations and enable Prettier tests ([967b7e0](https://github.com/voder-ai/eslint-plugin-traceability/commit/967b7e02e12c4415efa0df2772ccde77b94cd1a8))
 
 # Changelog
 

package/lib/src/rules/helpers/require-story-core.js

@@ -98,6 +98,46 @@ exports.STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
  * Allowed values for export priority option.
  */
 exports.EXPORT_PRIORITY_VALUES = ["all", "exported", "non-exported"];
+/**
+ * Safely execute a reporting operation, swallowing unexpected errors so that
+ * traceability rules never break ESLint runs. When TRACEABILITY_DEBUG=1 is
+ * set in the environment, a diagnostic message is logged to stderr.
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-RESILIENCE
+ */
+function withSafeReporting(label, fn) {
+    try {
+        fn();
+    }
+    catch (error) {
+        if (process.env.TRACEABILITY_DEBUG === "1") {
+            // Debug logging only when explicitly enabled for troubleshooting helper failures.
+            console.error(`[traceability] ${label} failed`, error?.message ?? error);
+        }
+    }
+}
+/**
+ * Build the shared ESLint report descriptor for a missing @story annotation.
+ * This keeps the core helpers focused on computing names, targets, and
+ * templates while centralizing the diagnostic wiring.
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ERROR-SPECIFIC
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-RESILIENCE
+ */
+function createMissingStoryReportDescriptor(config) {
+    const { nameNode, name, resolvedTarget, effectiveTemplate, allowFix, createFix, } = config;
+    const baseFix = createFix(resolvedTarget, effectiveTemplate);
+    return {
+        node: nameNode,
+        messageId: "missingStory",
+        data: { name, functionName: name },
+        fix: allowFix ? baseFix : undefined,
+        suggest: [
+            {
+                desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
+                fix: baseFix,
+            },
+        ],
+    };
+}
 /**
  * Core helper to report a missing @story annotation for a function-like node.
  * This reporting utility delegates behavior to injected dependencies so that
@@ -111,7 +151,7 @@ exports.EXPORT_PRIORITY_VALUES = ["all", "exported", "non-exported"];
  */
 function coreReportMissing(deps, context, sourceCode, config) {
     const { node, target: passedTarget, options = {} } = config;
-    try {
+    withSafeReporting("coreReportMissing", () => {
         if (deps.hasStoryAnnotation(sourceCode, node)) {
             return;
         }
@@ -120,30 +160,15 @@ function coreReportMissing(deps, context, sourceCode, config) {
         const nameNode = deps.getNameNodeForReport(node);
         const { effectiveTemplate, allowFix } = deps.buildTemplateConfig(options);
         const name = functionName;
-        context.report({
-            node: nameNode,
-            messageId: "missingStory",
-            data: { name, functionName: name },
-            fix: allowFix
-                ? deps.createAddStoryFix(resolvedTarget, effectiveTemplate)
-                : undefined,
-            suggest: [
-                {
-                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
-                    fix: deps.createAddStoryFix(resolvedTarget, effectiveTemplate),
-                },
-            ],
-        });
-    }
-    catch (error) {
-        // Intentionally swallow unexpected helper errors so traceability checks never
-        // break lint runs. When TRACEABILITY_DEBUG=1 is set, log a debug message to
-        // help diagnose misbehaving helpers in local development without affecting
-        // normal CI or production usage.
-        if (process.env.TRACEABILITY_DEBUG === "1") {
-            console.error("[traceability] coreReportMissing failed for node", error?.message ?? error);
-        }
-    }
+        context.report(createMissingStoryReportDescriptor({
+            nameNode,
+            name,
+            resolvedTarget,
+            effectiveTemplate,
+            allowFix,
+            createFix: deps.createAddStoryFix,
+        }));
+    });
 }
 /**
  * Core helper to report a missing @story annotation for a method-like node.
@@ -158,37 +183,21 @@ function coreReportMissing(deps, context, sourceCode, config) {
  */
 function coreReportMethod(deps, context, sourceCode, config) {
     const { node, target: passedTarget, options = {} } = config;
-    try {
+    withSafeReporting("coreReportMethod", () => {
         if (deps.hasStoryAnnotation(sourceCode, node)) {
             return;
         }
         const resolvedTarget = passedTarget ?? deps.resolveAnnotationTargetNode(sourceCode, node, null);
         const name = deps.extractName(node);
         const nameNode = (node.key && node.key.type === "Identifier" && node.key) || node;
-        const effectiveTemplate = deps.getAnnotationTemplate(options.annotationTemplateOverride);
-        const allowFix = deps.shouldApplyAutoFix(options.autoFixToggle);
-        context.report({
-            node: nameNode,
-            messageId: "missingStory",
-            data: { name, functionName: name },
-            fix: allowFix
-                ? deps.createMethodFix(resolvedTarget, effectiveTemplate)
-                : undefined,
-            suggest: [
-                {
-                    desc: `Add JSDoc @story annotation for function '${name}', e.g., ${effectiveTemplate}`,
-                    fix: deps.createMethodFix(resolvedTarget, effectiveTemplate),
-                },
-            ],
-        });
-    }
-    catch (error) {
-        // Intentionally swallow unexpected helper errors so traceability checks never
-        // break lint runs. When TRACEABILITY_DEBUG=1 is set, log a debug message to
-        // help diagnose misbehaving helpers in local development without affecting
-        // normal CI or production usage.
-        if (process.env.TRACEABILITY_DEBUG === "1") {
-            console.error("[traceability] coreReportMethod failed for node", error?.message ?? error);
-        }
-    }
+        const { effectiveTemplate, allowFix } = deps.buildTemplateConfig(options);
+        context.report(createMissingStoryReportDescriptor({
+            nameNode,
+            name,
+            resolvedTarget,
+            effectiveTemplate,
+            allowFix,
+            createFix: deps.createMethodFix,
+        }));
+    });
 }

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

@@ -86,6 +86,70 @@ function validateBranchTypes(context) {
 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;
+}
+/**
+ * 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
+ */
+function scanCommentLinesInRange(lines, startIndex, endIndexInclusive) {
+    if (!Array.isArray(lines) || lines.length === 0) {
+        return "";
+    }
+    if (startIndex < 0 ||
+        startIndex >= lines.length ||
+        startIndex > endIndexInclusive) {
+        return "";
+    }
+    const comments = [];
+    const lastIndex = Math.min(endIndexInclusive, lines.length - 1);
+    let i = startIndex;
+    while (i <= lastIndex) {
+        if (!collectCommentLine(lines, i, comments)) {
+            break;
+        }
+        i++;
+    }
+    return comments.join(" ");
+}
 function isElseIfBranch(node, parent) {
     return (node &&
         node.type === "IfStatement" &&
@@ -120,65 +184,115 @@ function gatherCatchClauseCommentText(sourceCode, node, beforeText) {
         const lines = sourceCode.lines;
         const startIndex = node.body.loc.start.line - 1;
         const endIndex = node.body.loc.end.line - 1;
-        const comments = [];
-        let i = startIndex + 1;
-        while (i <= endIndex) {
-            const line = lines[i];
-            if (!line || !line.trim()) {
-                break;
-            }
-            if (!/^\s*(\/\/|\/\*)/.test(line)) {
-                break;
-            }
-            comments.push(line.trim());
-            i++;
-        }
-        const insideText = comments.join(" ");
+        const insideText = scanCommentLinesInRange(lines, startIndex + 1, endIndex);
         if (insideText) {
             return insideText;
         }
     }
     return beforeText;
 }
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+function scanElseIfPrecedingComments(sourceCode, node) {
+    const lines = sourceCode.lines;
+    if (!node.loc || !node.loc.start || typeof node.loc.start.line !== "number") {
+        return "";
+    }
+    const startLine = node.loc.start.line - 1;
+    const comments = [];
+    let i = startLine - 1;
+    let scanned = 0;
+    while (i >= 0 && scanned < PRE_COMMENT_OFFSET) {
+        const commentText = getCommentTextAtLine(lines, i);
+        if (!commentText) {
+            break;
+        }
+        comments.unshift(commentText);
+        i--;
+        scanned++;
+    }
+    return comments.join(" ");
+}
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+function hasValidElseIfBlockLoc(node) {
+    const hasBlockConsequent = node.consequent &&
+        node.consequent.type === "BlockStatement" &&
+        node.consequent.loc &&
+        node.consequent.loc.start;
+    return !!(node.test &&
+        node.test.loc &&
+        node.test.loc.end &&
+        hasBlockConsequent);
+}
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+function scanElseIfBetweenConditionAndBody(sourceCode, node) {
+    const lines = sourceCode.lines;
+    const conditionEndLine = node.test.loc.end.line;
+    const consequentStartLine = node.consequent.loc.start.line;
+    // Lines in sourceCode are 0-based indexes, but loc.line values are 1-based.
+    // We want to scan comments strictly between the condition and the
+    // consequent body, so we start at the line after the condition's end and
+    // stop at the line immediately before the consequent's starting line.
+    const startIndex = conditionEndLine; // already the next logical line index when 0-based
+    const endIndexExclusive = consequentStartLine - 1;
+    if (endIndexExclusive <= startIndex) {
+        return "";
+    }
+    return scanCommentLinesInRange(lines, startIndex, endIndexExclusive - 1);
+}
+/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
+function scanElseIfInsideBlockComments(sourceCode, node) {
+    const lines = sourceCode.lines;
+    const consequentStartLine = node.consequent.loc.start.line;
+    const comments = [];
+    // Intentionally start from the block's start line (using the same 1-based line value as provided by the parser)
+    // so that, when indexing into sourceCode.lines, this corresponds to the first logical line inside the block body
+    // for typical formatter layouts.
+    let lineIndex = consequentStartLine;
+    while (lineIndex < lines.length) {
+        if (!collectCommentLine(lines, lineIndex, comments)) {
+            break;
+        }
+        lineIndex++;
+    }
+    return comments.join(" ");
+}
 /**
  * Gather annotation text for IfStatement else-if branches, supporting comments placed
- * between the else-if condition and the consequent statement body.
+ * before the else keyword, between the else-if condition and the consequent body,
+ * and in the first comment-only lines inside the consequent block body.
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
  * @supports REQ-FALLBACK-LOGIC
  */
 function gatherElseIfCommentText(sourceCode, node, parent, beforeText) {
-    if (/@story\b/.test(beforeText) || /@req\b/.test(beforeText)) {
+    if (beforeText &&
+        (/@story\b/.test(beforeText) ||
+            /@req\b/.test(beforeText) ||
+            /@supports\b/.test(beforeText))) {
         return beforeText;
     }
     if (!isElseIfBranch(node, parent)) {
         return beforeText;
     }
-    if (!node.consequent ||
-        node.consequent.type !== "BlockStatement" ||
-        !node.consequent.loc ||
-        !node.consequent.loc.start) {
-        return beforeText;
+    const beforeElseText = scanElseIfPrecedingComments(sourceCode, node);
+    if (beforeElseText &&
+        (/@story\b/.test(beforeElseText) ||
+            /@req\b/.test(beforeElseText) ||
+            /@supports\b/.test(beforeElseText))) {
+        return beforeElseText;
     }
-    if (!node.test || !node.test.loc || !node.test.loc.end) {
+    if (!hasValidElseIfBlockLoc(node)) {
         return beforeText;
     }
-    const lines = sourceCode.lines;
-    const conditionEndLine = node.test.loc.end.line;
-    const consequentStartLine = node.consequent.loc.start.line;
-    const comments = [];
-    for (let lineIndex = conditionEndLine; lineIndex < consequentStartLine; lineIndex++) {
-        const line = lines[lineIndex];
-        if (!line || !line.trim()) {
-            break;
-        }
-        if (!/^\s*(\/\/|\/\*)/.test(line)) {
-            break;
-        }
-        comments.push(line.trim());
+    const betweenText = scanElseIfBetweenConditionAndBody(sourceCode, node);
+    if (betweenText) {
+        return betweenText;
+    }
+    const insideText = scanElseIfInsideBlockComments(sourceCode, node);
+    if (insideText) {
+        return insideText;
     }
-    const betweenText = comments.join(" ");
-    return betweenText || beforeText;
+    return beforeText;
 }
 /**
  * Gather leading comment text for a branch node.
@@ -345,11 +459,13 @@ function getBaseBranchIndentAndInsertPos(sourceCode, node) {
  * @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 missingStory = !/@story\b/.test(text);
-    const missingReq = !/@req\b/.test(text);
+    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 &&
@@ -378,13 +494,11 @@ function getBranchAnnotationInfo(sourceCode, node, parent) {
 function reportMissingAnnotations(context, node, storyFixCountRef) {
     const sourceCode = context.getSourceCode();
     /**
-     * Determine the direct parent of the node using the ancestors stack when available.
+     * 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 contextAny = context;
-    const ancestors = contextAny.getAncestors?.() || [];
-    const parent = ancestors.length > 0 ? ancestors[ancestors.length - 1] : undefined;
+    const parent = node.parent;
     const { missingStory, missingReq, indent, insertPos } = getBranchAnnotationInfo(sourceCode, node, parent);
     const actions = [
         {

package/lib/tests/integration/dogfooding-validation.test.js

@@ -35,10 +35,12 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Dogfooding validation integration tests
- * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-TEST REQ-DOGFOODING-CI
+ * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-TEST REQ-DOGFOODING-CI REQ-DOGFOODING-VERIFY REQ-DOGFOODING-PRESET
  */
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
+const index_1 = __importStar(require("../../src/index"));
 /**
  * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-TEST
  */
@@ -91,4 +93,34 @@ describe("Dogfooding Validation (Story 023.0-MAINT-DOGFOODING-VALIDATION)", () =
         expect(result.stdout).toContain("error");
         expect(result.stdout).toContain("src/dogfood.ts");
     });
+    it("[REQ-DOGFOODING-VERIFY] should report at least one traceability rule active for TS sources", () => {
+        /**
+         * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-VERIFY
+         */
+        const eslintConfig = require("../../eslint.config.js");
+        const tsConfig = getTsConfigFromEslintConfig(eslintConfig);
+        expect(tsConfig).toBeDefined();
+        const rules = tsConfig.rules || {};
+        const hasTraceabilityRule = Object.keys(rules).some((key) => key.startsWith("traceability/"));
+        expect(hasTraceabilityRule).toBe(true);
+    });
+    it("[REQ-DOGFOODING-PRESET] should be compatible with recommended preset usage without throwing", async () => {
+        /**
+         * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-PRESET
+         */
+        const config = [
+            { plugins: { traceability: index_1.default }, rules: {} },
+            ...index_1.configs.recommended,
+        ];
+        const eslint = new use_at_your_own_risk_1.FlatESLint({
+            overrideConfig: config,
+            overrideConfigFile: true,
+            ignore: false,
+        });
+        const results = await eslint.lintText("function foo() {}", {
+            filePath: "example.ts",
+        });
+        expect(results.length).toBeGreaterThanOrEqual(1);
+        expect(Array.isArray(results[0].messages)).toBe(true);
+    });
 });

package/lib/tests/integration/else-if-annotation-prettier.integration.test.js

@@ -50,9 +50,8 @@ describe("Else-if annotations with Prettier (Story 026.0-DEV-ELSE-IF-ANNOTATION-
         }
         return result.stdout;
     }
-    if (process.env.TRACEABILITY_EXPERIMENTAL_ELSE_IF === "1") {
-        it("[REQ-PRETTIER-COMPATIBILITY-ELSE-IF-BEFORE] accepts code where annotations start before else-if but are moved between condition and body by Prettier", () => {
-            const original = `
+    it("[REQ-PRETTIER-COMPATIBILITY-ELSE-IF-BEFORE] accepts code where annotations start before else-if but are moved between condition and body by Prettier", () => {
+        const original = `
 function doA() {
   return 1;
 }
@@ -72,15 +71,16 @@ else if (anotherVeryLongConditionThatForcesWrapping && someOtherCondition) {
   doB();
 }
 `;
-            const formatted = formatWithPrettier(original);
-            // Sanity check: Prettier should keep both the else-if branch and the associated story annotation.
-            expect(formatted).toContain("else if (");
-            expect(formatted).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
-            const result = runEslintWithRequireBranchAnnotation(formatted);
-            expect(result.status).toBe(0);
-        });
-        it("[REQ-PRETTIER-COMPATIBILITY-ELSE-IF-INSIDE] accepts code where annotations start between condition and body and are preserved by Prettier", () => {
-            const original = `
+        const formatted = formatWithPrettier(original);
+        // Sanity checks: Prettier should keep both the else-if branch and the associated story annotation,
+        // but the exact layout and comment movement may vary between versions.
+        expect(formatted).toContain("else if");
+        expect(formatted).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
+        const result = runEslintWithRequireBranchAnnotation(formatted);
+        expect(result.status).toBe(0);
+    });
+    it("[REQ-PRETTIER-COMPATIBILITY-ELSE-IF-INSIDE] accepts code where annotations start between condition and body and are preserved by Prettier", () => {
+        const original = `
 function doA() {
   return 1;
 }
@@ -101,16 +101,10 @@ if (aVeryLongConditionThatForcesPrettierToWrapTheElseIfBranch && anotherConditio
   doB();
 }
 `;
-            const formatted = formatWithPrettier(original);
-            // Note: Prettier's exact layout of the else-if and its comments may differ between versions;
-            // the rule should accept any of the supported annotation positions regardless of formatting.
-            const result = runEslintWithRequireBranchAnnotation(formatted);
-            expect(result.status).toBe(0);
-        });
-    }
-    else {
-        it.skip("Else-if Prettier integration tests are pending full else-if formatter support (set TRACEABILITY_EXPERIMENTAL_ELSE_IF=1 to enable)", () => {
-            // Pending full else-if formatter support.
-        });
-    }
+        const formatted = formatWithPrettier(original);
+        // Note: Prettier's exact layout of the else-if and its comments may differ between versions;
+        // the rule should accept any of the supported annotation positions regardless of formatting.
+        const result = runEslintWithRequireBranchAnnotation(formatted);
+        expect(result.status).toBe(0);
+    });
 });

package/lib/tests/rules/auto-fix-behavior-008.test.js

@@ -8,7 +8,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-AUTOFIX-MISSING - Verify ESLint --fix automatically adds missing @story annotations to functions
  * @req REQ-AUTOFIX-FORMAT - Verify ESLint --fix corrects simple annotation format issues for @story annotations
- * @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-MISSING REQ-AUTOFIX-FORMAT
+ * @req REQ-AUTOFIX-IDEMPOTENT - Verify ESLint --fix is idempotent and produces no changes on subsequent runs
+ * @req REQ-AUTOFIX-SINGLE-APPLICATION - Verify ESLint --fix does not apply the same fix multiple times or create duplicate annotations
+ * @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-MISSING REQ-AUTOFIX-FORMAT REQ-AUTOFIX-IDEMPOTENT REQ-AUTOFIX-SINGLE-APPLICATION
  */
 const eslint_1 = require("eslint");
 const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
@@ -196,4 +198,88 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
             ],
         });
     });
+    describe("[REQ-AUTOFIX-IDEMPOTENT] and [REQ-AUTOFIX-SINGLE-APPLICATION] require-story-annotation", () => {
+        functionRuleTester.run("require-story-annotation --fix idempotent behavior", require_story_annotation_1.default, {
+            valid: [
+                {
+                    name: "[REQ-AUTOFIX-IDEMPOTENT] second run on already fixed function produces no changes",
+                    code: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction fixedOnce() {}`,
+                },
+                {
+                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] already annotated code does not receive duplicate annotations",
+                    code: `class E {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                },
+            ],
+            invalid: [
+                {
+                    name: "[REQ-AUTOFIX-IDEMPOTENT] first run adds annotation; subsequent run is a no-op for function declarations",
+                    code: `function needsFixOnce() {}`,
+                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction needsFixOnce() {}`,
+                    errors: [
+                        {
+                            messageId: "missingStory",
+                            suggestions: [
+                                {
+                                    desc: "Add JSDoc @story annotation for function 'needsFixOnce', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction needsFixOnce() {}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] does not duplicate annotations for class methods on subsequent runs",
+                    code: `class F {\n  method() {}\n}`,
+                    output: `class F {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                    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 F {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+    describe("[REQ-AUTOFIX-IDEMPOTENT] and [REQ-AUTOFIX-SINGLE-APPLICATION] valid-annotation-format", () => {
+        formatRuleTester.run("valid-annotation-format --fix idempotent behavior", valid_annotation_format_1.default, {
+            valid: [
+                {
+                    name: "[REQ-AUTOFIX-IDEMPOTENT] second run after suffix normalization produces no changes",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                },
+                {
+                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] already-correct suffix is not altered or extended again",
+                    code: `// @story docs/stories/005.0-DEV-EXAMPLE.story.md`,
+                },
+            ],
+            invalid: [
+                {
+                    name: "[REQ-AUTOFIX-IDEMPOTENT] adds .story.md once; subsequent run sees no further change",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION`,
+                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                    errors: [
+                        {
+                            messageId: "invalidStoryFormat",
+                        },
+                    ],
+                },
+                {
+                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] converts .story to .story.md only once and does not double-append",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
+                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                    errors: [
+                        {
+                            messageId: "invalidStoryFormat",
+                        },
+                    ],
+                },
+            ],
+        });
+    });
 });

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

@@ -13,7 +13,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-ERROR-CONSISTENCY - Branch-level missing-annotation error messages follow shared conventions
  * @req REQ-ERROR-SUGGESTION - Branch-level missing-annotation errors include suggestions when applicable
  * @req REQ-NESTED-HANDLING - Nested branch annotations are correctly enforced without duplicative reporting
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION REQ-NESTED-HANDLING
+ * @req REQ-SUPPORTS-ALTERNATIVE - Branches annotated only with @supports are treated as fully annotated
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION REQ-NESTED-HANDLING REQ-SUPPORTS-ALTERNATIVE
  * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SPECIFIC REQ-ERROR-CONSISTENCY REQ-ERROR-SUGGESTION
  * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF REQ-POSITION-PRIORITY-ELSE-IF REQ-PRETTIER-AUTOFIX-ELSE-IF
  */
@@ -158,6 +159,34 @@ if (outer) {
 if (condition) {}`,
                 options: [{ branchTypes: ["IfStatement", "SwitchCase"] }],
             },
+            {
+                name: "[REQ-SUPPORTS-ALTERNATIVE] if-statement with only @supports annotation is treated as fully annotated",
+                code: `// @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+if (shouldHandleAlternative) {
+  handleAlternative();
+}`,
+            },
+            {
+                name: "[REQ-SUPPORTS-ALTERNATIVE] try/catch where both branches are annotated only with @supports",
+                code: `// @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+try {
+  mightThrow();
+}
+// @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+catch (error) {
+  recoverFrom(error);
+}`,
+            },
+            {
+                name: "[REQ-SUPPORTS-ALTERNATIVE] else-if branch with @supports inside the block body",
+                code: `// @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+if (mode === 'primary') {
+  handlePrimary();
+} else if (mode === 'alternative') {
+  // @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+  handleAlternativeMode();
+}`,
+            },
         ],
         invalid: [
             {

package/lib/tests/rules/require-story-core.autofix.test.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-AUTOFIX - Cover additional branch cases in require-story-core (addStoryFixer/reportMissing)
  * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-AUTOFIX
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-RESILIENCE
  */
 const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
 const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");
@@ -37,4 +38,29 @@ describe("Require Story Core (Story 003.0)", () => {
         expect(call.node).toBe(node);
         expect(call.messageId).toBe("missingStory");
     });
+    test("coreReportMissing swallows dependency errors and does not break lint run", () => {
+        const deps = {
+            hasStoryAnnotation: () => {
+                throw new Error("boom");
+            },
+            getReportedFunctionName: () => "fnX",
+            resolveAnnotationTargetNode: () => ({ type: "FunctionDeclaration" }),
+            getNameNodeForReport: (node) => node,
+            buildTemplateConfig: () => ({
+                effectiveTemplate: "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                allowFix: true,
+            }),
+            extractName: () => "fnX",
+            getAnnotationTemplate: () => "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+            shouldApplyAutoFix: () => true,
+            createAddStoryFix: () => () => ({}),
+            createMethodFix: () => () => ({}),
+        };
+        const context = {
+            report: jest.fn(),
+        };
+        const node = { type: "FunctionDeclaration" };
+        expect(() => (0, require_story_core_1.coreReportMissing)(deps, context, {}, { node })).not.toThrow();
+        expect(context.report).not.toHaveBeenCalled();
+    });
 });

package/lib/tests/utils/branch-annotation-else-if-insert-position.test.d.ts

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

package/lib/tests/utils/branch-annotation-else-if-insert-position.test.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Unit tests for else-if insert position calculation.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-PRETTIER-AUTOFIX-ELSE-IF
+ */
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+describe("Else-if insert position (Story 026.0-DEV-ELSE-IF-ANNOTATION-POSITION)", () => {
+    it("[REQ-PRETTIER-AUTOFIX-ELSE-IF] inserts annotations on a dedicated line inside the else-if block body", () => {
+        const lines = [
+            "if (a) {",
+            "  doA();",
+            "}",
+            "else if (b) {",
+            "  doB();",
+            "}",
+        ];
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({
+                r,
+                t,
+            })),
+        };
+        const context = {
+            getSourceCode() {
+                return {
+                    lines,
+                    getCommentsBefore() {
+                        return [];
+                    },
+                    getIndexFromLoc({ line, column }) {
+                        // simple line/column to index mapping for the test: assume each line ends with "\n"
+                        const prefix = lines.slice(0, line - 1).join("\n");
+                        return prefix.length + (line > 1 ? 1 : 0) + column;
+                    },
+                };
+            },
+            report({ fix }) {
+                // immediately invoke the fixer to exercise the insert position
+                if (typeof fix === "function") {
+                    fix(fixer);
+                }
+            },
+        };
+        const node = {
+            type: "IfStatement",
+            loc: { start: { line: 4 } },
+            test: { loc: { end: { line: 4 } } },
+            consequent: {
+                type: "BlockStatement",
+                loc: { start: { line: 4 } },
+                body: [
+                    {
+                        type: "ExpressionStatement",
+                        loc: { start: { line: 5 } },
+                    },
+                ],
+            },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: node,
+        };
+        node.parent = parent;
+        const storyFixCountRef = { count: 0 };
+        (0, branch_annotation_helpers_1.reportMissingAnnotations)(context, node, storyFixCountRef);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
+        const [range, text] = fixer.insertTextBeforeRange.mock
+            .calls[0];
+        // ensure we are inserting before the first statement in the else-if body (line 5)
+        const expectedIndex = context
+            .getSourceCode()
+            .getIndexFromLoc({ line: 5, column: 0 });
+        expect(range).toEqual([expectedIndex, expectedIndex]);
+        // and that the inserted text is prefixed with the inner indentation from line 5
+        expect(text.startsWith("  ")).toBe(true);
+    });
+});

package/lib/tests/utils/branch-annotation-else-if-position.test.d.ts

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

package/lib/tests/utils/branch-annotation-else-if-position.test.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+function createMockSourceCode(options) {
+    const { lines = [], commentsBefore = [] } = options;
+    return {
+        lines,
+        getCommentsBefore() {
+            return commentsBefore;
+        },
+    };
+}
+describe("gatherBranchCommentText else-if behavior (Story 026.0-DEV-ELSE-IF-ANNOTATION-POSITION)", () => {
+    it("[REQ-DUAL-POSITION-DETECTION-ELSE-IF] detects annotations placed before the else-if keyword", () => {
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [
+                {
+                    value: "@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+                },
+                { value: "@req REQ-DUAL-POSITION-DETECTION-ELSE-IF" },
+            ],
+            // lines are unused in this case because we short-circuit on before-text annotations.
+            lines: [],
+        });
+        const node = {
+            type: "IfStatement",
+            loc: { start: { line: 10 } },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: node,
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent);
+        expect(text).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-DUAL-POSITION-DETECTION-ELSE-IF");
+    });
+    it("[REQ-FALLBACK-LOGIC-ELSE-IF] falls back to annotations between condition and body when before-else-if comments lack annotations", () => {
+        const lines = [
+            "if (a) {",
+            "  doA();",
+            "} else if (b && c) {",
+            "  // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+            "  // @req REQ-FALLBACK-LOGIC-ELSE-IF",
+            "  doB();",
+            "}",
+        ];
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [{ value: "// some unrelated comment" }],
+            lines,
+        });
+        const node = {
+            type: "IfStatement",
+            loc: { start: { line: 3 } },
+            test: { loc: { end: { line: 3 } } },
+            consequent: {
+                type: "BlockStatement",
+                loc: { start: { line: 6 } },
+            },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: node,
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent);
+        expect(text).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-FALLBACK-LOGIC-ELSE-IF");
+    });
+    it("[REQ-POSITION-PRIORITY-ELSE-IF] prefers before-else-if annotations when both positions are present", () => {
+        const lines = [
+            "if (a) {",
+            "  doA();",
+            "} else if (b) {",
+            "  // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+            "  // @req REQ-POSITION-PRIORITY-ELSE-IF-BETWEEN",
+            "  doB();",
+            "}",
+        ];
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [
+                {
+                    value: "@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+                },
+                { value: "@req REQ-POSITION-PRIORITY-ELSE-IF" },
+            ],
+            lines,
+        });
+        const node = {
+            type: "IfStatement",
+            loc: { start: { line: 3 } },
+            test: { loc: { end: { line: 3 } } },
+            consequent: {
+                type: "BlockStatement",
+                loc: { start: { line: 6 } },
+            },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: node,
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent);
+        // The helper should use the before-else-if annotations and not need to
+        // fall back to between-condition-and-body comments.
+        expect(text).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-POSITION-PRIORITY-ELSE-IF");
+        expect(text).not.toContain("REQ-POSITION-PRIORITY-ELSE-IF-BETWEEN");
+    });
+    it("[REQ-SINGLE-LINE-ELSE-IF-SUPPORT] detects annotations on single-line else-if without braces when placed before the else-if keyword", () => {
+        const lines = [
+            "let suggestion;",
+            "// @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+            "// @req REQ-SINGLE-LINE-ELSE-IF-SUPPORT",
+            "if (arg === \"--json\") suggestion = \"--format=json\";",
+            "// @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+            "// @req REQ-SINGLE-LINE-ELSE-IF-SUPPORT",
+            "else if (arg.startsWith(\"--format\")) suggestion = \"--format\";",
+        ];
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [
+                {
+                    value: "@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md",
+                },
+                { value: "@req REQ-SINGLE-LINE-ELSE-IF-SUPPORT" },
+            ],
+            lines,
+        });
+        const node = {
+            type: "IfStatement",
+            loc: { start: { line: 7 } },
+            test: { loc: { end: { line: 7 } } },
+            consequent: {
+                // single-line consequent without BlockStatement braces in the real-world source;
+                // for this helper-level test we only care that loc values exist and are consistent.
+                type: "ExpressionStatement",
+                loc: { start: { line: 7 } },
+            },
+        };
+        const parent = {
+            type: "IfStatement",
+            alternate: node,
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent);
+        expect(text).toContain("@story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-SINGLE-LINE-ELSE-IF-SUPPORT");
+    });
+});

package/lib/tests/utils/req-annotation-detection.test.js

@@ -157,6 +157,20 @@ describe("reqAnnotationDetection advanced heuristics (Story 003.0-DEV-FUNCTION-A
         const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
         expect(has).toBe(false);
     });
+    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when range[0] is not a number", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({ text: "/* @req REQ-IN-TEXT-BUT-INVALID-RANGE */" });
+            },
+        };
+        const node = {
+            // First element of range is not a number; guard on numeric start index should trigger
+            range: ["not-a-number", 10],
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
     it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns true when text window contains @req", () => {
         const fullText = `
       // some header
@@ -244,4 +258,101 @@ describe("reqAnnotationDetection advanced heuristics (Story 003.0-DEV-FUNCTION-A
         const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, { parent: {} });
         expect(has).toBe(true);
     });
+    it("[REQ-ANNOTATION-REQ-DETECTION] linesBeforeHasReq returns true when preceding lines contain @req marker", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({
+                    lines: [
+                        "// some header",
+                        "/** @req REQ-LINE-BEFORE */",
+                        "function foo() {}",
+                    ],
+                });
+            },
+        };
+        const node = {
+            // Node starts on line 3 (1-based), so line 2 is inspected by linesBeforeHasReq
+            loc: { start: { line: 3 } },
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] parentChainHasReq returns true when leadingComments contain @supports and getCommentsBefore is unusable", () => {
+        const context = {
+            getSourceCode() {
+                return {
+                    // Not a callable function; forces parentChainHasReq to rely on leadingComments
+                    getCommentsBefore: 42,
+                };
+            },
+        };
+        const node = {
+            parent: {
+                leadingComments: [
+                    { value: "some other comment" },
+                    {
+                        value: "@supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-FROM-LEADING-COMMENT",
+                    },
+                ],
+                parent: {},
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] returns true when jsdoc has @req even if context is undefined", () => {
+        const jsdoc = { value: "/** @req REQ-JSDOC-NO-CONTEXT */" };
+        const node = {
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], undefined, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqAnnotation returns true when advanced heuristics find req via linesBeforeHasReq", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({
+                    lines: [
+                        "// header without req",
+                        "/** @req REQ-ADV-LINES */",
+                        "function bar() {}",
+                    ],
+                });
+            },
+        };
+        const node = {
+            loc: { start: { line: 3 } },
+            parent: {},
+        };
+        const jsdoc = { value: "/** no req here */" };
+        const comments = [{ value: "no req or supports here" }];
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, comments, context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqAnnotation returns true when advanced heuristics find req via parentChainHasReq", () => {
+        const sourceCode = {
+            getCommentsBefore(n) {
+                if (n && n.isReqParent) {
+                    return [{ value: "/* @req REQ-ADV-PARENT */" }];
+                }
+                return [{ value: "no req here" }];
+            },
+        };
+        const context = {
+            getSourceCode() {
+                return sourceCode;
+            },
+        };
+        const node = {
+            parent: {
+                isReqParent: true,
+                parent: {},
+            },
+        };
+        const jsdoc = { value: "/** jsdoc without requirement */" };
+        const comments = [{ value: "comment without requirement" }];
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, comments, context, node);
+        expect(has).toBe(true);
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.11.4",
+  "version": "1.12.1",
   "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",

package/user-docs/api-reference.md

@@ -15,7 +15,7 @@ In addition to the core `@story` and `@req` annotations, the plugin also underst
 `@supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND`
 to indicate that a given function supports a particular requirement from a payments story document within that project’s own `docs/stories` tree. For a detailed explanation of `@supports` behavior and validation, see [Migration Guide](migration-guide.md) (section **3.1 Multi-story @supports annotations**). Additional background on multi-story semantics is available in the project’s internal rule documentation, which is intended for maintainers rather than end users.
 
-The `prefer-supports-annotation` rule is an **opt-in migration helper** that is disabled by default and **not** part of any built-in preset. It can be enabled and given a severity like `"warn"` or `"error"` using normal ESLint rule configuration when you want to gradually encourage multi-story `@supports` usage. The legacy rule key `traceability/prefer-implements-annotation` remains available as a **deprecated alias** for backward compatibility, but new configurations should prefer `traceability/prefer-supports-annotation`. Detailed behavior and migration guidance are documented in the project’s internal rule documentation, which is targeted at maintainers; typical end users can rely on the high-level guidance in this API reference and the [Migration Guide](migration-guide.md).
+The `prefer-supports-annotation` rule is an **opt-in migration helper** that is disabled by default and **not** part of any built-in preset. It can be enabled and given a severity like `"warn"` or `"error"` using normal ESLint rule configuration when you want to gradually encourage multi-story `@supports` usage. The legacy rule key `traceability/prefer-implements-annotation` remains available as a **deprecated alias** for backward compatibility, but new configurations should prefer `traceability/prefer-supports-annotation`. Detailed behavior and migration guidance are documented in the project’s internal rule documentation, which is targeted for maintainers; typical end users can rely on the high-level guidance in this API reference and the [Migration Guide](migration-guide.md).
 
 ### traceability/require-story-annotation
 
@@ -68,7 +68,9 @@ function initAuth() {
 
 ### traceability/require-branch-annotation
 
-Description: Ensures significant code branches (if/else, loops, switch cases, try/catch) have both `@story` and `@req` annotations in preceding comments. For `catch` clauses specifically, the rule accepts annotations either immediately before the `catch` keyword or as the first comment-only lines inside the catch block; for `else if` branches, the rule accepts annotations either immediately before the `else if` keyword or on comment-only lines between the `else if (condition)` and the first statement of the consequent body, matching Prettier’s wrapped style.
+Description: Ensures significant code branches (if/else chains, loops, switch cases, try/catch) have both `@story` and `@req` annotations in nearby comments. When you adopt multi-story `@supports` annotations, a single `@supports <storyPath> <REQ-ID>...` line placed in any of the valid branch comment locations is treated as satisfying both the story and requirement presence checks for that branch, while detailed format validation of the `@supports` value (including story paths and requirement IDs) continues to be handled by `traceability/valid-annotation-format`, `traceability/valid-story-reference`, and `traceability/valid-req-reference`.
+
+For most branches, the rule looks for annotations in comments immediately preceding the branch keyword (for example, the line above an `if` or `for` statement). For `catch` clauses and `else if` branches, the rule is formatter-aware and accepts annotations in additional positions that common formatters like Prettier use when they reflow code.
 
 Options:
 
@@ -76,8 +78,22 @@ Options:
 
 Behavior notes:
 
-- When both before-`catch` and inside-block annotations are present for the same catch clause, the comments immediately before `catch` take precedence for validation and reporting.
-- When auto-fixing missing annotations on a catch clause, the rule inserts placeholder comments inside the catch body so that formatters like Prettier preserve them and do not move them to unexpected locations.
+- **Catch clauses**:
+  - Valid locations for `@story` / `@req` annotations are either immediately before the `catch` keyword or on the first comment-only lines inside the catch block (before any executable statements). A single `@supports` annotation in either of these locations is also accepted as covering both story and requirement presence for the catch branch.
+  - If annotations exist in both locations, the comments immediately before `catch` take precedence for validation and reporting.
+  - When auto-fixing missing annotations on a catch clause, the rule inserts placeholder comments inside the catch block body so that formatters like Prettier keep them attached to the branch.
+
+- **Else-if branches**:
+  - Valid locations for `@story` / `@req` annotations include:
+    - Line or block comments immediately before the `else if` line.
+    - Comment-only lines between the `else if (condition)` and the opening `{` of the consequent block (for styles where the condition and block are on separate lines).
+    - The first comment-only lines inside the consequent block body, which is where formatters like Prettier often move comments when they wrap long `else if` conditions. For a concrete before/after example of this formatter-aware behavior, see [user-docs/examples.md](examples.md) (section **6. Branch annotations with if/else/else-if and Prettier**).
+  - When annotations appear in more than one of these locations, the rule prefers the comments immediately before the `else if` line, then comments between the condition and the block, and finally comments inside the block body. This precedence is designed to closely mirror real-world formatter behavior and matches the formatter-aware scenarios described in stories 025.0 and 026.0.
+  - When auto-fixing missing annotations on an `else if` branch, the rule inserts placeholder comments as the first comment-only line inside the consequent block body (just after the opening `{`), which is a stable location under Prettier and similar formatters. As with catch clauses, a single `@supports` annotation placed in any of these accepted locations is treated as equivalent to having both `@story` and `@req` comments for that branch, with deep format and existence checks delegated to the other validation rules.
+
+For a concrete illustration of how these rules interact with Prettier, see the formatter-aware if/else/else-if example in [user-docs/examples.md](examples.md) (section **6. Branch annotations with if/else/else-if and Prettier**), which shows both the hand-written and formatted code that the rule considers valid.
+
+These behaviors are intentionally limited to `catch` clauses and `else if` branches; other branch types (plain `if`, `else`, loops, and `switch` cases) continue to use the simpler "comments immediately before the branch" association model for both validation and auto-fix placement.
 
 Default Severity: `error`
 Example:
@@ -689,4 +705,5 @@ If `--from` or `--to` is missing, the CLI prints an error, shows the help text,
 In CI:
 
 ```bash
-npm run traceability:verify
+npm run traceability:verify
+```

package/user-docs/examples.md

@@ -114,3 +114,65 @@ function performOperation(input: string): string {
   return "ok";
 }
 ```
+
+## 6. Branch annotations with if/else/else-if and Prettier
+
+This example shows how to keep `traceability/require-branch-annotation` satisfied while still running Prettier on your code.
+
+### 6.1 Before formatting
+
+In this version, annotations are placed immediately before each significant branch. This is a simple layout that is easy to read and accepted by the rule:
+
+```ts
+function pickCategory(score: number): string {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-BRANCH-DETECTION
+  if (score >= 80) {
+    return "high";
+  }
+  // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+  // @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
+  else if (score >= 50) {
+    return "medium";
+  }
+  // You can annotate `else` using the same pattern if you treat it as a significant branch.
+  else {
+    return "low";
+  }
+}
+```
+
+You can run just the branch-annotation rule via the CLI:
+
+```bash
+npx eslint --no-eslintrc \
+  --rule "traceability/require-branch-annotation:error" \
+  pick-category.ts
+```
+
+### 6.2 After formatting with Prettier
+
+Prettier may reflow your `else if` line, wrap the condition, or move comments into the body of the branch. The `traceability/require-branch-annotation` rule is formatter-aware and will still recognize valid annotations in supported positions, such as the first comment-only lines inside the block body:
+
+```ts
+function pickCategory(score: number): string {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-BRANCH-DETECTION
+  if (score >= 80) {
+    return "high";
+  } else if (score >= 50) {
+    // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+    // @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
+    return "medium";
+  } else {
+    return "low";
+  }
+}
+```
+
+Depending on your Prettier version and configuration, the exact layout of the `else if` line and braces may differ, but as long as your annotations are in one of the supported locations, the rule will accept them.
+
+- Notes:
+  - For most branch types, `traceability/require-branch-annotation` associates comments immediately before the branch keyword (such as `if`, `else`, `switch`, `case`) with that branch.
+  - For `catch` clauses and `else if` branches, the rule is formatter-aware and also looks at comments between the condition and the block, as well as the first comment-only lines inside the block body, so you do not need to fight Prettier if it moves your annotations.
+  - When annotations exist in more than one place around an `else if` branch, the rule prefers comments immediately before the `else if` line, then comments between the condition and the block, and finally comments inside the block body, matching the behavior described in the API reference and stories `025.0` and `026.0`.

package/user-docs/migration-guide.md

@@ -188,6 +188,15 @@ You can introduce `@supports` gradually without breaking existing code:
 
 Detailed semantics and edge cases (path validation, scoped requirement IDs, and multi-story fixtures) are ultimately governed by your own stories and requirements. For typical migrations, this guide together with the plugin’s API reference is sufficient.
 
+### 3.2 Else-if branch annotations and formatter compatibility
+
+Versions 1.x of `eslint-plugin-traceability` extend the `traceability/require-branch-annotation` rule to better support formatter-driven layouts for `else if` branches. In most projects you **do not need to change existing annotations**:
+
+- Comments immediately before an `else if` line remain valid and continue to satisfy the rule.
+- When formatters such as Prettier move comments between the `else if (condition)` and the opening `{`, or into the first comment-only lines inside the `{ ... }` block, those annotations are now also recognized and associated with the correct branch.
+
+If you previously added suppressions or workaround comments around `else if` branches due to formatter conflicts, you can usually remove those workarounds after upgrading to 1.x as long as your annotations live in one of the supported locations. For new code, you can place annotations either directly above the `else if` or, when you know a formatter will wrap a long condition, on the first comment-only line inside the consequent block body, which is where the rule places auto-fix placeholders by default.
+
 ## 4. Test and Validate
 
 Run your test suite to confirm everything passes: