eslint-plugin-traceability 1.11.1 → 1.11.3

package/lib/tests/utils/req-annotation-detection.test.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const reqAnnotationDetection_1 = require("../../src/utils/reqAnnotationDetection");
+// Small helper to construct a minimal SourceCode-like object for the detection helpers.
+function createMockSourceCode(options = {}) {
+    const { lines = null, text = "", commentsBefore = [] } = options;
+    return {
+        lines: lines ?? undefined,
+        getText() {
+            return text;
+        },
+        getCommentsBefore() {
+            return commentsBefore;
+        },
+    };
+}
+describe("reqAnnotationDetection advanced heuristics (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
+    it("[REQ-ANNOTATION-REQ-DETECTION] returns false when sourceCode is missing", () => {
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], undefined, {
+            loc: null,
+        });
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] returns false when node is missing", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({ lines: ["/** @req REQ-TEST */"] });
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, undefined);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] inspects jsdoc and comments when advanced heuristics throw", () => {
+        const context = {
+            getSourceCode() {
+                // This object intentionally causes hasReqInAdvancedHeuristics to throw by
+                // providing a getCommentsBefore implementation that throws on access.
+                return {
+                    getCommentsBefore() {
+                        throw new Error("boom");
+                    },
+                };
+            },
+        };
+        const jsdoc = { value: "/** @req REQ-FROM-JSDOC */" };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, {
+            // Minimal shape – the helper will call into the mock sourceCode and trigger the throw
+            parent: {},
+        });
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] treats @supports in comments as satisfying requirement", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode();
+            },
+        };
+        const comments = [{ value: "// @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-X" }];
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, comments, context, {
+            parent: {},
+        });
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] linesBeforeHasReq returns false when lines is not an array", () => {
+        const context = {
+            getSourceCode() {
+                // lines is null here, causing the helper to see a non-array and return false
+                return createMockSourceCode({ lines: null });
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, {
+            // Provide a minimal location so advanced heuristics try to use line info
+            loc: { start: { line: 5 } },
+            parent: {},
+        });
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] linesBeforeHasReq returns false when startLine is not a number", () => {
+        const sourceCode = createMockSourceCode({ lines: ["// @req REQ-SHOULD-NOT-BE-SEEN"] });
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], { getSourceCode: () => sourceCode }, {
+            // loc is missing/undefined; startLine will not be a valid number
+            loc: undefined,
+            parent: {},
+        });
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] parentChainHasReq returns false when getCommentsBefore is not a function and no leadingComments/parents have req", () => {
+        const context = {
+            getSourceCode() {
+                return {
+                    // getCommentsBefore is not a function here
+                    getCommentsBefore: 123,
+                };
+            },
+        };
+        const node = {
+            parent: {
+                leadingComments: [{ value: "no req here" }],
+                parent: {
+                    leadingComments: [{ value: "still nothing" }],
+                },
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] parentChainHasReq returns true when getCommentsBefore returns comments containing @req", () => {
+        const sourceCode = {
+            getCommentsBefore(n) {
+                if (n && n.isTargetParent) {
+                    return [{ value: "/* @req REQ-FROM-PARENT */" }];
+                }
+                return [];
+            },
+        };
+        const context = {
+            getSourceCode() {
+                return sourceCode;
+            },
+        };
+        const node = {
+            parent: {
+                isTargetParent: true,
+                parent: {},
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when getText is not a function", () => {
+        const context = {
+            getSourceCode() {
+                return {
+                    // getText is not a function
+                    getText: "not-a-function",
+                };
+            },
+        };
+        const node = {
+            range: [0, 10],
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when node.range is not an array", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({ text: "/* @req REQ-IN-TEXT */" });
+            },
+        };
+        const node = {
+            // range is missing; helper should see non-array range and return false
+            range: null,
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns true when text window contains @req", () => {
+        const fullText = `
+      // some header
+      /** @req REQ-IN-TEXT-WINDOW */
+      function foo() {}
+    `;
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({ text: fullText });
+            },
+        };
+        // Choose a range that starts after the @req comment so the "text before"
+        // window that the helper inspects includes the annotation.
+        const startIndex = fullText.indexOf("function foo");
+        const node = {
+            range: [startIndex, startIndex + 5],
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when getText throws", () => {
+        const context = {
+            getSourceCode() {
+                return {
+                    getText() {
+                        throw new Error("boom from getText");
+                    },
+                };
+            },
+        };
+        const node = {
+            range: [0, 10],
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqInAdvancedHeuristics short-circuits and returns false when sourceCode is missing", () => {
+        const context = {
+        // No getSourceCode method at all – internal advanced heuristics
+        // should immediately return false and not throw.
+        };
+        const node = {
+            loc: { start: { line: 3 } },
+            range: [0, 10],
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqInAdvancedHeuristics short-circuits and returns false when node is missing", () => {
+        const context = {
+            getSourceCode() {
+                return createMockSourceCode({ text: "@req REQ-SHOULD-NOT-BE-SEEN" });
+            },
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, undefined);
+        expect(has).toBe(false);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqAnnotation returns true when jsdoc contains @supports and advanced heuristics are false", () => {
+        const context = {
+            getSourceCode() {
+                // Returning a sourceCode that will not satisfy any advanced heuristic
+                // (no lines, no comments, empty text).
+                return createMockSourceCode({ lines: [], text: "" });
+            },
+        };
+        const jsdoc = {
+            value: "/** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-JSDOC-SUPPORTS */",
+        };
+        const node = {
+            parent: {},
+        };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, node);
+        expect(has).toBe(true);
+    });
+    it("[REQ-ANNOTATION-REQ-DETECTION] falls back to jsdoc/comments when context.getSourceCode throws", () => {
+        const context = {
+            getSourceCode() {
+                throw new Error("boom from getSourceCode");
+            },
+        };
+        const jsdoc = { value: "/** @req REQ-FROM-GETSOURCECODE */" };
+        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, { parent: {} });
+        expect(has).toBe(true);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.11.1",
+  "version": "1.11.3",
   "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",
@@ -29,7 +29,7 @@
     "lint": "eslint --config eslint.config.js \"src/**/*.{js,ts}\" \"tests/**/*.{js,ts}\" --max-warnings=0",
     "test": "jest --ci --bail",
     "ci-verify": "npm run type-check && npm run lint && npm run format:check && npm run duplication && npm run check:traceability && npm test && npm run audit:ci && npm run safety:deps",
-    "ci-verify:full": "npm run check:traceability && npm run safety:deps && npm run audit:ci && npm run build && npm run type-check && npm run lint-plugin-check && npm run lint -- --max-warnings=0 && npm run duplication && npm run test -- --coverage && npm run format:check && npm audit --omit=dev --audit-level=high && npm run audit:dev-high",
+    "ci-verify:full": "npm run check:traceability && npm run safety:deps && npm run audit:ci && npm run build && npm run type-check && npm run lint-plugin-check && npm run lint -- --max-warnings=0 && npm run duplication && npm run test -- --coverage && npm run format:check && npm audit --omit=dev --audit-level=high && npm run audit:dev-high && npm run check:ci-artifacts",
     "ci-verify:fast": "npm run type-check && npm run check:traceability && npm run duplication && jest --ci --bail --passWithNoTests --testPathPatterns 'tests/(rules|maintenance)'",
     "format": "prettier --write .",
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
@@ -41,7 +41,7 @@
     "safety:deps": "node scripts/ci-safety-deps.js",
     "audit:ci": "node scripts/ci-audit.js",
     "check:ci-artifacts": "node scripts/check-no-tracked-ci-artifacts.js",
-    "security:secrets": "secretlint \"**/*\" --no-color",
+    "security:secrets": "secretlint \"**/*\"",
     "smoke-test": "./scripts/smoke-test.sh",
     "debug:cli": "node scripts/cli-debug.js",
     "debug:require-story": "node scripts/debug-require-story.js",
@@ -99,7 +99,7 @@
     "eslint": "^9.0.0"
   },
   "engines": {
-    "node": ">=18.18.0"
+    "node": "^18.18.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
   },
   "overrides": {
     "glob": "12.0.0",

package/user-docs/api-reference.md

@@ -15,7 +15,7 @@ In addition to the core `@story` and `@req` annotations, the plugin also underst
 `@supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND`
 to indicate that a given function supports a particular requirement from a payments story document within that project’s own `docs/stories` tree. For a detailed explanation of `@supports` behavior and validation, see [Migration Guide](migration-guide.md) (section **3.1 Multi-story @supports annotations**). Additional background on multi-story semantics is available in the project’s internal rule documentation, which is intended for maintainers rather than end users.
 
-The `prefer-implements-annotation` rule is an **opt-in migration helper** that is disabled by default and **not** part of any built-in preset. It can be enabled and given a severity like `"warn"` or `"error"` using normal ESLint rule configuration when you want to gradually encourage multi-story `@supports` usage. Detailed behavior and migration guidance are documented in the project’s internal rule documentation, which is targeted at maintainers; typical end users can rely on the high-level guidance in this API reference and the [Migration Guide](migration-guide.md).
+The `prefer-supports-annotation` rule is an **opt-in migration helper** that is disabled by default and **not** part of any built-in preset. It can be enabled and given a severity like `"warn"` or `"error"` using normal ESLint rule configuration when you want to gradually encourage multi-story `@supports` usage. The legacy rule key `traceability/prefer-implements-annotation` remains available as a **deprecated alias** for backward compatibility, but new configurations should prefer `traceability/prefer-supports-annotation`. Detailed behavior and migration guidance are documented in the project’s internal rule documentation, which is targeted at maintainers; typical end users can rely on the high-level guidance in this API reference and the [Migration Guide](migration-guide.md).
 
 ### traceability/require-story-annotation
 
@@ -68,11 +68,17 @@ function initAuth() {
 
 ### traceability/require-branch-annotation
 
-Description: Ensures significant code branches (if/else, loops, switch cases, try/catch) have both `@story` and `@req` annotations in preceding comments.
+Description: Ensures significant code branches (if/else, loops, switch cases, try/catch) have both `@story` and `@req` annotations in preceding comments. For `catch` clauses specifically, the rule accepts annotations either immediately before the `catch` keyword or as the first comment-only lines inside the catch block. This dual-position handling is designed to stay compatible with common formatters such as Prettier, which often move comments from before `catch` into the catch body.
+
 Options:
 
 - `branchTypes` (string[], optional) – AST node types that are treated as significant branches for annotation enforcement. Allowed values: "IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement". Default: ["IfStatement", "SwitchCase", "TryStatement", "CatchClause", "ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement"]. If an invalid branch type is provided, the rule reports a configuration error for each invalid value.
 
+Behavior notes:
+
+- When both before-`catch` and inside-block annotations are present for the same catch clause, the comments immediately before `catch` take precedence for validation and reporting.
+- When auto-fixing missing annotations on a catch clause, the rule inserts placeholder comments inside the catch body so that formatters like Prettier preserve them and do not move them to unexpected locations.
+
 Default Severity: `error`
 Example:
 
@@ -246,9 +252,9 @@ describe("Refunds flow docs/stories/010.0-PAYMENTS.story.md", () => {
 });
 ```
 
-### traceability/prefer-implements-annotation
+### traceability/prefer-supports-annotation
 
-Description: An optional, opt-in migration helper that encourages converting legacy single‑story `@story` + `@req` JSDoc blocks into the newer multi‑story `@supports` format. The rule is **disabled by default** and is **not included in any built‑in preset**; you enable it explicitly and control its behavior entirely via ESLint severity (`"off" | "warn" | "error"`). It does not change what the core rules consider valid—it only adds migration recommendations and safe auto‑fixes on top of existing validation.
+Description: An optional, opt-in migration helper that encourages converting legacy single‑story `@story` + `@req` JSDoc blocks into the newer multi‑story `@supports` format. The rule is **disabled by default** and is **not included in any built‑in preset**; you enable it explicitly and control its behavior entirely via ESLint severity (`"off" | "warn" | "error"`). It does not change what the core rules consider valid—it only adds migration recommendations and safe auto‑fixes on top of existing validation. The legacy rule key `traceability/prefer-implements-annotation` is still recognized as a **deprecated alias** for `traceability/prefer-supports-annotation` so that existing configurations continue to work unchanged.
 
 Options: None – this rule does not accept a configuration object. All tuning is done via the ESLint rule level (`"off"`, `"warn"`, `"error"`).
 
@@ -272,7 +278,6 @@ Main behaviors:
    ```
 
    Conceptually, the auto‑fix:
-
    - Extracts the single `@story` value.
    - Collects the requirement IDs from each `@req` line in that block.
    - Emits a single `@supports story-path#REQ-1 REQ-2 ...` line (or your project’s equivalent anchor scheme).
@@ -319,7 +324,7 @@ function issueRefund() {
 }
 ```
 
-With `traceability/prefer-implements-annotation` enabled and ESLint run with `--fix`, the rule rewrites it to:
+With `traceability/prefer-supports-annotation` enabled (or its deprecated alias `traceability/prefer-implements-annotation`) and ESLint run with `--fix`, the rule rewrites it to:
 
 ```js
 /**
@@ -344,9 +349,11 @@ export default [
   traceability.configs.recommended,
   {
     rules: {
-      "traceability/prefer-implements-annotation": "warn"
-    }
-  }
+      "traceability/prefer-supports-annotation": "warn",
+      // The deprecated alias is still honored if you prefer:
+      // "traceability/prefer-implements-annotation": "warn",
+    },
+  },
 ];
 ```
 
@@ -359,7 +366,7 @@ The plugin provides two built-in presets for easy configuration:
 Enables the **six core traceability rules** with severities tuned for common usage (most at `error`, with
 `traceability/valid-annotation-format` at `warn` to reduce noise). This `warn` level for `traceability/valid-annotation-format` is intentional to keep early adoption noise low, but you can safely raise it to `error` in projects that want strict enforcement of annotation formatting.
 
-The `prefer-implements-annotation` migration rule is **not included** in this (or any) preset and remains disabled by default. If you want to encourage or enforce multi-story `@supports` annotations, you must enable `traceability/prefer-implements-annotation` explicitly in your ESLint configuration and choose an appropriate severity (for example, `"warn"` during migration or `"error"` once fully adopted).
+The `prefer-supports-annotation` migration rule (and its deprecated alias key `traceability/prefer-implements-annotation`) is **not included** in this (or any) preset and remains disabled by default. If you want to encourage or enforce multi-story `@supports` annotations, you must enable `traceability/prefer-supports-annotation` explicitly in your ESLint configuration and choose an appropriate severity (for example, `"warn"` during migration or `"error"` once fully adopted).
 
 Core rules enabled by the `recommended` preset:
 
@@ -382,7 +389,7 @@ export default [js.configs.recommended, traceability.configs.recommended];
 
 ### strict
 
-Currently mirrors the **recommended** preset, reserved for future stricter policies. As with the `recommended` preset, the `traceability/prefer-implements-annotation` rule is **not** enabled here by default and must be configured manually if desired.
+Currently mirrors the **recommended** preset, reserved for future stricter policies. As with the `recommended` preset, the `traceability/prefer-supports-annotation` rule is **not** enabled here by default, and the deprecated alias key `traceability/prefer-implements-annotation` continues to be honored only when you opt into it manually in your own configuration.
 
 Usage:
 
@@ -682,4 +689,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
+```

package/user-docs/examples.md

@@ -112,4 +112,5 @@ describe("Story 021.0-DEV-TEST-TRACEABILITY", () => {
 function performOperation(input: string): string {
   if (input === "edge-case") return "edge-ok";
   return "ok";
-}
+}
+```

package/user-docs/migration-guide.md

@@ -57,18 +57,22 @@ function integrate() {}
 
 You **do not** need to change existing, single-story annotations that already use `@story` and `@req`. Migration to `@supports` is only recommended when a function or module genuinely implements requirements from more than one story file.
 
-#### Optional `prefer-implements-annotation` migration rule
+#### Optional `prefer-supports-annotation` migration rule
 
-For teams that want to gradually migrate from `@story` + `@req` to `@supports`, the plugin provides an optional rule: `traceability/prefer-implements-annotation`.
+For teams that want to gradually migrate from `@story` + `@req` to `@supports`, the plugin provides an optional rule: `traceability/prefer-supports-annotation`.
 
-- This rule is **disabled by default** and is **not** included in any built-in presets.
+- This is the canonical rule name starting in v1.x.
+- The legacy key `traceability/prefer-implements-annotation` remains supported as a **deprecated alias** for backward compatibility, but should not be used in new configurations.
+
+- This rule is **disabled by default** and is **not** included in any built-in presets (the deprecated alias is also not enabled by any presets).
 - You can enable it with any standard ESLint severity (`"off"`, `"warn"`, or `"error"`) in your config, for example:
 
   ```js
   // excerpt from eslint.config.js
   {
     rules: {
-      "traceability/prefer-implements-annotation": "warn",
+      "traceability/prefer-supports-annotation": "warn",
+      // "traceability/prefer-implements-annotation": "warn", // deprecated alias
     },
   }
   ```
@@ -100,8 +104,8 @@ Aligned with the internal rule behavior, the key cases are:
   - Comments that contain only `@req` lines,
   - Comments that contain only `@supports` lines, and
   - Line comments such as `// @story ...`.
-  
-  These forms are still supported by the plugin and are not modified by `traceability/prefer-implements-annotation`.
+
+  These forms are still supported by the plugin and are not modified by `traceability/prefer-supports-annotation`.
 
 A typical migration path is:
 
@@ -204,4 +208,4 @@ Production dependency guarantees are enforced by CI scripts that run `npm audit
 
 ---
 
-If you encounter any issues during migration, please file an issue at https://github.com/voder-ai/eslint-plugin-traceability/issues.
+If you encounter any issues during migration, please file an issue at https://github.com/voder-ai/eslint-plugin-traceability/issues.