eslint-plugin-traceability 1.6.5 → 1.7.1

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

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-format-internal");
+// Maximum number of distinct @story paths allowed before treating as "multi-story".
+// @req REQ-MULTI-STORY-DETECT - Centralized threshold constant for detecting multi-story patterns
+const MULTI_STORY_THRESHOLD = 1;
+// Minimum number of tokens required for a valid @story annotation line.
+// @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+// @req REQ-MULTI-STORY-DETECT
+const MIN_STORY_TOKENS = 2;
+// Minimum number of tokens required for a valid @req annotation line, aligned with story tokens.
+const MIN_REQ_TOKENS = MIN_STORY_TOKENS;
+// Length of the opening "/*" portion of a block comment prefix.
+const COMMENT_PREFIX_LENGTH = 2;
+function collectStoryAndReqMetadata(comment) {
+    const rawValue = comment.value || "";
+    const rawLines = rawValue.split(/\r?\n/);
+    const storyLineIndices = [];
+    const reqLineIndices = [];
+    const reqIds = [];
+    let storyPath = null;
+    rawLines.forEach((rawLine, index) => {
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(rawLine);
+        if (!normalized)
+            return;
+        if (/^@implements\b/.test(normalized)) {
+            // Mixed @implements usage should have been filtered out earlier
+            return;
+        }
+        if (/^@story\b/.test(normalized)) {
+            const parts = normalized.split(/\s+/);
+            if (parts.length === MIN_STORY_TOKENS) {
+                storyLineIndices.push(index);
+                storyPath = parts[1];
+            }
+            else {
+                storyPath = null;
+            }
+            return;
+        }
+        if (/^@req\b/.test(normalized)) {
+            const parts = normalized.split(/\s+/);
+            if (parts.length === MIN_REQ_TOKENS) {
+                reqLineIndices.push(index);
+                reqIds.push(parts[1]);
+            }
+            else {
+                // Complex @req form; bail out entirely.
+                storyPath = null;
+            }
+        }
+    });
+    return { storyLineIndices, reqLineIndices, reqIds, storyPath };
+}
+function applyImplementsReplacement(context, comment, details) {
+    const { storyIdx, allIndicesToRemove, storyPath, reqIds } = details;
+    const rawValue = comment.value || "";
+    const rawLines = rawValue.split(/\r?\n/);
+    const implAnnotation = `@implements ${storyPath} ${reqIds.join(" ")}`;
+    // Determine the leading prefix (indentation and `*`) from the original @story line
+    const storyRawLine = rawLines[storyIdx];
+    const prefixMatch = storyRawLine.match(/^(\s*\*?\s*)/);
+    const linePrefix = prefixMatch ? prefixMatch[1] : "";
+    const implementsLine = `${linePrefix}${implAnnotation}`;
+    const fixedLines = [];
+    rawLines.forEach((line, index) => {
+        if (index === storyIdx) {
+            fixedLines.push(implementsLine);
+            return;
+        }
+        if (allIndicesToRemove.has(index)) {
+            return;
+        }
+        fixedLines.push(line);
+    });
+    const fixedValue = fixedLines.join("\n");
+    const sourceCode = context.getSourceCode();
+    return (fixer) => fixer.replaceTextRange([comment.range[0], comment.range[1]], sourceCode.text.slice(comment.range[0], comment.range[0] + COMMENT_PREFIX_LENGTH) +
+        fixedValue +
+        "*/");
+}
+/**
+ * Build an ESLint auto-fix for simple single-story `@story` + `@req` JSDoc
+ * blocks, converting them to a single `@implements` annotation while
+ * preserving the original comment formatting.
+ *
+ * The fixer is intentionally conservative and only activates when:
+ * - There is exactly one distinct `@story` path.
+ * - Exactly one `@story` line is present.
+ * - At least one `@req` line is present.
+ * - Each `@req` line has the simple form `@req <REQ-ID>` (no extra tokens).
+ *
+ * When applicable, the fix:
+ * - Removes the original `@story` and `@req` lines.
+ * - Inserts a single `@implements` line in their place, preserving the
+ *   original leading comment prefix (indentation and `*` markers).
+ *
+ * More complex patterns remain diagnostics-only with no fix to avoid
+ * producing invalid or ambiguous output.
+ *
+ * @implements docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.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
+ * @req REQ-VALID-OUTPUT - Avoid emitting auto-fixes for complex or ambiguous patterns
+ */
+function buildImplementsAutoFix(context, comment, storyPaths) {
+    if (storyPaths.size !== 1)
+        return null;
+    const { storyLineIndices, reqLineIndices, reqIds, storyPath } = collectStoryAndReqMetadata(comment);
+    if (storyPaths.size !== 1 ||
+        storyLineIndices.length !== 1 ||
+        reqLineIndices.length < 1 ||
+        storyPath === null) {
+        return null;
+    }
+    const storyIdx = storyLineIndices[0];
+    const allIndicesToRemove = new Set([
+        ...storyLineIndices,
+        ...reqLineIndices,
+    ]);
+    return applyImplementsReplacement(context, comment, {
+        storyIdx,
+        allIndicesToRemove,
+        storyPath,
+        reqIds,
+    });
+}
+function analyzeComment(comment) {
+    const rawLines = (comment.value || "").split(/\r?\n/);
+    let hasStory = false;
+    let hasReq = false;
+    let hasImplements = false;
+    const storyPaths = new Set();
+    rawLines.forEach((rawLine) => {
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(rawLine);
+        if (!normalized)
+            return;
+        if (/^@implements\b/.test(normalized)) {
+            hasImplements = true;
+            return;
+        }
+        if (/^@story\b/.test(normalized)) {
+            hasStory = true;
+            const parts = normalized.split(/\s+/);
+            if (parts.length >= MIN_STORY_TOKENS) {
+                storyPaths.add(parts[1]);
+            }
+            return;
+        }
+        if (/^@req\b/.test(normalized)) {
+            hasReq = true;
+        }
+    });
+    return { hasStory, hasReq, hasImplements, storyPaths };
+}
+function hasMultipleStories(storyPaths) {
+    // @req REQ-MULTI-STORY-DETECT - Use named threshold constant instead of a magic number
+    return storyPaths.size > MULTI_STORY_THRESHOLD;
+}
+function processComment(comment, context) {
+    const { hasStory, hasReq, hasImplements, storyPaths } = analyzeComment(comment);
+    if (!hasStory || !hasReq) {
+        return;
+    }
+    if (hasImplements) {
+        context.report({
+            node: comment,
+            messageId: "cannotAutoFix",
+            data: {
+                reason: "comment mixes @story/@req with existing @implements annotations",
+            },
+        });
+        return;
+    }
+    if (hasMultipleStories(storyPaths)) {
+        context.report({
+            node: comment,
+            messageId: "multiStoryDetected",
+        });
+        return;
+    }
+    const fix = buildImplementsAutoFix(context, comment, storyPaths);
+    context.report({
+        node: comment,
+        messageId: "preferImplements",
+        fix: fix ?? undefined,
+    });
+}
+/**
+ * ESLint rule: prefer-implements-annotation
+ *
+ * Recommend migrating from legacy `@story` + `@req` annotations to the
+ * newer `@implements` format. This rule is **disabled by default** and
+ * is intended as an optional, opt-in migration aid.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
+ */
+const preferImplementsAnnotationRule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Recommend using @implements instead of legacy @story + @req annotations (optional migration rule)",
+            recommended: false,
+        },
+        // Auto-fix support will be wired in a later iteration; the rule starts as
+        // a recommendation-only warning with no code modifications.
+        fixable: "code",
+        messages: {
+            /**
+             * Recommend migrating simple, single-story @story + @req blocks to a
+             * single @implements line. Auto-fix is provided where safe in a
+             * follow-up iteration.
+             *
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @req REQ-OPTIONAL-WARNING
+             */
+            preferImplements: "Consider using @implements instead of @story + @req for clearer traceability. Run ESLint with --fix to auto-convert.",
+            /**
+             * Report situations where the rule detects a legacy annotation pattern
+             * but cannot safely provide an automatic fix. The `reason` field gives
+             * a short, human-readable explanation to guide manual migration.
+             *
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @req REQ-MULTI-STORY-DETECT
+             */
+            cannotAutoFix: "Cannot auto-fix: {{reason}}. Manual migration to @implements required.",
+            /**
+             * Specialized message for the most common non-fixable case where more
+             * than one @story annotation appears in the same block, indicating a
+             * likely multi-story integration that must be converted manually.
+             *
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @req REQ-MULTI-STORY-DETECT
+             */
+            multiStoryDetected: "Multiple @story annotations detected in the same comment block. Manually convert to separate @implements lines.",
+        },
+        schema: [],
+    },
+    /**
+     * Rule entrypoint.
+     *
+     * This initial implementation focuses on **detection and messaging only**:
+     * it surfaces recommendations when legacy `@story` + `@req` combinations are
+     * present but does not yet perform automatic code modifications.
+     *
+     * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+     * @req REQ-OPTIONAL-WARNING
+     * @req REQ-MULTI-STORY-DETECT
+     */
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        return {
+            /**
+             * Program-level visitor that scans all comments for legacy
+             * `@story` + `@req` usage and emits recommendation diagnostics.
+             *
+             * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+             * @req REQ-OPTIONAL-WARNING - Emit recommendations when legacy annotations are detected
+             * @req REQ-MULTI-STORY-DETECT - Detect multi-story and mixed annotation patterns
+             */
+            Program() {
+                const comments = sourceCode.getAllComments() || [];
+                comments
+                    .filter((comment) => comment.type === "Block")
+                    .forEach((comment) => {
+                    processComment(comment, context);
+                });
+            },
+        };
+    },
+};
+exports.default = preferImplementsAnnotationRule;