eslint-plugin-traceability 1.12.0 → 1.12.1

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.12.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.11.4...v1.12.0) (2025-12-07)
+## [1.12.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.12.0...v1.12.1) (2025-12-07)
 
 
-### Features
+### Bug Fixes
 
-* accept [@supports](https://github.com/supports) annotations on branches as alternative format ([6773a3a](https://github.com/voder-ai/eslint-plugin-traceability/commit/6773a3ae190e9b9adc605c7d17112f44401e5b24))
+* 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

@@ -87,24 +87,69 @@ function extractCommentValue(_c) {
     return _c.value;
 }
 /**
- * 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).
+ * 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 collectCommentLine(lines, index, comments) {
+function getCommentTextAtLine(lines, index) {
     const line = lines[index];
     if (!line || !line.trim()) {
-        return false;
+        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(line.trim());
+    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" &&
@@ -139,15 +184,7 @@ 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) {
-            if (!collectCommentLine(lines, i, comments)) {
-                break;
-            }
-            i++;
-        }
-        const insideText = comments.join(" ");
+        const insideText = scanCommentLinesInRange(lines, startIndex + 1, endIndex);
         if (insideText) {
             return insideText;
         }
@@ -165,14 +202,11 @@ function scanElseIfPrecedingComments(sourceCode, node) {
     let i = startLine - 1;
     let scanned = 0;
     while (i >= 0 && scanned < PRE_COMMENT_OFFSET) {
-        const line = lines[i];
-        if (!line || !line.trim()) {
-            break;
-        }
-        if (!/^\s*(\/\/|\/\*)/.test(line)) {
+        const commentText = getCommentTextAtLine(lines, i);
+        if (!commentText) {
             break;
         }
-        comments.unshift(line.trim());
+        comments.unshift(commentText);
         i--;
         scanned++;
     }
@@ -194,13 +228,16 @@ function scanElseIfBetweenConditionAndBody(sourceCode, node) {
     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 - 1; lineIndex++) {
-        if (!collectCommentLine(lines, lineIndex, comments)) {
-            break;
-        }
+    // 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 comments.join(" ");
+    return scanCommentLinesInRange(lines, startIndex, endIndexExclusive - 1);
 }
 /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
 function scanElseIfInsideBlockComments(sourceCode, node) {
@@ -228,7 +265,10 @@ function scanElseIfInsideBlockComments(sourceCode, node) {
  * @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)) {
@@ -236,7 +276,9 @@ function gatherElseIfCommentText(sourceCode, node, parent, beforeText) {
     }
     const beforeElseText = scanElseIfPrecedingComments(sourceCode, node);
     if (beforeElseText &&
-        (/@story\b/.test(beforeElseText) || /@req\b/.test(beforeElseText))) {
+        (/@story\b/.test(beforeElseText) ||
+            /@req\b/.test(beforeElseText) ||
+            /@supports\b/.test(beforeElseText))) {
         return beforeElseText;
     }
     if (!hasValidElseIfBlockLoc(node)) {

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,16 +71,16 @@ else if (anotherVeryLongConditionThatForcesWrapping && someOtherCondition) {
   doB();
 }
 `;
-            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 = `
+        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;
 }
@@ -102,70 +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("[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;
-}
-
-function doB() {
-  return 2;
-}
-
-// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-BRANCH-DETECTION
-if (aVeryLongConditionThatForcesPrettierToWrapTheElseIfBranch && anotherCondition) {
-  doA();
-}
-// @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
-// @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
-else if (anotherVeryLongConditionThatForcesWrapping && someOtherCondition) {
-  doB();
-}
-`;
-            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.skip("[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;
-}
-
-function doB() {
-  return 2;
-}
-
-// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
-// @req REQ-BRANCH-DETECTION
-if (aVeryLongConditionThatForcesPrettierToWrapTheElseIfBranch && anotherCondition) {
-  doA();
-} else if (
-  anotherVeryLongConditionThatForcesWrapping && someOtherCondition
-) {
-  // @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
-  // @req REQ-DUAL-POSITION-DETECTION-ELSE-IF
-  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);
-        });
-    }
+        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-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-position.test.js

@@ -104,4 +104,42 @@ describe("gatherBranchCommentText else-if behavior (Story 026.0-DEV-ELSE-IF-ANNO
         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

@@ -309,4 +309,50 @@ describe("reqAnnotationDetection advanced heuristics (Story 003.0-DEV-FUNCTION-A
         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.12.0",
+  "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",