eslint-plugin-traceability 1.8.1 → 1.8.2

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

@@ -39,6 +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
     return value.replace(/\s+/g, "");
 }
 /**
@@ -51,29 +52,52 @@ function collapseAnnotationValue(value) {
  *
  * Returns the fixed path when safe, or null if no fix should be applied.
  *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
+ * @story docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and never broaden the referenced path
  * @req REQ-AUTOFIX-PRESERVE - Preserve surrounding formatting when normalizing story path suffixes
  */
 function getFixedStoryPath(original) {
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-SAFE - Skip auto-fix entirely for paths containing directory traversal segments ("..").
+    // @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.
     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
         return null;
     }
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT - Do not modify paths that already end with ".story.md" since they are already in the correct format.
+    // @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.
     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
         return null;
     }
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE - Append the missing ".md" extension when the path already ends with ".story", preserving the existing base path.
+    // @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".
     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
         return `${original}.md`;
     }
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE - Upgrade plain ".md" paths to ".story.md" while preserving the rest of the path unchanged.
+    // @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.
     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
         return original.replace(/\.md$/, ".story.md");
     }
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE REQ-AUTOFIX-SAFE - For paths with no extension, conservatively append ".story.md" to create a canonical story file path.
+    // @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
     return `${original}.story.md`;
 }
 /**
@@ -81,14 +105,21 @@ function getFixedStoryPath(original) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 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.
     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
         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
     return `Invalid story path "${value ?? ""}" for @story annotation. Expected a path like "${example}".`;
 }
 /**
@@ -96,13 +127,20 @@ function buildStoryErrorMessage(kind, value, options) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 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.
     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
         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
     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-implements-utils.d.ts

@@ -1,23 +1,23 @@
 /**
- * Helpers for @implements annotation validation used by valid-annotation-format.
+ * Helpers for @supports annotation validation used by valid-annotation-format.
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
- * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
- * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ * @req REQ-SUPPORTS-PARSE - Parse @supports annotations without affecting @story/@req
+ * @req REQ-FORMAT-VALIDATION - Validate @supports story path and requirement IDs
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@supports usage in comments
  */
 import type { ResolvedAnnotationOptions } from "./valid-annotation-options";
 /**
- * Minimum number of tokens required for a valid @implements value:
+ * Minimum number of tokens required for a valid @supports value:
  *   - one story path
  *   - at least one requirement ID
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-PARSE
+ * @req REQ-SUPPORTS-PARSE
  */
 export declare const MIN_IMPLEMENTS_TOKENS = 2;
 /**
- * Report a completely missing @implements value (no story path or req IDs).
+ * Report a completely missing @supports value (no story path or req IDs).
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-FORMAT-VALIDATION
@@ -31,14 +31,14 @@ export declare function reportMissingImplementsValue(context: any, comment: any,
  */
 export declare function reportMissingImplementsReqIds(context: any, comment: any, options: ResolvedAnnotationOptions): void;
 /**
- * Report an invalid story path inside @implements.
+ * Report an invalid story path inside @supports.
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-FORMAT-VALIDATION
  */
 export declare function reportInvalidImplementsStoryPath(context: any, comment: any, storyPath: string, options: ResolvedAnnotationOptions): void;
 /**
- * Report an invalid requirement ID token inside @implements.
+ * Report an invalid requirement ID token inside @supports.
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-FORMAT-VALIDATION
@@ -53,7 +53,7 @@ type ImplementsDeps = {
     reportInvalidImplementsReqId: typeof reportInvalidImplementsReqId;
 };
 /**
- * Validate an @implements annotation value.
+ * Validate an @supports annotation value.
  *
  * This helper encapsulates the logic previously in valid-annotation-format.ts:
  *   - trims the raw value
@@ -64,7 +64,7 @@ type ImplementsDeps = {
  *   - delegates reporting to the provided helpers
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-PARSE
+ * @req REQ-SUPPORTS-PARSE
  * @req REQ-FORMAT-VALIDATION
  * @req REQ-MIXED-SUPPORT
  */

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

@@ -8,16 +8,16 @@ exports.reportInvalidImplementsReqId = reportInvalidImplementsReqId;
 exports.validateImplementsAnnotationHelper = validateImplementsAnnotationHelper;
 const valid_annotation_utils_1 = require("./valid-annotation-utils");
 /**
- * Minimum number of tokens required for a valid @implements value:
+ * Minimum number of tokens required for a valid @supports value:
  *   - one story path
  *   - at least one requirement ID
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-PARSE
+ * @req REQ-SUPPORTS-PARSE
  */
 exports.MIN_IMPLEMENTS_TOKENS = 2;
 /**
- * Report a completely missing @implements value (no story path or req IDs).
+ * Report a completely missing @supports value (no story path or req IDs).
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-FORMAT-VALIDATION
@@ -28,7 +28,7 @@ function reportMissingImplementsValue(context, comment, options) {
         node: comment,
         messageId: "invalidImplementsFormat",
         data: {
-            details: `Missing story path and requirement IDs for @implements annotation. Expected a value like "${storyExample} ${reqExample}".`,
+            details: `Missing story path and requirement IDs for @supports annotation. Expected a value like "${storyExample} ${reqExample}".`,
         },
     });
 }
@@ -44,12 +44,12 @@ function reportMissingImplementsReqIds(context, comment, options) {
         node: comment,
         messageId: "invalidImplementsFormat",
         data: {
-            details: `Missing requirement IDs for @implements annotation. Expected a value like "${storyExample} ${reqExample}".`,
+            details: `Missing requirement IDs for @supports annotation. Expected a value like "${storyExample} ${reqExample}".`,
         },
     });
 }
 /**
- * Report an invalid story path inside @implements.
+ * Report an invalid story path inside @supports.
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-FORMAT-VALIDATION
@@ -60,12 +60,12 @@ function reportInvalidImplementsStoryPath(context, comment, storyPath, options)
         node: comment,
         messageId: "invalidImplementsFormat",
         data: {
-            details: `Invalid story path "${storyPath}" for @implements annotation. Expected a path like "${storyExample}".`,
+            details: `Invalid story path "${storyPath}" for @supports annotation. Expected a path like "${storyExample}".`,
         },
     });
 }
 /**
- * Report an invalid requirement ID token inside @implements.
+ * Report an invalid requirement ID token inside @supports.
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-FORMAT-VALIDATION
@@ -81,7 +81,7 @@ function reportInvalidImplementsReqId(context, comment, reqId, options) {
     });
 }
 /**
- * Prepare and validate the token array for an @implements value.
+ * Prepare and validate the token array for an @supports value.
  *
  * Returns { storyPath, reqIds } when tokens are present and structurally valid,
  * or null when a missing-value condition has been reported.
@@ -121,7 +121,7 @@ function validateImplementsTokens(deps, context, comment, rest) {
     }
 }
 /**
- * Validate an @implements annotation value.
+ * Validate an @supports annotation value.
  *
  * This helper encapsulates the logic previously in valid-annotation-format.ts:
  *   - trims the raw value
@@ -132,7 +132,7 @@ function validateImplementsTokens(deps, context, comment, rest) {
  *   - delegates reporting to the provided helpers
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-PARSE
+ * @req REQ-SUPPORTS-PARSE
  * @req REQ-FORMAT-VALIDATION
  * @req REQ-MIXED-SUPPORT
  */

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

@@ -20,11 +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
         const boundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(candidate, cwd);
         if (boundary.isWithinProject) {
+            // @implements 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
             hasOutOfProjectCandidate = true;
         }
     }
@@ -44,8 +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
         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
             reportInvalidPath({ storyPath, commentNode, context });
             return true;
         }
@@ -53,8 +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
         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
             reportInvalidPath({ storyPath, commentNode, context });
             return true;
         }
@@ -72,7 +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
         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
             reportInvalidPath({ storyPath, commentNode, context });
             return false;
         }
@@ -82,8 +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
         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
             reportInvalidPath({ storyPath, commentNode, context });
             return false;
         }

package/lib/src/rules/prefer-implements-annotation.d.ts

@@ -1,5 +1,5 @@
 /**
- * ESLint rule implementation for preferring the consolidated `@implements`
+ * ESLint rule implementation for preferring the consolidated `@supports`
  * annotation over legacy combinations of `@story` and `@req` within JSDoc
  * block comments. This module provides:
  *
@@ -7,14 +7,14 @@
  * - Identification of multi-story comment blocks that are not safely
  *   auto-fixable.
  * - A conservative auto-fix that rewrites simple, single-story patterns into
- *   a single `@implements` annotation while preserving formatting.
+ *   a single `@supports` annotation while preserving formatting.
  *
  * The rule is intended as an **optional migration aid** to help projects
- * gradually move to the newer `@implements` format without breaking existing
+ * gradually move to the newer `@supports` format without breaking existing
  * traceability links.
  *
- * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
- * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage in favor of @supports
  * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
  * @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
@@ -27,10 +27,10 @@ import type { Rule } from "eslint";
  * ESLint rule: prefer-implements-annotation
  *
  * Recommend migrating from legacy `@story` + `@req` annotations to the
- * newer `@implements` format. This rule is **disabled by default** and
+ * newer `@supports` format. This rule is **disabled by default** and
  * is intended as an optional, opt-in migration aid.
  *
- * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
  * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
  * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
  * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled

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

@@ -5,7 +5,7 @@ const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-f
 // @req REQ-MULTI-STORY-DETECT - Centralized threshold constant for detecting multi-story patterns
 const MULTI_STORY_THRESHOLD = 1;
 // Minimum number of tokens required for a valid @story annotation line.
-// @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+// @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
 // @req REQ-MULTI-STORY-DETECT
 const MIN_STORY_TOKENS = 2;
 // Minimum number of tokens required for a valid @req annotation line, aligned with story tokens.
@@ -23,8 +23,8 @@ function collectStoryAndReqMetadata(comment) {
         const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(rawLine);
         if (!normalized)
             return;
-        if (/^@implements\b/.test(normalized)) {
-            // Mixed @implements usage should have been filtered out earlier
+        if (/^@supports\b/.test(normalized)) {
+            // Mixed @supports usage should have been filtered out earlier
             return;
         }
         if (/^@story\b/.test(normalized)) {
@@ -56,7 +56,7 @@ function applyImplementsReplacement(context, comment, details) {
     const { storyIdx, allIndicesToRemove, storyPath, reqIds } = details;
     const rawValue = comment.value || "";
     const rawLines = rawValue.split(/\r?\n/);
-    const implAnnotation = `@implements ${storyPath} ${reqIds.join(" ")}`;
+    const implAnnotation = `@supports ${storyPath} ${reqIds.join(" ")}`;
     // Determine the leading prefix (indentation and `*`) from the original @story line
     const storyRawLine = rawLines[storyIdx];
     const prefixMatch = storyRawLine.match(/^(\s*\*?\s*)/);
@@ -81,7 +81,7 @@ function applyImplementsReplacement(context, comment, details) {
 }
 /**
  * Build an ESLint auto-fix for simple single-story `@story` + `@req` JSDoc
- * blocks, converting them to a single `@implements` annotation while
+ * blocks, converting them to a single `@supports` annotation while
  * preserving the original comment formatting.
  *
  * The fixer is intentionally conservative and only activates when:
@@ -92,13 +92,13 @@ function applyImplementsReplacement(context, comment, details) {
  *
  * When applicable, the fix:
  * - Removes the original `@story` and `@req` lines.
- * - Inserts a single `@implements` line in their place, preserving the
+ * - Inserts a single `@supports` line in their place, preserving the
  *   original leading comment prefix (indentation and `*` markers).
  *
  * More complex patterns remain diagnostics-only with no fix to avoid
  * producing invalid or ambiguous output.
  *
- * @implements docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @implements 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
@@ -136,7 +136,7 @@ function analyzeComment(comment) {
         const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(rawLine);
         if (!normalized)
             return;
-        if (/^@implements\b/.test(normalized)) {
+        if (/^@supports\b/.test(normalized)) {
             hasImplements = true;
             return;
         }
@@ -168,7 +168,7 @@ function processComment(comment, context) {
             node: comment,
             messageId: "cannotAutoFix",
             data: {
-                reason: "comment mixes @story/@req with existing @implements annotations",
+                reason: "comment mixes @story/@req with existing @supports annotations",
             },
         });
         return;
@@ -191,10 +191,10 @@ function processComment(comment, context) {
  * ESLint rule: prefer-implements-annotation
  *
  * Recommend migrating from legacy `@story` + `@req` annotations to the
- * newer `@implements` format. This rule is **disabled by default** and
+ * newer `@supports` format. This rule is **disabled by default** and
  * is intended as an optional, opt-in migration aid.
  *
- * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
  * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
  * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
  * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
@@ -203,7 +203,7 @@ const preferImplementsAnnotationRule = {
     meta: {
         type: "suggestion",
         docs: {
-            description: "Recommend using @implements instead of legacy @story + @req annotations (optional migration rule)",
+            description: "Recommend using @supports instead of legacy @story + @req annotations (optional migration rule)",
             recommended: false,
         },
         // Auto-fix support will be wired in a later iteration; the rule starts as
@@ -212,31 +212,31 @@ const preferImplementsAnnotationRule = {
         messages: {
             /**
              * Recommend migrating simple, single-story @story + @req blocks to a
-             * single @implements line. Auto-fix is provided where safe in a
+             * single @supports line. Auto-fix is provided where safe in a
              * follow-up iteration.
              *
-             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
              * @req REQ-OPTIONAL-WARNING
              */
-            preferImplements: "Consider using @implements instead of @story + @req for clearer traceability. Run ESLint with --fix to auto-convert.",
+            preferImplements: "Consider using @supports instead of @story + @req for clearer traceability. Run ESLint with --fix to auto-convert.",
             /**
              * Report situations where the rule detects a legacy annotation pattern
              * but cannot safely provide an automatic fix. The `reason` field gives
              * a short, human-readable explanation to guide manual migration.
              *
-             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
              * @req REQ-MULTI-STORY-DETECT
              */
-            cannotAutoFix: "Cannot auto-fix: {{reason}}. Manual migration to @implements required.",
+            cannotAutoFix: "Cannot auto-fix: {{reason}}. Manual migration to @supports required.",
             /**
              * Specialized message for the most common non-fixable case where more
              * than one @story annotation appears in the same block, indicating a
              * likely multi-story integration that must be converted manually.
              *
-             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
              * @req REQ-MULTI-STORY-DETECT
              */
-            multiStoryDetected: "Multiple @story annotations detected in the same comment block. Manually convert to separate @implements lines.",
+            multiStoryDetected: "Multiple @story annotations detected in the same comment block. Manually convert to separate @supports lines.",
         },
         schema: [],
     },
@@ -247,7 +247,7 @@ const preferImplementsAnnotationRule = {
      * it surfaces recommendations when legacy `@story` + `@req` combinations are
      * present but does not yet perform automatic code modifications.
      *
-     * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+     * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
      * @req REQ-OPTIONAL-WARNING
      * @req REQ-MULTI-STORY-DETECT
      */
@@ -258,7 +258,7 @@ const preferImplementsAnnotationRule = {
              * Program-level visitor that scans all comments for legacy
              * `@story` + `@req` usage and emits recommendation diagnostics.
              *
-             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
              * @req REQ-OPTIONAL-WARNING - Emit recommendations when legacy annotations are detected
              * @req REQ-MULTI-STORY-DETECT - Detect multi-story and mixed annotation patterns
              */