eslint-plugin-traceability 1.7.0 → 1.8.0

package/lib/src/rules/valid-req-reference.js

@@ -14,6 +14,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+/**
+ * Token index configuration for @implements annotations.
+ * This clarifies the expected positions of the story path and first requirement ID
+ * and avoids hard-coded "magic number" indices in parsing logic.
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ */
+const IMPLEMENTS_TOKENS = {
+    STORY_INDEX: 1,
+    FIRST_REQ_INDEX: 2,
+};
 /**
  * Extract the story path from a JSDoc comment.
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
@@ -164,11 +174,68 @@ function validateReqLine(opts) {
         reqSet,
     });
 }
+/**
+ * Parse an @implements annotation line into its story path and requirement IDs.
+ * Expects the format: "@implements <storyPath> <REQ-ID-1> <REQ-ID-2> ..."
+ * Invalid formats (missing storyPath or reqIds) are ignored by this deep rule.
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-VALIDATE - Support validation of @implements annotations
+ * @req REQ-MIXED-SUPPORT - Allow mixed @story/@req/@implements usage in the same comment
+ * @req REQ-SCOPED-IDS - Treat requirement IDs as scoped to the referenced story file
+ */
+function parseImplementsLine(line) {
+    const parts = line.split(/\s+/);
+    const storyPath = parts[IMPLEMENTS_TOKENS.STORY_INDEX];
+    const reqIds = parts.slice(IMPLEMENTS_TOKENS.FIRST_REQ_INDEX);
+    if (!storyPath || reqIds.length === 0) {
+        return null;
+    }
+    return { storyPath, reqIds };
+}
+/**
+ * Validate an @implements annotation line against the referenced story content.
+ * Performs path validation, file reading, caching, and requirement existence checks
+ * for each requirement ID listed on the line.
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-VALIDATE - Validate that all @implements requirement IDs exist
+ * @req REQ-MIXED-SUPPORT - Ensure @implements can coexist with @story/@req annotations
+ * @req REQ-SCOPED-IDS - Validate requirement IDs in the scope of their explicit story
+ */
+function validateImplementsLine(opts) {
+    const { comment, context, line, cwd, reqCache } = opts;
+    const parsed = parseImplementsLine(line);
+    if (!parsed) {
+        return;
+    }
+    const { storyPath, reqIds } = parsed;
+    const { reqSet } = resolveStoryAndRequirements({
+        comment,
+        context,
+        storyPath,
+        cwd,
+        reqCache,
+    });
+    if (!reqSet) {
+        return;
+    }
+    for (const reqId of reqIds) {
+        checkRequirementExists({
+            comment,
+            context,
+            reqId,
+            storyPath,
+            reqSet,
+        });
+    }
+}
 /**
  * Handle a single annotation line for story or requirement metadata.
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
  * @req REQ-DEEP-PARSE - Parse annotation lines for @story and @req tags
  * @req REQ-DEEP-MATCH - Dispatch @req lines for validation against story requirements
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-VALIDATE - Dispatch @implements lines for validation
+ * @req REQ-MIXED-SUPPORT - Support mixed annotation types without interfering with each other
  */
 function handleAnnotationLine(opts) {
     const { line, comment, context, cwd, reqCache, storyPath } = opts;
@@ -180,6 +247,10 @@ function handleAnnotationLine(opts) {
         validateReqLine({ comment, context, line, storyPath, cwd, reqCache });
         return storyPath;
     }
+    else if (line.startsWith("@implements")) {
+        validateImplementsLine({ comment, context, line, cwd, reqCache });
+        return storyPath;
+    }
     return storyPath;
 }
 /**

package/lib/src/utils/reqAnnotationDetection.d.ts

@@ -1,6 +1,9 @@
 /**
- * Helper to determine whether a JSDoc or any nearby comments contain a @req annotation.
+ * Helper to determine whether a JSDoc or any nearby comments contain a requirement annotation.
+ * Treats both @req and @implements annotations as evidence of requirement coverage.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements as requirement coverage
  */
 export declare function hasReqAnnotation(jsdoc: any, comments: any[], context?: any, node?: any): boolean;

package/lib/src/utils/reqAnnotationDetection.js

@@ -8,17 +8,24 @@ exports.hasReqAnnotation = hasReqAnnotation;
  */
 const require_story_io_1 = require("../rules/helpers/require-story-io");
 /**
- * Predicate helper to check whether a comment contains a @req annotation.
+ * Predicate helper to check whether a comment contains a requirement annotation.
+ * Treats both @req and @implements annotations as satisfying requirement presence checks.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req tag inside a comment
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements as requirement annotation
  */
 function commentContainsReq(c) {
-    return c && typeof c.value === "string" && c.value.includes("@req");
+    return (c &&
+        typeof c.value === "string" &&
+        (c.value.includes("@req") || c.value.includes("@implements")));
 }
 /**
- * Line-based helper adapted from linesBeforeHasStory to detect @req.
+ * Line-based helper adapted from linesBeforeHasStory to detect requirement annotations.
+ * Lines containing either @req or @implements are treated as annotated.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req in preceding source lines
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements in preceding source lines
  */
 function linesBeforeHasReq(sourceCode, node) {
     const lines = sourceCode && sourceCode.lines;
@@ -33,44 +40,53 @@ function linesBeforeHasReq(sourceCode, node) {
     }
     const from = Math.max(0, startLine - 1 - require_story_io_1.LOOKBACK_LINES);
     const to = Math.max(0, startLine - 1);
-    // Scan each physical line in the configured lookback window for an @req marker.
+    // Scan each physical line in the configured lookback window for @req or @implements markers.
     // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
     // @req REQ-ANNOTATION-REQ-DETECTION - Search preceding lines for @req text
+    // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Search preceding lines for @implements text
     for (let i = from; i < to; i++) {
         const text = lines[i];
-        // When a line contains @req we treat the function as already annotated.
+        // When a line contains @req or @implements we treat the function as already annotated.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req marker in raw source lines
-        if (typeof text === "string" && text.includes("@req")) {
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @implements marker in raw source lines
+        if (typeof text === "string" &&
+            (text.includes("@req") || text.includes("@implements"))) {
             return true;
         }
     }
     return false;
 }
 /**
- * Parent-chain helper adapted from parentChainHasStory to detect @req.
+ * Parent-chain helper adapted from parentChainHasStory to detect requirement annotations.
+ * Accepts both @req and @implements in parent-chain comments as satisfying requirement presence.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req in parent-chain comments
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements in parent-chain comments
  */
 function parentChainHasReq(sourceCode, node) {
     let p = node && node.parent;
     // Walk up the parent chain and inspect comments attached to each ancestor.
+    // Accept both @req and @implements markers when local comments are absent.
     // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
     // @req REQ-ANNOTATION-REQ-DETECTION - Traverse parent nodes when local comments are absent
+    // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Allow @implements to satisfy requirement on parents
     while (p) {
         const pComments = typeof sourceCode?.getCommentsBefore === "function"
             ? sourceCode.getCommentsBefore(p) || []
             : [];
-        // Look for @req in comments immediately preceding each parent node.
+        // Look for @req or @implements in comments immediately preceding each parent node.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req markers in parent comments
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @implements markers in parent comments
         if (Array.isArray(pComments) && pComments.some(commentContainsReq)) {
             return true;
         }
         const pLeading = p.leadingComments || [];
-        // Also inspect leadingComments attached directly to the parent node.
+        // Also inspect leadingComments attached directly to the parent node, accepting @req or @implements.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req markers in parent leadingComments
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @implements markers in parent leadingComments
         if (Array.isArray(pLeading) && pLeading.some(commentContainsReq)) {
             return true;
         }
@@ -79,9 +95,12 @@ function parentChainHasReq(sourceCode, node) {
     return false;
 }
 /**
- * Fallback text window helper adapted from fallbackTextBeforeHasStory to detect @req.
+ * Fallback text window helper adapted from fallbackTextBeforeHasStory to detect requirement annotations.
+ * Treats both @req and @implements in the fallback text window as requirement presence.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req in fallback text window before node
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements in fallback text window before node
  */
 function fallbackTextBeforeHasReq(sourceCode, node) {
     // Guard against unsupported sourceCode or nodes without a usable range.
@@ -101,10 +120,13 @@ function fallbackTextBeforeHasReq(sourceCode, node) {
     try {
         const start = Math.max(0, range[0] - require_story_io_1.FALLBACK_WINDOW);
         const textBefore = sourceCode.getText().slice(start, range[0]);
-        // Detect @req in the bounded text window immediately preceding the node.
+        // Detect @req or @implements in the bounded text window immediately preceding the node.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+        // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req marker in fallback text window
-        if (typeof textBefore === "string" && textBefore.includes("@req")) {
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @implements marker in fallback text window
+        if (typeof textBefore === "string" &&
+            (textBefore.includes("@req") || textBefore.includes("@implements"))) {
             return true;
         }
     }
@@ -117,9 +139,12 @@ function fallbackTextBeforeHasReq(sourceCode, node) {
     return false;
 }
 /**
- * Helper to determine whether a JSDoc or any nearby comments contain a @req annotation.
+ * Helper to determine whether a JSDoc or any nearby comments contain a requirement annotation.
+ * Treats both @req and @implements annotations as evidence of requirement coverage.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements as requirement coverage
  */
 function hasReqAnnotation(jsdoc, comments, context, node) {
     try {
@@ -129,6 +154,7 @@ function hasReqAnnotation(jsdoc, comments, context, node) {
         // Prefer robust, location-based heuristics when sourceCode and node are available.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Use multiple heuristics to detect @req markers around the node
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Use multiple heuristics to detect @implements markers around the node
         if (sourceCode && node) {
             if (linesBeforeHasReq(sourceCode, node) ||
                 parentChainHasReq(sourceCode, node) ||
@@ -142,11 +168,13 @@ function hasReqAnnotation(jsdoc, comments, context, node) {
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Fail gracefully when advanced detection heuristics throw
     }
-    // BRANCH @req detection on JSDoc or comments
+    // BRANCH requirement detection on JSDoc or comments, accepting both @req and @implements.
     // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
     // @req REQ-ANNOTATION-REQ-DETECTION
+    // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS
     return ((jsdoc &&
         typeof jsdoc.value === "string" &&
-        jsdoc.value.includes("@req")) ||
+        (jsdoc.value.includes("@req") || jsdoc.value.includes("@implements"))) ||
         comments.some(commentContainsReq));
 }

package/lib/tests/maintenance/cli.test.js

@@ -145,6 +145,31 @@ describe("Maintenance CLI (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
             fs_1.default.rmSync(dir, { recursive: true, force: true });
         }
     });
+    it("[REQ-MAINT-SAFE] report exits 2 and prints error on invalid --format value", () => {
+        const dir = withTempDir();
+        process.chdir(dir);
+        const errorSpy = jest.spyOn(console, "error").mockImplementation(() => { });
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const code = (0, cli_1.runMaintenanceCli)([
+            "node",
+            "traceability-maint",
+            "report",
+            "--format",
+            "yaml",
+        ]);
+        try {
+            expect(code).toBe(2);
+            expect(errorSpy).toHaveBeenCalledTimes(1);
+            const message = String(errorSpy.mock.calls[0][0]);
+            expect(message).toContain("Invalid format: yaml");
+            expect(message).toContain("Expected 'text' or 'json'");
+        }
+        finally {
+            errorSpy.mockRestore();
+            logSpy.mockRestore();
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+        }
+    });
     it("[REQ-MAINT-DETECT] detect supports --json output", () => {
         const dir = withTempDir();
         process.chdir(dir);
@@ -169,4 +194,68 @@ describe("Maintenance CLI (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
             fs_1.default.rmSync(dir, { recursive: true, force: true });
         }
     });
+    it("[REQ-MAINT-DETECT] detect with non-existent --root exits 0 and reports no stale annotations", () => {
+        const dir = withTempDir();
+        process.chdir(dir);
+        const missingRoot = path_1.default.join(dir, "missing-root");
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const code = (0, cli_1.runMaintenanceCli)([
+            "node",
+            "traceability-maint",
+            "detect",
+            "--root",
+            missingRoot,
+        ]);
+        try {
+            expect(code).toBe(0);
+            expect(logSpy).toHaveBeenCalledWith("No stale @story annotations found.");
+        }
+        finally {
+            logSpy.mockRestore();
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("[REQ-MAINT-SAFE] prints help and exits 0 when no subcommand is provided", () => {
+        const dir = withTempDir();
+        process.chdir(dir);
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const errorSpy = jest.spyOn(console, "error").mockImplementation(() => { });
+        const code = (0, cli_1.runMaintenanceCli)(["node", "traceability-maint"]);
+        try {
+            expect(code).toBe(0);
+            expect(logSpy).toHaveBeenCalled();
+            const allMessages = logSpy.mock.calls.flat().join("\n");
+            expect(allMessages).toContain("traceability-maint - Traceability annotation maintenance tools");
+            expect(errorSpy).not.toHaveBeenCalled();
+        }
+        finally {
+            logSpy.mockRestore();
+            errorSpy.mockRestore();
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("[REQ-MAINT-SAFE] detect catches filesystem permission errors and exits 2 with prefixed error message", () => {
+        const dir = withTempDir();
+        process.chdir(dir);
+        const errorSpy = jest.spyOn(console, "error").mockImplementation(() => { });
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const statSpy = jest.spyOn(fs_1.default, "statSync").mockImplementation(() => {
+            const err = new Error("EACCES simulated");
+            err.code = "EACCES";
+            throw err;
+        });
+        const code = (0, cli_1.runMaintenanceCli)(["node", "traceability-maint", "detect"]);
+        try {
+            expect(code).toBe(2);
+            expect(errorSpy).toHaveBeenCalled();
+            const message = String(errorSpy.mock.calls[0][0]);
+            expect(message).toContain("traceability-maint failed:");
+        }
+        finally {
+            statSpy.mockRestore();
+            errorSpy.mockRestore();
+            logSpy.mockRestore();
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+        }
+    });
 });

package/lib/tests/plugin-default-export-and-configs.test.js

@@ -55,6 +55,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
             "valid-annotation-format",
             "valid-story-reference",
             "valid-req-reference",
+            "prefer-implements-annotation",
         ];
         // Act: get actual rule names from plugin
         const actual = Object.keys(index_1.rules);
@@ -79,10 +80,12 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
         expect(recommendedRules).toHaveProperty("traceability/require-branch-annotation", "error");
         expect(recommendedRules).toHaveProperty("traceability/valid-story-reference", "error");
         expect(recommendedRules).toHaveProperty("traceability/valid-req-reference", "error");
+        expect(recommendedRules).toHaveProperty("traceability/prefer-implements-annotation", "warn");
     });
     it("[REQ-ERROR-SEVERITY] configs.strict uses same severity mapping as recommended", () => {
         const strictRules = index_1.configs.strict[0].rules;
         const recommendedRules = index_1.configs.recommended[0].rules;
         expect(strictRules).toEqual(recommendedRules);
+        expect(strictRules).toHaveProperty("traceability/prefer-implements-annotation", "warn");
     });
 });

package/lib/tests/rules/prefer-implements-annotation.test.d.ts

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

package/lib/tests/rules/prefer-implements-annotation.test.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Verify rule emits recommendations for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Verify rule detects multi-story and mixed-annotation patterns
+ * @req REQ-CONFIG-SEVERITY - Verify rule is disabled by default and can be enabled as warn/error
+ */
+const eslint_1 = require("eslint");
+const prefer_implements_annotation_1 = __importDefault(require("../../src/rules/prefer-implements-annotation"));
+const ruleTester = new eslint_1.RuleTester({
+    languageOptions: {
+        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+    },
+});
+describe("prefer-implements-annotation rule (Story 010.3-DEV-MIGRATE-TO-IMPLEMENTS)", () => {
+    ruleTester.run("prefer-implements-annotation", prefer_implements_annotation_1.default, {
+        valid: [
+            {
+                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @story is ignored",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction onlyStory() {}`,
+            },
+            {
+                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @req is ignored",
+                code: `/**\n * @req REQ-ONLY\n */\nfunction onlyReq() {}`,
+            },
+            {
+                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @implements only is ignored",
+                code: `/**\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction alreadyImplements() {}`,
+            },
+        ],
+        invalid: [
+            {
+                name: "[REQ-OPTIONAL-WARNING] single-story @story + @req block triggers preferImplements message",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
+                output: `/**\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
+                errors: [{ messageId: "preferImplements" }],
+            },
+            {
+                name: "[REQ-MULTI-STORY-DETECT] mixed @story/@req and @implements triggers cannotAutoFix",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction mixed() {}`,
+                errors: [
+                    {
+                        messageId: "cannotAutoFix",
+                        data: {
+                            reason: "comment mixes @story/@req with existing @implements annotations",
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-MULTI-STORY-DETECT] multiple @story paths in same block trigger multiStoryDetected",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n * @req REQ-BRANCH-DETECTION\n */\nfunction multiStory() {}`,
+                errors: [{ messageId: "multiStoryDetected" }],
+            },
+            {
+                name: "[REQ-AUTO-FIX] single @story + single @req auto-fixes to single @implements line",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
+                output: `/**\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
+                errors: [{ messageId: "preferImplements" }],
+            },
+            {
+                name: "[REQ-SINGLE-STORY-FIX] single @story with multiple @req lines auto-fixes to single @implements line containing all REQ IDs",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ONE\n * @req REQ-TWO\n * @req REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
+                output: `/**\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ONE REQ-TWO REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
+                errors: [{ messageId: "preferImplements" }],
+            },
+            {
+                name: "[REQ-AUTO-FIX] complex @req content (extra description) does not auto-fix but still warns",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED must handle extra description\n */\nfunction complexReqNoAutoFix() {}`,
+                errors: [{ messageId: "preferImplements" }],
+            },
+            {
+                name: "[REQ-AUTO-FIX] complex @story content (extra description) does not auto-fix but still warns",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md additional descriptive text\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction complexStoryNoAutoFix() {}`,
+                errors: [{ messageId: "preferImplements" }],
+            },
+        ],
+    });
+});

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

@@ -12,6 +12,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
  *
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-TYPESCRIPT-SUPPORT - Verify TypeScript declarations are checked via shared annotation checker helper
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Verify @implements is accepted as satisfying requirement annotations
  */
 const eslint_1 = require("eslint");
 const require_req_annotation_1 = __importDefault(require("../../src/rules/require-req-annotation"));
@@ -73,6 +76,10 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
                 name: "[REQ-ANNOTATION-REQUIRED] valid with only @req annotation",
                 code: `/**\n * @req REQ-EXAMPLE\n */\nfunction foo() {}`,
             },
+            {
+                name: "[REQ-REQUIRE-ACCEPTS-IMPLEMENTS] valid with only @implements annotation",
+                code: `/**\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction implOnly() {}`,
+            },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] valid with @story and @req annotations",
                 code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-EXAMPLE\n */\nfunction bar() {}`,
@@ -131,7 +138,7 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
         ],
         invalid: [
             {
-                name: "[REQ-ANNOTATION-REQUIRED] missing @req on function without JSDoc",
+                name: "[REQ-ANNOTATION-REQUIRED][REQ-REQUIRE-ACCEPTS-IMPLEMENTS] missing @req on function without JSDoc remains invalid under multi-story support",
                 code: `function baz() {}`,
                 errors: [
                     {

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

@@ -6,15 +6,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @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 - Verify require-story-annotation rule enforces @story annotation on functions
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Verify @implements annotation is accepted as satisfying story requirements
  */
 const eslint_1 = require("eslint");
 const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
 const ts_language_options_1 = require("../utils/ts-language-options");
 const ruleTester = new eslint_1.RuleTester({
-    languageOptions: {
-        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
-    },
+    languageOptions: ts_language_options_1.tsRuleTesterLanguageOptions,
 });
 describe("Require Story Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
     ruleTester.run("require-story-annotation", require_story_annotation_1.default, {
@@ -23,6 +23,10 @@ describe("Require Story Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)",
                 name: "[REQ-ANNOTATION-REQUIRED] valid with JSDoc @story annotation",
                 code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction foo() {}`,
             },
+            {
+                name: "[REQ-REQUIRE-ACCEPTS-IMPLEMENTS] valid with only @implements annotation",
+                code: `/**\n * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction implOnly() {}`,
+            },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] valid with line comment @story annotation",
                 code: `// @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -60,7 +64,8 @@ declare function tsDecl(): void;`,
         ],
         invalid: [
             {
-                name: "[REQ-ANNOTATION-REQUIRED] missing @story annotation on function",
+                // Backward compatibility: plain unannotated functions remain invalid under multi-story support
+                name: "[REQ-ANNOTATION-REQUIRED][BACKCOMPAT] missing @story annotation on function with no @implements",
                 code: `function bar() {}`,
                 output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}`,
                 errors: [

package/lib/tests/rules/valid-annotation-format.test.js

@@ -18,6 +18,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-CONFIGURABLE-PATTERNS-REQ - Rule supports configurable requirement ID regex patterns
  * @req REQ-CONFIGURABLE-PATTERNS-EXAMPLES - Rule supports configurable example strings in error messages
  * @req REQ-CONFIGURABLE-PATTERNS-FALLBACK - Invalid regex patterns fall back to default behavior without crashing
+ * Tests for: docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE - Rule parses @implements annotations with story and requirement references
+ * @req REQ-FORMAT-VALIDATION - Rule validates story and requirement formats inside @implements annotations
+ * @req REQ-MIXED-SUPPORT - Rule supports mixed @story/@req/@implements usage in the same comment
  */
 const eslint_1 = require("eslint");
 const valid_annotation_format_1 = __importDefault(require("../../src/rules/valid-annotation-format"));
@@ -168,6 +173,27 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
                     },
                 ],
             },
+            {
+                name: "[REQ-IMPLEMENTS-PARSE] valid single @implements with one story and one requirement (default patterns)",
+                code: `/**
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-IMPLEMENTS-PARSE
+ */`,
+            },
+            {
+                name: "[REQ-IMPLEMENTS-PARSE] valid multiple @implements lines with different stories and requirements",
+                code: `/**
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-IMPLEMENTS-PARSE REQ-FORMAT-VALIDATION
+ * @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-FORMAT-SPECIFICATION
+ */`,
+            },
+            {
+                name: "[REQ-MIXED-SUPPORT] valid mixed @story/@req/@implements usage in same block comment",
+                code: `/**
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-MIXED-SUPPORT
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-IMPLEMENTS-PARSE REQ-FORMAT-VALIDATION REQ-MIXED-SUPPORT
+ */`,
+            },
         ],
         invalid: [
             makeInvalidStory({
@@ -480,6 +506,58 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
                     },
                 ],
             },
+            makeInvalid({
+                name: "[REQ-IMPLEMENTS-PARSE] @implements with no value is invalid",
+                code: `/**
+ * @implements
+ */`,
+                messageId: "invalidImplementsFormat",
+                details: 'Missing story path and requirement IDs for @implements annotation. Expected a value like "docs/stories/005.0-DEV-EXAMPLE.story.md REQ-EXAMPLE".',
+            }),
+            makeInvalid({
+                name: "[REQ-IMPLEMENTS-PARSE] @implements with only story path and no requirement IDs is invalid",
+                code: `/**
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ */`,
+                messageId: "invalidImplementsFormat",
+                details: 'Missing requirement IDs for @implements annotation. Expected a value like "docs/stories/005.0-DEV-EXAMPLE.story.md REQ-EXAMPLE".',
+            }),
+            makeInvalid({
+                name: "[REQ-FORMAT-VALIDATION] @implements with invalid story path format",
+                code: `/**
+ * @implements invalid/path.txt REQ-IMPLEMENTS-PARSE
+ */`,
+                messageId: "invalidImplementsFormat",
+                details: 'Invalid story path "invalid/path.txt" for @implements annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+            }),
+            {
+                name: "[REQ-FORMAT-VALIDATION] @implements with invalid requirement ID format",
+                code: `/**
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-VALID invalid-format
+ */`,
+                errors: [
+                    {
+                        messageId: "invalidReqFormat",
+                        data: {
+                            details: 'Invalid requirement ID "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-FORMAT-VALIDATION] @implements with multiple requirement IDs where one is invalid",
+                code: `/**
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-VALID-1 REQ-VALID-2 bad-id
+ */`,
+                errors: [
+                    {
+                        messageId: "invalidReqFormat",
+                        data: {
+                            details: 'Invalid requirement ID "bad-id" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
+                        },
+                    },
+                ],
+            },
         ],
     });
 });