eslint-plugin-traceability 1.5.0 → 1.5.1

package/lib/src/index.js

@@ -77,7 +77,7 @@ const configs = {
                 "traceability/require-story-annotation": "error",
                 "traceability/require-req-annotation": "error",
                 "traceability/require-branch-annotation": "error",
-                "traceability/valid-annotation-format": "error",
+                "traceability/valid-annotation-format": "warn",
                 "traceability/valid-story-reference": "error",
                 "traceability/valid-req-reference": "error",
             },
@@ -92,7 +92,7 @@ const configs = {
                 "traceability/require-story-annotation": "error",
                 "traceability/require-req-annotation": "error",
                 "traceability/require-branch-annotation": "error",
-                "traceability/valid-annotation-format": "error",
+                "traceability/valid-annotation-format": "warn",
                 "traceability/valid-story-reference": "error",
                 "traceability/valid-req-reference": "error",
             },

package/lib/src/rules/require-req-annotation.js

@@ -22,7 +22,7 @@ exports.default = {
             recommended: "error",
         },
         messages: {
-            missingReq: "Missing @req annotation",
+            missingReq: "Missing @req annotation for function '{{name}}' (REQ-ANNOTATION-REQUIRED)",
         },
         schema: [],
     },
@@ -32,7 +32,6 @@ exports.default = {
      * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
      */
     create(context) {
-        const sourceCode = context.getSourceCode();
         return {
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -40,21 +39,7 @@ exports.default = {
              * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on function declarations
              */
             FunctionDeclaration(node) {
-                const jsdoc = sourceCode.getJSDocComment(node);
-                if (!jsdoc || !jsdoc.value.includes("@req")) {
-                    context.report({
-                        node,
-                        messageId: "missingReq",
-                        /**
-                         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-                         * @req REQ-AUTOFIX - Provide automatic fix to insert @req annotation
-                         * @req REQ-ANNOTATION-REQUIRED - Ensure inserted fix contains @req placeholder
-                         */
-                        fix(fixer) {
-                            return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
-                        },
-                    });
-                }
+                return (0, annotation_checker_1.checkReqAnnotation)(context, node);
             },
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md

package/lib/src/utils/annotation-checker.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkReqAnnotation = checkReqAnnotation;
+const require_story_utils_1 = require("../rules/helpers/require-story-utils");
 /**
  * Helper to retrieve the JSDoc comment for a node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -65,13 +66,20 @@ function createMissingReqFix(node) {
 }
 /**
  * Helper to report a missing @req annotation via the ESLint context API.
+ * Uses getNodeName to provide a readable name for the node.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @req REQ-ANNOTATION-REPORTING - Report missing @req annotation to context
+ * @req REQ-ERROR-SPECIFIC - Provide specific error details including node name
+ * @req REQ-ERROR-LOCATION - Include contextual location information in errors
  */
 function reportMissing(context, node) {
+    const rawName = (0, require_story_utils_1.getNodeName)(node);
+    const name = rawName ?? "(anonymous)";
     context.report({
         node,
         messageId: "missingReq",
+        data: { name },
         fix: createMissingReqFix(node),
     });
 }

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

@@ -7,6 +7,8 @@ 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-ANNOTATION-REQUIRED - Verify require-req-annotation rule enforces @req on functions
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-SPECIFIC - Verify enhanced, specific error messaging behavior
  */
 const eslint_1 = require("eslint");
 const require_req_annotation_1 = __importDefault(require("../../src/rules/require-req-annotation"));
@@ -48,19 +50,19 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
                 name: "[REQ-ANNOTATION-REQUIRED] missing @req on function without JSDoc",
                 code: `function baz() {}`,
                 output: `/** @req <REQ-ID> */\nfunction baz() {}`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [{ messageId: "missingReq", data: { name: "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() {}`,
                 output: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\n/** @req <REQ-ID> */\nfunction qux() {}`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [{ messageId: "missingReq", data: { name: "qux" } }],
             },
             {
                 name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSDeclareFunction",
                 code: `declare function baz(): void;`,
                 output: `/** @req <REQ-ID> */\ndeclare function baz(): void;`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [{ messageId: "missingReq", data: { name: "baz" } }],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },
@@ -70,7 +72,7 @@ describe("Require Req Annotation Rule (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", (
                 name: "[REQ-TYPESCRIPT-SUPPORT] missing @req on TSMethodSignature",
                 code: `interface I { method(): void; }`,
                 output: `interface I { /** @req <REQ-ID> */\nmethod(): void; }`,
-                errors: [{ messageId: "missingReq" }],
+                errors: [{ messageId: "missingReq", data: { name: "method" } }],
                 languageOptions: {
                     parser: require("@typescript-eslint/parser"),
                     parserOptions: { ecmaVersion: 2022, sourceType: "module" },

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

@@ -78,6 +78,30 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
                     },
                 ],
             },
+            {
+                name: "[REQ-PATH-FORMAT] missing extension in story path",
+                code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION`,
+                errors: [
+                    {
+                        messageId: "invalidStoryFormat",
+                        data: {
+                            details: 'Invalid story path "docs/stories/005.0-DEV-ANNOTATION-VALIDATION" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-PATH-FORMAT] story path must not use path traversal",
+                code: `// @story ../docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
+                errors: [
+                    {
+                        messageId: "invalidStoryFormat",
+                        data: {
+                            details: 'Invalid story path "../docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                        },
+                    },
+                ],
+            },
             {
                 name: "[REQ-REQ-FORMAT] missing req id (single line)",
                 code: `// @req`,
@@ -102,6 +126,18 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
                     },
                 ],
             },
+            {
+                name: "[REQ-REQ-FORMAT] missing req identifier with trailing space",
+                code: `// @req `,
+                errors: [
+                    {
+                        messageId: "invalidReqFormat",
+                        data: {
+                            details: 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".',
+                        },
+                    },
+                ],
+            },
             {
                 name: "[REQ-MULTILINE-SUPPORT] missing story path with multi-line block comment",
                 code: `/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "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",