eslint-plugin-traceability 1.2.0 → 1.4.0

package/lib/tests/rules/error-reporting.test.d.ts

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

package/lib/tests/rules/error-reporting.test.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-SPECIFIC - Specific details about what annotation is missing or invalid
+ * @req REQ-ERROR-SUGGESTION - Suggest concrete steps to fix the issue
+ * @req REQ-ERROR-CONTEXT - Include relevant context in error messages
+ */
+const eslint_1 = require("eslint");
+const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
+const ruleTester = new eslint_1.RuleTester({
+    languageOptions: {
+        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+    },
+});
+describe("Error Reporting Enhancements for require-story-annotation (Story 007.0-DEV-ERROR-REPORTING)", () => {
+    ruleTester.run("require-story-annotation", require_story_annotation_1.default, {
+        valid: [
+            {
+                name: "[007.0-DEV-ERROR-REPORTING] valid with existing annotation",
+                code: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */ function foo() {}`,
+            },
+        ],
+        invalid: [
+            {
+                name: "[REQ-ERROR-SPECIFIC] missing @story annotation should report specific details and suggestion",
+                code: `function bar() {}`,
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        data: { name: "bar" },
+                        suggestions: [
+                            {
+                                desc: "Add JSDoc @story annotation for function 'bar', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
+                                output: "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ],
+    });
+});

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

@@ -120,6 +120,18 @@ while (condition) {
     doSomething();
 }`,
             },
+            {
+                name: "[REQ-CONFIGURABLE-SCOPE] custom branchTypes ignores unlisted branch types",
+                code: `switch (value) { case 'a': break; }`,
+                options: [{ branchTypes: ["IfStatement"] }],
+            },
+            {
+                name: "[REQ-CONFIGURABLE-SCOPE] custom branchTypes only enforce listed types",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-DETECTION
+if (condition) {}`,
+                options: [{ branchTypes: ["IfStatement", "SwitchCase"] }],
+            },
         ],
         invalid: [
             {
@@ -248,6 +260,32 @@ try {
                     { messageId: "missingAnnotation", data: { missing: "@req" } },
                 ],
             },
+            {
+                name: "[REQ-CONFIGURABLE-SCOPE] missing annotations on configured branch type ForStatement",
+                code: `for (let i = 0; i < 3; i++) {}`,
+                options: [{ branchTypes: ["ForStatement"] }],
+                output: `// @story <story-file>.story.md
+for (let i = 0; i < 3; i++) {}`,
+                errors: [
+                    { messageId: "missingAnnotation", data: { missing: "@story" } },
+                    { messageId: "missingAnnotation", data: { missing: "@req" } },
+                ],
+            },
+        ],
+    });
+    ruleTester.run("require-branch-annotation", require_branch_annotation_1.default, {
+        valid: [],
+        invalid: [
+            {
+                name: "[REQ-CONFIGURABLE-SCOPE] invalid branchTypes option should error schema",
+                code: "if (condition) {}",
+                options: [{ branchTypes: ["UnknownType"] }],
+                errors: [
+                    {
+                        message: /should be equal to one of the allowed values/,
+                    },
+                ],
+            },
         ],
     });
 });

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

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// @ts-nocheck
 /**
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -65,52 +66,100 @@ declare function tsDecl(): void;`,
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story annotation on function",
                 code: `function bar() {}`,
-                output: `/** @story <story-file>.story.md */\nfunction bar() {}`,
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'bar', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on function expression",
                 code: `const fnExpr = function() {};`,
-                output: `/** @story <story-file>.story.md */\nconst fnExpr = function() {};`,
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'fnExpr', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on arrow function",
                 code: `const arrowFn = () => {};`,
-                output: `/** @story <story-file>.story.md */\nconst arrowFn = () => {};`,
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'arrowFn', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst arrowFn = () => {};`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on class method",
                 code: `class C {\n  method() {}\n}`,
-                output: `class C {\n  /** @story <story-file>.story.md */\n  method() {}\n}`,
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `class C {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on TS declare function",
                 code: `declare function tsDecl(): void;`,
-                output: `/** @story <story-file>.story.md */
-declare function tsDecl(): void;`,
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2020, sourceType: "module" },
                 },
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'tsDecl', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @story on TS method signature",
-                code: `interface D {
-  method(): void;
-}`,
-                output: `/** @story <story-file>.story.md */
-interface D {
-  method(): void;
-}`,
+                code: `interface D {\n  method(): void;\n}`,
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2020, sourceType: "module" },
                 },
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ninterface D {\n  method(): void;\n}`,
+                            },
+                        ],
+                    },
+                ],
             },
         ],
     });
@@ -131,16 +180,34 @@ interface D {
             {
                 name: "[exportPriority] exported function missing @story annotation",
                 code: `export function exportedMissing() {}`,
-                output: `/** @story <story-file>.story.md */\nexport function exportedMissing() {}`,
                 options: [{ exportPriority: "exported" }],
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'exportedMissing', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nexport function exportedMissing() {}`,
+                            },
+                        ],
+                    },
+                ],
             },
             {
                 name: "[exportPriority] exported arrow function missing @story annotation",
                 code: `export const arrowExported = () => {};`,
-                output: `/** @story <story-file>.story.md */\nexport const arrowExported = () => {};`,
                 options: [{ exportPriority: "exported" }],
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'arrowExported', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nexport const arrowExported = () => {};`,
+                            },
+                        ],
+                    },
+                ],
             },
         ],
     });
@@ -157,8 +224,17 @@ interface D {
                 name: "[scope] function declaration missing annotation when scope is FunctionDeclaration",
                 code: `function onlyDecl() {}`,
                 options: [{ scope: ["FunctionDeclaration"] }],
-                output: `/** @story <story-file>.story.md */\nfunction onlyDecl() {}`,
-                errors: [{ messageId: "missingStory" }],
+                errors: [
+                    {
+                        messageId: "missingStory",
+                        suggestions: [
+                            {
+                                desc: `Add JSDoc @story annotation for function 'onlyDecl', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,
+                                output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction onlyDecl() {}`,
+                            },
+                        ],
+                    },
+                ],
             },
         ],
     });

package/lib/tests/utils/annotation-checker.test.d.ts

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

package/lib/tests/utils/annotation-checker.test.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+ */
+const eslint_1 = require("eslint");
+const annotation_checker_1 = require("../../src/utils/annotation-checker");
+const ruleTester = new eslint_1.RuleTester();
+const rule = {
+    meta: {
+        type: "problem",
+        fixable: "code",
+        docs: {
+            description: "Test helper for checking @req annotation",
+            recommended: "error",
+        },
+        messages: { missingReq: "Missing @req annotation" },
+        schema: [],
+    },
+    create(context) {
+        return {
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+             */
+            TSDeclareFunction: (node) => (0, annotation_checker_1.checkReqAnnotation)(context, node),
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
+             */
+            TSMethodSignature: (node) => (0, annotation_checker_1.checkReqAnnotation)(context, node),
+        };
+    },
+};
+describe("annotation-checker helper", () => {
+    ruleTester.run("annotation-checker", rule, {
+        valid: [
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT] valid TSDeclareFunction with @req",
+                code: `/** @req REQ-TEST */\ndeclare function foo(): void;`,
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT] valid TSMethodSignature with @req",
+                code: `interface I { /** @req REQ-TEST */ method(): void; }`,
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
+        ],
+        invalid: [
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSDeclareFunction",
+                code: `declare function foo(): void;`,
+                output: `/** @req <REQ-ID> */\ndeclare function foo(): void;`,
+                errors: [{ messageId: "missingReq" }],
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
+            {
+                name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSMethodSignature",
+                code: `interface I { method(): void; }`,
+                output: `interface I { /** @req <REQ-ID> */\nmethod(): void; }`,
+                errors: [{ messageId: "missingReq" }],
+                languageOptions: {
+                    parser: require("@typescript-eslint/parser"),
+                    parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+                },
+            },
+        ],
+    });
+});

package/lib/tests/utils/branch-annotation-helpers.test.d.ts

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

package/lib/tests/utils/branch-annotation-helpers.test.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Unit tests for branch annotation helpers
+ * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+ */
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+describe("validateBranchTypes helper", () => {
+    let context;
+    beforeEach(() => {
+        context = { options: [], report: jest.fn() };
+    });
+    it("should return default branch types when no options provided", () => {
+        const result = (0, branch_annotation_helpers_1.validateBranchTypes)(context);
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toEqual(branch_annotation_helpers_1.DEFAULT_BRANCH_TYPES);
+    });
+    it("should return custom branch types when valid options provided", () => {
+        context.options = [{ branchTypes: ["IfStatement", "ForStatement"] }];
+        const result = (0, branch_annotation_helpers_1.validateBranchTypes)(context);
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toEqual(["IfStatement", "ForStatement"]);
+    });
+    it("should return listener when invalid branch types provided and report errors", () => {
+        const invalid = ["UnknownType", "Foo"];
+        context.options = [{ branchTypes: invalid }];
+        // Invoke helper
+        const result = (0, branch_annotation_helpers_1.validateBranchTypes)(context);
+        // Should return a listener object
+        expect(typeof result).toBe("object");
+        expect(result).toHaveProperty("Program");
+        // Call the Program listener
+        const fakeNode = {};
+        result.Program(fakeNode);
+        // report should be called for each invalid type
+        expect(context.report).toHaveBeenCalledTimes(invalid.length);
+        invalid.forEach((t) => {
+            expect(context.report).toHaveBeenCalledWith(expect.objectContaining({
+                node: fakeNode,
+                message: expect.stringContaining(`Value "${t}" should be equal to one of the allowed values:`),
+            }));
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.2.0",
+  "version": "1.4.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",
@@ -19,7 +19,7 @@
     "test": "jest --ci --bail",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "duplication": "jscpd src tests --reporters console --threshold 3",
+    "duplication": "jscpd src tests --reporters console --threshold 3 --ignore tests/utils/**",
     "audit:dev-high": "node scripts/generate-dev-deps-audit.js",
     "smoke-test": "./scripts/smoke-test.sh",
     "prepare": "husky install"