eslint-plugin-traceability 1.10.1 → 1.11.1

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

@@ -133,42 +133,32 @@ function parentChainHasStory(sourceCode, node) {
     return false;
 }
 /**
- * Fallback: inspect text immediately preceding the node in sourceCode.getText to find @story
- * Also accepts @supports annotations as satisfying story presence for this rule.
+ * Safely compute the starting range index for fallback text scanning.
+ * Centralizes guards around sourceCode.getText and node.range structure.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @supports annotations as satisfying story presence in fallback checks
+ * @req REQ-ANNOTATION-REQUIRED - Centralize guards for fallback range computation
  */
-function fallbackTextBeforeHasStory(sourceCode, node) {
-    // Skip fallback text inspection when the sourceCode API or node range information is not available.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQUIRED - Avoid throwing when source text or range metadata cannot be read
-    if (typeof sourceCode?.getText !== "function" ||
-        !Array.isArray((node && node.range) || [])) {
-        return false;
+function getFallbackRangeStart(sourceCode, node) {
+    if (typeof sourceCode?.getText !== "function") {
+        return null;
     }
-    const range = node.range;
-    // Guard against malformed range values that cannot provide a numeric start index for slicing.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQUIRED - Validate node range structure before computing fallback window
+    const range = (node && node.range) || null;
     if (!Array.isArray(range) || typeof range[0] !== "number") {
-        return false;
+        return null;
     }
+    return range[0];
+}
+/**
+ * Safely slice a bounded fallback text window immediately preceding the node start index.
+ * Restricts scanning to a fixed-size window and treats IO/slicing failures as non-fatal.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Restrict fallback text scanning to a safe, fixed-size window and handle failures gracefully
+ */
+function getFallbackTextWindow(sourceCode, nodeStartIndex) {
+    const start = Math.max(0, nodeStartIndex - exports.FALLBACK_WINDOW);
     try {
-        // Limit the fallback inspection window to a bounded region immediately preceding the node.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQUIRED - Restrict fallback text scanning to a safe, fixed-size window
-        const start = Math.max(0, range[0] - exports.FALLBACK_WINDOW);
-        const textBefore = sourceCode.getText().slice(start, range[0]);
-        // Detect any @story or @supports marker that appears within the bounded fallback window.
-        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-        // @req REQ-ANNOTATION-REQUIRED - Recognize story annotations discovered via fallback text scanning
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Recognize @supports annotations discovered via fallback text scanning
-        if (typeof textBefore === "string" &&
-            (textBefore.includes("@story") || textBefore.includes("@supports"))) {
-            return true;
-        }
+        const textBefore = sourceCode.getText().slice(start, nodeStartIndex);
+        return typeof textBefore === "string" ? textBefore : null;
     }
     catch {
         /*
@@ -176,6 +166,36 @@ function fallbackTextBeforeHasStory(sourceCode, node) {
          * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
          * @req REQ-ANNOTATION-REQUIRED - Treat fallback text inspection failures as "no annotation" instead of raising
          */
+        return null;
     }
-    return false;
+}
+/**
+ * Detect whether the provided fallback text window contains a story marker.
+ * Recognizes both @story and @supports annotations in the inspected text.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Recognize story annotations discovered via fallback text scanning
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Recognize @supports annotations discovered via fallback text scanning
+ */
+function fallbackTextHasMarker(textBefore) {
+    if (typeof textBefore !== "string") {
+        return false;
+    }
+    return textBefore.includes("@story") || textBefore.includes("@supports");
+}
+/**
+ * Fallback: inspect text immediately preceding the node in sourceCode.getText to find @story
+ * Also accepts @supports annotations as satisfying story presence for this rule.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @supports annotations as satisfying story presence in fallback checks
+ */
+function fallbackTextBeforeHasStory(sourceCode, node) {
+    const nodeStartIndex = getFallbackRangeStart(sourceCode, node);
+    if (nodeStartIndex === null) {
+        return false;
+    }
+    const textBefore = getFallbackTextWindow(sourceCode, nodeStartIndex);
+    return fallbackTextHasMarker(textBefore);
 }

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

@@ -27,7 +27,14 @@ function buildFunctionDeclarationVisitor(context, sourceCode, options) {
         if (!options.shouldProcessNode(node))
             return;
         const target = (0, require_story_helpers_1.resolveTargetNode)(sourceCode, node);
-        (0, require_story_helpers_1.reportMissing)(context, sourceCode, node, target);
+        (0, require_story_helpers_1.reportMissing)(context, sourceCode, {
+            node,
+            target,
+            options: {
+                annotationTemplateOverride: options.annotationTemplate,
+                autoFixToggle: options.autoFix,
+            },
+        });
     }
     return {
         FunctionDeclaration: handleFunctionDeclaration,
@@ -55,7 +62,14 @@ function buildFunctionExpressionVisitor(context, sourceCode, options) {
         if (node.parent && node.parent.type === "MethodDefinition")
             return;
         const target = (0, require_story_helpers_1.resolveTargetNode)(sourceCode, node);
-        (0, require_story_helpers_1.reportMissing)(context, sourceCode, node, target);
+        (0, require_story_helpers_1.reportMissing)(context, sourceCode, {
+            node,
+            target,
+            options: {
+                annotationTemplateOverride: options.annotationTemplate,
+                autoFixToggle: options.autoFix,
+            },
+        });
     }
     return {
         FunctionExpression: handleFunctionExpression,
@@ -76,7 +90,14 @@ function buildArrowFunctionVisitor(context, sourceCode, options) {
         if (!options.shouldProcessNode(node))
             return;
         const target = (0, require_story_helpers_1.resolveTargetNode)(sourceCode, node);
-        (0, require_story_helpers_1.reportMissing)(context, sourceCode, node, target);
+        (0, require_story_helpers_1.reportMissing)(context, sourceCode, {
+            node,
+            target,
+            options: {
+                annotationTemplateOverride: options.annotationTemplate,
+                autoFixToggle: options.autoFix,
+            },
+        });
     }
     return {
         ArrowFunctionExpression: handleArrowFunctionExpression,
@@ -96,7 +117,14 @@ function buildTSDeclareFunctionVisitor(context, sourceCode, options) {
     function handleTSDeclareFunction(node) {
         if (!options.shouldProcessNode(node))
             return;
-        (0, require_story_helpers_1.reportMissing)(context, sourceCode, node, node);
+        (0, require_story_helpers_1.reportMissing)(context, sourceCode, {
+            node,
+            target: node,
+            options: {
+                annotationTemplateOverride: options.annotationTemplate,
+                autoFixToggle: options.autoFix,
+            },
+        });
     }
     return {
         TSDeclareFunction: handleTSDeclareFunction,
@@ -117,7 +145,14 @@ function buildTSMethodSignatureVisitor(context, sourceCode, options) {
         if (!options.shouldProcessNode(node))
             return;
         const target = (0, require_story_helpers_1.resolveTargetNode)(sourceCode, node);
-        (0, require_story_helpers_1.reportMissing)(context, sourceCode, node, target);
+        (0, require_story_helpers_1.reportMissing)(context, sourceCode, {
+            node,
+            target,
+            options: {
+                annotationTemplateOverride: options.methodAnnotationTemplate ?? options.annotationTemplate,
+                autoFixToggle: options.autoFix,
+            },
+        });
     }
     return {
         TSMethodSignature: handleTSMethodSignature,
@@ -137,7 +172,13 @@ function buildMethodDefinitionVisitor(context, sourceCode, options) {
     function handleMethodDefinition(node) {
         if (!options.shouldProcessNode(node))
             return;
-        (0, require_story_helpers_1.reportMethod)(context, sourceCode, node);
+        (0, require_story_helpers_1.reportMethod)(context, sourceCode, {
+            node,
+            options: {
+                annotationTemplateOverride: options.methodAnnotationTemplate ?? options.annotationTemplate,
+                autoFixToggle: options.autoFix,
+            },
+        });
     }
     return {
         MethodDefinition: handleMethodDefinition,

package/lib/src/rules/helpers/valid-annotation-format-validators.js

@@ -167,7 +167,11 @@ function validateStoryAnnotation(context, comment, rawValue, options) {
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
     // @req REQ-AUTOFIX-FORMAT - Apply suffix-only auto-fix when it yields a pattern-compliant path
     if (fixed && pathPattern.test(fixed)) {
-        reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed);
+        if (options.autoFix !== false) {
+            reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed);
+            return;
+        }
+        reportInvalidStoryFormat(context, comment, collapsed, options);
         return;
     }
     reportInvalidStoryFormat(context, comment, collapsed, options);

package/lib/src/rules/helpers/valid-annotation-options.d.ts

@@ -53,6 +53,11 @@ export interface AnnotationRuleOptions {
      * Human-readable example requirement ID used in error messages.
      */
     requirementIdExample?: string;
+    /**
+     * Global toggle for auto-fix behavior in valid-annotation-format.
+     * When false, no automatic suffix-normalization fixes are applied.
+     */
+    autoFix?: boolean;
 }
 /**
  * Resolved, runtime-ready options for the rule.
@@ -62,6 +67,7 @@ export interface ResolvedAnnotationOptions {
     storyExample: string;
     reqPattern: RegExp;
     reqExample: string;
+    autoFix: boolean;
 }
 export declare function getDefaultReqExample(): string;
 export declare function getResolvedDefaults(): ResolvedAnnotationOptions;
@@ -113,6 +119,9 @@ export declare function getRuleSchema(): {
         requirementIdExample: {
             type: string;
         };
+        autoFix: {
+            type: string;
+        };
     };
     additionalProperties: boolean;
 }[];

package/lib/src/rules/helpers/valid-annotation-options.js

@@ -26,6 +26,7 @@ let resolvedDefaults = {
     storyExample: getDefaultStoryExample(),
     reqPattern: getDefaultReqPattern(),
     reqExample: getDefaultReqExample(),
+    autoFix: true,
 };
 /**
  * Collected configuration errors encountered while resolving options.
@@ -104,43 +105,88 @@ function resolveExample(nestedExample, flatExample, defaultExample) {
     }
     return defaultExample;
 }
-/**
- * Resolve user options into concrete, validated configuration.
- * Falls back to existing defaults when options are not provided or invalid.
- */
-function resolveOptions(rawOptions) {
-    optionErrors = [];
-    const user = normalizeUserOptions(rawOptions);
-    const nestedStoryPattern = user?.story?.pattern;
-    const flatStoryPattern = user?.storyPathPattern;
-    const nestedStoryExample = user?.story?.example;
-    const flatStoryExample = user?.storyPathExample;
-    const nestedReqPattern = user?.req?.pattern;
-    const flatReqPattern = user?.requirementIdPattern;
-    const nestedReqExample = user?.req?.example;
-    const flatReqExample = user?.requirementIdExample;
-    const storyPattern = resolvePattern({
+function getUserOptions(rawOptions) {
+    return normalizeUserOptions(rawOptions);
+}
+function resolveAutoFixFlag(user) {
+    const autoFixFlag = user?.autoFix;
+    return typeof autoFixFlag === "boolean" ? autoFixFlag : true;
+}
+function resolveStoryPattern(nestedStoryPattern, flatStoryPattern) {
+    return resolvePattern({
         nestedPattern: nestedStoryPattern,
         nestedFieldName: "story.pattern",
         flatPattern: flatStoryPattern,
         flatFieldName: "storyPathPattern",
         defaultPattern: getDefaultStoryPattern(),
     });
-    const reqPattern = resolvePattern({
+}
+function resolveReqPattern(nestedReqPattern, flatReqPattern) {
+    return resolvePattern({
         nestedPattern: nestedReqPattern,
         nestedFieldName: "req.pattern",
         flatPattern: flatReqPattern,
         flatFieldName: "requirementIdPattern",
         defaultPattern: getDefaultReqPattern(),
     });
-    const storyExample = resolveExample(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
-    const reqExample = resolveExample(nestedReqExample, flatReqExample, getDefaultReqExample());
-    resolvedDefaults = {
+}
+function resolveStoryExample(nestedStoryExample, flatStoryExample) {
+    return resolveExample(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
+}
+function resolveReqExample(nestedReqExample, flatReqExample) {
+    return resolveExample(nestedReqExample, flatReqExample, getDefaultReqExample());
+}
+function getStoryPatternInputs(user) {
+    return {
+        nestedStoryPattern: user?.story?.pattern,
+        flatStoryPattern: user?.storyPathPattern,
+    };
+}
+function getStoryExampleInputs(user) {
+    return {
+        nestedStoryExample: user?.story?.example,
+        flatStoryExample: user?.storyPathExample,
+    };
+}
+function getReqPatternInputs(user) {
+    return {
+        nestedReqPattern: user?.req?.pattern,
+        flatReqPattern: user?.requirementIdPattern,
+    };
+}
+function getReqExampleInputs(user) {
+    return {
+        nestedReqExample: user?.req?.example,
+        flatReqExample: user?.requirementIdExample,
+    };
+}
+function resolveOptionsInternal(user) {
+    const { nestedStoryPattern, flatStoryPattern } = getStoryPatternInputs(user);
+    const { nestedStoryExample, flatStoryExample } = getStoryExampleInputs(user);
+    const { nestedReqPattern, flatReqPattern } = getReqPatternInputs(user);
+    const { nestedReqExample, flatReqExample } = getReqExampleInputs(user);
+    const autoFix = resolveAutoFixFlag(user);
+    const storyPattern = resolveStoryPattern(nestedStoryPattern, flatStoryPattern);
+    const reqPattern = resolveReqPattern(nestedReqPattern, flatReqPattern);
+    const storyExample = resolveStoryExample(nestedStoryExample, flatStoryExample);
+    const reqExample = resolveReqExample(nestedReqExample, flatReqExample);
+    return {
         storyPattern,
         storyExample,
         reqPattern,
         reqExample,
+        autoFix,
     };
+}
+/**
+ * Resolve user options into concrete, validated configuration.
+ * Falls back to existing defaults when options are not provided or invalid.
+ */
+function resolveOptions(rawOptions) {
+    optionErrors = [];
+    const user = getUserOptions(rawOptions);
+    const resolved = resolveOptionsInternal(user);
+    resolvedDefaults = resolved;
     return resolvedDefaults;
 }
 /**
@@ -171,6 +217,7 @@ function getRuleSchema() {
                 storyPathExample: { type: "string" },
                 requirementIdPattern: { type: "string" },
                 requirementIdExample: { type: "string" },
+                autoFix: { type: "boolean" },
             },
             additionalProperties: false,
         },

package/lib/src/rules/helpers/valid-annotation-utils.js

@@ -39,7 +39,7 @@ exports.STORY_EXAMPLE_PATH = "docs/stories/005.0-DEV-EXAMPLE.story.md";
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 function collapseAnnotationValue(value) {
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-MULTILINE-SUPPORT
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-MULTILINE-SUPPORT
     return value.replace(/\s+/g, "");
 }
 /**
@@ -62,42 +62,42 @@ function collapseAnnotationValue(value) {
  */
 function getFixedStoryPath(original) {
     // @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md | REQ-AUTOFIX-SAFE - Reject auto-fix when the path contains ".." traversal segments to avoid broadening the reference.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by rejecting paths that use unsafe traversal segments.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by rejecting paths that use unsafe traversal segments.
     if (original.includes("..")) {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
-        // @implements docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-SAFE
-        // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-AUTOFIX-SAFE
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
+        // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-SAFE
+        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-AUTOFIX-SAFE
         return null;
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md | REQ-AUTOFIX-FORMAT - Leave correctly formatted ".story.md" paths unchanged so diagnostics are not hidden by redundant fixes.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by recognizing already valid ".story.md" paths without altering them.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by recognizing already valid ".story.md" paths without altering them.
     if (/\.story\.md$/.test(original)) {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
-        // @implements docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT
-        // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-AUTOFIX-FORMAT
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
+        // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT
+        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-AUTOFIX-FORMAT
         return null;
     }
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE - When ".story" is present but ".md" is missing, append only the extension without altering the base path.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by completing a partially correct ".story" suffix to the canonical ".story.md".
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by completing a partially correct ".story" suffix to the canonical ".story.md".
     if (/\.story$/.test(original)) {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
-        // @implements docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE
-        // @implements docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
+        // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE
+        // @supports docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
         return `${original}.md`;
     }
     // @story docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE - Normalize plain ".md" doc paths to ".story.md" while keeping the rest of the path intact.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by transforming generic ".md" references into canonical ".story.md" story paths.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by transforming generic ".md" references into canonical ".story.md" story paths.
     if (/\.md$/.test(original)) {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
-        // @implements docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE
-        // @implements docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
+        // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE
+        // @supports docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
         return original.replace(/\.md$/, ".story.md");
     }
     // @story docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE REQ-AUTOFIX-SAFE - For bare paths with no extension, append ".story.md" as a canonical story reference without touching the directory.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence and correctness of the story identifier by supplying the standard ".story.md" suffix when no extension is provided.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
-    // @implements docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE REQ-AUTOFIX-SAFE
-    // @implements docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence and correctness of the story identifier by supplying the standard ".story.md" suffix when no extension is provided.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
+    // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE REQ-AUTOFIX-SAFE
+    // @supports docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
     return `${original}.story.md`;
 }
 /**
@@ -112,14 +112,14 @@ function getFixedStoryPath(original) {
 function buildStoryErrorMessage(kind, value, options) {
     const example = options.storyExample || exports.STORY_EXAMPLE_PATH;
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md | REQ-ERROR-SPECIFICITY - Use a dedicated message variant when the @story value is completely missing.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence of the story identifier by emitting a targeted message when the @story value is absent.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence of the story identifier by emitting a targeted message when the @story value is absent.
     if (kind === "missing") {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-        // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
+        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
         return `Missing story path for @story annotation. Expected a path like "${example}".`;
     }
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-    // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
+    // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
     return `Invalid story path "${value ?? ""}" for @story annotation. Expected a path like "${example}".`;
 }
 /**
@@ -134,13 +134,13 @@ function buildStoryErrorMessage(kind, value, options) {
 function buildReqErrorMessage(kind, value, options) {
     const example = options.reqExample || (0, valid_annotation_options_1.getDefaultReqExample)();
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md | REQ-ERROR-SPECIFICITY - Distinguish a completely missing @req from one that is present but malformed.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence of the requirement identifier by emitting a specific message when the @req value is missing.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence of the requirement identifier by emitting a specific message when the @req value is missing.
     if (kind === "missing") {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-        // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
+        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
         return `Missing requirement ID for @req annotation. Expected an identifier like "${example}".`;
     }
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-    // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
+    // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
     return `Invalid requirement ID "${value ?? ""}" for @req annotation. Expected an identifier like "${example}" (uppercase letters, numbers, and dashes only).`;
 }

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

@@ -20,14 +20,14 @@ function analyzeCandidateBoundaries(candidates, cwd) {
     let hasInProjectCandidate = false;
     let hasOutOfProjectCandidate = false;
     for (const candidate of candidates) {
-        // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
+        // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
         const boundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(candidate, cwd);
         if (boundary.isWithinProject) {
-            // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY
+            // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY
             hasInProjectCandidate = true;
         }
         else {
-            // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY
+            // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY
             hasOutOfProjectCandidate = true;
         }
     }
@@ -47,12 +47,12 @@ function analyzeCandidateBoundaries(candidates, cwd) {
  */
 function handleProjectBoundaryForExistence({ storyPath, commentNode, context, cwd, candidates, existenceResult, reportInvalidPath, }) {
     if (candidates.length > 0) {
-        // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
-        // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
+        // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
+        // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
         const { hasInProjectCandidate, hasOutOfProjectCandidate } = analyzeCandidateBoundaries(candidates, cwd);
         if (hasOutOfProjectCandidate && !hasInProjectCandidate) {
-            // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
-            // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY
+            // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
+            // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY
             reportInvalidPath({ storyPath, commentNode, context });
             return true;
         }
@@ -60,12 +60,12 @@ function handleProjectBoundaryForExistence({ storyPath, commentNode, context, cw
     if (existenceResult &&
         existenceResult.status === "exists" &&
         existenceResult.matchedPath) {
-        // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
-        // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY
+        // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
+        // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY
         const boundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(existenceResult.matchedPath, cwd);
         if (!boundary.isWithinProject) {
-            // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
-            // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY
+            // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
+            // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY
             reportInvalidPath({ storyPath, commentNode, context });
             return true;
         }
@@ -83,11 +83,11 @@ function handleProjectBoundaryForExistence({ storyPath, commentNode, context, cw
 function performSecurityValidations({ storyPath, commentNode, context, cwd, allowAbsolute, reportInvalidPath, }) {
     // Absolute path check
     if (path_1.default.isAbsolute(storyPath)) {
-        // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
-        // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-SECURITY-VALIDATION
+        // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
+        // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-SECURITY-VALIDATION
         if (!allowAbsolute) {
-            // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
-            // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-SECURITY-VALIDATION
+            // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
+            // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-SECURITY-VALIDATION
             reportInvalidPath({ storyPath, commentNode, context });
             return false;
         }
@@ -97,12 +97,12 @@ function performSecurityValidations({ storyPath, commentNode, context, cwd, allo
     // Path traversal check
     const containsTraversal = storyPath.includes("..") || /\\|\//.test(storyPath);
     if (containsTraversal) {
-        // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
-        // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-SECURITY-VALIDATION
+        // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
+        // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-SECURITY-VALIDATION
         const full = path_1.default.resolve(cwd, path_1.default.normalize(storyPath));
         if (!full.startsWith(cwd + path_1.default.sep)) {
-            // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
-            // @implements docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-SECURITY-VALIDATION
+            // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-PROJECT-BOUNDARY REQ-SECURITY-VALIDATION
+            // @supports docs/stories/006.0-DEV-FILE-VALIDATION.story.md REQ-SECURITY-VALIDATION
             reportInvalidPath({ storyPath, commentNode, context });
             return false;
         }

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

@@ -12,6 +12,14 @@ const MIN_STORY_TOKENS = 2;
 const MIN_REQ_TOKENS = MIN_STORY_TOKENS;
 // Length of the opening "/*" portion of a block comment prefix.
 const COMMENT_PREFIX_LENGTH = 2;
+/**
+ * Collect line indices and metadata for @story and @req annotations within a
+ * single block comment. This helper isolates the parsing logic used by the
+ * auto-fix path so that complex or ambiguous patterns can be detected and
+ * safely rejected.
+ *
+ * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-AUTO-FIX REQ-SINGLE-STORY-FIX REQ-VALID-OUTPUT
+ */
 function collectStoryAndReqMetadata(comment) {
     const rawValue = comment.value || "";
     const rawLines = rawValue.split(/\r?\n/);
@@ -52,6 +60,13 @@ function collectStoryAndReqMetadata(comment) {
     });
     return { storyLineIndices, reqLineIndices, reqIds, storyPath };
 }
+/**
+ * Apply the @supports replacement for simple, single-story legacy blocks,
+ * constructing a fixed comment body that preserves existing indentation and
+ * prefix formatting while removing the original @story/@req lines.
+ *
+ * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-AUTO-FIX REQ-SINGLE-STORY-FIX REQ-PRESERVE-FORMAT REQ-VALID-OUTPUT
+ */
 function applyImplementsReplacement(context, comment, details) {
     const { storyIdx, allIndicesToRemove, storyPath, reqIds } = details;
     const rawValue = comment.value || "";
@@ -98,7 +113,7 @@ function applyImplementsReplacement(context, comment, details) {
  * More complex patterns remain diagnostics-only with no fix to avoid
  * producing invalid or ambiguous output.
  *
- * @implements docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
+ * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
  * @req REQ-AUTO-FIX - Provide safe, opt-in auto-fix for simple legacy patterns
  * @req REQ-SINGLE-STORY-FIX - Restrict auto-fix to single-story, single-path cases
  * @req REQ-PRESERVE-FORMAT - Preserve original JSDoc indentation and prefix formatting
@@ -126,6 +141,12 @@ function buildImplementsAutoFix(context, comment, storyPaths) {
         reqIds,
     });
 }
+/**
+ * Analyze a block comment to detect legacy @story/@req usage, existing
+ * @supports lines, and the presence of multiple distinct @story paths.
+ *
+ * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-OPTIONAL-WARNING REQ-MULTI-STORY-DETECT
+ */
 function analyzeComment(comment) {
     const rawLines = (comment.value || "").split(/\r?\n/);
     let hasStory = false;
@@ -158,6 +179,13 @@ function hasMultipleStories(storyPaths) {
     // @req REQ-MULTI-STORY-DETECT - Use named threshold constant instead of a magic number
     return storyPaths.size > MULTI_STORY_THRESHOLD;
 }
+/**
+ * End-to-end processing for a single block comment: classify its
+ * traceability annotations, decide whether to report recommendations only
+ * or emit an auto-fix, and surface the appropriate message ID.
+ *
+ * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-OPTIONAL-WARNING REQ-MULTI-STORY-DETECT REQ-AUTO-FIX REQ-VALID-OUTPUT
+ */
 function processComment(comment, context) {
     const { hasStory, hasReq, hasImplements, storyPaths } = analyzeComment(comment);
     if (!hasStory || !hasReq) {