eslint-plugin-traceability 1.9.0 → 1.10.1

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

@@ -0,0 +1,270 @@
+"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)) {
+        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;
+}

package/lib/src/rules/require-test-traceability.d.ts

@@ -6,6 +6,8 @@ import type { Rule } from "eslint";
  * - Test files have a file-level @supports annotation listing tested requirements.
  * - describe()/it()/test()/context() blocks include story and requirement references
  *   following project conventions.
+ * - When ESLint runs with --fix, safe, non-semantic auto-fixes are applied for
+ *   missing file-level @supports and malformed [REQ-XXX] prefixes in test names.
  *
  * @story docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
  * @req REQ-TEST-FILE-SUPPORTS
@@ -16,6 +18,7 @@ import type { Rule } from "eslint";
  * @req REQ-TEST-FRAMEWORK-COMPAT
  * @req REQ-TEST-NESTED-DESCRIBE
  * @req REQ-TEST-ERROR-CONTEXT
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-PLACEHOLDER REQ-TEST-FIX-NO-INFERENCE
  */
 declare const rule: Rule.RuleModule;
 export default rule;

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

@@ -1,62 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-/**
- * Determine if a file should be treated as a test file based on patterns.
- *
- * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT
- */
-function determineIsTestFile(filename, rawPatterns = [
-    "/tests/",
-    "/test/",
-    "/__tests__/",
-    ".test.",
-    ".spec.",
-]) {
-    return rawPatterns.some((pattern) => filename.includes(pattern.replace("**", "")));
-}
-/**
- * Ensure the file has a @supports annotation listing tested requirements.
- *
- * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS REQ-TEST-SUPPORTS-VALID
- */
-function ensureFileSupportsAnnotation(context, sourceCode) {
-    const fileComments = sourceCode.getAllComments() || [];
-    const fileHasSupports = fileComments.some((comment) => /@supports\b/.test(comment.value || ""));
-    if (!fileHasSupports) {
-        const node = fileComments[0] || (sourceCode.ast && sourceCode.ast);
-        context.report({
-            node: node,
-            messageId: "missingFileSupports",
-        });
-    }
-}
-/**
- * Check if a callee name corresponds to a test framework function.
- *
- * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FRAMEWORK-COMPAT
- */
-function isTestCallName(name) {
-    return ["describe", "it", "test", "context"].includes(name);
-}
-function getCalleeName(node) {
-    if (node.callee.type === "Identifier") {
-        return node.callee.name;
-    }
-    if (node.callee.type === "MemberExpression" &&
-        node.callee.object.type === "Identifier") {
-        return node.callee.object.name;
-    }
-    return null;
-}
-function getFirstArgumentLiteral(node) {
-    const arg = node.arguments && node.arguments[0];
-    if (!arg)
-        return null;
-    if (arg.type === "Literal" && typeof arg.value === "string") {
-        return arg.value;
-    }
-    return null;
-}
+const require_test_traceability_helpers_1 = require("./helpers/require-test-traceability-helpers");
 /**
  * Enforce traceability conventions in test files.
  *
@@ -64,6 +8,8 @@ function getFirstArgumentLiteral(node) {
  * - Test files have a file-level @supports annotation listing tested requirements.
  * - describe()/it()/test()/context() blocks include story and requirement references
  *   following project conventions.
+ * - When ESLint runs with --fix, safe, non-semantic auto-fixes are applied for
+ *   missing file-level @supports and malformed [REQ-XXX] prefixes in test names.
  *
  * @story docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
  * @req REQ-TEST-FILE-SUPPORTS
@@ -74,6 +20,7 @@ function getFirstArgumentLiteral(node) {
  * @req REQ-TEST-FRAMEWORK-COMPAT
  * @req REQ-TEST-NESTED-DESCRIBE
  * @req REQ-TEST-ERROR-CONTEXT
+ * @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-TEMPLATE REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-PLACEHOLDER REQ-TEST-FIX-NO-INFERENCE
  */
 const rule = {
     meta: {
@@ -82,6 +29,7 @@ const rule = {
             description: "Enforce traceability annotations and naming conventions in test files",
             recommended: "error",
         },
+        fixable: "code",
         schema: [
             {
                 type: "object",
@@ -108,6 +56,17 @@ const rule = {
                         type: "string",
                         default: "Story [0-9]+\\.[0-9]+-",
                     },
+                    autoFixTestTemplate: {
+                        type: "boolean",
+                        default: true,
+                    },
+                    autoFixTestPrefixFormat: {
+                        type: "boolean",
+                        default: true,
+                    },
+                    testSupportsTemplate: {
+                        type: "string",
+                    },
                 },
                 additionalProperties: false,
             },
@@ -120,49 +79,33 @@ const rule = {
     },
     create(context) {
         const filename = context.getFilename();
-        const options = (context.options && context.options[0]) || {};
+        const rawOptions = (context.options && context.options[0]) || {};
         const { testFilePatterns = [
             "/tests/",
             "/test/",
-            "/__tests__/",
+            "/__tests__",
             ".test.",
             ".spec.",
-        ], requireDescribeStory = true, requireTestReqPrefix = true, describePattern = "Story [0-9]+\\.[0-9]+-", } = options;
-        const isTestFile = determineIsTestFile(filename, testFilePatterns);
-        if (!isTestFile) {
+        ], requireDescribeStory = true, requireTestReqPrefix = true, describePattern = "Story [0-9]+\\.[0-9]+-", autoFixTestTemplate = true, autoFixTestPrefixFormat = true, testSupportsTemplate, } = rawOptions;
+        const isTestFile = (0, require_test_traceability_helpers_1.determineIsTestFile)(filename, testFilePatterns);
+        if (!isTestFile)
             return {};
-        }
         const sourceCode = context.getSourceCode();
-        ensureFileSupportsAnnotation(context, sourceCode);
+        (0, require_test_traceability_helpers_1.ensureFileSupportsAnnotation)(context, sourceCode, {
+            autoFixTestTemplate,
+            testSupportsTemplate,
+        });
         const describeRegex = new RegExp(describePattern);
         return {
             // @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX REQ-TEST-NESTED-DESCRIBE REQ-TEST-ERROR-CONTEXT
-            CallExpression(node) {
-                const calleeName = getCalleeName(node);
-                if (!calleeName || !isTestCallName(calleeName)) {
-                    return;
-                }
-                const description = getFirstArgumentLiteral(node);
-                if (!description)
-                    return;
-                if (requireDescribeStory && calleeName === "describe") {
-                    if (!describeRegex.test(description)) {
-                        context.report({
-                            node: node,
-                            messageId: "missingDescribeStory",
-                        });
-                    }
-                }
-                if (requireTestReqPrefix &&
-                    (calleeName === "it" || calleeName === "test")) {
-                    if (!/^\[REQ-[^\]]+]/.test(description)) {
-                        context.report({
-                            node: node,
-                            messageId: "missingReqPrefix",
-                        });
-                    }
-                }
-            },
+            // @supports docs/stories/021.0-DEV-TEST-ANNOTATION-AUTO-FIX.story.md REQ-TEST-FIX-PREFIX-FORMAT REQ-TEST-FIX-SAFE REQ-TEST-FIX-PRESERVE REQ-TEST-FIX-NO-INFERENCE
+            CallExpression: (0, require_test_traceability_helpers_1.handleCallExpression)(context, {
+                sourceCode,
+                describeRegex,
+                requireDescribeStory,
+                requireTestReqPrefix,
+                autoFixTestPrefixFormat,
+            }),
         };
     },
 };