eslint-plugin-traceability 1.10.1 → 1.11.0

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

@@ -167,7 +167,11 @@ function validateStoryAnnotation(context, comment, rawValue, options) {
     // @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);
+        if (options.autoFix !== false) {
+            reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed);
+            return;
+        }
+        reportInvalidStoryFormat(context, comment, collapsed, options);
         return;
     }
     reportInvalidStoryFormat(context, comment, collapsed, options);

package/lib/src/rules/helpers/valid-annotation-options.d.ts

@@ -53,6 +53,11 @@ export interface AnnotationRuleOptions {
      * Human-readable example requirement ID used in error messages.
      */
     requirementIdExample?: string;
+    /**
+     * Global toggle for auto-fix behavior in valid-annotation-format.
+     * When false, no automatic suffix-normalization fixes are applied.
+     */
+    autoFix?: boolean;
 }
 /**
  * Resolved, runtime-ready options for the rule.
@@ -62,6 +67,7 @@ export interface ResolvedAnnotationOptions {
     storyExample: string;
     reqPattern: RegExp;
     reqExample: string;
+    autoFix: boolean;
 }
 export declare function getDefaultReqExample(): string;
 export declare function getResolvedDefaults(): ResolvedAnnotationOptions;

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

@@ -26,6 +26,7 @@ let resolvedDefaults = {
     storyExample: getDefaultStoryExample(),
     reqPattern: getDefaultReqPattern(),
     reqExample: getDefaultReqExample(),
+    autoFix: true,
 };
 /**
  * Collected configuration errors encountered while resolving options.
@@ -119,6 +120,8 @@ function resolveOptions(rawOptions) {
     const flatReqPattern = user?.requirementIdPattern;
     const nestedReqExample = user?.req?.example;
     const flatReqExample = user?.requirementIdExample;
+    const autoFixFlag = user?.autoFix;
+    const autoFix = typeof autoFixFlag === "boolean" ? autoFixFlag : true;
     const storyPattern = resolvePattern({
         nestedPattern: nestedStoryPattern,
         nestedFieldName: "story.pattern",
@@ -140,6 +143,7 @@ function resolveOptions(rawOptions) {
         storyExample,
         reqPattern,
         reqExample,
+        autoFix,
     };
     return resolvedDefaults;
 }

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

@@ -39,7 +39,7 @@ exports.STORY_EXAMPLE_PATH = "docs/stories/005.0-DEV-EXAMPLE.story.md";
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
 function collapseAnnotationValue(value) {
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-MULTILINE-SUPPORT
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-MULTILINE-SUPPORT
     return value.replace(/\s+/g, "");
 }
 /**
@@ -62,42 +62,42 @@ function collapseAnnotationValue(value) {
  */
 function getFixedStoryPath(original) {
     // @story docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md | REQ-AUTOFIX-SAFE - Reject auto-fix when the path contains ".." traversal segments to avoid broadening the reference.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by rejecting paths that use unsafe traversal segments.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by rejecting paths that use unsafe traversal segments.
     if (original.includes("..")) {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
-        // @implements docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-SAFE
-        // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-AUTOFIX-SAFE
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
+        // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-SAFE
+        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-AUTOFIX-SAFE
         return null;
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md | REQ-AUTOFIX-FORMAT - Leave correctly formatted ".story.md" paths unchanged so diagnostics are not hidden by redundant fixes.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by recognizing already valid ".story.md" paths without altering them.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by recognizing already valid ".story.md" paths without altering them.
     if (/\.story\.md$/.test(original)) {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
-        // @implements docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT
-        // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-AUTOFIX-FORMAT
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
+        // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT
+        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-AUTOFIX-FORMAT
         return null;
     }
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE - When ".story" is present but ".md" is missing, append only the extension without altering the base path.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by completing a partially correct ".story" suffix to the canonical ".story.md".
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by completing a partially correct ".story" suffix to the canonical ".story.md".
     if (/\.story$/.test(original)) {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
-        // @implements docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE
-        // @implements docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
+        // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE
+        // @supports docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
         return `${original}.md`;
     }
     // @story docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE - Normalize plain ".md" doc paths to ".story.md" while keeping the rest of the path intact.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by transforming generic ".md" references into canonical ".story.md" story paths.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces correctness of the story identifier by transforming generic ".md" references into canonical ".story.md" story paths.
     if (/\.md$/.test(original)) {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
-        // @implements docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE
-        // @implements docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
+        // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE
+        // @supports docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
         return original.replace(/\.md$/, ".story.md");
     }
     // @story docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE REQ-AUTOFIX-SAFE - For bare paths with no extension, append ".story.md" as a canonical story reference without touching the directory.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence and correctness of the story identifier by supplying the standard ".story.md" suffix when no extension is provided.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
-    // @implements docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE REQ-AUTOFIX-SAFE
-    // @implements docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence and correctness of the story identifier by supplying the standard ".story.md" suffix when no extension is provided.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT
+    // @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE REQ-AUTOFIX-SAFE
+    // @supports docs/stories/010.2-REQ-STORY-PATH-AUTOFIX.story.md REQ-AUTOFIX-FORMAT
     return `${original}.story.md`;
 }
 /**
@@ -112,14 +112,14 @@ function getFixedStoryPath(original) {
 function buildStoryErrorMessage(kind, value, options) {
     const example = options.storyExample || exports.STORY_EXAMPLE_PATH;
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md | REQ-ERROR-SPECIFICITY - Use a dedicated message variant when the @story value is completely missing.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence of the story identifier by emitting a targeted message when the @story value is absent.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence of the story identifier by emitting a targeted message when the @story value is absent.
     if (kind === "missing") {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-        // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
+        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
         return `Missing story path for @story annotation. Expected a path like "${example}".`;
     }
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-    // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
+    // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
     return `Invalid story path "${value ?? ""}" for @story annotation. Expected a path like "${example}".`;
 }
 /**
@@ -134,13 +134,13 @@ function buildStoryErrorMessage(kind, value, options) {
 function buildReqErrorMessage(kind, value, options) {
     const example = options.reqExample || (0, valid_annotation_options_1.getDefaultReqExample)();
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md | REQ-ERROR-SPECIFICITY - Distinguish a completely missing @req from one that is present but malformed.
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence of the requirement identifier by emitting a specific message when the @req value is missing.
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-REQ-FORMAT REQ-ERROR-SPECIFICITY - Enforces presence of the requirement identifier by emitting a specific message when the @req value is missing.
     if (kind === "missing") {
-        // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-        // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+        // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
+        // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
         return `Missing requirement ID for @req annotation. Expected an identifier like "${example}".`;
     }
-    // @implements docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
-    // @implements docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
+    // @supports docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md REQ-ERROR-SPECIFICITY
+    // @supports docs/stories/010.1-REQ-STORY-PATH-STRICTNESS.story.md REQ-ERROR-SPECIFICITY
     return `Invalid requirement ID "${value ?? ""}" for @req annotation. Expected an identifier like "${example}" (uppercase letters, numbers, and dashes only).`;
 }

package/lib/src/rules/helpers/valid-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/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 {};