eslint-plugin-traceability 1.17.0 → 1.18.0

package/lib/tests/perf/maintenance-cli-large-workspace.test.js

@@ -42,6 +42,8 @@ const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const perf_hooks_1 = require("perf_hooks");
 const cli_1 = require("../../src/maintenance/cli");
+// Performance budget documented in docs/maintenance-performance-tests.md
+const CLI_LARGE_WORKSPACE_PERF_BUDGET_MS = 5000;
 function createCliLargeWorkspace() {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), "traceability-cli-large-"));
     // Create a modestly sized workspace reusing the same shape as the core perf tests,
@@ -71,78 +73,157 @@ export function cli_example_${moduleIndex}_${fileIndex}() {}
         },
     };
 }
+function createDeepNestedCliWorkspace() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "traceability-cli-deep-nested-"));
+    // Create a deeply nested directory structure with a small number of files.
+    for (let branchIndex = 0; branchIndex < 3; branchIndex += 1) {
+        const level1 = path.join(root, `branch-${branchIndex.toString().padStart(3, "0")}`);
+        fs.mkdirSync(level1);
+        const level2 = path.join(level1, "deep", "nested", "structure");
+        fs.mkdirSync(path.join(level1, "deep"), { recursive: true });
+        fs.mkdirSync(path.join(level1, "deep", "nested"), { recursive: true });
+        fs.mkdirSync(level2, { recursive: true });
+        for (let fileIndex = 0; fileIndex < 3; fileIndex += 1) {
+            const filePath = path.join(level2, `deep-file-${fileIndex.toString().padStart(3, "0")}.ts`);
+            const validStory = "cli-valid.story.md";
+            const staleStory = "cli-deep-stale.story.md";
+            const content = `/**
+ * @story ${validStory}
+ * @story ${staleStory}
+ */
+export function cli_deep_example_${branchIndex}_${fileIndex}() {}
+`;
+            fs.writeFileSync(filePath, content, "utf8");
+        }
+    }
+    // Create the valid story file so that only the stale entries are reported.
+    fs.writeFileSync(path.join(root, "cli-valid.story.md"), "# cli valid", "utf8");
+    return {
+        root,
+        cleanup: () => {
+            fs.rmSync(root, { recursive: true, force: true });
+        },
+    };
+}
 describe("Maintenance CLI on large workspaces (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-    let workspace;
-    let originalCwd;
-    beforeAll(() => {
-        originalCwd = process.cwd();
-        workspace = createCliLargeWorkspace();
-        process.chdir(workspace.root);
-    });
-    afterAll(() => {
-        process.chdir(originalCwd);
-        workspace.cleanup();
-    });
     it("[REQ-MAINT-DETECT] detect --json completes within a generous time budget and returns JSON payload", () => {
+        const { root, cleanup } = createCliLargeWorkspace();
+        const originalCwd = process.cwd();
+        process.chdir(root);
         const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
-        const start = perf_hooks_1.performance.now();
-        const exitCode = (0, cli_1.runMaintenanceCli)([
-            "node",
-            "traceability-maint",
-            "detect",
-            "--root",
-            workspace.root,
-            "--json",
-        ]);
-        const durationMs = perf_hooks_1.performance.now() - start;
-        expect(exitCode === 0 || exitCode === 1).toBe(true);
-        expect(durationMs).toBeLessThan(5000);
-        expect(logSpy).toHaveBeenCalledTimes(1);
-        const payloadRaw = String(logSpy.mock.calls[0][0]);
-        const payload = JSON.parse(payloadRaw);
-        expect(payload.root).toBe(workspace.root);
-        expect(Array.isArray(payload.stale)).toBe(true);
-        expect(payload.stale.length).toBeGreaterThan(0);
-        logSpy.mockRestore();
+        try {
+            const start = perf_hooks_1.performance.now();
+            const exitCode = (0, cli_1.runMaintenanceCli)([
+                "node",
+                "traceability-maint",
+                "detect",
+                "--root",
+                root,
+                "--json",
+            ]);
+            const durationMs = perf_hooks_1.performance.now() - start;
+            expect(exitCode === 0 || exitCode === 1).toBe(true);
+            expect(durationMs).toBeLessThan(CLI_LARGE_WORKSPACE_PERF_BUDGET_MS);
+            expect(logSpy).toHaveBeenCalledTimes(1);
+            const payloadRaw = String(logSpy.mock.calls[0][0]);
+            const payload = JSON.parse(payloadRaw);
+            expect(payload.root).toBe(root);
+            expect(Array.isArray(payload.stale)).toBe(true);
+            expect(payload.stale.length).toBeGreaterThan(0);
+        }
+        finally {
+            logSpy.mockRestore();
+            process.chdir(originalCwd);
+            cleanup();
+        }
     });
     it("[REQ-MAINT-REPORT] report --format=json completes within a generous time budget", () => {
+        const { root, cleanup } = createCliLargeWorkspace();
+        const originalCwd = process.cwd();
+        process.chdir(root);
         const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
-        const start = perf_hooks_1.performance.now();
-        const exitCode = (0, cli_1.runMaintenanceCli)([
-            "node",
-            "traceability-maint",
-            "report",
-            "--root",
-            workspace.root,
-            "--format",
-            "json",
-        ]);
-        const durationMs = perf_hooks_1.performance.now() - start;
-        expect(exitCode).toBe(0);
-        expect(durationMs).toBeLessThan(5000);
-        expect(logSpy).toHaveBeenCalledTimes(1);
-        const payloadRaw = String(logSpy.mock.calls[0][0]);
-        const payload = JSON.parse(payloadRaw);
-        expect(payload.root).toBe(workspace.root);
-        expect(typeof payload.report).toBe("string");
-        logSpy.mockRestore();
+        try {
+            const start = perf_hooks_1.performance.now();
+            const exitCode = (0, cli_1.runMaintenanceCli)([
+                "node",
+                "traceability-maint",
+                "report",
+                "--root",
+                root,
+                "--format",
+                "json",
+            ]);
+            const durationMs = perf_hooks_1.performance.now() - start;
+            expect(exitCode).toBe(0);
+            expect(durationMs).toBeLessThan(CLI_LARGE_WORKSPACE_PERF_BUDGET_MS);
+            expect(logSpy).toHaveBeenCalledTimes(1);
+            const payloadRaw = String(logSpy.mock.calls[0][0]);
+            const payload = JSON.parse(payloadRaw);
+            expect(payload.root).toBe(root);
+            expect(typeof payload.report).toBe("string");
+        }
+        finally {
+            logSpy.mockRestore();
+            process.chdir(originalCwd);
+            cleanup();
+        }
     });
     it("[REQ-MAINT-VERIFY] verify completes within a generous time budget and reports stale annotations", () => {
+        const { root, cleanup } = createCliLargeWorkspace();
+        const originalCwd = process.cwd();
+        process.chdir(root);
         const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
-        const start = perf_hooks_1.performance.now();
-        const exitCode = (0, cli_1.runMaintenanceCli)([
-            "node",
-            "traceability-maint",
-            "verify",
-            "--root",
-            workspace.root,
-        ]);
-        const durationMs = perf_hooks_1.performance.now() - start;
-        expect(exitCode).toBe(1);
-        expect(durationMs).toBeLessThan(5000);
-        expect(logSpy).toHaveBeenCalledTimes(1);
-        const message = String(logSpy.mock.calls[0][0]);
-        expect(message).toContain("Stale or invalid traceability annotations detected under");
-        logSpy.mockRestore();
+        try {
+            const start = perf_hooks_1.performance.now();
+            const exitCode = (0, cli_1.runMaintenanceCli)([
+                "node",
+                "traceability-maint",
+                "verify",
+                "--root",
+                root,
+            ]);
+            const durationMs = perf_hooks_1.performance.now() - start;
+            expect(exitCode).toBe(1);
+            expect(durationMs).toBeLessThan(CLI_LARGE_WORKSPACE_PERF_BUDGET_MS);
+            expect(logSpy).toHaveBeenCalledTimes(1);
+            const message = String(logSpy.mock.calls[0][0]);
+            expect(message).toContain("Stale or invalid traceability annotations detected under");
+        }
+        finally {
+            logSpy.mockRestore();
+            process.chdir(originalCwd);
+            cleanup();
+        }
+    });
+    it("[REQ-MAINT-DETECT] detect traverses deeply nested directories within a generous time budget", () => {
+        const { root, cleanup } = createDeepNestedCliWorkspace();
+        const originalCwd = process.cwd();
+        process.chdir(root);
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        try {
+            const start = perf_hooks_1.performance.now();
+            const exitCode = (0, cli_1.runMaintenanceCli)([
+                "node",
+                "traceability-maint",
+                "detect",
+                "--root",
+                root,
+                "--json",
+            ]);
+            const durationMs = perf_hooks_1.performance.now() - start;
+            expect(exitCode === 0 || exitCode === 1).toBe(true);
+            expect(durationMs).toBeLessThan(CLI_LARGE_WORKSPACE_PERF_BUDGET_MS);
+            expect(logSpy).toHaveBeenCalledTimes(1);
+            const payloadRaw = String(logSpy.mock.calls[0][0]);
+            const payload = JSON.parse(payloadRaw);
+            expect(payload.root).toBe(root);
+            expect(Array.isArray(payload.stale)).toBe(true);
+            expect(payload.stale.length).toBeGreaterThan(0);
+        }
+        finally {
+            logSpy.mockRestore();
+            process.chdir(originalCwd);
+            cleanup();
+        }
     });
 });

package/lib/tests/perf/maintenance-large-workspace.test.js

@@ -45,6 +45,8 @@ const detect_1 = require("../../src/maintenance/detect");
 const batch_1 = require("../../src/maintenance/batch");
 const report_1 = require("../../src/maintenance/report");
 const update_1 = require("../../src/maintenance/update");
+// Performance budget for large-workspace maintenance tests; documented in docs/maintenance-performance-tests.md.
+const LARGE_WORKSPACE_PERF_BUDGET_MS = 5000;
 /**
  * Shape of the synthetic large workspace:
  * - 10 modules (module-000 .. module-009)
@@ -92,58 +94,75 @@ export function example_${moduleIndex}_${fileIndex}() {}
     };
 }
 describe("Maintenance tools on large workspaces (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-    let workspace;
-    beforeAll(() => {
-        workspace = createLargeWorkspace();
-    });
-    afterAll(() => {
-        workspace.cleanup();
-    });
     it("[REQ-MAINT-DETECT] detectStaleAnnotations completes within a generous time budget", () => {
-        const start = perf_hooks_1.performance.now();
-        const stale = (0, detect_1.detectStaleAnnotations)(workspace.root);
-        const durationMs = perf_hooks_1.performance.now() - start;
-        // Sanity check: we expect at least some stale entries due to the generated stale-story-* references.
-        expect(stale.length).toBeGreaterThan(0);
-        // Guardrail: this operation should remain comfortably under ~5 seconds on CI hardware.
-        expect(durationMs).toBeLessThan(5000);
+        const workspace = createLargeWorkspace();
+        try {
+            const start = perf_hooks_1.performance.now();
+            const stale = (0, detect_1.detectStaleAnnotations)(workspace.root);
+            const durationMs = perf_hooks_1.performance.now() - start;
+            // Sanity check: we expect at least some stale entries due to the generated stale-story-* references.
+            expect(stale.length).toBeGreaterThan(0);
+            // Guardrail: this operation should remain comfortably under ~5 seconds on CI hardware.
+            expect(durationMs).toBeLessThan(LARGE_WORKSPACE_PERF_BUDGET_MS);
+        }
+        finally {
+            workspace.cleanup();
+        }
     });
     it("[REQ-MAINT-VERIFY] verifyAnnotations remains fast on large workspaces", () => {
-        const start = perf_hooks_1.performance.now();
-        const result = (0, batch_1.verifyAnnotations)(workspace.root);
-        const durationMs = perf_hooks_1.performance.now() - start;
-        // With both valid and stale references, verification should report false.
-        expect(result).toBe(false);
-        expect(durationMs).toBeLessThan(5000);
+        const workspace = createLargeWorkspace();
+        try {
+            const start = perf_hooks_1.performance.now();
+            const result = (0, batch_1.verifyAnnotations)(workspace.root);
+            const durationMs = perf_hooks_1.performance.now() - start;
+            // With both valid and stale references, verification should report false.
+            expect(result).toBe(false);
+            expect(durationMs).toBeLessThan(LARGE_WORKSPACE_PERF_BUDGET_MS);
+        }
+        finally {
+            workspace.cleanup();
+        }
     });
     it("[REQ-MAINT-REPORT] generateMaintenanceReport produces output within a generous time budget", () => {
-        const start = perf_hooks_1.performance.now();
-        const report = (0, report_1.generateMaintenanceReport)(workspace.root);
-        const durationMs = perf_hooks_1.performance.now() - start;
-        expect(report).not.toBe("");
-        expect(durationMs).toBeLessThan(5000);
+        const workspace = createLargeWorkspace();
+        try {
+            const start = perf_hooks_1.performance.now();
+            const report = (0, report_1.generateMaintenanceReport)(workspace.root);
+            const durationMs = perf_hooks_1.performance.now() - start;
+            expect(report).not.toBe("");
+            expect(durationMs).toBeLessThan(LARGE_WORKSPACE_PERF_BUDGET_MS);
+        }
+        finally {
+            workspace.cleanup();
+        }
     });
     it("[REQ-MAINT-UPDATE] updateAnnotationReferences and batchUpdateAnnotations remain tractable", () => {
-        const exampleOldPath = "stale-story-0000.story.md";
-        const exampleNewPath = "updated-story-0000.story.md";
-        const singleStart = perf_hooks_1.performance.now();
-        const updatedCount = (0, update_1.updateAnnotationReferences)(workspace.root, exampleOldPath, exampleNewPath);
-        const singleDuration = perf_hooks_1.performance.now() - singleStart;
-        expect(updatedCount).toBeGreaterThan(0);
-        expect(singleDuration).toBeLessThan(5000);
-        const batchStart = perf_hooks_1.performance.now();
-        const totalUpdated = (0, batch_1.batchUpdateAnnotations)(workspace.root, [
-            {
-                oldPath: "stale-story-0001.story.md",
-                newPath: "updated-story-0001.story.md",
-            },
-            {
-                oldPath: "stale-story-0002.story.md",
-                newPath: "updated-story-0002.story.md",
-            },
-        ]);
-        const batchDuration = perf_hooks_1.performance.now() - batchStart;
-        expect(totalUpdated).toBeGreaterThanOrEqual(2);
-        expect(batchDuration).toBeLessThan(5000);
+        const workspace = createLargeWorkspace();
+        try {
+            const exampleOldPath = "stale-story-0000.story.md";
+            const exampleNewPath = "updated-story-0000.story.md";
+            const singleStart = perf_hooks_1.performance.now();
+            const updatedCount = (0, update_1.updateAnnotationReferences)(workspace.root, exampleOldPath, exampleNewPath);
+            const singleDuration = perf_hooks_1.performance.now() - singleStart;
+            expect(updatedCount).toBeGreaterThan(0);
+            expect(singleDuration).toBeLessThan(LARGE_WORKSPACE_PERF_BUDGET_MS);
+            const batchStart = perf_hooks_1.performance.now();
+            const totalUpdated = (0, batch_1.batchUpdateAnnotations)(workspace.root, [
+                {
+                    oldPath: "stale-story-0001.story.md",
+                    newPath: "updated-story-0001.story.md",
+                },
+                {
+                    oldPath: "stale-story-0002.story.md",
+                    newPath: "updated-story-0002.story.md",
+                },
+            ]);
+            const batchDuration = perf_hooks_1.performance.now() - batchStart;
+            expect(totalUpdated).toBeGreaterThanOrEqual(2);
+            expect(batchDuration).toBeLessThan(LARGE_WORKSPACE_PERF_BUDGET_MS);
+        }
+        finally {
+            workspace.cleanup();
+        }
     });
 });

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

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-STATEMENT-SIGNIFICANCE - Verify that simple statements are treated as redundant when covered by scope
  * @req REQ-SAFE-REMOVAL - Verify that auto-fix removes only redundant annotations and preserves code
  * @req REQ-DIFFERENT-REQUIREMENTS - Verify that annotations with different requirement IDs are preserved
+ * @req REQ-CATCH-BLOCK-HANDLING - Verify that catch block annotations are not incorrectly treated as redundant
  */
 const eslint_1 = require("eslint");
 const no_redundant_annotation_1 = __importDefault(require("../../src/rules/no-redundant-annotation"));
@@ -37,6 +38,14 @@ describe("no-redundant-annotation rule (Story 027.0-DEV-REDUNDANT-ANNOTATION-DET
                 name: "[REQ-SCOPE-ANALYSIS] preserves annotations on both branch and statement when they intentionally duplicate each other",
                 code: `function example() {\n  if (condition) { // @story docs/stories/007.0-EXAMPLE.story.md @req REQ-BRANCH\n    // @story docs/stories/007.0-EXAMPLE.story.md\n    // @req REQ-BRANCH\n    doBranchWork();\n  }\n}`,
             },
+            {
+                name: "[REQ-CATCH-BLOCK-HANDLING] preserves catch block annotation from issue #6 scenario",
+                code: `async function example() {\n  try {\n    // @story prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.story.md\n    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-SAFE-ONLY\n    if (isSafeVersion({ version, vulnerabilityData })) {\n      return version;\n    }\n\n    // @story prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.story.md\n    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-SAFE-ONLY\n    if (!vulnerabilityData.isVulnerable) {\n      return version;\n    }\n  } catch (error) {\n    // @story prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.story.md\n    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-SAFE-ONLY\n    return null;\n  }\n}`,
+            },
+            {
+                name: "[REQ-CATCH-BLOCK-HANDLING] preserves annotations in nested catch blocks with repeated requirements",
+                code: `async function nestedCatches() {\n  try {\n    await checkPrimary();\n  } catch (outerError) {\n    // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-SAFE-ONLY\n    try {\n      await attemptRecovery(outerError);\n    } catch (innerError) {\n      // @supports prompts/004.0-DEV-FILTER-VULNERABLE-VERSIONS.md REQ-SAFE-ONLY\n      await reportFailure(innerError);\n    }\n  }\n}`,
+            },
         ],
         invalid: [
             {
@@ -87,6 +96,12 @@ describe("no-redundant-annotation rule (Story 027.0-DEV-REDUNDANT-ANNOTATION-DET
                 output: `/**\n * @story docs/stories/009.0-EXAMPLE.story.md\n * @supports REQ-SUP-A, REQ-SUP-B\n */\nfunction example() {\n  const supported = checkSupport();\n}`,
                 errors: [{ messageId: "redundantAnnotation" }],
             },
+            {
+                name: "[REQ-SCOPE-ANALYSIS][REQ-STATEMENT-SIGNIFICANCE] flags redundant annotation in finally block that repeats try-path coverage",
+                code: `async function example() {\n  // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION\n  try {\n    await doWork();\n  } finally {\n    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION\n    await cleanUp();\n  }\n}`,
+                output: `async function example() {\n  // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION\n  try {\n    await doWork();\n  } finally {\n    await cleanUp();\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",

package/lib/tests/rules/require-branch-annotation.test.js

@@ -8,15 +8,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md
+ * @story docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md
  * @req REQ-BRANCH-DETECTION - Verify require-branch-annotation rule enforces branch annotations
  * @req REQ-ERROR-SPECIFIC - Branch-level missing-annotation error messages are specific and informative
  * @req REQ-ERROR-CONSISTENCY - Branch-level missing-annotation error messages follow shared conventions
  * @req REQ-ERROR-SUGGESTION - Branch-level missing-annotation errors include suggestions when applicable
  * @req REQ-NESTED-HANDLING - Nested branch annotations are correctly enforced without duplicative reporting
  * @req REQ-SUPPORTS-ALTERNATIVE - Branches annotated only with @supports are treated as fully annotated
+ * @req REQ-PLACEMENT-CONFIG - Rule supports configurable annotation placement modes
+ * @req REQ-DEFAULT-BACKWARD-COMPAT - Default placement remains backward compatible with existing behavior
  * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION REQ-NESTED-HANDLING REQ-SUPPORTS-ALTERNATIVE
  * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SPECIFIC REQ-ERROR-CONSISTENCY REQ-ERROR-SUGGESTION
  * @supports docs/stories/026.0-DEV-ELSE-IF-ANNOTATION-POSITION.story.md REQ-DUAL-POSITION-DETECTION-ELSE-IF REQ-FALLBACK-LOGIC-ELSE-IF REQ-POSITION-PRIORITY-ELSE-IF REQ-PRETTIER-AUTOFIX-ELSE-IF
+ * @supports docs/stories/028.0-DEV-ANNOTATION-PLACEMENT-STANDARDIZATION.story.md REQ-PLACEMENT-CONFIG REQ-DEFAULT-BACKWARD-COMPAT
  */
 const eslint_1 = require("eslint");
 const require_branch_annotation_1 = __importDefault(require("../../src/rules/require-branch-annotation"));
@@ -184,6 +188,20 @@ if (outer) {
 if (condition) {}`,
                 options: [{ branchTypes: ["IfStatement", "SwitchCase"] }],
             },
+            {
+                name: "[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] if-statement with before-brace annotations using annotationPlacement: 'before'",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-PLACEMENT-CONFIG
+if (condition) {}`,
+                options: [{ annotationPlacement: "before" }],
+            },
+            {
+                name: "[REQ-PLACEMENT-CONFIG][REQ-DEFAULT-BACKWARD-COMPAT] if-statement with before-brace annotations using annotationPlacement: 'inside' (temporary backward-compatible behavior)",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-PLACEMENT-CONFIG
+if (condition) {}`,
+                options: [{ annotationPlacement: "inside" }],
+            },
             {
                 name: "[REQ-SUPPORTS-ALTERNATIVE] if-statement with only @supports annotation is treated as fully annotated",
                 code: `// @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-SUPPORTS-ALTERNATIVE

package/lib/tests/utils/{annotation-checker-branches.test.d.ts → annotation-checker-autofix-behavior.test.d.ts}

@@ -1,5 +1,5 @@
 /**
- * Focused branch coverage tests for annotation-checker helper.
+ * Focused autofix behavior tests for annotation-checker helper.
  * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-AUTOFIX REQ-ANNOTATION-REPORTING
  */
 export {};

package/lib/tests/utils/{annotation-checker-branches.test.js → annotation-checker-autofix-behavior.test.js}

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Focused branch coverage tests for annotation-checker helper.
+ * Focused autofix behavior tests for annotation-checker helper.
  * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-AUTOFIX REQ-ANNOTATION-REPORTING
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -34,7 +34,7 @@ function createContextStub() {
     };
     return { context, report };
 }
-describe("annotation-checker helper branch coverage (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
+describe("annotation-checker helper autofix behavior (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
     it("[REQ-ANNOTATION-AUTOFIX] attaches fix directly to node when parent is missing", () => {
         const { context, report } = createContextStub();
         const node = { type: "FunctionDeclaration" }; // no parent property

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.17.0",
+  "version": "1.18.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",
@@ -88,7 +88,7 @@
     "jest": "^30.2.0",
     "jscpd": "^4.0.5",
     "lint-staged": "^16.2.7",
-    "prettier": "^3.6.2",
+    "prettier": "^3.7.4",
     "semantic-release": "25.0.2",
     "ts-jest": "^29.4.6",
     "typescript": "^5.9.3",

package/user-docs/api-reference.md

@@ -290,7 +290,7 @@ The rule accepts an optional configuration object:
 - `requireDescribeStory` (boolean, optional) – When `true` (default), requires that each top-level `describe` block include a story reference somewhere in its description text (for example, a path such as `docs/stories/010.0-PAYMENTS.story.md` or a shorter project-specific alias that your team uses consistently).
 - `requireTestReqPrefix` (boolean, optional) – When `true` (default), requires each `it`/`test` block name to begin with a requirement identifier in square brackets, such as `[REQ-PAYMENTS-REFUND]`. The exact `REQ-` pattern is shared with the `valid-annotation-format` rule’s requirement ID checks.
 - `describePattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that the `describe` description text must match when `requireDescribeStory` is enabled. This lets you enforce a project-specific format such as requiring a canonical story path or a `STORY-` style identifier in the `describe` string. If omitted, the default is equivalent to `"Story [0-9]+\\.[0-9]+-"`, which expects the description to include a story label such as `"Story 021.0-DEV-TEST-TRACEABILITY"`. You can override this to instead require full story paths or whatever story-labeling convention your project prefers.
-- `autoFixTestTemplate` (boolean, optional) – When `true` (default), allows the rule’s `--fix` mode to insert a file-level `@supports` placeholder template at the top of test files that are missing it. The template is intentionally non-semantic and includes TODO-style guidance so humans can later replace it with a real story path and requirement IDs; disabling this option prevents the rule from inserting the template automatically.
+- `autoFixTestTemplate` (boolean, optional) – When `true` (default), allows the rule’s `--fix` mode to insert a file-level `@supports` placeholder template at the top of test files that are missing it. The template is intentionally non-semantic and includes TODO-style guidance so humans can later replace it with a real story and requirement IDs; disabling this option prevents the rule from inserting the template automatically.
 - `autoFixTestPrefixFormat` (boolean, optional) – When `true` (default), enables safe normalization of malformed `[REQ-XXX]` prefixes in `it`/`test` names during `--fix`. The rule only rewrites prefixes that already contain a recognizable requirement identifier and limits changes to formatting concerns (spacing, square brackets vs. parentheses, underscore and dash usage, and letter casing) without fabricating new IDs or guessing requirement names.
 - `testSupportsTemplate` (string, optional) – Overrides the default file-level `@supports` placeholder template used when `autoFixTestTemplate` is enabled. This string should be a complete JSDoc-style block (for example, including `/**`, `*`, and `*/`) that encodes your project’s preferred TODO guidance or placeholder story path; it is inserted verbatim at the top of matching test files that lack a `@supports` annotation, and is never interpreted or expanded by the rule.
 
@@ -327,6 +327,8 @@ describe("Refunds flow docs/stories/010.0-PAYMENTS.story.md", () => {
 
 Description: Detects and optionally removes **redundant** traceability annotations on code that is already covered by an enclosing annotated scope. It focuses on simple, statement-level constructs—such as `return` statements, basic variable declarations, and other leaf statements—where repeating the same `@story` / `@req` / `@supports` information adds noise without improving coverage. When run with `--fix`, the rule offers safe auto-fixes that remove only the redundant comments while preserving all annotations that are required to maintain correct traceability.
 
+Catch blocks are treated as separate execution paths for traceability purposes, and annotations inside a `catch` block that intentionally repeat the requirements of the corresponding `try` path are not considered redundant and are never auto-removed. This behavior was introduced as part of story `027.0-DEV-REDUNDANT-ANNOTATION-DETECTION (Detect and Remove Redundant Annotations)` to avoid false positives on error-handling paths that implement the same requirement as the success path.
+
 The rule is designed to complement the core presence and validation rules: it never treats removing a redundant annotation as valid if doing so would leave the underlying requirement or story **uncovered** according to the plugin’s normal rules. It only targets comments whose traceability content is already implied by a surrounding function, method, or branch annotation.
 
 Options:
@@ -344,6 +346,9 @@ The rule accepts an optional configuration object:
 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. 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.
+- **Catch blocks and error-handling paths**
+  - The rule never treats annotations inside a `catch` block as redundant, even when they repeat exactly the same `(story, requirement)` pairs that already cover the surrounding `try` statement or other enclosing branches.
+  - This preserves explicit traceability for error-handling logic, in line with the requirements captured in story `027.0-DEV-REDUNDANT-ANNOTATION-DETECTION`, and avoids collapsing success-path and failure-path coverage into a single, less precise annotation.
 - 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.
 

package/user-docs/examples.md

@@ -187,3 +187,35 @@ Depending on your Prettier version and configuration, the exact layout of the `e
   - For most branch types, `traceability/require-branch-annotation` associates comments immediately before the branch keyword (such as `if`, `else`, `switch`, `case`) with that branch. Branches can be annotated either with a single `@supports` line (preferred), or with the older `@story`/`@req` pair for backward compatibility. The rule treats a valid `@supports` annotation as satisfying both the story and requirement presence checks.
   - For `catch` clauses and `else if` branches, the rule is formatter-aware and also looks at comments between the condition and the block, as well as the first comment-only lines inside the block body, so you do not need to fight Prettier if it moves your annotations.
   - When annotations exist in more than one place around an `else if` branch, the rule prefers comments immediately before the `else if` line, then comments between the condition and the block, and finally comments inside the block body, matching the behavior described in the API reference and stories `025.0` and `026.0`.
+
+## 7. Redundant annotations and catch blocks
+
+When `traceability/no-redundant-annotation` is enabled (for example, via the recommended preset), `catch` blocks are always treated as distinct execution paths. Repeating the same `(story, requirement)` pair in a `catch` block as in the corresponding `try` path is not considered redundant and will be preserved. This behavior is part of the improvements captured in story `027.0-DEV-REDUNDANT-ANNOTATION-DETECTION`.
+
+In the following example, running ESLint with `--fix` will not remove the `@supports` annotation on the `catch` block, even though it repeats the requirement from the `try` path, because it represents separate error-handling coverage.
+
+```js
+function filterSafeVersions(allVersions) {
+  try {
+    const stable = allVersions.filter((v) => !v.includes("-beta"));
+
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    if (stable.length > 0) {
+      return stable;
+    }
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    else if (allVersions.length > 0) {
+      // Fall back to all versions if we have no clearly stable ones
+      return allVersions;
+    }
+
+    // Fallback when the input list is empty
+    return [];
+  } catch (error) {
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    // traceability/no-redundant-annotation keeps this as separate error-handling coverage,
+    // even though it repeats the requirement from the try path.
+    return [];
+  }
+}
+```

package/user-docs/migration-guide.md

@@ -123,7 +123,7 @@ A typical migration path is:
 - Enable it as `"warn"` to get non-breaking guidance and auto-fixes for straightforward cases.
 - Optionally move to `"error"` once you want to strictly enforce `@supports` usage for all JSDoc blocks that are eligible for safe conversion.
 
-#### When to keep `@story` + `@req`
+#### When to keep `@story` + `req`
 
 Keep your current annotations if:
 
@@ -229,6 +229,8 @@ In all cases, the rule is conservative:
 
 The rule operates over both `@supports` and legacy `@story`/`@req` style annotations, so it continues to work even in mixed codebases during a long-running migration.
 
+In addition, `catch` blocks are treated as distinct execution paths: repeating the same `(story, requirement)` pair in a `catch` block is **not** considered redundant, because the error-handling path is typically validated and reasoned about separately from the main control flow.
+
 A simplified example, using an illustrative story path that represents a file in **your** documentation tree:
 
 Before (redundant duplication inside a branch):
@@ -271,6 +273,38 @@ if (cart.items.length === 0) {
 }
 ```
 
+#### Example: try/if/else-if/catch with non-redundant catch annotation
+
+The following example shows a `try` block with an `if` / `else if` chain that validates a safe operation, and a `catch` block that handles the error path for the **same** requirement. Both paths are annotated with the same `(story, requirement)` pair to make it clear that the requirement covers normal execution and error handling:
+
+```js
+async function performSafeOperation(input) {
+  try {
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    if (input == null) {
+      throw new Error("Missing input");
+    }
+
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    if (typeof input === "string") {
+      return await doSafeStringOperation(input);
+    } else if (Array.isArray(input)) {
+      return await doSafeArrayOperation(input);
+    }
+
+    return await doSafeFallbackOperation(input);
+  } catch (error) {
+    // This catch represents the error-handling path for the same safe-operation requirement.
+    // Even though the coverage matches the try/if/else-if chain above, it is *not* redundant:
+    // it documents how failures are handled for the same requirement.
+    // @supports docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION
+    return handleSafeOperationFailure(error, input);
+  }
+}
+```
+
+Here, `traceability/no-redundant-annotation` recognizes the `catch` block as a separate execution path from the main `try` body. The annotation in the `catch` remains intact and is **not** treated as redundant, even though it repeats the same `docs/stories/010.0-EXAMPLE.story.md REQ-SAFE-OPERATION` coverage as the guarded `if` / `else if` chain in the `try`. This behavior was introduced and validated as part of story `027.0-DEV-REDUNDANT-ANNOTATION-DETECTION (Detect and Remove Redundant Annotations)` to prevent regressions in real-world `try/if/else-if/catch` scenarios like the one discussed there.
+
 #### Safe migration workflow
 
 To use `traceability/no-redundant-annotation` safely during your v1.x migration: