eslint-plugin-traceability 1.10.0 → 1.11.0

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

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

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

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

package/lib/src/rules/require-story-annotation.js

@@ -45,6 +45,9 @@ const rule = {
                         uniqueItems: true,
                     },
                     exportPriority: { type: "string", enum: require_story_helpers_1.EXPORT_PRIORITY_VALUES },
+                    annotationTemplate: { type: "string" },
+                    methodAnnotationTemplate: { type: "string" },
+                    autoFix: { type: "boolean" },
                 },
                 additionalProperties: false,
             },
@@ -63,6 +66,15 @@ const rule = {
         const opts = (context.options && context.options[0]) || {};
         const scope = opts.scope || require_story_helpers_1.DEFAULT_SCOPE;
         const exportPriority = opts.exportPriority || "all";
+        const annotationTemplate = typeof opts.annotationTemplate === "string" &&
+            opts.annotationTemplate.trim().length > 0
+            ? opts.annotationTemplate.trim()
+            : undefined;
+        const methodAnnotationTemplate = typeof opts.methodAnnotationTemplate === "string" &&
+            opts.methodAnnotationTemplate.trim().length > 0
+            ? opts.methodAnnotationTemplate.trim()
+            : undefined;
+        const autoFix = typeof opts.autoFix === "boolean" ? opts.autoFix : true;
         /**
          * Optional debug logging for troubleshooting this rule.
          * Developers can temporarily uncomment the block below to log when the rule
@@ -84,6 +96,9 @@ const rule = {
             shouldProcessNode: should,
             scope,
             exportPriority,
+            annotationTemplate,
+            methodAnnotationTemplate,
+            autoFix,
         });
     },
 };

package/lib/src/rules/require-test-traceability.js

@@ -37,12 +37,7 @@ const rule = {
                     testFilePatterns: {
                         type: "array",
                         items: { type: "string" },
-                        default: [
-                            "**/tests/**/*.test.{js,ts}",
-                            "**/tests/**/*.spec.{js,ts}",
-                            "**/__tests__/**/*.{js,ts}",
-                            "**/*.{test,spec}.{js,ts}",
-                        ],
+                        default: ["/tests/", "/test/", "/__tests__", ".test.", ".spec."],
                     },
                     requireDescribeStory: {
                         type: "boolean",

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

@@ -1,247 +1,8 @@
 "use strict";
 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");
-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) {
-    context.report({
-        node: comment,
-        messageId: "invalidStoryFormat",
-        data: { details: (0, valid_annotation_utils_1.buildStoryErrorMessage)("invalid", collapsed, options) },
-    });
-}
-/**
- * Compute the text replacement for an invalid @story annotation within a comment.
- *
- * This helper:
- *   - finds the @story tag in the raw comment text,
- *   - computes the character range of its value,
- *   - and returns an ESLint fix that replaces only that range.
- *
- * Returns null when the tag or value cannot be safely located.
- *
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @req REQ-AUTOFIX-SAFE
- * @req REQ-AUTOFIX-PRESERVE
- */
-function createStoryFix(context, comment, fixed) {
-    const sourceCode = context.getSourceCode();
-    const commentText = sourceCode.getText(comment);
-    const search = "@story";
-    const tagIndex = commentText.indexOf(search);
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-    // @req REQ-AUTOFIX-SAFE - Skip auto-fix when @story tag cannot be reliably located
-    if (tagIndex === valid_annotation_utils_1.TAG_NOT_FOUND_INDEX) {
-        return null;
-    }
-    const afterTagIndex = tagIndex + search.length;
-    const rest = commentText.slice(afterTagIndex);
-    const valueMatch = rest.match(/[^\S\r\n]*([^\r\n*]+)/);
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-    // @req REQ-AUTOFIX-SAFE - Abort auto-fix when story value range cannot be safely determined
-    if (!valueMatch || valueMatch.index === undefined) {
-        return null;
-    }
-    const valueStartInComment = afterTagIndex +
-        valueMatch.index +
-        (valueMatch[0].length - valueMatch[1].length);
-    const valueEndInComment = valueStartInComment + valueMatch[1].length;
-    const start = comment.range[0];
-    const fixRange = [
-        start + valueStartInComment,
-        start + valueEndInComment,
-    ];
-    return () => (fixer) => fixer.replaceTextRange(fixRange, fixed);
-}
-/**
- * Report an invalid @story annotation and attempt a minimal, safe auto-fix
- * for common path suffix issues by locating and replacing the path text
- * within the original comment.
- *
- * This helper:
- *   - only adjusts the story path suffix when a safe, well-understood
- *     transformation is available, satisfying REQ-AUTOFIX-SAFE.
- *   - preserves all surrounding comment formatting, spacing, and text
- *     outside the path substring, satisfying REQ-AUTOFIX-PRESERVE.
- *
- * @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
- * @req REQ-AUTOFIX-PRESERVE - Auto-fix must preserve surrounding formatting and comments
- */
-function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
-    const fixFactory = createStoryFix(context, comment, fixed);
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-    // @req REQ-AUTOFIX-SAFE - Fall back to reporting without fix when safe fix cannot be created
-    if (!fixFactory) {
-        reportInvalidStoryFormat(context, comment, collapsed, (0, valid_annotation_options_1.getResolvedDefaults)());
-        return;
-    }
-    context.report({
-        node: comment,
-        messageId: "invalidStoryFormat",
-        data: {
-            details: (0, valid_annotation_utils_1.buildStoryErrorMessage)("invalid", collapsed, (0, valid_annotation_options_1.getResolvedDefaults)()),
-        },
-        fix: fixFactory(),
-    });
-}
-/**
- * Validate a @story annotation value and report detailed errors when needed.
- * Where safe and unambiguous, apply an automatic fix for missing suffixes.
- *
- * @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();
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-PATH-FORMAT - Treat missing @story value as a specific validation error
-    if (!trimmed) {
-        context.report({
-            node: comment,
-            messageId: "invalidStoryFormat",
-            data: { details: (0, valid_annotation_utils_1.buildStoryErrorMessage)("missing", null, options) },
-        });
-        return;
-    }
-    const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
-    const pathPattern = options.storyPattern;
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-PATH-FORMAT - Accept @story value when it matches configured storyPattern
-    if (pathPattern.test(collapsed)) {
-        return;
-    }
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-PATH-FORMAT - Reject @story values containing internal whitespace as invalid
-    if (/\s/.test(trimmed)) {
-        reportInvalidStoryFormat(context, comment, collapsed, options);
-        return;
-    }
-    const fixed = (0, valid_annotation_utils_1.getFixedStoryPath)(collapsed);
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-    // @req REQ-AUTOFIX-FORMAT - Apply suffix-only auto-fix when it yields a pattern-compliant path
-    if (fixed && pathPattern.test(fixed)) {
-        reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed);
-        return;
-    }
-    reportInvalidStoryFormat(context, comment, collapsed, options);
-}
-/**
- * Validate a @req annotation value and report detailed errors when needed.
- *
- * @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();
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-REQ-FORMAT - Treat missing @req value as a specific validation error
-    if (!trimmed) {
-        context.report({
-            node: comment,
-            messageId: "invalidReqFormat",
-            data: { details: (0, valid_annotation_utils_1.buildReqErrorMessage)("missing", null, options) },
-        });
-        return;
-    }
-    const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
-    const reqPattern = options.reqPattern;
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-REQ-FORMAT - Flag @req identifiers that do not match the configured pattern
-    if (!reqPattern.test(collapsed)) {
-        context.report({
-            node: comment,
-            messageId: "invalidReqFormat",
-            data: { details: (0, valid_annotation_utils_1.buildReqErrorMessage)("invalid", collapsed, options) },
-        });
-    }
-}
-/**
- * Validate an @supports annotation value and report detailed errors when needed.
- *
- * Expected format:
- *   @supports <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-SUPPORTS-PARSE - Parse @supports 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) {
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-MULTILINE-SUPPORT - Do nothing when there is no pending multi-line annotation to finalize
-    if (!pending) {
-        return null;
-    }
-    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @req REQ-SYNTAX-VALIDATION - Dispatch to @story or @req validator based on pending annotation type
-    // @req REQ-AUTOFIX-FORMAT - Route to story validator which may apply safe auto-fixes
-    // @req REQ-MIXED-SUPPORT - Ensure @story and @req annotations are handled independently
-    if (pending.type === "story") {
-        validateStoryAnnotation(context, comment, pending.value, options);
-    }
-    else {
-        validateReqAnnotation(context, comment, pending.value, options);
-    }
-    return null;
-}
+const valid_annotation_format_validators_1 = require("./helpers/valid-annotation-format-validators");
 /**
  * Process a single normalized comment line and update the pending annotation state.
  *
@@ -269,7 +30,7 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     // @req REQ-IMPLEMENTS-PARSE - Immediately validate @supports without starting multi-line state
     if (isImplements) {
         const implementsValue = normalized.replace(/^@supports\b/, "").trim();
-        validateImplementsAnnotation(context, comment, implementsValue, options);
+        (0, valid_annotation_format_validators_1.validateImplementsAnnotation)(context, comment, implementsValue, options);
         return pending;
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
@@ -279,7 +40,7 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     // @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);
+        (0, valid_annotation_format_validators_1.finalizePendingAnnotation)(context, comment, options, pending);
         const value = normalized.replace(/^@story\b|^@req\b/, "").trim();
         return {
             type: isStory ? "story" : "req",
@@ -287,6 +48,12 @@ function processCommentLine({ normalized, pending, context, comment, options, })
             hasValue: value.trim().length > 0,
         };
     }
+    // Implement JSDoc tag coexistence behavior: terminate @story/@req values when a new non-traceability JSDoc tag line (e.g., @param, @returns) is encountered.
+    // @supports docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md REQ-ANNOTATION-TERMINATION REQ-CONTINUATION-LOGIC
+    if ((0, valid_annotation_format_internal_1.isNonTraceabilityJSDocTagLine)(normalized)) {
+        (0, valid_annotation_format_validators_1.finalizePendingAnnotation)(context, comment, options, pending);
+        return null;
+    }
     // @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
@@ -344,7 +111,7 @@ function processComment(context, comment, options) {
             options,
         });
     });
-    finalizePendingAnnotation(context, comment, options, pending);
+    (0, valid_annotation_format_validators_1.finalizePendingAnnotation)(context, comment, options, pending);
 }
 exports.default = {
     meta: {

package/lib/src/utils/annotation-checker.js

@@ -76,7 +76,7 @@ function getFixTargetNode(node) {
  * Returned function is a proper named function so no inline arrow is used.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-AUTOFIX - Provide autofix for missing @req annotation
- * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-AUTOFIX REQ-ANNOTATION-REPORTING
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-AUTOFIX REQ-ANNOTATION-REPORTING
  */
 function createMissingReqFix(node) {
     const target = getFixTargetNode(node);

package/lib/tests/perf/maintenance-cli-large-workspace.test.d.ts

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

package/lib/tests/perf/maintenance-cli-large-workspace.test.js

@@ -0,0 +1,130 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * CLI-level performance tests for maintenance tools on large workspaces.
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-REPORT REQ-MAINT-SAFE
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const perf_hooks_1 = require("perf_hooks");
+const cli_1 = require("../../src/maintenance/cli");
+function createCliLargeWorkspace() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "traceability-cli-large-"));
+    // Create a modestly sized workspace reusing the same shape as the core perf tests,
+    // but with fewer files to keep end-to-end CLI timing predictable.
+    for (let moduleIndex = 0; moduleIndex < 5; moduleIndex += 1) {
+        const moduleDir = path.join(root, `module-${moduleIndex.toString().padStart(3, "0")}`);
+        fs.mkdirSync(moduleDir);
+        for (let fileIndex = 0; fileIndex < 20; fileIndex += 1) {
+            const filePath = path.join(moduleDir, `file-${fileIndex.toString().padStart(3, "0")}.ts`);
+            const validStory = "cli-valid.story.md";
+            const staleStory = "cli-stale.story.md";
+            const content = `/**
+ * @story ${validStory}
+ * @story ${staleStory}
+ */
+export function cli_example_${moduleIndex}_${fileIndex}() {}
+`;
+            fs.writeFileSync(filePath, content, "utf8");
+        }
+    }
+    // Create the valid story file so that only the stale entries are reported.
+    fs.writeFileSync(path.join(root, "cli-valid.story.md"), "# cli valid", "utf8");
+    return {
+        root,
+        cleanup: () => {
+            fs.rmSync(root, { recursive: true, force: true });
+        },
+    };
+}
+describe("Maintenance CLI on large workspaces (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    let workspace;
+    let originalCwd;
+    beforeAll(() => {
+        originalCwd = process.cwd();
+        workspace = createCliLargeWorkspace();
+        process.chdir(workspace.root);
+    });
+    afterAll(() => {
+        process.chdir(originalCwd);
+        workspace.cleanup();
+    });
+    it("[REQ-MAINT-DETECT] detect --json completes within a generous time budget and returns JSON payload", () => {
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const start = perf_hooks_1.performance.now();
+        const exitCode = (0, cli_1.runMaintenanceCli)([
+            "node",
+            "traceability-maint",
+            "detect",
+            "--root",
+            workspace.root,
+            "--json",
+        ]);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        expect(exitCode === 0 || exitCode === 1).toBe(true);
+        expect(durationMs).toBeLessThan(5000);
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        const payloadRaw = String(logSpy.mock.calls[0][0]);
+        const payload = JSON.parse(payloadRaw);
+        expect(payload.root).toBe(workspace.root);
+        expect(Array.isArray(payload.stale)).toBe(true);
+        expect(payload.stale.length).toBeGreaterThan(0);
+        logSpy.mockRestore();
+    });
+    it("[REQ-MAINT-REPORT] report --format=json completes within a generous time budget", () => {
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const start = perf_hooks_1.performance.now();
+        const exitCode = (0, cli_1.runMaintenanceCli)([
+            "node",
+            "traceability-maint",
+            "report",
+            "--root",
+            workspace.root,
+            "--format",
+            "json",
+        ]);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        expect(exitCode).toBe(0);
+        expect(durationMs).toBeLessThan(5000);
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        const payloadRaw = String(logSpy.mock.calls[0][0]);
+        const payload = JSON.parse(payloadRaw);
+        expect(payload.root).toBe(workspace.root);
+        expect(typeof payload.report).toBe("string");
+        logSpy.mockRestore();
+    });
+});

package/lib/tests/perf/maintenance-large-workspace.test.d.ts

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