eslint-plugin-traceability 1.6.5 → 1.7.1

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

@@ -12,12 +12,50 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-ERROR-MESSAGES-CONSISTENT - Verify invalid annotation errors use consistent wording and structure
  * @req REQ-ERROR-MESSAGES-ACTIONABLE - Verify invalid annotation errors provide actionable guidance and examples
  * @req REQ-ERROR-MESSAGES-IDENTIFIERS - Verify invalid annotation errors echo the offending identifier/path in the message
+ * Tests for: docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-CONFIGURABLE-PATTERNS-STORY - Rule supports configurable story path regex patterns
+ * @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"));
 const ruleTester = new eslint_1.RuleTester({
     languageOptions: { parserOptions: { ecmaVersion: 2020 } },
 });
+const makeInvalid = ({ name, code, output, messageId, details, options, }) => ({
+    name,
+    code,
+    ...(output ? { output } : {}),
+    ...(options ? { options } : {}),
+    errors: [
+        {
+            messageId,
+            data: {
+                details,
+            },
+        },
+    ],
+});
+/**
+ * Test-only convenience for Story 005.0 error messaging consistency.
+ * Preconfigures the invalidStoryFormat messageId so tests only specify
+ * name, code, and details (plus optional output/options).
+ */
+const makeInvalidStory = ({ name, code, details, output, options, }) => makeInvalid({
+    name,
+    code,
+    output,
+    options,
+    messageId: "invalidStoryFormat",
+    details,
+});
 describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)", () => {
     ruleTester.run("valid-annotation-format", valid_annotation_format_1.default, {
         valid: [
@@ -55,150 +93,467 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
                 code: `/**
  *   @story   docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  *   @req   REQ-FLEXIBLE-PARSING
+ */`,
+            },
+            {
+                name: "[REQ-CONFIGURABLE-PATTERNS-STORY] custom storyPathPattern accepts alternate extension",
+                code: `// @story stories/feature-010.1-CUSTOM.story.mdx`,
+                options: [
+                    {
+                        story: {
+                            pattern: "^stories\\/[^\\s]+\\.story\\.mdx$",
+                            example: "stories/example-010.1-CUSTOM.story.mdx",
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-CONFIGURABLE-PATTERNS-REQ] custom requirementIdPattern accepts PROJECT-123 style IDs",
+                code: `// @req PROJECT-123`,
+                options: [
+                    {
+                        req: {
+                            pattern: "^[A-Z]+-[0-9]+$",
+                            example: "PROJECT-123",
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-CONFIGURABLE-PATTERNS-BOTH] custom patterns accept alternative story and req shapes",
+                code: `/**
+ * @story stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.mdx
+ * @req STORY-10
+ */`,
+                options: [
+                    {
+                        story: {
+                            pattern: "^stories\\/[^\\s]+\\.story\\.mdx$",
+                            example: "stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.mdx",
+                        },
+                        req: {
+                            pattern: "^[A-Z]+-[0-9]+$",
+                            example: "STORY-10",
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-CONFIGURABLE-PATTERNS-STORY-FLAT] flat storyPathPattern accepts alternate extension when nested config not provided",
+                code: `// @story stories/feature-010.1-CUSTOM.story.mdx`,
+                options: [
+                    {
+                        storyPathPattern: "^stories\\/[^\\s]+\\.story\\.mdx$",
+                        storyPathExample: "stories/example-010.1-CUSTOM.story.mdx",
+                    },
+                ],
+            },
+            {
+                name: "[REQ-CONFIGURABLE-PATTERNS-REQ-FLAT] flat requirementIdPattern accepts PROJECT-123 style IDs when nested config not provided",
+                code: `// @req PROJECT-123`,
+                options: [
+                    {
+                        requirementIdPattern: "^[A-Z]+-[0-9]+$",
+                        requirementIdExample: "PROJECT-123",
+                    },
+                ],
+            },
+            {
+                name: "[REQ-CONFIGURABLE-PATTERNS-BOTH-FLAT] flat patterns accept alternative story and req shapes when nested config not provided",
+                code: `/**
+ * @story stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.mdx
+ * @req STORY-10
+ */`,
+                options: [
+                    {
+                        storyPathPattern: "^stories\\/[^\\s]+\\.story\\.mdx$",
+                        storyPathExample: "stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.mdx",
+                        requirementIdPattern: "^[A-Z]+-[0-9]+$",
+                        requirementIdExample: "STORY-10",
+                    },
+                ],
+            },
+            {
+                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({
                 name: "[REQ-PATH-FORMAT] missing story path (single line)",
                 code: `// @story`,
+                details: 'Missing story path for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+            }),
+            makeInvalidStory({
+                name: "[REQ-PATH-FORMAT] invalid story file extension",
+                code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
+                output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                details: 'Invalid story path "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+            }),
+            makeInvalidStory({
+                name: "[REQ-PATH-FORMAT] missing extension in story path",
+                code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION`,
+                output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                details: 'Invalid story path "docs/stories/005.0-DEV-ANNOTATION-VALIDATION" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+            }),
+            makeInvalidStory({
+                name: "[REQ-PATH-FORMAT] story path must not use path traversal",
+                code: `// @story ../docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                details: 'Invalid story path "../docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+            }),
+            makeInvalid({
+                name: "[REQ-REQ-FORMAT] missing req id (single line)",
+                code: `// @req`,
+                messageId: "invalidReqFormat",
+                details: 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".',
+            }),
+            makeInvalid({
+                name: "[REQ-REQ-FORMAT] invalid req id format (single line)",
+                code: `// @req invalid-format`,
+                messageId: "invalidReqFormat",
+                details: 'Invalid requirement ID "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
+            }),
+            makeInvalid({
+                name: "[REQ-REQ-FORMAT] missing req identifier with trailing space",
+                code: `// @req `,
+                messageId: "invalidReqFormat",
+                details: 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".',
+            }),
+            makeInvalidStory({
+                name: "[REQ-MULTILINE-SUPPORT] missing story path with multi-line block comment",
+                code: `/**
+ * @story
+ */`,
+                details: 'Missing story path for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+            }),
+            makeInvalidStory({
+                name: "[REQ-MULTILINE-SUPPORT] invalid multi-line story path after collapsing whitespace",
+                code: `/**
+ * @story docs/stories/005.0-
+ * DEV-ANNOTATION-VALIDATION.story
+ */`,
+                details: 'Invalid story path "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+            }),
+            makeInvalid({
+                name: "[REQ-MULTILINE-SUPPORT] missing req id with multi-line block comment",
+                code: `/**
+ * @req
+ */`,
+                messageId: "invalidReqFormat",
+                details: 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".',
+            }),
+            makeInvalid({
+                name: "[REQ-MULTILINE-SUPPORT] invalid multi-line req id after collapsing whitespace",
+                code: `/**
+ * @req invalid-
+ * format
+ */`,
+                messageId: "invalidReqFormat",
+                details: 'Invalid requirement ID "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
+            }),
+            {
+                name: "[REQ-CONFIGURABLE-PATTERNS-EXAMPLES] custom story example appears in error message",
+                code: `// @story invalid/path.txt`,
+                options: [
+                    {
+                        story: {
+                            pattern: "^stories\\/[^\\s]+\\.story\\.mdx$",
+                            example: "stories/example-010.1-CUSTOM.story.mdx",
+                        },
+                    },
+                ],
                 errors: [
                     {
                         messageId: "invalidStoryFormat",
                         data: {
-                            details: 'Missing story path for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                            details: 'Invalid story path "invalid/path.txt" for @story annotation. Expected a path like "stories/example-010.1-CUSTOM.story.mdx".',
                         },
                     },
                 ],
             },
             {
-                name: "[REQ-PATH-FORMAT] invalid story file extension",
+                name: "[REQ-CONFIGURABLE-PATTERNS-EXAMPLES] custom requirement example appears in error message",
+                code: `// @req not-matching`,
+                options: [
+                    {
+                        req: {
+                            pattern: "^[A-Z]+-[0-9]+$",
+                            example: "PROJECT-123",
+                        },
+                    },
+                ],
+                errors: [
+                    {
+                        messageId: "invalidReqFormat",
+                        data: {
+                            details: 'Invalid requirement ID "not-matching" for @req annotation. Expected an identifier like "PROJECT-123" (uppercase letters, numbers, and dashes only).',
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-CONFIGURABLE-PATTERNS-FALLBACK] invalid storyPathPattern falls back to default behavior",
                 code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
+                options: [
+                    {
+                        // invalid regex should be caught by the rule and ignored
+                        story: {
+                            pattern: "[unclosed",
+                        },
+                    },
+                ],
                 output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
                 errors: [
+                    {
+                        // Configuration error should also be reported
+                        messageId: "invalidRuleConfiguration",
+                        data: {
+                            details: 'Invalid regular expression for option "story.pattern": "[unclosed"',
+                        },
+                    },
                     {
                         messageId: "invalidStoryFormat",
                         data: {
+                            // Because we fall back, we still use the default example text
                             details: 'Invalid story path "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
                         },
                     },
                 ],
             },
             {
-                name: "[REQ-PATH-FORMAT] missing extension in story path",
-                code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION`,
-                output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                name: "[REQ-CONFIGURABLE-PATTERNS-FALLBACK] invalid requirementIdPattern falls back to default behavior",
+                code: `// @req invalid-format`,
+                options: [
+                    {
+                        // invalid regex should be caught by the rule and ignored
+                        req: {
+                            pattern: "(unclosed",
+                        },
+                    },
+                ],
                 errors: [
                     {
-                        messageId: "invalidStoryFormat",
+                        // Configuration error should also be reported
+                        messageId: "invalidRuleConfiguration",
+                        data: {
+                            details: 'Invalid regular expression for option "req.pattern": "(unclosed"',
+                        },
+                    },
+                    {
+                        messageId: "invalidReqFormat",
                         data: {
-                            details: 'Invalid story path "docs/stories/005.0-DEV-ANNOTATION-VALIDATION" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                            // Because we fall back, we still use the default example text
+                            details: 'Invalid requirement ID "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
                         },
                     },
                 ],
             },
             {
-                name: "[REQ-PATH-FORMAT] story path must not use path traversal",
-                code: `// @story ../docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                name: "[REQ-CONFIGURABLE-PATTERNS-FALLBACK-FLAT] invalid flat storyPathPattern falls back to default and reports config error",
+                code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
+                options: [
+                    {
+                        // invalid regex should be caught by the rule and ignored
+                        storyPathPattern: "[unclosed",
+                    },
+                ],
+                output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
                 errors: [
                     {
+                        // Configuration error should also be reported
+                        messageId: "invalidRuleConfiguration",
+                        data: {
+                            details: 'Invalid regular expression for option "storyPathPattern": "[unclosed"',
+                        },
+                    },
+                    {
+                        // Because we fall back, we still use the default example text
                         messageId: "invalidStoryFormat",
                         data: {
-                            details: 'Invalid story path "../docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                            details: 'Invalid story path "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
                         },
                     },
                 ],
             },
             {
-                name: "[REQ-REQ-FORMAT] missing req id (single line)",
-                code: `// @req`,
+                name: "[REQ-CONFIGURABLE-PATTERNS-FALLBACK-FLAT] invalid flat requirementIdPattern falls back to default and reports config error",
+                code: `// @req invalid-format`,
+                options: [
+                    {
+                        // invalid regex should be caught by the rule and ignored
+                        requirementIdPattern: "(unclosed",
+                    },
+                ],
                 errors: [
                     {
+                        // Configuration error should also be reported
+                        messageId: "invalidRuleConfiguration",
+                        data: {
+                            details: 'Invalid regular expression for option "requirementIdPattern": "(unclosed"',
+                        },
+                    },
+                    {
+                        // Because we fall back, we still use the default example text
                         messageId: "invalidReqFormat",
                         data: {
-                            details: 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".',
+                            details: 'Invalid requirement ID "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
                         },
                     },
                 ],
             },
             {
-                name: "[REQ-REQ-FORMAT] invalid req id format (single line)",
-                code: `// @req invalid-format`,
+                name: "[REQ-PATTERN-CONFIG] nested story.pattern takes precedence over flat storyPathPattern and its example",
+                code: `// @story not-matching.mdx`,
+                options: [
+                    {
+                        story: {
+                            pattern: "^stories\\/nested-only\\.story\\.mdx$",
+                            example: "stories/nested-only.story.mdx",
+                        },
+                        storyPathPattern: "^docs\\/stories\\/should-not-apply\\.story\\.mdx$",
+                        storyPathExample: "docs/stories/should-not-apply.story.mdx",
+                    },
+                ],
                 errors: [
                     {
-                        messageId: "invalidReqFormat",
+                        messageId: "invalidStoryFormat",
                         data: {
-                            details: 'Invalid requirement ID "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
+                            details: 'Invalid story path "not-matching.mdx" for @story annotation. Expected a path like "stories/nested-only.story.mdx".',
                         },
                     },
                 ],
             },
             {
-                name: "[REQ-REQ-FORMAT] missing req identifier with trailing space",
-                code: `// @req `,
+                name: "[REQ-PATTERN-CONFIG] nested req.pattern takes precedence over flat requirementIdPattern and its example",
+                code: `// @req DOES-NOT-MATCH`,
+                options: [
+                    {
+                        req: {
+                            pattern: "^REQ-[0-9]{4}$",
+                            example: "REQ-0001",
+                        },
+                        requirementIdPattern: "^[A-Z]+-[0-9]+$",
+                        requirementIdExample: "PROJECT-123",
+                    },
+                ],
                 errors: [
                     {
                         messageId: "invalidReqFormat",
                         data: {
-                            details: 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".',
+                            details: 'Invalid requirement ID "DOES-NOT-MATCH" for @req annotation. Expected an identifier like "REQ-0001" (uppercase letters, numbers, and dashes only).',
                         },
                     },
                 ],
             },
             {
-                name: "[REQ-MULTILINE-SUPPORT] missing story path with multi-line block comment",
-                code: `/**
- * @story
- */`,
+                name: "[REQ-EXAMPLE-MESSAGES] nested story example text overrides flat storyPathExample in error messages",
+                code: `// @story invalid/path.txt`,
+                options: [
+                    {
+                        story: {
+                            pattern: "^stories\\/special\\/.+\\.story\\.mdx$",
+                            example: "stories/special/example.story.mdx",
+                        },
+                        storyPathPattern: "^stories\\/ignored\\/.+\\.story\\.mdx$",
+                        storyPathExample: "stories/ignored/example.story.mdx",
+                    },
+                ],
                 errors: [
                     {
                         messageId: "invalidStoryFormat",
                         data: {
-                            details: 'Missing story path for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                            details: 'Invalid story path "invalid/path.txt" for @story annotation. Expected a path like "stories/special/example.story.mdx".',
                         },
                     },
                 ],
             },
             {
-                name: "[REQ-MULTILINE-SUPPORT] invalid multi-line story path after collapsing whitespace",
-                code: `/**
- * @story docs/stories/005.0-
- * DEV-ANNOTATION-VALIDATION.story
- */`,
+                name: "[REQ-EXAMPLE-MESSAGES] nested req example text overrides flat requirementIdExample in error messages",
+                code: `// @req bad-id`,
+                options: [
+                    {
+                        req: {
+                            pattern: "^REQ-[A-Z]+-[0-9]{3}$",
+                            example: "REQ-FOO-001",
+                        },
+                        requirementIdPattern: "^[A-Z]+-[0-9]+$",
+                        requirementIdExample: "PROJECT-123",
+                    },
+                ],
                 errors: [
                     {
-                        messageId: "invalidStoryFormat",
+                        messageId: "invalidReqFormat",
                         data: {
-                            details: 'Invalid story path "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                            details: 'Invalid requirement ID "bad-id" for @req annotation. Expected an identifier like "REQ-FOO-001" (uppercase letters, numbers, and dashes only).',
                         },
                     },
                 ],
             },
+            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-MULTILINE-SUPPORT] missing req id with multi-line block comment",
+                name: "[REQ-FORMAT-VALIDATION] @implements with invalid requirement ID format",
                 code: `/**
- * @req
+ * @implements docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md REQ-VALID invalid-format
  */`,
                 errors: [
                     {
                         messageId: "invalidReqFormat",
                         data: {
-                            details: 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".',
+                            details: 'Invalid requirement ID "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
                         },
                     },
                 ],
             },
             {
-                name: "[REQ-MULTILINE-SUPPORT] invalid multi-line req id after collapsing whitespace",
+                name: "[REQ-FORMAT-VALIDATION] @implements with multiple requirement IDs where one is invalid",
                 code: `/**
- * @req invalid-
- * format
+ * @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 "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
+                            details: 'Invalid requirement ID "bad-id" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
                         },
                     },
                 ],

package/lib/tests/rules/valid-req-reference.test.js

@@ -32,6 +32,15 @@ describe("Valid Req Reference Rule (Story 010.0-DEV-DEEP-VALIDATION)", () => {
                 code: `// @story tests/fixtures/story_bullet.md
 // @req REQ-BULLET-LIST`,
             },
+            {
+                name: "[REQ-DEEP-IMPLEMENTS] single implements line with multiple requirements in multi-story fixture (see 010.2-DEV-MULTI-STORY-SUPPORT)",
+                code: `// @implements tests/fixtures/story_multi_a.md REQ-SHARED-ID REQ-ONLY-A`,
+            },
+            {
+                name: "[REQ-DEEP-IMPLEMENTS] multi-story implements with shared requirement IDs (see 010.2-DEV-MULTI-STORY-SUPPORT)",
+                code: `// @implements tests/fixtures/story_multi_a.md REQ-SHARED-ID REQ-ONLY-A
+// @implements tests/fixtures/story_multi_b.md REQ-SHARED-ID REQ-ONLY-B`,
+            },
         ],
         invalid: [
             {
@@ -88,6 +97,31 @@ describe("Valid Req Reference Rule (Story 010.0-DEV-DEEP-VALIDATION)", () => {
                     },
                 ],
             },
+            {
+                name: "[REQ-DEEP-IMPLEMENTS] missing implements requirement in multi-story fixture (see 010.2-DEV-MULTI-STORY-SUPPORT)",
+                code: `// @implements tests/fixtures/story_multi_a.md REQ-NOT-IN-A`,
+                errors: [
+                    {
+                        messageId: "reqMissing",
+                        data: {
+                            reqId: "REQ-NOT-IN-A",
+                            storyPath: "tests/fixtures/story_multi_a.md",
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-DEEP-IMPLEMENTS] disallow path traversal in implements story path (see 010.2-DEV-MULTI-STORY-SUPPORT)",
+                code: `// @implements ../tests/fixtures/story_multi_a.md REQ-SHARED-ID`,
+                errors: [
+                    {
+                        messageId: "invalidPath",
+                        data: {
+                            storyPath: "../tests/fixtures/story_multi_a.md",
+                        },
+                    },
+                ],
+            },
         ],
     });
 });

package/lib/tests/utils/annotation-checker.test.d.ts

@@ -1 +1,24 @@
+type AnnotationCheckerTestConfig = {
+    rule: any;
+    valid: Array<{
+        name: string;
+        code: string;
+        [key: string]: any;
+    }>;
+    invalid: Array<{
+        name: string;
+        code: string;
+        errors: any[];
+        [key: string]: any;
+    }>;
+};
+/**
+ * Shared helper for running tests that exercise the annotation-checker logic
+ * for TypeScript constructs.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+ * @req REQ-TEST-UTILS-TS-LANG - Shared TS RuleTester language options helper
+ */
+export declare function runAnnotationCheckerTests(ruleName: string, config: AnnotationCheckerTestConfig): void;
 export {};