eslint-plugin-traceability 1.17.0 → 1.18.0

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/src/utils/branch-annotation-helpers.d.ts

@@ -10,6 +10,12 @@ export declare const DEFAULT_BRANCH_TYPES: readonly ["IfStatement", "SwitchCase"
  * Type for branch nodes supported by require-branch-annotation rule.
  */
 export type BranchType = (typeof DEFAULT_BRANCH_TYPES)[number];
+/**
+ * Placement options for branch annotations relative to their associated branch.
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
+ * @req REQ-PLACEMENT-CONFIG - Allow configuration of annotation placement (before/inside)
+ */
+export type AnnotationPlacement = "before" | "inside";
 /**
  * Validate branchTypes configuration option and return branch types to enforce,
  * or return an ESLint listener if configuration is invalid.
@@ -33,8 +39,9 @@ export declare function scanCommentLinesInRange(lines: string[], startIndex: num
  * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
-export declare function gatherBranchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, parent?: any): string;
+export declare function gatherBranchCommentText(sourceCode: ReturnType<Rule.RuleContext["getSourceCode"]>, node: any, parent?: any, _annotationPlacement?: AnnotationPlacement): string;
 /**
  * Report missing @story annotation tag on a branch node when that branch lacks a corresponding @story reference in its comments.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md

package/lib/src/utils/branch-annotation-helpers.js

@@ -316,8 +316,9 @@ function gatherSwitchCaseCommentText(sourceCode, node) {
  * @req REQ-COMMENT-ASSOCIATION - Associate inline comments with their corresponding code branches
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
-function gatherBranchCommentText(sourceCode, node, parent) {
+function gatherBranchCommentText(sourceCode, node, parent, _annotationPlacement = "before") {
     /**
      * Conditional branch for SwitchCase nodes that may include inline comments.
      * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md

package/lib/src/utils/branch-annotation-report-helpers.d.ts

@@ -5,6 +5,7 @@ import type { Rule } from "eslint";
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 export declare function reportMissingAnnotations(context: Rule.RuleContext, node: any, storyFixCountRef: {
     count: number;

package/lib/src/utils/branch-annotation-report-helpers.js

@@ -22,8 +22,11 @@ function getIndentAndInsertPosForLine(sourceCode, line, fallbackIndent) {
     });
     return { indent, insertPos };
 }
-/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */
-function getBaseBranchIndentAndInsertPos(sourceCode, node) {
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ */
+function getBaseBranchIndentAndInsertPos(sourceCode, node, _annotationPlacement) {
     let { indent, insertPos } = getIndentAndInsertPosForLine(sourceCode, node.loc.start.line, "");
     if (node.type === "CatchClause" && node.body) {
         const bodyNode = node.body;
@@ -50,19 +53,24 @@ function getBaseBranchIndentAndInsertPos(sourceCode, node) {
     return { indent, insertPos };
 }
 /**
- * Compute annotation-related metadata for a branch node.
+ * Compute which annotations are missing for a branch based on its gathered comment text.
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
- * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
- * @supports REQ-DUAL-POSITION-DETECTION
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
-function getBranchAnnotationInfo(sourceCode, node, parent) {
-    const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent);
+function getBranchMissingFlags(sourceCode, node, parent, annotationPlacement) {
+    const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node, parent, annotationPlacement);
     const hasSupports = /@supports\b/.test(text);
     const missingStory = !/@story\b/.test(text) && !hasSupports;
     const missingReq = !/@req\b/.test(text) && !hasSupports;
-    let { indent, insertPos } = getBaseBranchIndentAndInsertPos(sourceCode, node);
+    return { missingStory, missingReq };
+}
+/**
+ * Compute indentation and insert position used for auto-fix insertion on a branch.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ */
+function getBranchIndentAndInsertPos(sourceCode, node, parent, annotationPlacement) {
+    let { indent, insertPos } = getBaseBranchIndentAndInsertPos(sourceCode, node, annotationPlacement);
     if (node.type === "IfStatement" &&
         parent &&
         parent.type === "IfStatement" &&
@@ -76,6 +84,20 @@ function getBranchAnnotationInfo(sourceCode, node, parent) {
         indent = commentLineInfo.indent;
         insertPos = commentLineInfo.insertPos;
     }
+    return { indent, insertPos };
+}
+/**
+ * Compute annotation-related metadata for a branch node.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
+ * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
+ */
+function getBranchAnnotationInfo(sourceCode, node, parent, annotationPlacement) {
+    const { missingStory, missingReq } = getBranchMissingFlags(sourceCode, node, parent, annotationPlacement);
+    const { indent, insertPos } = getBranchIndentAndInsertPos(sourceCode, node, parent, annotationPlacement);
     return { missingStory, missingReq, indent, insertPos };
 }
 /**
@@ -84,11 +106,18 @@ function getBranchAnnotationInfo(sourceCode, node, parent) {
  * @req REQ-ANNOTATION-PARSING - Parse @story and @req annotations from branch comments
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
  * @supports REQ-DUAL-POSITION-DETECTION
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG
  */
 function reportMissingAnnotations(context, node, storyFixCountRef) {
     const sourceCode = context.getSourceCode();
+    const rawOptions = context.options && context.options[0];
+    const annotationPlacement = rawOptions &&
+        (rawOptions.annotationPlacement === "inside" ||
+            rawOptions.annotationPlacement === "before")
+        ? rawOptions.annotationPlacement
+        : "before";
     const parent = node.parent;
-    const { missingStory, missingReq, indent, insertPos } = getBranchAnnotationInfo(sourceCode, node, parent);
+    const { missingStory, missingReq, indent, insertPos } = getBranchAnnotationInfo(sourceCode, node, parent, annotationPlacement);
     const actions = [
         {
             missing: missingStory,

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
             }
         }
     });