eslint-plugin-traceability 1.16.1 → 1.17.1

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

@@ -286,17 +286,8 @@ function tryBuildInlineAutoFix(context, comments, storyIndex, reqIndices) {
  * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
  * @req REQ-MIGRATE-INLINE
  */
-function handleInlineStorySequence(context, group, startIndex) {
+function collectReqIndicesAfterStory(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) {
@@ -312,6 +303,19 @@ function handleInlineStorySequence(context, group, startIndex) {
         }
         break;
     }
+    return { reqIndices, nextIndex: j };
+}
+function handleInlineStorySequence(context, group, startIndex) {
+    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, nextIndex } = collectReqIndicesAfterStory(group, startIndex);
     if (reqIndices.length === 0) {
         context.report({
             node: current,
@@ -333,7 +337,7 @@ function handleInlineStorySequence(context, group, startIndex) {
             messageId: "preferImplements",
         });
     }
-    return reqIndices[reqIndices.length - 1] + 1;
+    return nextIndex;
 }
 /**
  * Process a contiguous group of inline line comments, identifying legacy
@@ -343,19 +347,20 @@ function handleInlineStorySequence(context, group, startIndex) {
  * @story docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md
  * @req REQ-MIGRATE-INLINE
  */
+function advanceInlineGroupIndex(context, group, currentIndex) {
+    const current = group[currentIndex];
+    const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(current.value || "");
+    if (!normalized || !/^@story\b/.test(normalized)) {
+        return currentIndex + 1;
+    }
+    return handleInlineStorySequence(context, group, currentIndex);
+}
 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);
+    while (i < group.length) {
+        i = advanceInlineGroupIndex(context, group, i);
     }
 }
 /**

package/lib/src/rules/require-story-annotation.js

@@ -49,6 +49,11 @@ const rule = {
                     methodAnnotationTemplate: { type: "string" },
                     autoFix: { type: "boolean" },
                     excludeTestCallbacks: { type: "boolean" },
+                    additionalTestHelperNames: {
+                        type: "array",
+                        items: { type: "string" },
+                        uniqueItems: true,
+                    },
                 },
                 additionalProperties: false,
             },
@@ -79,6 +84,10 @@ const rule = {
         const excludeTestCallbacks = typeof opts.excludeTestCallbacks === "boolean"
             ? opts.excludeTestCallbacks
             : true;
+        const additionalTestHelperNames = Array.isArray(opts.additionalTestHelperNames) &&
+            opts.additionalTestHelperNames.every((name) => typeof name === "string")
+            ? opts.additionalTestHelperNames
+            : undefined;
         /**
          * Optional debug logging for troubleshooting this rule.
          * Developers can temporarily uncomment the block below to log when the rule
@@ -94,7 +103,10 @@ const rule = {
         //     : "<unknown>",
         // );
         // Local closure that binds configured scope and export priority to the helper.
-        const should = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority, { excludeTestCallbacks });
+        const should = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority, {
+            excludeTestCallbacks,
+            additionalTestHelperNames,
+        });
         // Delegate visitor construction to helper to keep this file concise.
         return (0, require_story_visitors_1.buildVisitors)(context, sourceCode, {
             shouldProcessNode: should,
@@ -104,6 +116,7 @@ const rule = {
             methodAnnotationTemplate,
             autoFix,
             excludeTestCallbacks,
+            additionalTestHelperNames,
         });
     },
 };

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

@@ -3,6 +3,49 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const valid_annotation_options_1 = require("./helpers/valid-annotation-options");
 const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-format-internal");
 const valid_annotation_format_validators_1 = require("./helpers/valid-annotation-format-validators");
+function handleImplementsLine(normalized, pending, deps) {
+    const { context, comment, options } = deps;
+    const isImplements = /@supports\b/.test(normalized);
+    if (!isImplements) {
+        return pending;
+    }
+    const implementsValue = normalized.replace(/^@supports\b/, "").trim();
+    (0, valid_annotation_format_validators_1.validateImplementsAnnotation)(context, comment, implementsValue, options);
+    return pending;
+}
+function handleStoryOrReqLine(normalized, pending, deps) {
+    const { context, comment, options } = deps;
+    const isStory = /@story\b/.test(normalized);
+    const isReq = /@req\b/.test(normalized);
+    if (!isStory && !isReq) {
+        return pending;
+    }
+    (0, valid_annotation_format_validators_1.finalizePendingAnnotation)(context, comment, options, pending);
+    const rawValue = normalized.replace(/^@story\b|^@req\b/, "");
+    const trimmedValue = rawValue.trim();
+    return {
+        type: isStory ? "story" : "req",
+        value: trimmedValue,
+        hasValue: trimmedValue.length > 0,
+    };
+}
+function extendPendingAnnotation(normalized, pending) {
+    if (!pending) {
+        return 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,
+    };
+}
 /**
  * Process a single normalized comment line and update the pending annotation state.
  *
@@ -22,31 +65,21 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     if (!normalized) {
         return pending;
     }
-    const isStory = /@story\b/.test(normalized);
-    const isReq = /@req\b/.test(normalized);
-    const isImplements = /@supports\b/.test(normalized);
-    // Handle @supports as an immediate, single-line annotation
-    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
-    // @req REQ-IMPLEMENTS-PARSE - Immediately validate @supports without starting multi-line state
-    if (isImplements) {
-        const implementsValue = normalized.replace(/^@supports\b/, "").trim();
-        (0, valid_annotation_format_validators_1.validateImplementsAnnotation)(context, comment, implementsValue, options);
-        return pending;
+    const afterImplements = handleImplementsLine(normalized, pending, {
+        context,
+        comment,
+        options,
+    });
+    if (afterImplements !== pending) {
+        return afterImplements;
     }
-    // @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 - Start new pending annotation when a tag is found
-    // @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
-    if (isStory || isReq) {
-        (0, valid_annotation_format_validators_1.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,
-        };
+    const afterStoryOrReq = handleStoryOrReqLine(normalized, pending, {
+        context,
+        comment,
+        options,
+    });
+    if (afterStoryOrReq !== pending) {
+        return afterStoryOrReq;
     }
     // Implement JSDoc tag coexistence behavior: terminate @story/@req values when a new non-traceability JSDoc tag line (e.g., @param, @returns) is encountered.
     // @supports docs/stories/022.0-DEV-JSDOC-COEXISTENCE.story.md REQ-ANNOTATION-TERMINATION REQ-CONTINUATION-LOGIC
@@ -60,23 +93,7 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     // @req REQ-MULTILINE-SUPPORT - Extend value of existing pending annotation across lines
     // @req REQ-AUTOFIX-FORMAT - Maintain complete logical value for downstream validation and fixes
     // @req REQ-MIXED-SUPPORT - Leave non-annotation lines untouched when no pending state exists
-    if (pending) {
-        const continuation = normalized.trim();
-        // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-        // @req REQ-MULTILINE-SUPPORT - Skip blank continuation lines without altering pending annotation
-        if (!continuation) {
-            return pending;
-        }
-        const updatedValue = pending.value
-            ? `${pending.value} ${continuation}`
-            : continuation;
-        return {
-            ...pending,
-            value: updatedValue,
-            hasValue: pending.hasValue || continuation.length > 0,
-        };
-    }
-    return pending;
+    return extendPendingAnnotation(normalized, pending);
 }
 /**
  * Process a single comment node and validate any @story/@req/@supports annotations it contains.
@@ -98,7 +115,7 @@ function processCommentLine({ normalized, pending, context, comment, options, })
  * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
  * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
-function processComment(context, comment, options) {
+function processCommentLines({ context, comment, options, }) {
     const rawLines = (comment.value || "").split(/\r?\n/);
     let pending = null;
     rawLines.forEach((rawLine) => {
@@ -113,6 +130,9 @@ function processComment(context, comment, options) {
     });
     (0, valid_annotation_format_validators_1.finalizePendingAnnotation)(context, comment, options, pending);
 }
+function processComment(context, comment, options) {
+    processCommentLines({ context, comment, options });
+}
 exports.default = {
     meta: {
         type: "problem",

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

@@ -95,4 +95,35 @@ function process(value) {
         expect(fixedB.output).toContain("@req REQ-PROCESS");
         expect(fixedB.output).not.toContain("@req REQ-PROCESS\n     */\n    return");
     });
+    it("[REQ-CATCH-BLOCK-HANDLING] does not report redundant annotations for try/if/else-if/catch pattern from story 027.0 (regression from issue #6)", async () => {
+        const code = `// @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md
+// @req REQ-SAFE-ONLY
+async function filterVulnerableVersions(versionInfo, safeVersions) {
+  try {
+    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md
+    // @req REQ-SAFE-ONLY
+    if (!versionInfo) {
+      return [];
+    } else if (!safeVersions || safeVersions.length === 0) {
+      return versionInfo;
+    }
+
+    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md
+    // @req REQ-SAFE-ONLY
+    return versionInfo.filter(v => safeVersions.includes(v));
+  } catch (error) {
+    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md
+    // @req REQ-SAFE-ONLY
+    return [];
+  }
+}
+`;
+        const config = {
+            rules: {
+                "traceability/no-redundant-annotation": ["warn"],
+            },
+        };
+        const result = await lintTextWithConfig(code, "filter-vulnerable-versions.js", config);
+        expect(result.messages.filter((m) => m.ruleId === "traceability/no-redundant-annotation").length).toBe(0);
+    });
 });

package/lib/tests/integration/require-traceability-test-callbacks.integration.test.d.ts

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

package/lib/tests/integration/require-traceability-test-callbacks.integration.test.js

@@ -0,0 +1,148 @@
+"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 require-traceability with configurable test callback exclusion.
+ *
+ * @supports docs/stories/010.4-DEV-UNIFIED-FUNCTION-RULE-AND-ALIASES.story.md REQ-UNIFIED-ALIAS-ENGINE
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED REQ-FUNCTION-DETECTION
+ * @supports docs/stories/013-exclude-test-framework-callbacks.proposed.md REQ-TEST-CALLBACK-EXCLUSION
+ */
+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,
+        },
+    };
+    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("Unified require-traceability with configurable test callback exclusion (Story 013-exclude-test-framework-callbacks)", () => {
+    const baseHeader = `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */`;
+    const jsTestCallback = `${baseHeader}\n
+describe('suite', () => {\n  it('does something', () => {\n    const value = 1;\n  });\n});`;
+    const tsTestCallback = `${baseHeader}\n
+import { describe, it } from 'vitest';
+
+describe('suite', () => {\n  it('does something', () => {\n    const value = 1;\n  });\n});`;
+    const jsBenchCallback = `${baseHeader}\n
+import { bench } from 'vitest';
+
+bench('bench case', () => {\n  function helper() {}\n  helper();\n});`;
+    const jsCustomHelperCallback = `${baseHeader}\n
+function helperWrapper(fn) {\n  return fn;\n}
+
+helperWrapper(() => {\n  function helper() {}\n  helper();\n});`;
+    async function getRuleMessages(code, filename, extraConfig) {
+        const result = await lintTextWithConfig(code, filename, extraConfig);
+        return result.messages.filter((m) => m.ruleId === "traceability/require-traceability" ||
+            m.ruleId === "traceability/require-story-annotation");
+    }
+    it("[REQ-TEST-CALLBACK-EXCLUSION] excludes callbacks under known test helpers when configured", async () => {
+        const config = [
+            {
+                rules: {
+                    "traceability/require-traceability": ["error"],
+                    "traceability/require-story-annotation": [
+                        "error",
+                        {
+                            excludeTestCallbacks: true,
+                        },
+                    ],
+                },
+            },
+        ];
+        const messagesJs = await getRuleMessages(jsTestCallback, "example.test.js", config);
+        const messagesTs = await getRuleMessages(tsTestCallback, "example.test.ts", config);
+        expect(messagesJs).toHaveLength(0);
+        expect(messagesTs).toHaveLength(0);
+    });
+    it("[REQ-TEST-CALLBACK-EXCLUSION] never excludes Vitest bench callbacks via test-callback exclusion, even when exclusion is enabled", async () => {
+        const baseConfig = [
+            {
+                rules: {
+                    "traceability/require-traceability": ["error"],
+                    "traceability/require-story-annotation": [
+                        "error",
+                        {
+                            excludeTestCallbacks: true,
+                        },
+                    ],
+                },
+            },
+        ];
+        const withBenchAsHelperConfig = [
+            {
+                rules: {
+                    "traceability/require-traceability": ["error"],
+                    "traceability/require-story-annotation": [
+                        "error",
+                        {
+                            excludeTestCallbacks: true,
+                            additionalTestHelperNames: ["bench"],
+                        },
+                    ],
+                },
+            },
+        ];
+        const baseResult = await lintTextWithConfig(jsBenchCallback, "bench.test.ts", baseConfig);
+        const withBenchHelperResult = await lintTextWithConfig(jsBenchCallback, "bench.test.ts", withBenchAsHelperConfig);
+        const baseMessages = baseResult.messages.filter((m) => m.ruleId === "traceability/require-traceability" ||
+            m.ruleId === "traceability/require-story-annotation");
+        const withBenchHelperMessages = withBenchHelperResult.messages.filter((m) => m.ruleId === "traceability/require-traceability" ||
+            m.ruleId === "traceability/require-story-annotation");
+        expect(withBenchHelperMessages.length).toBeGreaterThanOrEqual(baseMessages.length);
+    });
+    it("[REQ-TEST-CALLBACK-EXCLUSION] respects additionalTestHelperNames for custom helpers but not for bench callbacks", async () => {
+        const baseConfig = [
+            {
+                rules: {
+                    "traceability/require-traceability": ["error"],
+                    "traceability/require-story-annotation": [
+                        "error",
+                        {
+                            excludeTestCallbacks: true,
+                        },
+                    ],
+                },
+            },
+        ];
+        const withAdditionalHelpersConfig = [
+            {
+                rules: {
+                    "traceability/require-traceability": ["error"],
+                    "traceability/require-story-annotation": [
+                        "error",
+                        {
+                            excludeTestCallbacks: true,
+                            additionalTestHelperNames: ["helperWrapper", "bench"],
+                        },
+                    ],
+                },
+            },
+        ];
+        const wrapperBaseResult = await lintTextWithConfig(jsCustomHelperCallback, "helper-wrapper.test.ts", baseConfig);
+        const wrapperWithHelpersResult = await lintTextWithConfig(jsCustomHelperCallback, "helper-wrapper.test.ts", withAdditionalHelpersConfig);
+        const benchBaseResult = await lintTextWithConfig(jsBenchCallback, "bench.test.ts", baseConfig);
+        const benchWithHelpersResult = await lintTextWithConfig(jsBenchCallback, "bench.test.ts", withAdditionalHelpersConfig);
+        const wrapperBaseMessages = wrapperBaseResult.messages.filter((m) => m.ruleId === "traceability/require-traceability" ||
+            m.ruleId === "traceability/require-story-annotation");
+        const wrapperWithHelpersMessages = wrapperWithHelpersResult.messages.filter((m) => m.ruleId === "traceability/require-traceability" ||
+            m.ruleId === "traceability/require-story-annotation");
+        const benchBaseMessages = benchBaseResult.messages.filter((m) => m.ruleId === "traceability/require-traceability" ||
+            m.ruleId === "traceability/require-story-annotation");
+        const benchWithHelpersMessages = benchWithHelpersResult.messages.filter((m) => m.ruleId === "traceability/require-traceability" ||
+            m.ruleId === "traceability/require-story-annotation");
+        expect(wrapperWithHelpersMessages.length).toBeLessThanOrEqual(wrapperBaseMessages.length);
+        expect(benchWithHelpersMessages.length).toBeGreaterThanOrEqual(benchBaseMessages.length);
+    });
+});

package/lib/tests/maintenance/detect-isolated.test.js

@@ -77,8 +77,8 @@ describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)",
         }
     });
     it("[REQ-MAINT-DETECT] handles permission denied errors by returning an empty result", () => {
-        const tmpDir2 = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-perm-"));
-        const dir = path.join(tmpDir2, "subdir");
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-perm-"));
+        const dir = path.join(tmpDir, "subdir");
         fs.mkdirSync(dir);
         const filePath = path.join(dir, "file.ts");
         const content = `
@@ -87,24 +87,32 @@ describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)",
  */
 `;
         fs.writeFileSync(filePath, content, "utf8");
-        // Remove read permission
+        const originalReadFileSync = fs.readFileSync;
+        const readSpy = jest
+            .spyOn(fs, "readFileSync")
+            .mockImplementation((p, ...args) => {
+            const strPath = typeof p === "string" ? p : p.toString();
+            if (strPath === filePath) {
+                const err = new Error("EACCES: permission denied, open");
+                err.code = "EACCES";
+                throw err;
+            }
+            // Delegate to original implementation for all other paths
+            // to keep behavior realistic.
+            // @ts-ignore
+            return originalReadFileSync(p, ...args);
+        });
         try {
-            fs.chmodSync(dir, 0o000);
-            expect(() => (0, detect_1.detectStaleAnnotations)(tmpDir2)).toThrow();
+            const result = (0, detect_1.detectStaleAnnotations)(tmpDir);
+            expect(result).toEqual([]);
         }
         finally {
-            // Restore permissions and cleanup temporary directory, ignoring errors during cleanup
-            try {
-                fs.chmodSync(dir, 0o700);
-            }
-            catch {
-                // ignore
-            }
+            readSpy.mockRestore();
             try {
-                fs.rmSync(tmpDir2, { recursive: true, force: true });
+                fs.rmSync(tmpDir, { recursive: true, force: true });
             }
             catch {
-                // ignore
+                // ignore cleanup errors
             }
         }
     });