eslint-plugin-traceability 1.6.4 → 1.7.0

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

@@ -1,16 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const STORY_EXAMPLE_PATH = "docs/stories/005.0-DEV-EXAMPLE.story.md";
-/**
- * Constant to represent the "tag not found" index when searching
- * for @story or @req within a comment.
- *
- * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- * @req REQ-AUTOFIX-PRESERVE - Avoid risky text replacements when the annotation tag cannot be located
- */
-const TAG_NOT_FOUND_INDEX = -1;
+const valid_annotation_options_1 = require("./helpers/valid-annotation-options");
+const valid_annotation_utils_1 = require("./helpers/valid-annotation-utils");
 /**
  * Normalize a raw comment line to make annotation parsing more robust.
  *
@@ -35,92 +26,57 @@ function normalizeCommentLine(rawLine) {
     return trimmed.slice(annotationMatch.index);
 }
 /**
- * Collapse internal whitespace in an annotation value so that multi-line
- * annotations are treated as a single logical value.
- *
- * Example:
- *   "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md" across
- *   multiple lines will be collapsed before validation.
- *
- * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
- * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- */
-function collapseAnnotationValue(value) {
-    return value.replace(/\s+/g, "");
-}
-/**
- * Build a detailed error message for invalid @story annotations.
- *
- * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @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
- */
-function buildStoryErrorMessage(kind, value) {
-    if (kind === "missing") {
-        return `Missing story path for @story annotation. Expected a path like "${STORY_EXAMPLE_PATH}".`;
-    }
-    return `Invalid story path "${value ?? ""}" for @story annotation. Expected a path like "${STORY_EXAMPLE_PATH}".`;
-}
-/**
- * Build a detailed error message for invalid @req annotations.
+ * 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
- * @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
  */
-function buildReqErrorMessage(kind, value) {
-    if (kind === "missing") {
-        return 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".';
-    }
-    return `Invalid requirement ID "${value ?? ""}" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).`;
+function reportInvalidStoryFormat(context, comment, collapsed, options) {
+    context.report({
+        node: comment,
+        messageId: "invalidStoryFormat",
+        data: { details: (0, valid_annotation_utils_1.buildStoryErrorMessage)("invalid", collapsed, options) },
+    });
 }
 /**
- * Attempt a minimal, safe auto-fix for common @story path suffix issues.
+ * Compute the text replacement for an invalid @story annotation within a comment.
  *
- * Only handles:
- *   - missing ".md"
- *   - missing ".story.md"
- * and skips any paths with traversal segments (e.g. "..").
+ * 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 the fixed path when safe, or null if no fix should be applied.
+ * Returns null when the tag or value cannot be safely located.
  *
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and never broaden the referenced path
- * @req REQ-AUTOFIX-PRESERVE - Preserve surrounding formatting when normalizing story path suffixes
+ * @req REQ-AUTOFIX-SAFE
+ * @req REQ-AUTOFIX-PRESERVE
  */
-function getFixedStoryPath(original) {
-    if (original.includes("..")) {
+function createStoryFix(context, comment, fixed) {
+    const sourceCode = context.getSourceCode();
+    const commentText = sourceCode.getText(comment);
+    const search = "@story";
+    const tagIndex = commentText.indexOf(search);
+    if (tagIndex === valid_annotation_utils_1.TAG_NOT_FOUND_INDEX) {
         return null;
     }
-    if (/\.story\.md$/.test(original)) {
+    const afterTagIndex = tagIndex + search.length;
+    const rest = commentText.slice(afterTagIndex);
+    const valueMatch = rest.match(/[^\S\r\n]*([^\r\n*]+)/);
+    if (!valueMatch || valueMatch.index === undefined) {
         return null;
     }
-    if (/\.story$/.test(original)) {
-        return `${original}.md`;
-    }
-    if (/\.md$/.test(original)) {
-        return original.replace(/\.md$/, ".story.md");
-    }
-    return `${original}.story.md`;
-}
-/**
- * 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
- * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- */
-function reportInvalidStoryFormat(context, comment, collapsed) {
-    context.report({
-        node: comment,
-        messageId: "invalidStoryFormat",
-        data: { details: buildStoryErrorMessage("invalid", collapsed) },
-    });
+    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
@@ -141,37 +97,18 @@ function reportInvalidStoryFormat(context, comment, collapsed) {
  * @req REQ-AUTOFIX-PRESERVE - Auto-fix must preserve surrounding formatting and comments
  */
 function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
-    const sourceCode = context.getSourceCode();
-    const commentText = sourceCode.getText(comment);
-    const search = "@story";
-    const tagIndex = commentText.indexOf(search);
-    if (tagIndex === TAG_NOT_FOUND_INDEX) {
-        reportInvalidStoryFormat(context, comment, collapsed);
-        return;
-    }
-    const afterTagIndex = tagIndex + search.length;
-    const rest = commentText.slice(afterTagIndex);
-    const valueMatch = rest.match(/[^\S\r\n]*([^\r\n*]+)/);
-    if (!valueMatch || valueMatch.index === undefined) {
-        reportInvalidStoryFormat(context, comment, collapsed);
+    const fixFactory = createStoryFix(context, comment, fixed);
+    if (!fixFactory) {
+        reportInvalidStoryFormat(context, comment, collapsed, (0, valid_annotation_options_1.getResolvedDefaults)());
         return;
     }
-    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,
-    ];
     context.report({
         node: comment,
         messageId: "invalidStoryFormat",
-        data: { details: buildStoryErrorMessage("invalid", collapsed) },
-        fix(fixer) {
-            return fixer.replaceTextRange(fixRange, fixed);
+        data: {
+            details: (0, valid_annotation_utils_1.buildStoryErrorMessage)("invalid", collapsed, (0, valid_annotation_options_1.getResolvedDefaults)()),
         },
+        fix: fixFactory(),
     });
 }
 /**
@@ -183,32 +120,34 @@ function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
  * @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
  */
-function validateStoryAnnotation(context, comment, rawValue) {
+function validateStoryAnnotation(context, comment, rawValue, options) {
     const trimmed = rawValue.trim();
     if (!trimmed) {
         context.report({
             node: comment,
             messageId: "invalidStoryFormat",
-            data: { details: buildStoryErrorMessage("missing", null) },
+            data: { details: (0, valid_annotation_utils_1.buildStoryErrorMessage)("missing", null, options) },
         });
         return;
     }
-    const collapsed = collapseAnnotationValue(trimmed);
-    const pathPattern = /^docs\/stories\/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$/;
+    const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
+    const pathPattern = options.storyPattern;
     if (pathPattern.test(collapsed)) {
         return;
     }
     if (/\s/.test(trimmed)) {
-        reportInvalidStoryFormat(context, comment, collapsed);
+        reportInvalidStoryFormat(context, comment, collapsed, options);
         return;
     }
-    const fixed = getFixedStoryPath(collapsed);
+    const fixed = (0, valid_annotation_utils_1.getFixedStoryPath)(collapsed);
     if (fixed && pathPattern.test(fixed)) {
         reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed);
         return;
     }
-    reportInvalidStoryFormat(context, comment, collapsed);
+    reportInvalidStoryFormat(context, comment, collapsed, options);
 }
 /**
  * Validate a @req annotation value and report detailed errors when needed.
@@ -217,27 +156,101 @@ function validateStoryAnnotation(context, comment, rawValue) {
  * @story docs/stories/008.0-DEV-AUTO-FIX.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
  */
-function validateReqAnnotation(context, comment, rawValue) {
+function validateReqAnnotation(context, comment, rawValue, options) {
     const trimmed = rawValue.trim();
     if (!trimmed) {
         context.report({
             node: comment,
             messageId: "invalidReqFormat",
-            data: { details: buildReqErrorMessage("missing", null) },
+            data: { details: (0, valid_annotation_utils_1.buildReqErrorMessage)("missing", null, options) },
         });
         return;
     }
-    const collapsed = collapseAnnotationValue(trimmed);
-    const reqPattern = /^REQ-[A-Z0-9-]+$/;
+    const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
+    const reqPattern = options.reqPattern;
     if (!reqPattern.test(collapsed)) {
         context.report({
             node: comment,
             messageId: "invalidReqFormat",
-            data: { details: buildReqErrorMessage("invalid", collapsed) },
+            data: { details: (0, valid_annotation_utils_1.buildReqErrorMessage)("invalid", collapsed, 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
+ * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+function finalizePendingAnnotation(context, comment, options, pending) {
+    if (!pending) {
+        return null;
+    }
+    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @req REQ-SYNTAX-VALIDATION - Dispatch validation based on annotation type
+    // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+    if (pending.type === "story") {
+        validateStoryAnnotation(context, comment, pending.value, options);
+    }
+    else {
+        validateReqAnnotation(context, comment, pending.value, options);
+    }
+    return null;
+}
+/**
+ * Process a single normalized comment line and update the pending annotation state.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-SYNTAX-VALIDATION - Start new pending annotation when a tag is found
+ * @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+function processCommentLine({ normalized, pending, context, comment, options, }) {
+    if (!normalized) {
+        return pending;
+    }
+    const isStory = /@story\b/.test(normalized);
+    const isReq = /@req\b/.test(normalized);
+    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @req REQ-SYNTAX-VALIDATION - Start new pending annotation when a tag is found
+    // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+    if (isStory || isReq) {
+        finalizePendingAnnotation(context, comment, options, pending);
+        const value = normalized.replace(/^@story\b|^@req\b/, "").trim();
+        return {
+            type: isStory ? "story" : "req",
+            value,
+            hasValue: value.trim().length > 0,
+        };
+    }
+    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
+    // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+    if (pending) {
+        const continuation = normalized.trim();
+        if (!continuation) {
+            return pending;
+        }
+        const updatedValue = pending.value
+            ? `${pending.value} ${continuation}`
+            : continuation;
+        return {
+            ...pending,
+            value: updatedValue,
+            hasValue: pending.hasValue || continuation.length > 0,
+        };
+    }
+    return pending;
+}
 /**
  * Process a single comment node and validate any @story/@req annotations it contains.
  *
@@ -251,70 +264,20 @@ function validateReqAnnotation(context, comment, rawValue) {
  * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
  */
-function processComment(context, comment) {
+function processComment(context, comment, options) {
     const rawLines = (comment.value || "").split(/\r?\n/);
     let pending = null;
-    /**
-     * 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
-     * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
-     * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
-     */
-    function finalizePending() {
-        if (!pending) {
-            return;
-        }
-        // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-        // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-        // @req REQ-SYNTAX-VALIDATION - Dispatch validation based on annotation type
-        // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
-        if (pending.type === "story") {
-            validateStoryAnnotation(context, comment, pending.value);
-        }
-        else {
-            validateReqAnnotation(context, comment, pending.value);
-        }
-        pending = null;
-    }
     rawLines.forEach((rawLine) => {
         const normalized = normalizeCommentLine(rawLine);
-        if (!normalized) {
-            return;
-        }
-        const isStory = /@story\b/.test(normalized);
-        const isReq = /@req\b/.test(normalized);
-        // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-        // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-        // @req REQ-SYNTAX-VALIDATION - Start new pending annotation when a tag is found
-        // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
-        if (isStory || isReq) {
-            finalizePending();
-            const value = normalized.replace(/^@story\b|^@req\b/, "").trim();
-            pending = {
-                type: isStory ? "story" : "req",
-                value,
-                hasValue: value.trim().length > 0,
-            };
-            return;
-        }
-        // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-        // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-        // @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
-        // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
-        if (pending) {
-            const continuation = normalized.trim();
-            if (!continuation) {
-                return;
-            }
-            pending.value = pending.value
-                ? `${pending.value} ${continuation}`
-                : continuation;
-            pending.hasValue = pending.hasValue || continuation.length > 0;
-        }
+        pending = processCommentLine({
+            normalized,
+            pending,
+            context,
+            comment,
+            options,
+        });
     });
-    finalizePending();
+    finalizePendingAnnotation(context, comment, options, pending);
 }
 exports.default = {
     meta: {
@@ -338,8 +301,14 @@ exports.default = {
              * @req REQ-ERROR-CONSISTENCY - Use shared "Invalid annotation format: {{details}}." message pattern across rules
              */
             invalidReqFormat: "Invalid annotation format: {{details}}.",
+            /**
+             * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+             * @req REQ-REGEX-VALIDATION - Surface configuration errors for invalid regex patterns
+             * @req REQ-BACKWARD-COMP - Preserve behavior by falling back to default patterns on error
+             */
+            invalidRuleConfiguration: "Invalid configuration for valid-annotation-format: {{details}}",
         },
-        schema: [],
+        schema: (0, valid_annotation_options_1.getRuleSchema)(),
         /**
          * This rule's fixable support is limited to safe @story path suffix normalization per Story 008.0.
          * Fixes are limited strictly to adjusting the suffix portion of the @story path (e.g., adding
@@ -348,32 +317,51 @@ exports.default = {
          * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
          * @req REQ-AUTOFIX-SAFE
          * @req REQ-AUTOFIX-PRESERVE
+         * @req REQ-REGEX-VALIDATION - Ensure regex configuration does not affect fix safety
+         * @req REQ-BACKWARD-COMP - Maintain previous auto-fix behavior under invalid configs
          */
         fixable: "code",
     },
     /**
      * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
      * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+     * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
      * @req REQ-SYNTAX-VALIDATION - Ensure rule create function validates annotations syntax
      * @req REQ-FORMAT-SPECIFICATION - Implement formatting checks per specification
      * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+     * @req REQ-REGEX-VALIDATION - Derive validation regexes from shared options helper
+     * @req REQ-BACKWARD-COMP - Fall back to default patterns and continue validation on config errors
      */
     create(context) {
         const sourceCode = context.getSourceCode();
+        const options = (0, valid_annotation_options_1.resolveOptions)(context.options || []);
+        const optionErrors = (0, valid_annotation_options_1.getOptionErrors)();
         return {
             /**
              * Program-level handler that inspects all comments for @story and @req tags
              *
              * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
              * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+             * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
              * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
              * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
              * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+             * @req REQ-REGEX-VALIDATION - Surface regex configuration errors without blocking validation
+             * @req REQ-BACKWARD-COMP - Continue validating comments using default patterns on error
              */
-            Program() {
+            Program(node) {
+                if (optionErrors && optionErrors.length > 0) {
+                    optionErrors.forEach((details) => {
+                        context.report({
+                            node,
+                            messageId: "invalidRuleConfiguration",
+                            data: { details },
+                        });
+                    });
+                }
                 const comments = sourceCode.getAllComments() || [];
                 comments.forEach((comment) => {
-                    processComment(context, comment);
+                    processComment(context, comment, options);
                 });
             },
         };