eslint-plugin-traceability 1.13.1 → 1.14.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.13.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.13.0...v1.13.1) (2025-12-08)
+# [1.14.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.13.1...v1.14.0) (2025-12-08)
 
 
-### Bug Fixes
+### Features
 
-* refine no-redundant-annotation rule tests and behavior ([7d72670](https://github.com/voder-ai/eslint-plugin-traceability/commit/7d726702e3ad2268778c06de3f3a9673033e3a61))
+* support inline [@supports](https://github.com/supports) migration in prefer-supports-annotation rule ([32b064d](https://github.com/voder-ai/eslint-plugin-traceability/commit/32b064daee35d867d74c3f4f9041c4b780918559))
 
 # Changelog
 

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

@@ -186,7 +186,7 @@ function hasMultipleStories(storyPaths) {
  *
  * @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) {
+function processBlockComment(comment, context) {
     const { hasStory, hasReq, hasImplements, storyPaths } = analyzeComment(comment);
     if (!hasStory || !hasReq) {
         return;
@@ -215,6 +215,137 @@ function processComment(comment, context) {
         fix: fix ?? undefined,
     });
 }
+function getLinePrefixFromText(fullText) {
+    const match = fullText.match(/^(\s*\/\/\s*)/);
+    return match ? match[1] : "";
+}
+function tryBuildInlineAutoFix(context, comments, storyIndex, reqIndices) {
+    const sourceCode = context.getSourceCode();
+    const storyComment = comments[storyIndex];
+    const storyNormalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(storyComment.value || "");
+    if (!storyNormalized || !/^@story\b/.test(storyNormalized)) {
+        return null;
+    }
+    const storyParts = storyNormalized.split(/\s+/);
+    if (storyParts.length !== MIN_STORY_TOKENS) {
+        return null;
+    }
+    const storyPath = storyParts[1];
+    const reqIds = [];
+    for (const idx of reqIndices) {
+        const reqComment = comments[idx];
+        const reqNormalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(reqComment.value || "");
+        if (!reqNormalized || !/^@req\b/.test(reqNormalized)) {
+            return null;
+        }
+        const reqParts = reqNormalized.split(/\s+/);
+        if (reqParts.length !== MIN_REQ_TOKENS) {
+            return null;
+        }
+        reqIds.push(reqParts[1]);
+    }
+    if (!reqIds.length) {
+        return null;
+    }
+    const fullText = sourceCode.text.slice(storyComment.range[0], storyComment.range[1]);
+    const linePrefix = getLinePrefixFromText(fullText);
+    const implAnnotation = `@supports ${storyPath} ${reqIds.join(" ")}`;
+    const implLine = `${linePrefix}${implAnnotation}`;
+    const start = storyComment.range[0];
+    const end = comments[reqIndices[reqIndices.length - 1]].range[1];
+    return (fixer) => fixer.replaceTextRange([start, end], implLine);
+}
+function handleInlineStorySequence(context, group, startIndex) {
+    const n = group.length;
+    const current = group[startIndex];
+    const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
+    if (!normalized || !/^@story\b/.test(normalized)) {
+        return startIndex + 1;
+    }
+    if (/^@supports\b/.test(normalized)) {
+        return startIndex + 1;
+    }
+    const storyIndex = startIndex;
+    const reqIndices = [];
+    let j = startIndex + 1;
+    while (j < n) {
+        const next = group[j];
+        const nextNormalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(next.value || "");
+        if (!nextNormalized || /^@supports\b/.test(nextNormalized)) {
+            break;
+        }
+        if (/^@req\b/.test(nextNormalized)) {
+            reqIndices.push(j);
+            j += 1;
+            continue;
+        }
+        break;
+    }
+    if (reqIndices.length === 0) {
+        context.report({
+            node: current,
+            messageId: "preferImplements",
+        });
+        return startIndex + 1;
+    }
+    const fix = tryBuildInlineAutoFix(context, group, storyIndex, reqIndices);
+    if (fix) {
+        context.report({
+            node: current,
+            messageId: "preferImplements",
+            fix,
+        });
+    }
+    else {
+        context.report({
+            node: current,
+            messageId: "preferImplements",
+        });
+    }
+    return reqIndices[reqIndices.length - 1] + 1;
+}
+function processInlineGroup(context, group) {
+    if (group.length === 0)
+        return;
+    const n = group.length;
+    let i = 0;
+    while (i < n) {
+        const current = group[i];
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
+        if (!normalized || !/^@story\b/.test(normalized)) {
+            i += 1;
+            continue;
+        }
+        i = handleInlineStorySequence(context, group, i);
+    }
+}
+/**
+ * Scan sequences of Line comments for inline legacy @story/@req patterns and
+ * report diagnostics and optional auto-fixes.
+ */
+function processInlineComments(context, lineComments) {
+    if (!lineComments.length)
+        return;
+    // Group by contiguous line numbers
+    let group = [lineComments[0]];
+    const flushGroup = () => {
+        processInlineGroup(context, group);
+        group = [];
+    };
+    for (let idx = 1; idx < lineComments.length; idx++) {
+        const prev = lineComments[idx - 1];
+        const curr = lineComments[idx];
+        if (curr.loc.start.line === prev.loc.start.line + 1 &&
+            curr.loc.start.column === prev.loc.start.column) {
+            group.push(curr);
+        }
+        else {
+            flushGroup();
+            group.push(curr);
+        }
+    }
+    flushGroup();
+}
 /**
  * ESLint rule: prefer-implements-annotation
  *
@@ -292,11 +423,12 @@ const preferImplementsAnnotationRule = {
              */
             Program() {
                 const comments = sourceCode.getAllComments() || [];
-                comments
-                    .filter((comment) => comment.type === "Block")
-                    .forEach((comment) => {
-                    processComment(comment, context);
+                const blockComments = comments.filter((comment) => comment.type === "Block");
+                blockComments.forEach((comment) => {
+                    processBlockComment(comment, context);
                 });
+                const lineComments = comments.filter((comment) => comment.type === "Line");
+                processInlineComments(context, lineComments);
             },
         };
     },

package/lib/tests/rules/prefer-implements-annotation.test.js

@@ -87,6 +87,29 @@ describe("prefer-supports-annotation / prefer-implements-annotation aliasing (St
             code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md additional descriptive text\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction complexStoryNoAutoFix() {}`,
             errors: [{ messageId: "preferImplements" }],
         },
+        {
+            name: "[REQ-INLINE-COMMENT-SUPPORT] single inline // @story + // @req auto-fixes to single // @supports line above function",
+            code: `// @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md\n// @req REQ-INLINE-COMMENT-SUPPORT\nfunction inlineLegacy() {}`,
+            output: `// @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-INLINE-COMMENT-SUPPORT\nfunction inlineLegacy() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-INLINE-COMMENT-SUPPORT] single inline // @story with multiple // @req lines auto-fixes to single // @supports containing all REQ IDs",
+            code: `// @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md\n// @req REQ-INLINE-COMMENT-SUPPORT\n// @req REQ-BRANCH-POSITION-PRESERVE\nfunction inlineMultiReq() {}`,
+            output: `// @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-INLINE-COMMENT-SUPPORT REQ-BRANCH-POSITION-PRESERVE\nfunction inlineMultiReq() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-INLINE-COMMENT-SUPPORT] inline // @story + // @req above statement is auto-fixed preserving branch position (REQ-BRANCH-POSITION-PRESERVE)",
+            code: `if (flag) {\n  // @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md\n  // @req REQ-BRANCH-POSITION-PRESERVE\n  doSomething();\n}`,
+            output: `if (flag) {\n  // @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-BRANCH-POSITION-PRESERVE\n  doSomething();\n}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-INLINE-COMMENT-SUPPORT] complex inline // @req content is not safely auto-fixable but still reports preferImplements",
+            code: `// @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md\n// @req REQ-INLINE-COMMENT-SUPPORT extra description inline\nfunction inlineComplexReqNoAutoFix() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
     ];
     ruleTester.run("prefer-implements-annotation", prefer_implements_annotation_1.default, {
         valid,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",

package/user-docs/api-reference.md

@@ -349,7 +349,7 @@ Main behaviors:
 Deliberate non‑targets and ignored comments:
 
 - JSDoc blocks that contain **only** `@story`, **only** `@req`, or **only** `@supports` are **not** modified by this rule. They remain valid and continue to be governed solely by the core rules such as `require-story-annotation`, `require-req-annotation`, and `valid-annotation-format`.
-- Inline or line comments like `// @story ...`, `// @req ...`, or `// @supports ...` are intentionally ignored by this migration helper; they are still checked by the underlying validation rules where applicable.
+- Inline or line comments like `// @story ...`, `// @req ...`, or `// @supports ...` are also supported in a limited, migration‑oriented way: when the rule detects a simple, consecutive pair or small run of `// @story ...` and `// @req ...` lines that are directly attached to a function or branch, it can, in `--fix` mode, consolidate them into a single `// @supports ...` line while preserving indentation and the comment’s relative position next to the code. More complex inline patterns (such as mixed traceability and non‑traceability content, multiple distinct stories, or interleaved unrelated comments) are still reported without auto‑fix for safety. As with JSDoc migration, this behavior is opt‑in: the rule remains disabled by default and must be explicitly enabled with your desired severity when you are ready to start migrating inline annotations.
 - Any block that does not match the “single story + simple requirements, no supports” shape is treated conservatively: the rule may report a diagnostic to flag the legacy/mixed pattern, but it will not rewrite comments unless it is clearly safe.
 
 Interaction with other rules: