eslint-plugin-traceability 1.6.1 → 1.6.3

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

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @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
+ * @req REQ-ERROR-LOCATION - Include precise location information in error messages
  */
 const eslint_1 = require("eslint");
 const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
@@ -18,31 +19,79 @@ const ruleTester = new eslint_1.RuleTester({
     },
 });
 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() {}`,
-                output: "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction bar() {}",
-                errors: [
+    describe("valid cases", () => {
+        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: [],
+        });
+    });
+    describe("REQ-ERROR-SPECIFIC - missing @story annotation should report specific details and suggestion", () => {
+        it("reports specific message, data, and suggestions for function 'bar'", () => {
+            const code = "function bar() {}";
+            const reported = [];
+            const context = {
+                id: "require-story-annotation",
+                options: [],
+                report: (descriptor) => {
+                    reported.push(descriptor);
+                },
+                getFilename: () => "test.js",
+                getSourceCode: () => ({
+                    text: code,
+                    getText: () => code,
+                    ast: {
+                        type: "Program",
+                        body: [],
+                        sourceType: "module",
+                    },
+                }),
+            };
+            const listeners = require_story_annotation_1.default.create(context);
+            // Minimal synthetic AST nodes for the visitors
+            const programNode = {
+                type: "Program",
+                body: [
                     {
-                        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() {}",
-                            },
-                        ],
+                        type: "FunctionDeclaration",
+                        id: { type: "Identifier", name: "bar" },
+                        params: [],
+                        body: {
+                            type: "BlockStatement",
+                            body: [],
+                        },
                     },
                 ],
-            },
-        ],
+                sourceType: "module",
+            };
+            const functionNode = programNode.body[0];
+            // Invoke visitors if they exist
+            if (typeof listeners.Program === "function") {
+                listeners.Program(programNode);
+            }
+            if (typeof listeners.FunctionDeclaration === "function") {
+                listeners.FunctionDeclaration(functionNode);
+            }
+            expect(reported.length).toBe(1);
+            const error = reported[0];
+            // Message template should be defined and contain the {{name}} placeholder
+            const template = require_story_annotation_1.default.meta?.messages?.missingStory;
+            expect(typeof template).toBe("string");
+            expect(template.length).toBeGreaterThan(0);
+            expect(template.includes("{{name}}")).toBe(true);
+            // Ensure messageId and data wiring is correct
+            expect(error.messageId).toBe("missingStory");
+            expect(error.data).toEqual({ name: "bar", functionName: "bar" });
+            // Suggestions
+            expect(Array.isArray(error.suggest)).toBe(true);
+            expect(error.suggest.length).toBeGreaterThanOrEqual(1);
+            const suggestion = error.suggest[0];
+            expect(suggestion.desc).toBe("Add JSDoc @story annotation for function 'bar', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */");
+            expect(suggestion.fix).toBeDefined();
+        });
     });
 });

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

@@ -4,9 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * Tests for: docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md, docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.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
  */
 const eslint_1 = require("eslint");
 const require_branch_annotation_1 = __importDefault(require("../../src/rules/require-branch-annotation"));

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

@@ -108,17 +108,32 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @req on function without JSDoc",
                 code: `function baz() {}`,
-                errors: [{ messageId: "missingReq", data: { name: "baz" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "baz", functionName: "baz" },
+                    },
+                ],
             },
             {
                 name: "[REQ-ANNOTATION-REQUIRED] missing @req on function with only @story annotation",
                 code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction qux() {}`,
-                errors: [{ messageId: "missingReq", data: { name: "qux" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "qux", functionName: "qux" },
+                    },
+                ],
             },
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSDeclareFunction",
                 code: `declare function baz(): void;`,
-                errors: [{ messageId: "missingReq", data: { name: "baz" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "baz", functionName: "baz" },
+                    },
+                ],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
@@ -127,7 +142,12 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSMethodSignature",
                 code: `interface I { method(): void; }`,
-                errors: [{ messageId: "missingReq", data: { name: "method" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "method", functionName: "method" },
+                    },
+                ],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
@@ -136,27 +156,52 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
             {
                 name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on FunctionExpression assigned to variable",
                 code: `const fn = function () {};`,
-                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "fn", functionName: "fn" },
+                    },
+                ],
             },
             {
                 name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on anonymous FunctionExpression (no variable name)",
                 code: `(function () {})();`,
-                errors: [{ messageId: "missingReq", data: { name: "(anonymous)" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "(anonymous)", functionName: "(anonymous)" },
+                    },
+                ],
             },
             {
                 name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on MethodDefinition in class",
                 code: `class C {\n  m() {}\n}`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "m", functionName: "m" },
+                    },
+                ],
             },
             {
                 name: "[REQ-FUNCTION-DETECTION][Story 003.0] missing @req on MethodDefinition in object literal",
                 code: `const o = { m() {} };`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "m", functionName: "m" },
+                    },
+                ],
             },
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT][REQ-FUNCTION-DETECTION][Story 003.0] missing @req on TS FunctionExpression in variable declarator",
                 code: `const fn = function () {};`,
-                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "fn", functionName: "fn" },
+                    },
+                ],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
@@ -165,7 +210,12 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT][REQ-FUNCTION-DETECTION][Story 003.0] missing @req on exported TS FunctionExpression in variable declarator",
                 code: `export const fn = function () {};`,
-                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "fn", functionName: "fn" },
+                    },
+                ],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
@@ -175,43 +225,78 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
                 name: "[REQ-CONFIGURABLE-SCOPE][Story 003.0] FunctionDeclaration still reported when scope only includes FunctionDeclaration",
                 code: `function scoped() {}`,
                 options: [{ scope: ["FunctionDeclaration"] }],
-                errors: [{ messageId: "missingReq", data: { name: "scoped" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "scoped", functionName: "scoped" },
+                    },
+                ],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported function reported when exportPriority is 'exported'",
                 code: `export function exportedFn() {}`,
                 options: [{ exportPriority: "exported" }],
-                errors: [{ messageId: "missingReq", data: { name: "exportedFn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "exportedFn", functionName: "exportedFn" },
+                    },
+                ],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported function reported when exportPriority is 'non-exported'",
                 code: `function nonExported() {}`,
                 options: [{ exportPriority: "non-exported" }],
-                errors: [{ messageId: "missingReq", data: { name: "nonExported" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "nonExported", functionName: "nonExported" },
+                    },
+                ],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported method reported when exportPriority is 'exported'",
                 code: `export class C {\n  m() {}\n}`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "m", functionName: "m" },
+                    },
+                ],
                 options: [{ exportPriority: "exported" }],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported method reported when exportPriority is 'non-exported'",
                 code: `class C {\n  m() {}\n}`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "m", functionName: "m" },
+                    },
+                ],
                 options: [{ exportPriority: "non-exported" }],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] exported FunctionExpression reported when exportPriority is 'exported'",
                 code: `export const fn = function () {};`,
                 options: [{ exportPriority: "exported" }],
-                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "fn", functionName: "fn" },
+                    },
+                ],
             },
             {
                 name: "[REQ-EXPORT-PRIORITY][Story 003.0] non-exported FunctionExpression reported when exportPriority is 'non-exported'",
                 code: `const fn = function () {};`,
                 options: [{ exportPriority: "non-exported" }],
-                errors: [{ messageId: "missingReq", data: { name: "fn" } }],
+                errors: [
+                    {
+                        messageId: "missingReq",
+                        data: { name: "fn", functionName: "fn" },
+                    },
+                ],
             },
         ],
     });

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

@@ -105,6 +105,7 @@ declare function tsDecl(): void;`,
                 errors: [
                     {
                         messageId: "missingStory",
+                        data: { name: "method", functionName: "method" },
                         suggestions: [
                             {
                                 desc: `Add JSDoc @story annotation for function 'method', e.g., /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */`,

package/lib/tests/rules/valid-annotation-format.test.js

@@ -7,6 +7,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @req REQ-FORMAT-SPECIFICATION - Verify valid-annotation-format rule enforces annotation format syntax
+ * Tests for: docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-MESSAGES-CONSISTENT - Verify invalid annotation errors use consistent wording and structure
+ * @req REQ-ERROR-MESSAGES-ACTIONABLE - Verify invalid annotation errors provide actionable guidance and examples
+ * @req REQ-ERROR-MESSAGES-IDENTIFIERS - Verify invalid annotation errors echo the offending identifier/path in the message
  */
 const eslint_1 = require("eslint");
 const valid_annotation_format_1 = __importDefault(require("../../src/rules/valid-annotation-format"));

package/lib/tests/rules/valid-req-reference.test.js

@@ -7,6 +7,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
  * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
  * @req REQ-DEEP-PARSE - Verify valid-req-reference rule enforces existing requirement content
+ *
+ * Additional coverage for error reporting behavior:
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-SPECIFIC - Verify requirement-level errors identify the exact missing requirement
+ * @req REQ-ERROR-CONTEXT - Verify requirement-level errors include relevant story path context
+ * @req REQ-ERROR-CONSISTENCY - Verify requirement-level error messages are consistent across cases
  */
 const eslint_1 = require("eslint");
 const valid_req_reference_1 = __importDefault(require("../../src/rules/valid-req-reference"));