eslint-plugin-traceability 1.10.0 → 1.11.0

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

@@ -28,3 +28,14 @@ export interface PendingAnnotation {
  * of the line for downstream logic.
  */
 export declare function normalizeCommentLine(rawLine: string): string;
+/**
+ * Detect whether a normalized comment line starts with a non-traceability JSDoc tag.
+ *
+ * This is used to distinguish regular JSDoc tags (e.g. @param, @returns) from
+ * traceability-related annotations such as @story, @req, and @supports.
+ *
+ * @supports docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
+ * @req REQ-JSDOC-BOUNDARY-DETECTION
+ * @req REQ-JSDOC-TAG-COEXISTENCE
+ */
+export declare function isNonTraceabilityJSDocTagLine(normalized: string): boolean;

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

@@ -13,6 +13,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeCommentLine = normalizeCommentLine;
+exports.isNonTraceabilityJSDocTagLine = isNonTraceabilityJSDocTagLine;
 /**
  * Normalize a raw comment line to make annotation parsing more robust.
  *
@@ -34,3 +35,23 @@ function normalizeCommentLine(rawLine) {
     }
     return trimmed.slice(annotationMatch.index);
 }
+/**
+ * Detect whether a normalized comment line starts with a non-traceability JSDoc tag.
+ *
+ * This is used to distinguish regular JSDoc tags (e.g. @param, @returns) from
+ * traceability-related annotations such as @story, @req, and @supports.
+ *
+ * @supports docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md
+ * @req REQ-JSDOC-BOUNDARY-DETECTION
+ * @req REQ-JSDOC-TAG-COEXISTENCE
+ */
+function isNonTraceabilityJSDocTagLine(normalized) {
+    const trimmed = normalized.trimStart();
+    if (!trimmed || !trimmed.startsWith("@")) {
+        return false;
+    }
+    if (/^@(story|req|supports)\b/.test(trimmed)) {
+        return false;
+    }
+    return true;
+}

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

@@ -0,0 +1,125 @@
+/**
+ * Validators and helper functions for the valid-annotation-format rule.
+ *
+ * This module contains the core validation logic that was originally
+ * embedded in src/rules/valid-annotation-format.ts. It is extracted
+ * here to keep the main rule module smaller and easier to read while
+ * preserving existing behavior.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-SPECIFICATION
+ * @req REQ-SYNTAX-VALIDATION
+ * @req REQ-PATH-FORMAT
+ * @req REQ-REQ-FORMAT
+ * @req REQ-MULTILINE-SUPPORT
+ * @req REQ-AUTOFIX-FORMAT
+ * @req REQ-ERROR-SPECIFICITY
+ * @req REQ-REGEX-VALIDATION
+ * @req REQ-BACKWARD-COMP
+ * @req REQ-SUPPORTS-PARSE
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+import type { ResolvedAnnotationOptions } from "./valid-annotation-options";
+import type { PendingAnnotation } from "./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
+ */
+export declare function reportInvalidStoryFormat(context: any, comment: any, collapsed: string, options: ResolvedAnnotationOptions): void;
+/**
+ * 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
+ */
+export declare function createStoryFix(context: any, comment: any, fixed: string): null | (() => any);
+/**
+ * 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.
+ *
+ * @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
+ */
+export declare function reportInvalidStoryFormatWithFix(context: any, comment: any, collapsed: string, fixed: string): void;
+/**
+ * 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
+ */
+export declare function validateStoryAnnotation(context: any, comment: any, rawValue: string, options: ResolvedAnnotationOptions): void;
+/**
+ * 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
+ */
+export declare function validateReqAnnotation(context: any, comment: any, rawValue: string, options: ResolvedAnnotationOptions): void;
+/**
+ * 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
+ */
+export declare function validateImplementsAnnotation(context: any, comment: any, rawValue: string, options: ResolvedAnnotationOptions): void;
+/**
+ * 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
+ */
+export declare function finalizePendingAnnotation(context: any, comment: any, options: ResolvedAnnotationOptions, pending: PendingAnnotation | null): PendingAnnotation | null;

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

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * Validators and helper functions for the valid-annotation-format rule.
+ *
+ * This module contains the core validation logic that was originally
+ * embedded in src/rules/valid-annotation-format.ts. It is extracted
+ * here to keep the main rule module smaller and easier to read while
+ * preserving existing behavior.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-SPECIFICATION
+ * @req REQ-SYNTAX-VALIDATION
+ * @req REQ-PATH-FORMAT
+ * @req REQ-REQ-FORMAT
+ * @req REQ-MULTILINE-SUPPORT
+ * @req REQ-AUTOFIX-FORMAT
+ * @req REQ-ERROR-SPECIFICITY
+ * @req REQ-REGEX-VALIDATION
+ * @req REQ-BACKWARD-COMP
+ * @req REQ-SUPPORTS-PARSE
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportInvalidStoryFormat = reportInvalidStoryFormat;
+exports.createStoryFix = createStoryFix;
+exports.reportInvalidStoryFormatWithFix = reportInvalidStoryFormatWithFix;
+exports.validateStoryAnnotation = validateStoryAnnotation;
+exports.validateReqAnnotation = validateReqAnnotation;
+exports.validateImplementsAnnotation = validateImplementsAnnotation;
+exports.finalizePendingAnnotation = finalizePendingAnnotation;
+const valid_annotation_utils_1 = require("./valid-annotation-utils");
+const valid_implements_utils_1 = require("./valid-implements-utils");
+const valid_annotation_options_1 = require("./valid-annotation-options");
+/**
+ * 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.
+ *
+ * @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)) {
+        if (options.autoFix !== false) {
+            reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed);
+            return;
+        }
+        reportInvalidStoryFormat(context, comment, collapsed, options);
+        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;
+}

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).`;
 }