eslint-plugin-traceability 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [1.13.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.12.1...v1.13.0) (2025-12-07)
+# [1.14.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.13.1...v1.14.0) (2025-12-08)
 
 
 ### Features
 
-* add no-redundant-annotation rule and scope analyzer utilities ([5dfc6a8](https://github.com/voder-ai/eslint-plugin-traceability/commit/5dfc6a897a986ba5999c933e67a3834d9f237c33))
+* 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/no-redundant-annotation.js

@@ -127,6 +127,97 @@ function debugScopePairs(scopeNode, scopePairs) {
     }
     console.log("[no-redundant-annotation] Scope node type=%s pairs=%o", scopeNode && scopeNode.type, Array.from(scopePairs));
 }
+/**
+ * Walk up enclosing scopes starting from the given scope node and
+ * accumulate all story/requirement pairs, limited by maxScopeDepth.
+ *
+ * This keeps REQ-SCOPE-INHERITANCE and REQ-CONFIGURABLE-STRICTNESS
+ * aligned with the story's configuration model while delegating the
+ * actual comment parsing to getScopePairs.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SCOPE-ANALYSIS REQ-SCOPE-INHERITANCE REQ-CONFIGURABLE-STRICTNESS
+ */
+function collectScopePairs(context, startingScopeNode, maxScopeDepth) {
+    const result = new Set();
+    if (!startingScopeNode || maxScopeDepth <= 0) {
+        return result;
+    }
+    let current = startingScopeNode;
+    let depth = 0;
+    while (current && depth < maxScopeDepth) {
+        const parent = current.parent;
+        const pairs = getScopePairs(context, current, parent);
+        for (const key of pairs) {
+            result.add(key);
+        }
+        current = parent;
+        depth += 1;
+    }
+    return result;
+}
+/**
+ * Determine whether a statement is redundant relative to the provided
+ * scopePairs and options, and when so return the associated annotation
+ * comments. Returns null when the statement should not be treated as
+ * redundant.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-STATEMENT-SIGNIFICANCE REQ-CONFIGURABLE-STRICTNESS
+ */
+function getRedundantStatementContext(context, stmt, scopePairs, options) {
+    if (scopePairs.size === 0) {
+        return null;
+    }
+    if (!(0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(stmt, options, branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES)) {
+        return null;
+    }
+    const stmtComments = getStatementComments(context, stmt);
+    if (stmtComments.length === 0) {
+        return null;
+    }
+    const stmtPairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(stmtComments);
+    if (process.env.TRACEABILITY_DEBUG === "1") {
+        console.log("[no-redundant-annotation] Statement type=%s eligible=%s commentCount=%d pairs=%o", stmt && stmt.type, (0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(stmt, options, branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES), stmtComments.length, Array.from(stmtPairs));
+    }
+    if (stmtPairs.size === 0) {
+        return null;
+    }
+    // When emphasis duplication is allowed, treat a single fully-covered
+    // pair as intentional emphasis and skip reporting.
+    if (options.allowEmphasisDuplication && stmtPairs.size === 1) {
+        if ((0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
+            return null;
+        }
+    }
+    if (!(0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
+        return null;
+    }
+    // At this point the statement-level annotations are fully
+    // covered by the parent/ancestor scopes and therefore redundant.
+    const annotationComments = stmtComments.filter((comment) => {
+        const commentText = typeof comment.value === "string" ? comment.value : "";
+        return /@story\b|@req\b|@supports\b/.test(commentText);
+    });
+    if (annotationComments.length === 0) {
+        return null;
+    }
+    return { comments: annotationComments };
+}
+/**
+ * Compute unique removal ranges for the given annotation comments.
+ *
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-SAFE-REMOVAL
+ */
+function getRemovalRangesForAnnotationComments(comments, sourceCode) {
+    const rangeMap = new Map();
+    for (const comment of comments) {
+        const [removalStart, removalEnd] = (0, annotation_scope_analyzer_1.getCommentRemovalRange)(comment, sourceCode);
+        const key = `${removalStart}:${removalEnd}`;
+        if (!rangeMap.has(key)) {
+            rangeMap.set(key, [removalStart, removalEnd]);
+        }
+    }
+    return Array.from(rangeMap.values()).sort((a, b) => b[0] - a[0]);
+}
 /**
  * Analyze a block's statements and report redundant traceability annotations.
  *
@@ -137,42 +228,25 @@ function debugScopePairs(scopeNode, scopePairs) {
  */
 function reportRedundantAnnotationsInBlock(context, blockNode, scopePairs, options) {
     const statements = Array.isArray(blockNode.body) ? blockNode.body : [];
-    if (statements.length === 0)
+    if (statements.length === 0 || scopePairs.size === 0)
         return;
+    const sourceCode = context.getSourceCode();
     for (const stmt of statements) {
-        if (!(0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(stmt, options, branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES)) {
+        const info = getRedundantStatementContext(context, stmt, scopePairs, options);
+        if (!info) {
             continue;
         }
-        const stmtComments = getStatementComments(context, stmt);
-        if (stmtComments.length === 0) {
+        const ranges = getRemovalRangesForAnnotationComments(info.comments, sourceCode);
+        if (ranges.length === 0) {
             continue;
         }
-        const stmtPairs = (0, annotation_scope_analyzer_1.extractStoryReqPairsFromComments)(stmtComments);
-        if (process.env.TRACEABILITY_DEBUG === "1") {
-            console.log("[no-redundant-annotation] Statement type=%s eligible=%s commentCount=%d pairs=%o", stmt && stmt.type, (0, annotation_scope_analyzer_1.isStatementEligibleForRedundancy)(stmt, options, branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES), stmtComments.length, Array.from(stmtPairs));
-        }
-        if (stmtPairs.size === 0) {
-            continue;
-        }
-        if (!(0, annotation_scope_analyzer_1.arePairsFullyCovered)(stmtPairs, scopePairs)) {
-            continue;
-        }
-        // At this point the statement-level annotations are fully
-        // covered by the parent scope and therefore redundant.
-        for (const comment of stmtComments) {
-            const commentText = typeof comment.value === "string" ? comment.value : "";
-            if (!/@story\b|@req\b|@supports\b/.test(commentText)) {
-                continue;
-            }
-            const [removalStart, removalEnd] = (0, annotation_scope_analyzer_1.getCommentRemovalRange)(comment, context.getSourceCode());
-            context.report({
-                node: stmt,
-                messageId: "redundantAnnotation",
-                fix(fixer) {
-                    return fixer.removeRange([removalStart, removalEnd]);
-                },
-            });
-        }
+        context.report({
+            node: stmt,
+            messageId: "redundantAnnotation",
+            fix(fixer) {
+                return ranges.map(([start, end]) => fixer.removeRange([start, end]));
+            },
+        });
     }
 }
 const rule = {
@@ -219,12 +293,11 @@ const rule = {
             // @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL
             BlockStatement(node) {
                 const parent = node.parent;
-                const scopeNode = parent;
                 if (process.env.TRACEABILITY_DEBUG === "1") {
                     console.log("[no-redundant-annotation] BlockStatement parent=%s statements=%d", parent && parent.type, Array.isArray(node.body) ? node.body.length : 0);
                 }
-                const scopePairs = getScopePairs(context, scopeNode, scopeNode?.parent);
-                debugScopePairs(scopeNode, scopePairs);
+                const scopePairs = collectScopePairs(context, parent, options.maxScopeDepth);
+                debugScopePairs(parent, scopePairs);
                 if (scopePairs.size === 0)
                     return;
                 reportRedundantAnnotationsInBlock(context, node, scopePairs, options);

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/integration/no-redundant-annotation.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tests/integration/no-redundant-annotation.integration.test.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Integration tests for no-redundant-annotation rule across multiple files
+ * @supports docs/stories/027.0-DEV-REDUNDANT-ANNOTATION-DETECTION.story.md REQ-REDUNDANCY-PATTERNS REQ-SAFE-REMOVAL REQ-SCOPE-INHERITANCE
+ */
+const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
+const index_1 = __importDefault(require("../../src/index"));
+async function lintTextWithConfig(text, filename, extraConfig = {}) {
+    const baseConfig = {
+        plugins: {
+            traceability: index_1.default,
+        },
+        rules: {},
+    };
+    const eslint = new use_at_your_own_risk_1.FlatESLint({
+        overrideConfig: [baseConfig, extraConfig],
+        overrideConfigFile: true,
+        ignore: false,
+    });
+    const [result] = await eslint.lintText(text, { filePath: filename });
+    return result;
+}
+describe("no-redundant-annotation integration (Story 027.0-DEV-REDUNDANT-ANNOTATION-DETECTION)", () => {
+    it("[REQ-REDUNDANCY-PATTERNS] cleans up redundant annotations in multiple files while preserving required ones", async () => {
+        const codeA = `// @story docs/stories/003.0-EXAMPLE.story.md
+// @req REQ-INIT
+function init() {
+  // @story docs/stories/003.0-EXAMPLE.story.md
+  // @req REQ-INIT
+  const config = loadConfig();
+  const validator = new Validator(config);
+}`;
+        const codeB = `/**
+ * @story docs/stories/004.0-EXAMPLE.story.md
+ * @req REQ-PROCESS
+ */
+function process(value) {
+  if (value) {
+    /* @story docs/stories/004.0-EXAMPLE.story.md
+     * @req REQ-PROCESS
+     */
+    return handle(value);
+  }
+}`;
+        const config = {
+            rules: {
+                "traceability/no-redundant-annotation": ["warn"],
+            },
+        };
+        const [resultA, resultB] = await Promise.all([
+            lintTextWithConfig(codeA, "file-a.js", config),
+            lintTextWithConfig(codeB, "file-b.js", config),
+        ]);
+        expect(resultA.messages.map((m) => m.ruleId)).toContain("traceability/no-redundant-annotation");
+        expect(resultB.messages.map((m) => m.ruleId)).toContain("traceability/no-redundant-annotation");
+        const fixerConfig = {
+            rules: {
+                "traceability/no-redundant-annotation": ["warn"],
+            },
+            fix: true,
+        };
+        const eslintFix = new use_at_your_own_risk_1.FlatESLint({
+            overrideConfig: [
+                {
+                    plugins: { traceability: index_1.default },
+                    rules: fixerConfig.rules,
+                },
+            ],
+            overrideConfigFile: true,
+            ignore: false,
+            fix: true,
+        });
+        const [fixedA, fixedB] = await Promise.all([
+            (async () => {
+                const [result] = await eslintFix.lintText(codeA, {
+                    filePath: "file-a.js",
+                });
+                return result;
+            })(),
+            (async () => {
+                const [result] = await eslintFix.lintText(codeB, {
+                    filePath: "file-b.js",
+                });
+                return result;
+            })(),
+        ]);
+        expect(fixedA.output).toContain("// @story docs/stories/003.0-EXAMPLE.story.md");
+        expect(fixedA.output).toContain("// @req REQ-INIT");
+        expect(fixedA.output).not.toContain("// @req REQ-INIT\n  const config");
+        expect(fixedB.output).toContain("@story docs/stories/004.0-EXAMPLE.story.md");
+        expect(fixedB.output).toContain("@req REQ-PROCESS");
+        expect(fixedB.output).not.toContain("@req REQ-PROCESS\n     */\n    return");
+    });
+});

package/lib/tests/rules/no-redundant-annotation.test.js

@@ -31,33 +31,97 @@ describe("no-redundant-annotation rule (Story 027.0-DEV-REDUNDANT-ANNOTATION-DET
             },
         ],
         invalid: [
-        // TODO: rule implementation exists; full invalid-case behavior tests pending refinement
-        // {
-        //   name: "[REQ-SCOPE-ANALYSIS][REQ-STATEMENT-SIGNIFICANCE] flags redundant annotation on simple return inside annotated if",
-        //   code: `function example() {\n  // @story docs/stories/004.0-EXAMPLE.story.md\n  // @req REQ-PROCESS\n  if (condition) {\n    // @req REQ-PROCESS\n    return value;\n  }\n}`,
-        //   output: `function example() {\n  // @story docs/stories/004.0-EXAMPLE.story.md\n  // @req REQ-PROCESS\n  if (condition) {\n    return value;\n  }\n}`,
-        //   errors: [
-        //     {
-        //       messageId: "redundantAnnotation",
-        //     },
-        //   ],
-        // },
-        // {
-        //   name: "[REQ-DUPLICATION-DETECTION] flags redundant annotations on sequential simple statements in same scope",
-        //   code: `// @story docs/stories/003.0-EXAMPLE.story.md\n// @req REQ-INIT\nfunction init() {\n  // @req REQ-INIT\n  const config = loadConfig();\n  const validator = new Validator(config);\n}`,
-        //   output: `// @story docs/stories/003.0-EXAMPLE.story.md\n// @req REQ-INIT\nfunction init() {\n  const config = loadConfig();\n  const validator = new Validator(config);\n}`,
-        //   errors: [
-        //     { messageId: "redundantAnnotation" },
-        //   ],
-        // },
-        // {
-        //   name: "[REQ-SAFE-REMOVAL] removes full-line redundant comment without touching code on same line above",
-        //   code: `function example() {\n  const keep = 1;\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  if (flag) {\n    // @req REQ-INIT\n    const value = 1;\n  }\n}`,
-        //   output: `function example() {\n  const keep = 1;\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  if (flag) {\n    const value = 1;\n  }\n}`,
-        //   errors: [
-        //     { messageId: "redundantAnnotation" },
-        //   ],
-        // },
+            {
+                name: "[REQ-SCOPE-ANALYSIS][REQ-STATEMENT-SIGNIFICANCE] flags redundant annotation on simple return inside annotated if",
+                code: `function example() {
+  // @story docs/stories/004.0-EXAMPLE.story.md
+  // @req REQ-PROCESS
+  if (condition) {
+    /* @story docs/stories/004.0-EXAMPLE.story.md\n     * @req REQ-PROCESS
+     */
+    return value;
+  }
+}`,
+                output: `function example() {
+  // @story docs/stories/004.0-EXAMPLE.story.md
+  // @req REQ-PROCESS
+  if (condition) {
+    return value;
+  }
+}`,
+                errors: [
+                    {
+                        messageId: "redundantAnnotation",
+                    },
+                ],
+            },
+            {
+                name: "[REQ-DUPLICATION-DETECTION] flags redundant annotations on sequential simple statements in same scope",
+                code: `// @story docs/stories/003.0-EXAMPLE.story.md\n// @req REQ-INIT\nfunction init() {\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  const config = loadConfig();\n  const validator = new Validator(config);\n}`,
+                output: `// @story docs/stories/003.0-EXAMPLE.story.md\n// @req REQ-INIT\nfunction init() {\n  const config = loadConfig();\n  const validator = new Validator(config);\n}`,
+                errors: [{ messageId: "redundantAnnotation" }],
+            },
+            {
+                name: "[REQ-SAFE-REMOVAL] removes full-line redundant comment without touching code on same line above",
+                code: `function example() {\n  const keep = 1;\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  if (flag) {\n    // @story docs/stories/003.0-EXAMPLE.story.md\n    // @req REQ-INIT\n    const value = 1;\n  }\n}`,
+                output: `function example() {\n  const keep = 1;\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  if (flag) {\n    const value = 1;\n  }\n}`,
+                errors: [{ messageId: "redundantAnnotation" }],
+            },
+            // TODO: rule implementation exists; full invalid-case behavior tests pending refinement
+            // {
+            //   name: "[REQ-SCOPE-ANALYSIS][REQ-STATEMENT-SIGNIFICANCE] flags redundant annotation on simple return inside annotated if",
+            //   code: `function example() {\n  // @story docs/stories/004.0-EXAMPLE.story.md\n  // @req REQ-PROCESS\n  if (condition) {\n    // @req REQ-PROCESS\n    return value;\n  }\n}`,
+            //   output: `function example() {\n  // @story docs/stories/004.0-EXAMPLE.story.md\n  // @req REQ-PROCESS\n  if (condition) {\n    return value;\n  }\n}`,
+            //   errors: [
+            //     {
+            //       messageId: "redundantAnnotation",
+            //     },
+            //   ],
+            // },
+            // {
+            //   name: "[REQ-DUPLICATION-DETECTION] flags redundant annotations on sequential simple statements in same scope",
+            //   code: `// @story docs/stories/003.0-EXAMPLE.story.md\n// @req REQ-INIT\nfunction init() {\n  // @req REQ-INIT\n  const config = loadConfig();\n  const validator = new Validator(config);\n}`,
+            //   output: `// @story docs/stories/003.0-EXAMPLE.story.md\n// @req REQ-INIT\nfunction init() {\n  const config = loadConfig();\n  const validator = new Validator(config);\n}`,
+            //   errors: [
+            //     { messageId: "redundantAnnotation" },
+            //   ],
+            // },
+            // {
+            //   name: "[REQ-SAFE-REMOVAL] removes full-line redundant comment without touching code on same line above",
+            //   code: `function example() {\n  const keep = 1;\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  if (flag) {\n    // @req REQ-INIT\n    const value = 1;\n  }\n}`,
+            //   output: `function example() {\n  const keep = 1;\n  // @story docs/stories/003.0-EXAMPLE.story.md\n  // @req REQ-INIT\n  if (flag) {\n    const value = 1;\n  }\n}`,
+            //   errors: [
+            //     { messageId: "redundantAnnotation" },
+            //   ],
+            // },
+        ],
+    });
+    runRule({
+        valid: [
+            {
+                name: "[REQ-CONFIGURABLE-STRICTNESS] permissive mode does not flag expression statements as redundant",
+                options: [{ strictness: "permissive" }],
+                code: `function example() {\n  // @story docs/stories/004.0-EXAMPLE.story.md\n  // @req REQ-PROCESS\n  if (condition) {\n    // @story docs/stories/004.0-EXAMPLE.story.md\n    // @req REQ-PROCESS\n    doSomething();\n  }\n}`,
+            },
+            {
+                name: "[REQ-CONFIGURABLE-STRICTNESS] allowEmphasisDuplication skips single covered pair",
+                options: [{ allowEmphasisDuplication: true }],
+                code: `function example() {\n  // @story docs/stories/004.0-EXAMPLE.story.md\n  // @req REQ-PROCESS\n  if (condition) {\n    // @story docs/stories/004.0-EXAMPLE.story.md\n    // @req REQ-PROCESS\n    return value;\n  }\n}`,
+            },
+            {
+                name: "[REQ-SCOPE-INHERITANCE] maxScopeDepth=1 does not treat grandparent function annotations as covering nested block",
+                options: [{ maxScopeDepth: 1 }],
+                code: `/**\n * @story docs/stories/004.0-EXAMPLE.story.md\n * @req REQ-PROCESS\n */\nfunction example() {\n  if (outer) {\n    {\n      // @story docs/stories/004.0-EXAMPLE.story.md\n      // @req REQ-PROCESS\n      const value = compute();\n    }\n  }\n}`,
+            },
+        ],
+        invalid: [
+            {
+                name: "[REQ-SCOPE-INHERITANCE] maxScopeDepth>1 treats function-level annotations as covering nested block statements",
+                options: [{ maxScopeDepth: 4 }],
+                code: `/**\n * @story docs/stories/004.0-EXAMPLE.story.md\n * @req REQ-PROCESS\n */\nfunction example() {\n  if (outer) {\n    {\n      // @story docs/stories/004.0-EXAMPLE.story.md\n      // @req REQ-PROCESS\n      const value = compute();\n    }\n  }\n}`,
+                output: `/**\n * @story docs/stories/004.0-EXAMPLE.story.md\n * @req REQ-PROCESS\n */\nfunction example() {\n  if (outer) {\n    {\n      const value = compute();\n    }\n  }\n}`,
+                errors: [{ messageId: "redundantAnnotation" }],
+            },
         ],
     });
 });

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.0",
+  "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

@@ -278,17 +278,17 @@ Options:
 
 The rule accepts an optional configuration object:
 
-- `strictness` (`"conservative" | "balanced" | "aggressive"`, optional) – Controls how eagerly redundancy is inferred.
-  - `"conservative"` – Only removes annotations when they are an exact structural duplicate of their containing scope (same story path and requirement IDs, no extras). Intended to minimize false positives.
-  - `"balanced"` (default) – Treats annotations as redundant when they do not add any **new** requirements or stories beyond what is already declared on the nearest enclosing scope, allowing for minor formatting differences.
-  - `"aggressive"` – Additionally flags cases where the inner annotation merely reorders or partially repeats the same requirement set, or where emphasis-only duplication (such as repeating a single requirement for emphasis) is considered redundant. Use with care in projects that rely heavily on local commentary.
-- `allowEmphasisDuplication` (boolean, optional) – When `true`, allows a statement-level annotation that repeats a **single** requirement or story from its parent purely to emphasize a critical line or edge case (for example, a guard clause that deserves its own comment), even when it would otherwise be considered redundant under the current `strictness`. Defaults to `true`. Set to `false` if you prefer to remove all covered duplicates, including emphasis-style comments.
-- `maxScopeDepth` (number, optional) – Limits how deep the rule will search for covering scopes when deciding whether an annotation is redundant. A depth of `1` (the default) considers only the nearest enclosing function/method or branch. Larger values allow walking further up nested scopes (e.g., inner blocks inside loops inside functions). Increasing this value can find more redundancy but may also make reasoning about coverage more subtle.
-- `alwaysCovered` (string[], optional) – A list of short annotation **aliases** or requirement patterns that your project treats as “implicitly covered” by higher-level documentation (for example, high-level safety or logging requirements that apply to an entire module). Any annotation whose requirement/story ID matches one of these entries is treated as redundant when it appears on simple leaf statements beneath the already-covered area, even if there is no local function-level annotation. Entries are compared as literal strings; pattern-like values (such as `"REQ-LOGGING-*"` or `"REQ-SAFETY"`) are project-specific conventions and are not treated as regular expressions by this rule.
+- `strictness` (`"strict" | "moderate" | "permissive"`, optional)  Controls how broadly statements are considered eligible for redundancy.
+  - `"strict"`  Treats any non-branch statement as a candidate for redundancy once it is covered by a containing annotated scope. This is the most aggressive mode and is useful in codebases that want to push almost all traceability down to function/branch level only.
+  - `"moderate"` (default)  Focuses on obviously leaf-like statements: anything in `alwaysCovered` **plus** bare `ExpressionStatement` nodes (for example, simple calls or assignments) that are not themselves branches. This mode balances redundancy cleanup with readability.
+  - `"permissive"`  Only treats AST node types listed in `alwaysCovered` as candidates. Other statements are ignored even when they are technically covered by an enclosing scope, which is useful when you prefer more explicit, local annotations.
+- `allowEmphasisDuplication` (boolean, optional)  When `true`, allows a statement-level annotation that repeats a **single** fully-covered story/requirement pair from its parent scope purely for emphasis (for example, a guard clause with its own comment) and **does not** report it as redundant. When omitted or `false` (the default), even emphasis-only duplicates are treated as redundant when they add no new coverage.
+- `maxScopeDepth` (number, optional)  Limits how far up the ancestor chain the rule searches for covering scopes when deciding whether a statements annotations are redundant. A value of `1` restricts checks to the immediate parent scope; larger values allow the rule to consider annotations on enclosing branches and functions further up the tree. The default is `3`, which is suitable for most common function and branch nesting patterns, but you can increase it (for example, to `4` or higher) in projects that use additional nested blocks inside annotated functions.
+- `alwaysCovered` (string[], optional)  List of AST statement `node.type` strings that your project treats as "always covered" by their containing scope when that scope is annotated. By default, the rule treats `ReturnStatement` and `VariableDeclaration` as always-covered leaf statements. You can extend or override this list to tune which statement types are considered trivial enough to inherit coverage from their parent scopes.
 
 Behavior notes:
 
-- The rule only inspects comments that contain recognized traceability annotations (`@story`, `@req`, `@supports`) and are attached to simple statements (returns, expression statements, variable declarations, and similar leaf nodes). It intentionally does **not** attempt to de-duplicate annotations on functions, classes, or major branches, which remain the responsibility of the core rules.
+- The rule only inspects comments that contain recognized traceability annotations (`@story`, `@req`, `@supports`) and are attached to simple statements (returns, expression statements, variable declarations, and similar leaf nodes). It intentionally does **not** attempt to de-duplicate annotations on functions, classes, or major branches, which remain the responsibility of the core rules. When a statement has multiple redundant traceability comments (for example, a small comment block that repeats both @story and @req lines), the rule reports a **single** diagnostic for that statement and, in fix mode, removes all of the redundant annotation comments associated with it in a single grouped fix.
 - Auto-fix removes only the redundant traceability lines (and any now-empty comment delimiters when safe) while preserving surrounding non-traceability text in the same comment where possible.
 - When no enclosing scope with compatible coverage is found within `maxScopeDepth`, the annotation is not considered redundant and is left unchanged.
 
@@ -299,8 +299,8 @@ This rule is **not** enabled in the `recommended` or `strict` presets by default
 ```jsonc
 {
   "rules": {
-    "traceability/no-redundant-annotation": "warn"
-  }
+    "traceability/no-redundant-annotation": "warn",
+  },
 }
 ```
 
@@ -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:
@@ -741,4 +741,5 @@ If `--from` or `--to` is missing, the CLI prints an error, shows the help text,
 In CI:
 
 ```bash
-npm run traceability:verify
+npm run traceability:verify
+```