eslint-plugin-traceability 1.4.4 → 1.4.5

package/lib/src/rules/helpers/require-story-io.js

@@ -56,12 +56,22 @@ function parentChainHasStory(sourceCode, node) {
             ? sourceCode.getCommentsBefore(p) || []
             : [];
         if (Array.isArray(pComments) &&
-            pComments.some((c) => typeof c.value === "string" && c.value.includes("@story"))) {
+            pComments.some(
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-ANNOTATION-REQUIRED - Detect @story in parent comments via value inspection
+             */
+            (c) => typeof c.value === "string" && c.value.includes("@story"))) {
             return true;
         }
         const pLeading = p.leadingComments || [];
         if (Array.isArray(pLeading) &&
-            pLeading.some((c) => typeof c.value === "string" && c.value.includes("@story"))) {
+            pLeading.some(
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-ANNOTATION-REQUIRED - Detect @story in parent leadingComments via value inspection
+             */
+            (c) => typeof c.value === "string" && c.value.includes("@story"))) {
             return true;
         }
         p = p.parent;

package/lib/src/rules/valid-req-reference.js

@@ -162,6 +162,15 @@ function programListener(context) {
     let rawStoryPath = null;
     return function Program() {
         const comments = sourceCode.getAllComments() || [];
+        /**
+         * Process each comment to handle story and requirement annotations.
+         *
+         * @story docs/stories/010.0-DEV-DEEP-VALIDATION.story.md
+         * @req REQ-DEEP-PARSE - Parse annotations from comment blocks
+         * @req REQ-DEEP-MATCH - Validate @req references found in comments
+         * @req REQ-DEEP-CACHE - Use cache for parsed story files to avoid repeated IO
+         * @req REQ-DEEP-PATH - Enforce path validation when resolving story files
+         */
         comments.forEach((comment) => {
             rawStoryPath = handleComment({
                 comment,

package/lib/src/rules/valid-story-reference.js

@@ -94,6 +94,10 @@ function handleComment(opts) {
     const { commentNode, context, cwd, storyDirs, allowAbsolute, requireExt } = opts;
     const lines = commentNode.value
         .split(/\r?\n/)
+        /**
+         * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+         * @req REQ-ANNOTATION-VALIDATION - Ensure each annotation line is parsed
+         */
         .map((l) => l.replace(/^[^@]*/, "").trim());
     for (const line of lines) {
         if (line.startsWith("@story")) {

package/lib/tests/rules/require-story-core.branches.test.d.ts

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

package/lib/tests/rules/require-story-core.branches.test.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Branch tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Cover additional branch cases in require-story-core (addStoryFixer/reportMissing)
+ */
+const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
+const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");
+describe("Require Story Core branches (Story 003.0)", () => {
+    test("createAddStoryFix falls back to 0 when target is falsy", () => {
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixFn = (0, require_story_core_1.createAddStoryFix)(null);
+        const res = fixFn(fixer);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
+        const args = fixer.insertTextBeforeRange.mock.calls[0];
+        expect(args[0]).toEqual([0, 0]);
+        expect(args[1]).toBe(`${require_story_helpers_1.ANNOTATION}\n`);
+        expect(res).toEqual({ r: [0, 0], t: `${require_story_helpers_1.ANNOTATION}\n` });
+    });
+    test("createAddStoryFix uses target.range when parent not export and parent.range missing", () => {
+        const target = {
+            type: "FunctionDeclaration",
+            range: [21, 33],
+            parent: { type: "ClassBody" },
+        };
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixFn = (0, require_story_core_1.createAddStoryFix)(target);
+        const res = fixFn(fixer);
+        expect(fixer.insertTextBeforeRange.mock.calls[0][0]).toEqual([21, 21]);
+        expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(`${require_story_helpers_1.ANNOTATION}\n`);
+        expect(res).toEqual({ r: [21, 21], t: `${require_story_helpers_1.ANNOTATION}\n` });
+    });
+    test("createAddStoryFix prefers ExportDefaultDeclaration parent.range when present", () => {
+        const target = {
+            type: "FunctionDeclaration",
+            range: [50, 70],
+            parent: { type: "ExportDefaultDeclaration", range: [5, 100] },
+        };
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixFn = (0, require_story_core_1.createAddStoryFix)(target);
+        const res = fixFn(fixer);
+        expect(fixer.insertTextBeforeRange.mock.calls[0][0]).toEqual([5, 5]);
+        expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(`${require_story_helpers_1.ANNOTATION}\n`);
+        expect(res).toEqual({ r: [5, 5], t: `${require_story_helpers_1.ANNOTATION}\n` });
+    });
+    test("reportMissing uses context.getSourceCode fallback when sourceCode not provided and still reports", () => {
+        const node = {
+            type: "FunctionDeclaration",
+            id: { name: "fnX" },
+            range: [0, 10],
+        };
+        const fakeSource = {
+            /* intentionally missing getJSDocComment to exercise branch */ getText: () => "",
+        };
+        const context = { getSourceCode: () => fakeSource, report: jest.fn() };
+        (0, require_story_core_1.reportMissing)(context, undefined, node, node);
+        expect(context.report).toHaveBeenCalledTimes(1);
+        const call = context.report.mock.calls[0][0];
+        expect(call.node).toBe(node);
+        expect(call.messageId).toBe("missingStory");
+    });
+});

package/lib/tests/rules/require-story-core.test.d.ts

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

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

@@ -0,0 +1,58 @@
+"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-AUTOFIX - Verify createMethodFix and reportMethod behaviors
+ */
+const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
+const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");
+describe("Require Story Core (Story 003.0)", () => {
+    test("createMethodFix uses parent range start when parent is export", () => {
+        const node = {
+            type: "MethodDefinition",
+            range: [30, 60],
+            parent: { type: "ExportNamedDeclaration", range: [12, 90] },
+        };
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixFn = (0, require_story_core_1.createMethodFix)(node);
+        const result = fixFn(fixer);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
+        const calledArgs = fixer.insertTextBeforeRange.mock.calls[0];
+        expect(calledArgs[0]).toEqual([12, 12]);
+        expect(calledArgs[1]).toBe(`${require_story_helpers_1.ANNOTATION}\n  `);
+        expect(result).toEqual({ r: [12, 12], t: `${require_story_helpers_1.ANNOTATION}\n  ` });
+    });
+    test("reportMethod calls context.report with proper data and suggest.fix works", () => {
+        const node = {
+            type: "MethodDefinition",
+            key: { name: "myMethod" },
+            range: [40, 80],
+            parent: { type: "ClassBody" },
+        };
+        const fakeSource = { getText: () => "" };
+        const context = {
+            getSourceCode: () => fakeSource,
+            report: jest.fn(),
+        };
+        (0, require_story_core_1.reportMethod)(context, fakeSource, node, node);
+        expect(context.report).toHaveBeenCalledTimes(1);
+        const call = context.report.mock.calls[0][0];
+        expect(call.messageId).toBe("missingStory");
+        expect(call.data).toEqual({ name: "myMethod" });
+        // The suggest fix should be a function; exercise it with a mock fixer
+        expect(Array.isArray(call.suggest)).toBe(true);
+        expect(typeof call.suggest[0].fix).toBe("function");
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const fixResult = call.suggest[0].fix(fixer);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalled();
+        const args = fixer.insertTextBeforeRange.mock.calls[0];
+        expect(args[0]).toEqual([40, 40]);
+        expect(args[1]).toBe(`${require_story_helpers_1.ANNOTATION}\n  `);
+        expect(fixResult).toEqual({ r: [40, 40], t: `${require_story_helpers_1.ANNOTATION}\n  ` });
+    });
+});

package/package.json

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