eslint-plugin-traceability 1.7.0 → 1.8.0

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

@@ -0,0 +1,39 @@
+/**
+ * ESLint rule implementation for preferring the consolidated `@implements`
+ * annotation over legacy combinations of `@story` and `@req` within JSDoc
+ * block comments. This module provides:
+ *
+ * - Detection of legacy `@story` + `@req` patterns.
+ * - 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.
+ *
+ * The rule is intended as an **optional migration aid** to help projects
+ * gradually move to the newer `@implements` 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
+ * @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
+ * @req REQ-VALID-OUTPUT - Avoid emitting auto-fixes for complex or ambiguous patterns
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
+ * @req REQ-AUTO-FIX - Provide safe, opt-in auto-fix for simple legacy patterns
+ */
+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
+ * is intended as an optional, opt-in migration aid.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.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
+ */
+declare const preferImplementsAnnotationRule: Rule.RuleModule;
+export default preferImplementsAnnotationRule;

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

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-format-internal");
+// Maximum number of distinct @story paths allowed before treating as "multi-story".
+// @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
+// @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.
+const MIN_REQ_TOKENS = MIN_STORY_TOKENS;
+// Length of the opening "/*" portion of a block comment prefix.
+const COMMENT_PREFIX_LENGTH = 2;
+function collectStoryAndReqMetadata(comment) {
+    const rawValue = comment.value || "";
+    const rawLines = rawValue.split(/\r?\n/);
+    const storyLineIndices = [];
+    const reqLineIndices = [];
+    const reqIds = [];
+    let storyPath = null;
+    rawLines.forEach((rawLine, index) => {
+        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
+            return;
+        }
+        if (/^@story\b/.test(normalized)) {
+            const parts = normalized.split(/\s+/);
+            if (parts.length === MIN_STORY_TOKENS) {
+                storyLineIndices.push(index);
+                storyPath = parts[1];
+            }
+            else {
+                storyPath = null;
+            }
+            return;
+        }
+        if (/^@req\b/.test(normalized)) {
+            const parts = normalized.split(/\s+/);
+            if (parts.length === MIN_REQ_TOKENS) {
+                reqLineIndices.push(index);
+                reqIds.push(parts[1]);
+            }
+            else {
+                // Complex @req form; bail out entirely.
+                storyPath = null;
+            }
+        }
+    });
+    return { storyLineIndices, reqLineIndices, reqIds, storyPath };
+}
+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(" ")}`;
+    // Determine the leading prefix (indentation and `*`) from the original @story line
+    const storyRawLine = rawLines[storyIdx];
+    const prefixMatch = storyRawLine.match(/^(\s*\*?\s*)/);
+    const linePrefix = prefixMatch ? prefixMatch[1] : "";
+    const implementsLine = `${linePrefix}${implAnnotation}`;
+    const fixedLines = [];
+    rawLines.forEach((line, index) => {
+        if (index === storyIdx) {
+            fixedLines.push(implementsLine);
+            return;
+        }
+        if (allIndicesToRemove.has(index)) {
+            return;
+        }
+        fixedLines.push(line);
+    });
+    const fixedValue = fixedLines.join("\n");
+    const sourceCode = context.getSourceCode();
+    return (fixer) => fixer.replaceTextRange([comment.range[0], comment.range[1]], sourceCode.text.slice(comment.range[0], comment.range[0] + COMMENT_PREFIX_LENGTH) +
+        fixedValue +
+        "*/");
+}
+/**
+ * Build an ESLint auto-fix for simple single-story `@story` + `@req` JSDoc
+ * blocks, converting them to a single `@implements` annotation while
+ * preserving the original comment formatting.
+ *
+ * The fixer is intentionally conservative and only activates when:
+ * - There is exactly one distinct `@story` path.
+ * - Exactly one `@story` line is present.
+ * - At least one `@req` line is present.
+ * - Each `@req` line has the simple form `@req <REQ-ID>` (no extra tokens).
+ *
+ * When applicable, the fix:
+ * - Removes the original `@story` and `@req` lines.
+ * - Inserts a single `@implements` 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
+ * @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
+ * @req REQ-VALID-OUTPUT - Avoid emitting auto-fixes for complex or ambiguous patterns
+ */
+function buildImplementsAutoFix(context, comment, storyPaths) {
+    if (storyPaths.size !== 1)
+        return null;
+    const { storyLineIndices, reqLineIndices, reqIds, storyPath } = collectStoryAndReqMetadata(comment);
+    if (storyPaths.size !== 1 ||
+        storyLineIndices.length !== 1 ||
+        reqLineIndices.length < 1 ||
+        storyPath === null) {
+        return null;
+    }
+    const storyIdx = storyLineIndices[0];
+    const allIndicesToRemove = new Set([
+        ...storyLineIndices,
+        ...reqLineIndices,
+    ]);
+    return applyImplementsReplacement(context, comment, {
+        storyIdx,
+        allIndicesToRemove,
+        storyPath,
+        reqIds,
+    });
+}
+function analyzeComment(comment) {
+    const rawLines = (comment.value || "").split(/\r?\n/);
+    let hasStory = false;
+    let hasReq = false;
+    let hasImplements = false;
+    const storyPaths = new Set();
+    rawLines.forEach((rawLine) => {
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(rawLine);
+        if (!normalized)
+            return;
+        if (/^@implements\b/.test(normalized)) {
+            hasImplements = true;
+            return;
+        }
+        if (/^@story\b/.test(normalized)) {
+            hasStory = true;
+            const parts = normalized.split(/\s+/);
+            if (parts.length >= MIN_STORY_TOKENS) {
+                storyPaths.add(parts[1]);
+            }
+            return;
+        }
+        if (/^@req\b/.test(normalized)) {
+            hasReq = true;
+        }
+    });
+    return { hasStory, hasReq, hasImplements, storyPaths };
+}
+function hasMultipleStories(storyPaths) {
+    // @req REQ-MULTI-STORY-DETECT - Use named threshold constant instead of a magic number
+    return storyPaths.size > MULTI_STORY_THRESHOLD;
+}
+function processComment(comment, context) {
+    const { hasStory, hasReq, hasImplements, storyPaths } = analyzeComment(comment);
+    if (!hasStory || !hasReq) {
+        return;
+    }
+    if (hasImplements) {
+        context.report({
+            node: comment,
+            messageId: "cannotAutoFix",
+            data: {
+                reason: "comment mixes @story/@req with existing @implements annotations",
+            },
+        });
+        return;
+    }
+    if (hasMultipleStories(storyPaths)) {
+        context.report({
+            node: comment,
+            messageId: "multiStoryDetected",
+        });
+        return;
+    }
+    const fix = buildImplementsAutoFix(context, comment, storyPaths);
+    context.report({
+        node: comment,
+        messageId: "preferImplements",
+        fix: fix ?? undefined,
+    });
+}
+/**
+ * ESLint rule: prefer-implements-annotation
+ *
+ * Recommend migrating from legacy `@story` + `@req` annotations to the
+ * newer `@implements` 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
+ * @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
+ */
+const preferImplementsAnnotationRule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Recommend using @implements 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
+        // a recommendation-only warning with no code modifications.
+        fixable: "code",
+        messages: {
+            /**
+             * Recommend migrating simple, single-story @story + @req blocks to a
+             * single @implements line. Auto-fix is provided where safe in a
+             * follow-up iteration.
+             *
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @req REQ-OPTIONAL-WARNING
+             */
+            preferImplements: "Consider using @implements 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
+             * @req REQ-MULTI-STORY-DETECT
+             */
+            cannotAutoFix: "Cannot auto-fix: {{reason}}. Manual migration to @implements 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
+             * @req REQ-MULTI-STORY-DETECT
+             */
+            multiStoryDetected: "Multiple @story annotations detected in the same comment block. Manually convert to separate @implements lines.",
+        },
+        schema: [],
+    },
+    /**
+     * Rule entrypoint.
+     *
+     * This initial implementation focuses on **detection and messaging only**:
+     * 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
+     * @req REQ-OPTIONAL-WARNING
+     * @req REQ-MULTI-STORY-DETECT
+     */
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        return {
+            /**
+             * 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
+             * @req REQ-OPTIONAL-WARNING - Emit recommendations when legacy annotations are detected
+             * @req REQ-MULTI-STORY-DETECT - Detect multi-story and mixed annotation patterns
+             */
+            Program() {
+                const comments = sourceCode.getAllComments() || [];
+                comments
+                    .filter((comment) => comment.type === "Block")
+                    .forEach((comment) => {
+                    processComment(comment, context);
+                });
+            },
+        };
+    },
+};
+exports.default = preferImplementsAnnotationRule;

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

@@ -2,34 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const valid_annotation_options_1 = require("./helpers/valid-annotation-options");
 const valid_annotation_utils_1 = require("./helpers/valid-annotation-utils");
-/**
- * Normalize a raw comment line to make annotation parsing more robust.
- *
- * This function trims whitespace, keeps any annotation tags that appear
- * later in the line, and supports common JSDoc styles such as leading "*".
- *
- * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
- * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- */
-function normalizeCommentLine(rawLine) {
-    const trimmed = rawLine.trim();
-    if (!trimmed) {
-        return "";
-    }
-    const annotationMatch = trimmed.match(/@story\b|@req\b/);
-    if (!annotationMatch || annotationMatch.index === undefined) {
-        const withoutLeadingStar = trimmed.replace(/^\*\s?/, "");
-        return withoutLeadingStar;
-    }
-    return trimmed.slice(annotationMatch.index);
-}
+const valid_implements_utils_1 = require("./helpers/valid-implements-utils");
+const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-format-internal");
 /**
  * Report an invalid @story annotation without applying a fix.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 function reportInvalidStoryFormat(context, comment, collapsed, options) {
@@ -91,6 +71,7 @@ function createStoryFix(context, comment, fixed) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and avoid changing semantics
@@ -117,11 +98,13 @@ function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
  * @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
  * @req REQ-REGEX-VALIDATION - Validate configurable story regex patterns and fall back safely
  * @req REQ-BACKWARD-COMP - Preserve behavior when invalid regex config is supplied
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 function validateStoryAnnotation(context, comment, rawValue, options) {
     const trimmed = rawValue.trim();
@@ -154,10 +137,12 @@ function validateStoryAnnotation(context, comment, rawValue, 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.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
  * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
  * @req REQ-REGEX-VALIDATION - Validate configurable requirement regex patterns and fall back safely
  * @req REQ-BACKWARD-COMP - Preserve behavior when invalid regex config is supplied
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 function validateReqAnnotation(context, comment, rawValue, options) {
     const trimmed = rawValue.trim();
@@ -179,13 +164,47 @@ function validateReqAnnotation(context, comment, rawValue, options) {
         });
     }
 }
+/**
+ * Validate an @implements annotation value and report detailed errors when needed.
+ *
+ * Expected format:
+ *   @implements <storyPath> <REQ-ID> [<REQ-ID> ...]
+ *
+ * Validation rules:
+ *   - Value must include at least a story path and one requirement ID.
+ *   - Story path must match the same storyPattern used for @story (no auto-fix).
+ *   - Each subsequent token must match reqPattern and is validated individually.
+ *
+ * Story path issues are reported with "invalidImplementsFormat" and
+ * requirement ID issues reuse the existing "invalidReqFormat" message.
+ *
+ * @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
+ */
+function validateImplementsAnnotation(context, comment, rawValue, options) {
+    const deps = {
+        MIN_IMPLEMENTS_TOKENS: valid_implements_utils_1.MIN_IMPLEMENTS_TOKENS,
+        reportMissingImplementsReqIds: valid_implements_utils_1.reportMissingImplementsReqIds,
+        reportMissingImplementsValue: valid_implements_utils_1.reportMissingImplementsValue,
+        reportInvalidImplementsReqId: valid_implements_utils_1.reportInvalidImplementsReqId,
+        reportInvalidImplementsStoryPath: valid_implements_utils_1.reportInvalidImplementsStoryPath,
+    };
+    (0, valid_implements_utils_1.validateImplementsAnnotationHelper)(deps, context, comment, {
+        rawValue,
+        options,
+    });
+}
 /**
  * Finalize and validate the currently pending annotation, if any.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 function finalizePendingAnnotation(context, comment, options, pending) {
     if (!pending) {
@@ -193,8 +212,10 @@ function finalizePendingAnnotation(context, comment, options, pending) {
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
     // @req REQ-SYNTAX-VALIDATION - Dispatch validation based on annotation type
     // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+    // @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
     if (pending.type === "story") {
         validateStoryAnnotation(context, comment, pending.value, options);
     }
@@ -208,9 +229,13 @@ function finalizePendingAnnotation(context, comment, options, pending) {
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-SYNTAX-VALIDATION - Start new pending annotation when a tag is found
  * @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @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
  */
 function processCommentLine({ normalized, pending, context, comment, options, }) {
     if (!normalized) {
@@ -218,10 +243,19 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     }
     const isStory = /@story\b/.test(normalized);
     const isReq = /@req\b/.test(normalized);
+    const isImplements = /@implements\b/.test(normalized);
+    // Handle @implements as an immediate, single-line annotation
+    if (isImplements) {
+        const implementsValue = normalized.replace(/^@implements\b/, "").trim();
+        validateImplementsAnnotation(context, comment, implementsValue, options);
+        return pending;
+    }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
     // @req REQ-SYNTAX-VALIDATION - Start new pending annotation when a tag is found
     // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+    // @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
     if (isStory || isReq) {
         finalizePendingAnnotation(context, comment, options, pending);
         const value = normalized.replace(/^@story\b|^@req\b/, "").trim();
@@ -233,8 +267,10 @@ function processCommentLine({ normalized, pending, context, comment, 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.2-DEV-MULTI-STORY-SUPPORT.story.md
     // @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
     // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+    // @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
     if (pending) {
         const continuation = normalized.trim();
         if (!continuation) {
@@ -252,23 +288,30 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     return pending;
 }
 /**
- * Process a single comment node and validate any @story/@req annotations it contains.
+ * Process a single comment node and validate any @story/@req/@implements annotations it contains.
  *
- * Supports annotations whose values span multiple lines within the same
+ * Supports @story and @req annotations whose values span multiple lines within the same
  * comment block, collapsing whitespace so that the logical value can be
  * validated against the configured patterns.
  *
+ * @implements annotations are validated immediately per-line and are not
+ * accumulated into pending multi-line state.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
  * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @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
  */
 function processComment(context, comment, options) {
     const rawLines = (comment.value || "").split(/\r?\n/);
     let pending = null;
     rawLines.forEach((rawLine) => {
-        const normalized = normalizeCommentLine(rawLine);
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(rawLine);
         pending = processCommentLine({
             normalized,
             pending,
@@ -283,7 +326,7 @@ exports.default = {
     meta: {
         type: "problem",
         docs: {
-            description: "Validate format and syntax of @story and @req annotations",
+            description: "Validate format and syntax of @story, @req, and @implements annotations",
             recommended: "error",
         },
         messages: {
@@ -301,6 +344,14 @@ exports.default = {
              * @req REQ-ERROR-CONSISTENCY - Use shared "Invalid annotation format: {{details}}." message pattern across rules
              */
             invalidReqFormat: "Invalid annotation format: {{details}}.",
+            /**
+             * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+             * @req REQ-ERROR-SPECIFIC - Provide specific details about invalid @implements annotation format
+             * @req REQ-ERROR-CONTEXT - Include human-readable details about the expected @implements annotation format
+             * @req REQ-ERROR-CONSISTENCY - Use shared "Invalid annotation format: {{details}}." message pattern across rules
+             * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
+             */
+            invalidImplementsFormat: "Invalid annotation format: {{details}}.",
             /**
              * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
              * @req REQ-REGEX-VALIDATION - Surface configuration errors for invalid regex patterns
@@ -326,11 +377,15 @@ exports.default = {
      * @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-DEV-CONFIGURABLE-PATTERNS.story.md
+     * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
      * @req REQ-SYNTAX-VALIDATION - Ensure rule create function validates annotations syntax
      * @req REQ-FORMAT-SPECIFICATION - Implement formatting checks per specification
      * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
      * @req REQ-REGEX-VALIDATION - Derive validation regexes from shared options helper
      * @req REQ-BACKWARD-COMP - Fall back to default patterns and continue validation on config errors
+     * @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
      */
     create(context) {
         const sourceCode = context.getSourceCode();
@@ -338,16 +393,20 @@ exports.default = {
         const optionErrors = (0, valid_annotation_options_1.getOptionErrors)();
         return {
             /**
-             * Program-level handler that inspects all comments for @story and @req tags
+             * Program-level handler that inspects all comments for @story, @req, and @implements tags
              *
              * @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-DEV-CONFIGURABLE-PATTERNS.story.md
+             * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
              * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
              * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
              * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
              * @req REQ-REGEX-VALIDATION - Surface regex configuration errors without blocking validation
              * @req REQ-BACKWARD-COMP - Continue validating comments using default patterns on error
+             * @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
              */
             Program(node) {
                 if (optionErrors && optionErrors.length > 0) {